run-dmcp 0.1.0

package/dist/tools/__tests__/constraint.test.js

@@ -0,0 +1,212 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createTestDb, destroyTestDb } from "../../db/__tests__/testDb.js";
+import { createGame } from "../game.js";
+import { createResource } from "../resource.js";
+import { declareBoundedConstraint, declareMonotonicConstraint, declareConservedConstraint, listConstraints, getConstraintsForResource, removeConstraint, } from "../constraint.js";
+describe("resource constraint registry", () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: "Test Game", setting: "test", style: "test" }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    describe("bounded", () => {
+        it("declares a bounded constraint on a resource that has min/max set", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 50,
+                minValue: 0,
+                maxValue: 100,
+            });
+            const constraint = declareBoundedConstraint({ gameId, resourceId: resource.id });
+            expect(constraint.kind).toBe("bounded");
+            expect(constraint.gameId).toBe(gameId);
+            expect(constraint.resourceIds).toEqual([resource.id]);
+            expect(constraint.id).toBeTruthy();
+            expect(constraint.createdAt).toBeTruthy();
+        });
+        it("rejects declaring a bounded constraint on a resource with no bounds", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "grain", value: 50 });
+            expect(() => declareBoundedConstraint({ gameId, resourceId: resource.id })).toThrow();
+        });
+        it("rejects declaring a second bounded constraint on the same resource", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 50,
+                minValue: 0,
+                maxValue: 100,
+            });
+            declareBoundedConstraint({ gameId, resourceId: resource.id });
+            expect(() => declareBoundedConstraint({ gameId, resourceId: resource.id })).toThrow();
+        });
+        it("rejects declaring a constraint on a nonexistent resource", () => {
+            expect(() => declareBoundedConstraint({ gameId, resourceId: "does-not-exist" })).toThrow();
+        });
+    });
+    describe("monotonic", () => {
+        it("declares a never-decreasing (increasing) constraint", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "population", value: 10 });
+            const constraint = declareMonotonicConstraint({
+                gameId,
+                resourceId: resource.id,
+                direction: "increasing",
+            });
+            expect(constraint.kind).toBe("monotonic");
+            expect(constraint.direction).toBe("increasing");
+            expect(constraint.resourceIds).toEqual([resource.id]);
+        });
+        it("declares a never-increasing (decreasing) constraint", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "treasury_debt", value: 10 });
+            const constraint = declareMonotonicConstraint({
+                gameId,
+                resourceId: resource.id,
+                direction: "decreasing",
+            });
+            expect(constraint.direction).toBe("decreasing");
+        });
+        it("rejects a second monotonic constraint on the same resource", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "population", value: 10 });
+            declareMonotonicConstraint({ gameId, resourceId: resource.id, direction: "increasing" });
+            expect(() => declareMonotonicConstraint({ gameId, resourceId: resource.id, direction: "decreasing" })).toThrow();
+        });
+    });
+    // Full enforcement (transfer_resource_value, the ambiguous-single-write
+    // rejection, delete/update guards, atomicity, float drift, etc.) is
+    // covered exhaustively in conserved.test.ts. This block covers only
+    // declare-time validation of the registry entry itself.
+    describe("conserved: declaration validation", () => {
+        it("registers a conserved constraint across a set of resources whose values already sum to total", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            const constraint = declareConservedConstraint({
+                gameId,
+                resourceIds: [a.id, b.id],
+                total: 100,
+            });
+            expect(constraint.kind).toBe("conserved");
+            expect(constraint.resourceIds.sort()).toEqual([a.id, b.id].sort());
+            expect(constraint.total).toBe(100);
+            expect(constraint.direction).toBeNull();
+        });
+        it("registers a conserved constraint across 3+ resources", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 20 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 30 });
+            const c = createResource({ gameId, ownerType: "game", name: "seed_grain", value: 50 });
+            const constraint = declareConservedConstraint({
+                gameId,
+                resourceIds: [a.id, b.id, c.id],
+                total: 100,
+            });
+            expect(constraint.resourceIds.sort()).toEqual([a.id, b.id, c.id].sort());
+        });
+        it("rejects a conserved constraint with fewer than two resources", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id], total: 40 })).toThrow();
+        });
+        it("rejects a conserved constraint with an empty resource list", () => {
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [], total: 0 })).toThrow();
+        });
+        it("rejects when a listed resource does not exist", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id, "does-not-exist"], total: 40 })).toThrow();
+        });
+        it("rejects when the game does not exist", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            expect(() => declareConservedConstraint({ gameId: "does-not-exist", resourceIds: [a.id, b.id], total: 100 })).toThrow();
+        });
+        it("rejects a declaration whose members' current values do not already sum to the declared total", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: 999 })).toThrow(/sum/i);
+            // Must NOT have silently "fixed" either resource's value to make it true.
+            expect(a.value).toBe(40);
+            expect(b.value).toBe(60);
+        });
+        it("does not silently adjust resource values when the declared total is wrong", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: 50 })).toThrow();
+            expect(getConstraintsForResource(a.id)).toEqual([]);
+            expect(getConstraintsForResource(b.id)).toEqual([]);
+        });
+        it("rejects a non-finite total (NaN)", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: NaN })).toThrow();
+        });
+        it("rejects a non-finite total (Infinity)", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: Infinity })).toThrow();
+        });
+        it("dedupes a repeated resourceId in the input and validates the sum against the unique set", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            const constraint = declareConservedConstraint({
+                gameId,
+                resourceIds: [a.id, b.id, a.id],
+                total: 100,
+            });
+            expect(constraint.resourceIds.sort()).toEqual([a.id, b.id].sort());
+        });
+        it("rejects declaring a second conserved constraint that overlaps membership with an existing one", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            const c = createResource({ gameId, ownerType: "game", name: "seed_grain", value: 10 });
+            declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: 100 });
+            // 'a' is already a member of a conserved set -- a second, overlapping
+            // conserved set would make it ambiguous which set a transfer touching
+            // 'a' is supposed to preserve.
+            expect(() => declareConservedConstraint({ gameId, resourceIds: [a.id, c.id], total: 50 })).toThrow(/already belongs to a 'conserved' constraint/i);
+        });
+        it("allows a resource with a 'bounded' constraint to also join a 'conserved' set", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40, minValue: 0, maxValue: 100 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            declareBoundedConstraint({ gameId, resourceId: a.id });
+            const constraint = declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: 100 });
+            expect(constraint.kind).toBe("conserved");
+            const forA = getConstraintsForResource(a.id).map((c) => c.kind).sort();
+            expect(forA).toEqual(["bounded", "conserved"]);
+        });
+        it("allows a resource with a 'monotonic' constraint to also join a 'conserved' set", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            declareMonotonicConstraint({ gameId, resourceId: a.id, direction: "increasing" });
+            const constraint = declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: 100 });
+            expect(constraint.kind).toBe("conserved");
+        });
+    });
+    describe("listConstraints / getConstraintsForResource / removeConstraint", () => {
+        it("lists constraints for a game, optionally filtered by resource", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 50, minValue: 0, maxValue: 100 });
+            const b = createResource({ gameId, ownerType: "game", name: "population", value: 10 });
+            const c1 = declareBoundedConstraint({ gameId, resourceId: a.id });
+            const c2 = declareMonotonicConstraint({ gameId, resourceId: b.id, direction: "increasing" });
+            const all = listConstraints(gameId);
+            expect(all.map((c) => c.id).sort()).toEqual([c1.id, c2.id].sort());
+            const forA = listConstraints(gameId, a.id);
+            expect(forA.map((c) => c.id)).toEqual([c1.id]);
+        });
+        it("getConstraintsForResource finds constraints where the resource is a member, including conserved sets", () => {
+            const a = createResource({ gameId, ownerType: "game", name: "grain", value: 40 });
+            const b = createResource({ gameId, ownerType: "game", name: "reserve_grain", value: 60 });
+            const conserved = declareConservedConstraint({ gameId, resourceIds: [a.id, b.id], total: 100 });
+            expect(getConstraintsForResource(a.id).map((c) => c.id)).toEqual([conserved.id]);
+            expect(getConstraintsForResource(b.id).map((c) => c.id)).toEqual([conserved.id]);
+        });
+        it("removes a constraint by id", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "grain", value: 50, minValue: 0, maxValue: 100 });
+            const constraint = declareBoundedConstraint({ gameId, resourceId: resource.id });
+            expect(removeConstraint(constraint.id)).toBe(true);
+            expect(getConstraintsForResource(resource.id)).toEqual([]);
+            expect(removeConstraint(constraint.id)).toBe(false);
+        });
+    });
+});

package/dist/tools/__tests__/expiry-consequences.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/__tests__/expiry-consequences.test.js

@@ -0,0 +1,110 @@
+// Cross-cutting tests for the opt-in "expiry consequence" capability across
+// BOTH systems that support it: scheduled events (time.ts) and timers
+// (timers.ts). Each system has its own focused unit tests in time.test.ts
+// and timers.test.ts respectively; this file exists specifically to cover
+// interleaving between them, since a DM session commonly has both a
+// scheduled event and a countdown timer live at once, sometimes targeting
+// the very same resource.
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestDb, destroyTestDb } from '../../db/__tests__/testDb.js';
+import { createGame } from '../game.js';
+import { createResource, getResource, getResourceHistory } from '../resource.js';
+import { setCalendar, advanceTime, scheduleEvent } from '../time.js';
+import { createTimer, tickTimer } from '../timers.js';
+const dt = (overrides = {}) => ({
+    year: 1,
+    month: 0,
+    day: 0,
+    hour: 8,
+    minute: 0,
+    ...overrides,
+});
+describe('interleaved scheduled events and timers', () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+        setCalendar(gameId, {});
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('applies a scheduled-event consequence and a timer consequence to the same resource, each exactly once, regardless of order', () => {
+        const treasury = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 100 });
+        scheduleEvent({
+            gameId,
+            name: 'toll collected',
+            triggerTime: dt({ hour: 9 }),
+            consequence: { resourceId: treasury.id, delta: -10 },
+        });
+        const timer = createTimer({
+            gameId,
+            name: 'ritual completes',
+            timerType: 'countdown',
+            currentValue: 2,
+            triggerAt: 0,
+            consequence: { resourceId: treasury.id, delta: -25 },
+        });
+        tickTimer(timer.id, 1); // 2 -> 1, not yet
+        advanceTime(gameId, { hours: 2 }); // crosses the event's trigger, -10
+        tickTimer(timer.id, 1); // 1 -> 0, crosses the timer's trigger, -25
+        expect(getResource(treasury.id)?.value).toBe(65);
+        const history = getResourceHistory(treasury.id);
+        expect(history).toHaveLength(2);
+        expect(history).toEqual(expect.arrayContaining([
+            expect.objectContaining({ delta: -10, reason: expect.stringContaining('toll collected') }),
+            expect.objectContaining({ delta: -25, reason: expect.stringContaining('ritual completes') }),
+        ]));
+    });
+    it('ticking a timer in between two advanceTime calls does not disturb the scheduled event bookkeeping', () => {
+        const grain = createResource({ gameId, ownerType: 'game', name: 'grain', value: 50 });
+        const gold = createResource({ gameId, ownerType: 'game', name: 'gold', value: 50 });
+        scheduleEvent({
+            gameId,
+            name: 'spoilage',
+            triggerTime: dt({ hour: 12 }),
+            consequence: { resourceId: grain.id, delta: -5 },
+        });
+        const timer = createTimer({
+            gameId,
+            name: 'a spell wearing off',
+            timerType: 'countdown',
+            currentValue: 3,
+            triggerAt: 0,
+            consequence: { resourceId: gold.id, delta: -1 },
+        });
+        const first = advanceTime(gameId, { hours: 1 }); // 08:00 -> 09:00, event not due yet
+        expect(first?.triggeredEvents).toHaveLength(0);
+        tickTimer(timer.id, 1); // 3 -> 2
+        tickTimer(timer.id, 1); // 2 -> 1
+        expect(getResource(gold.id)?.value).toBe(50); // timer hasn't triggered yet
+        const second = advanceTime(gameId, { hours: 4 }); // 09:00 -> 13:00, crosses the event
+        expect(second?.triggeredEvents).toHaveLength(1);
+        expect(getResource(grain.id)?.value).toBe(45);
+        tickTimer(timer.id, 1); // 1 -> 0, triggers
+        expect(getResource(gold.id)?.value).toBe(49);
+    });
+    it('a failing timer consequence does not affect an independently-processed scheduled event, and vice versa', () => {
+        const treasury = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 100 });
+        scheduleEvent({
+            gameId,
+            name: 'healthy toll',
+            triggerTime: dt({ hour: 9 }),
+            consequence: { resourceId: treasury.id, delta: -10 },
+        });
+        const brokenTimer = createTimer({
+            gameId,
+            name: 'broken spell',
+            timerType: 'countdown',
+            currentValue: 1,
+            triggerAt: 0,
+            consequence: { resourceId: 'does-not-exist', delta: -999 },
+        });
+        const result = advanceTime(gameId, { hours: 2 });
+        expect(result?.triggeredEvents).toHaveLength(1);
+        expect(getResource(treasury.id)?.value).toBe(90);
+        expect(() => tickTimer(brokenTimer.id, 1)).toThrow();
+        // The unrelated, already-applied event consequence must be untouched.
+        expect(getResource(treasury.id)?.value).toBe(90);
+    });
+});

package/dist/tools/__tests__/images.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/__tests__/images.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { v4 as uuidv4 } from 'uuid';
+import { createTestDb, destroyTestDb } from '../../db/__tests__/testDb.js';
+import { getDatabase } from '../../db/connection.js';
+import { createGame } from '../game.js';
+import { createCharacter } from '../character.js';
+import { getImage, setPrimaryImage } from '../images.js';
+// Inserts a stored_images row directly via SQL so these tests can exercise
+// setPrimaryImage() without going through storeImage()'s file I/O / network
+// fetch, which is unrelated to the atomicity behavior under test here.
+function insertStoredImage(params) {
+    const db = getDatabase();
+    const id = uuidv4();
+    db.prepare(`
+    INSERT INTO stored_images (id, game_id, entity_id, entity_type, file_path, file_size, mime_type, source, is_primary, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, params.gameId, params.entityId, params.entityType, `${id}.png`, 100, 'image/png', 'uploaded', params.isPrimary ? 1 : 0, new Date().toISOString());
+    return id;
+}
+describe('setPrimaryImage', () => {
+    let gameId;
+    let characterId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+        characterId = createCharacter({ gameId, name: 'Narrator', isPlayer: false }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('unsets the previous primary and sets the new one', () => {
+        const first = insertStoredImage({ gameId, entityId: characterId, entityType: 'character', isPrimary: true });
+        const second = insertStoredImage({ gameId, entityId: characterId, entityType: 'character', isPrimary: false });
+        setPrimaryImage(second);
+        expect(getImage(first)?.isPrimary).toBe(false);
+        expect(getImage(second)?.isPrimary).toBe(true);
+    });
+    it('leaves NO partial write when the second update fails mid-operation: the old primary stays primary', () => {
+        const first = insertStoredImage({ gameId, entityId: characterId, entityType: 'character', isPrimary: true });
+        const second = insertStoredImage({ gameId, entityId: characterId, entityType: 'character', isPrimary: false });
+        // Fault injection: make the UPDATE that sets `second` as primary fail,
+        // simulating a mid-operation failure between the unset and the set.
+        const db = getDatabase();
+        db.exec(`
+      CREATE TRIGGER fail_set_new_primary_image
+      BEFORE UPDATE ON stored_images
+      WHEN NEW.id = '${second}' AND NEW.is_primary = 1
+      BEGIN
+        SELECT RAISE(ABORT, 'simulated failure');
+      END;
+    `);
+        expect(() => setPrimaryImage(second)).toThrow();
+        // Without a real transaction, the first UPDATE (unsetting `first`)
+        // would have already committed, leaving NO primary at all. With a
+        // transaction, `first` must still be primary.
+        expect(getImage(first)?.isPrimary).toBe(true);
+        expect(getImage(second)?.isPrimary).toBe(false);
+    });
+});

package/dist/tools/__tests__/relationship.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/__tests__/relationship.test.js

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestDb, destroyTestDb } from '../../db/__tests__/testDb.js';
+import { getDatabase } from '../../db/connection.js';
+import { createGame } from '../game.js';
+import { createBidirectionalRelationship, createRelationship, getRelationship, getRelationshipHistory, modifyRelationship, updateRelationshipValue, } from '../relationship.js';
+describe('createBidirectionalRelationship', () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('creates two relationship rows, one in each direction', () => {
+        const [relA, relB] = createBidirectionalRelationship({
+            gameId,
+            entityA: { id: 'alice', type: 'character' },
+            entityB: { id: 'bob', type: 'character' },
+            relationshipType: 'ally',
+            value: 10,
+        });
+        expect(relA.sourceId).toBe('alice');
+        expect(relA.targetId).toBe('bob');
+        expect(relB.sourceId).toBe('bob');
+        expect(relB.targetId).toBe('alice');
+    });
+    it('leaves NO partial write when the second insert fails mid-operation', () => {
+        const db = getDatabase();
+        // Fault injection: make the INSERT for the second (bob -> alice) row
+        // fail, simulating a mid-operation failure such as a constraint
+        // violation or disk error.
+        db.exec(`
+      CREATE TRIGGER fail_second_relationship_insert
+      BEFORE INSERT ON relationships
+      WHEN NEW.source_id = 'bob'
+      BEGIN
+        SELECT RAISE(ABORT, 'simulated failure');
+      END;
+    `);
+        expect(() => createBidirectionalRelationship({
+            gameId,
+            entityA: { id: 'alice', type: 'character' },
+            entityB: { id: 'bob', type: 'character' },
+            relationshipType: 'ally',
+            value: 10,
+        })).toThrow();
+        const rows = db.prepare('SELECT * FROM relationships').all();
+        expect(rows).toHaveLength(0);
+    });
+});
+describe('modifyRelationship', () => {
+    let gameId;
+    let relationshipId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+        relationshipId = createRelationship({
+            gameId,
+            sourceId: 'alice',
+            sourceType: 'character',
+            targetId: 'bob',
+            targetType: 'character',
+            relationshipType: 'ally',
+            value: 0,
+        }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('updates the value and logs a history row together', () => {
+        const result = modifyRelationship({ relationshipId, delta: 5, reason: 'helped in a fight' });
+        expect(result?.relationship.value).toBe(5);
+        const history = getRelationshipHistory(relationshipId);
+        expect(history).toHaveLength(1);
+        expect(history[0]).toMatchObject({ previousValue: 0, newValue: 5, reason: 'helped in a fight' });
+    });
+    it('leaves NO partial write when the history insert fails mid-operation', () => {
+        const db = getDatabase();
+        // Fault injection: make the relationship_history INSERT fail after the
+        // relationships UPDATE has already run.
+        db.exec(`
+      CREATE TRIGGER fail_relationship_history_insert
+      BEFORE INSERT ON relationship_history
+      BEGIN
+        SELECT RAISE(ABORT, 'simulated failure');
+      END;
+    `);
+        expect(() => modifyRelationship({ relationshipId, delta: 5, reason: 'helped in a fight' })).toThrow();
+        expect(getRelationship(relationshipId)?.value).toBe(0);
+        expect(getRelationshipHistory(relationshipId)).toHaveLength(0);
+    });
+});
+describe('updateRelationshipValue', () => {
+    let gameId;
+    let relationshipId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+        relationshipId = createRelationship({
+            gameId,
+            sourceId: 'alice',
+            sourceType: 'character',
+            targetId: 'bob',
+            targetType: 'character',
+            relationshipType: 'ally',
+            value: 0,
+        }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('updates the value and logs history when the value changes', () => {
+        const result = updateRelationshipValue({ relationshipId, mode: 'set', value: 20, reason: 'reconciled' });
+        expect(result?.relationship.value).toBe(20);
+        expect(result?.change).toMatchObject({ previousValue: 0, newValue: 20, reason: 'reconciled' });
+    });
+    it('leaves NO partial write when the history insert fails mid-operation', () => {
+        const db = getDatabase();
+        db.exec(`
+      CREATE TRIGGER fail_relationship_history_insert_2
+      BEFORE INSERT ON relationship_history
+      BEGIN
+        SELECT RAISE(ABORT, 'simulated failure');
+      END;
+    `);
+        expect(() => updateRelationshipValue({ relationshipId, mode: 'set', value: 20, reason: 'reconciled' })).toThrow();
+        // Value must not have moved, since the paired history write failed.
+        expect(getRelationship(relationshipId)?.value).toBe(0);
+        expect(getRelationshipHistory(relationshipId)).toHaveLength(0);
+    });
+});

package/dist/tools/__tests__/resource-constraints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/__tests__/resource-constraints.test.js

@@ -0,0 +1,131 @@
+// Integration tests: does updateResourceValue() actually enforce declared
+// constraints, and does it leave unconstrained resources exactly as they
+// behaved before this feature existed?
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createTestDb, destroyTestDb } from "../../db/__tests__/testDb.js";
+import { createGame } from "../game.js";
+import { createResource, getResource, updateResourceValue } from "../resource.js";
+import { declareBoundedConstraint, declareMonotonicConstraint, ConstraintViolationError, } from "../constraint.js";
+describe("constraint enforcement on updateResourceValue", () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: "Test Game", setting: "test", style: "test" }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    describe("no constraint declared (baseline, must be unchanged)", () => {
+        it("still silently clamps to min/max as before", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 50,
+                minValue: 0,
+                maxValue: 100,
+            });
+            const result = updateResourceValue({ resourceId: resource.id, mode: "set", value: 999 });
+            expect(result?.resource.value).toBe(100);
+            expect(getResource(resource.id)?.value).toBe(100);
+        });
+        it("allows values to move in either direction with no monotonic constraint", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "population", value: 10 });
+            updateResourceValue({ resourceId: resource.id, mode: "delta", value: 5 });
+            const down = updateResourceValue({ resourceId: resource.id, mode: "delta", value: -20 });
+            expect(down?.resource.value).toBe(-5);
+        });
+    });
+    describe("bounded constraint declared", () => {
+        it("rejects (does not clamp) a 'set' that would exceed the max", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 50,
+                minValue: 0,
+                maxValue: 100,
+            });
+            declareBoundedConstraint({ gameId, resourceId: resource.id });
+            expect(() => updateResourceValue({ resourceId: resource.id, mode: "set", value: 999 })).toThrow(ConstraintViolationError);
+            // Value must be untouched -- rejection, not a partial/clamped write.
+            expect(getResource(resource.id)?.value).toBe(50);
+        });
+        it("rejects a delta that would go below the min", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 10,
+                minValue: 0,
+                maxValue: 100,
+            });
+            declareBoundedConstraint({ gameId, resourceId: resource.id });
+            expect(() => updateResourceValue({ resourceId: resource.id, mode: "delta", value: -50 })).toThrow(ConstraintViolationError);
+            expect(getResource(resource.id)?.value).toBe(10);
+        });
+        it("allows an in-bounds change through untouched", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 50,
+                minValue: 0,
+                maxValue: 100,
+            });
+            declareBoundedConstraint({ gameId, resourceId: resource.id });
+            const result = updateResourceValue({ resourceId: resource.id, mode: "delta", value: 25 });
+            expect(result?.resource.value).toBe(75);
+        });
+    });
+    describe("monotonic constraint declared", () => {
+        it("rejects a decrease on an 'increasing' (never-decreasing) resource", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "population", value: 100 });
+            declareMonotonicConstraint({ gameId, resourceId: resource.id, direction: "increasing" });
+            expect(() => updateResourceValue({ resourceId: resource.id, mode: "delta", value: -1 })).toThrow(ConstraintViolationError);
+            expect(getResource(resource.id)?.value).toBe(100);
+        });
+        it("allows an increase on an 'increasing' resource", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "population", value: 100 });
+            declareMonotonicConstraint({ gameId, resourceId: resource.id, direction: "increasing" });
+            const result = updateResourceValue({ resourceId: resource.id, mode: "delta", value: 5 });
+            expect(result?.resource.value).toBe(105);
+        });
+        it("rejects an increase on a 'decreasing' (never-increasing) resource", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "countdown", value: 10 });
+            declareMonotonicConstraint({ gameId, resourceId: resource.id, direction: "decreasing" });
+            expect(() => updateResourceValue({ resourceId: resource.id, mode: "set", value: 20 })).toThrow(ConstraintViolationError);
+            expect(getResource(resource.id)?.value).toBe(10);
+        });
+        it("allows a value to stay the same (not a strict decrease requirement)", () => {
+            const resource = createResource({ gameId, ownerType: "game", name: "countdown", value: 10 });
+            declareMonotonicConstraint({ gameId, resourceId: resource.id, direction: "decreasing" });
+            const result = updateResourceValue({ resourceId: resource.id, mode: "delta", value: 0 });
+            expect(result?.resource.value).toBe(10);
+        });
+    });
+    describe("thrown error shape", () => {
+        it("ConstraintViolationError carries the resourceId and constraint kind", () => {
+            const resource = createResource({
+                gameId,
+                ownerType: "game",
+                name: "grain",
+                value: 50,
+                minValue: 0,
+                maxValue: 100,
+            });
+            declareBoundedConstraint({ gameId, resourceId: resource.id });
+            try {
+                updateResourceValue({ resourceId: resource.id, mode: "set", value: 999 });
+                expect.unreachable("expected updateResourceValue to throw");
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(ConstraintViolationError);
+                const violation = error;
+                expect(violation.resourceId).toBe(resource.id);
+                expect(violation.constraintKind).toBe("bounded");
+                expect(violation.message).toBeTruthy();
+            }
+        });
+    });
+});

package/dist/tools/__tests__/resource.test.d.ts

@@ -0,0 +1 @@
+export {};