@crowdedkingdoms/crowdyjs 18.13.2 → 18.14.0-test.1

package/MIGRATION.md

@@ -120,6 +120,18 @@ super-admin's session). There is no SDK replacement.
 `dev`'s SDL after #417 merged (`npm run schema:sync:paths -- --schema <that schema.gql>`, then
 `npm run codegen`).
 
+## 18.14.0: billing descriptions, and `playerWallet.charges()` deprecated
+
+No breaking change. The schema is cks-game-api `dev`'s after #550: the billing descriptions say
+what the lossless ledger does (settled about once a minute, per dimension and period, with no
+clock-hour close), and the voxel comments say what `getChunk` returns (an edit is in the
+chunk's `voxelStates`; only `updateChunk` writes the packed grid).
+
+`playerWallet.charges()` is **deprecated**, like the `playerUsageCharges` field it wraps: that
+field reads the cents-era hourly charge rows, which the ledger does not write, so the list ends
+where the ledger took over. Read `playerWallet.transactions()`: each `usage_debit` entry is one
+usage charge, per app, with the app's markup included. Nothing is removed in 18.x.
+
 ## 18.13.0: the economy
 
 Additive. **Needs a compute toolchain whose starter pack has the `player` and `market`

package/README.md

@@ -12,19 +12,23 @@ gameplay, minted per app through `client.portal`.
 
 Start here:
 
-- [SDK guide](https://docs.crowdedkingdoms.com/crowdyjs/readme) — the canonical
+- [SDK guide](https://docs.dev.crowdedkingdoms.com/crowdyjs/readme) — the canonical
   walkthrough of everything in this README.
-- [Build a game](https://docs.crowdedkingdoms.com/build-a-game/intro) — a
+- [Build a game](https://docs.dev.crowdedkingdoms.com/build-a-game/intro) — a
   hands-on tutorial from sign-in to a playable voxel game.
-- [Platform overview](https://docs.crowdedkingdoms.com/overview/client-workflow)
+- [Platform overview](https://docs.dev.crowdedkingdoms.com/overview/client-workflow)
   — how a client session flows through the platform.
 
 ## Install
 
 ```bash
-npm install @crowdedkingdoms/crowdyjs
+npm install @crowdedkingdoms/crowdyjs@dev
 ```
 
+This README is the `dev` branch's: it documents the release on the `dev` dist-tag
+(`npm view @crowdedkingdoms/crowdyjs dist-tags`), and its links go to the dev docs site. A
+plain `npm install` resolves `latest`, the production release, which has no `client.exec`.
+
 **Server compatibility.** A release selects fields the Game API it was built against has,
 so it needs that Game API or newer; promote the Game API before the SDK on each tier.
 
@@ -195,8 +199,8 @@ Notes:
 - Use `client.auth.setToken(token)` to seed a token externally (e.g. when
   restoring auth from a non-default storage).
 
-Deeper reading: [Portals & app-scoped tokens](https://docs.crowdedkingdoms.com/management-api/portals-and-app-tokens)
-and [Sign in](https://docs.crowdedkingdoms.com/management-api/authentication).
+Deeper reading: [Portals & app-scoped tokens](https://docs.dev.crowdedkingdoms.com/management-api/portals-and-app-tokens)
+and [Sign in](https://docs.dev.crowdedkingdoms.com/management-api/authentication).
 
 ### Token refresh during gameplay
 
@@ -320,7 +324,7 @@ query AppForRouting($appId: BigInt!) {
 `CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) holding
 that app's app-scoped token, then drive gameplay through that client. Apps
 with no `gameApiUrl` keep working against the default `httpUrl` you
-configured. See [Loading an app's Game API](https://docs.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
+configured. See [Loading an app's Game API](https://docs.dev.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
 
 ## Realtime notifications
 
@@ -731,7 +735,7 @@ reach your bundle. Reads are synchronous snapshots and writes happen on
 WebSocket events (not `requestAnimationFrame`), so render loops read freely
 and a backgrounded tab keeps ingesting updates; pass `workerTicker()` to also
 keep timer-driven sends at full rate while hidden. See the
-[World Stores guide](https://docs.crowdedkingdoms.com/crowdyjs/stores).
+[World Stores guide](https://docs.dev.crowdedkingdoms.com/crowdyjs/stores).
 
 ## Game Kit
 
@@ -809,7 +813,7 @@ The protocol is held to ck-exec's golden record of the starters
 (`test/unit/fixtures/kit-protocol.json`): every module call and topic in it is replayed in
 `test/unit/game-kit.test.mjs`. The blueprints, `kit.deploy`, the engines and the model-backed
 helpers went with the game model in 18.0.0; the hub modules replace them. See the
-[Game Kit docs](https://docs.crowdedkingdoms.com/game-kit/intro) and
+[Game Kit docs](https://docs.dev.crowdedkingdoms.com/game-kit/intro) and
 [MIGRATION.md](MIGRATION.md).
 
 ## ck-exec
@@ -873,7 +877,7 @@ Integers above 2^53 decode as `number` and lose precision unless you pass
 `{ decode: { useBigInt64: true } }`. A call's whole numbers outside 32 bits (a timestamp in
 milliseconds, a player id) go out as 64-bit integers (18.11.0; before, as floats, which a
 hub's integer fields refuse). The wire format is in the
-[ck-exec docs](https://docs.crowdedkingdoms.com/exec/intro).
+[ck-exec docs](https://docs.dev.crowdedkingdoms.com/exec/intro).
 
 ### A mod's CLIENT half
 
@@ -944,7 +948,7 @@ counts what was dropped); `invoke` sends at most 256 KiB each way and is refused
 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.crowdedkingdoms.com/exec/client-halves).
+[CLIENT halves](https://docs.dev.crowdedkingdoms.com/exec/client-halves).
 
 ## Hosting a game on Crowdy Games
 
@@ -1063,8 +1067,8 @@ CLIENT project needs ck-api `v2.25.1` or later. A CLIENT crate still on the lega
 `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.crowdedkingdoms.com/exec/client-halves), [mods](https://docs.crowdedkingdoms.com/exec/mods)
-and [Embed Crowdy Studio in your game](https://docs.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
+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.dev.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
 
 ### The Studio agent (DeepSeek Harness in the browser)
 
@@ -1253,7 +1257,7 @@ no other repositories and no network access required:
   `src/generated/graphql-schema.ts`, the generated schema types.
 
 Schema refresh is explicit, from the published
-[SDL](https://docs.crowdedkingdoms.com/schema/game-api.graphql):
+[SDL](https://docs.dev.crowdedkingdoms.com/schema/game-api.graphql):
 
 ```bash
 npm run schema:sync:prod

package/dist/default-origin.d.ts

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier prod` writes this file, and
+ * `sync-client-origins.mjs --write --tier test` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,14 +10,14 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'prod'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'test'
  */
 /** The tier this build of the SDK is published for. */
-export declare const CROWDY_DEFAULT_TIER = "prod";
+export declare const CROWDY_DEFAULT_TIER = "test";
 /** The public CK API origin for that tier. */
-export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.test.crowdedkingdoms.com";
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.test.crowdedkingdoms.com";
 /** The bare hostname, for callers that need to compare rather than dial. */
-export declare const CROWDY_DEFAULT_HOST = "ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HOST = "ck.test.crowdedkingdoms.com";
 //# sourceMappingURL=default-origin.d.ts.map

package/dist/default-origin.js

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier prod` writes this file, and
+ * `sync-client-origins.mjs --write --tier test` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,13 +10,13 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'prod'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'test'
  */
 /** The tier this build of the SDK is published for. */
-export const CROWDY_DEFAULT_TIER = 'prod';
+export const CROWDY_DEFAULT_TIER = 'test';
 /** The public CK API origin for that tier. */
-export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.test.crowdedkingdoms.com';
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.test.crowdedkingdoms.com';
 /** The bare hostname, for callers that need to compare rather than dial. */
-export const CROWDY_DEFAULT_HOST = 'ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HOST = 'ck.test.crowdedkingdoms.com';

package/dist/domains/playerWallet.d.ts

@@ -23,11 +23,17 @@ export declare class PlayerWalletAPI {
      * worst case while it runs). `balanceCents` is the deprecated truncation.
      */
     balance(): Promise<PlayerWalletBalanceQuery["playerWalletBalance"]>;
-    /** The caller's wallet ledger, newest first. */
+    /**
+     * The caller's wallet ledger, newest first. Usage charges are its `usage_debit` entries: one
+     * per app, dimension and period each time that period's usage costs more, the app's markup
+     * included.
+     */
     transactions(variables?: PlayerWalletTransactionsQueryVariables): Promise<PlayerWalletTransactionsQuery["playerWalletTransactions"]>;
     /**
-     * The caller's posted hourly usage charges; each splits platformCents vs
-     * markupCents with a per-metric snapshot ("what is this grid costing me").
+     * The caller's hourly usage charges from the cents-era billing, which the lossless ledger
+     * replaced: nothing is added to this list any more.
+     *
+     * @deprecated Read {@link transactions}: its `usage_debit` entries are the usage charges.
      */
     charges(variables?: PlayerUsageChargesQueryVariables): Promise<PlayerUsageChargesQuery["playerUsageCharges"]>;
     /** The caller's self-set spend caps with running counters. */

package/dist/domains/playerWallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playerWallet.d.ts","sourceRoot":"","sources":["../../src/domains/playerWallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EASL,KAAK,4BAA4B,EAOjC,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,sCAAsC,EAC3C,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EACrC,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,EACvC,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC1C,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,mCAAmC,EACxC,KAAK,4CAA4C,EAClD,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa;IAEnD;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;IAKzE,gDAAgD;IAC1C,YAAY,CAChB,SAAS,GAAE,sCAA2C,GACrD,OAAO,CAAC,6BAA6B,CAAC,0BAA0B,CAAC,CAAC;IAQrE;;;OAGG;IACG,OAAO,CACX,SAAS,GAAE,gCAAqC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAQzD,8DAA8D;IACxD,SAAS,IAAI,OAAO,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAKnE,0EAA0E;IACpE,WAAW,CACf,SAAS,EAAE,kCAAkC,GAC5C,OAAO,CAAC,yBAAyB,CAAC,mBAAmB,CAAC,CAAC;IAQ1D,2CAA2C;IACrC,WAAW,IAAI,OAAO,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IAKzE,6EAA6E;IACvE,cAAc,CAClB,SAAS,EAAE,qCAAqC,GAC/C,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;IAQhE;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAC7B,4BAA4B,CAAC,sBAAsB,CAAC,CACrD;IAKD,+DAA+D;IACzD,aAAa,IAAI,OAAO,CAC5B,wBAAwB,CAAC,qBAAqB,CAAC,CAChD;IAKD,8EAA8E;IACxE,UAAU,CACd,SAAS,EAAE,8BAA8B,GACxC,OAAO,CAAC,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;IAQrD,+EAA+E;IACzE,aAAa,CACjB,SAAS,EAAE,oCAAoC,GAC9C,OAAO,CAAC,2BAA2B,CAAC,qBAAqB,CAAC,CAAC;IAQ9D,uEAAuE;IACjE,cAAc,CAClB,SAAS,EAAE,4BAA4B,GACtC,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAKjD;;;OAGG;IACG,gBAAgB,CACpB,SAAS,EAAE,oCAAoC,GAC9C,OAAO,CAAC,2BAA2B,CAAC,wBAAwB,CAAC,CAAC;IAQjE,gFAAgF;IAC1E,wBAAwB,CAC5B,SAAS,EAAE,4CAA4C,GACtD,OAAO,CACR,mCAAmC,CAAC,gCAAgC,CAAC,CACtE;CAOF"}
+{"version":3,"file":"playerWallet.d.ts","sourceRoot":"","sources":["../../src/domains/playerWallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EASL,KAAK,4BAA4B,EAOjC,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,sCAAsC,EAC3C,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EACrC,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,EACvC,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC1C,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,oCAAoC,EACzC,KAAK,mCAAmC,EACxC,KAAK,4CAA4C,EAClD,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa;IAEnD;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;IAKzE;;;;OAIG;IACG,YAAY,CAChB,SAAS,GAAE,sCAA2C,GACrD,OAAO,CAAC,6BAA6B,CAAC,0BAA0B,CAAC,CAAC;IAQrE;;;;;OAKG;IACG,OAAO,CACX,SAAS,GAAE,gCAAqC,GAC/C,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAQzD,8DAA8D;IACxD,SAAS,IAAI,OAAO,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAKnE,0EAA0E;IACpE,WAAW,CACf,SAAS,EAAE,kCAAkC,GAC5C,OAAO,CAAC,yBAAyB,CAAC,mBAAmB,CAAC,CAAC;IAQ1D,2CAA2C;IACrC,WAAW,IAAI,OAAO,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IAKzE,6EAA6E;IACvE,cAAc,CAClB,SAAS,EAAE,qCAAqC,GAC/C,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;IAQhE;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAC7B,4BAA4B,CAAC,sBAAsB,CAAC,CACrD;IAKD,+DAA+D;IACzD,aAAa,IAAI,OAAO,CAC5B,wBAAwB,CAAC,qBAAqB,CAAC,CAChD;IAKD,8EAA8E;IACxE,UAAU,CACd,SAAS,EAAE,8BAA8B,GACxC,OAAO,CAAC,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;IAQrD,+EAA+E;IACzE,aAAa,CACjB,SAAS,EAAE,oCAAoC,GAC9C,OAAO,CAAC,2BAA2B,CAAC,qBAAqB,CAAC,CAAC;IAQ9D,uEAAuE;IACjE,cAAc,CAClB,SAAS,EAAE,4BAA4B,GACtC,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAKjD;;;OAGG;IACG,gBAAgB,CACpB,SAAS,EAAE,oCAAoC,GAC9C,OAAO,CAAC,2BAA2B,CAAC,wBAAwB,CAAC,CAAC;IAQjE,gFAAgF;IAC1E,wBAAwB,CAC5B,SAAS,EAAE,4CAA4C,GACtD,OAAO,CACR,mCAAmC,CAAC,gCAAgC,CAAC,CACtE;CAOF"}

package/dist/domains/playerWallet.js

@@ -26,14 +26,20 @@ export class PlayerWalletAPI {
         const data = await this.graphql.request(PlayerWalletBalanceDocument, {});
         return data.playerWalletBalance;
     }
-    /** The caller's wallet ledger, newest first. */
+    /**
+     * The caller's wallet ledger, newest first. Usage charges are its `usage_debit` entries: one
+     * per app, dimension and period each time that period's usage costs more, the app's markup
+     * included.
+     */
     async transactions(variables = {}) {
         const data = await this.graphql.request(PlayerWalletTransactionsDocument, variables);
         return data.playerWalletTransactions;
     }
     /**
-     * The caller's posted hourly usage charges; each splits platformCents vs
-     * markupCents with a per-metric snapshot ("what is this grid costing me").
+     * The caller's hourly usage charges from the cents-era billing, which the lossless ledger
+     * replaced: nothing is added to this list any more.
+     *
+     * @deprecated Read {@link transactions}: its `usage_debit` entries are the usage charges.
      */
     async charges(variables = {}) {
         const data = await this.graphql.request(PlayerUsageChargesDocument, variables);

package/dist/domains/voxels.d.ts

@@ -7,8 +7,9 @@ import { type ListVoxelsQuery, type ListVoxelsQueryVariables, type ListVoxelUpda
  *
  * A "voxel edit" is one row of the `voxel_updates` log (a {@link Voxel}): the
  * app / chunk / local position that changed, the new voxel type, an optional
- * base64 state blob, and who/when. A background maintenance job later folds these
- * edits into the chunk's packed grid (see {@link ChunksAPI}). For high-frequency
+ * base64 state blob, and who/when. `getChunk` applies these edits to the chunk it
+ * returns, as entries of its `voxelStates`; the packed grid itself is written only
+ * by `updateChunk` (see {@link ChunksAPI}). For high-frequency
  * realtime edits prefer the UDP path (`client.udp.sendVoxelUpdate(...)`); use
  * this API for authoritative reads, audit history, and administrative rollback.
  *
@@ -60,10 +61,12 @@ export declare class VoxelsAPI {
     listByDistance(input: ListVoxelUpdatesByDistanceQueryVariables['input']): Promise<ListVoxelUpdatesByDistanceQuery['listVoxelUpdatesByDistance']>;
     /**
      * Record (upsert) a single voxel edit in the `voxel_updates` log for one chunk.
-     * **Writes world state**; a background job later folds the edit into the
-     * chunk's packed grid. Requires voxel-edit permission for the target region:
-     * active app access plus the `update_voxel_data` runtime permission (and, where
-     * grids cover the chunk, `update_voxel_data` on a covering grid).
+     * **Writes world state**; `getChunk` returns the edit in the chunk's
+     * `voxelStates` (the packed grid is written only by `updateChunk`). Requires
+     * voxel-edit permission for the target region: active app access, the
+     * `update_voxel_data` tier permission, and `update_voxel_data` on the most
+     * specific grid covering the chunk. A chunk no grid covers is refused, and so
+     * is one only the app's world grid covers while its wilderness is closed.
      *
      * @param input - {@link UpdateVoxelInput}: `appId`, chunk `coordinates`, the
      *   local voxel `location` and the `voxelType` to write (app-defined

package/dist/domains/voxels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voxels.d.ts","sourceRoot":"","sources":["../../src/domains/voxels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,+BAA+B,EACpC,KAAK,wCAAwC,EAE7C,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EAErC,KAAK,iCAAiC,EACtC,KAAK,0CAA0C,EAE/C,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC3C,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;OAUG;IACG,IAAI,CACR,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKzC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,KAAK,EAAE,wCAAwC,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,+BAA+B,CAAC,4BAA4B,CAAC,CAAC;IAKzE;;;;;;;;;;;;;OAaG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CACX,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAKzD;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,IAAI,EAAE,0CAA0C,GAC/C,OAAO,CAAC,iCAAiC,CAAC,8BAA8B,CAAC,CAAC;IAQ7E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CACZ,KAAK,EAAE,qCAAqC,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;CAIjE"}
+{"version":3,"file":"voxels.d.ts","sourceRoot":"","sources":["../../src/domains/voxels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAE7B,KAAK,+BAA+B,EACpC,KAAK,wCAAwC,EAE7C,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EAErC,KAAK,iCAAiC,EACtC,KAAK,0CAA0C,EAE/C,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC3C,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;OAUG;IACG,IAAI,CACR,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKzC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,KAAK,EAAE,wCAAwC,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,+BAA+B,CAAC,4BAA4B,CAAC,CAAC;IAKzE;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CACX,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAKzD;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,IAAI,EAAE,0CAA0C,GAC/C,OAAO,CAAC,iCAAiC,CAAC,8BAA8B,CAAC,CAAC;IAQ7E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CACZ,KAAK,EAAE,qCAAqC,CAAC,OAAO,CAAC,GACpD,OAAO,CAAC,4BAA4B,CAAC,sBAAsB,CAAC,CAAC;CAIjE"}

package/dist/domains/voxels.js

@@ -6,8 +6,9 @@ import { ListVoxelsDocument, ListVoxelUpdatesByDistanceDocument, UpdateVoxelDocu
  *
  * A "voxel edit" is one row of the `voxel_updates` log (a {@link Voxel}): the
  * app / chunk / local position that changed, the new voxel type, an optional
- * base64 state blob, and who/when. A background maintenance job later folds these
- * edits into the chunk's packed grid (see {@link ChunksAPI}). For high-frequency
+ * base64 state blob, and who/when. `getChunk` applies these edits to the chunk it
+ * returns, as entries of its `voxelStates`; the packed grid itself is written only
+ * by `updateChunk` (see {@link ChunksAPI}). For high-frequency
  * realtime edits prefer the UDP path (`client.udp.sendVoxelUpdate(...)`); use
  * this API for authoritative reads, audit history, and administrative rollback.
  *
@@ -66,10 +67,12 @@ export class VoxelsAPI {
     }
     /**
      * Record (upsert) a single voxel edit in the `voxel_updates` log for one chunk.
-     * **Writes world state**; a background job later folds the edit into the
-     * chunk's packed grid. Requires voxel-edit permission for the target region:
-     * active app access plus the `update_voxel_data` runtime permission (and, where
-     * grids cover the chunk, `update_voxel_data` on a covering grid).
+     * **Writes world state**; `getChunk` returns the edit in the chunk's
+     * `voxelStates` (the packed grid is written only by `updateChunk`). Requires
+     * voxel-edit permission for the target region: active app access, the
+     * `update_voxel_data` tier permission, and `update_voxel_data` on the most
+     * specific grid covering the chunk. A chunk no grid covers is refused, and so
+     * is one only the app's world grid covers while its wilderness is closed.
      *
      * @param input - {@link UpdateVoxelInput}: `appId`, chunk `coordinates`, the
      *   local voxel `location` and the `voxelType` to write (app-defined

package/dist/generated/graphql-schema.d.ts

@@ -4596,7 +4596,7 @@ export type Mutation = {
     confirmEmail: Scalars['Boolean']['output'];
     /** Open the UDP proxy session for this game token (idempotent: returns the existing status if one is already open). Binds a socket and selects the game server with the fewest clients on first open. Optional: send mutations and udpNotifications also create a session lazily when none exists. To force a fresh socket, call disconnectUdpProxy first. */
     connectUdpProxy: UdpProxyConnectionStatus;
-    /** Operator only. Credit the payer of an over-billed charge (an I3 finding: an allowance or rate was raised after the charge landed) the difference, and close the charge row. Idempotent per charge state. SIDE EFFECT: a wallet credit and a CREDIT event. */
+    /** Operator only. Close an over-billed charge (an I3 finding: its priced total fell below what was billed and written off). The billed part of the difference is credited to the payer (a wallet credit and a CREDIT event); a written-off part (an exempt org) was never paid, so no money moves and a WRITE_OFF event of the opposite sign (reason OVERBILL_REVERSAL) offsets it. creditedMicrousd is the wallet credit only. Idempotent per charge state. */
     cpBillingCreditOverbill: BillingCreditResult;
     /** Operator only (is_operator or is_super_admin). Publish or release an emergency kill for one app. This state is separate from the app's own kill and always takes precedence in Management's effective envelope; app users cannot clear it. SIDE EFFECTS: revision increment and a sanitized audit event. NOTHING IS PUSHED TO GAME API: preemption takes effect when its runtime next pulls this app's crowdy.studio-agent-policy/1 replica, which is within about a minute for an app already holding one and not at all for an app that does not until a permitted caller asks. Releasing the operator kill does not enable the app or clear its own kill. Stable errors: AGENT_POLICY_INVALID, AGENT_POLICY_REVISION_CONFLICT, IDEMPOTENCY_CONFLICT. */
     cpSetCrowdyStudioAgentAppKill: CrowdyStudioAgentPolicy;
@@ -8261,13 +8261,13 @@ export type SetRateCardInput = {
     acknowledgeRepricing?: InputMaybe<Scalars['Boolean']['input']>;
     /** true removes the dimension's bands so it is priced flat at priceCents (the former first band's price unless priceCents is also given). Not combinable with priceBands. */
     clearPriceBands?: InputMaybe<Scalars['Boolean']['input']>;
-    /** New hourly free allowance in raw metric units, as a BigInt decimal string. Must be >= 0. Omit to leave the allowance unchanged. */
+    /** New hourly free allowance in raw metric units, as a BigInt decimal string. Must be >= 0. Omit to leave the allowance unchanged. Like a price, it applies from a dimension's next period where a period has already been charged. */
     freePerHour?: InputMaybe<Scalars['BigInt']['input']>;
-    /** New monthly free allowance in raw metric units, as a BigInt decimal string. Must be >= 0. On the PLAYER card with metric player_wasm_compute_units this is the pooled monthly TRIAL BUDGET per (player, app) — the only sanctioned way to change it on a live tier. Omit to leave it unchanged. */
+    /** New monthly free allowance in raw metric units, as a BigInt decimal string. Must be >= 0. On the PLAYER card with metric player_wasm_compute_units this is the pooled monthly TRIAL BUDGET per (player, app) — the only sanctioned way to change it on a live tier. Omit to leave it unchanged. Like a price, it applies from a dimension's next period where a period has already been charged. */
     freePerMonth?: InputMaybe<Scalars['BigInt']['input']>;
     /** New period for the free allowance. Leaves the units as they are unless freeUnits is also given. Moving a dimension to MONTH is how the development quota is stated. */
     freePeriod?: InputMaybe<AllowancePeriod>;
-    /** New free allowance in raw metric units per freePeriod, as a BigInt decimal string. Must be >= 0. Leaves the period as it is unless freePeriod is also given. Not combinable with freePerHour, which is the older spelling of freeUnits with freePeriod HOUR. */
+    /** New free allowance in raw metric units per freePeriod, as a BigInt decimal string. Must be >= 0. Leaves the period as it is unless freePeriod is also given. Not combinable with freePerHour, which is the older spelling of freeUnits with freePeriod HOUR. Like a price, it applies from a dimension's next period where a period has already been charged. */
     freeUnits?: InputMaybe<Scalars['BigInt']['input']>;
     /** The metered dimension to reprice. Refused unless the platform actually meters it: a rate for an unmetered metric bills nobody while appearing configured. */
     metric: Scalars['String']['input'];