@crowdedkingdoms/crowdyjs 17.14.0-dev.1 → 18.0.1-dev.1

package/MIGRATION.md

@@ -1,3 +1,125 @@
+# CrowdyJS v18 — the legacy engines are gone
+
+**Breaking.** The game API deleted its legacy developer-code engines on dev (cks-game-api #417,
+ck-api `v2.27.0`): Studio compute, the game model and its automations, player compute (its
+browser CLIENT modules too) and the player model. `18.0.0` removes their SDK surface. Their
+code moves to ck-exec (`client.exec`): an app's server code as hubs and spokes, a player's grid
+code as mods, and a mod's browser code as its CLIENT half. Nothing is migrated for you; port the
+code, then upgrade.
+
+**Which 18.** 18.0.0 was published only on the `dev` channel (`18.0.0-dev.1`). **18.0.1 is the
+first 18.x a client on the production channel will see**, and it carries everything on this page:
+the legacy engines' removal (18.0.0) and the platform-administration removal
+([below](#platform-administration-is-not-in-the-sdk), 18.0.1).
+
+**What it needs.** 18.0.0 calls nothing the legacy engines served, so it runs against any API
+with ck-exec CLIENT halves (ck-api `v2.24.0`, as 17.14.0 did). **Crowdy Studio's CLIENT
+projects need ck-api `v2.25.1` or later:** `v2.24.0` and `v2.25.0` refuse to save a
+`crowdy-client-sdk` crate in a Studio project (`CROWDY_STUDIO_MANIFEST_INVALID`, cks-game-api
+#425). The other way round, a 17.x SDK against `v2.27.0` fails every call into a deleted field
+as a GraphQL validation error.
+
+| 17.x | 18.0 |
+| --- | --- |
+| `client.gameModel` (containers, properties, functions, `invoke`, sessions, events, timers, automations, `seed`, lint, the player-count feed) | A hub's own state and endpoints: `client.exec.connect(appId, { nodeType, key })`, then `call` / `subscribe`; timers are `ctx.timer_after` / `ctx.timer_every` in the hub; sessions are a keyed hub (the `session` starter) |
+| `gameModel.defineFeature`, `grantTierFeature`, `revokeTierFeature`, `features`, `tierFeatures` | `client.appAccess.defineFeature`, `grantTierFeature`, `revokeTierFeature`, `features(appId)`, `tierFeatures(appId, tierId?)` (same fields; a hub reads them with `players.features`) |
+| `client.compute` (modules, `invoke`, templates, runs, logs) | `client.exec.starters` / `build` / `waitForBuild` / `deploy`, `logs`, `instances`, `versions`, `activateVersion`, `setEnabled`; manual calls through `connectAsDeveloper` |
+| `client.playerModel` (containers, automations) | A mod's own state and timers |
+| `client.playerCompute` SERVER side (`deploy` with `target: SERVER`, `setEnabled`, `setRequires`, `invoke`, `runs`, `logs`) | Mods: `client.exec.modBuild` / `waitForModBuild` / `modDeploy` / `modSetEnabled`, calls through `connect(appId, { nodeType: execModType(name), key: gridId })`, `modLogs` |
+| `client.playerCompute` CLIENT modules (`deploy`, `versions`, `artifact`, `artifactBytes`, `usage`, `myModules`, `delete`, `setSwitch`, `switches`) | A mod's CLIENT half: `client.exec.modClientBuild` (polled with `modBuildStatus` / `waitForModBuild`), `modClientDeploy` / `modClientDelete`, `modClientArtifactBytes`; its kill ladder is the mod's, `modSetSwitch` |
+| `marketplace.gridClientMods`, `consentGridClientMod`, `trustGridAuthor`, `clientArtifact`, `clientArtifactBytes`, and `client.grid(...).compute.clientMods` | `client.exec.gridClientMods`, `consentClientMod`, `trustAuthor`, `modClientArtifactBytes` (which checks the bytes against their digest); `ExecClientHalves` runs a grid's CLIENT halves |
+| `marketplace.listings` / `versions` / `publishListing` / `publishVersion` / `acquire` / `install` / `uninstall` / `myAcquisitions` / `myInstalls` | `client.exec.modPublish` / `modListings` / `modInstall` / `modUnpublish`; a listing carries its mod's CLIENT half |
+| `playerWallet.policies` / `setPolicy` / `deletePolicy` (`playerWasmPolicies`) | Mods run under the platform's mod limits; the kill ladder is `client.exec.modSetSwitch` |
+| `client.operator` (`computePlatformCeilings`, `setComputePlatformCeilings`) | ck-exec code is bounded by its manifest limits within the platform's; there is nothing to call |
+| `client.kit(appId)` blueprints, `kit.deploy`, engines, `kit.inventory` … `kit.minigames`, `kit.features` | Hubs; the starters for NPCs and mobs, sessions and matchmaking. `kit.social` stays; `kit/wire.ts` codecs and `runOptimisticAction` stay |
+| `createWorldSession({ model })` (`ContainerMirror`) | Subscribe to the hub's topic |
+| `client.grid(...).sessions`, `.model`, `.compute` | A mod on the grid (`client.exec.mod*`) |
+| `PlayerCodeBroker` / `startGridMod` without `engine` (a legacy CLIENT module: unmetered, with the whole client catalog), `ALLOWED_HOST_CALLS` | A CLIENT half, the only kind of player module: `artifactHash`, `fuelPerDispatch` and `consentedHostCalls` are required, the allowlist is `EXEC_CLIENT_HOST_CALLS`, and the module must carry the `ck_fuel` meter |
+| `MODEL_LINT_QUERY`, `modelLintDiagnostics`, `CrowdyModelLintLog`, the `'model-lint'` diagnostic source | The Rust compiler's diagnostics from the build |
+
+- **The player runtime runs CLIENT halves only.** `PlayerCodeBroker`'s `artifactHash` (the
+  served `digest`), `fuelPerDispatch` and `consentedHostCalls` are required, and `engine` is
+  `'ck-exec'` or absent; a broker without them, or asked for another engine, does not start.
+  The glue offers exactly `EXEC_CLIENT_ABI_IMPORTS` and refuses a module without the `ck_fuel`
+  meter; its inert wasi stubs and the `wasi_unstable` alias are gone. `ALLOWED_HOST_CALLS` is
+  gone, and `GLUE_HOST_FUNCTIONS` names the CLIENT allowlist. `startGridMod`'s wasm spec needs
+  the same three values.
+- **CLIENT host calls the legacy engines answered are refused** by the broker as not allowed:
+  the Game Model group (`container_*`, `containers_list`, `property_set`, `edge_*`,
+  `model_invoke`), `sessions_list`, and `grid_state_get` / `grid_state_set`. A mod's server
+  half, a hub keyed by the grid, holds grid state now. `createGridHostCalls` / `startGridMod`
+  lost `allowModelInvoke` and the client's `gameModel`.
+- **What a CLIENT half says and answers, on the page** (new):
+  - `onLog`: its `crowdy::log` lines (crowdy-client-sdk levels 0 debug, 1 info, 2 warn,
+    3 error), at most `PLAYER_CODE_LOG_LINES_PER_SECOND` (20) a second and
+    `PLAYER_CODE_LOG_MAX_CHARS` (1,000) characters each, then a `warn` counting what was
+    dropped. On `PlayerCodeBroker`, `ExecClientHalves` (with the mod) and `startGridMod`. The
+    text is the mod author's: render it as text. Crowdy Studio shows its preview's lines in
+    Logs.
+  - `invoke(payload)`: the module's `handle_invoke` export, called by the page:
+    `PlayerCodeBroker.invoke`, `ExecClientHalves.invoke(modId, payload)` and
+    `RunningGridMod.invoke`, up to `PLAYER_CODE_INVOKE_MAX_BYTES` (256 KiB) each way. The reply
+    is the module's: treat it as untrusted input.
+  - `createGridHostCalls` answers `avatar_state_get` and `grid_permission_check` as the host
+    catalog scopes them: an avatar whose live actor the game places inside the grid
+    (`local.avatarChunk`, then the public `avatarAppState`), and the visiting player
+    (`userId`) on this grid, from the permission keys the game knows
+    (`local.gridPermissionKeys`). Without those they are refused as not offered, as
+    `actors_list` is without `local.actorsInChunk`.
+- **Crowdy Studio runs on ck-exec only.** Drop `serverEngine` from the embed, the controller
+  and `mountCrowdyStudio`, and `playerCompute` from the embed's services and the controller's
+  and `mountCrowdyStudio`'s options (`CrowdyStudioPlayerCompute` is gone); they require
+  `mods: client.exec`, and the embed requires `client.exec`. `CrowdyStudioState` loses
+  `serverEngine`, `runs` (the Runs panel went) and `usage` (`CrowdyStudioUsageSnapshot`:
+  nothing on ck-exec spends player compute quota, and the `'usage'` surface reads the
+  wallet); `logs` are `CrowdyStudioLogLine`s (`id`, `source` `'mod' | 'preview'`,
+  `moduleName`, `level`, `at`, `text`); `CrowdyStudioInvokeResult` is
+  `{ resultJson, durationUs }`. `createCrowdyStudioStarterProject` needs `modStarter` for a
+  kind with a SERVER target and has no `engine`: a CLIENT target is a `crowdy-client-sdk`
+  CLIENT half. The pairing control went: a mod has no pairing.
+- A CLIENT crate still on `crowdy-compute-sdk` is refused before any build, with what to
+  change: `crowdy-client-sdk = "0.1.0"` in `Cargo.toml` and `crowdy_client_sdk` in place of
+  `crowdy_compute_sdk` in `src/`. Its host calls are the same less the Game Model, sessions and
+  grid state (`grid_state_get` / `grid_state_set`).
+- `ENGINE_SWITCHED_OFF` left `CrowdyFaultCode`: nothing raises it now.
+- The kit's type-98 parser is `parseZoneChangeEvent` beside the other wire parsers.
+
+## Platform administration is not in the SDK
+
+The SDK is for normal clients and designed for production: it carries what players,
+developers and org-admins call, and nothing only a super-admin or a platform operator can
+call. **18.0.1** removes the wrappers that were left (18.0.0 still had them). The API still has every one of these
+fields; **use the API directly from your own tooling** (a GraphQL request with an operator's or
+super-admin's session). There is no SDK replacement.
+
+| Removed | Root field |
+| --- | --- |
+| `client.users.paginated`, `client.users.listConnection` | `usersPaginated`, `usersConnection` |
+| `client.users.setSuperAdmin` | `setSuperAdmin` |
+| `client.users.setOperator` | `setOperator` |
+| `client.users.setEarlyAccessOverride` | `setEarlyAccessOverride` |
+| `client.users.updateType` | `updateUserType` |
+| `client.users.forceLogout` | `forceLogoutUser` |
+| `client.payments.all`, `allConnection` (also `client.admin.payments`) | `checkouts`, `checkoutsConnection` |
+| `client.payments.events`, `eventsConnection` | `paymentEvents`, `paymentEventsConnection` |
+| `client.organizations.setStatus` | `setOrgStatus` |
+| `client.apps.setVisibility` | `setAppVisibility` |
+| `client.hosting.all` | `allHostedGames` |
+| `client.hosting.setListing` | `setHostedGameListing` |
+| `client.hosting.takeDown` | `takeDownHostedGame` |
+
+- `client.quotas.set` takes a `ScopedSetQuotaInput`: an `appId` or an `orgId` (and optionally a
+  `tierId`) is required, and it refuses a platform-global rule before any request.
+  `client.quotas.remove` is unchanged; it removes a rule on an org or app the caller manages.
+- `client.users.get` and `client.users.updateState` stay: any session can call them
+  (`updateState` writes only the caller); their docs had said super-admin only.
+- The generated types and documents for those operations are gone from
+  `@crowdedkingdoms/crowdyjs/generated` as well.
+
+`schema.gql` and the generated types follow the game API: the release carries cks-game-api
+`dev`'s SDL after #417 merged (`npm run schema:sync:paths -- --schema <that schema.gql>`, then
+`npm run codegen`).
+
 # 17.14.0 ck-exec CLIENT halves
 
 Dev-tier preview (cks-game-api #422, P3 W1). **The release needs a game API that has #422:**
@@ -65,9 +187,15 @@ trust its author. It replaces the legacy grid-attached client mods, which keep w
 Existing CLIENT projects keep their files: a CLIENT crate on `crowdy-compute-sdk` is refused on
 ck-exec before any build, with what to change (the SDK line becomes
 `crowdy-client-sdk = "0.1.0"`, `crowdy_compute_sdk` becomes `crowdy_client_sdk`; the host
-calls are the same less the Game Model and sessions). `serverEngine: 'player-compute'` keeps
+calls are the same less the Game Model, sessions and grid state, `grid_state_get` /
+`grid_state_set`, which a mod's server half holds now). `serverEngine: 'player-compute'` keeps
 both targets on legacy player compute until 18.0.
 
+**Studio's CLIENT target on ck-exec needs ck-api `v2.25.1` or later.** `v2.24.0` and
+`v2.25.0` refuse to save a `crowdy-client-sdk` crate in a Studio project
+(`CROWDY_STUDIO_MANIFEST_INVALID`, cks-game-api #425), so a CLIENT project cannot start there;
+the SDK calls themselves need only `v2.24.0`.
+
 # 17.13.0 ck-exec observability
 
 Additive (dev-tier preview; ck-api `v2.22.0`).

package/README.md

@@ -2,9 +2,9 @@
 
 The official browser-first TypeScript SDK for **Crowded Kingdoms**. CrowdyJS
 gives you typed clients for the whole platform: identity and
-studio administration (the Management surface), world data and the abstract
-game model (the Game surface), and the UDP proxy realtime stream — all over
-one unified GraphQL API.
+studio administration (the Management surface), world data (the Game surface),
+the UDP proxy realtime stream, and ck-exec, where an app's server code runs —
+all behind one unified GraphQL API.
 
 Authentication follows a two-token model: an identity **session token** for
 account and admin operations, and short-lived **app-scoped tokens** for
@@ -221,27 +221,23 @@ never told about, so a native refresh without it is a re-placement.
 | `client.users` | `me`, `updateGamertag`, profile reads. |
 | `client.session` | Token store, `restore()`, `getToken()`, manual `setToken()`. |
 | `client.portal` | App-scoped token minting (`mintAppToken`) and the cross-origin PKCE entry flow (`beginEntry` / `handleAuthorizeRequest` / `completeEntry` / `refresh`). |
-| `client.hosting` | Third-party hosting on Crowdy Games (17.2.0): `claim` a slug for an app, `beginPublish` / `completePublish` / `abandonPublish` a built bundle, `setEnabled`; public `game(slug)` / `listed()`; operator `all` / `setListing` / `takeDown`. Mutations need an identity session with `manage_apps`. `@crowdedkingdoms/crowdyjs/hosting` exports `publishDirectory(client, { dir, slug })`, the Node helper that does the whole publish for a `dist/`. |
+| `client.hosting` | Third-party hosting on Crowdy Games (17.2.0): `claim` a slug for an app, `beginPublish` / `completePublish` / `abandonPublish` a built bundle, `setEnabled`; public `game(slug)` / `listed()`. Mutations need an identity session with `manage_apps`. `@crowdedkingdoms/crowdyjs/hosting` exports `publishDirectory(client, { dir, slug })`, the Node helper that does the whole publish for a `dist/`. |
 | `client.platform` | Public platform configuration (`config()`). |
 | `client.serverStatus` | `gameClientBootstrap(appId)` — per-app version info, UDP status, spatial limits. |
 | `client.chunks`, `client.voxels`, `client.actors`, `client.avatars`, `client.state` | World data reads + writes: terrain/LODs, voxel edit + history/rollback, durable actors, avatars, per-user app state blobs. |
-| `client.host` | Game-host election (`get`, `amIHost`) + actor liveness `heartbeat`. `amIHost` is UI convenience only — authoritative host gating uses `gameModelInvoke`'s `is_host` policy. |
+| `client.host` | Game-host election (`get`, `amIHost`) + actor liveness `heartbeat`. `amIHost` is UI convenience only — a hub decides host-only actions from its caller. |
 | `client.teleport` | Teleport requests. |
 | `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
-| `client.gameModel` | Abstract game model: containers, properties, functions (incl. model-driven `notify_*` effects), sessions, app-scoped active-session counts (`activePlayerCount`, `activePlayerCountChanged`), container-change push (`containerChanged`), flow-correlation timelines (`flow`), automations / NPCs (`upsertAutomation`, `runAutomation`, `automationRuns`, `automationStats`, …), and one-shot timers (`scheduleInvoke`, `cancelTimer`, `timers`). |
-| `client.compute` | Compute Modules — server-side Rust/WASM logic: author + deploy source (`upsertModule`, `deployVersion`, `deployTemplate`, `waitForCompile`), triggers + policy, synchronous `invoke`, and monitoring (`moduleRuns`, `moduleStats`, `moduleLogs`, `appDiagnostics`). See [Compute Modules](https://docs.crowdedkingdoms.com/game-api/compute-modules). |
-| `client.exec` | **ck-exec (dev-tier preview, 17.9.0):** `connect(appId, { nodeType, key })` opens a player's connection to an execution host; the `ExecConnection` it returns has `call`, `callRaw`, `subscribe`, `ping`, `onReconnect` and `close`, with MessagePack payloads, and it reconnects and renews subscriptions by itself. `deploy({ appId, root, types })` deploys an app's hubs and spokes (`manage_compute`). Players' mods (`modBuild`, `modDeploy`, ...) and, since 17.14.0, their CLIENT halves (`modClientBuild`, `modClientDeploy`, `gridClientMods`, `consentClientMod`, `trustAuthor`, `modClientArtifactBytes`). See [ck-exec](#ck-exec-dev-tier-preview). |
-| `client.playerCompute` | Player-authored SERVER/CLIENT Rust/WASM bound to player-owned grids: deploy source, activate/deactivate, list modules/versions, delete self-authored modules. |
-| `client.playerModel` | Player-owned flexible model containers and grid-confined automations (`containers`, `createContainer`, `setProperty`, `automations`, `createAutomation`, …). |
-| `client.playerWallet` | Player spend: balance, spend caps, card setup, policy, charges. |
-| `client.marketplace` | Player-code store/install/consent flows plus player-authorized grid claims (`claimGridOwnership`, `claimGridChunk`, `releaseClaimedGrid`) and client-mod artifact fetches. The grid-attached client mods (`gridClientMods`, `consentGridClientMod`, `trustGridAuthor`, `clientArtifact(Bytes)`) are superseded by ck-exec CLIENT halves and go in 18.0. |
+| `client.exec` | **ck-exec (dev-tier preview):** an app's server code as hubs and spokes. `connect(appId, { nodeType, key })` opens a player's connection to an execution host; the `ExecConnection` it returns has `call`, `callRaw`, `subscribe`, `ping`, `onReconnect` and `close`, with MessagePack payloads, and it reconnects and renews subscriptions by itself. `starters` / `build` / `deploy` build and deploy an app (`manage_compute`); `logs`, `instances`, `versions`, `activateVersion` and `setEnabled` operate it; `mod*` are players' mods on grids they own, and `modClient*`, `gridClientMods`, `consentClientMod` and `trustAuthor` their CLIENT halves. See [ck-exec](#ck-exec-dev-tier-preview). |
+| `client.playerWallet` | Player spend: balance, ledger, hourly charges, spend caps, card setup, auto-recharge. A ck-exec mod's compute is billed here, to its owner. |
+| `client.marketplace` | Player-authorized grid claims (`claimGridOwnership`, `claimGridChunk`, `releaseClaimedGrid`, requests and invites) and studio moderation of player code (admission queue, listing administration, claim policy). Mods publish and install through `client.exec`. |
 | `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, optimistic revisions, copy-by-value imports, atomic saves. |
 | `client.crowdyStudioGitHub` | Optional GitHub repository for a Crowdy Studio project: status, `bind` (push the project in, or take the repository), `unbind`, `refresh`, `layout`, `tree`, `getFile`, commit-guarded `putFile` / `deleteFile`. While bound the repository is the working tree and every Studio save commits; the project's `files` are the server's mirror at `github.sha`. Never required. |
 | `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendVideoPacket` / `sendVideoFrame`, `sendTextPacket`, `sendClientEvent`, `sendSingleActorMessage`, `sendChannelMessage`). |
 | `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
 | `client.refreshGameplayToken()` | Safely rotates an active game client's app token (see [Token refresh](#token-refresh-during-gameplay)). |
 | `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`, `actor.sendToActor`). |
-| `client.kit(appId)` | Game Kit: ready-made mappings of game concepts onto the game model — see [Game Kit](#game-kit). |
+| `client.kit(appId)` | Game Kit: parties, guilds and chat over teams and channels (`kit.social`) — see [Game Kit](#game-kit). |
 | `createWorldSession(client, appId, config)` | World Stores: opt-in, SDK-managed game state from the `@crowdedkingdoms/crowdyjs/stores` subpath — see [World Stores](#world-stores). |
 
 **Studio-admin surface** (privileged; drive with a server-side / studio token,
@@ -251,7 +247,7 @@ grouped under `client.admin` and mirrored at the top level):
 |---|---|
 | `client.organizations` | Orgs, members, RBAC roles, org API tokens. |
 | `client.apps` | App registry, discovery + routing (`create`, `routeFor`, `marketplace`), visibility, and player-code admission mode / allow-list administration. |
-| `client.appAccess` | Access tiers + per-user grants. |
+| `client.appAccess` | Access tiers + per-user grants, and the feature keys a tier grants (`defineFeature`, `grantTierFeature`, `tierFeatures`, …), which a hub checks with the node API's `players.features`. |
 | `client.billing` | Org wallet + per-app spend budgets. |
 | `client.payments` | Payment checkouts (wallet top-ups, plan purchases). |
 | `client.quotas` | Usage quotas at the org/app scope. |
@@ -259,15 +255,15 @@ grouped under `client.admin` and mirrored at the top level):
 | `client.sharedEnvironment` | Publish to shared, runtime gating, spend caps, auto-billing. |
 | `client.gameApps` | App grids (`createGrid` / `deleteGrid`), first-class grid ownership (`ownership` / `assignOwnership` / `transferOwnership`), and grid runtime-permission administration. |
 
-**Operator surface** (platform operations; requires `is_operator`):
+**The SDK is for normal clients, and designed for production.** It carries what players,
+developers and org-admins call, and nothing only a super-admin or a platform operator can
+call: those fields are in the API, and platform tooling calls them directly (18.0.1 removed
+the last wrappers; see [MIGRATION.md](MIGRATION.md)). There is no `client.operator`, and
+infrastructure operations live in the separate infra-control-plane service.
 
-| Sub-client | What it does |
-|---|---|
-| `client.operator` | Platform compute ceilings (`computePlatformCeilings`, `setComputePlatformCeilings`). Infrastructure operations live in the separate infra-control-plane service, not this SDK. |
-
-Auth, user reads and the studio-admin / operator surfaces use the **identity
-session token**; the world/UDP surfaces require an **app-scoped token** for that
-app. Both go to the same endpoint.
+Auth, user reads and the studio-admin surface use the **identity session token**; the
+world/UDP surfaces require an **app-scoped token** for that app. Both go to the same
+endpoint.
 
 CrowdyJS wraps the full public API surface — every
 non-deprecated public root field has a typed method, with Relay `*Connection`
@@ -485,16 +481,14 @@ pre-bound — convenient for browser games. Advanced callers can always use
 
 ## Grids: player code inside one grid
 
-A grid is a box of chunks a player can own. Everything an app-scoped Studio
-module can do, code running in a grid can do too, confined to that grid:
-spatial messages that originate in it, the grid's own channels, a grid event
-bus, sessions hosted in it, and the player-tier Game Model.
+A grid is a box of chunks a player can own. Code running in a grid is confined
+to it: spatial messages that originate in it, the grid's own channels, and a
+grid event bus. Its server side is a ck-exec mod (`client.exec.mod*`).
 
 ```ts
 const plot = client.grid(appId, gridId);
 await plot.mintToken();                        // learns the box; a grid-scoped token
 await plot.channels.create('plot-chat');       // a grid channel (owner only)
-await plot.sessions.create({ name: 'race' });  // a game within the game
 await plot.send.text({ chunk: { x: 4, y: 0, z: 0 }, uuid, text: 'hi', distance: 2 });
 plot.send.text({ chunk: { x: 9, y: 0, z: 0 }, uuid, text: 'x' }); // throws GridScopeError
 ```
@@ -512,11 +506,17 @@ import { hostGridProgram } from '@crowdedkingdoms/crowdyjs/grid-program';
 await hostGridProgram({ port, scope: client.grid(appId, gridId), graphqlUrl, graphqlWsUrl });
 ```
 
-`startGridMod` runs either a Rust CLIENT mod (WASM) or a JS grid program
-behind one interface; `createGridHostCalls` answers every CLIENT host call in
-the platform catalog through CrowdyJS for a mod's broker. A ck-exec mod's
-CLIENT half is `engine: 'ck-exec'`, and `ExecClientHalves` runs a whole grid's
-(see [A mod's CLIENT half](#a-mods-client-half)).
+`startGridMod` runs either a mod's CLIENT half (WASM) or a JS grid program
+behind one interface, and `ExecClientHalves` runs a whole grid's CLIENT halves
+(see [A mod's CLIENT half](#a-mods-client-half)). `createGridHostCalls` answers
+a CLIENT half's host calls through CrowdyJS confined to the grid. The ones only
+the game can answer need its knowledge: `local.actorsInChunk` for
+`actors_list*`, `local.avatarChunk` (where an avatar's live actor is) for
+`avatar_state_get`, `local.gridPermissionKeys` with the visiting player's
+`userId` for `grid_permission_check`, and `local.drainPointerClicks` for
+`pointer_clicks`; without its hook such a call is refused as not offered. The
+Game Model, sessions and grid state calls went with the legacy engines in
+18.0.0: the broker refuses them.
 
 ## World Stores
 
@@ -573,8 +573,8 @@ The available stores are `self` (your actor + send loop), `actors` (remote
 actor registry with lanes/history/staleness), `errors` (attributed send
 errors), `chunks` (chunk/voxel cache with realtime merge + worldgen
 write-back), `channelInbox` / `actorInbox` (message inboxes), `events` (typed
-event router), `host` (host tracking), `save` / `avatar` (typed durable
-state), and `model` (game-model container mirror).
+event router), `host` (host tracking), and `save` / `avatar` (typed durable
+state).
 
 Every store is **opt-in twice over**: only configured stores are constructed
 (and only they exist on the session's TYPE — `session.host` without
@@ -588,101 +588,25 @@ keep timer-driven sends at full rate while hidden. See the
 
 ## Game Kit
 
-`client.kit(appId)` maps traditional game concepts onto the abstract game
-model + automations API. Studios **deploy blueprints** (the admin "load the
-state/rules" step, requires `manage_apps`); game clients then use the typed
-runtime helpers. Everything composes `client.gameModel` — no new server
-surface.
-
-```ts
-// Studio setup (admin context):
-import { inventoryBlueprint, lockBlueprint, npcBlueprint } from '@crowdedkingdoms/crowdyjs';
-
-await admin.kit(appId).deploy([
-  inventoryBlueprint(),
-  lockBlueprint({ objectTypeName: 'Door', authority: { kind: 'key' } }),
-  npcBlueprint({
-    behaviors: [{
-      name: 'npc-wander',
-      role: 'wanderer',
-      trigger: { intervalMs: 60000 },
-      mutations: [
-        { target: 'self', property: 'x', expression: 'self.x + rand_int(-2, 2)' },
-        { target: 'self', property: 'z', expression: 'self.z + rand_int(-2, 2)' },
-      ],
-    }],
-  }),
-]);
-
-// Game client (player token):
-const kit = game.kit(appId);
-const bag = await kit.inventory.ensure(me.userId);
-const result = await kit.objects.open(doorId, { keyId });
-if (!result.success) console.warn('locked:', result.errorMessage);
-```
-
-Land sale closes the permission loop end to end:
+`client.kit(appId).social` gives parties, guilds and chat rooms in familiar
+words over teams (membership and roles) and channels (messaging), with
+realtime delivery on the UDP notification subscription:
 
 ```ts
-// Studio: sell a plot over a grid; doors on it honor the purchase automatically.
-await admin.kit(appId).deploy([
-  plotBlueprint({ rentable: true }),
-  lockBlueprint({ objectTypeName: 'PlotDoor',
-    authority: { kind: 'chunkPermission', key: 'access', mode: 'smallest' } }),
-]);
-
-// Game client: buying spends gold AND grants enforced grid access atomically.
-const buy = await kit.plots.buy(plotId, walletId);
-if (buy.success) await kit.objects.open(doorId); // has_chunk_permission passes now
+const kit = game.kit(appId, { social: { actorUuid: me.uuid } });
+const party = await kit.social.party.create('raid');   // team + paired channel
+const room = await kit.social.chat.room('lobby');
+kit.social.chat.onMessage(room.groupId, (m) => log(m.senderUuid, m.text));
 ```
 
-NPC blueprints can target by permissions too — e.g. a guard automation whose
-selector has `candidatePermissionWhere: [{ userFrom: { property: 'owner_user_id' },
-op: 'lacks', key: 'access', grid: { property: 'grid_id' } }]` reacts only to
-intruders.
-
-The kit covers the common genre staples end to end — each layer is a blueprint
-builder plus a typed runtime helper:
-
-| Layer | Builder → helper | Highlights |
-| --- | --- | --- |
-| Inventory | `inventoryBlueprint` → `kit.inventory` | bags/stacks, grant/consume/transfer, craft, barter |
-| Objects | `lockBlueprint` → `kit.objects` | lockable doors/chests with key or permission authority |
-| NPCs | `npcBlueprint` → `kit.npcs` | automation-driven NPC instances (spawn, runNow, enable) |
-| Plots | `plotBlueprint` → `kit.plots` | buy/rent land with transactional, replication-enforced grid grants |
-| Economy | `economyBlueprint` → `kit.economy` | multi-currency wallets, atomic shop buys, escrow trades, player market, escrowed order book (`kit.economy.orderBook`) |
-| Progression | `progressionBlueprint` → `kit.progression` | xp/levels via the `fn:` curve helper, skill prerequisite chains, achievements, host-gated rating |
-| Loot | `lootBlueprint` → `kit.loot` | weighted tables unrolled into seed-driven expressions, atomic single-claim, event-triggered drops |
-| Quests | `questsBlueprint` → `kit.quests` | event-automation progress, atomic claim into stack+wallet, cron daily resets, tutorial sequencing |
-| Combat | `combatBlueprint` → `kit.combat` | server-side damage/death, status-effect tick automation, `turnBased`/`hostSynced`, routed attacks |
-| Matches | `matchesBlueprint` → `kit.matches` | session lobbies/rounds/turns/scores, per-match channel + `onMatchChanged` (notify-to-pull) |
-| Decks | `decksBlueprint` → `kit.decks` | hidden hands via owner-visibility `card_id`, shuffle-by-position automation |
-| World sim | `worldsimBlueprint` → `kit.worldsim` | day/night clock with spatial notify, node regen + atomic gather, crops, wave counters, forecasts |
-| Social | `guildBlueprint` → `kit.social` | parties/guilds/chat over teams+channels, grid territory grants, guild hall + bank composite |
-| Leaderboards | `leaderboardsBlueprint` → `kit.leaderboards` | trusted keep-best submits, client-side ranking, cron seasons |
-| Live ops | `liveopsBlueprint` → `kit.liveops` | timed event windows and seasons |
-| Moderation | `moderationBlueprint` → `kit.moderation` | reports, queues, mutes |
-| Telemetry | `telemetryBlueprint` → `kit.telemetry` | counters and lightweight event tracking |
-| Monetization | `featureGate` → `kit.features` | feature keys, tier grants, `*policyExtra` gating on builders |
-| Abilities | — → `kit.abilities` | ability definitions, casts, loadouts |
-| Movement | — → `kit.movement` | movement warden configs + violation parsing |
-| Territory | — → `kit.territory` | control points, factions, enrollment |
-| Racing | — → `kit.racing` | courses, entries, possession (claim/pass/shoot) |
-
-Engine-aware layers talk to compute-module game engines when they are
-deployed, and degrade gracefully on model-only apps via capability detection
-(`kit.engines`): `kit.mobs` (refereed attacks, defs/slots, contact-damage
-parsing), `kit.pets` (adopt/summon/dismiss/rename), `kit.instances` (private
-world slices, seeded runs), `kit.director` (encounter runs),
-`kit.matchmaking` (queues/proposals/rating), `kit.minigames` (invoke-loop
-wrapper), plus engine paths on `kit.matches` / `kit.decks` /
-`kit.leaderboards` and the `kit/wire` pose codec + event parsers. Deploy
-engines alongside blueprints with `kit.deploy(blueprints, { engines })`.
-
-See the docs guides [Modeling game concepts](https://docs.crowdedkingdoms.com/game-api/modeling-game-concepts)
-(the underlying model + genre map) and [Game Kit](https://docs.crowdedkingdoms.com/crowdyjs/game-kit)
-(the SDK surface + the simulation-tier / notify-to-pull / timer / hidden-info
-/ anti-cheat patterns).
+Game rules and state are ck-exec hubs (`client.exec`, below). Two kit pieces
+stand alone: the wire codecs (`encodeEnginePose` / `decodeEnginePose`, the
+48-byte engine pose, `engineLanes`, and `parseEngineEvent` with the typed
+parsers for server events 77 and 90-98) for games whose hubs keep that wire,
+and `runOptimisticAction`, which applies an action locally, asks a referee
+(a hub endpoint, say) and rolls back on a denial. The blueprints,
+`kit.deploy`, the engines and the model-backed helpers went with the game
+model in 18.0.0; see [MIGRATION.md](MIGRATION.md).
 
 ## ck-exec (dev-tier preview)
 
@@ -742,7 +666,8 @@ Integers above 2^53 decode as `number` and lose precision unless you pass
 A mod (a player's code on a grid they own: `modBuild`, `modDeploy`) can carry a **CLIENT
 half** (17.14.0): browser WASM from one `crowdy-client-sdk` crate, which the mod's grid serves
 to visitors who consent to it or trust its author. It runs in the visitor's
-`PlayerCodeBroker`, sandboxed like a legacy CLIENT module.
+`PlayerCodeBroker`, in a worker with no DOM, token or network, and it is the only kind of
+player module the broker runs since 18.0.0.
 
 ```ts
 // The mod's owner builds one crowdy-client-sdk crate and attaches it to the mod.
@@ -770,24 +695,30 @@ const halves = new ExecClientHalves({
   workerUrl,                                  // the platform glue worker, same origin
   onHostCall: (call) => hostCalls(call),      // e.g. createGridHostCalls({ scope, client })
   onPresentation: (p, mod) => hud.set({ source: mod.modId, label: mod.name, payload: p.payload }),
+  onLog: (line, mod) => devConsole.append(mod.name, line.level, line.message), // text, never HTML
   confirm: (prompt) => window.confirm(describe(prompt)), // once per author; ask: 'mod' for each
   onStopped: (mod) => hud.remove(mod.modId),
 });
 halves.enterGrid({ gridId, low, high });      // the grid the player stands in; null to leave
 setInterval(() => void halves.refresh().catch(console.warn), 10_000);
+
+// The page calls a running CLIENT half's handle_invoke; the reply is the module's bytes.
+const reply = await halves.invoke(modId, new TextEncoder().encode('{"ask":"score"}'));
 ```
 
 Each refresh stops the CLIENT halves whose mod is gone or whose digest, capability hash or
-tick interval changed, asks about the rest, and starts the consented ones in a broker with
-`engine: 'ck-exec'`. That engine allows exactly the host calls crowdy-client-sdk makes
-(`EXEC_CLIENT_HOST_CALLS`: no Game Model, sessions or `grid_state_*`), offers exactly the CLIENT
-ABI imports (`EXEC_CLIENT_ABI_IMPORTS`) and runs a module only with its digest, its fuel budget
-and `consentedHostCalls`, the host calls of the summary the player consented to: a call outside
-them is refused, even one whose name the module assembled at run time.
-`NOT_FOUND` holds a CLIENT half back 15 s and `RATE_LIMITED` 60 s. The grid's owner is asked
-about their own CLIENT halves like anyone; answer yes in `confirm` when `prompt.authorId` is
-the player. The legacy grid-attached client mods (`marketplace.gridClientMods` and the rest)
-keep working until 18.0.
+tick interval changed, asks about the rest, and starts the consented ones in a broker. The
+broker allows at most the host calls crowdy-client-sdk makes (`EXEC_CLIENT_HOST_CALLS`: no Game
+Model, sessions or `grid_state_*`), offers exactly the CLIENT ABI imports
+(`EXEC_CLIENT_ABI_IMPORTS`) and runs a module only with its digest, its fuel budget and
+`consentedHostCalls`, the host calls of the summary the player consented to: a call outside them
+is refused, even one whose name the module assembled at run time. A CLIENT half's
+`crowdy::log` lines reach `onLog` at most 20 a second and 1,000 characters each (then a `warn`
+counts what was dropped); `invoke` sends at most 256 KiB each way and is refused while the
+module is not running. `NOT_FOUND` holds a CLIENT half back 15 s and `RATE_LIMITED` 60 s. The
+grid's owner is asked about their own CLIENT halves like anyone; answer yes in `confirm` when
+`prompt.authorId` is the player. See
+[CLIENT halves](https://docs.dev.crowdedkingdoms.com/exec/client-halves).
 
 ## Hosting a game on Crowdy Games
 
@@ -818,7 +749,7 @@ uploads with the exact signed headers, and `completeGamePublish` verifies every
 object, promotes it and invalidates the CDN. The slug is a DNS label, global on the
 tier, and first-party names are reserved (`HOSTED_SLUG_UNAVAILABLE`); a tier without
 a content CDN answers `CONTENT_HOSTING_DISABLED`. Being *listed* in the lobby is an
-operator decision (`setListing`); publishing is self-serve. `the-construct`'s
+operator decision, made outside the SDK; publishing is self-serve. `the-construct`'s
 `npm run publish` is this section as a command.
 
 ## Crowdy Studio
@@ -827,28 +758,32 @@ Crowdy Studio is the in-game SERVER/CLIENT Rust authoring surface for player
 code: cloud projects with target-scoped files, optimistic-concurrency
 autosave, draft/live/stop orchestration, and a Monaco editor backed by a local
 Rust language worker. The worker receives source files and the embedded
-platform index only — never a credential and never a server connection.
-Compiled CLIENT artifacts run through `PlayerCodeBroker`, which keeps tokens
-on the page, allow-lists host calls, and locally clamps chunk-targeted effects
-to the owned grid before the normal SDK path reaches server authorization.
-The host only ticks a CLIENT mod when `tickIntervalMs` is set (omit or `0`
-is invoke-only):
+platform index (the `ckx-sdk` and `crowdy-client-sdk` symbols) only — never a
+credential and never a server connection. A CLIENT half runs through
+`PlayerCodeBroker`, which keeps tokens on the page, allow-lists host calls
+(narrowed to what the player consented to), and locally clamps chunk-targeted
+effects to the owned grid before the normal SDK path reaches server
+authorization. It takes what the platform served with the module, and ticks it
+only when `tickIntervalMs` is set (omit or `0` is invoke-only):
 
 ```ts
 import { PlayerCodeBroker } from '@crowdedkingdoms/crowdyjs';
 
+const half = await client.exec.modClientArtifactBytes(appId, modId);
 const broker = new PlayerCodeBroker({
   workerUrl,
   grid,
   onHostCall,
-  tickIntervalMs: 1000, // required for on_tick; omit for invoke-only
+  moduleName: half.name,
+  artifactHash: half.digest,
+  fuelPerDispatch: half.fuelPerDispatch,
+  consentedHostCalls: half.capabilitySummary.hostFunctions,
+  tickIntervalMs: half.tickIntervalMs, // omit for invoke-only
+  onLog: (line) => console.log(`[${line.moduleName}] ${line.level}: ${line.message}`),
 });
-await broker.start(artifactBytes);
+await broker.start(half.bytes);
 ```
 
-The Studio embed defaults `clientTickIntervalMs` to `1000` when you do not
-pass one; a raw `PlayerCodeBroker` does not.
-
 Most games embed the ready-made shell rather than hand-rolling window chrome
 around `mountCrowdyStudio`:
 
@@ -859,7 +794,7 @@ import { createCrowdyStudioEmbed } from '@crowdedkingdoms/crowdyjs/crowdy-studio
 import workerUrl from '@crowdedkingdoms/crowdyjs/player-glue-worker?worker&url';
 
 const studio = createCrowdyStudioEmbed({
-  client: game, // CrowdyClient: crowdyStudio, exec, playerCompute, playerWallet, crowdyStudioGitHub
+  client: game, // CrowdyClient: crowdyStudio, exec, playerWallet, crowdyStudioGitHub
   appId,
   gameName: 'My Game',
   suppressGameplayInput: () => pauseInput(),
@@ -882,29 +817,27 @@ fullscreen modal on narrow screens. For custom chrome, call
 `new CrowdyStudioController(options)`. New games should start SERVER-only.
 Untrusted HUD payloads always render as text, never HTML.
 
-**The SERVER target runs as a ck-exec mod.** The embed's `serverEngine` defaults to
-`'ck-exec'` when the client has `exec` (a `CrowdyClient` always does): a new project's
-SERVER target starts from the platform's mod starter (`client.exec.modStarter(appId)`, a
-`ckx-sdk` crate), Test draft and Deploy live build it with `modBuild` and deploy it to the
-grid as the mod `mod:<server module name>`, Invoke calls one of its endpoints (`state` by
-default) over an exec connection, and Logs shows its `ctx.log` lines.
+**The SERVER target runs as a ck-exec mod.** A new project's SERVER target starts from
+the platform's mod starter (`client.exec.modStarter(appId)`, a `ckx-sdk` crate), Test draft
+and Deploy live build it with `modBuild` and deploy it to the grid as the mod
+`mod:<server module name>`, Invoke calls one of its endpoints (`state` by default) over an
+exec connection, and Logs shows its `ctx.log` lines.
 
 **The CLIENT target is that mod's CLIENT half** (17.14.0). A new CLIENT target starts from a
 `crowdy-client-sdk` crate; Test draft and Deploy live build it with `modClientBuild`, attach
 it to the project's mod with `modClientDeploy`, consent to it as its author (the API serves a
 CLIENT half only to players who consented, its author too) and preview the served module in
-the HUD layer. A CLIENT-only project's CLIENT half rides the mod named for its CLIENT module:
+the HUD layer; the preview's `crowdy::log` lines show in Logs beside the mod's own. A
+CLIENT-only project's CLIENT half rides the mod named for its CLIENT module:
 when the player has no mod of that name on the grid, Studio deploys the mod starter's server
 half under it first and says so in the build log, and Stop switches that mod off. The
-preview loads only while the player stands in the grid with `run_client_code`. A CLIENT crate
-still on the legacy `crowdy-compute-sdk` is refused with what to change.
-
-`mountCrowdyStudio` and the controller take the same `serverEngine` with
-`mods: client.exec`; without `mods` they stay on legacy player compute, and
-`serverEngine: 'player-compute'` keeps it explicitly for both targets. The platform is
-switching legacy player compute off, so that option lasts only until 18.0 removes it.
+preview loads only while the player stands in the grid with `run_client_code`, and saving a
+CLIENT project needs ck-api `v2.25.1` or later. A CLIENT crate still on the legacy
+`crowdy-compute-sdk` is refused with what to change. The embed takes `exec` from the client;
+`mountCrowdyStudio` and the controller take `mods: client.exec`. Crowdy Studio runs nothing
+on legacy player compute since 18.0.0.
 
-See [Crowdy Studio & player client mods](https://docs.crowdedkingdoms.com/crowdyjs/player-client-mods)
+See [CLIENT halves](https://docs.dev.crowdedkingdoms.com/exec/client-halves), [mods](https://docs.dev.crowdedkingdoms.com/exec/mods)
 and [Embed Crowdy Studio in your game](https://docs.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
 
 ### The Studio agent (DeepSeek Harness in the browser)