run-dmcp 0.9.0 → 0.10.0

package/dist/register/timeline.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { ANNOTATIONS } from "../utils/tool-annotations.js";
 import { createLogger } from "../utils/logger.js";
 import { replay } from "../timeline/replay.js";
+import { declareTurnOrder, dueAt, advanceTurn } from "../timeline/turns.js";
 import { declareTimeAxis, setStoryTime, currentStoryTime } from "../timeline/clock.js";
 import { declareIrreversible, listIrreversibleFacts } from "../timeline/irreversible.js";
 import { exportTimelineToFile, importTimelineFromFile } from "../timeline/export.js";
@@ -46,11 +47,16 @@ export function registerTimelineTools(server) {
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
             t: tSchema,
+            entityIds: z
+                .array(z.string().max(100))
+                .max(10000)
+                .optional()
+                .describe("Scope the read to these entities -- a selection you built, such as what one character perceives. Omitted: every entity. An empty list: none. An id not alive at t is simply absent."),
         },
         annotations: ANNOTATIONS.READ_ONLY,
-    }, async ({ gameId, t }) => {
+    }, async ({ gameId, t, entityIds }) => {
         try {
-            const snapshot = replay({ gameId, t });
+            const snapshot = replay({ gameId, t, entityIds });
             return { content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }] };
         }
         catch (error) {
@@ -308,4 +314,25 @@ export function registerTimelineTools(server) {
             };
         }
     });
+    // Issue #40: a principal is due to act. The engine records whose turn it
+    // is and refuses an out-of-turn `resolve`; it never runs a turn.
+    const turnTool = (name, description, inputSchema, annotations, run) => server.registerTool(name, { description, inputSchema, annotations }, async (args) => {
+        try {
+            return { content: [{ type: "text", text: JSON.stringify(run(args), null, 2) }] };
+        }
+        catch (error) {
+            log.error(`${name} failed`, { error: error.message });
+            return { content: [{ type: "text", text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+    });
+    turnTool("declare_turn_order", "Declare which entities act, in what cycle, one per t on this game's counter axis from fromT onward. Append-only: " +
+        "to change the order, declare again from a later t -- earlier turns keep answering as they did. Once declared, a resolve " +
+        "naming an actor who is not due at the current t is refused. The engine records whose turn it is; it never runs one.", {
+        gameId: z.string().max(100).describe("The game ID"),
+        principals: z.array(z.string().max(100)).max(1000).describe("Entity ids, in the order they act."),
+        fromT: tSchema.describe("The first t this order covers. An integer t on the counter axis, not before the current t."),
+    }, ANNOTATIONS.UPDATE, (a) => declareTurnOrder({ gameId: a.gameId, principals: a.principals, fromT: a.fromT }));
+    turnTool("due_at", "Who is due to act at t under this game's declared turn order -- any t, past included -- with the round and " +
+        "position in the cycle. {due: null} when no declaration covers t.", { gameId: z.string().max(100).describe("The game ID"), t: tSchema }, ANNOTATIONS.READ_ONLY, (a) => dueAt({ gameId: a.gameId, t: a.t }) ?? { due: null });
+    turnTool("advance_turn", "Move this game's clock to the next turn and say who is due there. Moves time only; runs nothing.", { gameId: z.string().max(100).describe("The game ID") }, ANNOTATIONS.UPDATE, (a) => advanceTurn({ gameId: a.gameId }));
 }

package/dist/rpg/server.d.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Mechanic } from "../timeline/resolve.js";
 import type { RenderVocabulary } from "../timeline/render.js";
+import type { DeclaredRules } from "../timeline/declared.js";
 /**
  * Build the FULL assembly: every core tool plus every RPG tool, resource and
  * prompt this engine has always served. Same name and same `{ mechanics?,
@@ -12,5 +13,6 @@ import type { RenderVocabulary } from "../timeline/render.js";
 export declare function createMcpServer(options?: {
     mechanics?: readonly Mechanic[];
     vocabulary?: RenderVocabulary;
+    rules?: DeclaredRules;
 }): McpServer;
 export { createHttpServer, startHttpServer } from "../http/server.js";

package/dist/schemas/index.d.ts

@@ -83,14 +83,14 @@ export declare const subjectDescriptionSchema: z.ZodObject<{
         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>;
@@ -127,9 +127,9 @@ export declare const subjectDescriptionSchema: z.ZodObject<{
         vegetation?: string | undefined;
     } | undefined;
     objectDetails?: {
+        condition?: string | undefined;
         size?: string | undefined;
         material?: string | undefined;
-        condition?: string | undefined;
         glowOrEffects?: string | undefined;
     } | undefined;
     pose?: string | undefined;
@@ -166,9 +166,9 @@ export declare const subjectDescriptionSchema: z.ZodObject<{
         vegetation?: string | undefined;
     } | undefined;
     objectDetails?: {
+        condition?: string | undefined;
         size?: string | undefined;
         material?: string | undefined;
-        condition?: string | undefined;
         glowOrEffects?: string | undefined;
     } | undefined;
     pose?: string | undefined;
@@ -394,14 +394,14 @@ export declare const imageGenSchema: z.ZodObject<{
             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>;
@@ -438,9 +438,9 @@ export declare const imageGenSchema: z.ZodObject<{
             vegetation?: string | undefined;
         } | undefined;
         objectDetails?: {
+            condition?: string | undefined;
             size?: string | undefined;
             material?: string | undefined;
-            condition?: string | undefined;
             glowOrEffects?: string | undefined;
         } | undefined;
         pose?: string | undefined;
@@ -477,9 +477,9 @@ export declare const imageGenSchema: z.ZodObject<{
             vegetation?: string | undefined;
         } | undefined;
         objectDetails?: {
+            condition?: string | undefined;
             size?: string | undefined;
             material?: string | undefined;
-            condition?: string | undefined;
             glowOrEffects?: string | undefined;
         } | undefined;
         pose?: string | undefined;
@@ -726,9 +726,9 @@ export declare const imageGenSchema: z.ZodObject<{
             vegetation?: string | undefined;
         } | undefined;
         objectDetails?: {
+            condition?: string | undefined;
             size?: string | undefined;
             material?: string | undefined;
-            condition?: string | undefined;
             glowOrEffects?: string | undefined;
         } | undefined;
         pose?: string | undefined;
@@ -822,9 +822,9 @@ export declare const imageGenSchema: z.ZodObject<{
             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/dist/timeline/constrained.d.ts

@@ -190,11 +190,10 @@ export declare function transferConstrainedValue(params: {
  * Fact transitions are joined to their annotation (if any) by
  * `json_extract(causes, '$.fact_id') = facts.id` -- an EXACT, unique link,
  * because `applyLiveWrite` recorded the fact id at write time. This is
- * deliberately stronger than irreversible.ts's `findOpenedByEventId`, which
- * has to approximate the same relationship via `(at_t, row_id)` because the
- * projection triggers that write `row_id` have no fact id to record at the
- * point they fire (issue #2 predates this module). Here, recording the real
- * id costs nothing extra and removes the approximation entirely.
+ * the same move issue #30 later made for a fact's opening event
+ * (`facts.opened_by_event_id`, stamped by the projection trigger in the
+ * firing that opens the fact): record the edge when it is true rather than
+ * approximate it afterward from `(at_t, row_id)`.
  *
  * `json_valid(causes)` guards every extraction, matching irreversible.ts's
  * `CASE WHEN json_valid(causes) THEN causes END` idiom for the same reason

package/dist/timeline/constrained.js

@@ -122,12 +122,23 @@ export function assertConstraintsAllow(params) {
                 throw new ConstraintViolationError("monotonic", entityId, `Resource '${entityId}' is constrained to never increase; rejected change from ${previousValue} to ${intendedValue}.`);
             }
         }
-        if (constraint.kind === "bounded" && bounds) {
-            if (bounds.minValue !== null && intendedValue < bounds.minValue) {
-                throw new ConstraintViolationError("bounded", entityId, `Resource '${entityId}' is bounded-constrained (min ${bounds.minValue}); rejected value ${intendedValue} instead of clamping.`);
-            }
-            if (bounds.maxValue !== null && intendedValue > bounds.maxValue) {
-                throw new ConstraintViolationError("bounded", entityId, `Resource '${entityId}' is bounded-constrained (max ${bounds.maxValue}); rejected value ${intendedValue} instead of clamping.`);
+        if (constraint.kind === "bounded") {
+            // Two sources of bounds, both checked, so the tighter side wins. The
+            // write's own `bounds` are how every 'bounded' constraint has always
+            // worked (a resource's min/max columns, supplied by its caller). A
+            // constraint DECLARED with bounds -- a `create` leg's `constraints`
+            // (issue #42) -- carries its own, and holds them against a write that
+            // supplies none: "held bounded from the moment it exists" means the
+            // declaration binds, not that every later writer must repeat it.
+            // Declared nulls leave that side to the write, as before.
+            const declared = { minValue: constraint.minValue ?? null, maxValue: constraint.maxValue ?? null };
+            for (const pair of bounds ? [declared, bounds] : [declared]) {
+                if (pair.minValue !== null && intendedValue < pair.minValue) {
+                    throw new ConstraintViolationError("bounded", entityId, `Resource '${entityId}' is bounded-constrained (min ${pair.minValue}); rejected value ${intendedValue} instead of clamping.`);
+                }
+                if (pair.maxValue !== null && intendedValue > pair.maxValue) {
+                    throw new ConstraintViolationError("bounded", entityId, `Resource '${entityId}' is bounded-constrained (max ${pair.maxValue}); rejected value ${intendedValue} instead of clamping.`);
+                }
             }
         }
         // 'resolve_only' (design §5.3, §5.2a; issue #13): every direct write to
@@ -270,20 +281,16 @@ function applyLiveWrite(params) {
     const at = new Date().toISOString();
     const delta = newValue - previousValue;
     const eventId = uuidv4();
-    // `causes` deliberately does NOT carry a `row_id` key. irreversible.ts's
-    // `findOpenedByEventId` matches `json_extract(causes, '$.row_id')` to
-    // attach design §5.2c's one hop of provenance, picking the first event at
-    // a given `t` by a random hex id when more than one matches. `row_id` is
-    // the PROJECTION triggers' own token for "the live row this projection
-    // event was generated from" (projection.ts) -- an annotation event this
-    // choke point writes is not a projection event, and if it carried
-    // `row_id` too, a projection event and an annotation event sharing one
-    // `t` (which a constrained write's own UPDATE produces: the `_au`
-    // trigger's `<kind>.updated` event and this `value.changed` event both
-    // land at the same `t`) would make `findOpenedByEventId`'s pick
-    // non-deterministic. `entity_id` is the accurate key for what this event
-    // is about anyway, so using it instead of `row_id` is both the honest
-    // name and the one that can never collide with that lookup.
+    // `causes` carries `entity_id`, not `row_id`. `row_id` is the PROJECTION
+    // triggers' own token for "the live row this projection event was
+    // generated from" (projection.ts), and an annotation event this choke
+    // point writes is not a projection event, so `entity_id` is the honest
+    // name for what it is about. (This once also kept a derived one-hop
+    // lookup deterministic when a projection event and this event shared a
+    // `t`; issue #30 replaced that lookup with the recorded
+    // `facts.opened_by_event_id`, so that reason is gone. `projectionEventId`
+    // below still matches `$.row_id`, but filters by event kind, so it could
+    // not collide either way.)
     const causes = JSON.stringify({
         source: "constrained_write",
         entity_id: entityId,
@@ -555,11 +562,10 @@ export function transferConstrainedValue(params) {
  * Fact transitions are joined to their annotation (if any) by
  * `json_extract(causes, '$.fact_id') = facts.id` -- an EXACT, unique link,
  * because `applyLiveWrite` recorded the fact id at write time. This is
- * deliberately stronger than irreversible.ts's `findOpenedByEventId`, which
- * has to approximate the same relationship via `(at_t, row_id)` because the
- * projection triggers that write `row_id` have no fact id to record at the
- * point they fire (issue #2 predates this module). Here, recording the real
- * id costs nothing extra and removes the approximation entirely.
+ * the same move issue #30 later made for a fact's opening event
+ * (`facts.opened_by_event_id`, stamped by the projection trigger in the
+ * firing that opens the fact): record the edge when it is true rather than
+ * approximate it afterward from `(at_t, row_id)`.
  *
  * `json_valid(causes)` guards every extraction, matching irreversible.ts's
  * `CASE WHEN json_valid(causes) THEN causes END` idiom for the same reason

package/dist/timeline/declared.d.ts

@@ -0,0 +1,147 @@
+import { type T } from "./t.js";
+import type { Mechanic } from "./resolve.js";
+/**
+ * Mechanics, gates and end conditions as DECLARED DATA (GitHub issue #41),
+ * so a stock server can load a game whose rules would otherwise be
+ * TypeScript handed to `createResolver` by whoever assembled it.
+ *
+ * DELIBERATELY SMALL. The issue's admission paragraph scopes the first cut to
+ * what its real caller's rules are made of -- bounded changes to numeric
+ * facts, and gates that open once a fact crosses a threshold -- "a small,
+ * generic subset to start from, not a general rules language". So:
+ *
+ *   - a CONDITION is a named set of clauses (`all` or `any`), each comparing
+ *     one stored fact to a declared value, or naming another condition;
+ *   - a DECLARED MECHANIC applies its `legs` when every condition in `when`
+ *     holds, and its `otherwise` legs (or nothing) when one does not;
+ *   - a leg is `adjust` (current + sign * amount, clamped) or `set`.
+ *
+ * Anything else stays a TypeScript `Mechanic` -- that is the escape hatch, and
+ * both kinds register side by side on one resolver. A rule that needs an
+ * event ("after a search") rather than a fact, or arithmetic across
+ * entities, is the escape hatch's, not a reason to grow this.
+ *
+ * THE ENGINE READS NONE OF IT FOR MEANING (hard rule 4). `id`, `name`,
+ * `for`, `then` and `text` are opaque strings, compared for equality or
+ * carried through. A clause compares a stored value with a declared one:
+ * numerically when both are finite numbers, by equality otherwise -- a
+ * structural comparison of the same kind `contradictions()` makes, never an
+ * interpretation. `holds` is that comparison's result (hard rule 2): a row
+ * saying a stored value meets a declared threshold, never "the game is won".
+ *
+ * WHY `for`/`then` LIVE HERE. A principal's condition list -- "if these hold,
+ * this becomes available to you" -- is what measurably made model-driven
+ * principals act on their unlocks. Declared once, the list a caller renders
+ * and the gate a mechanic enforces are the SAME data, instead of prose kept
+ * in step with code by a test.
+ *
+ * All of it is plain JSON, so it round-trips through a file unchanged; the
+ * application loads one from `DMCP_RULES_FILE` (src/bin/run-dmcp.ts).
+ */
+export type ComparisonOp = "<" | "<=" | "==" | "!=" | ">=" | ">";
+/** A value from the proposal's own parameters, by name. */
+export interface ParamRef {
+    param: string;
+}
+/** An entity: its id, a proposal parameter holding its id, or its name --
+ *  resolved against the entities that have facts at `t`, and reported as
+ *  unresolved when no entity or more than one carries that name. */
+export type EntityOperand = string | ParamRef | {
+    named: string;
+};
+export type FactClause = {
+    entity: EntityOperand;
+    key: string;
+    op: ComparisonOp;
+    value: number | string | ParamRef;
+    /** Opaque, carried through for a caller's condition list. */
+    text?: string;
+};
+export type ConditionClause = FactClause | {
+    condition: string;
+};
+export interface DeclaredCondition {
+    id: string;
+    /** Opaque: whose condition this is, for rendering one principal's list. */
+    for?: string;
+    /** Opaque: what holding it makes available. */
+    then?: string;
+    all?: readonly ConditionClause[];
+    any?: readonly ConditionClause[];
+}
+export type NumberOperand = number | ParamRef;
+export type DeclaredLeg = {
+    kind: "adjust";
+    entity: EntityOperand;
+    key: string;
+    amount: NumberOperand;
+    /** 1 adds, -1 subtracts. Default 1. */
+    sign?: 1 | -1;
+    min?: NumberOperand | null;
+    max?: NumberOperand | null;
+} | {
+    kind: "set";
+    entity: EntityOperand;
+    key: string;
+    value: number | string | null | ParamRef;
+    min?: NumberOperand | null;
+    max?: NumberOperand | null;
+};
+export interface DeclaredMechanic {
+    name: string;
+    /** Condition ids that must ALL hold for `legs` to apply. */
+    when?: readonly string[];
+    legs: readonly DeclaredLeg[];
+    /** Applied instead when a `when` condition does not hold. */
+    otherwise?: readonly DeclaredLeg[];
+}
+export interface DeclaredRules {
+    conditions: readonly DeclaredCondition[];
+    mechanics: readonly DeclaredMechanic[];
+}
+export interface ClauseRow {
+    /** Present for a fact clause. */
+    entityId?: string | null;
+    resolution?: "resolved" | "none" | "ambiguous";
+    key?: string;
+    op?: ComparisonOp;
+    value?: number | string;
+    observed?: number | string | null;
+    /** Present for a clause naming another condition. */
+    condition?: string;
+    /** The proposal parameter this clause needed and was not given; the clause
+     *  then does not hold. A gate that fails because of it is refused naming it. */
+    missingParameter?: string;
+    text?: string;
+    holds: boolean;
+}
+export interface ConditionRow {
+    id: string;
+    for?: string;
+    then?: string;
+    holds: boolean;
+    clauses: ClauseRow[];
+}
+export declare function validateDeclaredRules(rules: DeclaredRules): void;
+type Params = Readonly<Record<string, unknown>>;
+/**
+ * Every declared condition at `t`, in declared order, with whether it holds
+ * and each clause's observed value -- or only the conditions whose `for`
+ * equals the one given, which is a principal's condition list. Read-only.
+ */
+export declare function evaluateConditions(params: {
+    gameId: string;
+    t: T;
+    rules: DeclaredRules;
+    for?: string;
+    parameters?: Params;
+}): ConditionRow[];
+/**
+ * One `Mechanic` per declared mechanic, for `createResolver` beside any
+ * hand-written ones. Each reads only the constraint `resolve()` hands it, like
+ * every mechanic, and returns ordinary changes that go through the one choke
+ * point. `result` records what it did: which gate conditions held, which leg
+ * set applied (`legs`, `otherwise`, or `none`), and each leg's before/after.
+ */
+export declare function declaredMechanics(rules: DeclaredRules): Mechanic[];
+export {};