run-dmcp 0.6.0 → 0.8.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, CreatedEntity, DestroyedEntity } 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, IntendedCreate, IntendedDestroy, EntityRef, 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.6.0";
+export declare const SERVER_VERSION = "0.8.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.6.0";
+export const SERVER_VERSION = "0.8.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

@@ -1,4 +1,5 @@
 import { type T } from "./t.js";
+import type { EntityKind } from "./kinds.js";
 /**
  * The choke point (design §5.4 option (C), Phase 3 step 2): the ONE place a
  * constrained numeric fact key is written, and the ONE place `resources`'
@@ -218,3 +219,112 @@ 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;
+/**
+ * One entity a resolution brought into existence (issue #34). A row, never
+ * a verdict: which kind, the id the engine allocated, where on the timeline
+ * it landed, and the `<kind>.created` event the projection trigger wrote --
+ * design §5.2c's one hop, recorded rather than derived later.
+ */
+export interface CreatedEntity {
+    entityId: string;
+    entityKind: EntityKind;
+    t: T;
+    eventId: string | null;
+}
+/** One entity a resolution ended (issue #34): the `<kind>.destroyed` event
+ *  and the `t` its facts were closed at. */
+export interface DestroyedEntity {
+    entityId: string;
+    entityKind: EntityKind;
+    t: T;
+    eventId: string | null;
+}
+/**
+ * Inserts one live row into the projected table for `entityKind` (issue
+ * #34) -- the choke point's door for bringing an entity into existence
+ * inside a resolution. The projection insert trigger (projection.ts) does
+ * every piece of timeline work: the `entities` row, one open fact per
+ * non-NULL column, the `<kind>.created` event, the provenance stamp. Nothing
+ * here writes `facts` or `events` directly.
+ *
+ * What it refuses, before any write: a kind with no projected table; the
+ * `game` kind (a resolution belongs to a game and cannot create one); a
+ * caller-supplied `id` (the engine allocates it, because a mechanic has no
+ * database handle and could not know a free one); the column that places
+ * the entity in its game (filled from the proposal, never the mechanic);
+ * and any column the table's `liveColumns()` does not report. Column names
+ * are interpolated only after that check -- they are this codebase's own
+ * `pragma_table_info` vocabulary by then, never a caller's string. Values
+ * are bound. A column the table itself requires and the caller omitted is
+ * SQLite's refusal, not this function's: the engine never learns what a
+ * column means, including whether it is optional.
+ *
+ * Not exported from the library: `resolve()` is its only caller, so an
+ * entity comes into being through a resolution or through the tool layer,
+ * and there is no third way.
+ */
+export declare function createProjectedEntity(params: {
+    gameId: string;
+    entityKind: EntityKind;
+    columns: Readonly<Record<string, string | number | null>>;
+}): CreatedEntity;
+/**
+ * Deletes one entity's live row (issue #34) -- the choke point's door for
+ * ending an entity inside a resolution. The projection delete trigger closes
+ * every open fact, sets `destroyed_at_t` and writes `<kind>.destroyed`.
+ *
+ * Refused, before any write: an entity that does not exist, or is already
+ * destroyed, naming it; the `game` kind; and -- the conservative reading
+ * #34 asked to be pinned -- an entity carrying an irreversible fact, as a
+ * typed `ConstraintViolationError` with the one hop attached: destroying the
+ * entity would close that fact, and a fact declared to hold thereafter is
+ * not ended by removing what it is about. A `resolve_only` fact does not
+ * refuse a destroy: closing an interval is not a write of a new value
+ * (src/db/schema.ts's own note on `timeline_facts_resolve_only`), and inside
+ * a resolution the window is open, which is all resolve_only asks.
+ *
+ * Not exported from the library, for the reason `createProjectedEntity`
+ * gives.
+ */
+export declare function destroyProjectedEntity(params: {
+    entityId: string;
+}): DestroyedEntity;

package/dist/timeline/constrained.js

@@ -4,7 +4,7 @@ import { assertT, compareT } from "./t.js";
 import { currentStoryTime } from "./clock.js";
 import { PROJECTED_TABLES, liveColumns } from "./projection.js";
 import { constraintsFor, conservedConstraintFor, ConstraintViolationError, CONSERVED_SUM_EPSILON } from "./registry.js";
-import { irreversibleFactFor } from "./irreversible.js";
+import { irreversibleFactFor, listIrreversibleFacts } from "./irreversible.js";
 import { adjudicationOpen } from "./adjudication.js";
 /**
  * A1: resolves `entityId` to the live table its `key` column lives in, and
@@ -669,3 +669,222 @@ 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);
+    }
+}
+/** The projection event the trigger just wrote for `rowId` -- found by the
+ *  trigger's own `row_id` token (projection.ts), never by guessing at `t`.
+ *  `json_valid` guards the extraction for the reason `valueHistory` gives. */
+function projectionEventId(db, kind, rowId) {
+    const row = db
+        .prepare(`SELECT id FROM events WHERE kind = ?
+         AND json_extract(CASE WHEN json_valid(causes) THEN causes END, '$.row_id') = ?
+       ORDER BY rowid DESC LIMIT 1`)
+        .get(kind, rowId);
+    return row?.id ?? null;
+}
+/**
+ * Inserts one live row into the projected table for `entityKind` (issue
+ * #34) -- the choke point's door for bringing an entity into existence
+ * inside a resolution. The projection insert trigger (projection.ts) does
+ * every piece of timeline work: the `entities` row, one open fact per
+ * non-NULL column, the `<kind>.created` event, the provenance stamp. Nothing
+ * here writes `facts` or `events` directly.
+ *
+ * What it refuses, before any write: a kind with no projected table; the
+ * `game` kind (a resolution belongs to a game and cannot create one); a
+ * caller-supplied `id` (the engine allocates it, because a mechanic has no
+ * database handle and could not know a free one); the column that places
+ * the entity in its game (filled from the proposal, never the mechanic);
+ * and any column the table's `liveColumns()` does not report. Column names
+ * are interpolated only after that check -- they are this codebase's own
+ * `pragma_table_info` vocabulary by then, never a caller's string. Values
+ * are bound. A column the table itself requires and the caller omitted is
+ * SQLite's refusal, not this function's: the engine never learns what a
+ * column means, including whether it is optional.
+ *
+ * Not exported from the library: `resolve()` is its only caller, so an
+ * entity comes into being through a resolution or through the tool layer,
+ * and there is no third way.
+ */
+export function createProjectedEntity(params) {
+    const projected = PROJECTED_TABLES.find((p) => p.kind === params.entityKind);
+    if (!projected) {
+        throw new Error(`timeline: '${String(params.entityKind)}' is not a projected entity kind -- a resolution can create only ` +
+            PROJECTED_TABLES.filter((p) => p.kind !== "game")
+                .map((p) => `'${p.kind}'`)
+                .join(", "));
+    }
+    if (projected.kind === "game") {
+        throw new Error(`timeline: a resolution belongs to a game and cannot create one`);
+    }
+    const db = getDatabase();
+    const cols = liveColumns(db, projected.table);
+    const keys = Object.keys(params.columns);
+    for (const key of keys) {
+        if (key === "id") {
+            throw new Error(`timeline: 'id' is allocated by the engine and cannot be supplied for a created ${projected.kind}`);
+        }
+        if (key === projected.gameIdColumn) {
+            throw new Error(`timeline: '${key}' places a created ${projected.kind} in its game and is filled from the proposal, never by the mechanic`);
+        }
+        if (!cols.includes(key)) {
+            throw new Error(`timeline: '${key}' is not a live column of '${projected.table}' -- a created ${projected.kind} has no fact key by that name`);
+        }
+    }
+    const id = uuidv4();
+    return withTransaction(() => {
+        const columnList = ["id", projected.gameIdColumn, ...keys];
+        db.prepare(`INSERT INTO ${projected.table} (${columnList.join(", ")}) VALUES (${columnList.map(() => "?").join(", ")})`).run(id, params.gameId, ...keys.map((key) => params.columns[key]));
+        const entity = db.prepare(`SELECT created_at_t FROM entities WHERE id = ?`).get(id);
+        if (!entity) {
+            // Cannot happen while the projection triggers are installed; not a
+            // case to assume silently forever.
+            throw new Error(`timeline: the insert trigger on '${projected.table}' recorded no entity for the row it just projected`);
+        }
+        assertT(entity.created_at_t);
+        return {
+            entityId: id,
+            entityKind: projected.kind,
+            t: entity.created_at_t,
+            eventId: projectionEventId(db, `${projected.kind}.created`, id),
+        };
+    });
+}
+/**
+ * Deletes one entity's live row (issue #34) -- the choke point's door for
+ * ending an entity inside a resolution. The projection delete trigger closes
+ * every open fact, sets `destroyed_at_t` and writes `<kind>.destroyed`.
+ *
+ * Refused, before any write: an entity that does not exist, or is already
+ * destroyed, naming it; the `game` kind; and -- the conservative reading
+ * #34 asked to be pinned -- an entity carrying an irreversible fact, as a
+ * typed `ConstraintViolationError` with the one hop attached: destroying the
+ * entity would close that fact, and a fact declared to hold thereafter is
+ * not ended by removing what it is about. A `resolve_only` fact does not
+ * refuse a destroy: closing an interval is not a write of a new value
+ * (src/db/schema.ts's own note on `timeline_facts_resolve_only`), and inside
+ * a resolution the window is open, which is all resolve_only asks.
+ *
+ * Not exported from the library, for the reason `createProjectedEntity`
+ * gives.
+ */
+export function destroyProjectedEntity(params) {
+    const db = getDatabase();
+    const entity = db.prepare(`SELECT game_id, kind, destroyed_at_t FROM entities WHERE id = ?`).get(params.entityId);
+    if (!entity) {
+        throw new Error(`timeline: cannot destroy entity '${params.entityId}' -- it does not exist`);
+    }
+    if (entity.destroyed_at_t !== null) {
+        throw new Error(`timeline: entity '${params.entityId}' was already destroyed at t=${entity.destroyed_at_t}`);
+    }
+    const projected = PROJECTED_TABLES.find((p) => p.kind === entity.kind);
+    if (!projected) {
+        throw new Error(`timeline: entity '${params.entityId}' has kind '${entity.kind}', which has no projected table to delete from`);
+    }
+    if (projected.kind === "game") {
+        throw new Error(`timeline: a resolution belongs to a game and cannot destroy one`);
+    }
+    const live = db.prepare(`SELECT id FROM ${projected.table} WHERE id = ?`).get(params.entityId);
+    if (!live) {
+        throw new Error(`timeline: no live row in '${projected.table}' for entity '${params.entityId}' -- it may have been destroyed since it was last confirmed to exist`);
+    }
+    const [irreversible] = listIrreversibleFacts({ gameId: entity.game_id, entityId: params.entityId });
+    if (irreversible) {
+        throw new ConstraintViolationError("irreversible", params.entityId, `Entity '${params.entityId}' carries an irreversible fact for key '${irreversible.key}': value '${irreversible.value}' ` +
+            `holds as of t=${irreversible.validFromT}` +
+            (irreversible.openedByEventId !== null
+                ? ` (opened by event '${irreversible.openedByEventId}')`
+                : ` (no event is recorded for when this was opened)`) +
+            `. Destroying the entity would end that fact and is refused.`, irreversible);
+    }
+    return withTransaction(() => {
+        db.prepare(`DELETE FROM ${projected.table} WHERE id = ?`).run(params.entityId);
+        const after = db.prepare(`SELECT destroyed_at_t FROM entities WHERE id = ?`).get(params.entityId);
+        if (!after || after.destroyed_at_t === null) {
+            throw new Error(`timeline: the delete trigger on '${projected.table}' recorded no destruction for entity '${params.entityId}'`);
+        }
+        assertT(after.destroyed_at_t);
+        return {
+            entityId: params.entityId,
+            entityKind: projected.kind,
+            t: after.destroyed_at_t,
+            eventId: projectionEventId(db, `${projected.kind}.destroyed`, params.entityId),
+        };
+    });
+}

package/dist/timeline/resolve.d.ts

@@ -1,6 +1,7 @@
 import { type T } from "./t.js";
 import { type NarrationConstraint, type Contradiction } from "./narration.js";
-import { type ValueTransition } from "./constrained.js";
+import type { EntityKind } from "./kinds.js";
+import { type ValueTransition, type SetTransition, type CreatedEntity, type DestroyedEntity } 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 +72,17 @@ 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) / `createProjectedEntity` /
+ *      `destroyProjectedEntity` (issue #34, an entity beginning or ending)
+ *      -- the one choke point (root CLAUDE.md hard rule 7) -- never a
+ *      direct write. A `create` is labelled with a caller-chosen `ref`,
+ *      and a later leg of the same resolution may say `{ ref }` wherever
+ *      it would say an entity id, because a mechanic has no database
+ *      handle and cannot know the id the engine will allocate; every ref
+ *      is checked against the legs before it, BEFORE the transaction
+ *      opens, so a ref naming nothing refuses with no write attempted.
+ *      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
@@ -135,13 +145,24 @@ export interface AdjudicationInput {
     parameters: Record<string, unknown>;
     constraint: NarrationConstraint;
 }
+/**
+ * An entity id, or the label of an entity created by an earlier `create`
+ * leg of the same resolution (issue #34). A mechanic cannot know the id the
+ * engine allocates -- it has no database handle, which is the whole
+ * mechanism of "every write goes through the audited path" -- so it names
+ * the new entity by the `ref` it chose, and `resolve()` substitutes the
+ * real id when it applies the leg.
+ */
+export type EntityRef = string | {
+    ref: string;
+};
 /** One intended write to a single fact key -- the generic shape
  *  `writeConstrainedValue` (constrained.ts) already takes, carried here so a
  *  mechanic can express "change this value" without ever calling that
  *  function itself. */
 export interface IntendedWrite {
     kind: "write";
-    entityId: string;
+    entityId: EntityRef;
     key: string;
     mode: "delta" | "set";
     value: number;
@@ -155,8 +176,8 @@ export interface IntendedWrite {
  *  shape `transferConstrainedValue` (constrained.ts) already takes. */
 export interface IntendedTransfer {
     kind: "transfer";
-    fromEntityId: string;
-    toEntityId: string;
+    fromEntityId: EntityRef;
+    toEntityId: EntityRef;
     key: string;
     amount: number;
     reason?: string | null;
@@ -169,7 +190,43 @@ 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: EntityRef;
+    key: string;
+    /** `{ ref }` names an entity created earlier in this resolution -- the
+     *  new thing becoming this entity's owner, say. */
+    value: string | number | null | {
+        ref: string;
+    };
+}
+/** One intended entity coming into existence (issue #34): a row in the
+ *  projected table for `entityKind`, with `columns` restricted to that
+ *  table's live columns and the game column filled by the engine from the
+ *  proposal. `ref` is the label later legs of this same resolution use for
+ *  it; the engine allocates the id and reports it in `Outcome.created`.
+ *  The engine never learns what the entity is for or what it was made
+ *  from -- "derived from" is the caller's to record. */
+export interface IntendedCreate {
+    kind: "create";
+    ref: string;
+    entityKind: EntityKind;
+    columns: Readonly<Record<string, string | number | null | {
+        ref: string;
+    }>>;
+}
+/** One intended entity ending (issue #34): its live row deleted, its facts
+ *  closed by the projection trigger. See `destroyProjectedEntity`
+ *  (constrained.ts) for what it refuses. */
+export interface IntendedDestroy {
+    kind: "destroy";
+    entityId: EntityRef;
+}
+export type IntendedChange = IntendedWrite | IntendedTransfer | IntendedSet | IntendedCreate | IntendedDestroy;
 /**
  * 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 +258,18 @@ 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[];
+    /** Every entity this resolution created, in order, each with the `ref`
+     *  the mechanic labelled it with and the id the engine allocated (issue
+     *  #34). Kept apart from `transitions` and `sets`, so existing callers are
+     *  unchanged. */
+    created: (CreatedEntity & {
+        ref: string;
+    })[];
+    /** Every entity this resolution destroyed, in order (issue #34). */
+    destroyed: DestroyedEntity[];
     constraint: NarrationConstraint;
     eventId: string;
 }
@@ -218,7 +287,13 @@ export interface Mechanic {
  *  under -- never a judgement about the proposal, the mechanic, or the
  *  world (see the module doc comment's "records decisions, does not make
  *  them" paragraph). */
-export type ResolveRefusalReason = "unknown-mechanic" | "no-clock" | "expectation-contradicted";
+export type ResolveRefusalReason = "unknown-mechanic" | "no-clock" | "expectation-contradicted"
+/** A leg said `{ ref }` and no earlier `create` leg of the same
+ *  resolution defined that ref (issue #34). Refused before any write. */
+ | "unresolved-ref"
+/** Two `create` legs of one resolution chose the same `ref` (issue #34).
+ *  Refused before any write. */
+ | "duplicate-ref";
 /**
  * Refused before dispatch, before any write, or (never, by construction --
  * see step 5 above) mid-apply. `reason` is the discriminant a caller

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, createProjectedEntity, destroyProjectedEntity, } 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
@@ -80,30 +80,106 @@ export function createResolver(params) {
         },
     };
 }
-function applyChange(change) {
+/** Every `{ ref }` a change carries, in the order it is read (issue #34) --
+ *  the one place the shape of each intent kind's ref-bearing fields is
+ *  known, shared by the pre-transaction check and the apply step. */
+function refsUsedBy(change) {
+    const refOf = (value) => (typeof value === "object" && value !== null && "ref" in value ? [String(value.ref)] : []);
+    switch (change.kind) {
+        case "write":
+            return refOf(change.entityId);
+        case "transfer":
+            return [...refOf(change.fromEntityId), ...refOf(change.toEntityId)];
+        case "set":
+            return [...refOf(change.entityId), ...refOf(change.value)];
+        case "create":
+            return Object.values(change.columns).flatMap(refOf);
+        case "destroy":
+            return refOf(change.entityId);
+        default:
+            return [];
+    }
+}
+/**
+ * Step 5's precondition (issue #34): every `{ ref }` names a `create` leg
+ * EARLIER in the list, and no two creates share a ref. Checked over the
+ * intent list alone -- a structural property of what the mechanic returned,
+ * decidable with no database at all -- so a bad ref refuses with no
+ * transaction opened and no write attempted, in the same voice as every
+ * other protocol refusal.
+ */
+function assertRefsResolvable(mechanicName, changes) {
+    const defined = new Set();
+    changes.forEach((change, index) => {
+        for (const ref of refsUsedBy(change)) {
+            if (!defined.has(ref)) {
+                throw new ResolveProtocolError("unresolved-ref", `resolve: leg ${index + 1} of mechanic '${mechanicName}' names ref '${ref}', and no earlier 'create' leg of this ` +
+                    `resolution defines it; refused before any write. A ref may only name an entity created by a leg before the one that uses it.`);
+            }
+        }
+        if (change.kind === "create") {
+            if (defined.has(change.ref)) {
+                throw new ResolveProtocolError("duplicate-ref", `resolve: mechanic '${mechanicName}' creates two entities under the ref '${change.ref}'; refused before any write. ` +
+                    `A ref is unique within one resolution.`);
+            }
+            defined.add(change.ref);
+        }
+    });
+}
+function deref(value, refs) {
+    if (typeof value === "string")
+        return value;
+    const id = refs.get(value.ref);
+    if (id === undefined) {
+        // Unreachable after assertRefsResolvable; guarded so a future caller of
+        // this function alone still fails loudly.
+        throw new ResolveProtocolError("unresolved-ref", `resolve: ref '${value.ref}' names no entity created in this resolution`);
+    }
+    return id;
+}
+function derefValue(value, refs) {
+    return typeof value === "object" && value !== null ? deref(value, refs) : value;
+}
+function applyChange(change, gameId, refs) {
+    if (change.kind === "set") {
+        return { set: setProjectedValue({ entityId: deref(change.entityId, refs), key: change.key, value: derefValue(change.value, refs) }) };
+    }
     if (change.kind === "write") {
-        return [
-            writeConstrainedValue({
-                entityId: change.entityId,
-                key: change.key,
-                mode: change.mode,
-                value: change.value,
-                reason: change.reason,
-                bounds: change.bounds,
-            }),
-        ];
+        return {
+            transitions: [
+                writeConstrainedValue({
+                    entityId: deref(change.entityId, refs),
+                    key: change.key,
+                    mode: change.mode,
+                    value: change.value,
+                    reason: change.reason,
+                    bounds: change.bounds,
+                }),
+            ],
+        };
     }
     if (change.kind === "transfer") {
         const { from, to } = transferConstrainedValue({
-            fromEntityId: change.fromEntityId,
-            toEntityId: change.toEntityId,
+            fromEntityId: deref(change.fromEntityId, refs),
+            toEntityId: deref(change.toEntityId, refs),
             key: change.key,
             amount: change.amount,
             reason: change.reason,
             fromBounds: change.fromBounds,
             toBounds: change.toBounds,
         });
-        return [from, to];
+        return { transitions: [from, to] };
+    }
+    if (change.kind === "create") {
+        const columns = {};
+        for (const [key, value] of Object.entries(change.columns))
+            columns[key] = derefValue(value, refs);
+        const created = createProjectedEntity({ gameId, entityKind: change.entityKind, columns });
+        refs.set(change.ref, created.entityId);
+        return { created: { ...created, ref: change.ref } };
+    }
+    if (change.kind === "destroy") {
+        return { destroyed: destroyProjectedEntity({ entityId: deref(change.entityId, refs) }) };
     }
     // Unreachable through the exported types (`IntendedChange` is an
     // exhaustive discriminated union), but a mechanic is caller-supplied code
@@ -170,6 +246,8 @@ function resolveProposal(mechanicsByName, proposal) {
     });
     const resolutionId = uuidv4();
     const changes = adjudication.changes ?? [];
+    // 5's precondition: every ref resolves, before the transaction opens.
+    assertRefsResolvable(mechanicName, changes);
     // 5 & 6. Apply every intended change through the one choke point, and
     // record one event -- both inside ONE transaction with the adjudication
     // window nested inside it (adjudication.ts's own doc comment asks for
@@ -180,8 +258,20 @@ function resolveProposal(mechanicsByName, proposal) {
     // is never relabelled as a ResolveProtocolError).
     const applied = withTransaction(() => withAdjudicationOpen(gameId, () => {
         const transitions = [];
+        const sets = [];
+        const created = [];
+        const destroyed = [];
+        const refs = new Map();
         for (const change of changes) {
-            transitions.push(...applyChange(change));
+            const applied = applyChange(change, gameId, refs);
+            if ("transitions" in applied)
+                transitions.push(...applied.transitions);
+            else if ("set" in applied)
+                sets.push(applied.set);
+            else if ("created" in applied)
+                created.push(applied.created);
+            else
+                destroyed.push(applied.destroyed);
         }
         // 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 +296,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, created, destroyed, 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 +310,9 @@ function resolveProposal(mechanicsByName, proposal) {
         t,
         result: adjudication.result ?? {},
         transitions: applied.transitions,
+        sets: applied.sets,
+        created: applied.created,
+        destroyed: applied.destroyed,
         constraint: postConstraint,
         eventId: applied.eventId,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-dmcp",
-  "version": "0.6.0",
+  "version": "0.8.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",