run-dmcp 0.9.0 → 0.10.0

package/dist/timeline/declared.js

@@ -0,0 +1,388 @@
+import { narrationConstraintAt } from "./narration.js";
+import { assertT } from "./t.js";
+const OPS = ["<", "<=", "==", "!=", ">=", ">"];
+// ============================================================================
+// Validation -- once, before anything runs
+// ============================================================================
+function fail(message) {
+    throw new Error(`declared rules: ${message}`);
+}
+function isParamRef(v) {
+    return typeof v === "object" && v !== null && typeof v.param === "string";
+}
+function checkEntity(where, entity) {
+    if (typeof entity === "string")
+        return;
+    if (isParamRef(entity))
+        return;
+    if (typeof entity === "object" && entity !== null && typeof entity.named === "string")
+        return;
+    fail(`${where}: entity must be an id, {param}, or {named}, got ${JSON.stringify(entity)}`);
+}
+function checkNumberOperand(where, field, v, optional) {
+    if (v === undefined || v === null) {
+        if (optional)
+            return;
+        fail(`${where}: '${field}' is required`);
+    }
+    if (typeof v === "number" && Number.isFinite(v))
+        return;
+    if (isParamRef(v))
+        return;
+    fail(`${where}: '${field}' must be a finite number or {param}, got ${JSON.stringify(v)}`);
+}
+function clausesOf(condition) {
+    return condition.all ?? condition.any ?? [];
+}
+export function validateDeclaredRules(rules) {
+    if (!rules || !Array.isArray(rules.conditions) || !Array.isArray(rules.mechanics)) {
+        fail("expected { conditions: [], mechanics: [] }");
+    }
+    const byId = new Map();
+    for (const condition of rules.conditions) {
+        if (typeof condition?.id !== "string" || condition.id.length === 0)
+            fail(`a condition's 'id' must be a non-empty string`);
+        if (byId.has(condition.id))
+            fail(`duplicate condition id '${condition.id}'`);
+        byId.set(condition.id, condition);
+        if ((condition.all === undefined) === (condition.any === undefined)) {
+            fail(`condition '${condition.id}' must declare exactly one of 'all' or 'any'`);
+        }
+        const clauses = clausesOf(condition);
+        if (!Array.isArray(clauses) || clauses.length === 0)
+            fail(`condition '${condition.id}' needs at least one clause`);
+        for (const clause of clauses) {
+            if (typeof clause !== "object" || clause === null)
+                fail(`condition '${condition.id}': a clause must be an object, got ${JSON.stringify(clause)}`);
+            if ("condition" in clause)
+                continue;
+            const where = `condition '${condition.id}'`;
+            checkEntity(where, clause.entity);
+            if (typeof clause.key !== "string" || clause.key.length === 0)
+                fail(`${where}: a clause's 'key' must be a non-empty string`);
+            if (!OPS.includes(clause.op))
+                fail(`${where}: unknown operator '${String(clause.op)}' (one of ${OPS.join(" ")})`);
+            const v = clause.value;
+            if (!(typeof v === "string" || (typeof v === "number" && Number.isFinite(v)) || isParamRef(v))) {
+                fail(`${where}: a clause's 'value' must be a number, a string or {param}, got ${JSON.stringify(v)}`);
+            }
+        }
+    }
+    // References resolve, and never loop.
+    for (const condition of rules.conditions) {
+        for (const clause of clausesOf(condition)) {
+            if ("condition" in clause && !byId.has(clause.condition)) {
+                fail(`condition '${condition.id}' names unknown condition '${clause.condition}'`);
+            }
+        }
+    }
+    const state = new Map();
+    const visit = (id, path) => {
+        if (state.get(id) === "done")
+            return;
+        if (state.get(id) === "visiting")
+            fail(`conditions form a cycle: ${[...path, id].join(" -> ")}`);
+        state.set(id, "visiting");
+        const condition = byId.get(id);
+        for (const clause of condition ? clausesOf(condition) : []) {
+            if ("condition" in clause)
+                visit(clause.condition, [...path, id]);
+        }
+        state.set(id, "done");
+    };
+    for (const condition of rules.conditions)
+        visit(condition.id, []);
+    const names = new Set();
+    for (const mechanic of rules.mechanics) {
+        if (typeof mechanic?.name !== "string" || mechanic.name.length === 0)
+            fail(`a mechanic's 'name' must be a non-empty string`);
+        if (names.has(mechanic.name))
+            fail(`duplicate mechanic name '${mechanic.name}'`);
+        names.add(mechanic.name);
+        if (mechanic.when !== undefined && !Array.isArray(mechanic.when))
+            fail(`mechanic '${mechanic.name}': 'when' must be a list of condition ids`);
+        for (const id of mechanic.when ?? []) {
+            if (!byId.has(id))
+                fail(`mechanic '${mechanic.name}' is gated on unknown condition '${id}'`);
+        }
+        if (!Array.isArray(mechanic.legs))
+            fail(`mechanic '${mechanic.name}' must declare 'legs'`);
+        for (const leg of [...mechanic.legs, ...(mechanic.otherwise ?? [])]) {
+            const where = `mechanic '${mechanic.name}'`;
+            if (leg?.kind !== "adjust" && leg?.kind !== "set")
+                fail(`${where}: unknown leg kind '${String(leg?.kind)}'`);
+            checkEntity(where, leg.entity);
+            if (typeof leg.key !== "string" || leg.key.length === 0)
+                fail(`${where}: a leg's 'key' must be a non-empty string`);
+            if (leg.kind === "adjust") {
+                checkNumberOperand(where, "amount", leg.amount, false);
+                if (leg.sign !== undefined && leg.sign !== 1 && leg.sign !== -1)
+                    fail(`${where}: 'sign' must be 1 or -1`);
+            }
+            if (leg.kind === "set") {
+                const v = leg.value;
+                if (!("value" in leg) || !(v === null || typeof v === "string" || (typeof v === "number" && Number.isFinite(v)) || isParamRef(v))) {
+                    fail(`${where}: a set leg's 'value' must be a number, a string, null or {param}, got ${JSON.stringify(v)}`);
+                }
+            }
+            checkNumberOperand(where, "min", leg.min, true);
+            checkNumberOperand(where, "max", leg.max, true);
+            if (typeof leg.min === "number" && typeof leg.max === "number" && leg.min > leg.max) {
+                fail(`${where}: min ${leg.min} is above max ${leg.max}`);
+            }
+        }
+    }
+}
+function param(params, name, type) {
+    const v = params[name];
+    const ok = type === "number"
+        ? typeof v === "number" && Number.isFinite(v)
+        : type === "string"
+            ? typeof v === "string"
+            : typeof v === "string" || v === null || (typeof v === "number" && Number.isFinite(v));
+    if (!ok)
+        throw new Error(`declared rules: parameter '${name}' must be a ${type === "scalar" ? "number, string or null" : type}, got ${JSON.stringify(v)}`);
+    return v;
+}
+function numberOf(operand, params) {
+    return isParamRef(operand) ? param(params, operand.param, "number") : operand;
+}
+/** Stored fact values are text ("100.0"); one that is a plain decimal
+ *  number -- optional sign, digits, optional fraction and exponent, nothing
+ *  else -- is compared as a number. Hex, padding, "Infinity" and words stay
+ *  strings, compared by exact equality. */
+function isPlainNumber(text) {
+    // A character scan, not a pattern: the timeline modules construct no regex
+    // (hard rule 4's guard), and this is a question about characters anyway.
+    const digit = (c) => c !== undefined && c >= "0" && c <= "9";
+    let i = 0;
+    if (text[i] === "-")
+        i++;
+    let digits = 0;
+    while (digit(text[i])) {
+        i++;
+        digits++;
+    }
+    if (text[i] === ".") {
+        i++;
+        while (digit(text[i])) {
+            i++;
+            digits++;
+        }
+    }
+    if (digits === 0)
+        return false;
+    if (text[i] === "e" || text[i] === "E") {
+        i++;
+        if (text[i] === "+" || text[i] === "-")
+            i++;
+        if (!digit(text[i]))
+            return false;
+        while (digit(text[i]))
+            i++;
+    }
+    return i === text.length;
+}
+function asNumber(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : null;
+    if (v === null || !isPlainNumber(v))
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+/** Only facts that HOLD at t: a narration constraint also carries a destroyed
+ *  entity's irreversible facts, which must neither answer a value nor make a
+ *  name ambiguous. */
+function indexFacts(facts, t) {
+    const values = new Map();
+    const idsByName = new Map();
+    for (const fact of facts) {
+        if (fact.validFromT > t || (fact.validToT !== null && fact.validToT <= t))
+            continue;
+        values.set(`${fact.entityId}\u0000${fact.key}`, fact.value);
+        if (fact.entityName !== null) {
+            const ids = idsByName.get(fact.entityName) ?? new Set();
+            ids.add(fact.entityId);
+            idsByName.set(fact.entityName, ids);
+        }
+    }
+    return {
+        value: (entityId, key) => values.get(`${entityId}\u0000${key}`) ?? null,
+        overlay: (entityId, key, value) => void values.set(`${entityId}\u0000${key}`, value),
+        byName: (name) => {
+            const ids = idsByName.get(name);
+            if (!ids || ids.size === 0)
+                return { entityId: null, resolution: "none" };
+            if (ids.size > 1)
+                return { entityId: null, resolution: "ambiguous" };
+            return { entityId: [...ids][0], resolution: "resolved" };
+        },
+    };
+}
+function resolveEntity(entity, params, facts) {
+    if (typeof entity === "string")
+        return { entityId: entity, resolution: "resolved" };
+    if (isParamRef(entity))
+        return { entityId: param(params, entity.param, "string"), resolution: "resolved" };
+    return facts.byName(entity.named);
+}
+function compare(observed, op, declared) {
+    if (observed === null)
+        return false;
+    const a = asNumber(observed);
+    const b = asNumber(declared);
+    if (a !== null && b !== null) {
+        switch (op) {
+            case "<": return a < b;
+            case "<=": return a <= b;
+            case "==": return a === b;
+            case "!=": return a !== b;
+            case ">=": return a >= b;
+            case ">": return a > b;
+        }
+    }
+    // Not both numbers: equality only, exact, no normalisation of any kind.
+    if (op === "==")
+        return observed === String(declared);
+    if (op === "!=")
+        return observed !== String(declared);
+    return false;
+}
+/** Evaluates `roots` (default: every condition) and whatever they reference --
+ *  lazily, so a gate never touches an unrelated condition, whose parameters
+ *  the proposal has no reason to carry. */
+function evaluateAll(rules, facts, params, roots) {
+    const byId = new Map(rules.conditions.map((c) => [c.id, c]));
+    const rows = new Map();
+    const evaluate = (id) => {
+        const done = rows.get(id);
+        if (done)
+            return done;
+        const condition = byId.get(id);
+        if (!condition)
+            throw new Error(`declared rules: unknown condition '${id}'`); // validated away; guarded, not asserted
+        const clauses = clausesOf(condition).map((clause) => {
+            if ("condition" in clause)
+                return { condition: clause.condition, holds: evaluate(clause.condition).holds };
+            // A parameter the proposal did not carry makes a row, not a throw: a
+            // condition list shows every condition, and only a gate that FAILS on
+            // one refuses (declaredMechanics, below).
+            const missing = [clause.entity, clause.value].find((o) => isParamRef(o) && params[o.param] === undefined);
+            if (missing) {
+                return { key: clause.key, op: clause.op, missingParameter: missing.param, ...(clause.text !== undefined ? { text: clause.text } : {}), holds: false };
+            }
+            const { entityId, resolution } = resolveEntity(clause.entity, params, facts);
+            const declared = isParamRef(clause.value) ? param(params, clause.value.param, "scalar") : clause.value;
+            const raw = entityId === null ? null : facts.value(entityId, clause.key);
+            const observedNumber = raw === null ? null : asNumber(raw);
+            return {
+                entityId,
+                resolution,
+                key: clause.key,
+                op: clause.op,
+                value: declared,
+                observed: raw === null ? null : (observedNumber ?? raw),
+                ...(clause.text !== undefined ? { text: clause.text } : {}),
+                holds: compare(raw, clause.op, declared),
+            };
+        });
+        const holds = condition.all ? clauses.every((c) => c.holds) : clauses.some((c) => c.holds);
+        const row = {
+            id,
+            ...(condition.for !== undefined ? { for: condition.for } : {}),
+            ...(condition.then !== undefined ? { then: condition.then } : {}),
+            holds,
+            clauses,
+        };
+        rows.set(id, row);
+        return row;
+    };
+    for (const id of roots ?? rules.conditions.map((c) => c.id))
+        evaluate(id);
+    return rows;
+}
+/**
+ * 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 function evaluateConditions(params) {
+    validateDeclaredRules(params.rules);
+    assertT(params.t);
+    const facts = indexFacts(narrationConstraintAt({ gameId: params.gameId, t: params.t }).mustHonor, params.t);
+    const listed = params.rules.conditions.filter((c) => params.for === undefined || c.for === params.for);
+    const rows = evaluateAll(params.rules, facts, params.parameters ?? {}, listed.map((c) => c.id));
+    return listed.flatMap((c) => rows.get(c.id) ?? []);
+}
+// ============================================================================
+// Mechanics -- ordinary `Mechanic`s built from the declaration
+// ============================================================================
+function legToChange(leg, params, facts) {
+    const { entityId } = resolveEntity(leg.entity, params, facts);
+    if (entityId === null) {
+        throw new Error(`declared rules: leg names entity ${JSON.stringify(leg.entity)}, which does not resolve to exactly one entity`);
+    }
+    const min = leg.min === undefined || leg.min === null ? null : numberOf(leg.min, params);
+    const max = leg.max === undefined || leg.max === null ? null : numberOf(leg.max, params);
+    const bounds = min !== null || max !== null ? { bounds: { minValue: min, maxValue: max } } : {};
+    const beforeRaw = facts.value(entityId, leg.key);
+    const recorded = (change, before, after) => {
+        // A later leg of the same mechanic on the same key reads this one's result.
+        facts.overlay(entityId, leg.key, after === null ? null : String(after));
+        return { change, record: { entityId, key: leg.key, before, after } };
+    };
+    if (leg.kind === "adjust") {
+        const before = beforeRaw === null ? null : asNumber(beforeRaw);
+        if (before === null) {
+            throw new Error(`declared rules: no numeric fact '${leg.key}' on entity '${entityId}' to adjust`);
+        }
+        let after = before + (leg.sign ?? 1) * numberOf(leg.amount, params);
+        if (min !== null)
+            after = Math.max(min, after);
+        if (max !== null)
+            after = Math.min(max, after);
+        return recorded({ kind: "write", entityId, key: leg.key, mode: "set", value: after, ...bounds }, before, after);
+    }
+    const value = isParamRef(leg.value) ? param(params, leg.value.param, "scalar") : leg.value;
+    const before = beforeRaw === null ? null : (asNumber(beforeRaw) ?? beforeRaw);
+    if (typeof value === "number") {
+        return recorded({ kind: "write", entityId, key: leg.key, mode: "set", value, ...bounds }, before, value);
+    }
+    return recorded({ kind: "set", entityId, key: leg.key, value }, before, value);
+}
+/**
+ * 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 function declaredMechanics(rules) {
+    validateDeclaredRules(rules);
+    return rules.mechanics.map((declared) => ({
+        name: declared.name,
+        adjudicate(input) {
+            const params = input.parameters ?? {};
+            const facts = indexFacts(input.constraint.mustHonor, input.t);
+            const evaluated = evaluateAll(rules, facts, params, declared.when ?? []);
+            const when = (declared.when ?? []).map((id) => ({ id, holds: evaluated.get(id)?.holds === true }));
+            const gateHolds = when.every((w) => w.holds);
+            if (!gateHolds) {
+                // A gate that fails only because the proposal lacked a parameter is a
+                // malformed proposal, not a closed gate: refuse it, naming what is missing.
+                const missing = [...evaluated.values()].flatMap((row) => row.clauses).find((c) => c.missingParameter !== undefined);
+                if (missing) {
+                    throw new Error(`declared rules: mechanic '${declared.name}' needs parameter '${missing.missingParameter}' to evaluate its gate`);
+                }
+            }
+            const legs = gateHolds ? declared.legs : (declared.otherwise ?? []);
+            const applied = gateHolds ? "legs" : declared.otherwise && declared.otherwise.length > 0 ? "otherwise" : "none";
+            const built = legs.map((leg) => legToChange(leg, params, facts));
+            return {
+                changes: built.map((b) => b.change),
+                result: { applied, when, legs: built.map((b) => b.record) },
+            };
+        },
+    }));
+}

package/dist/timeline/render.d.ts

@@ -97,9 +97,12 @@ export interface RenderedState {
     unnamed: UnnamedFact[];
 }
 export interface StateRenderer {
+    /** `entityIds` scopes the render to a caller's selection (issue #18), with
+     *  replay()'s semantics: omitted is unscoped, `[]` renders nothing. */
     render(params: {
         gameId: string;
         t: T;
+        entityIds?: readonly string[];
     }): RenderedState;
 }
 /**

package/dist/timeline/render.js

@@ -125,7 +125,7 @@ function composePhrase(entry) {
  * uses.
  */
 function renderState(vocabulary, params) {
-    const snapshot = replay({ gameId: params.gameId, t: params.t });
+    const snapshot = replay({ gameId: params.gameId, t: params.t, entityIds: params.entityIds });
     const nouns = [];
     const unnamed = [];
     for (const entity of snapshot.entities) {

package/dist/timeline/replay.d.ts

@@ -60,6 +60,20 @@ export interface Snapshot {
  *
  * DECISION(#18): replay() applies no visibility filtering, by decision rather than omission.
  *
+ * DECISION(#18): a per-principal view is the caller's selection; the engine scopes a read to it (entityIds), and holds no principal relation.
+ *
+ * SCOPED, NOT FILTERED (issue #18, decided 2026-09-26). `entityIds` restricts
+ * the snapshot to a selection the CALLER built -- which entities a principal
+ * perceives -- and a scoped snapshot is exactly the unscoped one restricted
+ * to those entities, never a different answer. The first real caller's
+ * measurement settled where the line falls: both of its view builders select
+ * positively and subtract nothing, from game-specific predicates (a
+ * concealment threshold, containers, shared location) the engine has no
+ * business owning. What it could not do was ask for the selection, so it
+ * read the omniscient world and picked from it. The principal relation stays
+ * in the caller; the paragraphs below about omniscience still describe what
+ * an unscoped read returns.
+ *
  * OMNISCIENT, DELIBERATELY (issue #18). This returns every fact valid at
  * `t`, for every entity alive at `t`, with no visibility filtering of any
  * kind. That is a decision, not an omission: per-principal visibility is
@@ -83,4 +97,5 @@ export interface Snapshot {
 export declare function replay(params: {
     gameId: string;
     t: T;
+    entityIds?: readonly string[];
 }): Snapshot;

package/dist/timeline/replay.js

@@ -39,6 +39,20 @@ const ALIVE_AT_T = "e.created_at_t <= ? AND (e.destroyed_at_t IS NULL OR e.destr
  *
  * DECISION(#18): replay() applies no visibility filtering, by decision rather than omission.
  *
+ * DECISION(#18): a per-principal view is the caller's selection; the engine scopes a read to it (entityIds), and holds no principal relation.
+ *
+ * SCOPED, NOT FILTERED (issue #18, decided 2026-09-26). `entityIds` restricts
+ * the snapshot to a selection the CALLER built -- which entities a principal
+ * perceives -- and a scoped snapshot is exactly the unscoped one restricted
+ * to those entities, never a different answer. The first real caller's
+ * measurement settled where the line falls: both of its view builders select
+ * positively and subtract nothing, from game-specific predicates (a
+ * concealment threshold, containers, shared location) the engine has no
+ * business owning. What it could not do was ask for the selection, so it
+ * read the omniscient world and picked from it. The principal relation stays
+ * in the caller; the paragraphs below about omniscience still describe what
+ * an unscoped read returns.
+ *
  * OMNISCIENT, DELIBERATELY (issue #18). This returns every fact valid at
  * `t`, for every entity alive at `t`, with no visibility filtering of any
  * kind. That is a decision, not an omission: per-principal visibility is
@@ -65,6 +79,21 @@ export function replay(params) {
     // it can silently compare unequal to every row and produce a confidently
     // wrong empty snapshot.
     assertT(t);
+    // Scope (issue #18): the snapshot restricted to a caller's selection. Bound
+    // as ONE JSON array through `json_each`, so the SQL text stays fixed and
+    // the bind count stays constant whatever the list's length -- the same two
+    // properties the paragraph above keeps for the unscoped read. Omitted is
+    // unscoped; `[]` narrows to nothing, as narrationConstraintAt's does.
+    const entityIds = params.entityIds;
+    if (entityIds !== undefined) {
+        if (!Array.isArray(entityIds) || entityIds.some((id) => typeof id !== "string")) {
+            throw new Error(`replay: entityIds must be a list of entity id strings, got ${JSON.stringify(entityIds)}`);
+        }
+        if (entityIds.length === 0)
+            return { gameId, t, entities: [] };
+    }
+    const scope = entityIds === undefined ? null : JSON.stringify(entityIds);
+    const SCOPED = "(? IS NULL OR e.id IN (SELECT value FROM json_each(?)))";
     const db = getDatabase();
     // Query 1 of 2: which entities were alive at t, in the caller-diffable
     // order the design calls for (created_at_t, then id -- id as the
@@ -75,8 +104,9 @@ export function replay(params) {
        FROM entities e
        WHERE e.game_id = ?
          AND ${ALIVE_AT_T}
+         AND ${SCOPED}
        ORDER BY e.created_at_t, e.id`)
-        .all(gameId, t, t);
+        .all(gameId, t, t, scope, scope);
     const entities = entityRows.map((row) => ({
         id: row.id,
         kind: row.kind,
@@ -107,10 +137,11 @@ export function replay(params) {
        JOIN entities e ON e.id = f.entity_id
        WHERE e.game_id = ?
          AND ${ALIVE_AT_T}
+         AND ${SCOPED}
          AND f.valid_from_t <= ?
          AND (f.valid_to_t IS NULL OR f.valid_to_t > ?)
        ORDER BY f.valid_from_t`)
-        .all(gameId, t, t, t, t);
+        .all(gameId, t, t, scope, scope, t, t);
     for (const factRow of factRows) {
         const entity = byId.get(factRow.entity_id);
         // Cannot happen: every fact row came from a JOIN against entities e

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
@@ -329,7 +335,11 @@ 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"

package/dist/timeline/resolve.js

@@ -1,10 +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 } from "./registry.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 --
@@ -102,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
@@ -226,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),
                 }),
             ],
         };
@@ -293,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
@@ -391,6 +421,7 @@ function resolveProposal(mechanicsByName, proposal) {
             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