@jgengine/core 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/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.18.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,25 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.17.0";
+export const VERSION = "0.18.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "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.",
+        ],
+        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`).",
+        ],
+        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.",
+            "`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.",
+        ],
+        removed: [],
+    },
     "0.17.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.17.0`: `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.14.0`; `@jgengine/github` is `0.4.0`.",

package/dist/runtime/commandRunner.d.ts

@@ -1,10 +1,46 @@
 export type CommandValidationError = {
     reason: 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.
+ */
+export 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[];
+};
 export 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 unhydrated chunk would overwrite
+     * the stored one with a blank. Omit it to keep the whole-world default.
+     */
+    scope?: (input: TInput, actorUserId: string) => CommandScope;
     validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => CommandValidationError | null;
     apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => import("./snapshot.js").GameRuntimeSnapshot;
 };
+/**
+ * The scope a command declares for this input, or `undefined` when it declares none (hydrate everything).
+ * Evaluate it before hydration: the actor and the command's own input are both known by then.
+ * @internal
+ */
+export declare function resolveCommandScope<TInput>(commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): CommandScope | undefined;
+/**
+ * Widen a scope so the actor is always hydrated. A command's own player row is dirtied by
+ * {@link runCommand} whatever the command did, and an unhydrated player is dropped from the persist.
+ * @internal
+ */
+export declare function scopeWithActor(scope: CommandScope | undefined, actorUserId: string): CommandScope | undefined;
+/**
+ * Why a command's writes escaped the scope it was hydrated under, or `null` when they did not.
+ * A write outside the scope is a silent overwrite of unread state, so the host refuses it.
+ * @internal
+ */
+export declare function commandScopeEscape(scope: CommandScope | undefined, dirty: import("./snapshot.js").GameRuntimeSnapshot["dirty"], commandName: string): string | null;
 export type RunCommandResult = {
     ok: true;
     snapshot: import("./snapshot.js").GameRuntimeSnapshot;

package/dist/runtime/commandRunner.js

@@ -1,3 +1,39 @@
+/**
+ * The scope a command declares for this input, or `undefined` when it declares none (hydrate everything).
+ * Evaluate it before hydration: the actor and the command's own input are both known by then.
+ * @internal
+ */
+export function resolveCommandScope(commands, commandName, input, actorUserId) {
+    return commands[commandName]?.scope?.(input, actorUserId);
+}
+/**
+ * Widen a scope so the actor is always hydrated. A command's own player row is dirtied by
+ * {@link runCommand} whatever the command did, and an unhydrated player is dropped from the persist.
+ * @internal
+ */
+export function scopeWithActor(scope, actorUserId) {
+    if (!scope || scope.players === undefined || scope.players.includes(actorUserId))
+        return scope;
+    return { ...scope, players: [...scope.players, actorUserId] };
+}
+/**
+ * Why a command's writes escaped the scope it was hydrated under, or `null` when they did not.
+ * A write outside the scope is a silent overwrite of unread state, so the host refuses it.
+ * @internal
+ */
+export function commandScopeEscape(scope, dirty, commandName) {
+    if (!scope)
+        return null;
+    const strayPlayers = scope.players === undefined ? [] : dirty.players.filter((id) => !scope.players?.includes(id));
+    const strayChunks = scope.chunkKeys === undefined ? [] : dirty.chunks.filter((key) => !scope.chunkKeys?.includes(key));
+    if (strayPlayers.length === 0 && strayChunks.length === 0)
+        return null;
+    const parts = [
+        strayPlayers.length > 0 ? `players ${strayPlayers.join(", ")}` : null,
+        strayChunks.length > 0 ? `chunks ${strayChunks.join(", ")}` : null,
+    ].filter((part) => part !== null);
+    return `Command "${commandName}" wrote outside its declared scope: ${parts.join("; ")}`;
+}
 /** @internal */
 export function runCommand(snapshot, commands, commandName, input, actorUserId) {
     const command = commands[commandName];

package/dist/runtime/gameRuntime.d.ts

@@ -1,11 +1,17 @@
 import type { SaveConfig } from "./save.js";
-import type { CommandDef } from "./commandRunner.js";
+import type { CommandDef, CommandScope } from "./commandRunner.js";
 import { runCommand } from "./commandRunner.js";
 import { type GameRuntimeSnapshot, type RuntimeChunkRow, type RuntimePlayerRow, type RuntimeProfileRow, type RuntimeServerRow } from "./snapshot.js";
 export 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 `onNewPlayer` exists — without the hook a join provably needs the joining member and nothing
+     * else. Omit it and a join keeps hydrating everything.
+     */
+    joinScope?: (userId: string, isNew: boolean) => CommandScope;
 };
 export type RuntimeInitContext = {
     snapshot: GameRuntimeSnapshot;
@@ -45,6 +51,13 @@ export type GameRuntime = {
     hasTick: boolean;
     hydrate: (input: HydrateInput) => GameRuntimeSnapshot;
     runCommand: (snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown) => ReturnType<typeof runCommand>;
+    /**
+     * What a command declares it will touch, evaluated before hydration so a host can load that slice
+     * and nothing else. `undefined` means the command declared no scope — hydrate everything.
+     */
+    commandScope: (commandName: string, input: unknown, actorUserId: string) => CommandScope | undefined;
+    /** What a join has to hydrate. `undefined` means the whole world, as when `onNewPlayer` is unscoped. */
+    joinScope: (userId: string, isNew: boolean) => CommandScope | undefined;
     tick: (snapshot: GameRuntimeSnapshot, dtSeconds: number) => GameRuntimeSnapshot;
     joinPlayer: (snapshot: GameRuntimeSnapshot, userId: string, isNew: boolean) => GameRuntimeSnapshot;
     toProfileRow: (snapshot: GameRuntimeSnapshot, userId: string) => RuntimeProfileRow | null;

package/dist/runtime/gameRuntime.js

@@ -1,4 +1,4 @@
-import { runCommand } from "./commandRunner.js";
+import { resolveCommandScope, runCommand } from "./commandRunner.js";
 import { createEmptyPlayerRow, createRuntimeSnapshot, } from "./snapshot.js";
 /** @internal */
 export function createGameRuntime(definition) {
@@ -33,6 +33,14 @@ export function createGameRuntime(definition) {
         runCommand(snapshot, actorUserId, commandName, input) {
             return runCommand(snapshot, definition.commands, commandName, input, actorUserId);
         },
+        commandScope(commandName, input, actorUserId) {
+            return resolveCommandScope(definition.commands, commandName, input, actorUserId);
+        },
+        joinScope(userId, isNew) {
+            if (!loop?.onNewPlayer)
+                return { players: [userId], chunkKeys: [] };
+            return loop.joinScope?.(userId, isNew);
+        },
         tick(snapshot, dtSeconds) {
             if (!loop?.onTick)
                 return snapshot;

package/dist/runtime/transport.d.ts

@@ -62,6 +62,12 @@ export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGa
 };
 export 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 needs no second lookup. */
+    label?: string;
     position: {
         x: number;
         y: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

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