run-dmcp 0.1.0 → 0.2.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

@@ -27,6 +27,14 @@ export declare function listResources(gameId: string, filter?: {
 /**
  * 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[];

package/dist/tools/resource.js

@@ -1,7 +1,8 @@
 import { v4 as uuidv4 } from "uuid";
-import { getDatabase, withTransaction } from "../db/connection.js";
+import { getDatabase } from "../db/connection.js";
 import { validateGameExists } from "./game.js";
-import { checkResourceConstraints, checkBoundedAndMonotonicConstraints, getConservedConstraintFor, ConstraintViolationError, CONSERVED_SUM_EPSILON, } from "./constraint.js";
+import { ConstraintViolationError, conservedConstraintFor } from "../timeline/registry.js";
+import { assertConstraintsAllow, writeConstrainedValue, transferConstrainedValue, valueHistory, } from "../timeline/constrained.js";
 function clampValue(value, minValue, maxValue) {
     let result = value;
     if (minValue !== null)
@@ -11,24 +12,27 @@ function clampValue(value, minValue, maxValue) {
     return result;
 }
 /**
- * Reject (never clamp) a transfer leg that would push `resource` outside
- * its own minValue/maxValue. Used only by transferResourceValue() -- see
- * the doc comment there for why a transfer never clamps, even when the
- * resource has no separately-declared 'bounded' constraint.
+ * Maps a timeline `ValueTransition` (src/timeline/constrained.ts) onto the
+ * public `ResourceChange` shape every existing caller of
+ * updateResourceValue()/transferResourceValue()/getResourceHistory() already
+ * expects. `id` prefers the annotation event's id, falling back to the fact
+ * id for a transition no constrained write annotated (a direct column
+ * write, a bounds re-clamp, a startup reconciliation) -- either is a real,
+ * unique identifier for the row, and a transition can never lack both.
+ * `timestamp` prefers the wall-clock `at` the choke point stamped; an
+ * unannotated transition has no wall-clock moment to report, so its
+ * timeline coordinate `t` is the honest answer instead of inventing one.
  */
-function assertWithinBoundsForTransfer(resource, intendedValue, role) {
-    if (resource.minValue !== null && intendedValue < resource.minValue) {
-        throw new ConstraintViolationError("conserved", resource.id, `Transfer rejected: '${resource.name}' (${resource.id}) would go below its minimum value ` +
-            `(${resource.minValue}) as the ${role} of this transfer. transfer_resource_value never clamps -- ` +
-            `clamping one side of a transfer would apply an uneven delta and silently create or destroy value. ` +
-            `Choose a smaller amount.`);
-    }
-    if (resource.maxValue !== null && intendedValue > resource.maxValue) {
-        throw new ConstraintViolationError("conserved", resource.id, `Transfer rejected: '${resource.name}' (${resource.id}) would exceed its maximum value ` +
-            `(${resource.maxValue}) as the ${role} of this transfer. transfer_resource_value never clamps -- ` +
-            `clamping one side of a transfer would apply an uneven delta and silently create or destroy value. ` +
-            `Choose a smaller amount.`);
-    }
+function transitionToResourceChange(transition) {
+    return {
+        id: transition.eventId ?? transition.factId ?? "",
+        resourceId: transition.entityId,
+        previousValue: transition.previousValue,
+        newValue: transition.newValue,
+        delta: transition.delta,
+        reason: transition.reason,
+        timestamp: transition.at ?? String(transition.t),
+    };
 }
 export function createResource(params) {
     // Validate game exists to prevent orphaned records
@@ -98,14 +102,28 @@ export function updateResource(id, updates) {
     // its own -- silently, with no counterpart adjustment -- which is exactly
     // the kind of isolated write that breaks the set's total. Reject instead;
     // the caller can still change bounds that don't affect the current value.
+    //
+    // Routed through assertConstraintsAllow() (src/timeline/constrained.ts) --
+    // the single site the whole constraint family (monotonic/bounded/conserved)
+    // is evaluated -- rather than throwing directly, so this is not a second
+    // place the 'conserved' rule is written down. `context` carries this
+    // guard's own explanation so the thrown message still names update_resource
+    // (what this caller actually did), not a generic mention of
+    // update_resource_value. No `bounds` is passed: this call is not itself
+    // testing this resource's own min/max against a declared 'bounded'
+    // constraint (updateResourceValue does that); it exists only to refuse an
+    // isolated conserved-member value change.
     if (newValue !== current.value) {
-        const conserved = getConservedConstraintFor(id);
-        if (conserved) {
-            throw new ConstraintViolationError("conserved", id, `Resource '${id}' is a member of a 'conserved' constraint (id '${conserved.id}', total ${conserved.total}) ` +
-                `and its value cannot be changed by update_resource, including indirectly by narrowing minValue/maxValue ` +
+        assertConstraintsAllow({
+            entityId: id,
+            key: "value",
+            previousValue: current.value,
+            intendedValue: newValue,
+            conservedMemberWrite: "reject",
+            context: `and its value cannot be changed by update_resource, including indirectly by narrowing minValue/maxValue ` +
                 `so the current value would be reclamped. Rejected instead of silently changing the value -- use ` +
-                `transfer_resource_value if the value itself needs to move, or choose bounds that don't affect the current value.`);
-        }
+                `transfer_resource_value if the value itself needs to move, or choose bounds that don't affect the current value.`,
+        });
     }
     const stmt = db.prepare(`
     UPDATE resources
@@ -129,7 +147,12 @@ export function deleteResource(id) {
     // CASCADE on resource_constraint_members, would silently remove it from
     // the set rather than raise any error). Reject instead: the caller must
     // remove_resource_constraint first if the set itself is being redefined.
-    const conserved = getConservedConstraintFor(id);
+    //
+    // This is not a value-change check -- deleting a resource doesn't move
+    // any number -- so it reads the registry directly (conservedConstraintFor,
+    // key-scoped to 'value') rather than going through assertConstraintsAllow,
+    // which exists to evaluate an INTENDED value change.
+    const conserved = conservedConstraintFor(id, "value");
     if (conserved) {
         throw new ConstraintViolationError("conserved", id, `Resource '${id}' is a member of a 'conserved' constraint (id '${conserved.id}', total ${conserved.total}) ` +
             `and cannot be deleted while that constraint exists -- deleting it would shrink the set below its declared ` +
@@ -174,66 +197,41 @@ export function listResources(gameId, filter) {
         createdAt: row.created_at,
     }));
 }
-function logChange(resourceId, previousValue, newValue, reason) {
-    const db = getDatabase();
-    const id = uuidv4();
-    const now = new Date().toISOString();
-    const delta = newValue - previousValue;
-    const stmt = db.prepare(`
-    INSERT INTO resource_history (id, resource_id, previous_value, new_value, delta, reason, timestamp)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-  `);
-    stmt.run(id, resourceId, previousValue, newValue, delta, reason, now);
-    return {
-        id,
-        resourceId,
-        previousValue,
-        newValue,
-        delta,
-        reason,
-        timestamp: now,
-    };
-}
 /**
  * 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 function updateResourceValue(params) {
     const resource = getResource(params.resourceId);
     if (!resource)
         return null;
-    const previousValue = resource.value;
-    const intendedValue = params.mode === "delta" ? previousValue + params.value : params.value;
-    // Opt-in constraint enforcement: throws ConstraintViolationError and
-    // leaves the row untouched if this resource has a declared 'bounded' or
-    // 'monotonic' constraint that `intendedValue` would violate. Resources
-    // with no declared constraint are unaffected by this call and fall
-    // through to the existing clamp behavior below, unchanged.
-    checkResourceConstraints(params.resourceId, previousValue, intendedValue, {
-        minValue: resource.minValue,
-        maxValue: resource.maxValue,
-    });
-    const newValue = clampValue(intendedValue, resource.minValue, resource.maxValue);
-    // The value update and its resource_history row must land together --
-    // otherwise a failure between the two leaves a changed value with no
-    // audit trail explaining why it changed.
-    const change = withTransaction(() => {
-        const db = getDatabase();
-        const stmt = db.prepare(`UPDATE resources SET value = ? WHERE id = ?`);
-        stmt.run(newValue, params.resourceId);
-        return logChange(params.resourceId, previousValue, newValue, params.reason || null);
+    const transition = writeConstrainedValue({
+        entityId: params.resourceId,
+        key: "value",
+        mode: params.mode,
+        value: params.value,
+        reason: params.reason ?? null,
+        bounds: { minValue: resource.minValue, maxValue: resource.maxValue },
     });
     return {
-        resource: { ...resource, value: newValue },
-        change,
+        resource: { ...resource, value: transition.newValue },
+        change: transitionToResourceChange(transition),
     };
 }
 /**
  * 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:
@@ -260,15 +258,22 @@ export 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 function transferResourceValue(params) {
     if (params.fromResourceId === params.toResourceId) {
@@ -289,86 +294,34 @@ export function transferResourceValue(params) {
     if (!to) {
         throw new Error(`Resource '${params.toResourceId}' not found.`);
     }
-    const fromConstraint = getConservedConstraintFor(from.id);
-    const toConstraint = getConservedConstraintFor(to.id);
-    if (!fromConstraint || !toConstraint || fromConstraint.id !== toConstraint.id) {
-        const details = [];
-        if (!fromConstraint)
-            details.push(`'${from.name}' (${from.id}) is not a member of any 'conserved' constraint.`);
-        if (!toConstraint)
-            details.push(`'${to.name}' (${to.id}) is not a member of any 'conserved' constraint.`);
-        if (fromConstraint && toConstraint && fromConstraint.id !== toConstraint.id) {
-            details.push(`They belong to different 'conserved' constraints ('${fromConstraint.id}' and '${toConstraint.id}').`);
-        }
-        throw new ConstraintViolationError("conserved", from.id, `transfer_resource_value requires fromResourceId and toResourceId to both be members of the same declared ` +
-            `'conserved' constraint -- moving value between resources outside a shared conserved set would change ` +
-            `each side's total independently, which is what update_resource_value is for. ${details.join(" ")}`);
-    }
-    const fromPrev = from.value;
-    const toPrev = to.value;
-    const fromIntended = fromPrev - params.amount;
-    const toIntended = toPrev + params.amount;
-    // Bounded/monotonic constraints, if separately declared, apply during a
-    // transfer exactly as they do during a direct write.
-    checkBoundedAndMonotonicConstraints(from.id, fromPrev, fromIntended, {
-        minValue: from.minValue,
-        maxValue: from.maxValue,
-    });
-    checkBoundedAndMonotonicConstraints(to.id, toPrev, toIntended, {
-        minValue: to.minValue,
-        maxValue: to.maxValue,
-    });
-    // Never clamp (see doc comment above): reject outright if either side's
-    // own minValue/maxValue would be violated, even without a declared
-    // 'bounded' constraint.
-    assertWithinBoundsForTransfer(from, fromIntended, "source");
-    assertWithinBoundsForTransfer(to, toIntended, "destination");
-    const reason = params.reason || null;
-    const constraintId = fromConstraint.id;
-    const declaredTotal = fromConstraint.total ?? 0;
-    const memberIds = fromConstraint.resourceIds;
-    return withTransaction(() => {
-        const db = getDatabase();
-        db.prepare(`UPDATE resources SET value = ? WHERE id = ?`).run(fromIntended, from.id);
-        db.prepare(`UPDATE resources SET value = ? WHERE id = ?`).run(toIntended, to.id);
-        const fromChange = logChange(from.id, fromPrev, fromIntended, reason);
-        const toChange = logChange(to.id, toPrev, toIntended, reason);
-        // Defense in depth: re-read every member of the set (inside this same
-        // transaction, so this sees the writes above) and assert it still sums
-        // to the declared total. The primary guarantee is structural (an equal
-        // and opposite delta, above) -- this turns any future bug in this
-        // function, or a schema change that opens another write path around it,
-        // into a loud rollback instead of a silently wrong total.
-        const currentSum = memberIds.reduce((sum, id) => sum + (getResource(id)?.value ?? 0), 0);
-        if (Math.abs(currentSum - declaredTotal) > CONSERVED_SUM_EPSILON) {
-            throw new Error(`Invariant check failed after transfer: conserved constraint '${constraintId}' members now sum to ` +
-                `${currentSum}, expected ${declaredTotal}. Rolling back.`);
-        }
-        return {
-            from: { ...from, value: fromIntended },
-            to: { ...to, value: toIntended },
-            fromChange,
-            toChange,
-        };
+    const { from: fromTransition, to: toTransition } = transferConstrainedValue({
+        fromEntityId: from.id,
+        toEntityId: to.id,
+        key: "value",
+        amount: params.amount,
+        reason: params.reason ?? null,
+        fromBounds: { minValue: from.minValue, maxValue: from.maxValue },
+        toBounds: { minValue: to.minValue, maxValue: to.maxValue },
+        fromLabel: from.name,
+        toLabel: to.name,
     });
+    return {
+        from: { ...from, value: fromTransition.newValue },
+        to: { ...to, value: toTransition.newValue },
+        fromChange: transitionToResourceChange(fromTransition),
+        toChange: transitionToResourceChange(toTransition),
+    };
 }
+/**
+ * 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 function getResourceHistory(resourceId, limit) {
-    const db = getDatabase();
-    let query = `SELECT * FROM resource_history WHERE resource_id = ? ORDER BY timestamp DESC`;
-    const params = [resourceId];
-    if (limit !== undefined) {
-        query += ` LIMIT ?`;
-        params.push(limit);
-    }
-    const stmt = db.prepare(query);
-    const rows = stmt.all(...params);
-    return rows.map((row) => ({
-        id: row.id,
-        resourceId: row.resource_id,
-        previousValue: row.previous_value,
-        newValue: row.new_value,
-        delta: row.delta,
-        reason: row.reason,
-        timestamp: row.timestamp,
-    }));
+    return valueHistory(resourceId, "value", limit).map(transitionToResourceChange);
 }