@jgengine/convex 0.16.0 → 0.18.0

package/dist/server.js

@@ -1,14 +1,15 @@
 import { defineSchema, defineTable, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
-import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
+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 } from "@jgengine/core/runtime/gameRuntime";
-import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries } from "@jgengine/core/runtime/hostPersistence";
-import { isAutoJoinCandidate, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, statusAfterLeave, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
+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 { applyCommandWithOcc, commitIfRevisionMatch } from "./occ.js";
 /** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
-export { canJoinPrivateServer, isListablePublicly, } from "@jgengine/core/runtime/hostPolicy";
+export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, validateSlotsPerServer, } from "@jgengine/core/runtime/hostPolicy";
 const saveConfigValidator = v.union(v.literal("none"), v.object({
     auto: v.string(),
     scope: v.union(v.literal("player"), v.literal("chunks"), v.literal("player+chunks")),
@@ -37,6 +38,7 @@ export function jgengineTables() {
         })
             .index("by_game_and_status", ["gameId", "status"])
             .index("by_status", ["status"])
+            .index("by_game_status_tick", ["gameId", "status", "tickAnchorMs"])
             .index("by_dirty", ["dirtyAt"]),
         jgPlayerProfiles: defineTable({
             userId: v.string(),
@@ -76,15 +78,24 @@ export function jgengineTables() {
         jgPoses: defineTable({
             serverId: 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_updated", ["updatedAt"]),
         jgChatMessages: defineTable({
             serverId: v.string(),
             channelId: v.string(),
@@ -221,11 +232,16 @@ function serverDocToRecord(server) {
 /**
  * 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.
+ * Pass a {@link LoadSnapshotScope} to bound the read instead of loading the whole world.
  * @capability convex-load-server-snapshot read a hosted server's runtime snapshot inside a host-written Convex mutation
  */
-export async function loadServerSnapshot(ctx, server, runtime) {
+export async function loadServerSnapshot(ctx, server, runtime, scope) {
     const profiles = {};
-    for (const userId of server.memberUserIds) {
+    const memberIds = new Set(server.memberUserIds);
+    const hydrateUserIds = scope?.players === undefined
+        ? server.memberUserIds
+        : scope.players.filter((userId) => memberIds.has(userId));
+    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))
@@ -240,14 +256,25 @@ export async function loadServerSnapshot(ctx, server, runtime) {
             }
             : null;
     }
-    const playersByUserId = buildHydratePlayers(serverDocToRecord(server), profiles);
-    const chunks = await ctx.db
-        .query("jgWorldChunks")
-        .withIndex("by_server", (q) => q.eq("serverId", server._id))
-        .collect();
+    const playersByUserId = buildHydratePlayers(serverDocToRecord(server), profiles, hydrateUserIds);
     const chunksByKey = {};
-    for (const chunk of chunks) {
-        chunksByKey[chunk.chunkKey] = chunk.snapshot;
+    if (scope?.chunkKeys === undefined) {
+        const chunks = await ctx.db
+            .query("jgWorldChunks")
+            .withIndex("by_server", (q) => q.eq("serverId", server._id))
+            .collect();
+        for (const chunk of chunks)
+            chunksByKey[chunk.chunkKey] = chunk.snapshot;
+    }
+    else {
+        for (const chunkKey of new Set(scope.chunkKeys)) {
+            const chunk = await ctx.db
+                .query("jgWorldChunks")
+                .withIndex("by_server_and_chunk", (q) => q.eq("serverId", server._id).eq("chunkKey", chunkKey))
+                .unique();
+            if (chunk)
+                chunksByKey[chunk.chunkKey] = chunk.snapshot;
+        }
     }
     return runtime.hydrate({
         gameId: server.gameId,
@@ -287,11 +314,18 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
 /**
  * Write a snapshot back: server row, dirty player profiles, dirty chunks, and drained leaderboard
  * increments, all under `save`. Pair it with your own table writes to keep both in one transaction.
+ *
+ * A persist that would change nothing writes nothing and returns `false`. That matters beyond write
+ * cost: every subscriber of a query that read this row re-receives the whole result when the document
+ * changes, so an unconditional write on a 1 Hz tick re-pushes the entire world to every client once a
+ * second whether or not anything moved.
  * @capability convex-persist-server-snapshot write runtime state and host tables in one Convex transaction
  */
 export async function persistServerSnapshot(ctx, server, snapshot, save) {
     const now = Date.now();
     const plan = planServerPersist(serverDocToRecord(server), snapshot, save, now);
+    if (!plan.changed.any)
+        return false;
     if (plan.leaderboard.length > 0) {
         await applyLeaderboardIncrements(ctx, server.gameId, plan.leaderboard);
     }
@@ -347,29 +381,57 @@ export async function persistServerSnapshot(ctx, server, snapshot, save) {
             await ctx.db.delete(existing._id);
     }
     await ctx.db.patch(server._id, {
-        serverState: plan.server.serverState,
-        sessionPlayers: plan.server.sessionPlayers,
+        ...(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,
     });
+    return true;
 }
-async function flushServerIfDue(ctx, server, now, runtime) {
+/** Autosave a server whose `save.auto` interval has elapsed, reusing an already-hydrated snapshot. */
+async function flushServerIfDue(ctx, server, now, runtime, loaded) {
     if (!shouldAutoSave(server.save, server.dirtyAt, server.lastSavedAt, now)) {
         return false;
     }
-    const snapshot = await loadServerSnapshot(ctx, server, runtime);
+    // Unscoped on purpose: markAllPlayersDirty writes every member, so every member has to be hydrated.
+    const snapshot = loaded ?? (await loadServerSnapshot(ctx, server, runtime));
     await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
     return true;
 }
 export const JG_RUNTIME_TICK_MS = 1_000;
-/** @internal */
+/** How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist. */
+export const DEFAULT_MAX_SERVERS_PER_TICK = 32;
+/** How many chunk rows one `getChunks` call may return. */
+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.
+ * World geometry that outgrows one row belongs in `jgWorldChunks`, hydrated by key
+ * ({@link LoadSnapshotScope}) and read by clients through `getChunks` — not in `serverState`.
+ *
+ * `matchmaking: "singleton"` makes auto-match target one shared world per game: a join past capacity
+ * fails loudly instead of quietly starting a second world the player would be alone in.
+ * @internal
+ */
 export function createGameServerFunctions(options) {
     const mode = options?.auth ?? "required";
     const hostSlotsPerServer = options?.slotsPerServer ?? 16;
+    const slotsCheck = validateSlotsPerServer(hostSlotsPerServer);
+    if (!slotsCheck.ok)
+        throw new Error(slotsCheck.reason);
+    const matchmaking = options?.matchmaking ?? "auto";
+    const maxServersPerTick = Math.max(1, options?.maxServersPerTick ?? DEFAULT_MAX_SERVERS_PER_TICK);
     const feedWriteGate = createFeedWriteGate(options?.allowedFeedActions ?? []);
     const registry = buildRuntimeRegistry(options?.runtimes);
+    const tickableGameIds = (options?.runtimes ?? [])
+        .filter((runtime) => runtime.hasTick)
+        .map((runtime) => runtime.gameId);
     const joinServer = mutation({
         args: {
             gameId: v.string(),
@@ -397,6 +459,7 @@ export function createGameServerFunctions(options) {
             if (server && server.gameId !== args.gameId) {
                 throw new ConvexError("Server belongs to a different game");
             }
+            let mayCreate = true;
             if (!server) {
                 const joinable = [];
                 for (const status of ["running", "open"]) {
@@ -406,15 +469,21 @@ export function createGameServerFunctions(options) {
                         .collect();
                     joinable.push(...rows);
                 }
-                server =
-                    joinable.find((row) => isAutoJoinCandidate({
-                        memberUserIds: row.memberUserIds,
-                        slotsPerServer: row.slotsPerServer,
-                        visibility: row.visibility,
-                        userId: actorUserId,
-                    })) ?? null;
+                // Two concurrent first-joins can both see an empty list here and both insert. Convex's OCC
+                // resolves it — the loser's read set is invalidated and its mutation retries against the
+                // winner's row — so the engine adds no lock. A `HostPersistence` backend without
+                // serializable-snapshot retry must supply that guarantee itself.
+                const target = selectJoinTarget(joinable, {
+                    userId: actorUserId,
+                    mode: matchmaking,
+                    slotsPerServer,
+                });
+                if (target.kind === "refuse")
+                    throw new ConvexError(target.reason);
+                server = target.kind === "join" ? target.row : null;
+                mayCreate = target.kind === "create";
             }
-            if (!server) {
+            if (!server && mayCreate) {
                 const serverId = await ctx.db.insert("jgGameServers", {
                     gameId: args.gameId,
                     status: "running",
@@ -436,6 +505,17 @@ export function createGameServerFunctions(options) {
                 if (!server)
                     throw new ConvexError("Failed to create server");
             }
+            if (!server)
+                throw new ConvexError("No joinable server");
+            // Capacity and save policy live in host options, not in the row. Without this a long-lived
+            // world keeps whatever it was created with and raising the host option silently does nothing.
+            if (server.slotsPerServer !== slotsPerServer || JSON.stringify(server.save) !== JSON.stringify(save)) {
+                await ctx.db.patch(server._id, { slotsPerServer, save, updatedAt: now });
+                const reconciled = await ctx.db.get("jgGameServers", server._id);
+                if (!reconciled)
+                    throw new ConvexError("Server missing after reconcile");
+                server = reconciled;
+            }
             if (isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
                 throw new ConvexError("Server is full");
             }
@@ -463,7 +543,7 @@ export function createGameServerFunctions(options) {
             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);
+            let snapshot = await loadServerSnapshot(ctx, refreshed, runtime, scopeWithActor(runtime.joinScope(actorUserId, isNew), actorUserId));
             snapshot = runtime.joinPlayer(snapshot, actorUserId, isNew);
             await persistServerSnapshot(ctx, refreshed, snapshot, save);
             return { serverId: refreshed._id, isNew };
@@ -482,7 +562,11 @@ 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 };
@@ -504,12 +588,12 @@ export function createGameServerFunctions(options) {
         },
     });
     const helpers = {
-        async loadSnapshot(ctx, serverId) {
+        async loadSnapshot(ctx, serverId, scope) {
             const server = await ctx.db.get("jgGameServers", serverId);
             if (!server)
                 return null;
             const runtime = resolveRuntime(registry, server.gameId);
-            return { server, runtime, snapshot: await loadServerSnapshot(ctx, server, runtime) };
+            return { server, runtime, snapshot: await loadServerSnapshot(ctx, server, runtime, scope) };
         },
         applyCommand(args) {
             return applyCommandWithOcc({ ...args, runtime: resolveRuntime(registry, args.gameId) });
@@ -529,7 +613,8 @@ export function createGameServerFunctions(options) {
             }
             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,
@@ -542,6 +627,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" };
@@ -560,6 +649,10 @@ 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),
@@ -576,6 +669,7 @@ export function createGameServerFunctions(options) {
             if (server === null)
                 return false;
             const runtime = resolveRuntime(registry, server.gameId);
+            // Unscoped on purpose: markAllPlayersDirty writes every member.
             const snapshot = await loadServerSnapshot(ctx, server, runtime);
             await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
             return true;
@@ -617,6 +711,63 @@ export function createGameServerFunctions(options) {
             };
         }),
     });
+    /**
+     * Lobby-scale view of a server: status, capacity, revision — no world state. Subscribe a menu,
+     * roster, or "is it up" indicator to this instead of `getServer`, whose payload is the whole world.
+     */
+    const getServerMeta = 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(),
+            revision: v.number(),
+            updatedAt: v.number(),
+        }), v.null()),
+        handler: (ctx, args) => withMember(ctx, mode, args, null, (server) => ({
+            _id: server._id,
+            gameId: server.gameId,
+            status: server.status,
+            mode: server.mode,
+            memberCount: server.memberUserIds.length,
+            slotsPerServer: server.slotsPerServer,
+            revision: server.revision,
+            updatedAt: server.updatedAt,
+        })),
+    });
+    /**
+     * 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.
+     * Bounded to {@link MAX_CHUNKS_PER_QUERY} keys; ask for the cells around the viewer
+     * (`chunkKeysInRadius`), not the world.
+     */
+    const getChunks = query({
+        args: {
+            serverId: v.id("jgGameServers"),
+            chunkKeys: v.array(v.string()),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.array(v.object({ chunkKey: v.string(), snapshot: v.any(), updatedAt: v.number() })),
+        handler: (ctx, args) => withMember(ctx, mode, args, [], async (server) => {
+            const keys = [...new Set(args.chunkKeys)].slice(0, MAX_CHUNKS_PER_QUERY);
+            const out = [];
+            for (const chunkKey of keys) {
+                const row = await ctx.db
+                    .query("jgWorldChunks")
+                    .withIndex("by_server_and_chunk", (q) => q.eq("serverId", server._id).eq("chunkKey", chunkKey))
+                    .unique();
+                if (row)
+                    out.push({ chunkKey: row.chunkKey, snapshot: row.snapshot, updatedAt: row.updatedAt });
+            }
+            return out;
+        }),
+    });
     const getPlayerProfile = query({
         args: {
             gameId: v.string(),
@@ -736,31 +887,42 @@ export function createGameServerFunctions(options) {
             }));
         },
     });
+    // Only games that declare `loop.onTick` are swept, and only `maxServersPerTick` of their servers per
+    // transaction, oldest anchor first. A game with no tick hook used to pay a full hydrate + persist per
+    // running server per second to hand `runtime.tick` a snapshot it returned unchanged; now it pays
+    // nothing, and no single transaction can fan out across every world of every game.
     const tickActiveServers = internalMutation({
         args: {},
         handler: async (ctx) => {
             const now = Date.now();
-            const servers = await ctx.db
-                .query("jgGameServers")
-                .withIndex("by_status", (q) => q.eq("status", "running"))
-                .collect();
             let ticked = 0;
             let saved = 0;
-            for (const server of servers) {
-                if (server.memberUserIds.length === 0)
-                    continue;
-                const elapsedMs = now - server.tickAnchorMs;
-                if (elapsedMs < JG_RUNTIME_TICK_MS)
-                    continue;
-                const runtime = resolveRuntime(registry, server.gameId);
-                let snapshot = await loadServerSnapshot(ctx, server, runtime);
-                snapshot = runtime.tick(snapshot, elapsedMs / 1_000);
-                await persistServerSnapshot(ctx, server, snapshot, server.save);
-                await ctx.db.patch(server._id, { tickAnchorMs: now, updatedAt: now });
-                ticked += 1;
-                const refreshed = await ctx.db.get("jgGameServers", server._id);
-                if (refreshed && (await flushServerIfDue(ctx, refreshed, now, runtime))) {
-                    saved += 1;
+            let budget = maxServersPerTick;
+            for (const gameId of tickableGameIds) {
+                if (budget <= 0)
+                    break;
+                const servers = await ctx.db
+                    .query("jgGameServers")
+                    .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)
+                        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);
+                    await persistServerSnapshot(ctx, server, snapshot, server.save);
+                    await ctx.db.patch(server._id, { tickAnchorMs: now });
+                    ticked += 1;
+                    const refreshed = await ctx.db.get("jgGameServers", server._id);
+                    if (refreshed && (await flushServerIfDue(ctx, refreshed, now, runtime, snapshot))) {
+                        saved += 1;
+                    }
                 }
             }
             return { ticked, saved };
@@ -769,18 +931,17 @@ export function createGameServerFunctions(options) {
     const flushDirtyServers = internalMutation({
         args: {},
         handler: async (ctx) => {
-            const now = Date.now();
             const servers = await ctx.db
                 .query("jgGameServers")
                 .withIndex("by_dirty", (q) => q.gt("dirtyAt", 0))
-                .collect();
+                .take(maxServersPerTick);
             let saved = 0;
             for (const server of servers) {
                 const runtime = resolveRuntime(registry, server.gameId);
+                // Unscoped on purpose: markAllPlayersDirty writes every member.
                 const snapshot = await loadServerSnapshot(ctx, server, runtime);
                 await persistServerSnapshot(ctx, server, markAllPlayersDirty(snapshot), server.save);
                 saved += 1;
-                void now;
             }
             return { saved };
         },
@@ -791,6 +952,8 @@ export function createGameServerFunctions(options) {
         runCommand,
         flushSave,
         getServer,
+        getServerMeta,
+        getChunks,
         getPlayerProfile,
         getFeed,
         pushFeedEntry,
@@ -866,11 +1029,28 @@ 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(),
@@ -878,6 +1058,9 @@ export function createPresenceFunctions(options) {
         },
         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(),
@@ -891,9 +1074,12 @@ export function createPresenceFunctions(options) {
                     .withIndex("by_server", (q) => q.eq("serverId", args.serverId))
                     .collect();
                 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,
@@ -902,60 +1088,101 @@ 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);
+            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, 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,
+                    ...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(),
@@ -963,16 +1190,45 @@ 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 };
 }
 /** @internal */
 export function createChatFunctions(options) {
@@ -1062,8 +1318,9 @@ export function createChatFunctions(options) {
     return { messages, sendMessage };
 }
 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() {