@jgengine/convex 0.17.0 → 0.18.1

package/dist/server.js

@@ -1,11 +1,14 @@
 import { defineSchema, defineTable, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
+import { validateChatMessage } from "@jgengine/core/game/chat";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
-import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
-import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, isPresenceExpired, pickReusablePresence, resolveActivePresence, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
+import { commandScopeEscape, scopeWithActor } from "@jgengine/core/runtime/commandRunner";
+import { createGameRuntime, initialPlayerState } from "@jgengine/core/runtime/gameRuntime";
 import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
 import { JG_MAX_MEMBERS_PER_SERVER, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, selectJoinTarget, statusAfterLeave, validateSlotsPerServer, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
-import { createEmptyServerRow, markAllPlayersDirty } from "@jgengine/core/runtime/snapshot";
+import { createEmptyServerRow } from "@jgengine/core/runtime/snapshot";
+import { chunkKeyAt, parseChunkKey, chunkKeysAround, DEFAULT_CHUNK_SIZE } from "@jgengine/core/runtime/worldChunks";
 import { applyCommandWithOcc, commitIfRevisionMatch } from "./occ.js";
 /** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
 export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, validateSlotsPerServer, } from "@jgengine/core/runtime/hostPolicy";
@@ -23,6 +26,8 @@ export function jgengineTables() {
             modeConfig: v.optional(v.any()),
             visibility: v.optional(v.union(v.literal("public"), v.literal("private"))),
             joinCode: v.optional(v.string()),
+            topology: v.optional(v.union(v.literal("shared"), v.literal("rooms"))),
+            memberCount: v.optional(v.number()),
             memberUserIds: v.array(v.string()),
             slotsPerServer: v.number(),
             save: saveConfigValidator,
@@ -39,10 +44,31 @@ export function jgengineTables() {
             .index("by_status", ["status"])
             .index("by_game_status_tick", ["gameId", "status", "tickAnchorMs"])
             .index("by_dirty", ["dirtyAt"]),
+        jgServerCapacity: defineTable({
+            serverId: v.id("jgGameServers"),
+            gameId: v.string(),
+            status: v.union(v.literal("open"), v.literal("running"), v.literal("closed")),
+            mode: v.optional(v.string()),
+            memberCount: v.number(),
+            slotsPerServer: v.number(),
+        }).index("by_server", ["serverId"]),
+        jgServerMembers: defineTable({
+            serverId: v.id("jgGameServers"),
+            userId: v.string(),
+            joinedAt: v.number(),
+        }).index("by_server", ["serverId"]).index("by_server_and_user", ["serverId", "userId"]),
+        jgRateLimits: defineTable({
+            key: v.string(), startedAt: v.number(), count: v.number(), expiresAt: v.number(),
+        }).index("by_key", ["key"]).index("by_expires", ["expiresAt"]),
+        jgClientErrors: defineTable({
+            userId: v.string(), message: v.string(), details: v.optional(v.any()), createdAt: v.number(),
+        }).index("by_created", ["createdAt"]),
         jgPlayerProfiles: defineTable({
             userId: v.string(),
             gameId: v.string(),
             playerState: v.any(),
+            sessionState: v.optional(v.any()),
+            sessionServerId: v.optional(v.id("jgGameServers")),
             revision: v.number(),
             dirtyAt: v.optional(v.number()),
             createdAt: v.number(),
@@ -76,23 +102,44 @@ export function jgengineTables() {
         }).index("by_server_and_action", ["serverId", "action"]),
         jgPoses: defineTable({
             serverId: v.string(),
+            homeGameId: v.optional(v.string()),
+            ownerActorId: v.optional(v.string()),
+            lastWorldSnapshotAt: v.optional(v.number()),
+            chunkKey: v.optional(v.string()),
             userId: v.string(),
+            /** One row per live session, so a second tab is a second row rather than a fight over one. */
+            sessionId: v.optional(v.string()),
+            /** Actor class, e.g. `"player"` / `"agent"`, which selects the pose rules applied to it. */
+            kind: v.optional(v.string()),
+            /** Display name carried on the row, so nameplates need no per-frame join against users. */
+            label: v.optional(v.string()),
             x: v.number(),
             y: v.number(),
             z: v.number(),
             rotationY: v.number(),
             rotationPitch: v.number(),
             updatedAt: v.number(),
+            /** Set when the session was displaced or left; the reaper deletes the row once it goes idle. */
+            revokedAt: v.optional(v.number()),
         })
             .index("by_server", ["serverId"])
-            .index("by_server_and_user", ["serverId", "userId"]),
+            .index("by_server_and_user", ["serverId", "userId"])
+            .index("by_server_and_chunk", ["serverId", "chunkKey"])
+            .index("by_server_user_revoked_updated", ["serverId", "userId", "revokedAt", "updatedAt"])
+            .index("by_updated", ["updatedAt"])
+            .index("by_user", ["userId"])
+            .index("by_home_game", ["homeGameId"])
+            .index("by_home_game_revoked_updated", ["homeGameId", "revokedAt", "updatedAt"])
+            .index("by_revoked", ["revokedAt"])
+            .index("by_revoked_updated", ["revokedAt", "updatedAt"]),
         jgChatMessages: defineTable({
             serverId: v.string(),
             channelId: v.string(),
             userId: v.string(),
             body: v.string(),
+            authorName: v.optional(v.string()),
             at: v.number(),
-        }).index("by_server_channel", ["serverId", "channelId"]),
+        }).index("by_server_channel", ["serverId", "channelId", "at"]).index("by_at", ["at"]),
     };
 }
 /**
@@ -141,11 +188,19 @@ export async function resolveActor(ctx, claimedExternalId, mode) {
     }
     return null;
 }
+async function hasMember(ctx, server, userId) {
+    if (server.memberUserIds.includes(userId))
+        return true;
+    if (server.topology !== "shared")
+        return false;
+    return (await ctx.db.query("jgServerMembers")
+        .withIndex("by_server_and_user", q => q.eq("serverId", server._id).eq("userId", userId)).unique()) !== null;
+}
 async function requireServerMember(ctx, serverId, actorUserId) {
     const server = await ctx.db.get("jgGameServers", serverId);
     if (!server)
         return null;
-    if (!isServerMember(server.memberUserIds, actorUserId))
+    if (!(await hasMember(ctx, server, actorUserId)))
         return null;
     return server;
 }
@@ -219,6 +274,21 @@ function serverDocToRecord(server) {
         updatedAt: server.updatedAt,
     };
 }
+async function serverCapacity(ctx, server) {
+    return server.topology === "shared"
+        ? ctx.db.query("jgServerCapacity").withIndex("by_server", q => q.eq("serverId", server._id)).unique()
+        : null;
+}
+async function ensureServerCapacity(ctx, server) {
+    const existing = await serverCapacity(ctx, server);
+    if (existing)
+        return existing;
+    const id = await ctx.db.insert("jgServerCapacity", {
+        serverId: server._id, gameId: server.gameId, status: server.status, mode: server.mode,
+        memberCount: server.memberCount ?? server.memberUserIds.length, slotsPerServer: server.slotsPerServer,
+    });
+    return (await ctx.db.get("jgServerCapacity", id));
+}
 /**
  * Hydrate a server's `GameRuntimeSnapshot` from its row, its members' profiles, and its world chunks.
  * Reach for it when writing your own mutation that must read runtime state before touching host tables.
@@ -228,14 +298,27 @@ function serverDocToRecord(server) {
 export async function loadServerSnapshot(ctx, server, runtime, scope) {
     const profiles = {};
     const memberIds = new Set(server.memberUserIds);
-    const hydrateUserIds = scope?.players === undefined
-        ? server.memberUserIds
-        : scope.players.filter((userId) => memberIds.has(userId));
+    let hydrateUserIds;
+    if (server.topology === "shared") {
+        const requested = scope?.players ?? (await ctx.db.query("jgServerMembers")
+            .withIndex("by_server", q => q.eq("serverId", server._id)).collect()).map(row => row.userId);
+        hydrateUserIds = [];
+        for (const userId of new Set(requested))
+            if (await hasMember(ctx, server, userId))
+                hydrateUserIds.push(userId);
+    }
+    else {
+        hydrateUserIds = scope?.players === undefined ? server.memberUserIds : scope.players.filter(userId => memberIds.has(userId));
+    }
+    const sessionPlayers = {};
     for (const userId of hydrateUserIds) {
         const profile = await ctx.db
             .query("jgPlayerProfiles")
             .withIndex("by_user_and_game", (q) => q.eq("userId", userId).eq("gameId", server.gameId))
             .unique();
+        if (server.topology === "shared" && profile) {
+            sessionPlayers[userId] = { ...profile.playerState, ...(profile.sessionServerId === server._id ? { session: profile.sessionState ?? {} } : { session: {} }) };
+        }
         profiles[userId] = profile
             ? {
                 userId,
@@ -246,7 +329,7 @@ export async function loadServerSnapshot(ctx, server, runtime, scope) {
             }
             : null;
     }
-    const playersByUserId = buildHydratePlayers(serverDocToRecord(server), profiles, hydrateUserIds);
+    const playersByUserId = buildHydratePlayers(server.topology === "shared" ? { ...serverDocToRecord(server), memberUserIds: hydrateUserIds, sessionPlayers } : serverDocToRecord(server), profiles, hydrateUserIds);
     const chunksByKey = {};
     if (scope?.chunkKeys === undefined) {
         const chunks = await ctx.db
@@ -313,7 +396,9 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
  */
 export async function persistServerSnapshot(ctx, server, snapshot, save) {
     const now = Date.now();
-    const plan = planServerPersist(serverDocToRecord(server), snapshot, save, now);
+    const shared = server.topology === "shared";
+    const record = serverDocToRecord(server);
+    const plan = planServerPersist(shared ? { ...record, memberUserIds: Object.keys(snapshot.players), sessionPlayers: {} } : record, snapshot, save, now);
     if (!plan.changed.any)
         return false;
     if (plan.leaderboard.length > 0) {
@@ -326,6 +411,7 @@ export async function persistServerSnapshot(ctx, server, snapshot, save) {
             .unique();
         const profilePatch = {
             playerState: profile.playerState,
+            ...(shared ? { sessionState: snapshot.players[profile.userId]?.session ?? {}, sessionServerId: server._id } : {}),
             revision: profile.revision,
             updatedAt: profile.updatedAt,
         };
@@ -341,6 +427,22 @@ export async function persistServerSnapshot(ctx, server, snapshot, save) {
             });
         }
     }
+    if (shared) {
+        const persisted = new Set(plan.profiles.map(profile => profile.userId));
+        for (const userId of snapshot.dirty.players) {
+            if (persisted.has(userId))
+                continue;
+            const player = snapshot.players[userId];
+            if (!player)
+                continue;
+            const existing = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
+            const patch = { playerState: player, sessionState: player.session, sessionServerId: server._id, revision: snapshot.revision, updatedAt: now };
+            if (existing)
+                await ctx.db.patch(existing._id, patch);
+            else
+                await ctx.db.insert("jgPlayerProfiles", { userId, gameId: server.gameId, createdAt: now, ...patch });
+        }
+    }
     for (const chunk of plan.chunks) {
         const existing = await ctx.db
             .query("jgWorldChunks")
@@ -370,23 +472,25 @@ export async function persistServerSnapshot(ctx, server, snapshot, save) {
         if (existing)
             await ctx.db.delete(existing._id);
     }
-    await ctx.db.patch(server._id, {
-        ...(plan.changed.serverState ? { serverState: plan.server.serverState } : {}),
-        ...(plan.changed.sessionPlayers ? { sessionPlayers: plan.server.sessionPlayers } : {}),
-        revision: plan.server.revision,
-        dirtyAt: plan.server.dirtyAt,
-        updatedAt: plan.server.updatedAt,
-        lastSavedAt: plan.server.lastSavedAt,
-    });
+    if (!shared || plan.changed.serverState)
+        await ctx.db.patch(server._id, {
+            ...(plan.changed.serverState ? { serverState: plan.server.serverState } : {}),
+            ...(!shared && plan.changed.sessionPlayers ? { sessionPlayers: plan.server.sessionPlayers } : {}),
+            revision: plan.server.revision,
+            dirtyAt: plan.server.dirtyAt,
+            updatedAt: plan.server.updatedAt,
+            lastSavedAt: plan.server.lastSavedAt,
+        });
     return true;
 }
 /** Autosave a server whose `save.auto` interval has elapsed, reusing an already-hydrated snapshot. */
-async function flushServerIfDue(ctx, server, now, runtime, loaded) {
+async function flushServerIfDue(ctx, server, now, _runtime, loaded) {
     if (!shouldAutoSave(server.save, server.dirtyAt, server.lastSavedAt, now)) {
         return false;
     }
-    const snapshot = loaded ?? (await loadServerSnapshot(ctx, server, runtime));
-    await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
+    if (loaded)
+        await persistServerSnapshot(ctx, server, loaded, server.save);
+    await ctx.db.patch(server._id, { dirtyAt: undefined, lastSavedAt: now });
     return true;
 }
 export const JG_RUNTIME_TICK_MS = 1_000;
@@ -397,10 +501,9 @@ export const MAX_CHUNKS_PER_QUERY = 64;
 /**
  * Build the hosted-server Convex functions for a set of game runtimes.
  *
- * **Supported world size.** One server is one Convex document holding the world row, the member
- * roster, and every member's session state, and the host rewrites that document whenever the world
- * changes. `slotsPerServer` is therefore capped at {@link JG_MAX_MEMBERS_PER_SERVER} (256) and a
- * larger value throws here, at wiring time, rather than at the write that overflows the document.
+ * Room topology keeps its roster and session map in the server document and caps capacity at
+ * {@link JG_MAX_MEMBERS_PER_SERVER}. Shared topology stores membership, capacity, and per-player
+ * session state separately; player-only commands and roster changes do not rewrite the world row.
  * World geometry that outgrows one row belongs in `jgWorldChunks`, hydrated by key
  * ({@link LoadSnapshotScope}) and read by clients through `getChunks` — not in `serverState`.
  *
@@ -410,11 +513,12 @@ export const MAX_CHUNKS_PER_QUERY = 64;
  */
 export function createGameServerFunctions(options) {
     const mode = options?.auth ?? "required";
-    const hostSlotsPerServer = options?.slotsPerServer ?? 16;
-    const slotsCheck = validateSlotsPerServer(hostSlotsPerServer);
+    const shared = options?.topology === "shared" || (options?.topology === undefined && (options?.runtimes?.some(runtime => runtime.topology === "shared") ?? false));
+    const hostSlotsPerServer = shared ? Number.MAX_SAFE_INTEGER : options?.slotsPerServer ?? 16;
+    const slotsCheck = validateSlotsPerServer(hostSlotsPerServer, shared ? "shared" : "rooms");
     if (!slotsCheck.ok)
         throw new Error(slotsCheck.reason);
-    const matchmaking = options?.matchmaking ?? "auto";
+    const matchmaking = options?.matchmaking ?? (shared ? "singleton" : "auto");
     const maxServersPerTick = Math.max(1, options?.maxServersPerTick ?? DEFAULT_MAX_SERVERS_PER_TICK);
     const feedWriteGate = createFeedWriteGate(options?.allowedFeedActions ?? []);
     const registry = buildRuntimeRegistry(options?.runtimes);
@@ -431,23 +535,24 @@ export function createGameServerFunctions(options) {
             joinCode: v.optional(v.string()),
             externalId: v.optional(v.string()),
         },
-        returns: v.object({
-            serverId: v.id("jgGameServers"),
-            isNew: v.boolean(),
-        }),
+        returns: v.union(v.object({ ok: v.literal(true), serverId: v.id("jgGameServers"), isNew: v.boolean() }), v.object({ ok: v.literal(false), reason: v.union(v.literal("full"), v.literal("closed"), v.literal("unauthorized")) })),
         handler: async (ctx, args) => {
-            const actorUserId = await requireActor(ctx, args.externalId, mode);
+            const actorUserId = await resolveActor(ctx, args.externalId, mode);
+            if (!actorUserId)
+                return { ok: false, reason: "unauthorized" };
             const now = Date.now();
             const runtime = resolveRuntime(registry, args.gameId);
             const save = runtime.save;
             const slotsPerServer = hostSlotsPerServer;
             let server = args.serverId !== undefined ? await ctx.db.get("jgGameServers", args.serverId) : null;
             if (args.serverId !== undefined && !server) {
-                throw new ConvexError("Server not found");
+                return { ok: false, reason: "closed" };
             }
             if (server && server.gameId !== args.gameId) {
-                throw new ConvexError("Server belongs to a different game");
+                return { ok: false, reason: "unauthorized" };
             }
+            if (server?.status === "closed")
+                return { ok: false, reason: "closed" };
             let mayCreate = true;
             if (!server) {
                 const joinable = [];
@@ -455,7 +560,7 @@ export function createGameServerFunctions(options) {
                     const rows = await ctx.db
                         .query("jgGameServers")
                         .withIndex("by_game_and_status", (q) => q.eq("gameId", args.gameId).eq("status", status))
-                        .collect();
+                        .take(100);
                     joinable.push(...rows);
                 }
                 // Two concurrent first-joins can both see an empty list here and both insert. Convex's OCC
@@ -468,7 +573,7 @@ export function createGameServerFunctions(options) {
                     slotsPerServer,
                 });
                 if (target.kind === "refuse")
-                    throw new ConvexError(target.reason);
+                    return { ok: false, reason: "full" };
                 server = target.kind === "join" ? target.row : null;
                 mayCreate = target.kind === "create";
             }
@@ -480,6 +585,8 @@ export function createGameServerFunctions(options) {
                     modeConfig: args.modeConfig,
                     visibility: args.visibility ?? "public",
                     joinCode: args.joinCode,
+                    topology: shared ? "shared" : "rooms",
+                    memberCount: 0,
                     memberUserIds: [],
                     slotsPerServer,
                     save,
@@ -505,37 +612,64 @@ export function createGameServerFunctions(options) {
                     throw new ConvexError("Server missing after reconcile");
                 server = reconciled;
             }
-            if (isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
-                throw new ConvexError("Server is full");
+            if (!shared && isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
+                return { ok: false, reason: "full" };
             }
             if (isPrivateJoinBlocked({
                 visibility: server.visibility,
-                memberUserIds: server.memberUserIds,
+                memberUserIds: await hasMember(ctx, server, actorUserId) ? [actorUserId] : [],
                 userId: actorUserId,
                 joinCode: server.joinCode,
                 suppliedCode: args.joinCode,
             })) {
-                throw new ConvexError("Server is private");
+                return { ok: false, reason: "unauthorized" };
             }
-            const profile = await ctx.db
+            let profile = await ctx.db
                 .query("jgPlayerProfiles")
                 .withIndex("by_user_and_game", (q) => q.eq("userId", actorUserId).eq("gameId", args.gameId))
                 .unique();
+            if (shared && server.topology !== "shared") {
+                for (const userId of server.memberUserIds) {
+                    const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", server._id).eq("userId", userId)).unique();
+                    if (!member)
+                        await ctx.db.insert("jgServerMembers", { serverId: server._id, userId, joinedAt: now });
+                    const state = server.sessionPlayers[userId];
+                    if (!state)
+                        continue;
+                    const stored = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
+                    const patch = { sessionState: state.session ?? {}, sessionServerId: server._id };
+                    if (stored)
+                        await ctx.db.patch(stored._id, patch);
+                    else
+                        await ctx.db.insert("jgPlayerProfiles", { userId, gameId: server.gameId, playerState: state, revision: server.revision, createdAt: now, updatedAt: now, ...patch });
+                }
+                await ctx.db.patch(server._id, { topology: "shared", memberCount: server.memberUserIds.length, memberUserIds: [], sessionPlayers: {} });
+                server = (await ctx.db.get("jgGameServers", server._id));
+                profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", actorUserId).eq("gameId", args.gameId)).unique();
+            }
             const isNew = profile === null;
             const memberUserIds = withJoinedMember(server.memberUserIds, actorUserId);
-            await ctx.db.patch(server._id, {
-                memberUserIds,
-                status: "running",
-                updatedAt: now,
-                dirtyAt: now,
-            });
+            if (shared) {
+                const capacity = await ensureServerCapacity(ctx, server);
+                const isMember = await hasMember(ctx, server, actorUserId);
+                await ctx.db.patch(capacity._id, {
+                    memberCount: capacity.memberCount + (isMember ? 0 : 1), status: "running", slotsPerServer,
+                });
+                if (!isMember)
+                    await ctx.db.insert("jgServerMembers", { serverId: server._id, userId: actorUserId, joinedAt: now });
+                if (server.status !== "running")
+                    await ctx.db.patch(server._id, { status: "running" });
+            }
+            else {
+                await ctx.db.patch(server._id, { memberUserIds, status: "running", updatedAt: now });
+            }
             const refreshed = await ctx.db.get("jgGameServers", server._id);
             if (!refreshed)
                 throw new ConvexError("Server missing after join");
-            let snapshot = await loadServerSnapshot(ctx, refreshed, runtime);
-            snapshot = runtime.joinPlayer(snapshot, actorUserId, isNew);
+            let snapshot = await loadServerSnapshot(ctx, refreshed, runtime, scopeWithActor(runtime.joinScope(actorUserId, isNew), actorUserId));
+            snapshot = runtime.joinPlayer(snapshot, actorUserId, isNew, now);
             await persistServerSnapshot(ctx, refreshed, snapshot, save);
-            return { serverId: refreshed._id, isNew };
+            return { ok: true, serverId: refreshed._id, isNew };
         },
     });
     const leaveServer = mutation({
@@ -551,28 +685,74 @@ export function createGameServerFunctions(options) {
                 return null;
             const now = Date.now();
             const runtime = resolveRuntime(registry, server.gameId);
-            const snapshot = await loadServerSnapshot(ctx, server, runtime);
+            // Flushes the leaver's own state before the roster drops them; nobody else's rows are touched.
+            const snapshot = await loadServerSnapshot(ctx, server, runtime, {
+                players: [actorUserId],
+                chunkKeys: [],
+            });
             await persistServerSnapshot(ctx, server, snapshot, server.save);
             const memberUserIds = withoutMember(server.memberUserIds, actorUserId);
             const sessionPlayers = { ...server.sessionPlayers };
             delete sessionPlayers[actorUserId];
-            await ctx.db.patch(server._id, {
-                memberUserIds,
-                sessionPlayers,
-                updatedAt: now,
-                dirtyAt: now,
-                status: statusAfterLeave(memberUserIds.length, server.status),
-            });
-            const pose = await ctx.db
+            if (server.topology === "shared") {
+                const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", server._id).eq("userId", actorUserId)).unique();
+                if (member) {
+                    const capacity = await ensureServerCapacity(ctx, server);
+                    await ctx.db.delete(member._id);
+                    await ctx.db.patch(capacity._id, { memberCount: Math.max(0, capacity.memberCount - 1) });
+                    const profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", actorUserId).eq("gameId", server.gameId)).unique();
+                    if (profile?.sessionServerId === server._id)
+                        await ctx.db.patch(profile._id, { sessionState: {}, sessionServerId: undefined });
+                }
+            }
+            else {
+                await ctx.db.patch(server._id, { memberUserIds, sessionPlayers, updatedAt: now, status: statusAfterLeave(memberUserIds.length, server.status) });
+            }
+            const poses = await ctx.db
                 .query("jgPoses")
                 .withIndex("by_server_and_user", (q) => q.eq("serverId", args.serverId).eq("userId", actorUserId))
-                .unique();
-            if (pose)
+                .collect();
+            for (const pose of poses)
                 await ctx.db.delete(pose._id);
             return null;
         },
     });
     const helpers = {
+        async ensureServer(ctx, gameId) {
+            if (!shared || matchmaking !== "singleton")
+                throw new Error("ensureServer requires a shared singleton host");
+            for (const status of ["running", "open"]) {
+                const existing = await ctx.db.query("jgGameServers").withIndex("by_game_and_status", q => q.eq("gameId", gameId).eq("status", status)).first();
+                if (existing)
+                    return existing;
+            }
+            const runtime = resolveRuntime(registry, gameId);
+            const now = Date.now();
+            const id = await ctx.db.insert("jgGameServers", {
+                gameId, topology: "shared", status: "running", memberUserIds: [], slotsPerServer: hostSlotsPerServer,
+                save: runtime.save, serverState: defaultServerStateForGame(gameId), sessionPlayers: {}, revision: 0,
+                tickAnchorMs: now, createdAt: now, updatedAt: now,
+            });
+            const server = (await ctx.db.get("jgGameServers", id));
+            await ensureServerCapacity(ctx, server);
+            return server;
+        },
+        async resetPlayerProfile(ctx, serverId, userId) {
+            const server = await requireServerMember(ctx, serverId, userId);
+            if (!server)
+                throw new ConvexError("Not a member of this server");
+            const state = initialPlayerState(resolveRuntime(registry, server.gameId), userId);
+            const profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
+            const now = Date.now();
+            const patch = { playerState: state, sessionState: state.session, sessionServerId: server._id, revision: (profile?.revision ?? 0) + 1, updatedAt: now };
+            if (profile)
+                await ctx.db.patch(profile._id, patch);
+            else
+                await ctx.db.insert("jgPlayerProfiles", { userId, gameId: server.gameId, createdAt: now, ...patch });
+            if (server.topology !== "shared")
+                await ctx.db.patch(server._id, { sessionPlayers: { ...server.sessionPlayers, [userId]: state } });
+            return state;
+        },
         async loadSnapshot(ctx, serverId, scope) {
             const server = await ctx.db.get("jgGameServers", serverId);
             if (!server)
@@ -587,18 +767,19 @@ export function createGameServerFunctions(options) {
             return persistServerSnapshot(ctx, server, snapshot, save ?? server.save);
         },
         async runCommand(ctx, args) {
-            const actorUserId = await requireActor(ctx, args.externalId, mode);
+            const actorUserId = args.actorUserId ?? await requireActor(ctx, args.externalId, mode);
             const serverId = args.serverId;
             const server = await ctx.db.get("jgGameServers", serverId);
             if (!server) {
                 return { ok: false, reason: "Server not found" };
             }
-            if (!isServerMember(server.memberUserIds, actorUserId)) {
+            if (!(await hasMember(ctx, server, actorUserId))) {
                 return { ok: false, reason: "Not a member of this server" };
             }
             const loadedRevision = server.revision;
             const runtime = resolveRuntime(registry, server.gameId);
-            const snapshot = await loadServerSnapshot(ctx, server, runtime);
+            const scope = scopeWithActor(args.scope ?? runtime.commandScope(args.command, args.input, actorUserId), actorUserId);
+            const snapshot = await loadServerSnapshot(ctx, server, runtime, scope);
             const result = applyCommandWithOcc({
                 loadedRevision,
                 currentRevision: server.revision,
@@ -611,6 +792,10 @@ export function createGameServerFunctions(options) {
             if (!result.ok) {
                 return result;
             }
+            const escape = commandScopeEscape(scope, result.snapshot.dirty, args.command);
+            if (escape !== null) {
+                return { ok: false, reason: escape };
+            }
             const latest = await ctx.db.get("jgGameServers", serverId);
             if (!latest) {
                 return { ok: false, reason: "Server not found" };
@@ -619,6 +804,10 @@ export function createGameServerFunctions(options) {
             if (!commit.ok) {
                 return commit;
             }
+            await args.beforePersist?.(ctx, { server: latest, runtime, snapshot: result.snapshot });
+            const callbackEscape = commandScopeEscape(scope, result.snapshot.dirty, args.command);
+            if (callbackEscape !== null)
+                throw new ConvexError(callbackEscape);
             await persistServerSnapshot(ctx, latest, result.snapshot, latest.save);
             return { ok: true };
         },
@@ -629,9 +818,13 @@ export function createGameServerFunctions(options) {
             command: v.string(),
             input: v.any(),
             externalId: v.optional(v.string()),
+            scope: v.optional(v.object({
+                players: v.optional(v.array(v.string())),
+                chunkKeys: v.optional(v.array(v.string())),
+            })),
         },
         returns: v.union(v.object({ ok: v.literal(true) }), v.object({ ok: v.literal(false), reason: v.string() })),
-        handler: (ctx, args) => helpers.runCommand(ctx, args),
+        handler: (ctx, args) => helpers.runCommand(ctx, { serverId: args.serverId, command: args.command, input: args.input, externalId: args.externalId }),
     });
     const flushSave = mutation({
         args: {
@@ -644,9 +837,7 @@ export function createGameServerFunctions(options) {
             const server = await requireServerMember(ctx, args.serverId, actorUserId);
             if (server === null)
                 return false;
-            const runtime = resolveRuntime(registry, server.gameId);
-            const snapshot = await loadServerSnapshot(ctx, server, runtime);
-            await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
+            await ctx.db.patch(server._id, { dirtyAt: undefined, lastSavedAt: Date.now() });
             return true;
         },
     });
@@ -702,20 +893,38 @@ export function createGameServerFunctions(options) {
             mode: v.optional(v.string()),
             memberCount: v.number(),
             slotsPerServer: v.number(),
-            revision: v.number(),
-            updatedAt: v.number(),
         }), v.null()),
-        handler: (ctx, args) => withMember(ctx, mode, args, null, (server) => ({
+        handler: (ctx, args) => withMember(ctx, mode, args, null, async (server) => ({
             _id: server._id,
             gameId: server.gameId,
             status: server.status,
             mode: server.mode,
-            memberCount: server.memberUserIds.length,
+            memberCount: (await serverCapacity(ctx, server))?.memberCount ?? server.memberCount ?? server.memberUserIds.length,
             slotsPerServer: server.slotsPerServer,
-            revision: server.revision,
-            updatedAt: server.updatedAt,
         })),
     });
+    const getServerCapacity = query({
+        args: { serverId: v.id("jgGameServers"), externalId: v.optional(v.string()) },
+        returns: v.union(v.object({
+            _id: v.id("jgGameServers"), gameId: v.string(),
+            status: v.union(v.literal("open"), v.literal("running"), v.literal("closed")),
+            mode: v.optional(v.string()), memberCount: v.number(), slotsPerServer: v.number(),
+        }), v.null()),
+        handler: async (ctx, args) => {
+            const actor = await resolveActor(ctx, args.externalId, mode);
+            if (!actor)
+                return null;
+            const capacity = await ctx.db.query("jgServerCapacity").withIndex("by_server", q => q.eq("serverId", args.serverId)).unique();
+            if (capacity) {
+                const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", args.serverId).eq("userId", actor)).unique();
+                if (!member)
+                    return null;
+                return { _id: capacity.serverId, gameId: capacity.gameId, status: capacity.status, mode: capacity.mode, memberCount: capacity.memberCount, slotsPerServer: capacity.slotsPerServer };
+            }
+            const server = await requireServerMember(ctx, args.serverId, actor);
+            return server ? { _id: server._id, gameId: server.gameId, status: server.status, mode: server.mode, memberCount: server.memberUserIds.length, slotsPerServer: server.slotsPerServer } : null;
+        },
+    });
     /**
      * Read world chunks by key — the client half of the chunk escape hatch. Without it a game that moved
      * geometry out of `serverState` had no way to show it, because `getServer` returns only the row.
@@ -849,17 +1058,17 @@ export function createGameServerFunctions(options) {
                 .query("jgGameServers")
                 .withIndex("by_game_and_status", (q) => q.eq("gameId", args.gameId).eq("status", "running"))
                 .take(Math.min(limit * 4, 200));
-            return rows
+            return Promise.all(rows
                 .filter((row) => isListablePublicly(row.visibility))
                 .slice(0, limit)
-                .map((row) => ({
+                .map(async (row) => ({
                 _id: row._id,
                 status: row.status,
-                memberCount: row.memberUserIds.length,
+                memberCount: (await serverCapacity(ctx, row))?.memberCount ?? row.memberCount ?? row.memberUserIds.length,
                 slotsPerServer: row.slotsPerServer,
                 mode: row.mode,
                 updatedAt: row.updatedAt,
-            }));
+            })));
         },
     });
     // Only games that declare `loop.onTick` are swept, and only `maxServersPerTick` of their servers per
@@ -881,15 +1090,16 @@ export function createGameServerFunctions(options) {
                     .withIndex("by_game_status_tick", (q) => q.eq("gameId", gameId).eq("status", "running"))
                     .take(budget);
                 for (const server of servers) {
-                    if (server.memberUserIds.length === 0)
+                    if (((await serverCapacity(ctx, server))?.memberCount ?? server.memberCount ?? server.memberUserIds.length) === 0)
                         continue;
                     const elapsedMs = now - server.tickAnchorMs;
                     if (elapsedMs < JG_RUNTIME_TICK_MS)
                         continue;
                     budget -= 1;
                     const runtime = resolveRuntime(registry, server.gameId);
+                    // Unscoped on purpose: onTick is handed the whole world and may touch any of it.
                     const loaded = await loadServerSnapshot(ctx, server, runtime);
-                    const snapshot = runtime.tick(loaded, elapsedMs / 1_000);
+                    const snapshot = runtime.tick(loaded, elapsedMs / 1_000, now);
                     await persistServerSnapshot(ctx, server, snapshot, server.save);
                     await ctx.db.patch(server._id, { tickAnchorMs: now });
                     ticked += 1;
@@ -911,9 +1121,7 @@ export function createGameServerFunctions(options) {
                 .take(maxServersPerTick);
             let saved = 0;
             for (const server of servers) {
-                const runtime = resolveRuntime(registry, server.gameId);
-                const snapshot = await loadServerSnapshot(ctx, server, runtime);
-                await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
+                await ctx.db.patch(server._id, { dirtyAt: undefined, lastSavedAt: Date.now() });
                 saved += 1;
             }
             return { saved };
@@ -926,6 +1134,7 @@ export function createGameServerFunctions(options) {
         flushSave,
         getServer,
         getServerMeta,
+        getServerCapacity,
         getChunks,
         getPlayerProfile,
         getFeed,
@@ -1002,34 +1211,63 @@ export function createLeaderboardFunctions(options) {
     });
     return { getTop, getProfile, incrementMany };
 }
-/** @internal */
+/**
+ * The pose lane of a hosted server: the backend behind `PresenceSync`, which replicates where each
+ * member of one `jgGameServers` server is standing. It is not the backend for `PresenceTransport` —
+ * that contract (`ConvexPresenceFunctions` in `./convexPresenceTransport`) is a game-owned world's
+ * own presence, keyed by the game's own ids, with its own notion of who counts as a resident. A game
+ * on `createConvexPresenceTransport` supplies those functions itself; these do not substitute for them.
+ * @internal
+ */
 export function createPresenceFunctions(options) {
     const mode = options?.auth ?? "required";
     const freshWindowMs = options?.freshWindowMs ?? 10_000;
-    const poseRules = options?.poseRules ?? DEFAULT_CONVEX_POSE_RULES;
+    const idleCutoffMs = options?.idleCutoffMs ?? 60_000;
+    const maxReapPerRun = options?.maxReapPerRun ?? 256;
+    const rulesOption = options?.poseRules ?? DEFAULT_CONVEX_POSE_RULES;
+    const rulesFor = (kind) => typeof rulesOption === "function" ? rulesOption(kind) : rulesOption;
+    const poseValidator = v.object({
+        x: v.number(),
+        y: v.number(),
+        z: v.number(),
+        rotationY: v.number(),
+        rotationPitch: v.number(),
+    });
     const list = query({
         args: {
             serverId: v.string(),
+            viewerChunkKey: v.optional(v.string()),
             externalId: v.optional(v.string()),
         },
         returns: v.array(v.object({
             userId: v.string(),
+            sessionId: v.optional(v.string()),
+            kind: v.optional(v.string()),
+            label: v.optional(v.string()),
             position: v.object({ x: v.number(), y: v.number(), z: v.number() }),
             rotationY: v.number(),
             rotationPitch: v.number(),
             lastSeenAt: v.number(),
         })),
         handler: async (ctx, args) => {
-            return withMember(ctx, mode, args, [], async () => {
+            return withMember(ctx, mode, args, [], async (_server, actorUserId) => {
                 const threshold = Date.now() - freshWindowMs;
-                const rows = await ctx.db
-                    .query("jgPoses")
-                    .withIndex("by_server", (q) => q.eq("serverId", args.serverId))
-                    .collect();
+                const own = args.viewerChunkKey === undefined ? await ctx.db.query("jgPoses")
+                    .withIndex("by_server_and_user", q => q.eq("serverId", args.serverId).eq("userId", actorUserId)).first() : null;
+                const center = parseChunkKey(args.viewerChunkKey ?? (own ? chunkKeyAt([own.x, own.y, own.z]) : "0,0"));
+                if (!center)
+                    return [];
+                const rows = [];
+                for (const chunkKey of chunkKeysAround([center.cx * DEFAULT_CHUNK_SIZE, 0, center.cz * DEFAULT_CHUNK_SIZE], 1)) {
+                    rows.push(...await ctx.db.query("jgPoses").withIndex("by_server_and_chunk", q => q.eq("serverId", args.serverId).eq("chunkKey", chunkKey)).take(256));
+                }
                 return rows
-                    .filter((row) => row.updatedAt >= threshold)
+                    .filter((row) => row.revokedAt === undefined && row.updatedAt >= threshold)
                     .map((row) => ({
                     userId: row.userId,
+                    sessionId: row.sessionId,
+                    kind: row.kind,
+                    label: row.label,
                     position: { x: row.x, y: row.y, z: row.z },
                     rotationY: row.rotationY,
                     rotationPitch: row.rotationPitch,
@@ -1038,60 +1276,105 @@ export function createPresenceFunctions(options) {
             });
         },
     });
+    /**
+     * Upload a pose, or keep the session alive without one. Returns the pose the server actually holds
+     * after clamping, so a corrected client can reconcile, plus whether this session had been revoked
+     * by another of the same user's sessions since its last sync.
+     */
     const sync = mutation({
         args: {
             serverId: v.string(),
-            pose: v.object({
-                x: v.number(),
-                y: v.number(),
-                z: v.number(),
-                rotationY: v.number(),
-                rotationPitch: v.number(),
-            }),
+            pose: v.optional(poseValidator),
+            sessionId: v.optional(v.string()),
+            kind: v.optional(v.string()),
+            label: v.optional(v.string()),
             externalId: v.optional(v.string()),
         },
-        returns: v.null(),
+        returns: v.union(v.null(), v.object({
+            pose: poseValidator,
+            lastSeenAt: v.number(),
+            displaced: v.boolean(),
+        })),
         handler: (ctx, args) => withMember(ctx, mode, args, null, async (_server, actorUserId) => {
             const now = Date.now();
-            const existing = await ctx.db
+            const rows = await ctx.db
                 .query("jgPoses")
                 .withIndex("by_server_and_user", (q) => q.eq("serverId", args.serverId).eq("userId", actorUserId))
-                .unique();
-            const current = existing === null
-                ? spawnPresenceState(undefined, now, poseRules)
+                .collect();
+            const resolvable = rows.map((row) => ({
+                row,
+                revokedAt: row.revokedAt,
+                lastSeenAt: row.updatedAt,
+            }));
+            const existing = args.sessionId === undefined
+                ? (resolveActivePresence(resolvable).active ?? pickReusablePresence(resolvable))?.row
+                : rows.find((row) => row.sessionId === args.sessionId);
+            const rules = rulesFor(args.kind ?? existing?.kind);
+            if (existing && now - existing.updatedAt < (rules.minIntervalMs ?? 100)) {
+                return { pose: { x: existing.x, y: existing.y, z: existing.z, rotationY: existing.rotationY, rotationPitch: existing.rotationPitch }, lastSeenAt: existing.updatedAt, displaced: existing.revokedAt !== undefined };
+            }
+            const current = existing === undefined
+                ? spawnPresenceState((await options?.resolveSpawn?.(ctx, {
+                    serverId: args.serverId,
+                    userId: actorUserId,
+                    kind: args.kind,
+                })) ?? undefined, now, rules)
                 : {
                     position: { x: existing.x, y: existing.y, z: existing.z },
                     rotationY: existing.rotationY,
                     rotationPitch: existing.rotationPitch,
                     lastSeenAtMs: existing.updatedAt,
                 };
-            const decision = decidePoseSync(current, {
-                position: { x: args.pose.x, y: args.pose.y, z: args.pose.z },
-                rotationY: args.pose.rotationY,
-                rotationPitch: args.pose.rotationPitch,
-            }, poseRules, now);
-            const patch = {
+            // A pose-less call is a keep-alive: hold the stored pose and only move the stamp forward.
+            const decision = decidePoseSync(current, args.pose === undefined
+                ? { position: current.position, rotationY: current.rotationY, rotationPitch: current.rotationPitch }
+                : {
+                    position: { x: args.pose.x, y: args.pose.y, z: args.pose.z },
+                    rotationY: args.pose.rotationY,
+                    rotationPitch: args.pose.rotationPitch,
+                }, rules, now);
+            const pose = {
                 x: decision.position.x,
                 y: decision.position.y,
                 z: decision.position.z,
                 rotationY: decision.rotationY,
                 rotationPitch: decision.rotationPitch,
-                updatedAt: now,
             };
+            const identity = {
+                ...(args.sessionId === undefined ? {} : { sessionId: args.sessionId }),
+                ...(args.kind === undefined ? {} : { kind: args.kind }),
+                ...(args.label === undefined ? {} : { label: args.label }),
+            };
+            const displaced = existing?.revokedAt !== undefined;
             if (existing) {
-                if (decision.changed || decision.refreshKeepAlive) {
-                    await ctx.db.patch(existing._id, patch);
+                if (decision.changed || decision.refreshKeepAlive || displaced || Object.keys(identity).length > 0) {
+                    await ctx.db.patch(existing._id, { ...pose, ...identity, chunkKey: chunkKeyAt([pose.x, pose.y, pose.z]), updatedAt: now, revokedAt: undefined });
                 }
             }
             else {
-                await ctx.db.insert("jgPoses", { serverId: args.serverId, userId: actorUserId, ...patch });
+                await ctx.db.insert("jgPoses", {
+                    serverId: args.serverId,
+                    userId: actorUserId,
+                    ...pose,
+                    chunkKey: chunkKeyAt([pose.x, pose.y, pose.z]),
+                    ...identity,
+                    updatedAt: now,
+                });
             }
-            return null;
+            // This session is the live one; any other session of the same user is revoked, not deleted,
+            // so it learns it was displaced on its next sync instead of silently reappearing.
+            for (const row of rows) {
+                if (row._id === existing?._id || row.revokedAt !== undefined)
+                    continue;
+                await ctx.db.patch(row._id, { revokedAt: now });
+            }
+            return { pose, lastSeenAt: now, displaced };
         }),
     });
     const leave = mutation({
         args: {
             serverId: v.string(),
+            sessionId: v.optional(v.string()),
             externalId: v.optional(v.string()),
         },
         returns: v.null(),
@@ -1099,23 +1382,170 @@ export function createPresenceFunctions(options) {
             const actorUserId = await resolveActor(ctx, args.externalId, mode);
             if (!actorUserId)
                 return null;
-            const existing = await ctx.db
+            const now = Date.now();
+            const rows = await ctx.db
                 .query("jgPoses")
                 .withIndex("by_server_and_user", (q) => q.eq("serverId", args.serverId).eq("userId", actorUserId))
-                .unique();
-            if (existing)
-                await ctx.db.delete(existing._id);
+                .collect();
+            for (const row of rows) {
+                if (args.sessionId !== undefined && row.sessionId !== args.sessionId)
+                    continue;
+                if (row.revokedAt === undefined)
+                    await ctx.db.patch(row._id, { revokedAt: now });
+            }
             return null;
         },
     });
-    return { list, sync, leave };
+    /**
+     * Delete rows nobody has written for `idleCutoffMs`. `list` filters stale rows at read time but
+     * nothing removed them, so a player who closed the tab left a row behind forever. Register it on a
+     * cron — {@link jgengineCronSpecs} carries the interval.
+     */
+    const reapIdlePresence = internalMutation({
+        args: {},
+        returns: v.object({ reaped: v.number() }),
+        handler: async (ctx) => {
+            const now = Date.now();
+            const stale = await ctx.db
+                .query("jgPoses")
+                .withIndex("by_updated", (q) => q.lt("updatedAt", now - idleCutoffMs))
+                .take(maxReapPerRun);
+            let reaped = 0;
+            for (const row of stale) {
+                if (!isPresenceExpired(row.updatedAt, now, idleCutoffMs))
+                    continue;
+                await ctx.db.delete(row._id);
+                reaped += 1;
+            }
+            return { reaped };
+        },
+    });
+    return { list, sync, leave, reapIdlePresence };
+}
+/**
+ * Scan one bounded presence page and schedule its handler and continuation in separate transactions.
+ * @capability online-player-batches Schedule bounded active-player or home-game work in separate transactions.
+ */
+export async function forEachOnlinePlayer(ctx, options) {
+    const batchSize = options.batchSize ?? 25;
+    if (!Number.isSafeInteger(batchSize) || batchSize < 1 || batchSize > 256)
+        throw new Error("batchSize must be between 1 and 256");
+    const nowMs = options.nowMs ?? Date.now();
+    const freshWindowMs = options.freshWindowMs ?? 60_000;
+    if (!Number.isFinite(nowMs) || !Number.isFinite(freshWindowMs) || freshWindowMs <= 0 || !Number.isFinite(nowMs - freshWindowMs))
+        throw new Error("Invalid online-player time window");
+    const page = await ctx.db.query("jgPoses").withIndex("by_updated", q => q.gte("updatedAt", nowMs - freshWindowMs))
+        .paginate({ numItems: batchSize, cursor: options.cursor ?? null });
+    const players = [];
+    for (const row of page.page) {
+        if (row.revokedAt !== undefined)
+            continue;
+        const canonical = options.groupBy === "homeGameId" && row.homeGameId
+            ? await ctx.db.query("jgPoses").withIndex("by_home_game_revoked_updated", q => q.eq("homeGameId", row.homeGameId).eq("revokedAt", undefined)).order("desc").first()
+            : await ctx.db.query("jgPoses").withIndex("by_server_user_revoked_updated", q => q.eq("serverId", row.serverId).eq("userId", row.userId).eq("revokedAt", undefined)).order("desc").first();
+        if (canonical?._id === row._id)
+            players.push({ serverId: row.serverId, userId: row.userId, ...(row.homeGameId ? { homeGameId: row.homeGameId } : {}) });
+    }
+    if (players.length)
+        await ctx.scheduler.runAfter(0, options.handler, { players, nowMs });
+    if (!page.isDone)
+        await ctx.scheduler.runAfter(0, options.continuation, { cursor: page.continueCursor, nowMs });
+    return { scheduled: players.length, remaining: !page.isDone };
+}
+/**
+ * Consume one request in a fixed rate window; concurrent callers serialize on the indexed key.
+ * @capability host-rate-limit Enforce indexed per-key request windows inside authoritative mutations.
+ */
+export async function rateLimit(ctx, args) {
+    const now = args.nowMs ?? Date.now();
+    if (!args.key || args.key.length > 512 || !Number.isFinite(now) || !Number.isFinite(args.windowMs) || args.windowMs <= 0 || !Number.isFinite(now + args.windowMs) || !Number.isSafeInteger(args.max) || args.max < 1)
+        throw new Error("Invalid rate limit policy");
+    const row = await ctx.db.query("jgRateLimits").withIndex("by_key", q => q.eq("key", args.key)).unique();
+    if (row && now < row.expiresAt && row.count >= args.max)
+        return { ok: false, retryAfterMs: row.expiresAt - now };
+    const patch = !row || now >= row.expiresAt ? { startedAt: now, expiresAt: now + args.windowMs, count: 1 } : { startedAt: row.startedAt, expiresAt: row.expiresAt, count: row.count + 1 };
+    if (row)
+        await ctx.db.patch(row._id, patch);
+    else
+        await ctx.db.insert("jgRateLimits", { key: args.key, ...patch });
+    return { ok: true, retryAfterMs: 0 };
+}
+/**
+ * Write validated chat in a host transaction after the caller resolves its actor and world.
+ * @capability host-chat-send Validate, rate-limit and persist chat inside an authorized host mutation.
+ */
+export async function sendChatMessage(ctx, args) {
+    const maxBodyLength = args.maxBodyLength ?? 240;
+    if (!Number.isSafeInteger(maxBodyLength) || maxBodyLength < 1 || maxBodyLength > 4096)
+        throw new Error("Invalid chat body limit");
+    if (!(args.channelId ?? "global").trim() || (args.channelId?.length ?? 0) > 256 || (args.authorName?.length ?? 0) > 160)
+        return { ok: false, reason: "invalid_channel_or_author" };
+    const validation = validateChatMessage(args.body, { maxLength: args.maxBodyLength ?? 240 });
+    if (!validation.ok)
+        return validation;
+    const gate = await rateLimit(ctx, { key: JSON.stringify(["chat", args.serverId, args.userId]), windowMs: args.minIntervalMs ?? 2000, max: 1 });
+    if (!gate.ok)
+        return { ok: false, reason: "rate_limited" };
+    await ctx.db.insert("jgChatMessages", { serverId: args.serverId, channelId: args.channelId ?? "global", userId: args.userId, body: validation.text, authorName: args.authorName, at: Date.now() });
+    return { ok: true };
+}
+/**
+ * Bounded recent chat for a resolved server; authorization belongs to the calling query.
+ * @capability host-chat-history Read bounded channel history inside an authorized host query.
+ */
+export async function recentChatMessages(ctx, args) {
+    const limit = args.limit ?? 50;
+    if (!Number.isFinite(limit))
+        throw new Error("Invalid chat limit");
+    return ctx.db.query("jgChatMessages").withIndex("by_server_channel", q => q.eq("serverId", args.serverId).eq("channelId", args.channelId ?? "global"))
+        .order("desc").take(Math.min(100, Math.max(1, Math.floor(limit))));
+}
+/**
+ * Authenticated, bounded client diagnostics and bounded retention sweeps.
+ * @capability client-error-reporting Accept authenticated bounded diagnostics with cooldown and retention sweeps.
+ */
+export function createClientErrorFunctions() {
+    const reportClientError = mutation({
+        args: { message: v.string(), kind: v.optional(v.string()), stack: v.optional(v.string()), componentStack: v.optional(v.string()), url: v.optional(v.string()), pathname: v.optional(v.string()), userAgent: v.optional(v.string()), agentPrompt: v.optional(v.string()) },
+        returns: v.object({ ok: v.boolean(), reason: v.optional(v.string()) }),
+        handler: async (ctx, args) => {
+            const actor = await resolveActor(ctx, undefined, "required");
+            if (!actor)
+                return { ok: false, reason: "unauthorized" };
+            const message = JSON.stringify(args);
+            if (new TextEncoder().encode(message).length > 4096)
+                return { ok: false, reason: "too_long" };
+            const gate = await rateLimit(ctx, { key: `client-error:${actor}`, windowMs: 10_000, max: 1 });
+            if (!gate.ok)
+                return { ok: false, reason: "rate_limited" };
+            await ctx.db.insert("jgClientErrors", { userId: actor, message, createdAt: Date.now() });
+            return { ok: true };
+        },
+    });
+    const pruneClientErrors = internalMutation({ args: {}, handler: async (ctx) => {
+            const rows = await ctx.db.query("jgClientErrors").withIndex("by_created", q => q.lt("createdAt", Date.now() - 7 * 86_400_000)).take(256);
+            for (const row of rows)
+                await ctx.db.delete(row._id);
+            return { deleted: rows.length, remaining: rows.length === 256 };
+        } });
+    const pruneRateLimits = internalMutation({ args: {}, handler: async (ctx) => {
+            const rows = await ctx.db.query("jgRateLimits").withIndex("by_expires", q => q.lte("expiresAt", Date.now())).take(256);
+            for (const row of rows)
+                await ctx.db.delete(row._id);
+            return { deleted: rows.length, remaining: rows.length === 256 };
+        } });
+    return { reportClientError, pruneClientErrors, pruneRateLimits };
 }
 /** @internal */
 export function createChatFunctions(options) {
     const mode = options?.auth ?? "required";
-    const historyLimit = options?.historyLimit ?? 100;
-    const maxBodyLength = options?.maxBodyLength ?? 500;
-    const minIntervalMs = options?.minIntervalMs ?? 300;
+    if (options?.historyLimit !== undefined && (!Number.isSafeInteger(options.historyLimit) || options.historyLimit < 1))
+        throw new Error("Invalid chat history limit");
+    const historyLimit = Math.min(100, options?.historyLimit ?? 50);
+    const maxBodyLength = options?.maxBodyLength ?? 240;
+    const minIntervalMs = options?.minIntervalMs ?? 2_000;
+    if (!Number.isSafeInteger(maxBodyLength) || maxBodyLength < 1 || maxBodyLength > 4096 || !Number.isFinite(minIntervalMs) || minIntervalMs <= 0)
+        throw new Error("Invalid chat policy");
     const messages = query({
         args: {
             serverId: v.string(),
@@ -1162,28 +1592,9 @@ export function createChatFunctions(options) {
             if ((await requireServerMember(ctx, args.serverId, actorUserId)) === null) {
                 return { ok: false, reason: "not a member of this server" };
             }
-            const body = args.body.trim();
-            if (body.length === 0)
-                return { ok: false, reason: "empty message" };
-            if (body.length > maxBodyLength)
-                return { ok: false, reason: "message too long" };
-            const now = Date.now();
-            const newestByActor = await ctx.db
-                .query("jgChatMessages")
-                .withIndex("by_server_channel", (q) => q.eq("serverId", args.serverId).eq("channelId", args.channelId))
-                .order("desc")
-                .filter((q) => q.eq(q.field("userId"), actorUserId))
-                .first();
-            if (newestByActor && now - newestByActor.at < minIntervalMs) {
-                return { ok: false, reason: "sending too fast" };
-            }
-            await ctx.db.insert("jgChatMessages", {
-                serverId: args.serverId,
-                channelId: args.channelId,
-                userId: actorUserId,
-                body,
-                at: now,
-            });
+            const outcome = await sendChatMessage(ctx, { serverId: args.serverId, userId: actorUserId, channelId: args.channelId, body: args.body, maxBodyLength, minIntervalMs });
+            if (!outcome.ok)
+                return outcome.reason === "rate_limited" ? { ok: false, reason: "sending too fast" } : outcome;
             const recent = await ctx.db
                 .query("jgChatMessages")
                 .withIndex("by_server_channel", (q) => q.eq("serverId", args.serverId).eq("channelId", args.channelId))
@@ -1195,13 +1606,32 @@ export function createChatFunctions(options) {
             return { ok: true };
         },
     });
-    return { messages, sendMessage };
+    const pruneChatMessages = internalMutation({ args: {}, handler: async (ctx) => {
+            const rows = await ctx.db.query("jgChatMessages").withIndex("by_at", q => q.lt("at", Date.now() - 86_400_000)).take(256);
+            for (const row of rows)
+                await ctx.db.delete(row._id);
+            return { deleted: rows.length, remaining: rows.length === 256 };
+        } });
+    return { messages, recent: messages, sendMessage, pruneChatMessages };
 }
 const JG_CRON_SPECS = [
-    { name: "jg tick", intervalSeconds: 1, functionKey: "tickActiveServers" },
-    { name: "jg flush", intervalSeconds: 60, functionKey: "flushDirtyServers" },
+    { name: "jg tick", intervalSeconds: 1, functionKey: "tickActiveServers", module: "runtime" },
+    { name: "jg flush", intervalSeconds: 60, functionKey: "flushDirtyServers", module: "runtime" },
+    { name: "jg presence reap", intervalSeconds: 60, functionKey: "reapIdlePresence", module: "presence" },
 ];
 /** @internal */
-export function jgengineCronSpecs() {
-    return JG_CRON_SPECS;
+export function jgengineCronSpecs(options = {}) {
+    const specs = JG_CRON_SPECS.filter(spec => spec.functionKey !== "tickActiveServers" || options.runtimes?.some(runtime => runtime.hasTick));
+    if (options.chat)
+        specs.push({ name: "jg chat prune", intervalSeconds: 3600, functionKey: "pruneChatMessages", module: "chat" });
+    if (options.clientErrors) {
+        specs.push({ name: "jg error prune", intervalSeconds: 3600, functionKey: "pruneClientErrors", module: "clientErrors" });
+        specs.push({ name: "jg rate limit prune", intervalSeconds: 3600, functionKey: "pruneRateLimits", module: "clientErrors" });
+    }
+    return specs.map(spec => {
+        const intervalSeconds = options.intervalSeconds?.[spec.functionKey] ?? spec.intervalSeconds;
+        if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0)
+            throw new Error("Cron intervalSeconds must be positive");
+        return { ...spec, intervalSeconds };
+    });
 }