run-dmcp 0.1.0 → 0.3.0

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);
 }

package/dist/tools/time.js

@@ -133,9 +133,24 @@ export function advanceTime(gameId, duration) {
     const consequenceFailures = [];
     for (const row of events) {
         const triggerTime = safeJsonParse(row.trigger_time, { year: 1, month: 1, day: 1, hour: 0, minute: 0 });
-        // Check if event should trigger (trigger time is between previous and new time)
-        if (compareDateTime(triggerTime, previousTime, calendarConfig) >= 0 &&
-            compareDateTime(triggerTime, newTime, calendarConfig) <= 0) {
+        // Due if the trigger time has been reached -- deliberately NOT also gated
+        // on `triggerTime >= previousTime`.
+        //
+        // That lower bound looks like the right window ("did we cross it on THIS
+        // call?") and quietly broke the retry the catch block below promises. When
+        // a consequence throws, the transaction rolls back and the row stays
+        // pending, exactly as intended -- but the clock has already moved past
+        // triggerTime by then, because it is updated unconditionally above. On
+        // every subsequent call the lower bound therefore excluded the row, and
+        // the event sat pending forever with its consequence never applied. The
+        // rollback was correct and unreachable.
+        //
+        // Without the lower bound, "pending and past due" is the whole condition,
+        // which is the same retry semantics timers already have. The `triggered =
+        // 0` filter in the query above is what keeps this exactly-once: a
+        // successful event is marked (or, if recurring, rescheduled forward) in
+        // the same transaction as its consequence, so it cannot come back.
+        if (compareDateTime(triggerTime, newTime, calendarConfig) <= 0) {
             const eventId = row.id;
             const eventName = row.name;
             const recurring = row.recurring;

package/dist/types/index.d.ts

@@ -465,7 +465,7 @@ export interface Resource {
     id: string;
     gameId: string;
     ownerId: string | null;
-    ownerType: "game" | "character";
+    ownerType: "game" | "character" | "faction" | "location";
     name: string;
     description: string;
     category: string | null;
@@ -483,7 +483,24 @@ export interface ResourceChange {
     reason: string | null;
     timestamp: string;
 }
-export type ConstraintKind = "bounded" | "monotonic" | "conserved";
+/** `resolve_only` (design §5.3, §5.2a; issue #13) is the fourth row-based
+ * member: every DIRECT write to the fact key it governs is refused, so the
+ * value can move only through an adjudicating call (issue #10's resolver,
+ * which OPENS the window `src/timeline/adjudication.ts` defines and
+ * `assertConstraintsAllow` / the `timeline_facts_resolve_only` trigger both
+ * read). Unlike `bounded`/`monotonic`/`conserved`, it carries no shape of
+ * its own to check a value against -- `direction` and `total` are always
+ * null for it, exactly as they are for whichever of the OTHER three kinds a
+ * given row isn't. It is scoped per `factKey` like every member of this
+ * family (`resource_constraints.fact_key`, design §5.4 option (C)): a
+ * `resolve_only` constraint declared on one fact key of an entity never
+ * reaches a write to a different fact key of that same entity. */
+export type ConstraintKind = "bounded" | "monotonic" | "conserved" | "resolve_only";
+/** The five members of design §5.3's constraint family. `irreversible` is
+ * never a row in `resource_constraints` -- it is a flag on a fact -- so it is
+ * not a `ConstraintKind`, but it IS something a violation can be reported
+ * for. */
+export type DeclaredConstraintKind = ConstraintKind | "irreversible";
 /** For 'monotonic': the only direction the value is allowed to move. */
 export type MonotonicDirection = "increasing" | "decreasing";
 export interface ResourceConstraint {
@@ -493,6 +510,7 @@ export interface ResourceConstraint {
     resourceIds: string[];
     direction: MonotonicDirection | null;
     total: number | null;
+    factKey: string;
     createdAt: string;
 }
 export interface GameDateTime {

package/dist/utils/media-path.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one place a path beneath a media root is composed or resolved.
+ *
+ * Media file paths are built from ids that arrive over the wire -- a game id,
+ * an entity id, an entity type -- and are then handed to `writeFileSync` and,
+ * worse, to a recursive `rmSync`. `join()` resolves `..` happily, so an id
+ * carrying one walks out of the data directory before the write. The rule this
+ * breaks is the engine's: it writes nothing to the consumer's machine that the
+ * consumer did not name.
+ *
+ * The guard is here, at the composition point, rather than at each call site,
+ * because a per-site check is one forgotten site away from being no check. Two
+ * things are asserted, and both are literal checks over characters -- never an
+ * attempt to read meaning out of a value (root CLAUDE.md hard rule 4):
+ *
+ *   1. Every path segment matches an allowlist. Every id the engine mints is a
+ *      UUID and every entity type is an ASCII word, so the allowlist costs
+ *      nothing the engine actually uses.
+ *   2. The resolved result is strictly beneath the resolved root -- a
+ *      structural backstop that holds even for a path this module did not
+ *      compose, such as one read back out of a row written before this guard
+ *      existed.
+ *
+ * Rejection, never normalisation: an id containing `a/../b` is refused rather
+ * than quietly rewritten to `b`, because the rewrite would silently store one
+ * caller's media under a different id than the caller named.
+ */
+export declare class MediaPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a relative path against a media root, refusing anything that is not
+ * strictly beneath it. Use for paths read back from a row; `mediaFilePath` and
+ * `mediaDirPath` funnel through it too, so every media path in the codebase
+ * passes this check exactly once.
+ */
+export declare function mediaPathWithin(root: string, relativePath: string): string;
+/**
+ * Compose the path of a media file from segments and a leaf file name,
+ * returning both the relative path to store in the row and the full path to
+ * write to.
+ */
+export declare function mediaFilePath(root: string, segments: string[], filename: string): {
+    relativePath: string;
+    fullPath: string;
+};
+/**
+ * Compose the path of a directory beneath a media root. The caller of this one
+ * is a recursive delete, so an empty segment list -- which would resolve to the
+ * media root itself -- is refused along with everything else.
+ */
+export declare function mediaDirPath(root: string, segments: string[]): string;

package/dist/utils/media-path.js

@@ -0,0 +1,106 @@
+import { isAbsolute, join, resolve, sep } from "path";
+import { createLogger } from "./logger.js";
+const log = createLogger("media-path");
+/**
+ * The one place a path beneath a media root is composed or resolved.
+ *
+ * Media file paths are built from ids that arrive over the wire -- a game id,
+ * an entity id, an entity type -- and are then handed to `writeFileSync` and,
+ * worse, to a recursive `rmSync`. `join()` resolves `..` happily, so an id
+ * carrying one walks out of the data directory before the write. The rule this
+ * breaks is the engine's: it writes nothing to the consumer's machine that the
+ * consumer did not name.
+ *
+ * The guard is here, at the composition point, rather than at each call site,
+ * because a per-site check is one forgotten site away from being no check. Two
+ * things are asserted, and both are literal checks over characters -- never an
+ * attempt to read meaning out of a value (root CLAUDE.md hard rule 4):
+ *
+ *   1. Every path segment matches an allowlist. Every id the engine mints is a
+ *      UUID and every entity type is an ASCII word, so the allowlist costs
+ *      nothing the engine actually uses.
+ *   2. The resolved result is strictly beneath the resolved root -- a
+ *      structural backstop that holds even for a path this module did not
+ *      compose, such as one read back out of a row written before this guard
+ *      existed.
+ *
+ * Rejection, never normalisation: an id containing `a/../b` is refused rather
+ * than quietly rewritten to `b`, because the rewrite would silently store one
+ * caller's media under a different id than the caller named.
+ */
+export class MediaPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediaPathError";
+    }
+}
+/** Directory names: ids the engine mints, plus pluralised entity types. */
+const SAFE_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** Leaf file names: a safe stem, one dot, an alphanumeric extension. */
+const SAFE_FILENAME = /^[A-Za-z0-9_-]+\.[A-Za-z0-9]+$/;
+function reject(what, value) {
+    log.warn("Refused a media path built from an unsafe value", { what, value });
+    throw new MediaPathError(`Unsafe ${what} for a media path: ${JSON.stringify(value)}. ` +
+        `Only letters, digits, underscore and hyphen are allowed; a path separator, ` +
+        `"." or ".." would escape the media directory.`);
+}
+function assertSafeSegment(value) {
+    if (typeof value !== "string" || !SAFE_SEGMENT.test(value)) {
+        reject("path segment", String(value));
+    }
+}
+/**
+ * Resolve a relative path against a media root, refusing anything that is not
+ * strictly beneath it. Use for paths read back from a row; `mediaFilePath` and
+ * `mediaDirPath` funnel through it too, so every media path in the codebase
+ * passes this check exactly once.
+ */
+export function mediaPathWithin(root, relativePath) {
+    if (typeof relativePath !== "string" || relativePath.length === 0) {
+        reject("stored path", String(relativePath));
+    }
+    if (isAbsolute(relativePath)) {
+        reject("stored path", relativePath);
+    }
+    // Split on both separators regardless of platform: a stored path composed on
+    // one and read on another must not sneak a traversal past the check.
+    for (const segment of relativePath.split(/[\\/]/)) {
+        if (segment.length === 0 || segment === "." || segment === "..") {
+            reject("stored path", relativePath);
+        }
+    }
+    const rootResolved = resolve(root);
+    const fullPath = resolve(rootResolved, relativePath);
+    // Compare with the separator appended, so a sibling directory whose name
+    // merely starts with the root's (`<root>-elsewhere`) is not mistaken for a
+    // child of it.
+    if (!fullPath.startsWith(rootResolved + sep)) {
+        reject("stored path", relativePath);
+    }
+    return fullPath;
+}
+/**
+ * Compose the path of a media file from segments and a leaf file name,
+ * returning both the relative path to store in the row and the full path to
+ * write to.
+ */
+export function mediaFilePath(root, segments, filename) {
+    segments.forEach(assertSafeSegment);
+    if (typeof filename !== "string" || !SAFE_FILENAME.test(filename)) {
+        reject("file name", String(filename));
+    }
+    const relativePath = join(...segments, filename);
+    return { relativePath, fullPath: mediaPathWithin(root, relativePath) };
+}
+/**
+ * Compose the path of a directory beneath a media root. The caller of this one
+ * is a recursive delete, so an empty segment list -- which would resolve to the
+ * media root itself -- is refused along with everything else.
+ */
+export function mediaDirPath(root, segments) {
+    if (segments.length === 0) {
+        reject("path segment", "");
+    }
+    segments.forEach(assertSafeSegment);
+    return mediaPathWithin(root, join(...segments));
+}