run-dmcp 0.1.0 → 0.3.0

package/dist/timeline/changes.js

@@ -0,0 +1,169 @@
+import { getDatabase } from "../db/connection.js";
+import { assertT, compareT } from "./t.js";
+/**
+ * The deterministic total order every `changesWithin` result is sorted
+ * into: `t` ascending, then a tiebreaker chain that can never itself tie,
+ * so two rows can never come back in a different order across two runs of
+ * the same query (design §6's reproducibility depends on this for anyone
+ * freezing an artifact from these rows).
+ *
+ * Tiebreak chain, in order:
+ *   1. `t` (via `compareT`, the one comparator this codebase orders `t`
+ *      through).
+ *   2. `kind` -- "event" sorts before "fact"; fixed and arbitrary, but
+ *      fixed is all determinism requires.
+ *   3. The row's own id (`eventId` or `factId`) -- both are primary keys,
+ *      so this alone would already be unique EXCEPT for one case:
+ *   4. `endpoint` -- a zero-width fact interval (`validFromT === validToT`)
+ *      produces two rows sharing both `t` and `factId`; only `endpoint`
+ *      ("closed" < "opened") separates them.
+ */
+function compareChanges(a, b) {
+    const byT = compareT(a.t, b.t);
+    if (byT !== 0)
+        return byT;
+    if (a.kind !== b.kind) {
+        return a.kind < b.kind ? -1 : 1;
+    }
+    if (a.kind === "event" && b.kind === "event") {
+        return a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0;
+    }
+    // Both "fact" at this point (the `a.kind !== b.kind` branch above already
+    // returned otherwise), but TypeScript can't narrow a discriminated union
+    // through two independent variables -- assert what's already established.
+    const factA = a;
+    const factB = b;
+    if (factA.factId !== factB.factId) {
+        return factA.factId < factB.factId ? -1 : 1;
+    }
+    return factA.endpoint < factB.endpoint ? -1 : factA.endpoint > factB.endpoint ? 1 : 0;
+}
+/**
+ * `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 function changesWithin(params) {
+    const { gameId, t0, t1 } = params;
+    // A Date, a string, NaN or +-Infinity gets refused here, loudly, on
+    // either bound, before it can silently compare unequal to every row and
+    // produce a confidently wrong empty result.
+    assertT(t0);
+    assertT(t1);
+    // Through `compareT`, not a bare `<`, for the reason t.ts gives: it is the
+    // one comparator everything in the timeline that ORDERS `t` goes through,
+    // so a future axis can never introduce a second notion of "later" that
+    // this guard alone disagrees with. Same shape clock.ts uses for its own
+    // never-run-backwards refusals.
+    if (compareT(t1, t0) < 0) {
+        throw new Error(`timeline: changesWithin requires t1 >= t0, got t0=${t0}, t1=${t1}`);
+    }
+    const db = getDatabase();
+    const changes = [];
+    // Query 1 of 2: events at_t in [t0, t1), scoped directly by game_id.
+    const eventRows = db
+        .prepare(`SELECT id, at_t, kind, description, causes
+       FROM events
+       WHERE game_id = ?
+         AND at_t >= ?
+         AND at_t < ?`)
+        .all(gameId, t0, t1);
+    for (const row of eventRows) {
+        changes.push({
+            kind: "event",
+            t: row.at_t,
+            eventId: row.id,
+            eventKind: row.kind,
+            description: row.description,
+            causes: row.causes,
+        });
+    }
+    // Query 2 of 2: every fact whose valid_from_t OR valid_to_t landed in the
+    // window, joined back to entities so scoping is by game_id via the real
+    // FK-backed identity chain rather than a column on `facts` itself. Same
+    // half-open predicate as query 1, applied independently to each endpoint
+    // -- a fact can have one endpoint in the window and the other outside it
+    // (that's the "opened before t0, closes inside" / "opens inside, still
+    // open" cases below), so this is deliberately an OR over two half-open
+    // checks, not one range check over the whole interval.
+    const factRows = db
+        .prepare(`SELECT f.id, f.entity_id, f.key, f.value, f.valid_from_t, f.valid_to_t
+       FROM facts f
+       JOIN entities e ON e.id = f.entity_id
+       WHERE e.game_id = ?
+         AND (
+           (f.valid_from_t >= ? AND f.valid_from_t < ?)
+           OR (f.valid_to_t IS NOT NULL AND f.valid_to_t >= ? AND f.valid_to_t < ?)
+         )`)
+        .all(gameId, t0, t1, t0, t1);
+    for (const row of factRows) {
+        const opensInWindow = row.valid_from_t >= t0 && row.valid_from_t < t1;
+        const closesInWindow = row.valid_to_t !== null && row.valid_to_t >= t0 && row.valid_to_t < t1;
+        if (opensInWindow) {
+            changes.push({
+                kind: "fact",
+                t: row.valid_from_t,
+                factId: row.id,
+                entityId: row.entity_id,
+                factKey: row.key,
+                value: row.value,
+                endpoint: "opened",
+                validFromT: row.valid_from_t,
+                validToT: row.valid_to_t,
+            });
+        }
+        if (closesInWindow) {
+            changes.push({
+                kind: "fact",
+                // row.valid_to_t is not null here (closesInWindow already checked).
+                t: row.valid_to_t,
+                factId: row.id,
+                entityId: row.entity_id,
+                factKey: row.key,
+                value: row.value,
+                endpoint: "closed",
+                validFromT: row.valid_from_t,
+                validToT: row.valid_to_t,
+            });
+        }
+    }
+    changes.sort(compareChanges);
+    return { gameId, t0, t1, changes };
+}

package/dist/timeline/checkpoint.d.ts

@@ -0,0 +1,69 @@
+import type { EntityKind } from "./kinds.js";
+/**
+ * One row where the live tables and the replayed timeline disagree.
+ *
+ * This is a record, not a verdict -- hard rule 2 (design §5.5, §13): the
+ * engine reports what it found and the caller decides what it means. There
+ * is no `isClean`, no severity, no summary string, and `timelineDivergences`
+ * returning `[]` is itself the only "everything matched" this module ever
+ * says. The Phase 1 checkpoint (design §11, §13) is the caller that treats a
+ * non-empty result as a stop condition; that policy lives in the test, not
+ * here.
+ *
+ * - `missing-entity`: a live row exists with no entity of `kind` alive at
+ *   `now` for its id.
+ * - `missing-row`: an entity of `kind` is alive at `now` with no live row.
+ * - `value`: `key` (a column of `table`) disagrees between the live row and
+ *   the fact valid at `now` -- covers a value mismatch, a non-NULL column
+ *   with no fact, and a fact present where the column is NULL, all as the
+ *   same shape (see `timelineDivergences`'s doc comment for why one
+ *   comparison catches all three).
+ * - `duplicate-fact`: more than one fact is valid at `now` for the same
+ *   `(entityId, key)`. Checked directly against `facts`, never through
+ *   `replay()`'s `Record<string, ReplayedFact>` -- a duplicate would
+ *   collapse into that Record silently, so this is the one divergence a
+ *   checkpoint that only called `replay()` could never see.
+ */
+export interface Divergence {
+    reason: "missing-entity" | "missing-row" | "value" | "duplicate-fact";
+    table: string;
+    kind: EntityKind;
+    entityId: string;
+    key?: string;
+    live?: string | null;
+    replayed?: string | null;
+}
+/**
+ * Design §13's Phase 1 stop condition, made checkable: does `replay(now)`
+ * reproduce the live projected tables, exactly, for `gameId`?
+ *
+ * This calls `replay()` -- it does not re-derive "alive at t" or "valid at
+ * t" from `entities`/`facts` itself. Re-implementing those predicates here
+ * would make this a test of a second copy of the logic, not of the query
+ * issue #4 exists to check; the whole reason a checkpoint is worth having is
+ * that it exercises the same code path a real caller would. `liveColumns` is
+ * imported from `projection.ts` for the same reason -- one owner for the
+ * fact-key list, so this can never compare a different set of columns than
+ * the triggers actually project.
+ *
+ * `now` is read from `timeline_clock.current_t` via `currentStoryTime` --
+ * never a caller-supplied `t` -- because "current state" (design §11's
+ * checkpoint) means *this game's* current position on its own timeline, not
+ * an arbitrary point a test happened to pick.
+ *
+ * Every live column is compared as `CAST(... AS TEXT)`, produced by SQLite
+ * on both sides of every comparison (this side, and inside `replay()`'s own
+ * queries and the projection triggers that wrote the facts in the first
+ * place). Comparing in JS would invent divergences that are not there:
+ * `CAST(100.0 AS TEXT)` is `'100.0'` in SQLite, but better-sqlite3 hands the
+ * same REAL column to JS as the number `100` -- see timeline-architecture.md
+ * for the measured behaviour. A single strict-equality check between the
+ * live `CAST` string (or `null`) and the replayed fact's value (or `null`
+ * when no fact is open) is then enough to catch all three `value` shapes at
+ * once: a live NULL with an open fact, a non-NULL live column with no open
+ * fact, and two non-NULL values that simply disagree -- there is no reason
+ * to special-case any of them, because `null !== "x"` is already true for
+ * every combination that should diverge and false for every one that
+ * shouldn't.
+ */
+export declare function timelineDivergences(gameId: string): Divergence[];

package/dist/timeline/checkpoint.js

@@ -0,0 +1,131 @@
+import { getDatabase } from "../db/connection.js";
+import { currentStoryTime } from "./clock.js";
+import { replay } from "./replay.js";
+import { PROJECTED_TABLES, liveColumns } from "./projection.js";
+/**
+ * Design §13's Phase 1 stop condition, made checkable: does `replay(now)`
+ * reproduce the live projected tables, exactly, for `gameId`?
+ *
+ * This calls `replay()` -- it does not re-derive "alive at t" or "valid at
+ * t" from `entities`/`facts` itself. Re-implementing those predicates here
+ * would make this a test of a second copy of the logic, not of the query
+ * issue #4 exists to check; the whole reason a checkpoint is worth having is
+ * that it exercises the same code path a real caller would. `liveColumns` is
+ * imported from `projection.ts` for the same reason -- one owner for the
+ * fact-key list, so this can never compare a different set of columns than
+ * the triggers actually project.
+ *
+ * `now` is read from `timeline_clock.current_t` via `currentStoryTime` --
+ * never a caller-supplied `t` -- because "current state" (design §11's
+ * checkpoint) means *this game's* current position on its own timeline, not
+ * an arbitrary point a test happened to pick.
+ *
+ * Every live column is compared as `CAST(... AS TEXT)`, produced by SQLite
+ * on both sides of every comparison (this side, and inside `replay()`'s own
+ * queries and the projection triggers that wrote the facts in the first
+ * place). Comparing in JS would invent divergences that are not there:
+ * `CAST(100.0 AS TEXT)` is `'100.0'` in SQLite, but better-sqlite3 hands the
+ * same REAL column to JS as the number `100` -- see timeline-architecture.md
+ * for the measured behaviour. A single strict-equality check between the
+ * live `CAST` string (or `null`) and the replayed fact's value (or `null`
+ * when no fact is open) is then enough to catch all three `value` shapes at
+ * once: a live NULL with an open fact, a non-NULL live column with no open
+ * fact, and two non-NULL values that simply disagree -- there is no reason
+ * to special-case any of them, because `null !== "x"` is already true for
+ * every combination that should diverge and false for every one that
+ * shouldn't.
+ */
+export function timelineDivergences(gameId) {
+    const db = getDatabase();
+    // No clock row means nothing has ever been declared or written for this
+    // game -- there is no `now` to replay to, and (by construction: every
+    // projection trigger bootstraps a clock row on its game's first insert)
+    // no live row anywhere could exist for it either. Nothing to compare,
+    // nothing to diverge.
+    const clock = currentStoryTime(gameId);
+    if (!clock)
+        return [];
+    const now = clock.t;
+    const snapshot = replay({ gameId, t: now });
+    // Index the snapshot by (kind, id) once, rather than scanning the whole
+    // snapshot per projected table -- PROJECTED_TABLES has one row per kind,
+    // and this runs once per checkpoint call, not once per entity.
+    const aliveByKind = new Map();
+    for (const entity of snapshot.entities) {
+        let byId = aliveByKind.get(entity.kind);
+        if (!byId) {
+            byId = new Map();
+            aliveByKind.set(entity.kind, byId);
+        }
+        byId.set(entity.id, entity);
+    }
+    const divergences = [];
+    for (const row of PROJECTED_TABLES) {
+        const cols = liveColumns(db, row.table);
+        // Every column CAST(... AS TEXT) in the same SELECT that fetches the
+        // live row -- see this function's doc comment for why that CAST has to
+        // happen in SQL rather than after the row reaches JS.
+        const columnList = cols.map((col) => `CAST(${col} AS TEXT) AS "${col}"`).join(", ");
+        const liveRows = db
+            .prepare(`SELECT id, ${columnList} FROM ${row.table} WHERE ${row.gameIdColumn} = ?`)
+            .all(gameId);
+        const aliveOfKind = aliveByKind.get(row.kind) ?? new Map();
+        const liveIds = new Set();
+        for (const liveRow of liveRows) {
+            const id = liveRow.id;
+            liveIds.add(id);
+            const entity = aliveOfKind.get(id);
+            if (!entity) {
+                divergences.push({ reason: "missing-entity", table: row.table, kind: row.kind, entityId: id });
+                continue;
+            }
+            for (const col of cols) {
+                const liveValue = liveRow[col];
+                const fact = entity.facts[col];
+                const replayedValue = fact ? fact.value : null;
+                if (liveValue !== replayedValue) {
+                    divergences.push({
+                        reason: "value",
+                        table: row.table,
+                        kind: row.kind,
+                        entityId: id,
+                        key: col,
+                        live: liveValue,
+                        replayed: replayedValue,
+                    });
+                }
+            }
+        }
+        for (const id of aliveOfKind.keys()) {
+            if (!liveIds.has(id)) {
+                divergences.push({ reason: "missing-row", table: row.table, kind: row.kind, entityId: id });
+            }
+        }
+    }
+    // duplicate-fact: the one divergence replay() itself could never surface,
+    // because its Record<string, ReplayedFact> is keyed by `key` -- a second
+    // fact valid at `now` for the same (entity_id, key) would just overwrite
+    // the first in that Record rather than raise anything. Checked directly
+    // against `facts`, scoped to this game's own entities via the join.
+    const tableByKind = new Map(PROJECTED_TABLES.map((r) => [r.kind, r.table]));
+    const duplicateRows = db
+        .prepare(`SELECT f.entity_id AS entityId, f.key AS key, e.kind AS kind
+       FROM facts f
+       JOIN entities e ON e.id = f.entity_id
+       WHERE e.game_id = ?
+         AND f.valid_from_t <= ?
+         AND (f.valid_to_t IS NULL OR f.valid_to_t > ?)
+       GROUP BY f.entity_id, f.key
+       HAVING COUNT(*) > 1`)
+        .all(gameId, now, now);
+    for (const dup of duplicateRows) {
+        divergences.push({
+            reason: "duplicate-fact",
+            table: tableByKind.get(dup.kind) ?? dup.kind,
+            kind: dup.kind,
+            entityId: dup.entityId,
+            key: dup.key,
+        });
+    }
+    return divergences;
+}

package/dist/timeline/clock.d.ts

@@ -0,0 +1,89 @@
+import { type T, type TimeAxis } from "./t.js";
+/**
+ * One game's declared position on its own timeline: where `t` currently
+ * sits, and the axis it is measured on. What `currentStoryTime` /
+ * `declareTimeAxis` / `setStoryTime` all read and write, one row per game in
+ * `timeline_clock` (schema.ts).
+ */
+export interface StoryTime {
+    gameId: string;
+    t: T;
+    axis: TimeAxis;
+}
+/** Current position on a game's timeline, or null if nothing has ever been declared or written for it. */
+export declare function currentStoryTime(gameId: string): StoryTime | null;
+/**
+ * Declares (or re-declares) the axis a game's `t` moves along. This is the
+ * one place §14's property (hard rule 6) is enforced at runtime rather than
+ * merely documented by `TimeAxis`'s missing fourth variant (t.ts):
+ *
+ *   - No clock row yet: create one at `startAt ?? 0` on the requested axis.
+ *     This is the path a caller uses BEFORE creating anything for this game,
+ *     so its world starts at its own origin -- 0.0 seconds, turn 0, whatever
+ *     the caller's own axis calls zero -- rather than partway up the
+ *     engine's append ordinal, which is what every game gets by default the
+ *     moment its first entity is written with no axis declared (see
+ *     projection.ts).
+ *   - Re-declaring the IDENTICAL axis (same `kind`, and for `elapsed` /
+ *     `counter` the same `unit`) is a no-op unless `startAt` is supplied, in
+ *     which case it must be `>= current_t` -- `t` never runs backwards, full
+ *     stop, even when the axis itself is not changing.
+ *   - Declaring a DIFFERENT axis over a clock still on the default
+ *     `sequence` axis is allowed -- nothing has committed to `sequence`
+ *     meaning anything yet, it is just what every game gets before its
+ *     owner says otherwise -- but `startAt` (defaulting to the current `t`)
+ *     must still be `>= current_t`, so `t` never runs backwards across the
+ *     change either.
+ *   - Declaring a DIFFERENT axis over a clock already on a non-`sequence`
+ *     axis is refused outright. An axis is fixed for the life of a game's
+ *     timeline once it has been chosen for real: swapping it mid-timeline is
+ *     precisely what re-segmenting a caller's own units does to the meaning
+ *     of every `t` already recorded (§14) -- the one runtime action that
+ *     reproduces that failure, and this is where it is refused rather than
+ *     silently reinterpreting history. Declaring `sequence` back over a
+ *     declared axis is refused by this exact same rule: `sequence` is a
+ *     `kind` like any other here, not a neutral "no axis" state to fall back
+ *     to.
+ *
+ * Known limit, pinned by a test in clock.test.ts (not desired behaviour): a
+ * game created through `createGame` already has its own creation write
+ * recorded on the default `sequence` axis before any caller can act --
+ * `createGame` has no parameter for a caller-supplied id, so there is no id
+ * to declare an axis against before that write lands. The practical effect
+ * is that such a game's declared axis has a floor above zero (`startAt`
+ * below the game's current `t` at declaration time is refused, by the
+ * backwards-`t` rule above, with that floor named in the message). The fix
+ * is to move the origin UP to the floor, never to shift the caller's own
+ * numbers down to fit -- silently offsetting an axis to fit is exactly the
+ * failure §14 exists to prevent, so this limit is enforced the same loud way
+ * every other one here is. This lifts only if `createGame` (or an
+ * equivalent) gains a caller-supplied id, which is a separate issue.
+ */
+export declare function declareTimeAxis(params: {
+    gameId: string;
+    axis: TimeAxis;
+    startAt?: T;
+}): StoryTime;
+/**
+ * Moves a game's `t` forward. This is the caller's own hand on the clock --
+ * it exists only for a declared, non-`sequence` axis, because those are the
+ * only axes whose writes do not already advance `t` for themselves
+ * (projection.ts advances `current_t` on every write, but only `WHERE
+ * axis_kind = 'sequence'`; a declared `elapsed` or `counter` axis sits still
+ * between calls here by construction).
+ *
+ * Three refusals, none of them advisory:
+ *   - no clock row for `gameId`: nothing has declared or written anything
+ *     for this game yet, so there is no `t` to move.
+ *   - the axis is still `sequence`: the append ordinal belongs to the
+ *     engine, not to a caller positioning `t` by hand. This is the sharpest
+ *     form of "make the wrong axis awkward to supply" the API has -- a
+ *     caller who reaches for this on a default game is told to say what its
+ *     axis actually is first, not handed a silent success that means
+ *     nothing.
+ *   - `t` would move backwards under `compareT`.
+ */
+export declare function setStoryTime(params: {
+    gameId: string;
+    t: T;
+}): StoryTime;

package/dist/timeline/clock.js

@@ -0,0 +1,173 @@
+import { getDatabase } from "../db/connection.js";
+import { assertT, compareT } from "./t.js";
+/**
+ * `timeline_clock.axis_unit` always holds a string, including for
+ * `sequence` -- the generated projection triggers (projection.ts) write
+ * `'write'` there when they lazily bootstrap a clock row for a game that
+ * never called `declareTimeAxis`. The `TimeAxis` type has no `unit` field on
+ * `sequence` because a caller never chooses or reads it; this function
+ * exists so that fact is expressed once, not re-derived at every call site.
+ */
+function axisToRow(axis) {
+    return axis.kind === "sequence" ? { kind: "sequence", unit: "write" } : axis;
+}
+function rowToAxis(row) {
+    return row.axis_kind === "sequence"
+        ? { kind: "sequence" }
+        : { kind: row.axis_kind, unit: row.axis_unit };
+}
+/** Human-readable axis, for error messages only -- never parsed back. */
+function describeAxis(axis) {
+    return axis.kind === "sequence" ? "sequence (the engine's append ordinal)" : `${axis.kind}(${axis.unit})`;
+}
+/** `null` for `sequence` (no unit exists to compare), else the declared unit. */
+function axisUnitOrNull(axis) {
+    return axis.kind === "sequence" ? null : axis.unit;
+}
+function sameAxis(a, b) {
+    return a.kind === b.kind && axisUnitOrNull(a) === axisUnitOrNull(b);
+}
+function readClock(gameId) {
+    return getDatabase()
+        .prepare(`SELECT game_id, current_t, axis_kind, axis_unit, declared_at FROM timeline_clock WHERE game_id = ?`)
+        .get(gameId);
+}
+/** Current position on a game's timeline, or null if nothing has ever been declared or written for it. */
+export function currentStoryTime(gameId) {
+    const row = readClock(gameId);
+    if (!row)
+        return null;
+    return { gameId, t: row.current_t, axis: rowToAxis(row) };
+}
+/**
+ * Declares (or re-declares) the axis a game's `t` moves along. This is the
+ * one place §14's property (hard rule 6) is enforced at runtime rather than
+ * merely documented by `TimeAxis`'s missing fourth variant (t.ts):
+ *
+ *   - No clock row yet: create one at `startAt ?? 0` on the requested axis.
+ *     This is the path a caller uses BEFORE creating anything for this game,
+ *     so its world starts at its own origin -- 0.0 seconds, turn 0, whatever
+ *     the caller's own axis calls zero -- rather than partway up the
+ *     engine's append ordinal, which is what every game gets by default the
+ *     moment its first entity is written with no axis declared (see
+ *     projection.ts).
+ *   - Re-declaring the IDENTICAL axis (same `kind`, and for `elapsed` /
+ *     `counter` the same `unit`) is a no-op unless `startAt` is supplied, in
+ *     which case it must be `>= current_t` -- `t` never runs backwards, full
+ *     stop, even when the axis itself is not changing.
+ *   - Declaring a DIFFERENT axis over a clock still on the default
+ *     `sequence` axis is allowed -- nothing has committed to `sequence`
+ *     meaning anything yet, it is just what every game gets before its
+ *     owner says otherwise -- but `startAt` (defaulting to the current `t`)
+ *     must still be `>= current_t`, so `t` never runs backwards across the
+ *     change either.
+ *   - Declaring a DIFFERENT axis over a clock already on a non-`sequence`
+ *     axis is refused outright. An axis is fixed for the life of a game's
+ *     timeline once it has been chosen for real: swapping it mid-timeline is
+ *     precisely what re-segmenting a caller's own units does to the meaning
+ *     of every `t` already recorded (§14) -- the one runtime action that
+ *     reproduces that failure, and this is where it is refused rather than
+ *     silently reinterpreting history. Declaring `sequence` back over a
+ *     declared axis is refused by this exact same rule: `sequence` is a
+ *     `kind` like any other here, not a neutral "no axis" state to fall back
+ *     to.
+ *
+ * Known limit, pinned by a test in clock.test.ts (not desired behaviour): a
+ * game created through `createGame` already has its own creation write
+ * recorded on the default `sequence` axis before any caller can act --
+ * `createGame` has no parameter for a caller-supplied id, so there is no id
+ * to declare an axis against before that write lands. The practical effect
+ * is that such a game's declared axis has a floor above zero (`startAt`
+ * below the game's current `t` at declaration time is refused, by the
+ * backwards-`t` rule above, with that floor named in the message). The fix
+ * is to move the origin UP to the floor, never to shift the caller's own
+ * numbers down to fit -- silently offsetting an axis to fit is exactly the
+ * failure §14 exists to prevent, so this limit is enforced the same loud way
+ * every other one here is. This lifts only if `createGame` (or an
+ * equivalent) gains a caller-supplied id, which is a separate issue.
+ */
+export function declareTimeAxis(params) {
+    const { gameId, axis } = params;
+    if (params.startAt !== undefined)
+        assertT(params.startAt);
+    const db = getDatabase();
+    const existing = readClock(gameId);
+    if (!existing) {
+        const t = params.startAt ?? 0;
+        const row = axisToRow(axis);
+        db.prepare(`INSERT INTO timeline_clock (game_id, current_t, axis_kind, axis_unit, declared_at) VALUES (?, ?, ?, ?, ?)`).run(gameId, t, row.kind, row.unit, new Date().toISOString());
+        return { gameId, t, axis };
+    }
+    const existingAxis = rowToAxis(existing);
+    if (sameAxis(existingAxis, axis)) {
+        if (params.startAt === undefined) {
+            // No-op: the identical axis, no requested move.
+            return { gameId, t: existing.current_t, axis: existingAxis };
+        }
+        if (compareT(params.startAt, existing.current_t) < 0) {
+            throw new Error(`timeline: cannot declare startAt ${params.startAt} for game '${gameId}' -- ` +
+                `t never runs backwards, and its current t is ${existing.current_t}. ` +
+                `Pass startAt >= ${existing.current_t}, or omit startAt to leave t where it is.`);
+        }
+        db.prepare(`UPDATE timeline_clock SET current_t = ? WHERE game_id = ?`).run(params.startAt, gameId);
+        return { gameId, t: params.startAt, axis: existingAxis };
+    }
+    if (existingAxis.kind !== "sequence") {
+        throw new Error(`timeline: game '${gameId}' already declared axis ${describeAxis(existingAxis)}; ` +
+            `an axis is fixed for the life of a game's timeline once declared, and cannot become ` +
+            `${describeAxis(axis)} now. Swapping axes mid-timeline would silently reattach every ` +
+            `already-recorded t to a different meaning (design §14) -- start a new game if this one ` +
+            `truly needs a different axis, or re-declare ${describeAxis(existingAxis)} if that is what was meant.`);
+    }
+    const startAt = params.startAt ?? existing.current_t;
+    if (compareT(startAt, existing.current_t) < 0) {
+        throw new Error(`timeline: cannot declare axis ${describeAxis(axis)} starting at ${startAt} for game '${gameId}' -- ` +
+            `t never runs backwards, even across an axis change, and its current t is ${existing.current_t}. ` +
+            `Pass startAt >= ${existing.current_t}.`);
+    }
+    const newRow = axisToRow(axis);
+    db.prepare(`UPDATE timeline_clock SET current_t = ?, axis_kind = ?, axis_unit = ?, declared_at = ? WHERE game_id = ?`).run(startAt, newRow.kind, newRow.unit, new Date().toISOString(), gameId);
+    return { gameId, t: startAt, axis };
+}
+/**
+ * Moves a game's `t` forward. This is the caller's own hand on the clock --
+ * it exists only for a declared, non-`sequence` axis, because those are the
+ * only axes whose writes do not already advance `t` for themselves
+ * (projection.ts advances `current_t` on every write, but only `WHERE
+ * axis_kind = 'sequence'`; a declared `elapsed` or `counter` axis sits still
+ * between calls here by construction).
+ *
+ * Three refusals, none of them advisory:
+ *   - no clock row for `gameId`: nothing has declared or written anything
+ *     for this game yet, so there is no `t` to move.
+ *   - the axis is still `sequence`: the append ordinal belongs to the
+ *     engine, not to a caller positioning `t` by hand. This is the sharpest
+ *     form of "make the wrong axis awkward to supply" the API has -- a
+ *     caller who reaches for this on a default game is told to say what its
+ *     axis actually is first, not handed a silent success that means
+ *     nothing.
+ *   - `t` would move backwards under `compareT`.
+ */
+export function setStoryTime(params) {
+    assertT(params.t);
+    const { gameId, t } = params;
+    const existing = readClock(gameId);
+    if (!existing) {
+        throw new Error(`timeline: game '${gameId}' has no timeline clock yet -- nothing has been declared or written ` +
+            `for it. Call declare_time_axis first (or write something through the normal tools, which ` +
+            `bootstraps the default sequence axis), then set_story_time.`);
+    }
+    const axis = rowToAxis(existing);
+    if (axis.kind === "sequence") {
+        throw new Error(`timeline: game '${gameId}' is still on the default sequence axis -- the engine's own append ` +
+            `ordinal, which advances one tick per write and does not take a caller-supplied position. ` +
+            `Call declare_time_axis first with the axis this game's t actually is (elapsed or counter); ` +
+            `set_story_time will work once a non-sequence axis is declared.`);
+    }
+    if (compareT(t, existing.current_t) < 0) {
+        throw new Error(`timeline: cannot set story time to ${t} for game '${gameId}' -- t never runs backwards, and its ` +
+            `current t is ${existing.current_t}. Pass a t >= ${existing.current_t}.`);
+    }
+    getDatabase().prepare(`UPDATE timeline_clock SET current_t = ? WHERE game_id = ?`).run(t, gameId);
+    return { gameId, t, axis };
+}