run-dmcp 0.8.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/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/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