@jgengine/convex 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -26,14 +26,30 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.18.0
+
 ### Migrate
 
+- **Bump lockstep SDK packages to `^0.18.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.0`; `@jgengine/github` is `0.5.0`.
+- **Register the presence reaper and redeploy your schema.** `jgPoses` gains `sessionId` / `kind` / `label` / `revokedAt` (all optional) and a `by_updated` index, and `createPresenceFunctions` now also returns `reapIdlePresence`. Re-export it (`export const { list, sync, leave, reapIdlePresence } = createPresenceFunctions(...)`) and add `crons.interval("jg presence reap", { seconds: 60 }, internal.presence.reapIdlePresence, {})`. Without it nothing deletes the row of a player who closed the tab — `list` filtered stale rows at read time but the table grew forever. `jgengineCronSpecs()` carries the new entry, and every spec now names the `module` (`"runtime"` / `"presence"`) it is exported from.
+- **`presence.sync` returns `{ pose, lastSeenAt, displaced }` instead of `null`,** and `presence.leave` marks the row revoked instead of deleting it (the reaper collects it once idle). A caller that ignored the return value is unaffected.
+
 ### Changed
 
+- **`presence.sync` accepts a call with no `pose` at all,** which holds the stored position and moves only the liveness stamp. `createConvexPresenceSync` sends one itself when the pose gate has suppressed writes for 10s, so a standing player keeps their row alive without a pose write — and without the reaper collecting a live session.
+- **`PresencePoseRow` carries optional `sessionId` / `kind` / `label`,** so a nameplate reads off the presence row instead of joining against users per frame.
+
 ### Added
 
+- **`createPresenceFunctions` gains the policy hooks the pose lane was missing** — `resolveSpawn(ctx, { serverId, userId, kind })` for where a session with no row starts (async and ctx-bearing, so a spawn can read the world, replacing a hardcoded origin), `poseRules` as a function of the actor `kind` so an agent need not obey a human's speed cap, `idleCutoffMs` / `maxReapPerRun` for the reaper, and optional `sessionId` on `sync` / `leave`: a second tab is a second row, syncing revokes the others, and the displaced session learns it on its next call through `displaced: true`.
+
+- **A command declares what it touches, so `runCommand` hydrates that and nothing else.** `CommandDef` gains an optional `scope(input, actorUserId)` returning `{ players?, chunkKeys? }`, evaluated before hydration; the registered `runCommand` mutation also accepts an explicit `scope` argument, which wins over the declared one. A game that never sets either keeps the whole-world default. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`.
+- **`GameRuntime.commandScope` / `GameRuntime.joinScope`** expose those declarations to any host, alongside the pure helpers `resolveCommandScope` / `scopeWithActor` / `commandScopeEscape` (`@jgengine/core/runtime/commandRunner`).
+
 ### Fixed
 
+- **`runCommand` no longer reads the whole world on every command.** `LoadSnapshotScope` landed in 0.17 but only `helpers.loadSnapshot` accepted one, so the supported way to run a command — the registered `runCommand` mutation, a one-line delegation to `helpers.runCommand` — hydrated every member profile and every chunk however narrow the command was, and a game could only get bounded hydration by reimplementing the mutation. `runCommand`, `joinServer`, and `leaveServer` now hydrate a scope; a command whose `apply` dirties a player or chunk its scope never named is refused rather than persisted, since writing an unhydrated chunk overwrites the stored one with a blank. `flushSave` / `flushServerIfDue` / `tickActiveServers` / `flushDirtyServers` still hydrate everything, which is correct for what they write.
+
 ## 0.17.0
 
 ### Migrate

package/README.md

@@ -25,7 +25,7 @@ Once a session resolves, `GamePlayerShell` wires it up with no game code changes
 
 ## Server
 
-`@jgengine/convex/server` exports factories, not a template to copy: `jgengineTables()`, `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()`. A consumer's `convex/` directory is ~25 lines total:
+`@jgengine/convex/server` exports factories, not a template to copy: `jgengineTables()`, `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs?, idleCutoffMs?, poseRules?, resolveSpawn? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()`. A consumer's `convex/` directory is ~25 lines total:
 
 ```ts
 // convex/schema.ts
@@ -37,7 +37,7 @@ export default defineSchema({ ...jgengineTables() });
 import { createGameServerFunctions } from "@jgengine/convex/server";
 export const { joinServer, leaveServer, runCommand, flushSave, getServer, getPlayerProfile, getFeed, pushFeedEntry, listOpenServers, tickActiveServers, flushDirtyServers } = createGameServerFunctions();
 
-// convex/crons.ts registers tickActiveServers (1s) + flushDirtyServers (60s)
+// convex/crons.ts registers tickActiveServers (1s) + flushDirtyServers (60s) + reapIdlePresence (60s)
 ```
 
 No game-specific code lives there — any JGengine game can point at the same deployment. Games without a registered `GameRuntime` fall back to a no-save runtime that only understands `engine.ping`; pass `createGameServerFunctions({ runtimes: [createGameRuntime({ gameId, commands, loop, save })] })` to make `runCommand`/tick/save actually do something.

package/dist/convexPresenceTransport.d.ts

@@ -1,5 +1,11 @@
 import type { FunctionReference } from "convex/server";
 import type { PresenceTransport } from "@jgengine/core/multiplayer/presenceContract";
+/**
+ * The Convex functions a **game** supplies for a world it owns: presence keyed by the game's own ids,
+ * including which residents exist while offline, which is game content and has no engine analogue.
+ * Not satisfied by `createPresenceFunctions` (`@jgengine/convex/server`) — that is the pose lane of a
+ * hosted `jgGameServers` server, backing `PresenceSync` rather than `PresenceTransport`.
+ */
 export interface ConvexPresenceFunctions {
     snapshot: FunctionReference<"query">;
     cityResidents: FunctionReference<"query">;

package/dist/createConvexGameTransport.d.ts

@@ -64,17 +64,31 @@ export type ConvexGameApi = {
         }, PresencePoseRow[]>;
         sync: FunctionReference<"mutation", "public", {
             serverId: string;
-            pose: {
+            pose?: {
                 x: number;
                 y: number;
                 z: number;
                 rotationY: number;
                 rotationPitch: number;
             };
+            sessionId?: string;
+            kind?: string;
+            label?: string;
             externalId?: string;
-        }, null>;
+        }, {
+            pose: {
+                x: number;
+                y: number;
+                z: number;
+                rotationY: number;
+                rotationPitch: number;
+            };
+            lastSeenAt: number;
+            displaced: boolean;
+        } | null>;
         leave: FunctionReference<"mutation", "public", {
             serverId: string;
+            sessionId?: string;
             externalId?: string;
         }, null>;
     };

package/dist/createConvexGameTransport.js

@@ -69,17 +69,30 @@ const DEFAULT_CONVEX_POSE_TUNING = {
     verticalEpsilon: 0.01,
     rotationEpsilon: 0.01,
 };
+/** How long a suppressed pose stream may go quiet before a position-less keep-alive is sent. */
+const KEEP_ALIVE_MS = 10_000;
 export function createConvexPresenceSync(client, api, config, tuning) {
     const gate = createPoseSyncGate(tuning ?? DEFAULT_CONVEX_POSE_TUNING);
+    const lastSentAt = new Map();
     return {
         subscribe(serverId, onChange) {
             return watchConvexQuery(client, api.presence.list, { serverId, externalId: config.userId }, (rows) => rows, onChange);
         },
         syncPose(serverId, pose) {
-            if (!gate.evaluate(pose, Date.now()))
+            const now = Date.now();
+            const moved = gate.evaluate(pose, now);
+            // The gate drops an unchanged pose, so a standing player would otherwise send nothing at all
+            // and the reaper would eventually collect a live session. Keep the row alive without a write.
+            const keepAlive = !moved && now - (lastSentAt.get(serverId) ?? 0) >= KEEP_ALIVE_MS;
+            if (!moved && !keepAlive)
                 return;
+            lastSentAt.set(serverId, now);
             void client
-                .mutation(api.presence.sync, { serverId, pose, externalId: config.userId })
+                .mutation(api.presence.sync, {
+                serverId,
+                ...(moved ? { pose } : {}),
+                externalId: config.userId,
+            })
                 .catch(() => undefined);
         },
     };

package/dist/server.d.ts

@@ -3,6 +3,7 @@ import type { GenericId } from "convex/values";
 import type { ChatMessage } from "@jgengine/core/game/chat";
 import type { ChatSendOutcome } from "@jgengine/core/multiplayer/chatContract";
 import { type PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
+import type { CommandScope } from "@jgengine/core/runtime/commandRunner";
 import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import type { LeaderboardIncrement } from "@jgengine/core/runtime/hostPersistence";
 import { type MatchmakingMode } from "@jgengine/core/runtime/hostPolicy";
@@ -135,9 +136,13 @@ export declare function jgengineTables(): {
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        kind?: string | undefined;
+        label?: string | undefined;
+        revokedAt?: number | undefined;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
+        sessionId?: string | undefined;
         updatedAt: number;
         userId: string;
         x: number;
@@ -146,15 +151,24 @@ export declare function jgengineTables(): {
     }, {
         serverId: import("convex/values").VString<string, "required">;
         userId: import("convex/values").VString<string, "required">;
+        /** One row per live session, so a second tab is a second row rather than a fight over one. */
+        sessionId: import("convex/values").VString<string | undefined, "optional">;
+        /** Actor class, e.g. `"player"` / `"agent"`, which selects the pose rules applied to it. */
+        kind: import("convex/values").VString<string | undefined, "optional">;
+        /** Display name carried on the row, so nameplates need no per-frame join against users. */
+        label: import("convex/values").VString<string | undefined, "optional">;
         x: import("convex/values").VFloat64<number, "required">;
         y: import("convex/values").VFloat64<number, "required">;
         z: import("convex/values").VFloat64<number, "required">;
         rotationY: import("convex/values").VFloat64<number, "required">;
         rotationPitch: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "rotationPitch" | "rotationY" | "serverId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
+        /** Set when the session was displaced or left; the reaper deletes the row once it goes idle. */
+        revokedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "kind" | "label" | "revokedAt" | "rotationPitch" | "rotationY" | "serverId" | "sessionId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
         by_server: ["serverId", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
+        by_updated: ["updatedAt", "_creationTime"];
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
@@ -328,9 +342,13 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        kind?: string | undefined;
+        label?: string | undefined;
+        revokedAt?: number | undefined;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
+        sessionId?: string | undefined;
         updatedAt: number;
         userId: string;
         x: number;
@@ -339,15 +357,24 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {
         serverId: import("convex/values").VString<string, "required">;
         userId: import("convex/values").VString<string, "required">;
+        /** One row per live session, so a second tab is a second row rather than a fight over one. */
+        sessionId: import("convex/values").VString<string | undefined, "optional">;
+        /** Actor class, e.g. `"player"` / `"agent"`, which selects the pose rules applied to it. */
+        kind: import("convex/values").VString<string | undefined, "optional">;
+        /** Display name carried on the row, so nameplates need no per-frame join against users. */
+        label: import("convex/values").VString<string | undefined, "optional">;
         x: import("convex/values").VFloat64<number, "required">;
         y: import("convex/values").VFloat64<number, "required">;
         z: import("convex/values").VFloat64<number, "required">;
         rotationY: import("convex/values").VFloat64<number, "required">;
         rotationPitch: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "rotationPitch" | "rotationY" | "serverId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
+        /** Set when the session was displaced or left; the reaper deletes the row once it goes idle. */
+        revokedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "kind" | "label" | "revokedAt" | "rotationPitch" | "rotationY" | "serverId" | "sessionId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
         by_server: ["serverId", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
+        by_updated: ["updatedAt", "_creationTime"];
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
@@ -389,13 +416,11 @@ export declare function resolveActor(ctx: {
  *
  * Persisting a narrowed snapshot is safe: the plan merges session state over the stored map and
  * writes only dirty profiles and dirty chunks, so members and chunks left unhydrated are untouched.
+ *
+ * The registered `runCommand` mutation takes one, and a {@link CommandDef} can derive its own from
+ * its input via `scope`, so a game gets bounded hydration without writing its own mutation.
  */
-export type LoadSnapshotScope = {
-    /** Member ids to hydrate; omit for the whole roster. */
-    players?: readonly string[];
-    /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */
-    chunkKeys?: readonly string[];
-};
+export type LoadSnapshotScope = CommandScope;
 /**
  * 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.
@@ -430,6 +455,11 @@ export type RunCommandArgs = {
     command: string;
     input: unknown;
     externalId?: string;
+    /**
+     * How much of the server to hydrate before applying the command. Overrides whatever the
+     * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world.
+     */
+    scope?: LoadSnapshotScope;
 };
 /** A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot. */
 export type LoadedServerSnapshot = {
@@ -508,6 +538,10 @@ export declare function createGameServerFunctions(options?: {
         command: string;
         externalId?: string | undefined;
         input: any;
+        scope?: {
+            chunkKeys?: string[] | undefined;
+            players?: string[] | undefined;
+        } | undefined;
         serverId: GenericId<"jgGameServers">;
     }, Promise<RunCommandOutcome>>;
     flushSave: import("convex/server").RegisteredMutation<"public", {
@@ -630,41 +664,92 @@ export declare function createLeaderboardFunctions(options?: {
         gameId: string;
     }, Promise<null>>;
 };
-/** @internal */
+/** One member's pose as `list` reports it. */
+export type PresenceListRow = {
+    userId: string;
+    sessionId?: string;
+    kind?: string;
+    label?: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    rotationPitch: number;
+    lastSeenAt: number;
+};
+/** What `sync` hands back: the pose the server holds after clamping, and whether this session had been displaced. */
+export type PresenceSyncResult = {
+    pose: {
+        x: number;
+        y: number;
+        z: number;
+        rotationY: number;
+        rotationPitch: number;
+    };
+    lastSeenAt: number;
+    displaced: boolean;
+};
+/**
+ * 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 declare function createPresenceFunctions(options?: {
     auth?: JgAuthMode;
+    /** How recently a row must have been written to appear in `list`. */
     freshWindowMs?: number;
-    poseRules?: PoseSyncRules;
+    /** How long a row may go unwritten before `reapIdlePresence` deletes it. */
+    idleCutoffMs?: number;
+    /** Rows deleted per reaper run, so one sweep is a bounded transaction. */
+    maxReapPerRun?: number;
+    /** Movement clamping, optionally per actor `kind` — an agent need not obey a human's speed cap. */
+    poseRules?: PoseSyncRules | ((kind: string | undefined) => PoseSyncRules);
+    /** Where a session with no row starts. Async and ctx-bearing, so a spawn can read the world. */
+    resolveSpawn?: (ctx: JGMutationCtx, args: {
+        serverId: string;
+        userId: string;
+        kind?: string;
+    }) => Promise<{
+        x: number;
+        y: number;
+        z: number;
+    } | null> | {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
 }): {
     list: import("convex/server").RegisteredQuery<"public", {
         externalId?: string | undefined;
         serverId: string;
-    }, Promise<{
-        userId: string;
-        position: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        rotationY: number;
-        rotationPitch: number;
-        lastSeenAt: number;
-    }[]>>;
+    }, Promise<PresenceListRow[]>>;
     sync: import("convex/server").RegisteredMutation<"public", {
         externalId?: string | undefined;
-        pose: {
+        kind?: string | undefined;
+        label?: string | undefined;
+        pose?: {
             rotationPitch: number;
             rotationY: number;
             x: number;
             y: number;
             z: number;
-        };
+        } | undefined;
         serverId: string;
-    }, Promise<null>>;
+        sessionId?: string | undefined;
+    }, Promise<PresenceSyncResult | null>>;
     leave: import("convex/server").RegisteredMutation<"public", {
         externalId?: string | undefined;
         serverId: string;
+        sessionId?: string | undefined;
     }, Promise<null>>;
+    reapIdlePresence: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+        reaped: number;
+    }>>;
 };
 /** @internal */
 export declare function createChatFunctions(options?: {
@@ -688,7 +773,9 @@ export declare function createChatFunctions(options?: {
 export type JgCronSpec = {
     name: string;
     intervalSeconds: number;
-    functionKey: "tickActiveServers" | "flushDirtyServers";
+    functionKey: "tickActiveServers" | "flushDirtyServers" | "reapIdlePresence";
+    /** Which factory's exports the function lives in, i.e. which `convex/*.ts` file to reach it through. */
+    module: "runtime" | "presence";
 };
 /** @internal */
 export declare function jgengineCronSpecs(): readonly JgCronSpec[];

package/dist/server.js

@@ -1,7 +1,8 @@
 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 { JG_MAX_MEMBERS_PER_SERVER, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, selectJoinTarget, statusAfterLeave, validateSlotsPerServer, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
@@ -77,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(),
@@ -385,6 +395,7 @@ async function flushServerIfDue(ctx, server, now, runtime, loaded) {
     if (!shouldAutoSave(server.save, server.dirtyAt, server.lastSavedAt, now)) {
         return false;
     }
+    // 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;
@@ -532,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 };
@@ -551,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 };
@@ -598,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,
@@ -611,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" };
@@ -629,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),
@@ -645,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;
@@ -888,6 +913,7 @@ export function createGameServerFunctions(options) {
                         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);
@@ -912,6 +938,7 @@ export function createGameServerFunctions(options) {
             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;
@@ -1002,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(),
@@ -1014,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(),
@@ -1027,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,
@@ -1038,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(),
@@ -1099,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) {
@@ -1198,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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,7 +30,7 @@
     "check-types": "bun ../../scripts/check-types-preflight.ts && tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.17.0"
+    "@jgengine/core": "^0.18.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.17.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.18.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -228,7 +228,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.17.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.18.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -260,7 +260,8 @@
 
 ## @jgengine/core/runtime/commandRunner
 
-- `CommandDef` (type): type CommandDef<TInput = unknown> = { validate: ( snapshot: GameRuntimeSnapshot, input: TInput, actorUserId: string, ) => CommandValidationError | null; apply: ( snapshot: GameRuntimeSnapshot, input: TInput, actorUserId: string, ) => GameRuntimeSnapshot; } — ⚠ undocumented
+- `CommandDef` (type): type CommandDef<TInput = unknown> = { /** * What this command reads and writes, derived from its own input. A host that hydrates through a * scope loads only this slice instead of the whole world, and refuses the command if `apply` then * dirties a player or chunk the scope did not name — writing an… — ⚠ undocumented
+- `CommandScope` (type): type CommandScope = { /** Member ids to hydrate; omit for the whole roster. */ players?: readonly string[]; /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */ chunkKeys?: readonly string[]; } — Which slice of a server has to be hydrated before some work runs against it. Both fields default to "everything", which costs a read per member plus one per chunk — the cost that makes a large shared world unaffordable per mutation. Narrow them when the caller knows what it will touch.
 - `CommandValidationError` (type): type CommandValidationError = { reason: string } — ⚠ undocumented
 - `RunCommandResult` (type): type RunCommandResult = | { ok: true; snapshot: GameRuntimeSnapshot } | { ok: false; reason: string } — ⚠ undocumented
 
@@ -340,7 +341,7 @@
 - `RuntimeInitContext` (type): type RuntimeInitContext = { snapshot: GameRuntimeSnapshot; setSnapshot: (snapshot: GameRuntimeSnapshot) => void; } — ⚠ undocumented
 - `RuntimeLoopContext` (type): type RuntimeLoopContext = RuntimeInitContext & { player: { userId: string; isNew: boolean; }; } — ⚠ undocumented
 - `RuntimeWorldContext` (type): type RuntimeWorldContext = RuntimeInitContext & { playerIds: readonly string[]; } — ⚠ undocumented
-- `ServerLoopHooks` (type): type ServerLoopHooks = { onInit?: (ctx: RuntimeInitContext) => void; onNewPlayer?: (ctx: RuntimeLoopContext) => void; onTick?: (ctx: RuntimeWorldContext, dtSeconds: number) => void; } — ⚠ undocumented
+- `ServerLoopHooks` (type): type ServerLoopHooks = { onInit?: (ctx: RuntimeInitContext) => void; onNewPlayer?: (ctx: RuntimeLoopContext) => void; onTick?: (ctx: RuntimeWorldContext, dtSeconds: number) => void; /** * What `onNewPlayer` touches, so a join hydrates that instead of the whole world. Only consulted * when `onNewPlay… — ⚠ undocumented
 
 ## @jgengine/core/runtime/headlessRunner
 
@@ -477,7 +478,7 @@
 - `JoinServerResult` (type): type JoinServerResult = { serverId: string; isNew: boolean; } — ⚠ undocumented
 - `LiveGameBackend` (type): type LiveGameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = GameBackend<TPresenceRow, TPresenceLocation, TGameId> & { presenceSync: PresenceSync; pushFeedEntry: (args: { serverId: string; action: string; entry: unknown }) => Promise<void>; chatSyncFor… — ⚠ undocumented
 - `MultiplayerSession` (type): type MultiplayerSession = { gameId: string; userId: string; backend: LiveGameBackend; feedActions: string[]; } — ⚠ undocumented
-- `PresencePoseRow` (type): type PresencePoseRow = { userId: string; position: { x: number; y: number; z: number }; rotationY: number; rotationPitch: number; lastSeenAt: number; } — ⚠ undocumented
+- `PresencePoseRow` (type): type PresencePoseRow = { userId: string; /** Set when the host tracks presence per session, so one user can hold two rows. */ sessionId?: string; /** Actor class, e.g. `"player"` / `"agent"` — a host may clamp each differently. */ kind?: string; /** Display name carried on the row, so a nameplate ne… — ⚠ undocumented
 - `PresenceSync` (type): type PresenceSync = { subscribe: (serverId: string, onChange: (rows: PresencePoseRow[]) => void) => FeedUnsubscribe; syncPose: (serverId: string, pose: PlayerPose) => void; } — ⚠ undocumented
 - `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; } — ⚠ undocumented
 - `TransportRunCommandResult` (type): type TransportRunCommandResult = | { ok: true } | { ok: false; reason: string } — ⚠ undocumented

package/skills/jgengine-multiplayer/api.md

@@ -10,7 +10,7 @@
 - `ConvexGameApi` (type): type ConvexGameApi = { runtime: { joinServer: FunctionReference< "mutation", "public", { gameId: string; serverId?: string; mode?: string; visibility?: "public" | "private"; joinCode?: string; externalId?: string; }, { serverId: string; isNew: boolean } >; leaveServer: FunctionReference<"mutation", … — ⚠ undocumented
 - `ConvexGameTransportConfig` (type): type ConvexGameTransportConfig = { gameId: string; userId?: string; } — ⚠ undocumented
 - `ConvexLeaderboardReads` (type): type ConvexLeaderboardReads = ReturnType<typeof createConvexLeaderboardReads> — ⚠ undocumented
-- `ConvexPresenceFunctions` (interface): interface ConvexPresenceFunctions — ⚠ undocumented
+- `ConvexPresenceFunctions` (interface): interface ConvexPresenceFunctions — The Convex functions a **game** supplies for a world it owns: presence keyed by the game's own ids, including which residents exist while offline, which is game content and has no engine analogue. Not satisfied by `createPresenceFunctions` (`@jgengine/convex/server`) — that is the pose lane of a hosted `jgGameServers` server, backing `PresenceSync` rather than `PresenceTransport`.
 - `ConvexSaveBackendOptions` (interface): interface ConvexSaveBackendOptions — Config for {@link createConvexSaveBackend} — the Convex client, optional function refs (defaults to the `saves.*` convention), and an optional key `namespace`.
 - `ConvexSaveFunctions` (interface): interface ConvexSaveFunctions — The three Convex functions a save backend calls — a `query` that returns the stored string (or `null`) and two `mutation`s. Point them at your app's own module, or lean on the default `saves.*` convention.
 - `DEFAULT_CONVEX_POSE_RULES` (const): const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules — ⚠ undocumented
@@ -25,13 +25,15 @@
 - `JG_MAX_MEMBERS_PER_SERVER` (const): const JG_MAX_MEMBERS_PER_SERVER: 256 — Hard ceiling on `slotsPerServer` for a single hosted server row.
 - `JG_RUNTIME_TICK_MS` (const): const JG_RUNTIME_TICK_MS: 1000 — ⚠ undocumented
 - `JgAuthMode` (type): type JgAuthMode = "anonymous" | "required" — ⚠ undocumented
-- `JgCronSpec` (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers"; } — ⚠ undocumented
-- `LoadSnapshotScope` (type): type LoadSnapshotScope = { /** Member ids to hydrate; omit for the whole roster. */ players?: readonly string[]; /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */ chunkKeys?: readonly string[]; } — How much of a server to hydrate. Both fields default to "everything", which is a document read per member plus one per chunk — the cost that makes a large shared world unaffordable per mutation. Narrow them when the caller knows what it will touch: a command that only moves the actor's own state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
+- `JgCronSpec` (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers" | "reapIdlePresence"; /** Which factory's exports the function lives in, i.e. which `convex/*.ts` file to reach it through. */ module: "runtime" | "presence"; } — ⚠ undocumented
+- `LoadSnapshotScope` (type): type LoadSnapshotScope = CommandScope — How much of a server to hydrate. Both fields default to "everything", which is a document read per member plus one per chunk — the cost that makes a large shared world unaffordable per mutation. Narrow them when the caller knows what it will touch: a command that only moves the actor's own state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
 - `LoadedServerSnapshot` (type): type LoadedServerSnapshot = { server: ServerDoc; runtime: GameRuntime; snapshot: GameRuntimeSnapshot; } — A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot.
 - `MAX_CHUNKS_PER_QUERY` (const): const MAX_CHUNKS_PER_QUERY: 64 — How many chunk rows one `getChunks` call may return.
 - `MatchmakingMode` (type): type MatchmakingMode = "auto" | "singleton" — How auto-match behaves when no `serverId` is supplied.
+- `PresenceListRow` (type): type PresenceListRow = { userId: string; sessionId?: string; kind?: string; label?: string; position: { x: number; y: number; z: number }; rotationY: number; rotationPitch: number; lastSeenAt: number; } — One member's pose as `list` reports it.
+- `PresenceSyncResult` (type): type PresenceSyncResult = { pose: { x: number; y: number; z: number; rotationY: number; rotationPitch: number }; lastSeenAt: number; displaced: boolean; } — What `sync` hands back: the pose the server holds after clamping, and whether this session had been displaced.
 - `REVISION_CONFLICT_REASON` (const): const REVISION_CONFLICT_REASON: "Revision conflict" — ⚠ undocumented
-- `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; externalId?: string; } — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
+- `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; externalId?: string; /** * How much of the server to hydrate before applying the command. Overrides whatever the * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world. */ scope?: LoadSnap… — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
 - `RunCommandOutcome` (type): type RunCommandOutcome = { ok: true } | { ok: false; reason: string } — Outcome of a runtime command: applied, or refused with a reason (unknown server, non-member, validation, revision conflict).
 - `ServerDoc` (type): type ServerDoc = DocumentByName<JGDataModel, "jgGameServers"> — A `jgGameServers` row — the server handle the persistence helpers load from and write back to.
 - `canJoinPrivateServer` (function): function canJoinPrivateServer(args: { isMember: boolean; joinCode: string | undefined; suppliedCode: string | undefined; }): boolean — Private-server join-code gate. Existing members always pass; non-members must present a matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide whether the server is private — this only answers the code/membership half.
@@ -62,7 +64,7 @@
 
 ## @jgengine/convex/convexPresenceTransport
 
-- `ConvexPresenceFunctions` (interface): interface ConvexPresenceFunctions — ⚠ undocumented
+- `ConvexPresenceFunctions` (interface): interface ConvexPresenceFunctions — The Convex functions a **game** supplies for a world it owns: presence keyed by the game's own ids, including which residents exist while offline, which is game content and has no engine analogue. Not satisfied by `createPresenceFunctions` (`@jgengine/convex/server`) — that is the pose lane of a hosted `jgGameServers` server, backing `PresenceSync` rather than `PresenceTransport`.
 - `createConvexPresenceTransport` (function): function createConvexPresenceTransport<TRawRow extends RawPresenceActor, TRow, TLocation, TGameId extends string = string>(functions: ConvexPresenceFunctions, mapRow: (row: TRawRow) => TRow): PresenceTransport<TRow, TLocation, TGameId> — Wires a game's Convex presence functions into the engine's PresenceTransport contract: one snapshot subscription (my location + online players), one residents subscription (dormant candidates, decoupled from pose writes), and one tick mutation for pose upload + keep-alive. Dormant rows are derived client-side by subtracting the snapshot's online actors, so pose ticks never re-execute the residents query. mapRow converts backend rows into the game's row type (e.g. branding positions into its coordinate space).
 
 ## @jgengine/convex/convexSaveBackend
@@ -118,12 +120,14 @@
 - `JG_MAX_MEMBERS_PER_SERVER` (const): const JG_MAX_MEMBERS_PER_SERVER: 256 — Hard ceiling on `slotsPerServer` for a single hosted server row.
 - `JG_RUNTIME_TICK_MS` (const): const JG_RUNTIME_TICK_MS: 1000 — ⚠ undocumented
 - `JgAuthMode` (type): type JgAuthMode = "anonymous" | "required" — ⚠ undocumented
-- `JgCronSpec` (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers"; } — ⚠ undocumented
-- `LoadSnapshotScope` (type): type LoadSnapshotScope = { /** Member ids to hydrate; omit for the whole roster. */ players?: readonly string[]; /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */ chunkKeys?: readonly string[]; } — How much of a server to hydrate. Both fields default to "everything", which is a document read per member plus one per chunk — the cost that makes a large shared world unaffordable per mutation. Narrow them when the caller knows what it will touch: a command that only moves the actor's own state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
+- `JgCronSpec` (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers" | "reapIdlePresence"; /** Which factory's exports the function lives in, i.e. which `convex/*.ts` file to reach it through. */ module: "runtime" | "presence"; } — ⚠ undocumented
+- `LoadSnapshotScope` (type): type LoadSnapshotScope = CommandScope — How much of a server to hydrate. Both fields default to "everything", which is a document read per member plus one per chunk — the cost that makes a large shared world unaffordable per mutation. Narrow them when the caller knows what it will touch: a command that only moves the actor's own state needs `players: [actorUserId]`, and a spatial edit needs only the chunk keys it writes (`chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`).
 - `LoadedServerSnapshot` (type): type LoadedServerSnapshot = { server: ServerDoc; runtime: GameRuntime; snapshot: GameRuntimeSnapshot; } — A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot.
 - `MAX_CHUNKS_PER_QUERY` (const): const MAX_CHUNKS_PER_QUERY: 64 — How many chunk rows one `getChunks` call may return.
 - `MatchmakingMode` (type): type MatchmakingMode = "auto" | "singleton" — How auto-match behaves when no `serverId` is supplied.
-- `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; externalId?: string; } — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
+- `PresenceListRow` (type): type PresenceListRow = { userId: string; sessionId?: string; kind?: string; label?: string; position: { x: number; y: number; z: number }; rotationY: number; rotationPitch: number; lastSeenAt: number; } — One member's pose as `list` reports it.
+- `PresenceSyncResult` (type): type PresenceSyncResult = { pose: { x: number; y: number; z: number; rotationY: number; rotationPitch: number }; lastSeenAt: number; displaced: boolean; } — What `sync` hands back: the pose the server holds after clamping, and whether this session had been displaced.
+- `RunCommandArgs` (type): type RunCommandArgs = { serverId: string; command: string; input: unknown; externalId?: string; /** * How much of the server to hydrate before applying the command. Overrides whatever the * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world. */ scope?: LoadSnap… — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
 - `RunCommandOutcome` (type): type RunCommandOutcome = { ok: true } | { ok: false; reason: string } — Outcome of a runtime command: applied, or refused with a reason (unknown server, non-member, validation, revision conflict).
 - `ServerDoc` (type): type ServerDoc = DocumentByName<JGDataModel, "jgGameServers"> — A `jgGameServers` row — the server handle the persistence helpers load from and write back to.
 - `canJoinPrivateServer` (function): function canJoinPrivateServer(args: { isMember: boolean; joinCode: string | undefined; suppliedCode: string | undefined; }): boolean — Private-server join-code gate. Existing members always pass; non-members must present a matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide whether the server is private — this only answers the code/membership half.

package/skills/jgengine-multiplayer/reference.md

@@ -33,10 +33,14 @@ Once a session resolves, the shell (`GameHost`'s internal player) wires it up wi
 
 A synced pose (`@jgengine/ws/protocol`'s `WsPose`/`WsPresenceRow`) carries an optional `appearance: Record<string, string | number | boolean>` alongside position/rotation — primitive-valued client-set tags (skin id, mount id, active emote, team color) riding the same pose-sync frames as position, so a remote player's cosmetic state updates on the existing presence channel instead of a second round-trip.
 
-**Server side** — `@jgengine/convex/server` ships an entire authoritative Convex backend as factories, not a template to copy: `jgengineTables()` (schema spread), `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()` (tick/flush interval metadata for a `crons.ts`). A consumer's `convex/` directory is ~25 lines: `schema.ts` (`defineSchema({ ...jgengineTables() })`), four one-line re-export files (`runtime.ts`, `leaderboard.ts`, `presence.ts`, `chat.ts`, each just calling its factory), and `crons.ts` registering the tick (1s) + flush (60s) internal mutations — see `examples/convex-host` for the reference shape. No game-specific code lives there; any JGengine game can point at the same deployment. Games without a registered `GameRuntime` fall back to a no-save runtime that only understands `engine.ping`; pass `createGameServerFunctions({ runtimes: [createGameRuntime({ gameId, commands, loop, save })] })` to make `runCommand` / tick / save actually do something. When a host mutation must pair snapshot work with its own table writes in one transaction, use the factory's `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand` — same registry and auth mode) or the standalone `loadServerSnapshot` / `persistServerSnapshot` exports.
+**Server side** — `@jgengine/convex/server` ships an entire authoritative Convex backend as factories, not a template to copy: `jgengineTables()` (schema spread), `createGameServerFunctions({ runtimes?, auth? })`, `createLeaderboardFunctions({ auth? })`, `createPresenceFunctions({ auth?, freshWindowMs?, idleCutoffMs?, poseRules?, resolveSpawn? })`, `createChatFunctions({ auth?, historyLimit?, maxBodyLength?, minIntervalMs? })`, and `jgengineCronSpecs()` (tick/flush interval metadata for a `crons.ts`). A consumer's `convex/` directory is ~25 lines: `schema.ts` (`defineSchema({ ...jgengineTables() })`), four one-line re-export files (`runtime.ts`, `leaderboard.ts`, `presence.ts`, `chat.ts`, each just calling its factory), and `crons.ts` registering the tick (1s) + flush (60s) internal mutations — see `examples/convex-host` for the reference shape. No game-specific code lives there; any JGengine game can point at the same deployment. Games without a registered `GameRuntime` fall back to a no-save runtime that only understands `engine.ping`; pass `createGameServerFunctions({ runtimes: [createGameRuntime({ gameId, commands, loop, save })] })` to make `runCommand` / tick / save actually do something. When a host mutation must pair snapshot work with its own table writes in one transaction, use the factory's `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand` — same registry and auth mode) or the standalone `loadServerSnapshot` / `persistServerSnapshot` exports.
 
 **How big a hosted world gets.** One server is one Convex document holding the world row, the roster, and every member's session state, so member count is a per-transaction cost. `slotsPerServer` is capped at `JG_MAX_MEMBERS_PER_SERVER` (256) and `createGameServerFunctions` throws at wiring time on anything larger — a bigger number was never a bigger world, just a document that overflows later. World geometry that outgrows one row goes in `jgWorldChunks`: hydrate by key (`loadServerSnapshot(ctx, server, runtime, { players, chunkKeys })`), read from clients with the generated `getChunks`, and key cells with `chunkKeyAt` / `chunkKeysInRadius` from `@jgengine/core/runtime/worldChunks`. Mutate chunks through `setChunk` / `updateChunk` / `deleteChunk` — a raw `snapshot.chunks[key] = …` is never marked dirty and never persists.
 
+**Two presence lanes, and which one you want.** They are not interchangeable and neither replaces the other. `createPresenceFunctions` backs `PresenceSync` — where each member of one hosted `jgGameServers` server is standing, over `jgPoses`, membership-gated, and what the shell wires automatically. It takes `poseRules` (a `PoseSyncRules`, or a function of the actor `kind` so an agent need not obey a human's speed cap), `resolveSpawn(ctx, { serverId, userId, kind })` for where a new session starts, and `idleCutoffMs` for its `reapIdlePresence` cron; `sync` returns the clamped pose so a corrected client can reconcile, takes no `pose` at all for a keep-alive, and carries optional `sessionId` / `kind` / `label` (a second tab is a second row, and syncing revokes the others, which the displaced tab learns as `displaced: true`). `createConvexPresenceTransport` backs `PresenceTransport`, a different contract for a game-owned world: it needs the game's own `ConvexPresenceFunctions` (`snapshot`, `cityResidents`, `ensurePresence`, `leavePresence`, `tick`) keyed by the game's own ids, because who counts as a resident is game content. Reach for the first for members of a hosted server; supply the second yourself when presence spans your own world model.
+
+**Bounded hydration from the ordinary command path.** Give a `CommandDef` a `scope(input, actorUserId) => { players?, chunkKeys? }` and the registered `runCommand` mutation hydrates that slice instead of the whole world — no hand-rolled mutation needed. The mutation also takes a `scope` argument directly, which wins over the declared one; a caller that knows the answer at call time can skip the declaration. Declare only what the command actually writes: `apply` dirtying a player or chunk the scope never named is refused, because persisting an unhydrated chunk writes a blank over the stored one. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`; a runtime with no `onNewPlayer` already hydrates the joining member alone. Leave both off and hydration stays whole-world.
+
 **What the host does per second.** The tick cron sweeps only games whose runtime declares `loop.onTick`, at most `maxServersPerTick` (default 32) servers per transaction, oldest anchor first; a game with no tick hook costs nothing while idle. A persist that would change nothing writes nothing, so an idle world stops re-pushing itself to every subscriber once a second. Subscribe lobby UI to `getServerMeta` (status, member count, revision) rather than `getServer`, whose payload is the whole world, and set `replication: { aoiRadius }` so `entities`, `stats`, and `objects` all cull to each viewer.
 
 **One shared world.** `createGameServerFunctions({ matchmaking: "singleton" })` makes auto-match always target the existing world and refuse a join past capacity, instead of quietly creating a second world the player would be alone in. `joinServer` also reconciles a stored `slotsPerServer`/`save` that has drifted from the host options, so raising the option takes effect on worlds that already exist. Auto-match relies on Convex OCC to resolve two concurrent first-joins (the loser's read set is invalidated and its mutation retries); a non-Convex `HostPersistence` must supply that guarantee itself.