run-dmcp 0.1.0 → 0.3.0

package/dist/timeline/registry.js

@@ -0,0 +1,124 @@
+import { getDatabase } from "../db/connection.js";
+/**
+ * The read side of the resource-constraint registry (design §5.3 / §5.4
+ * option (C)): declarative, opt-in, server-enforced invariants on numeric
+ * fact keys, keyed on `(entityId, factKey)` rather than on an entity id
+ * alone.
+ *
+ * This lives in src/timeline/ -- not src/tools/constraint.ts, where the code
+ * below used to live -- so that the generic write choke point Phase 3
+ * introduces next (also under src/timeline/) can consult it WITHOUT
+ * importing anything from src/tools/. That import direction is what would
+ * otherwise close a cycle: src/tools/constraint.ts already imports
+ * src/tools/resource.ts (for getResource()), and the future choke point
+ * will need to check what's declared here before it writes a fact -- if the
+ * read side still lived in tools/constraint.ts, that edge would run
+ * tools/resource.ts -> timeline/<choke point> -> tools/constraint.ts, and
+ * tools/constraint.ts already sits downstream of tools/resource.ts. Moving
+ * 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.
+ */
+/** Absolute tolerance for floating-point sum comparisons on 'conserved'
+ * constraints. IEEE 754 doubles cannot represent values like 0.1 exactly,
+ * so repeated addition/subtraction across many transfers can drift by a
+ * few ULPs. This is large enough to absorb that drift over realistic
+ * transfer volumes while still catching an actual logic bug (which would
+ * typically desync the sum by a whole `amount`, not a fraction of one). */
+export const CONSERVED_SUM_EPSILON = 1e-6;
+export class ConstraintViolationError extends Error {
+    constraintKind;
+    resourceId;
+    contradictedFact;
+    constructor(constraintKind, resourceId, message, 
+    /** Design decision #7 / §5.2c's one hop of causality, attached as typed
+     *  data and not only baked into `message` -- a reviewer at a fired check
+     *  has to decide "is the fact wrong or is the claim wrong," and parsing
+     *  that back out of a sentence is exactly the shape §5.2c exists to
+     *  prevent. Only ever set when `constraintKind === "irreversible"`;
+     *  every other family in this union has no contradicted fact to attach,
+     *  so `undefined` is the correct default rather than a fourth sentinel
+     *  value. */
+    contradictedFact) {
+        super(message);
+        this.constraintKind = constraintKind;
+        this.resourceId = resourceId;
+        this.contradictedFact = contradictedFact;
+        this.name = "ConstraintViolationError";
+    }
+}
+/** The resource ids belonging to a constraint, in insertion order. Exported
+ * alongside ConstraintRow/rowToConstraint for the same reason. */
+export function memberIdsFor(constraintId) {
+    const db = getDatabase();
+    const rows = db
+        .prepare(`SELECT resource_id FROM resource_constraint_members WHERE constraint_id = ? ORDER BY rowid`)
+        .all(constraintId);
+    return rows.map((r) => r.resource_id);
+}
+export function rowToConstraint(row) {
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        kind: row.kind,
+        resourceIds: memberIdsFor(row.id),
+        direction: row.direction,
+        total: row.total,
+        factKey: row.fact_key,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Shared query underlying every constraint lookup by entity id, so the JOIN
+ * against resource_constraint_members is written exactly once. `factKey`
+ * omitted means "any key" -- today's getConstraintsForResource() behaviour
+ * (src/tools/constraint.ts), preserved for the one caller that still needs
+ * it. Every OTHER caller must pass a factKey; see constraintsFor() below.
+ */
+function queryConstraintsForEntity(entityId, factKey) {
+    const db = getDatabase();
+    const conditions = ["rcm.resource_id = ?"];
+    const args = [entityId];
+    if (factKey !== undefined) {
+        conditions.push("rc.fact_key = ?");
+        args.push(factKey);
+    }
+    const rows = db
+        .prepare(`SELECT rc.* FROM resource_constraints rc
+       JOIN resource_constraint_members rcm ON rcm.constraint_id = rc.id
+       WHERE ${conditions.join(" AND ")}
+       ORDER BY rc.created_at`)
+        .all(...args);
+    return rows.map(rowToConstraint);
+}
+/**
+ * Every constraint governing `(entityId, factKey)`, ordered by
+ * `created_at`. This is the whole point of Phase 3 step 1: a constraint
+ * declared on one fact key of an entity must never be visible when a
+ * different fact key of that SAME entity is asked about, even though today
+ * every constraint happens to govern the same key ('value').
+ */
+export function constraintsFor(entityId, factKey) {
+    return queryConstraintsForEntity(entityId, factKey);
+}
+/**
+ * Every constraint governing `entityId`, regardless of fact key. Exists
+ * only so getConstraintsForResource() (src/tools/constraint.ts) can keep
+ * its pre-Phase-3 "all keys" behaviour without a second copy of the JOIN
+ * above -- new callers should prefer constraintsFor(), which cannot
+ * accidentally forget to scope by key.
+ */
+export function allConstraintsForEntity(entityId) {
+    return queryConstraintsForEntity(entityId);
+}
+/** The 'conserved' constraint governing `(entityId, factKey)`, or `null` if
+ * none is declared. At most one can exist for a given key: declareConservedConstraint()
+ * (src/tools/constraint.ts) rejects overlapping conserved membership on the
+ * same key. */
+export function conservedConstraintFor(entityId, factKey) {
+    return constraintsFor(entityId, factKey).find((c) => c.kind === "conserved") ?? null;
+}

package/dist/timeline/render.d.ts

@@ -0,0 +1,121 @@
+import { type T } from "./t.js";
+import type { EntityKind } from "./kinds.js";
+/**
+ * The engine's state-to-text projection (design §7/§8, GitHub issue #16):
+ * "say what IS true, never what is absent." *"The grain stores are full and
+ * the treasury coffers overflow"* -- never *"the grain stores are no longer
+ * empty."*
+ *
+ * **The rule is enforced AT CONSTRUCTION, not by scanning generated text.**
+ * `createStateRenderer` validates a caller-injected `RenderVocabulary` once,
+ * up front, and every guard below exists to make negation UNCONSTRUCTABLE
+ * rather than detected (root CLAUDE.md hard rule 4, design §7's hazard
+ * paragraph): a `VocabularyEntry` has exactly two fields, `noun` and
+ * `adjectives`, both positive by construction -- there is no free-text
+ * sentence field, no template string with holes, and no field a negation
+ * could be written into. This module never scans generated text, never
+ * matches a word against a list, and never inspects any string this
+ * codebase did not itself define as an object key (hard rule 4's "a token
+ * WE defined" exception, applied here to the literal `noun`/`adjectives`
+ * check in `resolveEntry` below).
+ *
+ * **Mechanism is core; the vocabulary is injected by each caller.** This
+ * module ships NOT ONE vocabulary entry, example or default -- a vocabulary
+ * rich enough to render a real world contains client-specific nouns, and
+ * either sitting in this file would fail `engineVocabulary.test.ts` on day
+ * one, correctly (design §7's closing paragraph, §10). `RenderVocabulary` is
+ * a parameter type, never a value exported from here.
+ *
+ * **Output is generated ONLY from facts that hold at `t`.** The sole source
+ * of state is `replay({gameId, t})` (replay.ts) -- there is no diff, no
+ * set-complement against another `t`, no "expected keys minus present
+ * keys." A fact that does not hold at `t` produces NOTHING: not a phrase
+ * about its absence, not an "unknown," not a placeholder. Silence. A fact
+ * that DOES hold but has no vocabulary entry is reported as a row in
+ * `unnamed` -- a caller learns its vocabulary is too thin from a row, never
+ * from invented or negated text (the vocabulary-richness contract, task
+ * brief / design §7).
+ *
+ * **No transition/differential API.** There is no `renderChange(before,
+ * after)` and nothing here takes two `t`s -- that is precisely the shape
+ * that produces "no longer." State at one `t`, full stop
+ * (`render.test.ts`'s "module export surface" test locks the runtime export
+ * list to exactly `createStateRenderer` so a second, differential entry
+ * point cannot be added silently).
+ */
+/**
+ * A positive concrete noun naming a thing that is present, with optional
+ * positive adjectives qualifying it. This is the ENTIRE vocabulary
+ * language: there is no sentence field, no connective, no place for a
+ * negation to live. `resolveEntry` below refuses any object carrying a key
+ * other than these two -- the guard that stops an `avoid`/`unless`/`negate`
+ * field from being bolted on later.
+ */
+export interface VocabularyEntry {
+    /** A positive concrete noun naming a thing that is present. Required, non-empty after trim. */
+    noun: string;
+    /** Optional positive adjectives qualifying that noun. Each non-empty after trim. */
+    adjectives?: readonly string[];
+}
+/**
+ * Keyed by fact `key`, then by fact `value`. Both exact matches -- no
+ * pattern matching, no globs, no fallback entry, no wildcard key (hard rule
+ * 4: this module never matches meaning, only exact keys it was handed).
+ */
+export type RenderVocabulary = Readonly<Record<string, Readonly<Record<string, VocabularyEntry>>>>;
+/** One fact that held at `t` and was named by the injected vocabulary. */
+export interface RenderedNoun {
+    entityId: string;
+    entityKind: EntityKind;
+    entityName: string | null;
+    key: string;
+    value: string;
+    noun: string;
+    adjectives: readonly string[];
+    /** The noun and its adjectives joined -- the ONLY text this module composes. */
+    phrase: string;
+}
+/**
+ * A fact that held at `t` and had no vocabulary entry. A row, never a
+ * verdict (root CLAUDE.md hard rule 2) -- there is deliberately no
+ * `isComplete`/coverage/severity field anywhere near this shape. Carries no
+ * `noun`/`adjectives`/`phrase`: there is nothing to say about it, and this
+ * module never invents something to say.
+ */
+export interface UnnamedFact {
+    entityId: string;
+    entityKind: EntityKind;
+    entityName: string | null;
+    key: string;
+    value: string;
+}
+/** Everything the projection could say about a game at `t`, and everything it could not. */
+export interface RenderedState {
+    gameId: string;
+    t: T;
+    nouns: RenderedNoun[];
+    unnamed: UnnamedFact[];
+}
+export interface StateRenderer {
+    render(params: {
+        gameId: string;
+        t: T;
+    }): RenderedState;
+}
+/**
+ * Builds a `StateRenderer` over a caller-injected `vocabulary`. Validation
+ * happens ONCE here, over the whole vocabulary, never lazily per `render`
+ * call -- a vocabulary that would be invalid for entity #4,000 is refused
+ * before entity #1 is ever rendered, and every `render()` call after
+ * construction reuses the same validated, frozen internal copy rather than
+ * re-checking anything.
+ *
+ * Throws (see `resolveVocabulary`/`resolveEntry` above) on: an entry whose
+ * `noun` is missing, not a string, or empty/whitespace after trim; any
+ * `adjectives` element that is not a string or is empty/whitespace after
+ * trim; an entry object carrying any key other than `noun`/`adjectives`
+ * (named in the error); and an empty vocabulary.
+ */
+export declare function createStateRenderer(params: {
+    vocabulary: RenderVocabulary;
+}): StateRenderer;

package/dist/timeline/render.js

@@ -0,0 +1,187 @@
+import { replay } from "./replay.js";
+/**
+ * Exactly the fields `VocabularyEntry` declares. This is a literal check
+ * against identifiers THIS MODULE defined in a type THIS MODULE specified
+ * -- explicitly permitted by hard rule 4 -- and it is the load-bearing
+ * guard named in the task brief: it is what stops a caller (or a future
+ * editor of a caller's vocabulary file) from bolting an `avoid:`, an
+ * `unless:`, or a `negate:` field onto an entry six months from now. Any
+ * key outside this set is refused, by name, at construction.
+ */
+const ALLOWED_ENTRY_FIELDS = new Set(["noun", "adjectives"]);
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (Array.isArray(value))
+        return "an array";
+    const type = typeof value;
+    if (type === "object")
+        return "an object";
+    return `a ${type} (${JSON.stringify(value)})`;
+}
+/**
+ * Validates and defensively copies one `(key, value) -> entry` mapping.
+ * Never returns a reference into the caller's own object graph -- every
+ * field is read once and copied into a fresh, frozen object -- so a caller
+ * that holds onto its original vocabulary object and mutates it after
+ * construction (adding a forbidden field, blanking a noun) can never affect
+ * what a renderer built from it produces. `render.test.ts`'s
+ * "frozen/defensive-copy behaviour" test proves this by mutating the
+ * original object after `createStateRenderer` returns and asserting the
+ * renderer's output is unchanged.
+ */
+function resolveEntry(entry, key, value) {
+    const path = `["${key}"]["${value}"]`;
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new Error(`render vocabulary: entry at ${path} must be an object with a "noun" field, got ${describeValue(entry)}`);
+    }
+    const record = entry;
+    for (const field of Object.keys(record)) {
+        if (!ALLOWED_ENTRY_FIELDS.has(field)) {
+            throw new Error(`render vocabulary: entry at ${path} carries an unrecognized field "${field}". A vocabulary entry may ` +
+                `only declare "noun" and "adjectives" -- this refusal is what stops a forbidden field (an "avoid", a ` +
+                `"negate", a "mustNotSay") from being bolted onto the vocabulary later (root CLAUDE.md hard rules 4 ` +
+                `and 5, design §7).`);
+        }
+    }
+    if (typeof record.noun !== "string" || record.noun.trim().length === 0) {
+        throw new Error(`render vocabulary: entry at ${path}.noun must be a non-empty string, got ${describeValue(record.noun)}`);
+    }
+    let adjectives = [];
+    if (record.adjectives !== undefined) {
+        if (!Array.isArray(record.adjectives)) {
+            throw new Error(`render vocabulary: entry at ${path}.adjectives must be an array of strings, got ` +
+                `${describeValue(record.adjectives)}`);
+        }
+        adjectives = record.adjectives.map((adjective, index) => {
+            if (typeof adjective !== "string" || adjective.trim().length === 0) {
+                throw new Error(`render vocabulary: entry at ${path}.adjectives[${index}] must be a non-empty string, got ` +
+                    `${describeValue(adjective)}`);
+            }
+            return adjective;
+        });
+    }
+    return Object.freeze({ noun: record.noun, adjectives: Object.freeze(adjectives) });
+}
+/**
+ * Validates the WHOLE vocabulary once, at construction (never lazily per
+ * render -- see `createStateRenderer`), and returns a frozen, defensively
+ * copied internal form. Every reachable value is copied by primitive field,
+ * never by object reference, so nothing in the returned structure can be
+ * reached and mutated through the caller's original `vocabulary` argument.
+ */
+function resolveVocabulary(vocabulary) {
+    if (typeof vocabulary !== "object" || vocabulary === null || Array.isArray(vocabulary)) {
+        throw new Error(`render vocabulary: vocabulary must be an object mapping fact keys to value->entry maps, got ` +
+            `${describeValue(vocabulary)}`);
+    }
+    const resolved = {};
+    let entryCount = 0;
+    for (const key of Object.keys(vocabulary)) {
+        const valuesForKey = vocabulary[key];
+        if (typeof valuesForKey !== "object" || valuesForKey === null || Array.isArray(valuesForKey)) {
+            throw new Error(`render vocabulary: vocabulary["${key}"] must be an object mapping fact values to vocabulary entries, ` +
+                `got ${describeValue(valuesForKey)}`);
+        }
+        const resolvedValues = {};
+        for (const value of Object.keys(valuesForKey)) {
+            const entry = valuesForKey[value];
+            resolvedValues[value] = resolveEntry(entry, key, value);
+            entryCount++;
+        }
+        resolved[key] = Object.freeze(resolvedValues);
+    }
+    // A renderer that can name nothing is a configuration error, not a
+    // silent no-op -- an empty vocabulary would render every real fact into
+    // `unnamed` forever, which is a caller mistake worth refusing loudly
+    // rather than a legitimate "narrows to nothing" the way an empty
+    // `entityIds` list is elsewhere in this codebase (narration.ts).
+    if (entryCount === 0) {
+        throw new Error("render vocabulary: an empty vocabulary can name nothing at all -- that is a configuration error, not a " +
+            "silent no-op. Supply at least one (key, value) -> { noun, adjectives? } entry.");
+    }
+    return Object.freeze(resolved);
+}
+/** The noun and its adjectives joined -- the ONLY text this module composes. */
+function composePhrase(entry) {
+    return [...entry.adjectives, entry.noun].join(" ");
+}
+/**
+ * Renders one game's world at `t`. Reads `replay({gameId, t})` -- the sole
+ * source of state -- and nothing else.
+ *
+ * Ordering is deterministic and total, bottoming out at columns SQLite
+ * guarantees unique, copying `narration.ts`/`export.ts`'s discipline:
+ * `replay()` already orders entities by `(createdAtT, id)`, and `id` is the
+ * entities primary key, so that half is already a total order. Within one
+ * entity, interval versioning guarantees at most one fact per `key` is
+ * valid at a single `t` (replay.ts's own doc comment), so sorting that
+ * entity's fact keys ascending is itself a total order over that entity's
+ * facts -- no tie a fact `key` could produce. Two renders of the same world
+ * therefore produce identical arrays; `render.test.ts`'s determinism test
+ * checks this with `JSON.stringify` equality, the same proof `narration.ts`
+ * uses.
+ */
+function renderState(vocabulary, params) {
+    const snapshot = replay({ gameId: params.gameId, t: params.t });
+    const nouns = [];
+    const unnamed = [];
+    for (const entity of snapshot.entities) {
+        const keys = Object.keys(entity.facts).sort();
+        for (const key of keys) {
+            const fact = entity.facts[key];
+            const entry = vocabulary[key]?.[fact.value];
+            if (entry) {
+                nouns.push({
+                    entityId: entity.id,
+                    entityKind: entity.kind,
+                    entityName: entity.name,
+                    key,
+                    value: fact.value,
+                    noun: entry.noun,
+                    adjectives: entry.adjectives,
+                    phrase: composePhrase(entry),
+                });
+            }
+            else {
+                // A fact with no vocabulary entry is OMITTED as text, but REPORTED
+                // as a row -- the vocabulary-richness contract (task brief, design
+                // §7): the engine records the gap, never invents a noun, never
+                // negates, and passes no judgement on it (root CLAUDE.md hard rule
+                // 2 -- no isComplete, no coverage percentage, no severity).
+                unnamed.push({
+                    entityId: entity.id,
+                    entityKind: entity.kind,
+                    entityName: entity.name,
+                    key,
+                    value: fact.value,
+                });
+            }
+        }
+    }
+    return { gameId: snapshot.gameId, t: snapshot.t, nouns, unnamed };
+}
+/**
+ * Builds a `StateRenderer` over a caller-injected `vocabulary`. Validation
+ * happens ONCE here, over the whole vocabulary, never lazily per `render`
+ * call -- a vocabulary that would be invalid for entity #4,000 is refused
+ * before entity #1 is ever rendered, and every `render()` call after
+ * construction reuses the same validated, frozen internal copy rather than
+ * re-checking anything.
+ *
+ * Throws (see `resolveVocabulary`/`resolveEntry` above) on: an entry whose
+ * `noun` is missing, not a string, or empty/whitespace after trim; any
+ * `adjectives` element that is not a string or is empty/whitespace after
+ * trim; an entry object carrying any key other than `noun`/`adjectives`
+ * (named in the error); and an empty vocabulary.
+ */
+export function createStateRenderer(params) {
+    const vocabulary = resolveVocabulary(params.vocabulary);
+    return {
+        render(renderParams) {
+            return renderState(vocabulary, renderParams);
+        },
+    };
+}

package/dist/timeline/replay.d.ts

@@ -0,0 +1,86 @@
+import { type T } from "./t.js";
+import type { EntityKind } from "./kinds.js";
+/**
+ * One fact as it read at the replayed `t`. `validFromT` is carried because
+ * design §5.2c's one hop of causality needs the moment a fact opened --
+ * nothing more than that is in scope here. In particular there is no
+ * `validToT`: at the replayed instant the fact is simply open, and whether
+ * or when it later closes is not a property of *this* snapshot.
+ */
+export interface ReplayedFact {
+    value: string;
+    validFromT: T;
+}
+/**
+ * One entity as it read at the replayed `t`, with every fact that was valid
+ * then. `facts` is keyed by `key` because at most one fact per key can be
+ * valid at a single `t` -- interval versioning (schema.ts) guarantees that
+ * for well-formed data, and the query below is written so a duplicate key
+ * (malformed data) resolves deterministically rather than by map-insertion
+ * order.
+ */
+export interface ReplayedEntity {
+    id: string;
+    kind: EntityKind;
+    name: string | null;
+    createdAtT: T;
+    facts: Record<string, ReplayedFact>;
+}
+/** A full world snapshot: every entity alive at `t`, with every fact valid at `t`. */
+export interface Snapshot {
+    gameId: string;
+    t: T;
+    entities: ReplayedEntity[];
+}
+/**
+ * `replay(t)` -- design §5.1's "whole feature": the state of one game's
+ * world at any point in its recorded history, not only at "now".
+ *
+ * Half-open intervals, everywhere and identically (design §5.1, and the
+ * architecture note's flagged likeliest bug):
+ *
+ *   alive at t: created_at_t <= t AND (destroyed_at_t IS NULL OR destroyed_at_t > t)
+ *   valid at t: valid_from_t <= t AND (valid_to_t   IS NULL OR valid_to_t   > t)
+ *
+ * A fact valid [a, b) is present at a and gone at b -- b itself belongs to
+ * whatever superseded it, never to both. A zero-width interval (valid_from_t
+ * == valid_to_t, which two writes at one declared t produce) is therefore
+ * invisible at every t: it opens and closes at the same instant, so the
+ * "> t" half of its own close condition is never satisfied at the t it
+ * would need to be visible at.
+ *
+ * Exactly two queries, never one per entity -- this runs over a whole
+ * world. The first finds who was alive; the second finds what was true of
+ * them, via a JOIN back to `entities` rather than a per-entity-id `IN (...)`
+ * list: this snapshot is meant to run over an entire world, and binding one
+ * parameter per entity would both hit SQLite's bound-variable limit on a
+ * large one and make every distinct entity count its own SQL text, which
+ * defeats better-sqlite3's prepared-statement cache. Fixed SQL, two binds
+ * of `t`, regardless of how many entities exist.
+ *
+ * DECISION(#18): replay() applies no visibility filtering, by decision rather than omission.
+ *
+ * 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
+ * deferred until a real caller makes the requirement concrete, because the
+ * expensive half of such a feature is the principal model, and inventing a
+ * principal against an imagined client is precisely what design §13 forbids.
+ *
+ * Worth stating out loud here rather than leaving to be inferred, because
+ * the predecessor's unenforced version of the same decision is legible
+ * today for exactly one reason -- `get_secret`'s own description says "DM
+ * view - shows all info" -- and a reader who finds an unfiltered query with
+ * no such sentence cannot tell a decision from a hole.
+ *
+ * A later filter is additive and needs nothing reserved for it now: it is
+ * one predicate, added here once, because this function is the single place
+ * every reader of "what was true at `t`" goes through. Do NOT add a
+ * nullable visibility column to `facts` in anticipation -- an unpopulated
+ * one reads equally well as "visible to everyone" and "visible to no one",
+ * and both readings survive review.
+ */
+export declare function replay(params: {
+    gameId: string;
+    t: T;
+}): Snapshot;

package/dist/timeline/replay.js

@@ -0,0 +1,126 @@
+import { getDatabase } from "../db/connection.js";
+import { assertT } from "./t.js";
+/**
+ * The "alive at t" half of both queries below, as one shared string.
+ *
+ * This has to be a single constant, not two hand-matched copies, because
+ * the whole point of replay is that "who was alive" and "what was true of
+ * them" describe the same instant. Two copies would compile and pass review
+ * right up until someone edited one -- silently reintroducing entities whose
+ * facts vanished, or facts belonging to nobody the snapshot admits exists.
+ * Always used against an `entities` row aliased `e` (see both queries).
+ */
+const ALIVE_AT_T = "e.created_at_t <= ? AND (e.destroyed_at_t IS NULL OR e.destroyed_at_t > ?)";
+/**
+ * `replay(t)` -- design §5.1's "whole feature": the state of one game's
+ * world at any point in its recorded history, not only at "now".
+ *
+ * Half-open intervals, everywhere and identically (design §5.1, and the
+ * architecture note's flagged likeliest bug):
+ *
+ *   alive at t: created_at_t <= t AND (destroyed_at_t IS NULL OR destroyed_at_t > t)
+ *   valid at t: valid_from_t <= t AND (valid_to_t   IS NULL OR valid_to_t   > t)
+ *
+ * A fact valid [a, b) is present at a and gone at b -- b itself belongs to
+ * whatever superseded it, never to both. A zero-width interval (valid_from_t
+ * == valid_to_t, which two writes at one declared t produce) is therefore
+ * invisible at every t: it opens and closes at the same instant, so the
+ * "> t" half of its own close condition is never satisfied at the t it
+ * would need to be visible at.
+ *
+ * Exactly two queries, never one per entity -- this runs over a whole
+ * world. The first finds who was alive; the second finds what was true of
+ * them, via a JOIN back to `entities` rather than a per-entity-id `IN (...)`
+ * list: this snapshot is meant to run over an entire world, and binding one
+ * parameter per entity would both hit SQLite's bound-variable limit on a
+ * large one and make every distinct entity count its own SQL text, which
+ * defeats better-sqlite3's prepared-statement cache. Fixed SQL, two binds
+ * of `t`, regardless of how many entities exist.
+ *
+ * DECISION(#18): replay() applies no visibility filtering, by decision rather than omission.
+ *
+ * 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
+ * deferred until a real caller makes the requirement concrete, because the
+ * expensive half of such a feature is the principal model, and inventing a
+ * principal against an imagined client is precisely what design §13 forbids.
+ *
+ * Worth stating out loud here rather than leaving to be inferred, because
+ * the predecessor's unenforced version of the same decision is legible
+ * today for exactly one reason -- `get_secret`'s own description says "DM
+ * view - shows all info" -- and a reader who finds an unfiltered query with
+ * no such sentence cannot tell a decision from a hole.
+ *
+ * A later filter is additive and needs nothing reserved for it now: it is
+ * one predicate, added here once, because this function is the single place
+ * every reader of "what was true at `t`" goes through. Do NOT add a
+ * nullable visibility column to `facts` in anticipation -- an unpopulated
+ * one reads equally well as "visible to everyone" and "visible to no one",
+ * and both readings survive review.
+ */
+export function replay(params) {
+    const { gameId, t } = params;
+    // A Date, a string, NaN or +-Infinity gets refused here, loudly, before
+    // it can silently compare unequal to every row and produce a confidently
+    // wrong empty snapshot.
+    assertT(t);
+    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
+    // tiebreaker for entities created at the same t, so the order never
+    // depends on SQLite's unspecified tie behavior).
+    const entityRows = db
+        .prepare(`SELECT e.id, e.kind, e.name, e.created_at_t
+       FROM entities e
+       WHERE e.game_id = ?
+         AND ${ALIVE_AT_T}
+       ORDER BY e.created_at_t, e.id`)
+        .all(gameId, t, t);
+    const entities = entityRows.map((row) => ({
+        id: row.id,
+        kind: row.kind,
+        name: row.name,
+        createdAtT: row.created_at_t,
+        facts: {},
+    }));
+    // Nothing alive means nothing that could own a fact. Not load-bearing for
+    // correctness the way it was before the JOIN -- query 2 below is valid
+    // SQL and would themselves return zero rows -- but it is still a genuine
+    // short-circuit: an empty game skips a JOIN entirely rather than running
+    // it to find nothing.
+    if (entities.length === 0) {
+        return { gameId, t, entities };
+    }
+    const byId = new Map(entities.map((entity) => [entity.id, entity]));
+    // Query 2 of 2: every fact valid at t, joined back to `entities` so
+    // "valid" is scoped to exactly the entities `ALIVE_AT_T` says were alive
+    // -- the same predicate, not a hand-matched copy of it. Ordered by
+    // valid_from_t so that if malformed data ever puts two facts for the same
+    // key in the visible window at once -- which correct writers never
+    // produce -- the one opened later (the one that superseded the other) is
+    // the one left standing, rather than whichever row SQLite happened to
+    // return first.
+    const factRows = db
+        .prepare(`SELECT f.entity_id, f.key, f.value, f.valid_from_t
+       FROM facts f
+       JOIN entities e ON e.id = f.entity_id
+       WHERE e.game_id = ?
+         AND ${ALIVE_AT_T}
+         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);
+    for (const factRow of factRows) {
+        const entity = byId.get(factRow.entity_id);
+        // Cannot happen: every fact row came from a JOIN against entities e
+        // filtered by the same game_id and ALIVE_AT_T as query 1, so its
+        // entity_id is always a key already in byId. Guarded anyway rather than
+        // asserted, because a snapshot query has no business throwing over its
+        // own bookkeeping.
+        if (!entity)
+            continue;
+        entity.facts[factRow.key] = { value: factRow.value, validFromT: factRow.valid_from_t };
+    }
+    return { gameId, t, entities };
+}