run-dmcp 0.1.0 → 0.2.0

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 };
+}