@jgengine/convex 0.17.0 → 0.18.1

package/dist/server.d.ts

@@ -1,13 +1,14 @@
-import type { Auth, DataModelFromSchemaDefinition, DocumentByName, GenericMutationCtx } from "convex/server";
+import type { Auth, FunctionReference, DataModelFromSchemaDefinition, DocumentByName, GenericMutationCtx, GenericQueryCtx } from "convex/server";
 import type { GenericId } from "convex/values";
-import type { ChatMessage } from "@jgengine/core/game/chat";
+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";
 import type { SaveConfig } from "@jgengine/core/runtime/save";
-import type { GameRuntimeSnapshot } from "@jgengine/core/runtime/snapshot";
+import type { GameRuntimeSnapshot, RuntimePlayerRow } from "@jgengine/core/runtime/snapshot";
 /** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
 export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, validateSlotsPerServer, type MatchmakingMode, } from "@jgengine/core/runtime/hostPolicy";
 /** @internal */
@@ -18,6 +19,7 @@ export declare function jgengineTables(): {
         gameId: string;
         joinCode?: string | undefined;
         lastSavedAt?: number | undefined;
+        memberCount?: number | undefined;
         memberUserIds: string[];
         mode?: string | undefined;
         modeConfig?: any;
@@ -31,6 +33,7 @@ export declare function jgengineTables(): {
         slotsPerServer: number;
         status: "closed" | "open" | "running";
         tickAnchorMs: number;
+        topology?: "rooms" | "shared" | undefined;
         updatedAt: number;
         visibility?: "private" | "public" | undefined;
     }, {
@@ -40,6 +43,8 @@ export declare function jgengineTables(): {
         modeConfig: import("convex/values").VAny<any, "optional", string>;
         visibility: import("convex/values").VUnion<"private" | "public" | undefined, [import("convex/values").VLiteral<"public", "required">, import("convex/values").VLiteral<"private", "required">], "optional", never>;
         joinCode: import("convex/values").VString<string | undefined, "optional">;
+        topology: import("convex/values").VUnion<"rooms" | "shared" | undefined, [import("convex/values").VLiteral<"shared", "required">, import("convex/values").VLiteral<"rooms", "required">], "optional", never>;
+        memberCount: import("convex/values").VFloat64<number | undefined, "optional">;
         memberUserIds: import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">;
         slotsPerServer: import("convex/values").VFloat64<number, "required">;
         save: import("convex/values").VUnion<"none" | {
@@ -60,29 +65,89 @@ export declare function jgengineTables(): {
         dirtyAt: import("convex/values").VFloat64<number | undefined, "optional">;
         createdAt: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "createdAt" | "dirtyAt" | "gameId" | "joinCode" | "lastSavedAt" | "memberUserIds" | "mode" | "modeConfig" | "revision" | "save" | "save.auto" | "save.scope" | "serverState" | "sessionPlayers" | "slotsPerServer" | "status" | "tickAnchorMs" | "updatedAt" | "visibility" | `modeConfig.${string}` | `serverState.${string}` | `sessionPlayers.${string}`>, {
+    }, "required", "createdAt" | "dirtyAt" | "gameId" | "joinCode" | "lastSavedAt" | "memberCount" | "memberUserIds" | "mode" | "modeConfig" | "revision" | "save" | "save.auto" | "save.scope" | "serverState" | "sessionPlayers" | "slotsPerServer" | "status" | "tickAnchorMs" | "topology" | "updatedAt" | "visibility" | `modeConfig.${string}` | `serverState.${string}` | `sessionPlayers.${string}`>, {
         by_dirty: ["dirtyAt", "_creationTime"];
         by_game_and_status: ["gameId", "status", "_creationTime"];
         by_game_status_tick: ["gameId", "status", "tickAnchorMs", "_creationTime"];
         by_status: ["status", "_creationTime"];
     }, {}, {}>;
+    jgServerCapacity: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        gameId: string;
+        memberCount: number;
+        mode?: string | undefined;
+        serverId: GenericId<"jgGameServers">;
+        slotsPerServer: number;
+        status: "closed" | "open" | "running";
+    }, {
+        serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
+        gameId: import("convex/values").VString<string, "required">;
+        status: import("convex/values").VUnion<"closed" | "open" | "running", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
+        mode: import("convex/values").VString<string | undefined, "optional">;
+        memberCount: import("convex/values").VFloat64<number, "required">;
+        slotsPerServer: import("convex/values").VFloat64<number, "required">;
+    }, "required", "gameId" | "memberCount" | "mode" | "serverId" | "slotsPerServer" | "status">, {
+        by_server: ["serverId", "_creationTime"];
+    }, {}, {}>;
+    jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        joinedAt: number;
+        serverId: GenericId<"jgGameServers">;
+        userId: string;
+    }, {
+        serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
+        userId: import("convex/values").VString<string, "required">;
+        joinedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "joinedAt" | "serverId" | "userId">, {
+        by_server: ["serverId", "_creationTime"];
+        by_server_and_user: ["serverId", "userId", "_creationTime"];
+    }, {}, {}>;
+    jgRateLimits: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        count: number;
+        expiresAt: number;
+        key: string;
+        startedAt: number;
+    }, {
+        key: import("convex/values").VString<string, "required">;
+        startedAt: import("convex/values").VFloat64<number, "required">;
+        count: import("convex/values").VFloat64<number, "required">;
+        expiresAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "count" | "expiresAt" | "key" | "startedAt">, {
+        by_expires: ["expiresAt", "_creationTime"];
+        by_key: ["key", "_creationTime"];
+    }, {}, {}>;
+    jgClientErrors: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        createdAt: number;
+        details?: any;
+        message: string;
+        userId: string;
+    }, {
+        userId: import("convex/values").VString<string, "required">;
+        message: import("convex/values").VString<string, "required">;
+        details: import("convex/values").VAny<any, "optional", string>;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "createdAt" | "details" | "message" | "userId" | `details.${string}`>, {
+        by_created: ["createdAt", "_creationTime"];
+    }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
         dirtyAt?: number | undefined;
         gameId: string;
         playerState: any;
         revision: number;
+        sessionServerId?: GenericId<"jgGameServers"> | undefined;
+        sessionState?: any;
         updatedAt: number;
         userId: string;
     }, {
         userId: import("convex/values").VString<string, "required">;
         gameId: import("convex/values").VString<string, "required">;
         playerState: import("convex/values").VAny<any, "required", string>;
+        sessionState: import("convex/values").VAny<any, "optional", string>;
+        sessionServerId: import("convex/values").VId<GenericId<"jgGameServers"> | undefined, "optional">;
         revision: import("convex/values").VFloat64<number, "required">;
         dirtyAt: import("convex/values").VFloat64<number | undefined, "optional">;
         createdAt: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "createdAt" | "dirtyAt" | "gameId" | "playerState" | "revision" | "updatedAt" | "userId" | `playerState.${string}`>, {
+    }, "required", "createdAt" | "dirtyAt" | "gameId" | "playerState" | "revision" | "sessionServerId" | "sessionState" | "updatedAt" | "userId" | `playerState.${string}` | `sessionState.${string}`>, {
         by_user_and_game: ["userId", "gameId", "_creationTime"];
     }, {}, {}>;
     jgWorldChunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
@@ -135,9 +200,17 @@ export declare function jgengineTables(): {
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        chunkKey?: string | undefined;
+        homeGameId?: string | undefined;
+        kind?: string | undefined;
+        label?: string | undefined;
+        lastWorldSnapshotAt?: number | undefined;
+        ownerActorId?: string | undefined;
+        revokedAt?: number | undefined;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
+        sessionId?: string | undefined;
         updatedAt: number;
         userId: string;
         x: number;
@@ -145,19 +218,40 @@ export declare function jgengineTables(): {
         z: number;
     }, {
         serverId: import("convex/values").VString<string, "required">;
+        homeGameId: import("convex/values").VString<string | undefined, "optional">;
+        ownerActorId: import("convex/values").VString<string | undefined, "optional">;
+        lastWorldSnapshotAt: import("convex/values").VFloat64<number | undefined, "optional">;
+        chunkKey: import("convex/values").VString<string | undefined, "optional">;
         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", "chunkKey" | "homeGameId" | "kind" | "label" | "lastWorldSnapshotAt" | "ownerActorId" | "revokedAt" | "rotationPitch" | "rotationY" | "serverId" | "sessionId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
+        by_home_game: ["homeGameId", "_creationTime"];
+        by_home_game_revoked_updated: ["homeGameId", "revokedAt", "updatedAt", "_creationTime"];
+        by_revoked: ["revokedAt", "_creationTime"];
+        by_revoked_updated: ["revokedAt", "updatedAt", "_creationTime"];
         by_server: ["serverId", "_creationTime"];
+        by_server_and_chunk: ["serverId", "chunkKey", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
+        by_server_user_revoked_updated: ["serverId", "userId", "revokedAt", "updatedAt", "_creationTime"];
+        by_updated: ["updatedAt", "_creationTime"];
+        by_user: ["userId", "_creationTime"];
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
+        authorName?: string | undefined;
         body: string;
         channelId: string;
         serverId: string;
@@ -167,9 +261,11 @@ export declare function jgengineTables(): {
         channelId: import("convex/values").VString<string, "required">;
         userId: import("convex/values").VString<string, "required">;
         body: import("convex/values").VString<string, "required">;
+        authorName: import("convex/values").VString<string | undefined, "optional">;
         at: import("convex/values").VFloat64<number, "required">;
-    }, "required", "at" | "body" | "channelId" | "serverId" | "userId">, {
-        by_server_channel: ["serverId", "channelId", "_creationTime"];
+    }, "required", "at" | "authorName" | "body" | "channelId" | "serverId" | "userId">, {
+        by_at: ["at", "_creationTime"];
+        by_server_channel: ["serverId", "channelId", "at", "_creationTime"];
     }, {}, {}>;
 };
 /**
@@ -211,6 +307,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         gameId: string;
         joinCode?: string | undefined;
         lastSavedAt?: number | undefined;
+        memberCount?: number | undefined;
         memberUserIds: string[];
         mode?: string | undefined;
         modeConfig?: any;
@@ -224,6 +321,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         slotsPerServer: number;
         status: "closed" | "open" | "running";
         tickAnchorMs: number;
+        topology?: "rooms" | "shared" | undefined;
         updatedAt: number;
         visibility?: "private" | "public" | undefined;
     }, {
@@ -233,6 +331,8 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         modeConfig: import("convex/values").VAny<any, "optional", string>;
         visibility: import("convex/values").VUnion<"private" | "public" | undefined, [import("convex/values").VLiteral<"public", "required">, import("convex/values").VLiteral<"private", "required">], "optional", never>;
         joinCode: import("convex/values").VString<string | undefined, "optional">;
+        topology: import("convex/values").VUnion<"rooms" | "shared" | undefined, [import("convex/values").VLiteral<"shared", "required">, import("convex/values").VLiteral<"rooms", "required">], "optional", never>;
+        memberCount: import("convex/values").VFloat64<number | undefined, "optional">;
         memberUserIds: import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">;
         slotsPerServer: import("convex/values").VFloat64<number, "required">;
         save: import("convex/values").VUnion<"none" | {
@@ -253,29 +353,89 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         dirtyAt: import("convex/values").VFloat64<number | undefined, "optional">;
         createdAt: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "createdAt" | "dirtyAt" | "gameId" | "joinCode" | "lastSavedAt" | "memberUserIds" | "mode" | "modeConfig" | "revision" | "save" | "save.auto" | "save.scope" | "serverState" | "sessionPlayers" | "slotsPerServer" | "status" | "tickAnchorMs" | "updatedAt" | "visibility" | `modeConfig.${string}` | `serverState.${string}` | `sessionPlayers.${string}`>, {
+    }, "required", "createdAt" | "dirtyAt" | "gameId" | "joinCode" | "lastSavedAt" | "memberCount" | "memberUserIds" | "mode" | "modeConfig" | "revision" | "save" | "save.auto" | "save.scope" | "serverState" | "sessionPlayers" | "slotsPerServer" | "status" | "tickAnchorMs" | "topology" | "updatedAt" | "visibility" | `modeConfig.${string}` | `serverState.${string}` | `sessionPlayers.${string}`>, {
         by_dirty: ["dirtyAt", "_creationTime"];
         by_game_and_status: ["gameId", "status", "_creationTime"];
         by_game_status_tick: ["gameId", "status", "tickAnchorMs", "_creationTime"];
         by_status: ["status", "_creationTime"];
     }, {}, {}>;
+    jgServerCapacity: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        gameId: string;
+        memberCount: number;
+        mode?: string | undefined;
+        serverId: GenericId<"jgGameServers">;
+        slotsPerServer: number;
+        status: "closed" | "open" | "running";
+    }, {
+        serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
+        gameId: import("convex/values").VString<string, "required">;
+        status: import("convex/values").VUnion<"closed" | "open" | "running", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
+        mode: import("convex/values").VString<string | undefined, "optional">;
+        memberCount: import("convex/values").VFloat64<number, "required">;
+        slotsPerServer: import("convex/values").VFloat64<number, "required">;
+    }, "required", "gameId" | "memberCount" | "mode" | "serverId" | "slotsPerServer" | "status">, {
+        by_server: ["serverId", "_creationTime"];
+    }, {}, {}>;
+    jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        joinedAt: number;
+        serverId: GenericId<"jgGameServers">;
+        userId: string;
+    }, {
+        serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
+        userId: import("convex/values").VString<string, "required">;
+        joinedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "joinedAt" | "serverId" | "userId">, {
+        by_server: ["serverId", "_creationTime"];
+        by_server_and_user: ["serverId", "userId", "_creationTime"];
+    }, {}, {}>;
+    jgRateLimits: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        count: number;
+        expiresAt: number;
+        key: string;
+        startedAt: number;
+    }, {
+        key: import("convex/values").VString<string, "required">;
+        startedAt: import("convex/values").VFloat64<number, "required">;
+        count: import("convex/values").VFloat64<number, "required">;
+        expiresAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "count" | "expiresAt" | "key" | "startedAt">, {
+        by_expires: ["expiresAt", "_creationTime"];
+        by_key: ["key", "_creationTime"];
+    }, {}, {}>;
+    jgClientErrors: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        createdAt: number;
+        details?: any;
+        message: string;
+        userId: string;
+    }, {
+        userId: import("convex/values").VString<string, "required">;
+        message: import("convex/values").VString<string, "required">;
+        details: import("convex/values").VAny<any, "optional", string>;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "createdAt" | "details" | "message" | "userId" | `details.${string}`>, {
+        by_created: ["createdAt", "_creationTime"];
+    }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
         dirtyAt?: number | undefined;
         gameId: string;
         playerState: any;
         revision: number;
+        sessionServerId?: GenericId<"jgGameServers"> | undefined;
+        sessionState?: any;
         updatedAt: number;
         userId: string;
     }, {
         userId: import("convex/values").VString<string, "required">;
         gameId: import("convex/values").VString<string, "required">;
         playerState: import("convex/values").VAny<any, "required", string>;
+        sessionState: import("convex/values").VAny<any, "optional", string>;
+        sessionServerId: import("convex/values").VId<GenericId<"jgGameServers"> | undefined, "optional">;
         revision: import("convex/values").VFloat64<number, "required">;
         dirtyAt: import("convex/values").VFloat64<number | undefined, "optional">;
         createdAt: import("convex/values").VFloat64<number, "required">;
         updatedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "createdAt" | "dirtyAt" | "gameId" | "playerState" | "revision" | "updatedAt" | "userId" | `playerState.${string}`>, {
+    }, "required", "createdAt" | "dirtyAt" | "gameId" | "playerState" | "revision" | "sessionServerId" | "sessionState" | "updatedAt" | "userId" | `playerState.${string}` | `sessionState.${string}`>, {
         by_user_and_game: ["userId", "gameId", "_creationTime"];
     }, {}, {}>;
     jgWorldChunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
@@ -328,9 +488,17 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        chunkKey?: string | undefined;
+        homeGameId?: string | undefined;
+        kind?: string | undefined;
+        label?: string | undefined;
+        lastWorldSnapshotAt?: number | undefined;
+        ownerActorId?: string | undefined;
+        revokedAt?: number | undefined;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
+        sessionId?: string | undefined;
         updatedAt: number;
         userId: string;
         x: number;
@@ -338,19 +506,40 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         z: number;
     }, {
         serverId: import("convex/values").VString<string, "required">;
+        homeGameId: import("convex/values").VString<string | undefined, "optional">;
+        ownerActorId: import("convex/values").VString<string | undefined, "optional">;
+        lastWorldSnapshotAt: import("convex/values").VFloat64<number | undefined, "optional">;
+        chunkKey: import("convex/values").VString<string | undefined, "optional">;
         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", "chunkKey" | "homeGameId" | "kind" | "label" | "lastWorldSnapshotAt" | "ownerActorId" | "revokedAt" | "rotationPitch" | "rotationY" | "serverId" | "sessionId" | "updatedAt" | "userId" | "x" | "y" | "z">, {
+        by_home_game: ["homeGameId", "_creationTime"];
+        by_home_game_revoked_updated: ["homeGameId", "revokedAt", "updatedAt", "_creationTime"];
+        by_revoked: ["revokedAt", "_creationTime"];
+        by_revoked_updated: ["revokedAt", "updatedAt", "_creationTime"];
         by_server: ["serverId", "_creationTime"];
+        by_server_and_chunk: ["serverId", "chunkKey", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
+        by_server_user_revoked_updated: ["serverId", "userId", "revokedAt", "updatedAt", "_creationTime"];
+        by_updated: ["updatedAt", "_creationTime"];
+        by_user: ["userId", "_creationTime"];
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
+        authorName?: string | undefined;
         body: string;
         channelId: string;
         serverId: string;
@@ -360,14 +549,18 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         channelId: import("convex/values").VString<string, "required">;
         userId: import("convex/values").VString<string, "required">;
         body: import("convex/values").VString<string, "required">;
+        authorName: import("convex/values").VString<string | undefined, "optional">;
         at: import("convex/values").VFloat64<number, "required">;
-    }, "required", "at" | "body" | "channelId" | "serverId" | "userId">, {
-        by_server_channel: ["serverId", "channelId", "_creationTime"];
+    }, "required", "at" | "authorName" | "body" | "channelId" | "serverId" | "userId">, {
+        by_at: ["at", "_creationTime"];
+        by_server_channel: ["serverId", "channelId", "at", "_creationTime"];
     }, {}, {}>;
 }, true>;
 /** Data model of the {@link jgengineTables} schema — the shape a host's own Convex ctx must satisfy to
  * call the exported persistence helpers. */
 export type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes>;
+/** Read-only context accepted by engine host queries. */
+export type JGQueryCtx = GenericQueryCtx<JGDataModel>;
 /** Mutation ctx accepted by {@link loadServerSnapshot} / {@link persistServerSnapshot}. */
 export type JGMutationCtx = GenericMutationCtx<JGDataModel>;
 /** A `jgGameServers` row — the server handle the persistence helpers load from and write back to. */
@@ -389,13 +582,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 +621,14 @@ 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;
+    /** Trusted host override after game-specific authorization; never forward a client-supplied actor. */
+    actorUserId?: string;
+    beforePersist?: (ctx: JGMutationCtx, loaded: LoadedServerSnapshot) => Promise<void>;
 };
 /** A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot. */
 export type LoadedServerSnapshot = {
@@ -443,6 +642,7 @@ export type LoadedServerSnapshot = {
  * table writes in one transaction, which a pre-registered mutation cannot do.
  */
 export type GameServerHelpers = {
+    ensureServer: (ctx: JGMutationCtx, gameId: string) => Promise<ServerDoc>;
     loadSnapshot: (ctx: JGMutationCtx, serverId: string, scope?: LoadSnapshotScope) => Promise<LoadedServerSnapshot | null>;
     applyCommand: (args: {
         gameId: string;
@@ -461,6 +661,7 @@ export type GameServerHelpers = {
     };
     persistSnapshot: (ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save?: SaveConfig) => Promise<boolean>;
     runCommand: (ctx: JGMutationCtx, args: RunCommandArgs) => Promise<RunCommandOutcome>;
+    resetPlayerProfile: (ctx: JGMutationCtx, serverId: string, userId: string) => Promise<RuntimePlayerRow>;
 };
 /** How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist. */
 export declare const DEFAULT_MAX_SERVERS_PER_TICK = 32;
@@ -469,10 +670,9 @@ export declare const MAX_CHUNKS_PER_QUERY = 64;
 /**
  * Build the hosted-server Convex functions for a set of game runtimes.
  *
- * **Supported world size.** One server is one Convex document holding the world row, the member
- * roster, and every member's session state, and the host rewrites that document whenever the world
- * changes. `slotsPerServer` is therefore capped at {@link JG_MAX_MEMBERS_PER_SERVER} (256) and a
- * larger value throws here, at wiring time, rather than at the write that overflows the document.
+ * Room topology keeps its roster and session map in the server document and caps capacity at
+ * {@link JG_MAX_MEMBERS_PER_SERVER}. Shared topology stores membership, capacity, and per-player
+ * session state separately; player-only commands and roster changes do not rewrite the world row.
  * World geometry that outgrows one row belongs in `jgWorldChunks`, hydrated by key
  * ({@link LoadSnapshotScope}) and read by clients through `getChunks` — not in `serverState`.
  *
@@ -484,6 +684,7 @@ export declare function createGameServerFunctions(options?: {
     runtimes?: GameRuntime[];
     auth?: JgAuthMode;
     slotsPerServer?: number;
+    topology?: "shared" | "rooms";
     matchmaking?: MatchmakingMode;
     maxServersPerTick?: number;
     allowedFeedActions?: readonly string[];
@@ -497,6 +698,23 @@ export declare function createGameServerFunctions(options?: {
         serverId?: GenericId<"jgGameServers"> | undefined;
         visibility?: "private" | "public" | undefined;
     }, Promise<{
+        ok: false;
+        reason: "unauthorized";
+        serverId?: undefined;
+        isNew?: undefined;
+    } | {
+        ok: false;
+        reason: "closed";
+        serverId?: undefined;
+        isNew?: undefined;
+    } | {
+        ok: false;
+        reason: "full";
+        serverId?: undefined;
+        isNew?: undefined;
+    } | {
+        reason?: undefined;
+        ok: true;
         serverId: GenericId<"jgGameServers">;
         isNew: boolean;
     }>>;
@@ -508,6 +726,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", {
@@ -545,8 +767,17 @@ export declare function createGameServerFunctions(options?: {
         mode: string | undefined;
         memberCount: number;
         slotsPerServer: number;
-        revision: number;
-        updatedAt: number;
+    } | null>>;
+    getServerCapacity: import("convex/server").RegisteredQuery<"public", {
+        externalId?: string | undefined;
+        serverId: GenericId<"jgGameServers">;
+    }, Promise<{
+        _id: GenericId<"jgGameServers">;
+        gameId: string;
+        status: "closed" | "open" | "running";
+        mode: string | undefined;
+        memberCount: number;
+        slotsPerServer: number;
     } | null>>;
     getChunks: import("convex/server").RegisteredQuery<"public", {
         chunkKeys: string[];
@@ -630,41 +861,198 @@ 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;
-    }[]>>;
+        viewerChunkKey?: string | undefined;
+    }, 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;
+    }>>;
+};
+/** One active player delivered to an online-system batch. */
+export type OnlinePlayer = {
+    serverId: string;
+    userId: string;
+    homeGameId?: string;
+};
+/**
+ * Scan one bounded presence page and schedule its handler and continuation in separate transactions.
+ * @capability online-player-batches Schedule bounded active-player or home-game work in separate transactions.
+ */
+export declare function forEachOnlinePlayer(ctx: JGMutationCtx, options: {
+    batchSize?: number;
+    handler: FunctionReference<"mutation", "internal", {
+        players: OnlinePlayer[];
+        nowMs: number;
+    }>;
+    continuation: FunctionReference<"mutation", "internal", {
+        cursor?: string | null;
+        nowMs?: number;
+    }>;
+    cursor?: string | null;
+    nowMs?: number;
+    freshWindowMs?: number;
+    /** Deliver one representative per home game when several agents share a simulation. */
+    groupBy?: "userId" | "homeGameId";
+}): Promise<{
+    scheduled: number;
+    remaining: boolean;
+}>;
+/**
+ * Consume one request in a fixed rate window; concurrent callers serialize on the indexed key.
+ * @capability host-rate-limit Enforce indexed per-key request windows inside authoritative mutations.
+ */
+export declare function rateLimit(ctx: JGMutationCtx, args: {
+    key: string;
+    windowMs: number;
+    max: number;
+    nowMs?: number;
+}): Promise<{
+    ok: boolean;
+    retryAfterMs: number;
+}>;
+/**
+ * Write validated chat in a host transaction after the caller resolves its actor and world.
+ * @capability host-chat-send Validate, rate-limit and persist chat inside an authorized host mutation.
+ */
+export declare function sendChatMessage(ctx: JGMutationCtx, args: {
+    serverId: string;
+    userId: string;
+    body: string;
+    channelId?: string;
+    authorName?: string;
+    maxBodyLength?: number;
+    minIntervalMs?: number;
+}): Promise<ChatSendOutcome>;
+/**
+ * Bounded recent chat for a resolved server; authorization belongs to the calling query.
+ * @capability host-chat-history Read bounded channel history inside an authorized host query.
+ */
+export declare function recentChatMessages(ctx: {
+    db: Pick<JGQueryCtx["db"], "query">;
+}, args: {
+    serverId: string;
+    channelId?: string;
+    limit?: number;
+}): Promise<{
+    _creationTime: number;
+    _id: GenericId<"jgChatMessages">;
+    at: number;
+    authorName?: string | undefined;
+    body: string;
+    channelId: string;
+    serverId: string;
+    userId: string;
+}[]>;
+/**
+ * Authenticated, bounded client diagnostics and bounded retention sweeps.
+ * @capability client-error-reporting Accept authenticated bounded diagnostics with cooldown and retention sweeps.
+ */
+export declare function createClientErrorFunctions(): {
+    reportClientError: import("convex/server").RegisteredMutation<"public", {
+        agentPrompt?: string | undefined;
+        componentStack?: string | undefined;
+        kind?: string | undefined;
+        message: string;
+        pathname?: string | undefined;
+        stack?: string | undefined;
+        url?: string | undefined;
+        userAgent?: string | undefined;
+    }, Promise<{
+        ok: boolean;
+        reason: string;
+    } | {
+        reason?: undefined;
+        ok: boolean;
+    }>>;
+    pruneClientErrors: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+        deleted: number;
+        remaining: boolean;
+    }>>;
+    pruneRateLimits: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+        deleted: number;
+        remaining: boolean;
+    }>>;
 };
 /** @internal */
 export declare function createChatFunctions(options?: {
@@ -678,17 +1066,33 @@ export declare function createChatFunctions(options?: {
         externalId?: string | undefined;
         serverId: string;
     }, Promise<ChatMessage[]>>;
+    recent: import("convex/server").RegisteredQuery<"public", {
+        channelId: string;
+        externalId?: string | undefined;
+        serverId: string;
+    }, Promise<ChatMessage[]>>;
     sendMessage: import("convex/server").RegisteredMutation<"public", {
         body: string;
         channelId: string;
         externalId?: string | undefined;
         serverId: string;
     }, Promise<ChatSendOutcome>>;
+    pruneChatMessages: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+        deleted: number;
+        remaining: boolean;
+    }>>;
 };
 export type JgCronSpec = {
     name: string;
     intervalSeconds: number;
-    functionKey: "tickActiveServers" | "flushDirtyServers";
+    functionKey: "tickActiveServers" | "flushDirtyServers" | "reapIdlePresence" | "pruneChatMessages" | "pruneClientErrors" | "pruneRateLimits";
+    /** Which factory's exports the function lives in, i.e. which `convex/*.ts` file to reach it through. */
+    module: "runtime" | "presence" | "chat" | "clientErrors";
 };
 /** @internal */
-export declare function jgengineCronSpecs(): readonly JgCronSpec[];
+export declare function jgengineCronSpecs(options?: {
+    runtimes?: readonly Pick<GameRuntime, "hasTick">[];
+    intervalSeconds?: Partial<Record<JgCronSpec["functionKey"], number>>;
+    chat?: boolean;
+    clientErrors?: boolean;
+}): readonly JgCronSpec[];