run-dmcp 0.1.0 → 0.3.0

package/dist/schemas/index.d.ts

@@ -292,22 +292,22 @@ export declare const generatedImageSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    timestamp: string;
     tool: string;
     prompt: string;
+    timestamp: string;
     url?: string | undefined;
     base64?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
     seed?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
 }, {
     id: string;
-    timestamp: string;
     tool: string;
     prompt: string;
+    timestamp: string;
     url?: string | undefined;
     base64?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
     seed?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
 }>;
 export declare const imageGenSchema: z.ZodObject<{
     subject: z.ZodObject<{
@@ -652,22 +652,22 @@ export declare const imageGenSchema: z.ZodObject<{
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         id: string;
-        timestamp: string;
         tool: string;
         prompt: string;
+        timestamp: string;
         url?: string | undefined;
         base64?: string | undefined;
-        metadata?: Record<string, unknown> | undefined;
         seed?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }, {
         id: string;
-        timestamp: string;
         tool: string;
         prompt: string;
+        timestamp: string;
         url?: string | undefined;
         base64?: string | undefined;
-        metadata?: Record<string, unknown> | undefined;
         seed?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }>, "many">>;
     consistency: z.ZodOptional<z.ZodObject<{
         characterRef: z.ZodOptional<z.ZodString>;
@@ -773,13 +773,13 @@ export declare const imageGenSchema: z.ZodObject<{
     } | undefined;
     generations?: {
         id: string;
-        timestamp: string;
         tool: string;
         prompt: string;
+        timestamp: string;
         url?: string | undefined;
         base64?: string | undefined;
-        metadata?: Record<string, unknown> | undefined;
         seed?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }[] | undefined;
 }, {
     style: {
@@ -869,13 +869,13 @@ export declare const imageGenSchema: z.ZodObject<{
     } | undefined;
     generations?: {
         id: string;
-        timestamp: string;
         tool: string;
         prompt: string;
+        timestamp: string;
         url?: string | undefined;
         base64?: string | undefined;
-        metadata?: Record<string, unknown> | undefined;
         seed?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }[] | undefined;
 }>;
 export declare const voiceSchema: z.ZodObject<{

package/dist/timeline/adjudication.d.ts

@@ -0,0 +1,150 @@
+import type Database from "better-sqlite3";
+/**
+ * The adjudication window (design §5.2a, §5.3; issue #13): an ephemeral
+ * marker that an adjudicating call -- issue #10's resolver, not built here
+ * -- is currently in progress. `resolve_only` (the fourth member of the
+ * constraint family, `src/types/index.ts`) means "every direct write to
+ * this fact key is refused"; this module is what "direct" is measured
+ * against. A write made while this window is open is the one write that is
+ * NOT direct -- it arrived through the adjudicating call that opened it.
+ *
+ * ONE SOURCE OF TRUTH, READ IN TWO PLACES. `adjudicationOpen()` below is
+ * called from the JS choke point (`assertConstraintsAllow`,
+ * src/timeline/constrained.ts) and the exact same table is read by
+ * `timeline_facts_resolve_only` (the `BEFORE INSERT ON facts` trigger,
+ * src/db/schema.ts) via `NOT EXISTS (SELECT 1 FROM
+ * timeline_adjudications_open)`. Two independent checks that happened to
+ * agree today would be two representations of one fact waiting to drift --
+ * exactly the "two write paths for one idea" shape root CLAUDE.md warns
+ * about and hard rule 7 exists to prevent for constrained writes generally.
+ * There is exactly one row of truth: this table. Neither reader owns a
+ * second copy of "is a window open" to keep in sync with the other.
+ *
+ * EMPTY AT REST. A database with no adjudicating call ever in flight has
+ * zero rows here, forever -- this is not a log and not a history; nothing
+ * here is meant to be read back after the window that wrote it closes. It
+ * is deliberately NOT a `PROJECTED_TABLES` entry (no entity/fact is ever
+ * derived from it -- an adjudication window is not part of the game's
+ * timeline, it is a fact about how a write reached the timeline), NOT
+ * frozen the way `resource_history`/`relationship_history` are (those hold
+ * rows nothing should ever add to again; this table's whole job is to gain
+ * and lose rows constantly), and NEVER exported as a query -- there is no
+ * `listOpenAdjudications()` beside `adjudicationOpen()` below, because
+ * nothing outside this module and its trigger counterpart has legitimate
+ * business asking anything about it other than the one boolean.
+ *
+ * SINGLE CONNECTION, NO RACE. better-sqlite3 is synchronous and this
+ * project holds exactly one connection per process (`getDatabase()`,
+ * src/db/connection.ts) -- there is no `await` between the INSERT that
+ * opens a window and the DELETE that closes it for two different callers'
+ * windows to interleave across, and no second connection that could read a
+ * half-open state. A future multi-process deployment would need to revisit
+ * this; nothing here assumes it.
+ *
+ * `withAdjudicationOpen` IS INTENDED TO BE CALLED FROM INSIDE
+ * `withTransaction()` (src/db/connection.ts) -- the resolver (issue #10,
+ * built separately) is expected to nest it as
+ * `withTransaction(() => withAdjudicationOpen(gameId, () => { ...writes...;
+ * ...event insert... }))`, so the marker row this module inserts commits or
+ * rolls back atomically WITH the writes it authorizes, exactly like every
+ * other constrained write's fact/event pair (see `applyLiveWrite`,
+ * constrained.ts). Getting that order backwards -- opening the window
+ * outside any transaction -- is exactly the crash scenario
+ * `initializeAdjudicationSchema`'s startup cleanup below exists to recover
+ * from; this module cannot enforce the nesting order on a caller, so it
+ * says so here instead.
+ *
+ * IMPORT DIRECTION IS LOAD-BEARING, same rule as constrained.ts's own doc
+ * comment states for itself: this file imports nothing from `src/tools/`.
+ * It stays a `src/timeline/` leaf -- the only thing it reaches for outside
+ * this directory is `getDatabase()` (src/db/connection.ts), exactly like
+ * constrained.ts and registry.ts already do.
+ */
+/**
+ * Creates `timeline_adjudications_open` if it doesn't already exist, and
+ * unconditionally clears every row it holds. Called from
+ * `src/db/schema.ts`'s `initializeSchema()`, BEFORE
+ * `timeline_facts_resolve_only` (the trigger that reads this table) is
+ * created -- a `WHEN` clause referencing a table that doesn't exist yet
+ * would fail at `CREATE TRIGGER` time, not silently defer.
+ *
+ * THE STARTUP DELETE IS NOT HOUSEKEEPING -- it closes a fail-OPEN hole that
+ * would otherwise be the worst failure mode a guard can have. `withAdjudicationOpen`'s
+ * `finally` closes the window on a throw, but nothing in JS runs if the
+ * PROCESS itself dies between the INSERT and the DELETE (SIGKILL, OOM, the
+ * host losing power) -- and better-sqlite3's default journal mode commits
+ * each statement as it runs, so a row that made it to disk stays there.
+ * Without this cleanup, that one surviving row would make `adjudicationOpen()`
+ * return `true` FOREVER, on every future startup, for the life of the
+ * database -- which does not refuse writes (the failure a reviewer would
+ * notice) but PERMITS every one of them: `timeline_facts_resolve_only`'s
+ * `NOT EXISTS (SELECT 1 FROM timeline_adjudications_open)` would never be
+ * satisfied again, silently turning `resolve_only` into a no-op. A guard
+ * that quietly stops guarding is worse than one that is visibly broken.
+ *
+ * WHY UNCONDITIONAL DELETE IS SAFE: startup and "an adjudicating call is in
+ * flight" are mutually exclusive by construction. `initializeSchema()` runs
+ * once, synchronously, before this process serves anything -- there is no
+ * caller that could be mid-`withAdjudicationOpen` while it executes, because
+ * the only thing that could be running one is THIS process, and this
+ * process is, at this exact moment, inside its own startup path, not inside
+ * a request. So any row found here was never going to be closed by the code
+ * that opened it -- that code is gone -- and the only correct reading of a
+ * leftover row is "not open, and never going to become open on its own."
+ * Clearing it fails CLOSED (enforcement resumes) rather than leaving it to
+ * fail OPEN (enforcement silently stays off), which is the direction every
+ * ambiguous case in this module resolves toward.
+ *
+ * No index: this table is expected to hold at most a small handful of rows
+ * at any instant (one per adjudicating call currently in flight, plus one
+ * per level of re-entrant nesting) and every query against it is either "do
+ * any rows exist" or "delete this one row by its primary key" -- neither
+ * benefits from one.
+ */
+export declare function initializeAdjudicationSchema(db: Database.Database): void;
+/**
+ * Is ANY adjudication window currently open? Not scoped to a game --
+ * `timeline_facts_resolve_only`'s own `WHEN` clause (src/db/schema.ts) isn't
+ * either, and the whole point of "one source of truth read in two places"
+ * above is that this function and that trigger can never answer the
+ * question differently. A resolver call for game A opening a window does,
+ * as a consequence, also permit a resolve_only write for game B for the
+ * duration -- an acceptable widening given there is exactly one process,
+ * exactly one adjudicating call site (issue #10), and no concurrent-game
+ * resolution happening on this connection at once. Narrowing this to
+ * `game_id` later is possible without changing the trigger's shape (add
+ * `AND game_id = NEW.<something-that-names-the-game>` to both sides at
+ * once) but is not needed for the window mechanism itself to be correct
+ * today, and inventing that requirement ahead of an actual caller needing
+ * it would be exactly the "nothing enters the core against an imagined
+ * client" mistake root CLAUDE.md's hard rule 1 warns against.
+ */
+export declare function adjudicationOpen(): boolean;
+/**
+ * Runs `fn` with the adjudication window open, and guarantees the window
+ * this call opened is closed again before returning or throwing -- a
+ * throwing adjudication must never leave `resolve_only` permanently
+ * unenforceable for the rest of the process's life.
+ *
+ * RE-ENTRANCY: each call inserts its OWN row (a fresh uuid, never reused)
+ * and its `finally` deletes only that row, by id -- never every row in the
+ * table. Nesting therefore composes correctly with no special-casing: if an
+ * adjudicating call invokes another adjudicating call while its own window
+ * is open (or, for that matter, if two unrelated adjudications happen to be
+ * in flight on this one synchronous connection at the same instant, which
+ * given the single-connection note above means one nested inside the
+ * other), the inner call's own finally block removes only the inner row.
+ * `adjudicationOpen()` asks "does at least one row exist", so the outer
+ * window is still reported open for as long as the outer row remains --
+ * whether or not the inner call already finished, and whether or not the
+ * inner call threw. A DELETE keyed on `WHERE id = ?` (this call's own row),
+ * rather than `DELETE FROM timeline_adjudications_open` (every row), is
+ * what makes an inner close unable to ever close an outer window.
+ *
+ * `gameId` is recorded on the row for the same reason `opened_at` is --
+ * legibility for anyone inspecting the table mid-flight (e.g. while
+ * debugging a wedged process) -- not because any reader queries by it; see
+ * `adjudicationOpen()`'s doc comment above for why the read side is
+ * deliberately unscoped.
+ */
+export declare function withAdjudicationOpen<R>(gameId: string, fn: () => R): R;

package/dist/timeline/adjudication.js

@@ -0,0 +1,174 @@
+import { v4 as uuidv4 } from "uuid";
+import { getDatabase } from "../db/connection.js";
+/**
+ * The adjudication window (design §5.2a, §5.3; issue #13): an ephemeral
+ * marker that an adjudicating call -- issue #10's resolver, not built here
+ * -- is currently in progress. `resolve_only` (the fourth member of the
+ * constraint family, `src/types/index.ts`) means "every direct write to
+ * this fact key is refused"; this module is what "direct" is measured
+ * against. A write made while this window is open is the one write that is
+ * NOT direct -- it arrived through the adjudicating call that opened it.
+ *
+ * ONE SOURCE OF TRUTH, READ IN TWO PLACES. `adjudicationOpen()` below is
+ * called from the JS choke point (`assertConstraintsAllow`,
+ * src/timeline/constrained.ts) and the exact same table is read by
+ * `timeline_facts_resolve_only` (the `BEFORE INSERT ON facts` trigger,
+ * src/db/schema.ts) via `NOT EXISTS (SELECT 1 FROM
+ * timeline_adjudications_open)`. Two independent checks that happened to
+ * agree today would be two representations of one fact waiting to drift --
+ * exactly the "two write paths for one idea" shape root CLAUDE.md warns
+ * about and hard rule 7 exists to prevent for constrained writes generally.
+ * There is exactly one row of truth: this table. Neither reader owns a
+ * second copy of "is a window open" to keep in sync with the other.
+ *
+ * EMPTY AT REST. A database with no adjudicating call ever in flight has
+ * zero rows here, forever -- this is not a log and not a history; nothing
+ * here is meant to be read back after the window that wrote it closes. It
+ * is deliberately NOT a `PROJECTED_TABLES` entry (no entity/fact is ever
+ * derived from it -- an adjudication window is not part of the game's
+ * timeline, it is a fact about how a write reached the timeline), NOT
+ * frozen the way `resource_history`/`relationship_history` are (those hold
+ * rows nothing should ever add to again; this table's whole job is to gain
+ * and lose rows constantly), and NEVER exported as a query -- there is no
+ * `listOpenAdjudications()` beside `adjudicationOpen()` below, because
+ * nothing outside this module and its trigger counterpart has legitimate
+ * business asking anything about it other than the one boolean.
+ *
+ * SINGLE CONNECTION, NO RACE. better-sqlite3 is synchronous and this
+ * project holds exactly one connection per process (`getDatabase()`,
+ * src/db/connection.ts) -- there is no `await` between the INSERT that
+ * opens a window and the DELETE that closes it for two different callers'
+ * windows to interleave across, and no second connection that could read a
+ * half-open state. A future multi-process deployment would need to revisit
+ * this; nothing here assumes it.
+ *
+ * `withAdjudicationOpen` IS INTENDED TO BE CALLED FROM INSIDE
+ * `withTransaction()` (src/db/connection.ts) -- the resolver (issue #10,
+ * built separately) is expected to nest it as
+ * `withTransaction(() => withAdjudicationOpen(gameId, () => { ...writes...;
+ * ...event insert... }))`, so the marker row this module inserts commits or
+ * rolls back atomically WITH the writes it authorizes, exactly like every
+ * other constrained write's fact/event pair (see `applyLiveWrite`,
+ * constrained.ts). Getting that order backwards -- opening the window
+ * outside any transaction -- is exactly the crash scenario
+ * `initializeAdjudicationSchema`'s startup cleanup below exists to recover
+ * from; this module cannot enforce the nesting order on a caller, so it
+ * says so here instead.
+ *
+ * IMPORT DIRECTION IS LOAD-BEARING, same rule as constrained.ts's own doc
+ * comment states for itself: this file imports nothing from `src/tools/`.
+ * It stays a `src/timeline/` leaf -- the only thing it reaches for outside
+ * this directory is `getDatabase()` (src/db/connection.ts), exactly like
+ * constrained.ts and registry.ts already do.
+ */
+/**
+ * Creates `timeline_adjudications_open` if it doesn't already exist, and
+ * unconditionally clears every row it holds. Called from
+ * `src/db/schema.ts`'s `initializeSchema()`, BEFORE
+ * `timeline_facts_resolve_only` (the trigger that reads this table) is
+ * created -- a `WHEN` clause referencing a table that doesn't exist yet
+ * would fail at `CREATE TRIGGER` time, not silently defer.
+ *
+ * THE STARTUP DELETE IS NOT HOUSEKEEPING -- it closes a fail-OPEN hole that
+ * would otherwise be the worst failure mode a guard can have. `withAdjudicationOpen`'s
+ * `finally` closes the window on a throw, but nothing in JS runs if the
+ * PROCESS itself dies between the INSERT and the DELETE (SIGKILL, OOM, the
+ * host losing power) -- and better-sqlite3's default journal mode commits
+ * each statement as it runs, so a row that made it to disk stays there.
+ * Without this cleanup, that one surviving row would make `adjudicationOpen()`
+ * return `true` FOREVER, on every future startup, for the life of the
+ * database -- which does not refuse writes (the failure a reviewer would
+ * notice) but PERMITS every one of them: `timeline_facts_resolve_only`'s
+ * `NOT EXISTS (SELECT 1 FROM timeline_adjudications_open)` would never be
+ * satisfied again, silently turning `resolve_only` into a no-op. A guard
+ * that quietly stops guarding is worse than one that is visibly broken.
+ *
+ * WHY UNCONDITIONAL DELETE IS SAFE: startup and "an adjudicating call is in
+ * flight" are mutually exclusive by construction. `initializeSchema()` runs
+ * once, synchronously, before this process serves anything -- there is no
+ * caller that could be mid-`withAdjudicationOpen` while it executes, because
+ * the only thing that could be running one is THIS process, and this
+ * process is, at this exact moment, inside its own startup path, not inside
+ * a request. So any row found here was never going to be closed by the code
+ * that opened it -- that code is gone -- and the only correct reading of a
+ * leftover row is "not open, and never going to become open on its own."
+ * Clearing it fails CLOSED (enforcement resumes) rather than leaving it to
+ * fail OPEN (enforcement silently stays off), which is the direction every
+ * ambiguous case in this module resolves toward.
+ *
+ * No index: this table is expected to hold at most a small handful of rows
+ * at any instant (one per adjudicating call currently in flight, plus one
+ * per level of re-entrant nesting) and every query against it is either "do
+ * any rows exist" or "delete this one row by its primary key" -- neither
+ * benefits from one.
+ */
+export function initializeAdjudicationSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS timeline_adjudications_open (
+      id TEXT PRIMARY KEY,
+      game_id TEXT NOT NULL,
+      opened_at TEXT NOT NULL
+    )
+  `);
+    db.exec(`DELETE FROM timeline_adjudications_open`);
+}
+/**
+ * Is ANY adjudication window currently open? Not scoped to a game --
+ * `timeline_facts_resolve_only`'s own `WHEN` clause (src/db/schema.ts) isn't
+ * either, and the whole point of "one source of truth read in two places"
+ * above is that this function and that trigger can never answer the
+ * question differently. A resolver call for game A opening a window does,
+ * as a consequence, also permit a resolve_only write for game B for the
+ * duration -- an acceptable widening given there is exactly one process,
+ * exactly one adjudicating call site (issue #10), and no concurrent-game
+ * resolution happening on this connection at once. Narrowing this to
+ * `game_id` later is possible without changing the trigger's shape (add
+ * `AND game_id = NEW.<something-that-names-the-game>` to both sides at
+ * once) but is not needed for the window mechanism itself to be correct
+ * today, and inventing that requirement ahead of an actual caller needing
+ * it would be exactly the "nothing enters the core against an imagined
+ * client" mistake root CLAUDE.md's hard rule 1 warns against.
+ */
+export function adjudicationOpen() {
+    const db = getDatabase();
+    const row = db.prepare(`SELECT 1 FROM timeline_adjudications_open LIMIT 1`).get();
+    return row !== undefined;
+}
+/**
+ * Runs `fn` with the adjudication window open, and guarantees the window
+ * this call opened is closed again before returning or throwing -- a
+ * throwing adjudication must never leave `resolve_only` permanently
+ * unenforceable for the rest of the process's life.
+ *
+ * RE-ENTRANCY: each call inserts its OWN row (a fresh uuid, never reused)
+ * and its `finally` deletes only that row, by id -- never every row in the
+ * table. Nesting therefore composes correctly with no special-casing: if an
+ * adjudicating call invokes another adjudicating call while its own window
+ * is open (or, for that matter, if two unrelated adjudications happen to be
+ * in flight on this one synchronous connection at the same instant, which
+ * given the single-connection note above means one nested inside the
+ * other), the inner call's own finally block removes only the inner row.
+ * `adjudicationOpen()` asks "does at least one row exist", so the outer
+ * window is still reported open for as long as the outer row remains --
+ * whether or not the inner call already finished, and whether or not the
+ * inner call threw. A DELETE keyed on `WHERE id = ?` (this call's own row),
+ * rather than `DELETE FROM timeline_adjudications_open` (every row), is
+ * what makes an inner close unable to ever close an outer window.
+ *
+ * `gameId` is recorded on the row for the same reason `opened_at` is --
+ * legibility for anyone inspecting the table mid-flight (e.g. while
+ * debugging a wedged process) -- not because any reader queries by it; see
+ * `adjudicationOpen()`'s doc comment above for why the read side is
+ * deliberately unscoped.
+ */
+export function withAdjudicationOpen(gameId, fn) {
+    const db = getDatabase();
+    const id = uuidv4();
+    db.prepare(`INSERT INTO timeline_adjudications_open (id, game_id, opened_at) VALUES (?, ?, ?)`).run(id, gameId, new Date().toISOString());
+    try {
+        return fn();
+    }
+    finally {
+        db.prepare(`DELETE FROM timeline_adjudications_open WHERE id = ?`).run(id);
+    }
+}

package/dist/timeline/changes.d.ts

@@ -0,0 +1,108 @@
+import { type T } from "./t.js";
+/**
+ * One event as it landed inside the window. `causes` is the raw JSON string
+ * as stored (design §5.2c's one hop of provenance) -- it is returned
+ * untouched, never parsed or interpreted here (hard rule 4: nothing in this
+ * codebase derives meaning by reading generated text).
+ */
+export interface EventChange {
+    kind: "event";
+    t: T;
+    eventId: string;
+    eventKind: string;
+    description: string | null;
+    causes: string | null;
+}
+/**
+ * One TRANSITION of one fact's interval, not one row per fact. A fact whose
+ * interval opens AND closes inside the window produces two `FactChange`
+ * rows -- an `"opened"` at `validFromT` and a `"closed"` at `validToT` --
+ * because a single row cannot carry two different `t` values to sort on. A
+ * tri-state "both" field was considered and rejected for exactly that
+ * reason: two rows sort correctly by `t`, and a caller that wants "did this
+ * fact both open and close in my window" recovers it for free by grouping
+ * the returned rows on `factId`.
+ *
+ * `endpoint` says which end of the fact's own interval this row is -- a
+ * mechanical property of the row against the window predicate, not a
+ * judgement about the fact's meaning. This is deliberately the only
+ * "extra" piece of information this module hands back beyond the raw
+ * columns (see the module doc comment on why nothing else is).
+ */
+export interface FactChange {
+    kind: "fact";
+    t: T;
+    factId: string;
+    entityId: string;
+    factKey: string;
+    value: string;
+    /** Which endpoint of this fact's interval landed in the window. */
+    endpoint: "opened" | "closed";
+    validFromT: T;
+    validToT: T | null;
+}
+export type Change = EventChange | FactChange;
+/**
+ * design §5.5: "the engine provides the query; the client declares the
+ * policy." `changes` is rows, nothing more -- no `isClean`, no severity, no
+ * contiguity flag, no count that implies a threshold. A continuous-take
+ * renderer reads a non-empty `changes` as a defect to fail; a turn-based
+ * consumer reads the same rows to *build* a summary of what happened since
+ * last look. Baking either reading into this type would hand the second
+ * caller the first caller's policy (root CLAUDE.md hard rule 2). If a
+ * future contributor is tempted to add `spansEntireInterval` or
+ * `durationCovered` here: don't -- that is a verdict wearing a shape.
+ */
+export interface ChangeSet {
+    gameId: string;
+    t0: T;
+    t1: T;
+    changes: Change[];
+}
+/**
+ * `changesWithin(t0, t1)` -- design §5.5's "because units have duration":
+ * every event and fact-interval transition recorded in one game's history
+ * during the half-open window `[t0, t1)`.
+ *
+ * Half-open, matching `replay.ts`'s intervals exactly and for the same
+ * reason (design §5.1): `t0` is in, `t1` is not. An event at exactly `t1`,
+ * or a fact endpoint landing exactly at `t1`, belongs to whatever window
+ * starts there, never to this one.
+ *
+ * `t1 === t0` is a legal empty window (returns zero rows, refused nowhere).
+ * `t1 < t0` is refused loudly, naming both values, before either query
+ * runs -- silently returning zero rows for a caller's off-by-one would be
+ * far more expensive to track down than a thrown error naming the mistake.
+ *
+ * Exactly two queries, never one per entity -- same reasoning as
+ * `replay()`: this runs over a whole game's history, and one prepared
+ * statement per entity would both hit SQLite's bound-variable limit on a
+ * large game and defeat better-sqlite3's prepared-statement cache. Facts
+ * are scoped to the game via a JOIN to `entities` on `entity_id` (there is
+ * no FK-enforced game_id on `facts` itself, and `facts.entity_id` is a real
+ * foreign key with referential integrity -- see the task briefing on why
+ * that JOIN, not a raw string match, is the identity axis to scope on).
+ * Events carry `game_id` directly and need no join.
+ *
+ * Deliberately NOT filtered by entity aliveness. `replay(t)` answers "what
+ * was true at an instant" and needs "alive at t" to make that meaningful;
+ * this answers "what transitions were recorded in a window", and a
+ * transition belonging to an entity that was later destroyed is still a
+ * transition that was recorded -- destroying the entity afterward doesn't
+ * retroactively un-happen it. Filtering these rows by aliveness would be
+ * exactly the kind of policy this module isn't allowed to have an opinion
+ * on (see `ChangeSet`'s doc comment).
+ *
+ * DECISION(#18): changesWithin() returns every transition, whoever could observe it.
+ *
+ * Omniscient for the same reason and by the same decision as `replay()` --
+ * see its doc comment for the argument. Every transition in the window is
+ * returned regardless of which principal could have observed it, and a
+ * later per-principal filter arrives as one predicate on the two queries
+ * below (issue #18).
+ */
+export declare function changesWithin(params: {
+    gameId: string;
+    t0: T;
+    t1: T;
+}): ChangeSet;