run-dmcp 0.1.0 → 0.3.0

package/dist/timeline/schema.js

@@ -0,0 +1,264 @@
+import { getDatabase } from "../db/connection.js";
+import { ENTITY_KINDS } from "./kinds.js";
+import { installProjectionTriggers, reconcileTimeline } from "./projection.js";
+/**
+ * The timeline substrate (design §5.1): `entities`, `facts`, `events`, and
+ * the per-game `timeline_clock` that tells a `sequence` axis what its next
+ * ordinal is. Strictly additive -- nothing here is read by any existing
+ * tool yet, and every statement is idempotent so calling this at every
+ * startup (the project's only migration mechanism; see root CLAUDE.md) is
+ * safe against both a fresh database and one that predates the timeline.
+ *
+ * What makes recorded `t` actually immutable is the trigger block at the
+ * bottom of this function, not application discipline -- see the comment
+ * there.
+ */
+export function initializeTimelineSchema() {
+    const db = getDatabase();
+    // entity_kinds -- the allowed values of entities.kind, enforced by FK
+    // rather than a CHECK constraint. SQLite cannot ALTER a CHECK, so a
+    // CHECK here would force a full table rebuild the day issue #2 (or
+    // anything later) adds a projected kind; a reference table just gets one
+    // more row via INSERT OR IGNORE, on every init, forever. This is the
+    // same shape as the inherited gotcha it exists to avoid: `stored_audio`
+    // and friends carry an unconstrained entity_type that can typo silently
+    // and read back never. `kinds.ts` is the single owner of the vocabulary
+    // seeded here.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS entity_kinds (
+      kind TEXT PRIMARY KEY
+    )
+  `);
+    const seedKind = db.prepare("INSERT OR IGNORE INTO entity_kinds (kind) VALUES (?)");
+    for (const kind of ENTITY_KINDS) {
+        seedKind.run(kind);
+    }
+    // entities -- one row per timeline-tracked thing. `name` is the name at
+    // creation and never changes; the current name (if the projection layer
+    // ever changes it) is a `name` fact instead, so nothing here can drift
+    // out from under a caller relying on it.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS entities (
+      id TEXT PRIMARY KEY,
+      game_id TEXT NOT NULL,
+      kind TEXT NOT NULL REFERENCES entity_kinds(kind),
+      name TEXT,
+      created_at_t REAL NOT NULL,
+      destroyed_at_t REAL,
+      CHECK (destroyed_at_t IS NULL OR destroyed_at_t >= created_at_t)
+    )
+  `);
+    // facts -- interval-versioned key/value history for an entity. `value` is
+    // NOT NULL on purpose: a NULL column on the live row produces no fact at
+    // all (absence is the absence of a fact, never a fact of absence -- hard
+    // rule 3). No ON DELETE CASCADE and no FK to `games`: deleting a game
+    // deletes its live rows, but the timeline of that game survives.
+    // DECISION(#21): a property to be declared irreversible needs its own fact key.
+    //
+    // `irreversible` is a per-fact flag, not a per-entity or per-value one --
+    // so any property a future consumer wants to declare irreversible has to
+    // live under its own fact key; you cannot flag half a blob.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS facts (
+      id TEXT PRIMARY KEY,
+      entity_id TEXT NOT NULL REFERENCES entities(id),
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      valid_from_t REAL NOT NULL,
+      valid_to_t REAL,
+      irreversible INTEGER NOT NULL DEFAULT 0,
+      CHECK (valid_to_t IS NULL OR valid_to_t >= valid_from_t)
+    )
+  `);
+    // events -- the append-only log entry itself. `causes` carries one hop of
+    // provenance (design §5.2c) as a JSON string; nothing here is inferred
+    // from anything anyone wrote (hard rule 4) -- `kind`/`description` are
+    // tokens this codebase defines.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS events (
+      id TEXT PRIMARY KEY,
+      game_id TEXT NOT NULL,
+      at_t REAL NOT NULL,
+      kind TEXT NOT NULL,
+      description TEXT,
+      causes TEXT
+    )
+  `);
+    // timeline_clock -- one row per game, tracking the declared axis and its
+    // current position. A game that never declares an axis still needs one
+    // of these once its first entity/fact/event is written, with axis_kind
+    // 'sequence' (#6 owns declareTimeAxis/setStoryTime; this table just
+    // holds the row).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS timeline_clock (
+      game_id TEXT PRIMARY KEY,
+      current_t REAL NOT NULL,
+      axis_kind TEXT NOT NULL CHECK (axis_kind IN ('sequence', 'elapsed', 'counter')),
+      axis_unit TEXT NOT NULL,
+      declared_at TEXT NOT NULL
+    )
+  `);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_entities_game_kind ON entities(game_id, kind);
+    CREATE INDEX IF NOT EXISTS idx_entities_game_created ON entities(game_id, created_at_t);
+    CREATE INDEX IF NOT EXISTS idx_facts_entity_key ON facts(entity_id, key);
+    CREATE INDEX IF NOT EXISTS idx_facts_entity_key_valid_to ON facts(entity_id, key, valid_to_t);
+    CREATE INDEX IF NOT EXISTS idx_facts_valid_from ON facts(valid_from_t);
+    CREATE INDEX IF NOT EXISTS idx_events_game_at ON events(game_id, at_t);
+  `);
+    // Append-only guard triggers.
+    //
+    // Recorded `t` must be impossible to rewrite, not merely discouraged --
+    // that is the whole point of a substrate the checkpoint (#4) can trust.
+    // Every column comparison below uses IS NOT rather than <>, because <>
+    // with a NULL operand evaluates to NULL (neither true nor false) and the
+    // WHEN clause would silently fail to fire on exactly the rows -- open
+    // intervals -- where firing matters most.
+    //
+    // Each table gets exactly one permitted mutation: closing an open
+    // interval once (`facts.valid_to_t`, `entities.destroyed_at_t`, both
+    // NULL -> value). Every other UPDATE, and every DELETE, aborts.
+    //
+    // Every trigger below is DROP-then-CREATE, not CREATE TRIGGER IF NOT
+    // EXISTS. The column set being fixed is not the risk that decides this --
+    // it's that IF NOT EXISTS makes whatever guard shipped in the build that
+    // first created a given database permanent for that database. If this
+    // logic is ever tightened or a bug in it is fixed, that fix would
+    // silently never reach any database that already had the old trigger,
+    // which is exactly the "test against an existing database, not just a
+    // fresh one" trap this project has already been bitten by once. Dropping
+    // and recreating on every init means the guard a database has always
+    // matches the guard this build believes it deployed.
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_entities_immutable;
+    CREATE TRIGGER timeline_entities_immutable
+    BEFORE UPDATE ON entities
+    WHEN NEW.id IS NOT OLD.id
+      OR NEW.game_id IS NOT OLD.game_id
+      OR NEW.kind IS NOT OLD.kind
+      OR NEW.name IS NOT OLD.name
+      OR NEW.created_at_t IS NOT OLD.created_at_t
+      OR (OLD.destroyed_at_t IS NOT NULL AND NEW.destroyed_at_t IS NOT OLD.destroyed_at_t)
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: entities are append-only; only destroyed_at_t may be set, once');
+    END;
+  `);
+    // `irreversible` is itself a one-way latch: 0 -> 1 exactly once, never
+    // 1 -> 0, never to any other value. The clause below aborts whenever the
+    // column changed at all (`NEW.irreversible IS NOT OLD.irreversible`)
+    // UNLESS that change is precisely OLD=0, NEW=1 -- so 0 -> 5 still aborts
+    // (NEW is not 1), 1 -> 0 still aborts (OLD is not 0), and 1 -> 1 never
+    // reaches this branch in the first place because the column didn't
+    // change. declareIrreversible() (irreversible.ts) relies on that last
+    // case to make re-declaring idempotent with a single UPDATE and no
+    // separate "already set" check.
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_facts_immutable;
+    CREATE TRIGGER timeline_facts_immutable
+    BEFORE UPDATE ON facts
+    WHEN NEW.id IS NOT OLD.id
+      OR NEW.entity_id IS NOT OLD.entity_id
+      OR NEW.key IS NOT OLD.key
+      OR NEW.value IS NOT OLD.value
+      OR NEW.valid_from_t IS NOT OLD.valid_from_t
+      OR (NEW.irreversible IS NOT OLD.irreversible
+          AND (OLD.irreversible IS NOT 0 OR NEW.irreversible IS NOT 1))
+      OR (OLD.valid_to_t IS NOT NULL AND NEW.valid_to_t IS NOT OLD.valid_to_t)
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: facts are append-only; valid_from_t cannot be rewritten, valid_to_t may only be closed once, and irreversible may only move 0 -> 1');
+    END;
+  `);
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_events_immutable;
+    CREATE TRIGGER timeline_events_immutable
+    BEFORE UPDATE ON events
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: an event never changes once recorded');
+    END;
+  `);
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_entities_no_delete;
+    CREATE TRIGGER timeline_entities_no_delete
+    BEFORE DELETE ON entities
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: entities are append-only; rows are never deleted');
+    END;
+  `);
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_facts_no_delete;
+    CREATE TRIGGER timeline_facts_no_delete
+    BEFORE DELETE ON facts
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: facts are append-only; rows are never deleted');
+    END;
+  `);
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_events_no_delete;
+    CREATE TRIGGER timeline_events_no_delete
+    BEFORE DELETE ON events
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: events are append-only; rows are never deleted');
+    END;
+  `);
+    // Issue #7 / design §5.3: `irreversible` is the temporal member of the
+    // constraint family (bounded, monotonic, conserved sets). Rule: once a
+    // fact F = (entity_id, key, value) has irreversible = 1 at valid_from_t
+    // tF, no INSERT for the same entity_id/key with a DIFFERENT value and
+    // valid_from_t >= tF is permitted -- "for all t' > t", stated at the row
+    // level as `>=` because valid_from_t IS the instant the new value would
+    // take effect. `f.value IS NOT NEW.value` (not `<>`) for the same reason
+    // every other comparison in this file uses IS NOT: a NULL operand would
+    // otherwise make the WHEN clause silently not fire, and `value` can never
+    // legitimately be NULL here regardless (see the `facts` table comment)
+    // but this keeps the idiom uniform rather than relying on that.
+    //
+    // Deliberately an INSERT guard, not an UPDATE guard: facts are append-only
+    // (see timeline_facts_immutable above), so every new value for a key
+    // arrives as a fresh INSERT, never an UPDATE to an existing row's value.
+    //
+    // Closing an interval is NOT a contradiction and is NOT blocked here --
+    // `UPDATE facts SET valid_to_t = ...` never reaches this trigger at all,
+    // it is a different table event. This matters concretely: the projection
+    // layer's `_ad` delete trigger (projection.ts) closes every open fact for
+    // a destroyed entity via that same UPDATE path, and if closing were
+    // treated as a contradiction, any entity carrying an irreversible fact
+    // would become impossible to delete -- a policy this engine has no
+    // business imposing (see hard rule 2). Reopening the key afterward with a
+    // DIFFERENT value is still refused, because the WHEN clause below matches
+    // every irreversible row for the key, open or closed, not only the
+    // currently-open one.
+    //
+    // Because SQLite's RAISE(ABORT) backs out every change made by the firing
+    // statement -- including everything every trigger it invoked did, not
+    // just the INSERT this trigger body itself guards -- a refused reopen
+    // attempted from inside the projection layer's own AFTER UPDATE trigger
+    // (buildUpdateTrigger in projection.ts, which closes the old fact and
+    // then attempts to insert the new one in the same firing statement) rolls
+    // the close back too. The fact stays open, the live column stays
+    // unwritten, and the game's clock (also advanced earlier in that same
+    // trigger body) does not advance either. irreversible.test.ts's
+    // "real tool path" tests exercise this rollback directly, through
+    // updateResourceValue -> `UPDATE resources SET value = ...`.
+    db.exec(`
+    DROP TRIGGER IF EXISTS timeline_facts_irreversible;
+    CREATE TRIGGER timeline_facts_irreversible
+    BEFORE INSERT ON facts
+    WHEN EXISTS (
+      SELECT 1 FROM facts f
+       WHERE f.entity_id = NEW.entity_id
+         AND f.key = NEW.key
+         AND f.irreversible = 1
+         AND f.value IS NOT NEW.value
+         AND NEW.valid_from_t >= f.valid_from_t
+    )
+    BEGIN
+      SELECT RAISE(ABORT, 'timeline: an irreversible fact holds for key ''' || NEW.key || ''' on this entity as of its valid_from_t; a contradicting value is refused from that point onward');
+    END;
+  `);
+    // Issue #2: the projection layer. Triggers first, so every write from
+    // here on appends by construction; reconciliation second, so it backfills
+    // against triggers that are already live rather than a stale set. See
+    // projection.ts for what each does and why reconciliation must run last.
+    installProjectionTriggers();
+    reconcileTimeline();
+}

package/dist/timeline/t.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `t` -- story time, client-defined, chosen by one rule (design §14, hard
+ * rule 6):
+ *
+ *   t is the axis that stays invariant when a caller re-segments its own
+ *   units.
+ *
+ * A timestamp qualifies; so does a turn counter. An index into re-cuttable
+ * units does NOT -- re-cutting the units shifts what the index points at
+ * while the story underneath is unchanged. Choosing wrong raises no error:
+ * it silently attaches one unit's content to another's.
+ *
+ * `t` is an opaque, client-declared ordinal. It is never a datetime -- a
+ * `Date` carries a specific re-segmentation temptation (timezone, calendar,
+ * "which second did this actually happen") that a plain number does not
+ * invite. Callers that want elapsed real time declare an `elapsed` axis
+ * (see clock.ts, #6) and hand it a float; they do not hand the engine a
+ * `Date`.
+ */
+export type T = number;
+/**
+ * The one comparator every place in the timeline that orders `t` goes
+ * through. Numeric ascending -- there is no other ordering `t` could have,
+ * since it is always a plain number, but centralizing this means a future
+ * axis kind can never introduce a second, inconsistent notion of "later."
+ */
+export declare function compareT(a: T, b: T): number;
+/**
+ * Throws unless `value` is a finite number. Rejects everything else --
+ * `Date`, string (including a numeric string like `"12"`), `NaN`,
+ * `Infinity`, `null`, `undefined` -- naming what was actually supplied so
+ * the caller doesn't have to guess which of those it sent.
+ */
+export declare function assertT(value: unknown): asserts value is T;
+/**
+ * The declared shape of a game's `t` -- which axis it moves along, chosen
+ * once per game and enforced by clock.ts (issue #6, `declareTimeAxis`).
+ * Every variant here is here because it satisfies §14's property (hard rule
+ * 6): it stays invariant when a caller re-segments its own units. There is a
+ * fourth, more obvious-looking kind that is deliberately absent, and the
+ * absence is the point -- see below.
+ *
+ * - `sequence` -- the engine's own append ordinal, one tick per write. The
+ *   default for a game that declares nothing. Invariant because nothing
+ *   re-cuts it: the engine is the only writer of the next value, so there is
+ *   no "the caller's own units" for it to be an index into in the first
+ *   place.
+ * - `elapsed` -- time since a fixed origin, in a caller-named `unit` (e.g.
+ *   "seconds", in-game "minutes" -- whatever the caller's own story runs on).
+ *   Invariant because re-segmenting is exactly the act of drawing new unit
+ *   boundaries over a timeline that does not itself move; elapsed time from
+ *   a fixed origin has nothing to re-cut.
+ * - `counter` -- a count of things that happened, in a caller-named `unit`
+ *   (turns, ticks). Not a count of things authored. Invariant for the same
+ *   reason `sequence` is: re-cutting authored material afterward does not
+ *   change how many real events occurred before a given point.
+ *
+ * There is deliberately **no** variant for an index into units the caller
+ * may re-cut. Editing re-cuts those: the index shifts while the story
+ * underneath does not, and choosing one raises no error -- it silently
+ * attaches one unit's content to another's (§14). Because there is no
+ * variant for it, a caller who wants to hand the engine that kind of index
+ * anyway has to pick `elapsed` or `counter` and lie about the unit to do it
+ * -- there is no honest way to spell "index into units I might re-cut" in
+ * this type. That awkwardness is deliberate: it is the API making the wrong
+ * choice hard to make by accident, not merely documenting that it is wrong.
+ * `clock.ts`'s `declareTimeAxis` backs this up at runtime by refusing to let
+ * a game's axis change once declared -- swapping axes mid-timeline is the
+ * one runtime action that reproduces this exact failure, so that is where
+ * it gets refused.
+ */
+export type TimeAxis = {
+    kind: "sequence";
+} | {
+    kind: "elapsed";
+    unit: string;
+} | {
+    kind: "counter";
+    unit: string;
+};

package/dist/timeline/t.js

@@ -0,0 +1,37 @@
+/**
+ * The one comparator every place in the timeline that orders `t` goes
+ * through. Numeric ascending -- there is no other ordering `t` could have,
+ * since it is always a plain number, but centralizing this means a future
+ * axis kind can never introduce a second, inconsistent notion of "later."
+ */
+export function compareT(a, b) {
+    return a - b;
+}
+/**
+ * Throws unless `value` is a finite number. Rejects everything else --
+ * `Date`, string (including a numeric string like `"12"`), `NaN`,
+ * `Infinity`, `null`, `undefined` -- naming what was actually supplied so
+ * the caller doesn't have to guess which of those it sent.
+ */
+export function assertT(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return;
+    }
+    throw new Error(`timeline: t must be a finite number, got ${describeRejectedT(value)}`);
+}
+function describeRejectedT(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (value instanceof Date)
+        return `a Date (${value.toISOString()})`;
+    if (typeof value === "number") {
+        // Only NaN and +-Infinity reach here -- every other number returned
+        // above.
+        return String(value);
+    }
+    if (typeof value === "string")
+        return `a string (${JSON.stringify(value)})`;
+    return `a ${typeof value}`;
+}

package/dist/tools/audio.js

@@ -2,6 +2,7 @@ import { v4 as uuidv4 } from "uuid";
 import { getDatabase, getDataDir, withTransaction } from "../db/connection.js";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync, rmSync, } from "fs";
 import { dirname, join, extname } from "path";
+import { mediaDirPath, mediaFilePath, mediaPathWithin } from "../utils/media-path.js";
 import { getCharacter } from "./character.js";
 import { getLocation } from "./world.js";
 import { getFaction } from "./faction.js";
@@ -128,10 +129,11 @@ export async function storeAudio(params) {
     else {
         throw new Error("Either url or filePath must be provided");
     }
-    // Build file path
+    // Build file path. Every segment below arrives from the caller, so the
+    // composition goes through the media-path choke point, which rejects
+    // anything that would land outside the audio directory.
     const ext = getExtension(mimeType);
-    const relativePath = join(params.gameId, `${params.entityType}s`, params.entityId, `${id}.${ext}`);
-    const fullPath = join(getAudioDir(), relativePath);
+    const { relativePath, fullPath } = mediaFilePath(getAudioDir(), [params.gameId, `${params.entityType}s`, params.entityId], `${id}.${ext}`);
     // Ensure directory exists and write file
     ensureDir(dirname(fullPath));
     writeFileSync(fullPath, audioBuffer);
@@ -192,7 +194,7 @@ export function getAudioFilePath(audioId) {
     const audio = getAudio(audioId);
     if (!audio)
         return null;
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (!existsSync(fullPath))
         return null;
     return fullPath;
@@ -201,7 +203,7 @@ export function getAudioData(audioId) {
     const audio = getAudio(audioId);
     if (!audio)
         return null;
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (!existsSync(fullPath))
         return null;
     const buffer = readFileSync(fullPath);
@@ -264,7 +266,7 @@ export function getCharacterVoiceReferences(gameId, characterId) {
     const audioDir = getAudioDir();
     const filePaths = voiceRefs
         .map((ref) => {
-        const fullPath = join(audioDir, ref.filePath);
+        const fullPath = mediaPathWithin(audioDir, ref.filePath);
         return existsSync(fullPath) ? fullPath : null;
     })
         .filter((p) => p !== null);
@@ -283,7 +285,7 @@ export function deleteAudio(audioId) {
     if (!audio)
         return false;
     // Delete file
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (existsSync(fullPath)) {
         unlinkSync(fullPath);
     }
@@ -339,8 +341,10 @@ export function updateAudioMetadata(audioId, updates) {
 // Cleanup helper - delete all audio for a game
 export function deleteGameAudio(gameId) {
     const db = getDatabase();
-    // Delete files
-    const gameDir = join(getAudioDir(), gameId);
+    // Delete files. mediaDirPath rejects before the rmSync below, which is
+    // recursive and forced: an unchecked `..` here would take the whole data
+    // directory with it.
+    const gameDir = mediaDirPath(getAudioDir(), [gameId]);
     if (existsSync(gameDir)) {
         rmSync(gameDir, { recursive: true, force: true });
     }

package/dist/tools/constraint.d.ts

@@ -1,47 +1,12 @@
-import type { ConstraintKind, MonotonicDirection, ResourceConstraint } from "../types/index.js";
-/**
- * Declarative, opt-in, server-enforced invariants on `resources` rows.
- *
- * A resource with no declared constraint behaves exactly as it always has --
- * out-of-bounds writes are silently clamped by clampValue() in resource.ts.
- * Declaring a constraint here changes that contract for that one resource
- * (or set of resources, for 'conserved') only.
- *
- * SCOPE NOTE: this layer covers the `resources` table only. Three other
- * numeric write paths bypass it entirely and are NOT covered:
- *   - factions.resources (JSON blob; see modifyFactionResource/setFactionResource
- *     in src/tools/faction.ts -- no bounds, no history, silently deletes an
- *     entry when it hits <= 0)
- *   - characters.attributes (arbitrary numeric JSON, unvalidated)
- *   - relationships.value (its own separate system)
- * A game author who needs a server-enforced invariant on a quantity must
- * model that quantity as a `resources` row, not one of the above.
- *
- * '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.
- */
-/** 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 declare const CONSERVED_SUM_EPSILON = 0.000001;
-export declare class ConstraintViolationError extends Error {
-    readonly constraintKind: ConstraintKind;
-    readonly resourceId: string;
-    constructor(constraintKind: ConstraintKind, resourceId: string, message: string);
-}
+import type { MonotonicDirection, ResourceConstraint } from "../types/index.js";
+import { ConstraintViolationError, CONSERVED_SUM_EPSILON } from "../timeline/registry.js";
+export { ConstraintViolationError, CONSERVED_SUM_EPSILON };
 /**
  * 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 declare function declareBoundedConstraint(params: {
     gameId: string;
@@ -58,6 +23,42 @@ export declare function declareMonotonicConstraint(params: {
     resourceId: string;
     direction: MonotonicDirection;
 }): ResourceConstraint;
+/**
+ * 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 declare function declareResolveOnlyConstraint(params: {
+    gameId: string;
+    resourceId: string;
+    factKey?: string;
+}): ResourceConstraint;
 /**
  * Register a 'conserved' constraint: a set of resources that must always
  * sum to a fixed total.
@@ -87,46 +88,9 @@ export declare function declareConservedConstraint(params: {
 }): ResourceConstraint;
 /** List constraints for a game, optionally filtered to ones governing a given resource. */
 export declare function listConstraints(gameId: string, resourceId?: string): ResourceConstraint[];
-/** 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 declare function getConstraintsForResource(resourceId: string): ResourceConstraint[];
 /** Remove a constraint by id. Returns true if a row was deleted. */
 export declare function removeConstraint(id: string): boolean;
-/**
- * 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 declare function checkBoundedAndMonotonicConstraints(resourceId: string, previousValue: number, intendedValue: number, bounds: {
-    minValue: number | null;
-    maxValue: number | null;
-}): void;
-/**
- * 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 declare function checkResourceConstraints(resourceId: string, previousValue: number, intendedValue: number, bounds: {
-    minValue: number | null;
-    maxValue: number | null;
-}): void;
-/** 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 declare function getConservedConstraintFor(resourceId: string): ResourceConstraint | null;