run-dmcp 0.8.0 → 0.10.0

package/dist/timeline/resolve.d.ts

@@ -92,8 +92,7 @@ import { type ValueTransition, type SetTransition, type CreatedEntity, type Dest
  *      mechanic's name, and the change count -- following
  *      `applyLiveWrite`'s (constrained.ts) `causes` discipline of never
  *      including a `row_id` key, which belongs to the projection triggers'
- *      own vocabulary (see that function's comment on why colliding with it
- *      would make `findOpenedByEventId`'s pick non-deterministic).
+ *      own vocabulary.
  *   7. Build the outcome's constraint AFTER the writes have landed --
  *      re-reading `currentStoryTime` inside the same transaction, after
  *      every change has been applied, so a `sequence`-axis game (whose `t`
@@ -125,6 +124,13 @@ export interface Proposal {
     mechanic: string;
     parameters?: Record<string, unknown>;
     expects?: readonly Expectation[];
+    /** The principal proposing (issue #40): an entity id. When the game has
+     *  declared any turn order, a proposal whose actor is not the one due at
+     *  the current t -- including a t no declaration covers yet -- is refused
+     *  `out-of-turn` before dispatch. Omitted, the
+     *  proposal is the world's own (time passing, a scheduled consequence) and
+     *  is not a turn. Recorded in the resolution's causes either way. */
+    actor?: string;
 }
 /**
  * What a `Mechanic`'s `adjudicate` receives -- and ALL it receives. There is
@@ -204,13 +210,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 +265,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`
@@ -287,13 +335,20 @@ export interface Mechanic {
  *  under -- never a judgement about the proposal, the mechanic, or the
  *  world (see the module doc comment's "records decisions, does not make
  *  them" paragraph). */
-export type ResolveRefusalReason = "unknown-mechanic" | "no-clock" | "expectation-contradicted"
+export type ResolveRefusalReason = "unknown-mechanic" | "no-clock"
+/** The proposal named an `actor`, the game has declared a turn order, and
+ *  that actor is not the one due at the current t (issue #40). Refused
+ *  before dispatch. */
+ | "out-of-turn" | "expectation-contradicted"
 /** A leg said `{ ref }` and no earlier `create` leg of the same
  *  resolution defined that ref (issue #34). Refused before any write. */
  | "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

@@ -1,8 +1,11 @@
 import { v4 as uuidv4 } from "uuid";
 import { getDatabase, withTransaction } from "../db/connection.js";
 import { currentStoryTime } from "./clock.js";
+import { dueAt, hasTurnOrder } from "./turns.js";
 import { narrationConstraintAt, contradictions } from "./narration.js";
 import { withAdjudicationOpen } from "./adjudication.js";
+import { PROJECTED_TABLES, liveColumns } from "./projection.js";
+import { insertConstraintRow, constraintsFor } from "./registry.js";
 import { writeConstrainedValue, transferConstrainedValue, setProjectedValue, createProjectedEntity, destroyProjectedEntity, } from "./constrained.js";
 /**
  * Refused before dispatch, before any write, or (never, by construction --
@@ -100,6 +103,24 @@ function refsUsedBy(change) {
             return [];
     }
 }
+/**
+ * A write leg that supplies no `bounds`, to a key a `bounded` constraint
+ * governs on a resource, is held to that resource's own min/max -- exactly
+ * the bounds `update_resource_value` supplies for the same write
+ * (tools/resource.ts). Without this, a resolution could write straight past a
+ * bound the tool path refuses, because the choke point checks `bounded`
+ * against the bounds a writer hands it and this writer handed none. Found by
+ * the 2026-09-26 review, through a declared mechanic (#41) with no min/max;
+ * a hand-written mechanic had the same hole. Nothing changes for a key with
+ * no `bounded` constraint: supplying bounds there would start CLAMPING writes
+ * that land outside min/max today.
+ */
+function boundedResourceDefault(entityId, key) {
+    if (key !== "value" || !constraintsFor(entityId, key).some((c) => c.kind === "bounded"))
+        return undefined;
+    const row = getDatabase().prepare(`SELECT min_value, max_value FROM resources WHERE id = ?`).get(entityId);
+    return row ? { minValue: row.min_value, maxValue: row.max_value } : undefined;
+}
 /**
  * Step 5's precondition (issue #34): every `{ ref }` names a `create` leg
  * EARLIER in the list, and no two creates share a ref. Checked over the
@@ -126,6 +147,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;
@@ -145,15 +245,16 @@ function applyChange(change, gameId, refs) {
         return { set: setProjectedValue({ entityId: deref(change.entityId, refs), key: change.key, value: derefValue(change.value, refs) }) };
     }
     if (change.kind === "write") {
+        const entityId = deref(change.entityId, refs);
         return {
             transitions: [
                 writeConstrainedValue({
-                    entityId: deref(change.entityId, refs),
+                    entityId,
                     key: change.key,
                     mode: change.mode,
                     value: change.value,
                     reason: change.reason,
-                    bounds: change.bounds,
+                    bounds: change.bounds ?? boundedResourceDefault(entityId, change.key),
                 }),
             ],
         };
@@ -212,6 +313,16 @@ function resolveProposal(mechanicsByName, proposal) {
             `something through the normal tools first, then propose again.`);
     }
     const t = preStory.t;
+    // 2b. Turns (issue #40): an actor who is not due is refused before the
+    // mechanic ever sees the proposal. No actor -> not a turn -> no check.
+    if (proposal.actor !== undefined && hasTurnOrder(gameId)) {
+        const due = dueAt({ gameId, t });
+        if (!due || due.principal !== proposal.actor) {
+            throw new ResolveProtocolError("out-of-turn", `resolve: '${proposal.actor}' proposed at t=${t}, but ` +
+                (due ? `'${due.principal}' is due at t=${t}` : `nobody is due at t=${t}`) +
+                ` under this game's declared turn order. Ask who is due (due_at) or move to the next turn (advance_turn).`);
+        }
+    }
     // 3. ONE query builds both the mechanic's read surface AND the inbound
     // precondition check -- see the module doc comment's unification note on
     // why this is the same structure read in two directions, not two
@@ -246,8 +357,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 +375,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,12 +416,12 @@ 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,
             mechanic: mechanicName,
             change_count: changes.length,
+            ...(proposal.actor !== undefined ? { actor: proposal.actor } : {}),
         };
         getDatabase()
             .prepare(`INSERT INTO events (id, game_id, at_t, kind, description, causes) VALUES (?, ?, ?, 'resolution.recorded', ?, ?)`)

package/dist/timeline/schema.js

@@ -282,6 +282,34 @@ export function initializeTimelineSchema() {
     BEGIN
       SELECT RAISE(ABORT, 'timeline: an irreversible fact holds for key ''' || NEW.key || ''' on this entity as of its valid_from_t; a contradicting value is refused from that point onward');
     END;
+  `);
+    // Issue #40: a game's declared turn order -- which entities act in what
+    // cycle, from a `from_t` on. Append-only like the timeline it answers for:
+    // `dueAt(t)` for a past t must give the same answer forever, so a
+    // declaration is never edited or removed, only superseded by a later one
+    // from a later `from_t` (turns.ts refuses anything else before insert).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS turn_orders (
+      id TEXT PRIMARY KEY,
+      game_id TEXT NOT NULL,
+      from_t REAL NOT NULL,
+      principals TEXT NOT NULL,
+      declared_at TEXT NOT NULL,
+      UNIQUE (game_id, from_t)
+    );
+    CREATE INDEX IF NOT EXISTS idx_turn_orders_game_from ON turn_orders(game_id, from_t);
+    DROP TRIGGER IF EXISTS timeline_turn_orders_immutable;
+    CREATE TRIGGER timeline_turn_orders_immutable
+    BEFORE UPDATE ON turn_orders
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: turn orders are append-only; a declaration is superseded, never edited');
+    END;
+    DROP TRIGGER IF EXISTS timeline_turn_orders_no_delete;
+    CREATE TRIGGER timeline_turn_orders_no_delete
+    BEFORE DELETE ON turn_orders
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: turn orders are append-only; a declaration is superseded, never deleted');
+    END;
   `);
     // Issue #2: the projection layer. Triggers first, so every write from
     // here on appends by construction; reconciliation second, so it backfills

package/dist/timeline/turns.d.ts

@@ -0,0 +1,60 @@
+import { type T } from "./t.js";
+/**
+ * A principal is due to act (GitHub issue #40). The issue draws the line:
+ * "The engine records whose turn it is and refuses out-of-turn proposals if
+ * a game declares turns. It never runs the turn itself." So this module holds
+ * a DECLARATION -- which entities act, in what cycle, from which t -- and
+ * answers "who is due at t" for any t, past included. It never schedules,
+ * waits, notifies or calls anything: an MCP server answers calls, so
+ * whatever runs minds asks (pull), moves the clock with `advanceTurn`, and
+ * proposes as that principal. `resolve()` refuses a proposal whose `actor` is
+ * not the one due (resolve.ts, `out-of-turn`).
+ *
+ * WHY A COUNTER AXIS ONLY. A turn is a count of things that happened, which is
+ * exactly what `counter` means (t.ts). On `sequence` the engine's own writes
+ * advance t, so "one principal per t" would hand the turn over mid-action;
+ * on `elapsed` t is a measure, and turns-per-second is a policy this engine
+ * has no business guessing.
+ *
+ * WHY APPEND-ONLY. `dueAt(t)` for a past t is history, and this engine can
+ * always say what the world looked like at any point. A changed order is a
+ * NEW declaration from a later t; the old one keeps answering for the t it
+ * covered. The `turn_orders` triggers (schema.ts) make an edit
+ * unconstructable rather than discouraged.
+ *
+ * A principal is an entity of the game (DESIGN.md §8's admission criterion:
+ * it resolves to an entity the engine already has). The engine never learns
+ * what a principal is for.
+ */
+export interface TurnDue {
+    t: T;
+    principal: string;
+    /** 1-based: which pass through the declared cycle this t belongs to. */
+    round: number;
+    /** 0-based position in the cycle. */
+    position: number;
+    /** The declaration this answer comes from. */
+    fromT: T;
+}
+export declare function declareTurnOrder(params: {
+    gameId: string;
+    principals: readonly string[];
+    fromT: T;
+}): {
+    fromT: T;
+    principals: string[];
+};
+/** Who is due at `t`, or `null`: no declaration covers `t`, or `t` is not a
+ *  whole step on from the declaration's `fromT`. */
+export declare function dueAt(params: {
+    gameId: string;
+    t: T;
+}): TurnDue | null;
+/** Moves the clock to the next turn -- one step on, or to the first
+ *  declaration's `fromT` if the clock has not reached it -- and says who is
+ *  due there. Moves time only; runs nothing. */
+export declare function advanceTurn(params: {
+    gameId: string;
+}): TurnDue;
+/** Whether the game has declared any turn order at all. */
+export declare function hasTurnOrder(gameId: string): boolean;

package/dist/timeline/turns.js

@@ -0,0 +1,93 @@
+import { v4 as uuidv4 } from "uuid";
+import { getDatabase } from "../db/connection.js";
+import { currentStoryTime, setStoryTime } from "./clock.js";
+import { assertT } from "./t.js";
+function declarationAt(gameId, t) {
+    return getDatabase()
+        .prepare(`SELECT from_t, principals FROM turn_orders WHERE game_id = ? AND from_t <= ? ORDER BY from_t DESC LIMIT 1`)
+        .get(gameId, t);
+}
+function latestDeclaration(gameId) {
+    return getDatabase()
+        .prepare(`SELECT from_t, principals FROM turn_orders WHERE game_id = ? ORDER BY from_t DESC LIMIT 1`)
+        .get(gameId);
+}
+export function declareTurnOrder(params) {
+    const { gameId, fromT } = params;
+    assertT(fromT);
+    const principals = [...params.principals];
+    const story = currentStoryTime(gameId);
+    if (!story || story.axis.kind !== "counter") {
+        throw new Error(`declareTurnOrder: game '${gameId}' must be on a counter axis -- a turn is a count of things that happened ` +
+            `(declare_time_axis with kind 'counter')`);
+    }
+    if (!Number.isInteger(fromT))
+        throw new Error(`declareTurnOrder: fromT must be an integer t on the counter axis, got ${fromT}`);
+    if (fromT < story.t) {
+        throw new Error(`declareTurnOrder: fromT ${fromT} is before the game's current t (${story.t}); turns already taken cannot be reordered`);
+    }
+    const latest = latestDeclaration(gameId);
+    // The current t may already be someone's turn (and a resolution may
+    // already record them acting in it); reassigning it would rewrite that.
+    if (latest && latest.from_t <= story.t && fromT <= story.t) {
+        throw new Error(`declareTurnOrder: t=${story.t} is already covered by the declaration from ${latest.from_t}; a new order can start at t=${story.t + 1} at the earliest`);
+    }
+    if (latest && fromT <= latest.from_t) {
+        throw new Error(`declareTurnOrder: fromT ${fromT} must come after the latest declaration's fromT (${latest.from_t})`);
+    }
+    if (principals.length === 0)
+        throw new Error(`declareTurnOrder: a turn order needs at least one principal`);
+    const seen = new Set();
+    const alive = getDatabase().prepare(`SELECT 1 FROM entities WHERE id = ? AND game_id = ? AND created_at_t <= ? AND (destroyed_at_t IS NULL OR destroyed_at_t > ?)`);
+    for (const principal of principals) {
+        if (typeof principal !== "string")
+            throw new Error(`declareTurnOrder: a principal must be an entity id, got ${JSON.stringify(principal)}`);
+        if (seen.has(principal))
+            throw new Error(`declareTurnOrder: principal '${principal}' appears twice in one cycle`);
+        seen.add(principal);
+        if (!alive.get(principal, gameId, fromT, fromT)) {
+            throw new Error(`declareTurnOrder: '${principal}' is not an entity of this game alive at t=${fromT}`);
+        }
+    }
+    getDatabase()
+        .prepare(`INSERT INTO turn_orders (id, game_id, from_t, principals, declared_at) VALUES (?, ?, ?, ?, ?)`)
+        .run(uuidv4(), gameId, fromT, JSON.stringify(principals), new Date().toISOString());
+    return { fromT, principals };
+}
+/** Who is due at `t`, or `null`: no declaration covers `t`, or `t` is not a
+ *  whole step on from the declaration's `fromT`. */
+export function dueAt(params) {
+    const { gameId, t } = params;
+    assertT(t);
+    const declaration = declarationAt(gameId, t);
+    if (!declaration)
+        return null;
+    const offset = t - declaration.from_t;
+    if (!Number.isInteger(offset))
+        return null;
+    const principals = JSON.parse(declaration.principals);
+    const position = offset % principals.length;
+    return { t, principal: principals[position], round: Math.floor(offset / principals.length) + 1, position, fromT: declaration.from_t };
+}
+/** Moves the clock to the next turn -- one step on, or to the first
+ *  declaration's `fromT` if the clock has not reached it -- and says who is
+ *  due there. Moves time only; runs nothing. */
+export function advanceTurn(params) {
+    const { gameId } = params;
+    const story = currentStoryTime(gameId);
+    const first = getDatabase()
+        .prepare(`SELECT from_t FROM turn_orders WHERE game_id = ? ORDER BY from_t ASC LIMIT 1`)
+        .get(gameId);
+    if (!story || !first)
+        throw new Error(`advanceTurn: game '${gameId}' has no turn order declared (declare_turn_order)`);
+    const next = story.t < first.from_t ? first.from_t : Math.floor(story.t) + 1;
+    const due = dueAt({ gameId, t: next });
+    if (!due)
+        throw new Error(`advanceTurn: nobody is due at t=${next}`);
+    setStoryTime({ gameId, t: next });
+    return due;
+}
+/** Whether the game has declared any turn order at all. */
+export function hasTurnOrder(gameId) {
+    return getDatabase().prepare(`SELECT 1 FROM turn_orders WHERE game_id = ? LIMIT 1`).get(gameId) !== undefined;
+}

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/dist/utils/output-schemas.d.ts

@@ -255,14 +255,14 @@ export declare const characterOutputSchema: {
                 condition: z.ZodOptional<z.ZodString>;
                 glowOrEffects: z.ZodOptional<z.ZodString>;
             }, "strip", z.ZodTypeAny, {
+                condition?: string | undefined;
                 size?: string | undefined;
                 material?: string | undefined;
-                condition?: string | undefined;
                 glowOrEffects?: string | undefined;
             }, {
+                condition?: string | undefined;
                 size?: string | undefined;
                 material?: string | undefined;
-                condition?: string | undefined;
                 glowOrEffects?: string | undefined;
             }>>;
             pose: z.ZodOptional<z.ZodString>;
@@ -299,9 +299,9 @@ export declare const characterOutputSchema: {
                 vegetation?: string | undefined;
             } | undefined;
             objectDetails?: {
+                condition?: string | undefined;
                 size?: string | undefined;
                 material?: string | undefined;
-                condition?: string | undefined;
                 glowOrEffects?: string | undefined;
             } | undefined;
             pose?: string | undefined;
@@ -338,9 +338,9 @@ export declare const characterOutputSchema: {
                 vegetation?: string | undefined;
             } | undefined;
             objectDetails?: {
+                condition?: string | undefined;
                 size?: string | undefined;
                 material?: string | undefined;
-                condition?: string | undefined;
                 glowOrEffects?: string | undefined;
             } | undefined;
             pose?: string | undefined;
@@ -587,9 +587,9 @@ export declare const characterOutputSchema: {
                 vegetation?: string | undefined;
             } | undefined;
             objectDetails?: {
+                condition?: string | undefined;
                 size?: string | undefined;
                 material?: string | undefined;
-                condition?: string | undefined;
                 glowOrEffects?: string | undefined;
             } | undefined;
             pose?: string | undefined;
@@ -683,9 +683,9 @@ export declare const characterOutputSchema: {
                 vegetation?: string | undefined;
             } | undefined;
             objectDetails?: {
+                condition?: string | undefined;
                 size?: string | undefined;
                 material?: string | undefined;
-                condition?: string | undefined;
                 glowOrEffects?: string | undefined;
             } | undefined;
             pose?: string | undefined;

package/package.json

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