run-dmcp 0.1.0 → 0.2.0

package/dist/tools/constraint.js

@@ -2,6 +2,11 @@ import { v4 as uuidv4 } from "uuid";
 import { getDatabase } from "../db/connection.js";
 import { validateGameExists } from "./game.js";
 import { getResource } from "./resource.js";
+import { ConstraintViolationError, CONSERVED_SUM_EPSILON, constraintsFor, allConstraintsForEntity, rowToConstraint, } from "../timeline/registry.js";
+// Re-exported so every existing importer (src/tools/resource.ts,
+// src/register/resources.ts) keeps working unchanged -- these two now live
+// in src/timeline/registry.js; see the paragraph below on why.
+export { ConstraintViolationError, CONSERVED_SUM_EPSILON };
 /**
  * Declarative, opt-in, server-enforced invariants on `resources` rows.
  *
@@ -22,52 +27,56 @@ import { getResource } from "./resource.js";
  *
  * 'conserved' is fully enforced: a resource that is a member of a declared
  * 'conserved' constraint can no longer be written directly through
- * update_resource_value (see checkResourceConstraints() below) -- it must go
- * through transferResourceValue() in resource.ts, which moves value between
- * exactly two members of the same set atomically. See the comment on
- * transferResourceValue() for why an explicit transfer, rather than a
- * balanced multi-resource write, was chosen.
+ * update_resource_value (see assertConstraintsAllow() in
+ * src/timeline/constrained.ts) -- it must go through transferResourceValue()
+ * in resource.ts, which moves value between exactly two members of the same
+ * set atomically. See the comment on transferResourceValue() for why an
+ * explicit transfer, rather than a balanced multi-resource write, was
+ * chosen.
+ *
+ * `resolve_only` (design §5.3, §5.2a; issue #13) is this family's fourth
+ * ROW-based member, alongside `bounded`/`monotonic`/`conserved`: every
+ * direct write to the fact key it governs is refused, so the value can move
+ * only through the adjudicating call issue #10's resolver will open (the
+ * window mechanism, `src/timeline/adjudication.ts`, lands here first --
+ * "a value that may move only through adjudication needs the adjudicator to
+ * exist first," design §5.3). Unlike the other three, it takes an explicit
+ * `factKey` parameter rather than always governing `'value'` -- see
+ * declareResolveOnlyConstraint() below.
+ *
+ * `irreversible` (design §5.3) is this family's FIFTH member and its only
+ * temporal, non-row one -- `bounded`/`monotonic` constrain a value's range
+ * and direction, 'conserved' constrains a set's total, 'resolve_only'
+ * constrains WHO may write a value, and `irreversible` constrains what may
+ * be asserted about a value after a point in time. It is declared per-FACT
+ * (src/timeline/irreversible.ts's declareIrreversible()), not as a row in
+ * `resource_constraints` here, and enforced by triggers on the timeline's
+ * `facts` table (src/timeline/schema.ts) rather than by
+ * assertConstraintsAllow(). The two families still live on different
+ * substrates -- this one on `resources`/`resource_constraints`, that one on
+ * the timeline's interval-versioned `facts`.
+ *
+ * Design §5.4's option (C) merge (Phase 3) is complete for `bounded`/
+ * `monotonic`/`conserved`/`resolve_only`: this file declares constraints
+ * (insertConstraint and the declare*() functions below) and reads them back
+ * for display (listConstraints/getConstraintsForResource); EVALUATING a
+ * declared constraint against an intended value change happens in exactly
+ * one place, assertConstraintsAllow() (src/timeline/constrained.ts), which
+ * every constrained write (writeConstrainedValue/transferConstrainedValue,
+ * and through them updateResourceValue/transferResourceValue/updateResource
+ * in resource.ts) goes through. Nothing in this file evaluates a constraint
+ * against a value any more -- grep for `constraint.kind === "bounded"` or
+ * `constraint.direction ===` and constrained.ts is the only hit outside a
+ * test. 'resolve_only' has no value-shape to evaluate (no bounds, no
+ * direction, no total) -- what constrained.ts checks for it is WHETHER an
+ * adjudication window is open (src/timeline/adjudication.ts), not anything
+ * about the intended value itself.
  */
-/** Absolute tolerance for floating-point sum comparisons on 'conserved'
- * constraints. IEEE 754 doubles cannot represent values like 0.1 exactly,
- * so repeated addition/subtraction across many transfers can drift by a
- * few ULPs. This is large enough to absorb that drift over realistic
- * transfer volumes while still catching an actual logic bug (which would
- * typically desync the sum by a whole `amount`, not a fraction of one). */
-export const CONSERVED_SUM_EPSILON = 1e-6;
-export class ConstraintViolationError extends Error {
-    constraintKind;
-    resourceId;
-    constructor(constraintKind, resourceId, message) {
-        super(message);
-        this.constraintKind = constraintKind;
-        this.resourceId = resourceId;
-        this.name = "ConstraintViolationError";
-    }
-}
-function memberIdsFor(constraintId) {
-    const db = getDatabase();
-    const rows = db
-        .prepare(`SELECT resource_id FROM resource_constraint_members WHERE constraint_id = ? ORDER BY rowid`)
-        .all(constraintId);
-    return rows.map((r) => r.resource_id);
-}
-function rowToConstraint(row) {
-    return {
-        id: row.id,
-        gameId: row.game_id,
-        kind: row.kind,
-        resourceIds: memberIdsFor(row.id),
-        direction: row.direction,
-        total: row.total,
-        createdAt: row.created_at,
-    };
-}
-function insertConstraint(gameId, kind, resourceIds, direction, total) {
+function insertConstraint(gameId, kind, resourceIds, direction, total, factKey = "value") {
     const db = getDatabase();
     const id = uuidv4();
     const now = new Date().toISOString();
-    db.prepare(`INSERT INTO resource_constraints (id, game_id, kind, direction, total, created_at) VALUES (?, ?, ?, ?, ?, ?)`).run(id, gameId, kind, direction, total, now);
+    db.prepare(`INSERT INTO resource_constraints (id, game_id, kind, direction, total, fact_key, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, gameId, kind, direction, total, factKey, now);
     const memberStmt = db.prepare(`INSERT INTO resource_constraint_members (constraint_id, resource_id) VALUES (?, ?)`);
     for (const resourceId of resourceIds) {
         memberStmt.run(id, resourceId);
@@ -79,6 +88,7 @@ function insertConstraint(gameId, kind, resourceIds, direction, total) {
         resourceIds,
         direction,
         total,
+        factKey,
         createdAt: now,
     };
 }
@@ -86,7 +96,8 @@ function insertConstraint(gameId, kind, resourceIds, direction, total) {
  * Declare a 'bounded' constraint: the resource's value must stay within its
  * existing minValue/maxValue (set via create_resource/update_resource).
  * Once declared, out-of-bounds writes through updateResourceValue() are
- * REJECTED instead of silently clamped -- see checkResourceConstraints().
+ * REJECTED instead of silently clamped -- see assertConstraintsAllow()
+ * (src/timeline/constrained.ts).
  */
 export function declareBoundedConstraint(params) {
     validateGameExists(params.gameId);
@@ -99,10 +110,10 @@ export function declareBoundedConstraint(params) {
             `A 'bounded' constraint enforces those bounds by rejecting instead of clamping -- ` +
             `set at least one bound with update_resource before declaring this constraint.`);
     }
-    if (getConstraintsForResource(params.resourceId).some((c) => c.kind === "bounded")) {
+    if (constraintsFor(params.resourceId, "value").some((c) => c.kind === "bounded")) {
         throw new Error(`Resource '${params.resourceId}' already has a 'bounded' constraint.`);
     }
-    return insertConstraint(params.gameId, "bounded", [params.resourceId], null, null);
+    return insertConstraint(params.gameId, "bounded", [params.resourceId], null, null, "value");
 }
 /**
  * Declare a 'monotonic' constraint: the resource's value may only move in
@@ -116,10 +127,53 @@ export function declareMonotonicConstraint(params) {
     if (!resource) {
         throw new Error(`Resource '${params.resourceId}' not found.`);
     }
-    if (getConstraintsForResource(params.resourceId).some((c) => c.kind === "monotonic")) {
+    if (constraintsFor(params.resourceId, "value").some((c) => c.kind === "monotonic")) {
         throw new Error(`Resource '${params.resourceId}' already has a 'monotonic' constraint.`);
     }
-    return insertConstraint(params.gameId, "monotonic", [params.resourceId], params.direction, null);
+    return insertConstraint(params.gameId, "monotonic", [params.resourceId], params.direction, null, "value");
+}
+/**
+ * Declare a 'resolve_only' constraint (design §5.3, §5.2a; issue #13): every
+ * direct write to `factKey` on `resourceId` is refused --
+ * assertConstraintsAllow() (src/timeline/constrained.ts) rejects it whether
+ * it arrives through writeConstrainedValue OR transferConstrainedValue --
+ * unless made while an adjudication window is open
+ * (src/timeline/adjudication.ts's `withAdjudicationOpen`). The window is the
+ * mechanism this issue builds; the resolver that OPENS it (issue #10) is a
+ * separate, not-yet-built caller, and this function does not know or care
+ * what that caller will look like.
+ *
+ * `factKey` is optional and defaults to `'value'`, matching every other
+ * declare*Constraint() function's implicit scope -- but, unlike those,
+ * 'resolve_only' takes it as a REAL parameter rather than hardcoding it,
+ * because it is designed to guard a fact key a caller chooses, not only the
+ * one numeric column `resources` happens to expose today (design §5.4
+ * option (C)'s eventual generalization; see `factKey`'s doc comment on
+ * `ResourceConstraint`, src/types/index.ts).
+ *
+ * Validation mirrors declareBoundedConstraint()/declareMonotonicConstraint()
+ * exactly: the game and resource must exist, and re-declaring the same
+ * (resourceId, factKey) pair is rejected rather than silently accepted --
+ * scoped by factKey, not just resourceId, because that is the one thing
+ * that makes 'resolve_only' different from its two row-based siblings: two
+ * DIFFERENT fact keys on the same resource are two independent declarations,
+ * never a duplicate of each other.
+ *
+ * No shape prerequisite the way 'bounded' requires a min/max or 'monotonic'
+ * requires a direction -- 'resolve_only' constrains WHO may write, not what
+ * shape the value must take, so there is nothing else to validate.
+ */
+export function declareResolveOnlyConstraint(params) {
+    validateGameExists(params.gameId);
+    const resource = getResource(params.resourceId);
+    if (!resource) {
+        throw new Error(`Resource '${params.resourceId}' not found.`);
+    }
+    const factKey = params.factKey ?? "value";
+    if (constraintsFor(params.resourceId, factKey).some((c) => c.kind === "resolve_only")) {
+        throw new Error(`Resource '${params.resourceId}' already has a 'resolve_only' constraint on fact key '${factKey}'.`);
+    }
+    return insertConstraint(params.gameId, "resolve_only", [params.resourceId], null, null, factKey);
 }
 /**
  * Register a 'conserved' constraint: a set of resources that must always
@@ -158,7 +212,7 @@ export function declareConservedConstraint(params) {
         if (!resource) {
             throw new Error(`Resource '${resourceId}' not found.`);
         }
-        if (getConstraintsForResource(resourceId).some((c) => c.kind === "conserved")) {
+        if (constraintsFor(resourceId, "value").some((c) => c.kind === "conserved")) {
             throw new Error(`Resource '${resourceId}' already belongs to a 'conserved' constraint. A resource may only be a ` +
                 `member of one 'conserved' set at a time -- remove the existing constraint first (remove_resource_constraint) ` +
                 `if you need to redefine the set it belongs to.`);
@@ -171,7 +225,7 @@ export function declareConservedConstraint(params) {
             `update_resource_value, before declaring the constraint) or the declared total so they already match -- ` +
             `declaring this constraint does not rewrite resource values to make a mismatched total true.`);
     }
-    return insertConstraint(params.gameId, "conserved", uniqueIds, null, params.total);
+    return insertConstraint(params.gameId, "conserved", uniqueIds, null, params.total, "value");
 }
 /** List constraints for a game, optionally filtered to ones governing a given resource. */
 export function listConstraints(gameId, resourceId) {
@@ -184,16 +238,11 @@ export function listConstraints(gameId, resourceId) {
         return constraints;
     return constraints.filter((c) => c.resourceIds.includes(resourceId));
 }
-/** All constraints (of any kind) that govern the given resource. */
+/** All constraints (of any kind, any fact key) that govern the given
+ * resource. Delegates to the registry's allConstraintsForEntity() rather
+ * than writing its own JOIN -- see src/timeline/registry.ts. */
 export function getConstraintsForResource(resourceId) {
-    const db = getDatabase();
-    const rows = db
-        .prepare(`SELECT rc.* FROM resource_constraints rc
-       JOIN resource_constraint_members rcm ON rcm.constraint_id = rc.id
-       WHERE rcm.resource_id = ?
-       ORDER BY rc.created_at`)
-        .all(resourceId);
-    return rows.map(rowToConstraint);
+    return allConstraintsForEntity(resourceId);
 }
 /** Remove a constraint by id. Returns true if a row was deleted. */
 export function removeConstraint(id) {
@@ -201,69 +250,11 @@ export function removeConstraint(id) {
     const result = db.prepare(`DELETE FROM resource_constraints WHERE id = ?`).run(id);
     return result.changes > 0;
 }
-/**
- * Check whether an intended value change for a single resource would
- * violate any 'bounded' or 'monotonic' constraint declared on it. Throws
- * ConstraintViolationError on violation; returns void otherwise. Shared by
- * checkResourceConstraints() (the single-resource write path) and
- * transferResourceValue() (resource.ts; the two-resource conserved-transfer
- * path) -- both paths must respect 'bounded'/'monotonic' the same way.
- * Deliberately does not look at 'conserved' constraints; callers decide
- * separately what to do about those (see checkResourceConstraints() below
- * and transferResourceValue()).
- */
-export function checkBoundedAndMonotonicConstraints(resourceId, previousValue, intendedValue, bounds) {
-    const constraints = getConstraintsForResource(resourceId);
-    for (const constraint of constraints) {
-        if (constraint.kind === "monotonic") {
-            if (constraint.direction === "increasing" && intendedValue < previousValue) {
-                throw new ConstraintViolationError("monotonic", resourceId, `Resource '${resourceId}' is constrained to never decrease; rejected change from ${previousValue} to ${intendedValue}.`);
-            }
-            if (constraint.direction === "decreasing" && intendedValue > previousValue) {
-                throw new ConstraintViolationError("monotonic", resourceId, `Resource '${resourceId}' is constrained to never increase; rejected change from ${previousValue} to ${intendedValue}.`);
-            }
-        }
-        if (constraint.kind === "bounded") {
-            if (bounds.minValue !== null && intendedValue < bounds.minValue) {
-                throw new ConstraintViolationError("bounded", resourceId, `Resource '${resourceId}' is bounded-constrained (min ${bounds.minValue}); rejected value ${intendedValue} instead of clamping.`);
-            }
-            if (bounds.maxValue !== null && intendedValue > bounds.maxValue) {
-                throw new ConstraintViolationError("bounded", resourceId, `Resource '${resourceId}' is bounded-constrained (max ${bounds.maxValue}); rejected value ${intendedValue} instead of clamping.`);
-            }
-        }
-        // constraint.kind === "conserved": handled by callers, not here.
-    }
-}
-/**
- * Check whether an intended value change for a single resource would
- * violate any constraint declared on it. Throws ConstraintViolationError on
- * violation; returns void otherwise. Called from updateResourceValue() in
- * resource.ts before the row is written.
- *
- * 'conserved' is handled specially here: ANY direct single-resource write to
- * a conserved member is rejected, unconditionally, regardless of whether the
- * particular delta would happen to preserve the total. The server cannot
- * know where update_resource_value's counterpart delta should come from --
- * writing one member without atomically adjusting another would silently
- * break the set's invariant, which is exactly the failure this constraint
- * exists to prevent. Use transfer_resource_value (transferResourceValue() in
- * resource.ts) instead, which moves value between two members of the same
- * set atomically.
- */
-export function checkResourceConstraints(resourceId, previousValue, intendedValue, bounds) {
-    const constraints = getConstraintsForResource(resourceId);
-    checkBoundedAndMonotonicConstraints(resourceId, previousValue, intendedValue, bounds);
-    const conserved = constraints.find((c) => c.kind === "conserved");
-    if (conserved) {
-        throw new ConstraintViolationError("conserved", resourceId, `Resource '${resourceId}' is a member of a 'conserved' constraint (id '${conserved.id}', total ${conserved.total}) ` +
-            `and cannot be written directly via update_resource_value -- a single-resource write is ambiguous about where ` +
-            `the counterpart delta should come from, and could silently break the set's total. Use transfer_resource_value ` +
-            `to move value between two members of this set atomically instead.`);
-    }
-}
-/** All conserved constraints (of kind 'conserved') governing a resource,
- * i.e. zero or one (declareConservedConstraint() rejects overlapping
- * conserved membership, so a resource can belong to at most one). */
-export function getConservedConstraintFor(resourceId) {
-    return getConstraintsForResource(resourceId).find((c) => c.kind === "conserved") ?? null;
-}
+// `getConservedConstraintFor(resourceId)` used to live here, unscoped by fact
+// key. Its callers (deleteResource/updateResource in src/tools/resource.ts)
+// now use `conservedConstraintFor(entityId, factKey)` from
+// src/timeline/registry.ts instead, and the unscoped version was left with no
+// caller at all. Deleted rather than kept: a key-blind lookup surviving beside
+// the key-scoped one is exactly the shape a future write reaches for by
+// accident, and it would silently find a constraint governing a different
+// fact key than the one being written.

package/dist/tools/relationship.d.ts

@@ -12,12 +12,52 @@ export declare function createRelationship(params: {
 }): Relationship;
 export declare function getRelationship(id: string): Relationship | null;
 export declare function getRelationshipBetween(gameId: string, sourceId: string, targetId: string, relationshipType?: string): Relationship | null;
+/**
+ * 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 declare function updateRelationship(id: string, updates: {
     relationshipType?: string;
     value?: number;
     label?: string | null;
     notes?: string;
 }): Relationship | null;
+/**
+ * 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 declare function modifyRelationship(params: {
     relationshipId: string;
     delta: number;
@@ -36,10 +76,51 @@ export declare function listRelationships(gameId: string, filter?: {
     relationshipType?: string;
     entityType?: string;
 }): Relationship[];
+/**
+ * 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 declare function getRelationshipHistory(relationshipId: string, limit?: number): RelationshipChange[];
 /**
- * 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 declare function updateRelationshipValue(params: {
     relationshipId: string;