run-dmcp 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -14,6 +14,7 @@ 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 type { SetTransition } from "./timeline/constrained.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";
@@ -22,7 +23,7 @@ export { writeConstrainedValue, transferConstrainedValue, valueHistory, } from "
 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 type { Mechanic, Resolver, Proposal, Expectation, AdjudicationInput, Adjudication, IntendedChange, IntendedWrite, IntendedTransfer, IntendedSet, 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";

package/dist/mcp-server.d.ts

@@ -6,7 +6,7 @@ export declare const SERVER_NAME = "dmcp";
  *  the published package version by src/__tests__/serverVersion.test.ts --
  *  this said "0.3.0" for the whole of 0.4.0, because a release bumps
  *  package.json and nothing was watching this. */
-export declare const SERVER_VERSION = "0.5.0";
+export declare const SERVER_VERSION = "0.7.0";
 /**
  * Build an MCP server with every CORE tool, resource and prompt this engine
  * serves -- entities, facts, events, the timeline, and the entity/property

package/dist/mcp-server.js

@@ -45,7 +45,7 @@ export const SERVER_NAME = "dmcp";
  *  the published package version by src/__tests__/serverVersion.test.ts --
  *  this said "0.3.0" for the whole of 0.4.0, because a release bumps
  *  package.json and nothing was watching this. */
-export const SERVER_VERSION = "0.5.0";
+export const SERVER_VERSION = "0.7.0";
 /**
  * Build an MCP server with every CORE tool, resource and prompt this engine
  * serves -- entities, facts, events, the timeline, and the entity/property

package/dist/timeline/constrained.d.ts

@@ -218,3 +218,42 @@ export declare function transferConstrainedValue(params: {
  * discipline. `limit` applies after ordering, never before.
  */
 export declare function valueHistory(entityId: string, key: string, limit?: number): ValueTransition[];
+/**
+ * One non-numeric column set, as `resolve()`'s `set` intent applies it (issue
+ * #32). A row, never a verdict: what the column held, what it holds now, and
+ * the fact the write opened -- `null` when the value did not move, because an
+ * unchanged value opens no new interval (projection.ts's update trigger).
+ */
+export interface SetTransition {
+    entityId: string;
+    key: string;
+    previousValue: string | number | null;
+    newValue: string | number | null;
+    t: T;
+    factId: string | null;
+}
+/**
+ * Sets one live column of an entity's projected table to `value` (issue #32).
+ * The engine stores what it is handed and never learns what the column means;
+ * the projection triggers version it exactly as they version every other
+ * column write, so nothing here touches `facts` directly.
+ *
+ * The same choke point as numeric writes, and the same checks in the same
+ * voice: the entity and column are resolved against `PROJECTED_TABLES` /
+ * `liveColumns` (never a caller-supplied table name); the column that places
+ * the entity in its game is refused; a key carrying a numeric constraint is
+ * refused, because that value changes by a write where the constraint is
+ * evaluated; `resolve_only` asks the one question it always asks, whether an
+ * adjudication window is open; and a contradicted irreversible fact is
+ * translated into a typed `ConstraintViolationError` with the one hop
+ * attached, by `translateIrreversibleFailure`, never by reading the trigger's
+ * message.
+ *
+ * Not exported from the library: `resolve()` is its only caller, so a
+ * non-numeric consequence reaches storage through a resolution or not at all.
+ */
+export declare function setProjectedValue(params: {
+    entityId: string;
+    key: string;
+    value: string | number | null;
+}): SetTransition;

package/dist/timeline/constrained.js

@@ -669,3 +669,81 @@ export function valueHistory(entityId, key, limit) {
     const limited = limit !== undefined ? ranked.slice(0, limit) : ranked;
     return limited.map((r) => r.transition);
 }
+/** The numeric members of the constraint family. A key carrying one of them
+ *  changes by a write (`writeConstrainedValue`), where the constraint is
+ *  evaluated; a `set` would step round it. */
+const NUMERIC_CONSTRAINT_KINDS = new Set(["monotonic", "bounded", "conserved"]);
+function openFactId(db, entityId, key) {
+    const row = db
+        .prepare(`SELECT id FROM facts WHERE entity_id = ? AND key = ? AND valid_to_t IS NULL ORDER BY valid_from_t DESC, id DESC LIMIT 1`)
+        .get(entityId, key);
+    return row?.id ?? null;
+}
+/**
+ * Sets one live column of an entity's projected table to `value` (issue #32).
+ * The engine stores what it is handed and never learns what the column means;
+ * the projection triggers version it exactly as they version every other
+ * column write, so nothing here touches `facts` directly.
+ *
+ * The same choke point as numeric writes, and the same checks in the same
+ * voice: the entity and column are resolved against `PROJECTED_TABLES` /
+ * `liveColumns` (never a caller-supplied table name); the column that places
+ * the entity in its game is refused; a key carrying a numeric constraint is
+ * refused, because that value changes by a write where the constraint is
+ * evaluated; `resolve_only` asks the one question it always asks, whether an
+ * adjudication window is open; and a contradicted irreversible fact is
+ * translated into a typed `ConstraintViolationError` with the one hop
+ * attached, by `translateIrreversibleFailure`, never by reading the trigger's
+ * message.
+ *
+ * Not exported from the library: `resolve()` is its only caller, so a
+ * non-numeric consequence reaches storage through a resolution or not at all.
+ */
+export function setProjectedValue(params) {
+    const resolved = resolveProjection(params.entityId, params.key);
+    const db = getDatabase();
+    const projected = PROJECTED_TABLES.find((p) => p.table === resolved.table);
+    if (projected && projected.gameIdColumn === params.key) {
+        throw new Error(`timeline: '${params.key}' places entity '${params.entityId}' in its game and cannot be set -- ` +
+            `an entity does not move between games`);
+    }
+    for (const constraint of constraintsFor(params.entityId, params.key)) {
+        if (NUMERIC_CONSTRAINT_KINDS.has(constraint.kind)) {
+            throw new ConstraintViolationError(constraint.kind, params.entityId, `Entity '${params.entityId}' is ${constraint.kind}-constrained for key '${params.key}', which a set does not ` +
+                `evaluate; this value changes by a write, where the constraint is checked.`);
+        }
+        if (constraint.kind === "resolve_only" && !adjudicationOpen()) {
+            throw new ConstraintViolationError("resolve_only", params.entityId, `Entity '${params.entityId}' is resolve_only-constrained for key '${params.key}'; direct writes are refused. ` +
+                `This value can only change through the adjudicating call that opens the resolution window.`);
+        }
+    }
+    const row = db.prepare(`SELECT ${resolved.key} AS value FROM ${resolved.table} WHERE id = ?`).get(resolved.entityId);
+    if (!row) {
+        throw new Error(`timeline: no live row in '${resolved.table}' for entity '${resolved.entityId}' -- ` +
+            `it may have been destroyed since it was last confirmed to exist`);
+    }
+    try {
+        return withTransaction(() => {
+            const before = openFactId(db, resolved.entityId, resolved.key);
+            db.prepare(`UPDATE ${resolved.table} SET ${resolved.key} = ? WHERE id = ?`).run(params.value, resolved.entityId);
+            const after = openFactId(db, resolved.entityId, resolved.key);
+            const story = currentStoryTime(resolved.gameId);
+            if (!story) {
+                throw new Error(`timeline: game '${resolved.gameId}' has no timeline clock -- a set has no t to attach to`);
+            }
+            return {
+                entityId: resolved.entityId,
+                key: resolved.key,
+                previousValue: row.value,
+                newValue: params.value,
+                t: story.t,
+                factId: after !== before ? after : null,
+            };
+        });
+    }
+    catch (err) {
+        if (params.value === null)
+            throw err;
+        translateIrreversibleFailure(db, [{ entityId: params.entityId, key: params.key, table: resolved.table, attemptedValue: params.value }], err);
+    }
+}

package/dist/timeline/export.d.ts

@@ -80,6 +80,13 @@ export interface TimelineExportFact {
     validFromT: T;
     validToT: T | null;
     irreversible: boolean;
+    /** The one hop of causality (design §5.2c, issue #30) -- the event that
+     *  opened this fact, or null when none is recorded. Optional, not just
+     *  nullable: a v1 artifact written before issue #30 landed carries no such
+     *  field at all, and `importTimeline` treats an absent field and an
+     *  explicit `null` identically -- there was never a recorded hop for
+     *  either, so there is nothing to guess and no reason to refuse. */
+    openedByEventId?: string | null;
 }
 export interface TimelineExportEvent {
     id: string;
@@ -158,10 +165,12 @@ export declare function exportTimeline(gameId: string): TimelineExport;
  * artifact shape above) is stamped fresh at import time; it was never
  * exported and never round-trips.
  *
- * `entities` are inserted before `facts` because `facts.entity_id` is a
- * real foreign key and this database runs with `PRAGMA foreign_keys = ON`
- * (`../db/connection.ts`) -- inserting out of order would fail loudly
- * rather than silently, but there is no reason to invite the failure.
+ * `entities` are inserted before `events` and `facts` because `facts.entity_id`
+ * is a real foreign key; `events` are inserted before `facts` (issue #30) for
+ * the identical reason now that `facts.opened_by_event_id` is one too --
+ * this database runs with `PRAGMA foreign_keys = ON` (`../db/connection.ts`),
+ * so inserting out of order would fail loudly rather than silently, but
+ * there is no reason to invite the failure.
  */
 export declare function importTimeline(artifact: TimelineExport): TimelineImportResult;
 /**

package/dist/timeline/export.js

@@ -103,7 +103,7 @@ function readTimeline(gameId) {
     // scoped by joining back to entities, exactly the way replay.ts scopes
     // "what was true of them" to "who was alive."
     const factRows = db
-        .prepare(`SELECT f.id, f.entity_id, f.key, f.value, f.valid_from_t, f.valid_to_t, f.irreversible
+        .prepare(`SELECT f.id, f.entity_id, f.key, f.value, f.valid_from_t, f.valid_to_t, f.irreversible, f.opened_by_event_id
        FROM facts f
        JOIN entities e ON e.id = f.entity_id
        WHERE e.game_id = ?
@@ -137,6 +137,7 @@ function readTimeline(gameId) {
             validFromT: row.valid_from_t,
             validToT: row.valid_to_t,
             irreversible: Boolean(row.irreversible),
+            openedByEventId: row.opened_by_event_id,
         })),
         events: eventRows.map((row) => ({
             id: row.id,
@@ -266,10 +267,12 @@ function assertTargetIsEmpty(gameId) {
  * artifact shape above) is stamped fresh at import time; it was never
  * exported and never round-trips.
  *
- * `entities` are inserted before `facts` because `facts.entity_id` is a
- * real foreign key and this database runs with `PRAGMA foreign_keys = ON`
- * (`../db/connection.ts`) -- inserting out of order would fail loudly
- * rather than silently, but there is no reason to invite the failure.
+ * `entities` are inserted before `events` and `facts` because `facts.entity_id`
+ * is a real foreign key; `events` are inserted before `facts` (issue #30) for
+ * the identical reason now that `facts.opened_by_event_id` is one too --
+ * this database runs with `PRAGMA foreign_keys = ON` (`../db/connection.ts`),
+ * so inserting out of order would fail loudly rather than silently, but
+ * there is no reason to invite the failure.
  */
 export function importTimeline(artifact) {
     assertValidArtifactShape(artifact);
@@ -289,14 +292,17 @@ export function importTimeline(artifact) {
         for (const entity of artifact.entities) {
             insertEntity.run(entity.id, entity.gameId, entity.kind, entity.name, entity.createdAtT, entity.destroyedAtT);
         }
-        const insertFact = db.prepare(`INSERT INTO facts (id, entity_id, key, value, valid_from_t, valid_to_t, irreversible) VALUES (?, ?, ?, ?, ?, ?, ?)`);
-        for (const fact of artifact.facts) {
-            insertFact.run(fact.id, fact.entityId, fact.key, fact.value, fact.validFromT, fact.validToT, fact.irreversible ? 1 : 0);
-        }
+        // Events before facts (issue #30): `facts.opened_by_event_id` is a real
+        // foreign key into `events` now, on top of `facts.entity_id`'s existing
+        // one into `entities` -- see this function's doc comment.
         const insertEvent = db.prepare(`INSERT INTO events (id, game_id, at_t, kind, description, causes) VALUES (?, ?, ?, ?, ?, ?)`);
         for (const event of artifact.events) {
             insertEvent.run(event.id, event.gameId, event.atT, event.kind, event.description, event.causes);
         }
+        const insertFact = db.prepare(`INSERT INTO facts (id, entity_id, key, value, valid_from_t, valid_to_t, irreversible, opened_by_event_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const fact of artifact.facts) {
+            insertFact.run(fact.id, fact.entityId, fact.key, fact.value, fact.validFromT, fact.validToT, fact.irreversible ? 1 : 0, fact.openedByEventId ?? null);
+        }
         return {
             gameId: artifact.gameId,
             entities: artifact.entities.length,

package/dist/timeline/irreversible.js

@@ -1,7 +1,11 @@
 import { getDatabase } from "../db/connection.js";
 import { assertT } from "./t.js";
-import { openingEventId } from "./provenance.js";
-function toIrreversibleFact(row, gameId) {
+/** `gameId` is no longer used to look up the hop (issue #30: it is a stored
+ *  column on the fact row itself, never derived), but stays a parameter so
+ *  every call site here keeps naming the game it is working in -- and so a
+ *  future caller that genuinely needs to re-scope by game has somewhere to
+ *  put it without changing every signature in this file again. */
+function toIrreversibleFact(row, _gameId) {
     assertT(row.valid_from_t);
     return {
         factId: row.id,
@@ -9,7 +13,7 @@ function toIrreversibleFact(row, gameId) {
         key: row.key,
         value: row.value,
         validFromT: row.valid_from_t,
-        openedByEventId: openingEventId(gameId, row.entity_id, row.valid_from_t),
+        openedByEventId: row.opened_by_event_id,
     };
 }
 /**
@@ -44,7 +48,7 @@ export function declareIrreversible(params) {
     // order. Same tiebreak as irreversibleFactFor below, so the two functions
     // can never disagree about which row they mean.
     const open = db
-        .prepare(`SELECT id, entity_id, key, value, valid_from_t FROM facts
+        .prepare(`SELECT id, entity_id, key, value, valid_from_t, opened_by_event_id FROM facts
         WHERE entity_id = ? AND key = ? AND valid_to_t IS NULL
         ORDER BY valid_from_t DESC, id DESC
         LIMIT 1`)
@@ -73,7 +77,7 @@ export function irreversibleFactFor(entityId, key) {
     if (!entity)
         return null;
     const row = db
-        .prepare(`SELECT id, entity_id, key, value, valid_from_t FROM facts
+        .prepare(`SELECT id, entity_id, key, value, valid_from_t, opened_by_event_id FROM facts
         WHERE entity_id = ? AND key = ? AND irreversible = 1
         ORDER BY valid_from_t DESC, id DESC
         LIMIT 1`)
@@ -92,7 +96,8 @@ export function irreversibleFactFor(entityId, key) {
 export function listIrreversibleFacts(params) {
     const db = getDatabase();
     let query = `
-    SELECT f.id AS id, f.entity_id AS entity_id, f.key AS key, f.value AS value, f.valid_from_t AS valid_from_t
+    SELECT f.id AS id, f.entity_id AS entity_id, f.key AS key, f.value AS value, f.valid_from_t AS valid_from_t,
+           f.opened_by_event_id AS opened_by_event_id
     FROM facts f
     JOIN entities e ON e.id = f.entity_id
     WHERE e.game_id = ? AND f.irreversible = 1

package/dist/timeline/narration.js

@@ -1,6 +1,5 @@
 import { getDatabase } from "../db/connection.js";
 import { assertT, compareT } from "./t.js";
-import { openingEventId } from "./provenance.js";
 /**
  * The outbound half of authority (design §5.2b/§5.2c, GitHub issues #11 and
  * #12): "Here is what is true; depict it, do not argue with it." One
@@ -47,7 +46,10 @@ import { openingEventId } from "./provenance.js";
  * opened it" in this codebase, not a second copy grown for this module.
  */
 export const NARRATION_CONSTRAINT_FORMAT_VERSION = 1;
-function toConstraintFact(row, gameId) {
+/** `gameId` is unused now that the hop is a stored column (issue #30) rather
+ *  than derived per-row, but the parameter stays -- see irreversible.ts's
+ *  identical note on `toIrreversibleFact`. */
+function toConstraintFact(row, _gameId) {
     assertT(row.valid_from_t);
     if (row.valid_to_t !== null)
         assertT(row.valid_to_t);
@@ -61,7 +63,7 @@ function toConstraintFact(row, gameId) {
         irreversible: Boolean(row.irreversible),
         entityKind: row.entity_kind,
         entityName: row.entity_name,
-        openedByEventId: openingEventId(gameId, row.entity_id, row.valid_from_t),
+        openedByEventId: row.opened_by_event_id,
     };
 }
 /**
@@ -125,7 +127,7 @@ export function narrationConstraintAt(params) {
     const rows = db
         .prepare(`SELECT f.id AS id, f.entity_id AS entity_id, f.key AS key, f.value AS value,
               f.valid_from_t AS valid_from_t, f.valid_to_t AS valid_to_t, f.irreversible AS irreversible,
-              e.kind AS entity_kind, e.name AS entity_name
+              e.kind AS entity_kind, e.name AS entity_name, f.opened_by_event_id AS opened_by_event_id
          FROM facts f
          JOIN entities e ON e.id = f.entity_id
         WHERE e.game_id = ?

package/dist/timeline/projection.js

@@ -41,10 +41,16 @@ function tExpr(gidExpr) {
 /**
  * `AFTER INSERT`: ensure the game's clock row exists, advance it, insert the
  * entity, insert one fact per non-NULL column, insert a `<kind>.created`
- * event. Column names are interpolated directly (never bound as parameters)
- * because they come from this codebase's own `pragma_table_info`, never
- * from anything a caller supplied -- there is no user input anywhere in
- * this SQL (trigger-sql-skeleton trap #6).
+ * event, then (issue #30) stamp every fact this firing just opened with that
+ * event's id via `last_insert_rowid()` -- the one hop of causality (design
+ * §5.2c), recorded rather than derived later. The `opened_by_event_id IS
+ * NULL` guard is what keeps a repeated `t` on a non-`sequence` axis correct:
+ * it restricts the stamp to facts THIS firing opened, never one a previous
+ * firing at the same `t` already stamped. Column names are interpolated
+ * directly (never bound as parameters) because they come from this
+ * codebase's own `pragma_table_info`, never from anything a caller supplied
+ * -- there is no user input anywhere in this SQL (trigger-sql-skeleton
+ * trap #6).
  */
 function buildInsertTrigger(row, cols) {
     const gid = `NEW.${row.gameIdColumn}`;
@@ -72,6 +78,9 @@ ${factInserts}
       INSERT INTO events (id, game_id, at_t, kind, description, causes)
         VALUES (lower(hex(randomblob(16))), ${gid}, ${t}, '${row.kind}.created', '${row.kind} created',
                 json_object('table', '${row.table}', 'row_id', NEW.id));
+
+      UPDATE facts SET opened_by_event_id = (SELECT id FROM events WHERE rowid = last_insert_rowid())
+        WHERE entity_id = NEW.id AND valid_from_t = ${t} AND opened_by_event_id IS NULL;
     END;
   `;
 }
@@ -84,6 +93,11 @@ ${factInserts}
  * column: reversed, the open's subquery would still see the value the
  * close was about to retire and write nothing (trap #3). The five-case
  * table this produces is walked by the test suite, not re-derived here.
+ * After the `<kind>.updated` event lands, every fact this firing just opened
+ * (across every column touched) is stamped with that event's id -- see
+ * `buildInsertTrigger`'s doc comment for why the `opened_by_event_id IS
+ * NULL` guard is what keeps this correct when a non-`sequence` axis repeats
+ * a `t` across firings (issue #30).
  */
 function buildUpdateTrigger(row, cols) {
     const gid = `NEW.${row.gameIdColumn}`;
@@ -111,6 +125,9 @@ ${perColumn}
       INSERT INTO events (id, game_id, at_t, kind, description, causes)
         VALUES (lower(hex(randomblob(16))), ${gid}, ${t}, '${row.kind}.updated', '${row.kind} updated',
                 json_object('table', '${row.table}', 'row_id', NEW.id));
+
+      UPDATE facts SET opened_by_event_id = (SELECT id FROM events WHERE rowid = last_insert_rowid())
+        WHERE entity_id = NEW.id AND valid_from_t = ${t} AND opened_by_event_id IS NULL;
     END;
   `;
 }

package/dist/timeline/provenance.d.ts

@@ -32,35 +32,28 @@ export interface FactProvenance {
     openedByEventId: string | null;
 }
 /**
- * The one hop of causality (design §5.2c): the event of `gameId` whose
- * `at_t` equals the fact's `valid_from_t` and whose `causes` JSON names this
- * entity as the row it was written for. `causes` is produced entirely by
- * this codebase's own projection triggers (`json_object('table', ...,
- * 'row_id', NEW.id)` in projection.ts) -- matching `$.row_id` here is a
- * literal comparison against a token we defined in output we generated, not
- * an attempt to understand what any event "means" (hard rule 4). Ordered
- * deterministically (`at_t`, then `id`) and only the first row is taken --
- * one hop, never a chain, never a trace of how the engine got here.
+ * The one hop of causality (design §5.2c), READ rather than derived (issue
+ * #30). `facts.opened_by_event_id` is stamped by the projection triggers'
+ * `_ai`/`_au` bodies (projection.ts) at the moment a fact opens, in the same
+ * firing, via `last_insert_rowid()` against the event they just inserted --
+ * so this is a direct column lookup now, not a search over `events` keyed by
+ * `(at_t, causes.row_id)` with a random-hex tiebreak among rows sharing a
+ * `t`. That derivation is gone, along with the failure modes it carried: it
+ * could return null for an event whose `causes` was not valid JSON, and it
+ * broke ties among same-`t` events arbitrarily.
  *
- * The `CASE WHEN json_valid(causes)` wrapper is load-bearing, not defensive
- * decoration. `events.causes` has no CHECK constraint, and SQLite's
- * `json_extract` RAISES "malformed JSON" rather than returning NULL when it
- * meets a value that is not JSON -- and that error belongs to the whole
- * query, not to the offending row, so a single bad row anywhere in this
- * game's events would make every function that calls this throw, including
- * ones that have nothing to do with that event. That is reachable in
- * practice: timeline import (export.ts) carries `causes` through verbatim
- * by design, because an importer that rewrote a recorded cause would be
- * inventing history. A hop of provenance must never be able to fail the
- * write it annotates, so a row we cannot read simply does not match.
- * Written as CASE rather than `json_valid(causes) AND json_extract(...)`
- * because SQLite does not guarantee the evaluation order of AND operands --
- * the planner may reorder them, and then the guard is decoration that
- * happens to work today.
+ * Both internal callers of this shape (`irreversible.ts`, `narration.ts`)
+ * no longer call this function at all -- each already queries its own fact
+ * row and now selects `opened_by_event_id` directly as part of that same
+ * query, which is strictly cheaper than a second round trip through here.
  *
- * Moved here verbatim (SQL, doc comment and all) from `irreversible.ts`'s
- * former module-private `findOpenedByEventId` -- this is the ONE owner of
- * §5.2c's hop now; `irreversible.ts` and `narration.ts` both call this
- * rather than each keeping a copy of the query.
+ * This function is kept, and re-pointed at the stored column rather than
+ * removed, because it is part of this package's published library surface
+ * (`src/index.ts` re-exports it) -- issue #30 did not ask for a public API
+ * removal, and removing an exported function silently would be exactly the
+ * kind of undocumented break root CLAUDE.md's "what we declare is what we
+ * mean" section warns against. A caller that already holds
+ * `(gameId, entityId, validFromT)` rather than a fact id can still use it;
+ * it now does less work to answer the same question.
  */
 export declare function openingEventId(gameId: string, entityId: string, validFromT: number): string | null;

package/dist/timeline/provenance.js

@@ -1,45 +1,41 @@
 import { getDatabase } from "../db/connection.js";
 /**
- * The one hop of causality (design §5.2c): the event of `gameId` whose
- * `at_t` equals the fact's `valid_from_t` and whose `causes` JSON names this
- * entity as the row it was written for. `causes` is produced entirely by
- * this codebase's own projection triggers (`json_object('table', ...,
- * 'row_id', NEW.id)` in projection.ts) -- matching `$.row_id` here is a
- * literal comparison against a token we defined in output we generated, not
- * an attempt to understand what any event "means" (hard rule 4). Ordered
- * deterministically (`at_t`, then `id`) and only the first row is taken --
- * one hop, never a chain, never a trace of how the engine got here.
+ * The one hop of causality (design §5.2c), READ rather than derived (issue
+ * #30). `facts.opened_by_event_id` is stamped by the projection triggers'
+ * `_ai`/`_au` bodies (projection.ts) at the moment a fact opens, in the same
+ * firing, via `last_insert_rowid()` against the event they just inserted --
+ * so this is a direct column lookup now, not a search over `events` keyed by
+ * `(at_t, causes.row_id)` with a random-hex tiebreak among rows sharing a
+ * `t`. That derivation is gone, along with the failure modes it carried: it
+ * could return null for an event whose `causes` was not valid JSON, and it
+ * broke ties among same-`t` events arbitrarily.
  *
- * The `CASE WHEN json_valid(causes)` wrapper is load-bearing, not defensive
- * decoration. `events.causes` has no CHECK constraint, and SQLite's
- * `json_extract` RAISES "malformed JSON" rather than returning NULL when it
- * meets a value that is not JSON -- and that error belongs to the whole
- * query, not to the offending row, so a single bad row anywhere in this
- * game's events would make every function that calls this throw, including
- * ones that have nothing to do with that event. That is reachable in
- * practice: timeline import (export.ts) carries `causes` through verbatim
- * by design, because an importer that rewrote a recorded cause would be
- * inventing history. A hop of provenance must never be able to fail the
- * write it annotates, so a row we cannot read simply does not match.
- * Written as CASE rather than `json_valid(causes) AND json_extract(...)`
- * because SQLite does not guarantee the evaluation order of AND operands --
- * the planner may reorder them, and then the guard is decoration that
- * happens to work today.
+ * Both internal callers of this shape (`irreversible.ts`, `narration.ts`)
+ * no longer call this function at all -- each already queries its own fact
+ * row and now selects `opened_by_event_id` directly as part of that same
+ * query, which is strictly cheaper than a second round trip through here.
  *
- * Moved here verbatim (SQL, doc comment and all) from `irreversible.ts`'s
- * former module-private `findOpenedByEventId` -- this is the ONE owner of
- * §5.2c's hop now; `irreversible.ts` and `narration.ts` both call this
- * rather than each keeping a copy of the query.
+ * This function is kept, and re-pointed at the stored column rather than
+ * removed, because it is part of this package's published library surface
+ * (`src/index.ts` re-exports it) -- issue #30 did not ask for a public API
+ * removal, and removing an exported function silently would be exactly the
+ * kind of undocumented break root CLAUDE.md's "what we declare is what we
+ * mean" section warns against. A caller that already holds
+ * `(gameId, entityId, validFromT)` rather than a fact id can still use it;
+ * it now does less work to answer the same question.
  */
 export function openingEventId(gameId, entityId, validFromT) {
     const db = getDatabase();
     const row = db
-        .prepare(`SELECT id FROM events
-        WHERE game_id = ?
-          AND at_t = ?
-          AND json_extract(CASE WHEN json_valid(causes) THEN causes END, '$.row_id') = ?
-        ORDER BY at_t, id
+        .prepare(`SELECT f.opened_by_event_id AS id
+         FROM facts f
+         JOIN entities e ON e.id = f.entity_id
+        WHERE e.game_id = ?
+          AND f.entity_id = ?
+          AND f.valid_from_t = ?
+          AND f.opened_by_event_id IS NOT NULL
+        ORDER BY f.id
         LIMIT 1`)
-        .get(gameId, validFromT, entityId);
+        .get(gameId, entityId, validFromT);
     return row?.id ?? null;
 }

package/dist/timeline/resolve.d.ts

@@ -1,6 +1,6 @@
 import { type T } from "./t.js";
 import { type NarrationConstraint, type Contradiction } from "./narration.js";
-import { type ValueTransition } from "./constrained.js";
+import { type ValueTransition, type SetTransition } from "./constrained.js";
 /**
  * The inbound half of authority (design §5.2a, GitHub issue #10): propose ->
  * adjudicate -> outcome. The engine enforces the PROTOCOL -- resolution
@@ -71,8 +71,9 @@ import { type ValueTransition } from "./constrained.js";
  *      INSIDE it (adjudication.ts's own doc comment asks for exactly this
  *      nesting, so the window row rolls back with the writes it
  *      authorized). Every change goes through `writeConstrainedValue` /
- *      `transferConstrainedValue` -- the one choke point (root CLAUDE.md
- *      hard rule 7) -- never a direct write. A constraint violation
+ *      `transferConstrainedValue` / `setProjectedValue` (issue #32, a
+ *      non-numeric column) -- the one choke point (root CLAUDE.md hard
+ *      rule 7) -- never a direct write. A constraint violation
  *      anywhere in the list propagates out of the transaction untouched
  *      (never caught and re-labelled here) and rolls back EVERY change the
  *      transaction made, including ones that individually would have
@@ -169,7 +170,17 @@ export interface IntendedTransfer {
         maxValue: number | null;
     };
 }
-export type IntendedChange = IntendedWrite | IntendedTransfer;
+/** One intended set of a non-numeric column on an entity's projected row
+ *  (issue #32) -- a thing changing owner, a character changing place. The
+ *  engine stores `value` and never learns what `key` means; see
+ *  `setProjectedValue` (constrained.ts) for what it refuses. */
+export interface IntendedSet {
+    kind: "set";
+    entityId: string;
+    key: string;
+    value: string | number | null;
+}
+export type IntendedChange = IntendedWrite | IntendedTransfer | IntendedSet;
 /**
  * What a mechanic returns. `changes` are intents, not writes -- `resolve()`
  * applies every one of them through the one choke point (step 5); the
@@ -201,6 +212,9 @@ export interface Outcome {
     t: T;
     result: Record<string, unknown>;
     transitions: ValueTransition[];
+    /** Every `set` this resolution applied, in order (issue #32). Kept apart
+     *  from `transitions`, whose values are numbers. */
+    sets: SetTransition[];
     constraint: NarrationConstraint;
     eventId: string;
 }

package/dist/timeline/resolve.js

@@ -3,7 +3,7 @@ import { getDatabase, withTransaction } from "../db/connection.js";
 import { currentStoryTime } from "./clock.js";
 import { narrationConstraintAt, contradictions } from "./narration.js";
 import { withAdjudicationOpen } from "./adjudication.js";
-import { writeConstrainedValue, transferConstrainedValue } from "./constrained.js";
+import { writeConstrainedValue, transferConstrainedValue, setProjectedValue } from "./constrained.js";
 /**
  * Refused before dispatch, before any write, or (never, by construction --
  * see step 5 above) mid-apply. `reason` is the discriminant a caller
@@ -81,6 +81,9 @@ export function createResolver(params) {
     };
 }
 function applyChange(change) {
+    if (change.kind === "set") {
+        return setProjectedValue({ entityId: change.entityId, key: change.key, value: change.value });
+    }
     if (change.kind === "write") {
         return [
             writeConstrainedValue({
@@ -180,8 +183,13 @@ function resolveProposal(mechanicsByName, proposal) {
     // is never relabelled as a ResolveProtocolError).
     const applied = withTransaction(() => withAdjudicationOpen(gameId, () => {
         const transitions = [];
+        const sets = [];
         for (const change of changes) {
-            transitions.push(...applyChange(change));
+            const applied = applyChange(change);
+            if (Array.isArray(applied))
+                transitions.push(...applied);
+            else
+                sets.push(applied);
         }
         // Re-read the clock AFTER every write has landed, inside this same
         // transaction -- a sequence-axis game advances its own t once per
@@ -206,7 +214,7 @@ function resolveProposal(mechanicsByName, proposal) {
         getDatabase()
             .prepare(`INSERT INTO events (id, game_id, at_t, kind, description, causes) VALUES (?, ?, ?, 'resolution.recorded', ?, ?)`)
             .run(eventId, gameId, postStory.t, adjudication.description ?? null, JSON.stringify(causes));
-        return { transitions, eventId, postT: postStory.t };
+        return { transitions, sets, eventId, postT: postStory.t };
     }));
     // 7. The outcome's constraint, built AFTER the writes landed and the
     // transaction holding them has already committed -- reachable only from a
@@ -220,6 +228,7 @@ function resolveProposal(mechanicsByName, proposal) {
         t,
         result: adjudication.result ?? {},
         transitions: applied.transitions,
+        sets: applied.sets,
         constraint: postConstraint,
         eventId: applied.eventId,
     };

package/dist/timeline/schema.js

@@ -84,6 +84,23 @@ export function initializeTimelineSchema() {
       causes TEXT
     )
   `);
+    // facts.opened_by_event_id -- issue #30: the one hop of causality (design
+    // §5.2c) recorded at the moment it is true, instead of derived at read
+    // time by searching `events` for a row whose `at_t`/`causes.row_id` happen
+    // to match (the query this replaces lived in provenance.ts, and could
+    // return null for a bad `causes` JSON blob, or pick the wrong event of
+    // several sharing one `t` by an arbitrary hex-id tiebreak). Idempotent
+    // ALTER, ordered after `events` exists -- legal under SQLite's ADD COLUMN
+    // restrictions because the implicit default is NULL, and a database that
+    // already has this column (every run after the first) just throws here,
+    // caught and ignored, same idiom as every other migration in this
+    // codebase (root CLAUDE.md).
+    try {
+        db.exec("ALTER TABLE facts ADD COLUMN opened_by_event_id TEXT REFERENCES events(id)");
+    }
+    catch {
+        // Column already exists.
+    }
     // timeline_clock -- one row per game, tracking the declared axis and its
     // current position. A game that never declares an axis still needs one
     // of these once its first entity/fact/event is written, with axis_kind
@@ -152,6 +169,16 @@ export function initializeTimelineSchema() {
     // change. declareIrreversible() (irreversible.ts) relies on that last
     // case to make re-declaring idempotent with a single UPDATE and no
     // separate "already set" check.
+    // Third one-way latch (issue #30): NULL -> value, once, exactly like
+    // `valid_to_t` above -- once the projection trigger has stamped
+    // `opened_by_event_id`, nothing may rewrite it, but the stamp itself (the
+    // trigger's own UPDATE, immediately after the fact's INSERT -- see
+    // projection.ts) must be allowed through. This clause is load-bearing, not
+    // hygiene: probed against better-sqlite3 at this project's own pragma
+    // settings, the append-only guard fires on trigger-initiated UPDATEs too.
+    // Without it, the projection trigger's own stamp would abort the write it
+    // annotates; with it, a stamped edge can never be rewritten -- a re-stamp
+    // raises ABORT.
     db.exec(`
     DROP TRIGGER IF EXISTS timeline_facts_immutable;
     CREATE TRIGGER timeline_facts_immutable
@@ -164,8 +191,9 @@ export function initializeTimelineSchema() {
       OR (NEW.irreversible IS NOT OLD.irreversible
           AND (OLD.irreversible IS NOT 0 OR NEW.irreversible IS NOT 1))
       OR (OLD.valid_to_t IS NOT NULL AND NEW.valid_to_t IS NOT OLD.valid_to_t)
+      OR (OLD.opened_by_event_id IS NOT NULL AND NEW.opened_by_event_id IS NOT OLD.opened_by_event_id)
     BEGIN
-      SELECT RAISE(ABORT, 'timeline: facts are append-only; valid_from_t cannot be rewritten, valid_to_t may only be closed once, and irreversible may only move 0 -> 1');
+      SELECT RAISE(ABORT, 'timeline: facts are append-only; valid_from_t cannot be rewritten, valid_to_t may only be closed once, irreversible may only move 0 -> 1, and opened_by_event_id may only be stamped once');
     END;
   `);
     db.exec(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-dmcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "An MCP server for LLM-run interactive fiction where the server owns what is true - including when it was true. A continuation of DMCP.",
   "license": "MIT",
   "author": "Derek Ferguson",