@crowdedkingdoms/crowdyjs 17.13.0-dev.1 → 18.0.0-dev.1

package/MIGRATION.md

@@ -1,3 +1,164 @@
+# 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.
+
+**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.
+
+`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:**
+the build and listing documents now select `ExecBuild.kind`, the artifacts' capability fields
+and the listings' `client*` fields, which an older API refuses as a validation error. Deploy
+the API first.
+
+A mod can carry a **CLIENT half**: browser WASM from one `crowdy-client-sdk` crate, built on
+the platform, attached to the mod and served by its grid to visitors who consent to it or
+trust its author. It replaces the legacy grid-attached client mods, which keep working until
+18.0.
+
+- **`client.exec`**: `modClientBuild(appId, crate)` (a build of `kind` `client`; poll it with
+  `modBuildStatus` / `waitForModBuild`), `modClientDeploy(appId, gridId, name, buildId)` →
+  `ExecModClient`, `modClientDelete(appId, gridId, name)`, `gridClientMods(appId, gridId)` →
+  `ExecGridClientMod[]` (with `capabilitySummary` and `authorCapabilitySummary` parsed beside
+  the JSON), `consentClientMod(appId, modId, capabilityHash)`, `trustAuthor(appId, gridId,
+  authorId, capabilityHash)`, `modClientArtifact(appId, modId)` and
+  `modClientArtifactBytes(appId, modId)`, which decodes the module, recomputes its SHA-256 and
+  refuses bytes that differ from `digest` (or a CLIENT ABI other than
+  `EXEC_CLIENT_ABI_VERSION`, 0, or a capability summary that does not parse) with a
+  `CrowdyProtocolError`. Errors are the API's: a stale
+  hash is `CONFLICT`, every artifact refusal `NOT_FOUND`, more than 12 fetches a minute per
+  player and mod `RATE_LIMITED`.
+- **Types**: `ExecBuild.kind`; `ExecBuildArtifact` (`capabilitySummaryJson`,
+  `capabilitySummary`, `capabilityHash`, `tickIntervalMs`, null for a ck-exec module);
+  `ExecModListing.clientDigest`, `clientCapabilitySummaryJson`, `clientCapabilitySummary`,
+  `clientCapabilityHash`, `clientTickIntervalMs`; `ExecClientCapabilitySummary`,
+  `ExecModClient`, `ExecGridClientMod`, `ExecModClientArtifact`, `ExecModClientArtifactBytes`.
+- **`ExecClientHalves`**, the exec twin of the-construct's `runConsentedGridMod` and
+  `ClientModLifecycle`: tell it the grid (`enterGrid`) and `refresh()` on a cadence. It lists
+  the grid's CLIENT halves, stops the ones removed or changed (keyed by `modId`, `digest`,
+  `capabilityHash` and tick interval), asks the player once per author (`trustAuthor`) or per
+  CLIENT half (`ask: 'mod'`, `consentClientMod`) through your `confirm`, fetches and caches by
+  digest, and runs each in a `PlayerCodeBroker` with its fuel budget and tick interval.
+  `NOT_FOUND` holds a CLIENT half back 15 s, `RATE_LIMITED` 60 s, refused bytes and a tripped
+  circuit 60 s.
+- **`PlayerCodeBroker({ engine: 'ck-exec' })`**: the allowlist is `EXEC_CLIENT_HOST_CALLS`,
+  exactly what crowdy-client-sdk calls (the client catalog less the Game Model group,
+  `sessions_list` and `grid_state_*`); the glue offers exactly `EXEC_CLIENT_ABI_IMPORTS`
+  (`ck::{log,now_ms,state_get,state_set,host_call}`, `wasi_snapshot_preview1::random_get`),
+  refuses a module without the `ck_fuel` meter, and the broker will not start without
+  `artifactHash`, `fuelPerDispatch` and `consentedHostCalls` (the served capability summary's
+  `hostFunctions`). A call outside that summary is refused too: the build derives the summary by
+  scanning the module for host-call names, so a name assembled at run time would otherwise reach
+  calls the player never consented to. The default, `'player-compute'`, is unchanged for legacy
+  CLIENT modules. `startGridMod`'s wasm spec takes `engine` and `consentedHostCalls` too.
+- **Crowdy Studio's CLIENT target runs on ck-exec** with `serverEngine: 'ck-exec'` (the
+  default when `exec` is present). A new CLIENT target starts from a `crowdy-client-sdk` crate
+  (`createCrowdyStudioStarterProject({ engine: 'ck-exec' })`); Test draft and Deploy live
+  build it with `modClientBuild`, attach it to the project's mod with `modClientDeploy`,
+  consent to it as its author and preview the served module with `engine: 'ck-exec'`. A
+  CLIENT-only project's CLIENT half rides the mod named for its CLIENT module (which must be a
+  mod name now): with no such mod of the player's on the grid, Studio deploys the mod starter's
+  server half under it first and says so in the build log, switches it on, and Stop switches
+  it off. The preview loads only for a player with `run_client_code` standing in the grid. On
+  ck-exec no target reads player compute usage, and the pairing select is disabled.
+- **`CrowdyStudioMods` gained `myMods`, `modClientBuild`, `modClientDeploy`,
+  `consentClientMod` and `modClientArtifactBytes`.** Pass `client.exec`; a hand-written
+  stand-in needs those too.
+- **Superseded** (`@deprecated`, removed in 18.0): `marketplace.gridClientMods`,
+  `consentGridClientMod`, `trustGridAuthor`, `clientArtifact`, `clientArtifactBytes`, and
+  `GridScope.compute.clientMods`.
+
+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, 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`).
@@ -37,7 +198,8 @@ Crowdy Studio's SERVER target moves to ck-exec mods, which 17.12.0 offered behin
   package named for the project, instead of the legacy `crowdy-compute-sdk` crate; the
   server module name fits a mod's (48 characters, starting with a letter) and a full-stack
   project records pairing `NONE`, since a mod has no client pairing. The CLIENT crate is
-  unchanged. `createCrowdyStudioStarterProject` takes the starter as `modStarter`.
+  unchanged (17.14.0 moved it to ck-exec). `createCrowdyStudioStarterProject` takes the
+  starter as `modStarter`.
 - **Invoke, Logs, Runs and the budget line follow the engine.** On ck-exec, Invoke calls the
   mod's endpoint (default `state`, JSON arguments sent as MessagePack) over one exec
   connection, and the result is the decoded reply as JSON; Logs are the mod's `ctx.log`

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
@@ -225,23 +225,19 @@ never told about, so a native refresh without it is a re-placement.
 | `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`). 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. |
+| `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,13 @@ 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`):
+There is no operator surface: `client.operator` held only the legacy compute ceilings and
+went with them in 18.0.0 (ck-exec code is bounded by its manifest limits within the
+platform's), 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 +479,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,9 +504,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.
+`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
 
@@ -571,8 +571,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
@@ -586,101 +586,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.
+`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 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);
+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));
 ```
 
-Land sale closes the permission loop end to end:
-
-```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
-```
-
-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)
 
@@ -735,6 +659,65 @@ Integers above 2^53 decode as `number` and lose precision unless you pass
 `{ decode: { useBigInt64: true } }`. The wire format is in the
 [ck-exec docs](https://docs.dev.crowdedkingdoms.com/exec/intro).
 
+### A mod's CLIENT half
+
+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`, 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.
+const queued = await client.exec.modClientBuild(appId, { name: 'hud', files }); // kind 'client'
+const built = await client.exec.waitForModBuild(appId, queued.buildId);
+const half = await client.exec.modClientDeploy(appId, gridId, 'shop', built.buildId);
+```
+
+A visitor's page lists what the grid serves (`gridClientMods`: each CLIENT half's capability
+summary and hash, its author's union and hash, and whether the player consented or trusts the
+author), asks the player, consents (`consentClientMod(appId, modId, capabilityHash)`, or
+`trustAuthor(appId, gridId, authorId, authorCapabilityHash)` once per author) and fetches the
+module (`modClientArtifactBytes(appId, modId)`: its bytes checked against `digest`, its fuel
+budget and tick interval). A stale hash is `CONFLICT`. The module is served only to a player
+holding `run_client_code` who stands in the grid now, every refusal is `NOT_FOUND`, and a
+player may fetch a mod's 12 times a minute, so cache it by `digest`. `ExecClientHalves` does
+all of that:
+
+```ts
+import { ExecClientHalves } from '@crowdedkingdoms/crowdyjs';
+
+const halves = new ExecClientHalves({
+  exec: client.exec,
+  appId,
+  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. 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
 
 Since 17.2.0 (ck-api v2.1) a developer can publish a built static bundle to the
@@ -773,28 +756,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`:
 
@@ -805,7 +792,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(),
@@ -828,18 +815,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 CLIENT target is
-unchanged. `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. The platform is switching legacy
-player compute off, so that option lasts only until it is removed.
-
-See [Crowdy Studio & player client mods](https://docs.crowdedkingdoms.com/crowdyjs/player-client-mods)
+**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; 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`, 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 [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)