run-dmcp 0.1.0 → 0.3.0

package/dist/tools/relationship.js

@@ -1,6 +1,29 @@
 import { v4 as uuidv4 } from "uuid";
 import { getDatabase, withTransaction } from "../db/connection.js";
 import { validateGameExists } from "./game.js";
+import { writeConstrainedValue, valueHistory } from "../timeline/constrained.js";
+/**
+ * Maps a timeline `ValueTransition` (src/timeline/constrained.ts) onto the
+ * public `RelationshipChange` shape every existing caller of
+ * modifyRelationship()/updateRelationshipValue()/getRelationshipHistory()
+ * already expects. Mirrors transitionToResourceChange() in
+ * src/tools/resource.ts exactly, minus `delta` -- RelationshipChange has no
+ * `delta` field (src/types/index.ts) and never has, so none is invented
+ * here. `id` prefers the annotation event's id, falling back to the fact id
+ * for a transition no constrained write annotated; `timestamp` prefers the
+ * wall-clock `at` the choke point stamped, falling back to the timeline
+ * coordinate `t` for a transition with no wall-clock moment to report.
+ */
+function transitionToRelationshipChange(transition) {
+    return {
+        id: transition.eventId ?? transition.factId ?? "",
+        relationshipId: transition.entityId,
+        previousValue: transition.previousValue,
+        newValue: transition.newValue,
+        reason: transition.reason,
+        timestamp: transition.at ?? String(transition.t),
+    };
+}
 export function createRelationship(params) {
     // Validate game exists to prevent orphaned records
     validateGameExists(params.gameId);
@@ -73,6 +96,19 @@ export function getRelationshipBetween(gameId, sourceId, targetId, relationshipT
         updatedAt: row.updated_at,
     };
 }
+/**
+ * Metadata updater that also accepts a new value, written by a single
+ * direct UPDATE -- deliberately NOT routed through writeConstrainedValue()
+ * (src/timeline/constrained.ts). Its value write therefore lands as an
+ * UNANNOTATED transition in valueHistory()/getRelationshipHistory() below
+ * (reason: null, eventId: null) rather than one a constrained write
+ * stamped -- which is still strictly MORE history than the old
+ * relationship_history table ever held for this path, since nothing wrote
+ * there for a plain updateRelationship() call either. Mirrors
+ * updateResource() in src/tools/resource.ts, whose own value-adjacent write
+ * (re-clamping on a bounds change) is likewise a direct column write, not a
+ * choke-point one.
+ */
 export function updateRelationship(id, updates) {
     const db = getDatabase();
     const current = getRelationship(id);
@@ -97,25 +133,34 @@ export function updateRelationship(id, updates) {
         updatedAt: now,
     };
 }
-function logRelationshipChange(relationshipId, previousValue, newValue, reason) {
-    const db = getDatabase();
-    const id = uuidv4();
-    const now = new Date().toISOString();
-    db.prepare(`
-    INSERT INTO relationship_history (id, relationship_id, previous_value, new_value, reason, timestamp)
-    VALUES (?, ?, ?, ?, ?, ?)
-  `).run(id, relationshipId, previousValue, newValue, reason, now);
-    return {
-        id,
-        relationshipId,
-        previousValue,
-        newValue,
-        reason,
-        timestamp: now,
-    };
-}
+/**
+ * Modify a relationship's value by a delta, with optional bounds. Delegates
+ * the value write entirely to writeConstrainedValue() (src/timeline/
+ * constrained.ts) -- the one choke point every constrained numeric fact key
+ * writes through, mirroring updateResourceValue() in src/tools/resource.ts.
+ * The resolve/check/clamp/write/annotate sequence, and the atomicity of the
+ * write and its audit trail, all live there now.
+ *
+ * Logs unconditionally, including for a zero delta -- exactly as this
+ * function always has. The choke point itself already handles a no-op
+ * write: it opens no new fact (there is nothing to version when the value
+ * doesn't move), but it still writes the annotation event, and
+ * valueHistory()/getRelationshipHistory() below surface that event as a
+ * history row regardless. So a zero-delta call still produces a row with no
+ * extra code here -- see conserved.test.ts's "logged even though nothing
+ * moved" assertions on the resource side of the same mechanism.
+ *
+ * `updated_at` gets its own UPDATE, in the same withTransaction() as the
+ * value write, for the same reason updateRelationshipValue() below writes
+ * its metadata separately: the choke point writes ONE column -- the
+ * constrained fact key -- and nothing else, because a writer that also
+ * touched neighbouring columns would be making policy about them. This
+ * function's `updated_at` bump is that policy, so it stays here, where it
+ * always was. Dropping it would be a silent regression: listRelationships()
+ * orders by `updated_at DESC`, so a relationship modified through this path
+ * would stop sorting as recently touched.
+ */
 export function modifyRelationship(params) {
-    const db = getDatabase();
     const relationship = getRelationship(params.relationshipId);
     if (!relationship)
         return null;
@@ -123,27 +168,23 @@ export function modifyRelationship(params) {
     if (params.minValue !== undefined && params.maxValue !== undefined && params.minValue > params.maxValue) {
         throw new Error(`Invalid bounds: minValue (${params.minValue}) cannot be greater than maxValue (${params.maxValue})`);
     }
-    const previousValue = relationship.value;
-    let newValue = previousValue + params.delta;
-    // Apply bounds (clamp to min first, then max to ensure max takes precedence)
-    if (params.minValue !== undefined) {
-        newValue = Math.max(newValue, params.minValue);
-    }
-    if (params.maxValue !== undefined) {
-        newValue = Math.min(newValue, params.maxValue);
-    }
     const now = new Date().toISOString();
-    // The value update and its history row must land together -- otherwise a
-    // failure between the two leaves a changed relationship value with no
-    // audit trail explaining why it changed.
-    const change = withTransaction(() => {
-        db.prepare(`UPDATE relationships SET value = ?, updated_at = ? WHERE id = ?`)
-            .run(newValue, now, params.relationshipId);
-        return logRelationshipChange(params.relationshipId, previousValue, newValue, params.reason || null);
+    const transition = withTransaction(() => {
+        getDatabase()
+            .prepare(`UPDATE relationships SET updated_at = ? WHERE id = ?`)
+            .run(now, params.relationshipId);
+        return writeConstrainedValue({
+            entityId: params.relationshipId,
+            key: "value",
+            mode: "delta",
+            value: params.delta,
+            reason: params.reason || null,
+            bounds: { minValue: params.minValue ?? null, maxValue: params.maxValue ?? null },
+        });
     });
     return {
-        relationship: { ...relationship, value: newValue, updatedAt: now },
-        change,
+        relationship: { ...relationship, value: transition.newValue, updatedAt: now },
+        change: transitionToRelationshipChange(transition),
     };
 }
 export function deleteRelationship(id) {
@@ -192,27 +233,53 @@ export function listRelationships(gameId, filter) {
         updatedAt: row.updated_at,
     }));
 }
+/**
+ * Every recorded change to a relationship's value, newest first. Built
+ * entirely from the timeline (valueHistory() in src/timeline/
+ * constrained.ts) -- there is no `relationship_history` table backing this
+ * any more (design §5.4 option (C); see the freeze trigger in
+ * src/db/schema.ts). Mirrors getResourceHistory() in src/tools/resource.ts
+ * exactly, and is a strict superset of what `relationship_history` ever
+ * held for the same reason: it also surfaces transitions no constrained
+ * write annotated (e.g. updateRelationship()'s direct column write above),
+ * which the old table simply never recorded.
+ */
 export function getRelationshipHistory(relationshipId, limit) {
-    const db = getDatabase();
-    let query = `SELECT * FROM relationship_history WHERE relationship_id = ? ORDER BY timestamp DESC`;
-    const params = [relationshipId];
-    if (limit) {
-        query += ` LIMIT ?`;
-        params.push(limit);
-    }
-    const rows = db.prepare(query).all(...params);
-    return rows.map(row => ({
-        id: row.id,
-        relationshipId: row.relationship_id,
-        previousValue: row.previous_value,
-        newValue: row.new_value,
-        reason: row.reason,
-        timestamp: row.timestamp,
-    }));
+    return valueHistory(relationshipId, "value", limit).map(transitionToRelationshipChange);
 }
 /**
- * Update a relationship value with optional metadata changes. Supports both direct set and delta modes.
- * Logs to history when value changes.
+ * Update a relationship value with optional metadata changes. Supports both
+ * direct set and delta modes. Logs to history when the value changes; no
+ * history row (and `change: null`) when it doesn't -- that "no-op means no
+ * row" contract is this function's own, distinct from modifyRelationship()
+ * above, which always logs (see its doc comment). The choke point itself
+ * ALWAYS leaves a trace of a write, including a no-op one (an annotation
+ * event with no fact behind it -- see applyLiveWrite() in
+ * src/timeline/constrained.ts), so writeConstrainedValue() below is called
+ * ONLY when newValue !== previousValue -- routing a genuine no-op through it
+ * would put a row in getRelationshipHistory() that this contract says must
+ * not appear.
+ *
+ * `newValue` is computed and clamped here, BEFORE the choke-point call, for
+ * two reasons: first, to make that changed/unchanged decision at all;
+ * second, so the value handed to writeConstrainedValue() (mode: "set") is
+ * already the caller's real intent -- the choke point's own clamp against
+ * the same `bounds` is then a no-op on an already-clamped number, and its
+ * constraint check (assertConstraintsAllow(), src/timeline/constrained.ts)
+ * still sees a real, meaningful intended value rather than a raw delta.
+ *
+ * The metadata columns (relationship_type, label, notes, updated_at) are
+ * written by their own UPDATE, separate from the value write below, but
+ * both run inside one withTransaction() so the whole call is still one
+ * atomic unit -- exactly as before, just as two statements against
+ * `relationships` instead of one. That is a real, visible consequence of
+ * routing the value column through the one choke point every constrained
+ * write goes through: each statement fires the table's own projection
+ * trigger (projection.ts) independently, so a value-changing call now
+ * advances the timeline's `t` twice and logs two `relationship.updated`
+ * events instead of one. One write path for "what did this value used to
+ * be" is worth that -- see constrained.ts's own header comment on why a
+ * second write path is the failure this project keeps rediscovering.
  */
 export function updateRelationshipValue(params) {
     const db = getDatabase();
@@ -242,19 +309,29 @@ export function updateRelationshipValue(params) {
     const newType = params.relationshipType ?? relationship.relationshipType;
     const newLabel = params.label !== undefined ? params.label : relationship.label;
     const newNotes = params.notes ?? relationship.notes;
-    // The value/metadata update and its (conditional) history row must land
-    // together, for the same reason as modifyRelationship() above.
+    const bounds = { minValue: params.minValue ?? null, maxValue: params.maxValue ?? null };
+    // The metadata update and the (conditional) value write must land
+    // together, for the same reason as modifyRelationship() above -- a
+    // failure between the two must never leave a changed value with no
+    // metadata update applied, or vice versa.
     const change = withTransaction(() => {
         db.prepare(`
       UPDATE relationships
-      SET relationship_type = ?, value = ?, label = ?, notes = ?, updated_at = ?
+      SET relationship_type = ?, label = ?, notes = ?, updated_at = ?
       WHERE id = ?
-    `).run(newType, newValue, newLabel, newNotes, now, params.relationshipId);
-        // Log to history if value changed
-        if (newValue !== previousValue) {
-            return logRelationshipChange(params.relationshipId, previousValue, newValue, params.reason || null);
+    `).run(newType, newLabel, newNotes, now, params.relationshipId);
+        if (newValue === previousValue) {
+            return null;
         }
-        return null;
+        const transition = writeConstrainedValue({
+            entityId: params.relationshipId,
+            key: "value",
+            mode: "set",
+            value: newValue,
+            reason: params.reason || null,
+            bounds,
+        });
+        return transitionToRelationshipChange(transition);
     });
     return {
         relationship: {

package/dist/tools/resource.d.ts

@@ -1,7 +1,7 @@
 import type { Resource, ResourceChange } from "../types/index.js";
 export declare function createResource(params: {
     gameId: string;
-    ownerType: "game" | "character";
+    ownerType: "game" | "character" | "faction" | "location";
     ownerId?: string;
     name: string;
     description?: string;
@@ -20,13 +20,21 @@ export declare function updateResource(id: string, updates: {
 }): Resource | null;
 export declare function deleteResource(id: string): boolean;
 export declare function listResources(gameId: string, filter?: {
-    ownerType?: "game" | "character";
+    ownerType?: "game" | "character" | "faction" | "location";
     ownerId?: string;
     category?: string;
 }): Resource[];
 /**
  * Update a resource's value - either by delta or absolute set.
  * Use mode: "delta" to add/subtract, mode: "set" to set an absolute value.
+ *
+ * Delegates entirely to writeConstrainedValue() (src/timeline/constrained.ts)
+ * -- the resolve/check/clamp/write/annotate sequence, and the atomicity of
+ * the write and its audit trail, all live there now. This function's own job
+ * is narrower than it used to be: translate the resource-shaped call into
+ * the generic (entityId, factKey) one, and translate the generic
+ * ValueTransition result back into the Resource/ResourceChange shapes every
+ * existing caller already expects.
  */
 export declare function updateResourceValue(params: {
     resourceId: string;
@@ -40,9 +48,9 @@ export declare function updateResourceValue(params: {
 /**
  * Move `amount` from one resource to another, atomically. This is the ONLY
  * write path for a resource that is a member of a declared 'conserved'
- * constraint -- checkResourceConstraints() (constraint.ts) rejects
- * update_resource_value against such a resource specifically because a
- * single-resource write can't express where the counterpart delta comes
+ * constraint -- assertConstraintsAllow() (src/timeline/constrained.ts)
+ * rejects update_resource_value against such a resource specifically because
+ * a single-resource write can't express where the counterpart delta comes
  * from. This function is that counterpart-carrying write.
  *
  * WHY AN EXPLICIT TRANSFER TOOL, NOT A BALANCED MULTI-RESOURCE WRITE:
@@ -69,15 +77,22 @@ export declare function updateResourceValue(params: {
  * be members of the SAME declared 'conserved' constraint. This is not a
  * general "move value between any two resources" tool -- for anything not
  * under a 'conserved' constraint, update_resource_value remains the right
- * tool (see checkResourceConstraints()). Keeping the two write paths
- * mutually exclusive per resource means which one to use is never
- * ambiguous.
+ * tool (see assertConstraintsAllow() in src/timeline/constrained.ts). Keeping
+ * the two write paths mutually exclusive per resource means which one to use
+ * is never ambiguous.
  *
  * Never clamps. Clamping one side of a transfer would apply an uneven delta
  * -- the source would lose less (or the destination gain less) than the
  * other side moved by, silently creating or destroying value -- so any
  * bound violation on either side rejects the whole transfer instead,
  * regardless of whether a 'bounded' constraint is separately declared.
+ *
+ * Keeps its own argument validation (self-transfer, non-finite, negative,
+ * not-found) -- that is about resource IDENTITY, not about the declared
+ * constraint family, so it stays here rather than moving into
+ * transferConstrainedValue() (src/timeline/constrained.ts), which delegates
+ * the actual membership check, the bounded/monotonic checks, the never-clamp
+ * bounds rejection, and both atomic writes.
  */
 export declare function transferResourceValue(params: {
     fromResourceId: string;
@@ -90,4 +105,14 @@ export declare function transferResourceValue(params: {
     fromChange: ResourceChange;
     toChange: ResourceChange;
 };
+/**
+ * Every recorded change to a resource's value, newest first. Built entirely
+ * from the timeline (valueHistory() in src/timeline/constrained.ts) -- there
+ * is no `resource_history` table backing this any more (design §5.4 option
+ * (C); see the freeze trigger in src/db/schema.ts). This is a strict
+ * superset of what `resource_history` ever held: it also surfaces
+ * transitions no constrained write annotated (a direct column write, a
+ * bounds re-clamp, a startup reconciliation), which the old table simply
+ * never recorded.
+ */
 export declare function getResourceHistory(resourceId: string, limit?: number): ResourceChange[];