run-dmcp 0.1.0 → 0.2.0

package/dist/db/schema.js

@@ -1,5 +1,9 @@
-import { getDatabase } from "./connection.js";
-export function initializeSchema() {
+import { getDatabase, withTransaction } from "./connection.js";
+import { createLogger } from "../utils/logger.js";
+import { initializeTimelineSchema } from "../timeline/schema.js";
+import { initializeAdjudicationSchema } from "../timeline/adjudication.js";
+const log = createLogger("schema");
+export function initializeSchema(options) {
     const db = getDatabase();
     // ============================================================================
     // MIGRATION: Rename 'sessions' to 'games' and 'session_id' to 'game_id'
@@ -215,7 +219,9 @@ export function initializeSchema() {
       FOREIGN KEY (game_id) REFERENCES games(id) ON DELETE CASCADE
     )
   `);
-    // Resource history table (tracks all changes)
+    // Resource history table (tracks all changes) -- FROZEN, see the trigger
+    // immediately below. Kept for existing rows only; nothing writes here any
+    // more.
     db.exec(`
     CREATE TABLE IF NOT EXISTS resource_history (
       id TEXT PRIMARY KEY,
@@ -227,22 +233,281 @@ export function initializeSchema() {
       timestamp TEXT NOT NULL,
       FOREIGN KEY (resource_id) REFERENCES resources(id) ON DELETE CASCADE
     )
+  `);
+    // Design §5.4 option (C) / issue #9, Phase 3: `resource_history` stops
+    // being a mechanism. Interval-versioned `facts` (via the timeline's one
+    // choke point, writeConstrainedValue/transferConstrainedValue in
+    // src/timeline/constrained.ts) are now the ONLY record of what a
+    // resource's value used to be -- see valueHistory() there, and
+    // getResourceHistory() in src/tools/resource.ts, which reads through it.
+    // This trigger makes the second write path this project spent its whole
+    // history accumulating (see engineVocabulary.test.ts's epigraph on
+    // resource_history/relationship_history) UNCONSTRUCTABLE rather than
+    // merely undocumented: any INSERT here -- from old code nobody rewrote,
+    // from a copy-pasted query, from anything -- aborts loudly instead of
+    // silently reintroducing a second history.
+    //
+    // The table is frozen, not dropped. This project has no down-migrations
+    // (root CLAUDE.md) and no framework beyond "idempotent DDL runs on every
+    // startup" -- a migration that DROPped this table would destroy rows a
+    // user's existing database may still hold, permanently, the first time
+    // they upgraded, which is a strictly worse outcome than a table that
+    // simply stops growing. Nothing reads it (getResourceHistory() no longer
+    // does) and nothing writes it (this trigger); the rows already on disk
+    // are inert history, not a mechanism.
+    //
+    // DROP TRIGGER IF EXISTS then CREATE, not CREATE TRIGGER IF NOT EXISTS --
+    // the same reasoning src/timeline/schema.ts's append-only guards give for
+    // their own triggers: IF NOT EXISTS would freeze whatever guard first
+    // shipped for a given on-disk database forever, so a later fix to this
+    // trigger's logic or message would silently never reach a database that
+    // already had an older version installed. Dropping and recreating on
+    // every startup keeps the guard a database actually has in sync with the
+    // guard this build believes it deployed.
+    db.exec(`
+    DROP TRIGGER IF EXISTS resource_history_frozen;
+    CREATE TRIGGER resource_history_frozen BEFORE INSERT ON resource_history
+    BEGIN
+      SELECT RAISE(ABORT, 'resource_history is frozen -- interval-versioned facts are now the only record of what a resource value used to be (design section 5.4 option C); write through writeConstrainedValue in src/timeline/constrained.ts instead');
+    END;
   `);
     // Resource constraints table -- optional, server-enforced invariants on
     // resource values (see src/tools/constraint.ts). Opt-in: a resource with
     // no row here (directly or via resource_constraint_members) behaves
     // exactly as before this feature existed.
-    db.exec(`
+    //
+    // `RESOURCE_CONSTRAINTS_DDL` is a shared constant, not a literal inlined
+    // here, because issue #13's `resolve_only` (design §5.3's fourth
+    // row-based member) needs this exact CHECK-widened text executed in TWO
+    // places: here, for a fresh database, and again inside the CHECK-rebuild
+    // migration further below, for a database that still carries the OLD
+    // three-member CHECK (SQLite cannot ALTER a CHECK constraint -- widening
+    // one needs a full table rebuild; see that block's comment for the
+    // recipe). Sharing one JS string is what makes "a fresh database and a
+    // migrated database converge on byte-identical `sqlite_master.sql` for
+    // this table" true BY CONSTRUCTION rather than by two hand-written
+    // literals happening to agree today -- resolveOnly.test.ts asserts
+    // exactly that equality, and it would be a permanent, silent trap to
+    // maintain as two copies.
+    const RESOURCE_CONSTRAINTS_DDL = `
     CREATE TABLE IF NOT EXISTS resource_constraints (
       id TEXT PRIMARY KEY,
       game_id TEXT NOT NULL,
-      kind TEXT NOT NULL CHECK (kind IN ('bounded', 'monotonic', 'conserved')),
+      kind TEXT NOT NULL CHECK (kind IN ('bounded', 'monotonic', 'conserved', 'resolve_only')),
       direction TEXT CHECK (direction IN ('increasing', 'decreasing')),
       total REAL,
       created_at TEXT NOT NULL,
       FOREIGN KEY (game_id) REFERENCES games(id) ON DELETE CASCADE
     )
-  `);
+  `;
+    db.exec(RESOURCE_CONSTRAINTS_DDL);
+    // Add fact_key column to resource_constraints (migration, Phase 3 / issue
+    // #9 step 1, design §5.4 option (C)). A constraint governs a numeric
+    // *fact key* on an entity, not an entire row -- once the generic
+    // (entityId, factKey) choke point this column exists to prepare for
+    // lands, an entity can carry more than one numeric fact, and a constraint
+    // must say which one it governs or it would silently apply to all of
+    // them. 'value' is the default because every constraint that exists
+    // today (declared through declareBoundedConstraint/declareMonotonicConstraint/
+    // declareConservedConstraint in src/tools/constraint.ts) governs
+    // `resources.value` -- the sole numeric fact key any of them has ever
+    // constrained -- so defaulting means an existing database needs no data
+    // migration to keep reading its own constraints correctly. This column belongs on
+    // resource_constraints (the constraint), NOT on resource_constraint_members
+    // below: a 'conserved' set's members all share one key by construction
+    // (they are summed against a single total), and putting it on the member
+    // row would permit a set whose members are constrained on different
+    // keys -- a generality nothing has asked for.
+    //
+    // Shared for the same reason RESOURCE_CONSTRAINTS_DDL is above: the
+    // CHECK-rebuild migration below re-adds this exact column to its
+    // replacement table, and reusing the identical statement text (rather
+    // than a second hand-written ALTER) is what makes the fresh and migrated
+    // paths' final stored SQL provably identical instead of coincidentally
+    // similar.
+    const RESOURCE_CONSTRAINTS_ADD_FACT_KEY_DDL = `ALTER TABLE resource_constraints ADD COLUMN fact_key TEXT NOT NULL DEFAULT 'value'`;
+    try {
+        db.exec(RESOURCE_CONSTRAINTS_ADD_FACT_KEY_DDL);
+    }
+    catch {
+        // Column already exists
+    }
+    // Issue #13 / design §5.3, §5.4 option (C): widen resource_constraints'
+    // `kind` CHECK to admit 'resolve_only', the fourth row-based constraint
+    // family member. SQLite cannot ALTER a CHECK constraint -- unlike the
+    // fact_key column just above, there is no `ALTER TABLE ... ADD` for
+    // "loosen this CHECK" -- so a database that already has resource_constraints
+    // rows under the OLD three-member CHECK needs SQLite's own documented
+    // recipe for "other kinds of table schema changes": build a replacement
+    // table with the new CHECK, copy every row across, drop the old table, and
+    // put the replacement in its place. This is the riskiest part of issue #13
+    // precisely because it is a real ALTER on a table other code already
+    // depends on (resource_constraint_members' own FOREIGN KEY points at it),
+    // so every step below is deliberate -- see resolveOnly.test.ts for the
+    // "an existing database survives the rebuild with every row and every FK
+    // intact" test this comment describes.
+    //
+    // DETECTION IS IDEMPOTENT AND LITERAL, not a guess: read this codebase's
+    // OWN generated DDL back out of `sqlite_master` and check whether it
+    // already contains the token 'resolve_only'. Hard rule 4 (never
+    // pattern-match meaning) forbids deriving state by matching words or
+    // phrases against natural language -- narrative text a model wrote, or a
+    // player typed. This is neither: it is a literal substring check against
+    // SQL text THIS FUNCTION generated a few lines above, for a token THIS
+    // FUNCTION defined (the CHECK's own enum member). Rule 4 explicitly
+    // permits exactly that ("a literal check for a token we defined in output
+    // we generated is fine; understanding English is not") -- flagged here in
+    // as many words because a future reader skimming a string-literal
+    // `.includes()` check might otherwise mistake it for the thing rule 4
+    // bans. A truly fresh database never takes the branch below:
+    // RESOURCE_CONSTRAINTS_DDL's CREATE TABLE IF NOT EXISTS a few lines up
+    // already carries the widened CHECK, so by the time this runs, this
+    // database's own resource_constraints already contains 'resolve_only'.
+    const resourceConstraintsDdl = db
+        .prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'resource_constraints'`)
+        .get();
+    if (resourceConstraintsDdl && !resourceConstraintsDdl.sql.includes("resolve_only")) {
+        // DROP THE resolve_only TRIGGER FIRST, UNCONDITIONALLY, IF IT EXISTS --
+        // made ORDER-INDEPENDENT rather than relying on "this trigger has never
+        // been created yet the one time this branch runs." That reliance was
+        // real on today's code (this block runs before initializeTimelineSchema()
+        // ever installs timeline_facts_resolve_only for the very first time, so
+        // on the one startup that performs a rebuild, the trigger genuinely does
+        // not exist yet) -- but it is an ACCIDENT OF ORDERING, not a structural
+        // guarantee, and root CLAUDE.md's "test against an existing database,
+        // not just a fresh one" warning exists precisely because accidents of
+        // ordering are how this kind of bug survives review. The trigger's own
+        // `WHEN` clause names `resource_constraints`, and SQLite revalidates
+        // every trigger body during schema surgery on a table it references
+        // (measured, not assumed -- see resolveOnly.test.ts, whose migration
+        // fixture hit exactly this: `ALTER TABLE ... RENAME TO resource_constraints`
+        // failed with "no such table: resource_constraints" while this trigger
+        // still existed and the table was transiently absent mid-rebuild) --
+        // so a database where the trigger was somehow installed before a rebuild
+        // runs (a future change that reorders trigger installation, or widens
+        // this CHECK a second time some other way) would break at startup with
+        // the schema half-rebuilt. Dropping it here costs nothing: the
+        // DROP-then-CREATE discipline every trigger in this codebase already
+        // follows (see the trigger's own creation site, far below, and the
+        // reasoning timeline_facts_irreversible gives for the same pattern)
+        // means it is unconditionally reinstalled before this function returns
+        // regardless -- this is that discipline paying for itself a second time.
+        db.exec(`DROP TRIGGER IF EXISTS timeline_facts_resolve_only`);
+        // PRAGMA foreign_keys is a documented no-op when toggled inside a
+        // pending transaction, so it brackets withTransaction() below rather
+        // than living inside it -- set OFF here (before BEGIN), restored ON
+        // after COMMIT. connection.ts turns it ON for every connection at
+        // open (`getDatabase()`); this block is the one place in the codebase
+        // that deliberately, temporarily, undoes that, and it is responsible
+        // for putting it back.
+        db.pragma("foreign_keys = OFF");
+        withTransaction(() => {
+            // EMPIRICALLY MEASURED, NOT ASSUMED (see resolveOnly.test.ts, whose
+            // FK-check assertion caught a real bug in an earlier version of this
+            // block): `ALTER TABLE ... RENAME TO` does not just rename the table
+            // being renamed -- it also rewrites the stored FOREIGN KEY clause of
+            // every OTHER table that references it by name (here,
+            // resource_constraint_members' `FOREIGN KEY (constraint_id)
+            // REFERENCES resource_constraints(id)`), REGARDLESS of the
+            // `foreign_keys` pragma above. Renaming the OLD table out of the way
+            // (the obvious first move) would therefore silently rewrite
+            // resource_constraint_members to reference the OLD table's new,
+            // temporary name -- and once that old table is dropped a few steps
+            // later, that reference is permanently dangling, with no further
+            // rename ever pointed at it to fix it back. `DROP TABLE`, unlike
+            // `RENAME TO`, does NOT rewrite other tables' references (there is
+            // nothing to rewrite them TO), so this recipe routes around the
+            // problem entirely: the old table is copied out of and then DROPped
+            // (never renamed), and the FINAL name is produced by a genuine
+            // `CREATE TABLE` (also never a rename target) -- so
+            // resource_constraint_members' FK text is never touched by anything
+            // in this block, and is simply valid again the moment step 4 below
+            // recreates a table under the name it always pointed at.
+            //
+            // 1. Copy the OLD table's rows into a staging table under a temporary
+            //    name -- widened CHECK, and fact_key included from the start
+            //    (unlike the final table a few steps down, this one is never
+            //    compared to RESOURCE_CONSTRAINTS_DDL's stored text, so there is
+            //    no reason to reproduce the fresh path's "add fact_key later via
+            //    ALTER" shape here).
+            db.exec(`
+        CREATE TABLE resource_constraints_staging (
+          id TEXT PRIMARY KEY,
+          game_id TEXT NOT NULL,
+          kind TEXT NOT NULL CHECK (kind IN ('bounded', 'monotonic', 'conserved', 'resolve_only')),
+          direction TEXT CHECK (direction IN ('increasing', 'decreasing')),
+          total REAL,
+          created_at TEXT NOT NULL,
+          fact_key TEXT NOT NULL DEFAULT 'value'
+        )
+      `);
+            db.exec(`
+        INSERT INTO resource_constraints_staging (id, game_id, kind, direction, total, created_at, fact_key)
+        SELECT id, game_id, kind, direction, total, created_at, fact_key FROM resource_constraints
+      `);
+            // 2. Drop the OLD table outright -- not renamed, per the note above.
+            db.exec(`DROP TABLE resource_constraints`);
+            // 3. Recreate under the FINAL name using the exact same DDL text the
+            //    fresh-database path executed above -- RESOURCE_CONSTRAINTS_DDL
+            //    itself, not a second hand-copied literal. This is a genuine
+            //    `CREATE TABLE resource_constraints (...)`, never a rename
+            //    target, so its stored SQL stays unquoted -- matching the
+            //    fresh-database path byte for byte (verified empirically, see
+            //    resolveOnly.test.ts's "byte-identical" assertion) rather than
+            //    picking up RENAME TO's habit of re-quoting the identifier.
+            db.exec(RESOURCE_CONSTRAINTS_DDL);
+            // 4. Copy every row across from the staging table with an EXPLICIT
+            //    column list -- never SELECT * -- naming every column except
+            //    fact_key, which the just-recreated table does not have yet. It
+            //    is added next, the same way the fresh path adds it.
+            db.exec(`
+        INSERT INTO resource_constraints (id, game_id, kind, direction, total, created_at)
+        SELECT id, game_id, kind, direction, total, created_at FROM resource_constraints_staging
+      `);
+            // 5. Add fact_key via the IDENTICAL statement text the fresh path
+            //    uses (RESOURCE_CONSTRAINTS_ADD_FACT_KEY_DDL, not a hand-written
+            //    equivalent). This is what makes the two paths' stored SQL
+            //    provably byte-identical after this point: SQLite's ALTER TABLE
+            //    ADD COLUMN rewrites a table's stored CREATE TABLE text by
+            //    inserting the new column definition right after the last
+            //    existing column and before any table-level constraint (verified
+            //    empirically, not assumed -- see resolveOnly.test.ts) -- running
+            //    the same statement against two structurally identical tables
+            //    produces the same rewritten text, with no need to hand-guess
+            //    that formatting.
+            db.exec(RESOURCE_CONSTRAINTS_ADD_FACT_KEY_DDL);
+            // 6. The ALTER above just backfilled every just-copied row's fact_key
+            //    with its DEFAULT 'value' -- correct for every row that can exist
+            //    today (every declare*Constraint() function other than
+            //    declareResolveOnlyConstraint hardcodes factKey 'value', and
+            //    declareResolveOnlyConstraint cannot have written a row before
+            //    this migration exists to run), but this UPDATE restores each
+            //    row's ACTUAL prior fact_key from the staging table by id rather
+            //    than leaning on that staying true forever. An UPDATE never
+            //    touches sqlite_master, so it cannot disturb the byte-identical
+            //    DDL text step 5 just produced.
+            db.exec(`
+        UPDATE resource_constraints
+           SET fact_key = (
+             SELECT fact_key FROM resource_constraints_staging
+              WHERE resource_constraints_staging.id = resource_constraints.id
+           )
+      `);
+            // 7. Drop the staging table. Every id was copied verbatim in step 4,
+            //    so resource_constraint_members' FOREIGN KEY (constraint_id)
+            //    REFERENCES resource_constraints(id) -- never touched by any of
+            //    the steps above -- is satisfied by the replacement table
+            //    throughout, verified for real by the PRAGMA foreign_key_check
+            //    below, not merely assumed here.
+            db.exec(`DROP TABLE resource_constraints_staging`);
+        });
+        const fkViolations = db.pragma("foreign_key_check");
+        if (fkViolations.length > 0) {
+            throw new Error(`resource_constraints CHECK migration (resolve_only, issue #13) left dangling foreign keys: ` +
+                JSON.stringify(fkViolations));
+        }
+        db.pragma("foreign_keys = ON");
+    }
     // Members of a resource constraint. 'bounded' and 'monotonic' constraints
     // have exactly one member (the resource they govern); 'conserved'
     // constraints have two or more (the set that must sum to a fixed total).
@@ -255,6 +520,12 @@ export function initializeSchema() {
       FOREIGN KEY (resource_id) REFERENCES resources(id) ON DELETE CASCADE
     )
   `);
+    // The adjudication window (design §5.3, §5.2a; issue #13): created here,
+    // BEFORE `timeline_facts_resolve_only` (the trigger that reads it, added
+    // near the end of this function once `facts` exists) -- see
+    // src/timeline/adjudication.ts for the table's own doc comment, including
+    // why its startup pass unconditionally clears every row.
+    initializeAdjudicationSchema(db);
     // Game time table (one per game)
     db.exec(`
     CREATE TABLE IF NOT EXISTS game_time (
@@ -366,7 +637,8 @@ export function initializeSchema() {
       FOREIGN KEY (game_id) REFERENCES games(id) ON DELETE CASCADE
     )
   `);
-    // Relationship history table
+    // Relationship history table -- FROZEN, see the trigger immediately below.
+    // Kept for existing rows only; nothing writes here any more.
     db.exec(`
     CREATE TABLE IF NOT EXISTS relationship_history (
       id TEXT PRIMARY KEY,
@@ -377,6 +649,25 @@ export function initializeSchema() {
       timestamp TEXT NOT NULL,
       FOREIGN KEY (relationship_id) REFERENCES relationships(id) ON DELETE CASCADE
     )
+  `);
+    // Design §5.4 option (C) / issue #9, Phase 3 step 3: `relationship_history`
+    // stops being a mechanism, same as `resource_history` immediately above --
+    // see that trigger's comment for the shared reasoning (why frozen and not
+    // dropped, why DROP-then-CREATE on every startup). The one thing specific
+    // here: `relationships` was already a `PROJECTED_TABLES` row (projection.ts)
+    // before this trigger existed, so its `value` column was already being
+    // dual-written into interval-versioned `facts` -- this freeze is what makes
+    // that the ONLY record, by routing every relationship value write through
+    // writeConstrainedValue() (src/timeline/constrained.ts) and cutting off the
+    // second path this table represented. See valueHistory() there, and
+    // getRelationshipHistory() in src/tools/relationship.ts, which reads
+    // through it.
+    db.exec(`
+    DROP TRIGGER IF EXISTS relationship_history_frozen;
+    CREATE TRIGGER relationship_history_frozen BEFORE INSERT ON relationship_history
+    BEGIN
+      SELECT RAISE(ABORT, 'relationship_history is frozen -- interval-versioned facts are now the only record of what a relationship value used to be (design section 5.4 option C); write through writeConstrainedValue in src/timeline/constrained.ts instead');
+    END;
   `);
     // Factions table
     db.exec(`
@@ -722,4 +1013,145 @@ export function initializeSchema() {
     CREATE INDEX IF NOT EXISTS idx_stored_audio_primary ON stored_audio(entity_id, entity_type, is_primary);
     CREATE INDEX IF NOT EXISTS idx_stored_audio_voice_ref ON stored_audio(game_id, is_voice_reference);
   `);
+    // Consumer-registered migrations (see `SchemaMigration` above) run after
+    // every core table above exists.
+    runConsumerMigrations(db, options?.migrations);
+    // Timeline substrate (design §5.1), and it must be LAST -- after the
+    // consumer's migrations, not merely after this function's own DDL.
+    //
+    // The projection triggers are generated from a live `pragma_table_info`
+    // read of each projected table (see timeline/projection.ts), so whatever
+    // ran most recently is what they are built against. A consumer migration
+    // that adds a column to a projected table therefore gets that column
+    // projected as a fact key, and reconciliation backfills it, with no code
+    // change on either side. Run this before `runConsumerMigrations` instead
+    // and such a column would be silently absent from the timeline until some
+    // later startup happened to regenerate -- which is precisely the drift the
+    // Phase 1 checkpoint exists to catch, arriving through the one door the
+    // engine hands a consumer.
+    initializeTimelineSchema();
+    // Issue #13 / design §5.3, §5.2a: `resolve_only`'s enforcement backstop --
+    // the SQL-level twin of the `resolve_only` branch in assertConstraintsAllow()
+    // (src/timeline/constrained.ts). That JS check covers every write that
+    // goes through writeConstrainedValue/transferConstrainedValue; THIS
+    // trigger is what makes a write that skips those functions entirely --
+    // a raw `UPDATE resources SET value = ...`, old code nobody rewrote, a
+    // copy-pasted query -- unconstructable rather than merely unchecked. It
+    // has to live HERE, not inside initializeTimelineSchema() (src/timeline/schema.ts)
+    // alongside timeline_facts_irreversible (the trigger it is modeled on):
+    // it reads resource_constraints/resource_constraint_members, which are
+    // src/db/schema.ts's own tables, AND facts, which initializeTimelineSchema()
+    // just created a line above -- and initializeTimelineSchema() is the LAST
+    // thing this function calls (see the comment above it), so `facts` does
+    // not exist at any point before that call returns. Creating this trigger
+    // any earlier would `CREATE TRIGGER` against a table that isn't there
+    // yet.
+    //
+    // ORDERING REQUIREMENT, STATED EXPLICITLY SO NOBODY MOVES THIS LATER: this
+    // CREATE must run AFTER resource_constraints, resource_constraint_members
+    // and timeline_adjudications_open all exist (true from here on, since all
+    // three are created earlier in this same function) AND after the CHECK
+    // -rebuild migration above has already run for this call. The rebuild
+    // block enforces the second half of that itself -- it unconditionally
+    // `DROP TRIGGER IF EXISTS`s this exact trigger before doing any table
+    // surgery, precisely so that surgery can never run while this trigger
+    // still exists to have its `WHEN` clause revalidated mid-rebuild against a
+    // table that is transiently missing (see that block's own comment). Do
+    // not reorder this CREATE ahead of that block on the theory that "it
+    // always ran after anyway" -- that theory is exactly what the rebuild
+    // block's DROP now makes irrelevant, and reordering would silently
+    // reintroduce the dependency the DROP exists to remove.
+    //
+    // SCOPED PER (entity_id, key), unlike timeline_facts_irreversible's
+    // per-(entity_id, key) VALUE comparison -- resolve_only has no value to
+    // compare, only a declaration to look up, via the same JOIN
+    // registry.ts's constraintsFor() runs in JS: is there a 'resolve_only'
+    // constraint whose member list includes NEW.entity_id and whose fact_key
+    // matches NEW.key. AND conditional on the window: the second half of the
+    // WHEN clause, `NOT EXISTS (SELECT 1 FROM timeline_adjudications_open)`,
+    // reads the exact same table `adjudicationOpen()` (src/timeline/adjudication.js)
+    // reads in JS -- see that module's doc comment for why this is one source
+    // of truth read in two places, never two independent checks that happen
+    // to agree.
+    //
+    // BEFORE INSERT ON facts, not UPDATE: facts are append-only
+    // (timeline_facts_immutable, src/timeline/schema.ts), so a new value for a
+    // key always arrives as a fresh INSERT. This is deliberately an INSERT
+    // guard for the same reason timeline_facts_irreversible is one: closing an
+    // interval is `UPDATE facts SET valid_to_t = ...`, a different table
+    // event entirely, and is NOT a write of a new value -- it never reaches
+    // this trigger. That is what keeps destroying an entity, or otherwise
+    // closing a resolve_only-governed fact, legal even with no adjudication
+    // window open: the engine records decisions, it does not impose policy on
+    // top of them (hard rule 2), and refusing to let an entity be destroyed
+    // because it happens to carry a resolve_only fact would be exactly that.
+    //
+    // DROP-then-CREATE, never CREATE TRIGGER IF NOT EXISTS -- the same
+    // reasoning timeline_facts_irreversible and every other trigger in this
+    // codebase give for themselves: IF NOT EXISTS would freeze whatever guard
+    // first shipped for a given on-disk database forever, so a later fix to
+    // this trigger's logic or wording would silently never reach a database
+    // that already had an older version installed. Dropping and recreating on
+    // every startup keeps the guard a database actually has in sync with the
+    // guard this build believes it deployed.
+    //
+    // NOTE FOR THE NEXT READER OF reconcileTimeline() (src/timeline/projection.ts):
+    // reconciliation runs at the end of every startup and, per column, closes
+    // a diverged fact and opens a new one -- an INSERT that would hit this
+    // very trigger for a resolve_only-governed key with no window open
+    // (reconciliation is not an adjudicating call). projection.ts's
+    // reconcileTable() carries its own guard for exactly that, modeled on the
+    // one it already had for `irreversible` -- see the comment on its
+    // close-UPDATE and open-INSERT statements.
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_facts_resolve_only;
+    CREATE TRIGGER timeline_facts_resolve_only
+    BEFORE INSERT ON facts
+    WHEN EXISTS (
+      SELECT 1 FROM resource_constraints rc
+        JOIN resource_constraint_members rcm ON rcm.constraint_id = rc.id
+       WHERE rc.kind = 'resolve_only'
+         AND rcm.resource_id = NEW.entity_id
+         AND rc.fact_key = NEW.key
+    ) AND NOT EXISTS (SELECT 1 FROM timeline_adjudications_open)
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: ''' || NEW.key || ''' on this entity is resolve_only-constrained; direct writes are refused -- this value can only change through the adjudicating call that opens the resolution window');
+    END;
+  `);
+}
+function runConsumerMigrations(db, migrations) {
+    if (!migrations || migrations.length === 0) {
+        return;
+    }
+    validateMigrations(migrations);
+    for (const migration of migrations) {
+        try {
+            db.transaction(() => {
+                migration.up(db);
+            })();
+        }
+        catch (err) {
+            log.error("Consumer schema migration failed", {
+                migration: migration.name,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw new Error(`Schema migration '${migration.name}' failed`, { cause: err });
+        }
+    }
+}
+function validateMigrations(migrations) {
+    const seen = new Set();
+    for (const migration of migrations) {
+        const name = migration?.name;
+        if (typeof name !== "string" || name.trim().length === 0) {
+            throw new Error(`Invalid schema migration: 'name' must be a non-empty string, got ${JSON.stringify(name)}`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`Duplicate schema migration name: '${name}'`);
+        }
+        seen.add(name);
+        if (typeof migration.up !== "function") {
+            throw new Error(`Schema migration '${name}' has no 'up' function`);
+        }
+    }
 }

package/dist/http/server.js

@@ -9,18 +9,18 @@ import { getCharacter, listCharacters, renderCharacterSheet, } from "../tools/ch
 import { getLocation, listLocations, renderMap } from "../tools/world.js";
 import { getImage, getImageData, listEntityImages, listGameImages, } from "../tools/images.js";
 import { getInventory, getItem, listGameItems } from "../tools/inventory.js";
-import { listQuests, getQuest } from "../tools/quest.js";
+import { listQuests, getQuest } from "../rpg/tools/quest.js";
 import { getHistory } from "../tools/narrative.js";
 import { getDisplayConfig, getGameDisplayConfig, hasGameTheme, } from "../tools/display.js";
 import { listFactions, getFaction } from "../tools/faction.js";
 import { listResources, getResource } from "../tools/resource.js";
 import { listNotes, getNote } from "../tools/notes.js";
 import { listRelationships } from "../tools/relationship.js";
-import { listAbilities, getAbility } from "../tools/ability.js";
+import { listAbilities, getAbility } from "../rpg/tools/ability.js";
 import { listTimers, getTimer } from "../tools/timers.js";
 import { listSecrets } from "../tools/secrets.js";
 import { getTime } from "../tools/time.js";
-import { getActiveCombat } from "../tools/combat.js";
+import { getActiveCombat } from "../rpg/tools/combat.js";
 import { gameEvents } from "../events/emitter.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

package/dist/index.d.ts

@@ -1,2 +1,36 @@
-#!/usr/bin/env node
-export {};
+export { createCoreMcpServer, SERVER_NAME, SERVER_VERSION } from "./mcp-server.js";
+export { getDatabase, closeDatabase, withTransaction, getDatabasePath, getDataDir, resolveDataPathFrom, } from "./db/connection.js";
+export type { DataPathInputs } from "./db/connection.js";
+export { initializeSchema } from "./db/schema.js";
+export type { SchemaMigration } from "./db/schema.js";
+export { replay } from "./timeline/replay.js";
+export type { Snapshot, ReplayedEntity, ReplayedFact } from "./timeline/replay.js";
+export { declareTimeAxis, setStoryTime, currentStoryTime } from "./timeline/clock.js";
+export type { StoryTime } from "./timeline/clock.js";
+export { changesWithin } from "./timeline/changes.js";
+export type { Change, ChangeSet, EventChange, FactChange } from "./timeline/changes.js";
+export { compareT, assertT } from "./timeline/t.js";
+export type { T, TimeAxis } from "./timeline/t.js";
+export { timelineDivergences } from "./timeline/checkpoint.js";
+export type { Divergence } from "./timeline/checkpoint.js";
+export { declareIrreversible, irreversibleFactFor, listIrreversibleFacts, } from "./timeline/irreversible.js";
+export type { IrreversibleFact } from "./timeline/irreversible.js";
+export { openingEventId } from "./timeline/provenance.js";
+export type { FactProvenance } from "./timeline/provenance.js";
+export { narrationConstraintAt, contradictions, NARRATION_CONSTRAINT_FORMAT_VERSION, } from "./timeline/narration.js";
+export type { NarrationConstraint, ConstraintFact, Claim, Contradiction } from "./timeline/narration.js";
+export { writeConstrainedValue, transferConstrainedValue, valueHistory, } from "./timeline/constrained.js";
+export type { ValueTransition } from "./timeline/constrained.js";
+export { ConstraintViolationError, constraintsFor, conservedConstraintFor } from "./timeline/registry.js";
+export { createResolver, ResolveProtocolError } from "./timeline/resolve.js";
+export type { Mechanic, Resolver, Proposal, Expectation, AdjudicationInput, Adjudication, IntendedChange, IntendedWrite, IntendedTransfer, Outcome, ResolveRefusalReason, } from "./timeline/resolve.js";
+export { createStateRenderer } from "./timeline/render.js";
+export type { RenderVocabulary, VocabularyEntry, StateRenderer, RenderedState, RenderedNoun, UnnamedFact, } from "./timeline/render.js";
+export { createTurnReader } from "./reader/turnReader.js";
+export type { TurnReader, ReaderQuestion, ReaderSource, ReaderTransport, ReadRequest, TransportAnswer, ReaderResult, AnsweredQuestion, RejectedOffer, RejectionReason, } from "./reader/turnReader.js";
+export { exportTimeline, importTimeline, exportTimelineToFile, importTimelineFromFile, TIMELINE_FORMAT_VERSION, } from "./timeline/export.js";
+export type { TimelineExport, TimelineExportEntity, TimelineExportFact, TimelineExportEvent, TimelineExportClock, TimelineImportResult, } from "./timeline/export.js";
+export { ENTITY_KINDS } from "./timeline/kinds.js";
+export type { EntityKind } from "./timeline/kinds.js";
+export { DEFAULT_HTTP_PORT, httpPortFromEnv, webUiEnabled, setHttpPort, getWebUiBaseUrl, } from "./utils/webui.js";
+export type * from "./types/index.js";