@crowdedkingdoms/crowdyjs 18.13.2 → 18.14.0-dev.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 dev` 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 'dev'
  */
 /** The tier this build of the SDK is published for. */
-export declare const CROWDY_DEFAULT_TIER = "prod";
+export declare const CROWDY_DEFAULT_TIER = "dev";
 /** 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.dev.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.dev.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.dev.crowdedkingdoms.com";
 //# sourceMappingURL=default-origin.d.ts.map

package/dist/default-origin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default-origin.d.ts","sourceRoot":"","sources":["../src/default-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,wCAAwC,CAAC;AAEhF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,sCAAsC,CAAC;AAE5E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,gCAAgC,CAAC"}
+{"version":3,"file":"default-origin.d.ts","sourceRoot":"","sources":["../src/default-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,uCAAuC,CAAC;AAE/E,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,qCAAqC,CAAC;AAE3E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,+BAA+B,CAAC"}

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 dev` 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 'dev'
  */
 /** The tier this build of the SDK is published for. */
-export const CROWDY_DEFAULT_TIER = 'prod';
+export const CROWDY_DEFAULT_TIER = 'dev';
 /** 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.dev.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.dev.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.dev.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

@@ -1663,7 +1663,7 @@ export declare enum CheckoutPurpose {
     PropertyTokens = "PROPERTY_TOKENS",
     /**
      * @deprecated Legacy recurring subscription for a paid shared app slot. No longer purchasable via createCheckout; retained for historical checkouts and webhook reconciliation.
-     * @deprecated Shared apps use org wallet hourly usage billing. Publish via publishAppToShared and top up with ORG_WALLET_TOPUP.
+     * @deprecated Shared apps are billed for metered usage from the org wallet. Publish via publishAppToShared and top up with ORG_WALLET_TOPUP.
      */
     SharedAppSubscription = "SHARED_APP_SUBSCRIPTION"
 }
@@ -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;
@@ -4784,7 +4784,7 @@ export type Mutation = {
     mintAppToken: AppTokenResponse;
     /** Mint a grid-scoped token from the app token you hold (DN-10). The result can call only a short, fixed list of gameplay fields, and each is confined to the grid: world reads and replication sends must address a chunk inside it (a send's origin; its reach follows distance), and channels must be the grid's own. refreshAppToken and logout are refused, so the token cannot widen or tear down its parent. Requires an app token (not a session token, not another grid token), and the caller must own the grid or hold run_client_code on it. */
     mintGridToken: GridTokenResponse;
-    /** Publishes an app to the shared game-api environment. Free under the org's app-slot quota (result.free = true); beyond the quota, publish still succeeds and hourly usage is debited from the org wallet. Requires the 'manage_apps' permission on the app's org. Blocked when SHARED_GAME_API_URL is not configured. */
+    /** Publishes an app to the shared game-api environment. Free under the org's app-slot quota (result.free = true); beyond the quota, publish still succeeds and metered usage is charged to the org wallet. Requires the 'manage_apps' permission on the app's org. Blocked when SHARED_GAME_API_URL is not configured. */
     publishAppToShared: PublishAppResult;
     /** Store acceptance of the current required legal documents (Game Terms, API Terms, SDK Developer Terms, Free Tier and Billing Basis, Overworld Privacy Policy) and the age-of-majority attestation. Both arguments must be true; a false value stores nothing and is refused with LEGAL_ACCEPTANCE_REQUIRED. Idempotent for a version already stored. Requires a session token. Gameplay tokens stay refused until this has succeeded for the current document set. */
     recordPlayerConsents: Scalars['Boolean']['output'];
@@ -4838,7 +4838,7 @@ export type Mutation = {
     revokeTierAccessRule: TierAccessRule;
     /** Reverts every voxel edit made by `userId` in `appId` between `from` and `to`, returning one RollbackVoxelEventResult per affected voxel (`applied` tells you whether each was actually changed). DEFAULTS to dryRun=true, which only PREVIEWS the planned reversions without writing; pass dryRun=false to actually apply them (DESTRUCTIVE — mutates world state). A reverted voxel’s edit-log row takes the earlier edit’s type, state and author and the ROLLBACK’s time as its createdAt, so a client reading edits `since` its last sync sees the revert. When the app’s wilderness is closed (`wildernessOpen` false), an applied rollback that would write any chunk of closed, unclaimed wilderness is refused (403) before it writes anything; a dry run is not. Requires a valid bearer token AND the `manage_apps` permission on the org that owns `appId` (super admins bypass). */
     rollbackVoxelUpdates: Array<RollbackVoxelEventResult>;
-    /** OPERATOR ONLY. Runs the shared-usage billing tick once. It still bills only the last CLOSED clock hour — it will not charge an open hour. Use this to prove a closed-hour debit without waiting for the ~60s cron. Backdating usage rows is a local-test fixture, not something this mutation does on a live tier. */
+    /** OPERATOR ONLY. Runs the shared-usage tick once instead of waiting for the ~60s cron: reserved-throughput billing, the itemised statement of the last closed clock hour, and the usage-gate evaluation of every shared app. Metered usage is priced and charged by the ledger's settlement, about once a minute, not by this tick. Backdating usage rows is a local-test fixture, not something this mutation does on a live tier. */
     runSharedUsageBillingTick: Scalars['Boolean']['output'];
     /** Send an actor (player/NPC) state update for spatial replication to nearby chunks. Requires a bearer game token; opens a UDP proxy session automatically if none exists. Returns Boolean! that is true only when the datagram was ACCEPTED FOR SENDING to the game server — it does NOT confirm the world applied the update. There is NO separate per-request success response: the game server fans the update out to every client in the target chunk INCLUDING the sender, so you observe your own applied update as an ActorUpdateNotification carrying the same sequenceNumber (ActorUpdateResponse is legacy and is never emitted). Failures arrive ASYNCHRONOUSLY as a GenericErrorResponse; both are correlated by the request sequenceNumber (correlation only — not an idempotency key; the server does not dedupe replays). Subscribe to udpNotifications before sending so the self-notification/error is not missed. */
     sendActorUpdate: Scalars['Boolean']['output'];
@@ -4880,7 +4880,7 @@ export type Mutation = {
     setAppVisibility: App;
     /** Enables or disables off-session auto-billing for an org and updates its thresholds. When enabled and the wallet falls to lowWaterThresholdCents, the saved payment method is charged rechargeAmountCents (requires setupSharedPaymentMethod first). Pass limitCents=null for no per-period cap. Requires the 'manage_billing' org permission. */
     setAutoBilling: OrgAutoBilling;
-    /** OPERATOR ONLY. Sets a metered dimension's price, the UNIT that price is quoted in, its free allowances, or any combination, and returns the new row alongside the values that moved. THIS IS THE ONLY SANCTIONED WAY TO CHANGE A PRICE OR A UNIT: the schema seeds use ON CONFLICT DO NOTHING, so a rate reaches a tier once at install and a unit corrected in the declaration never reaches a tier that already exists. Refuses an unknown or unmetered metric (a rate for a dimension nothing meters bills nobody while appearing configured), refuses a negative price, refuses unitLabel without unitQuantity (which would restate the rate card while the arithmetic kept the old divisor), and refuses a call that would change nothing. A unit change that also moves the money needs acknowledgeRepricing: true, so restating a price and cutting it cannot be confused. priceBands sets a graduated schedule (SHARED aggregate_data_volume only; band 1 becomes priceCents) and clearPriceBands returns the dimension to one flat price; while a dimension is banded a bare priceCents or a unit change is refused. NOT RETROACTIVE: charges already written are history and the tick is idempotent per closed hour, so a new rate applies to hours billed from now on. Takes effect within about a minute — both billing ticks reload the card on every run, so no restart is needed. */
+    /** OPERATOR ONLY. Sets a metered dimension's price, the UNIT that price is quoted in, its free allowances, or any combination, and returns the new row alongside the values that moved. THIS IS THE ONLY SANCTIONED WAY TO CHANGE A PRICE OR A UNIT: the schema seeds use ON CONFLICT DO NOTHING, so a rate reaches a tier once at install and a unit corrected in the declaration never reaches a tier that already exists. Refuses an unknown or unmetered metric (a rate for a dimension nothing meters bills nobody while appearing configured), refuses a negative price, refuses unitLabel without unitQuantity (which would restate the rate card while the arithmetic kept the old divisor), and refuses a call that would change nothing. A unit change that also moves the money needs acknowledgeRepricing: true, so restating a price and cutting it cannot be confused. priceBands sets a graduated schedule (SHARED aggregate_data_volume only; band 1 becomes priceCents) and clearPriceBands returns the dimension to one flat price; while a dimension is banded a bare priceCents or a unit change is refused. NOT RETROACTIVE: the ledger keeps the rate and allowance in force when a (payer, dimension, period) is first charged, so a change applies from each dimension's next period and nothing already charged is repriced. Takes effect within about a minute — the settlement reloads the card on every run, so no restart is needed. */
     setBillingRate: SetRateCardResult;
     /** Replace a member's channel roles with the given set (not additive — roles not listed are removed). Requires the 'manage_roles' channel permission (app admins bypass). Re-pushes the member's effective send permission to Buddy so their ability to post updates immediately. */
     setChannelMemberRoles: GroupMember;
@@ -6444,7 +6444,7 @@ export type PlayerSpendCap = {
     /** The owning player user id. */
     userId: Scalars['BigInt']['output'];
 };
-/** One posted player usage charge: a (player, app, closed clock hour) row. amountCents = platformCents + markupCents — players see what the platform charges and what the studio adds (06 §4). The UNIQUE hour key makes the billing tick idempotent. */
+/** One player usage charge from the hourly cents-era billing: a (player, app, closed clock hour) row. The lossless ledger, on by default, replaced that billing and writes no rows here, so the list ends where the ledger took over; usage since is in playerWalletTransactions as "usage_debit" entries. amountCents = platformCents + markupCents: what the platform charged and what the studio added. */
 export type PlayerUsageCharge = {
     __typename?: 'PlayerUsageCharge';
     /** Total debited cents. */
@@ -6491,7 +6491,7 @@ export type PlayerWallet = {
     /** Wallet id. */
     walletId: Scalars['BigInt']['output'];
 };
-/** One player-wallet ledger entry: top-ups, hourly usage debits, auto-recharges, refunds, and adjustments. Usage debits carry the app and reference the hour's charge row, whose snapshot splits platform vs studio-markup components. */
+/** One player-wallet ledger entry: top-ups, usage debits, auto-recharges, refunds, purchases, payouts and adjustments. A usage debit carries the app and charges what one dimension's running total for its period now costs beyond what was already charged, the app's markup included, so a period can bring several debits as its usage arrives; its description names the dimension and the period. */
 export type PlayerWalletTransaction = {
     __typename?: 'PlayerWalletTransaction';
     /**
@@ -6514,11 +6514,11 @@ export type PlayerWalletTransaction = {
     createdAt: Scalars['DateTime']['output'];
     /** Human description. */
     description: Maybe<Scalars['String']['output']>;
-    /** External reference (checkout/PaymentIntent id). */
+    /** External reference: the checkout or PaymentIntent id of a top-up, or for a usage debit the ledger charge it settles ("charge:<chargeId>:<n>", the n-th debit of that charge). */
     referenceId: Maybe<Scalars['String']['output']>;
     /** Transaction id. */
     transactionId: Scalars['BigInt']['output'];
-    /** What produced this entry. The complete set of values this API writes: "topup" (credit from a completed checkout, positive), "auto_recharge" (off-session automatic recharge, positive), "payout_credit" (marketplace seller payout, positive), "refund" (marketplace refund returned to the buyer, positive), "usage_debit" (hourly player-compute metered charge for one closed clock hour, negative), "purchase" (marketplace purchase, negative), "adjustment" (operator or dispute-clawback correction, signed). */
+    /** What produced this entry. The complete set of values this API writes: "topup" (credit from a completed checkout, positive), "auto_recharge" (off-session automatic recharge, positive), "payout_credit" (marketplace seller payout, positive), "refund" (marketplace refund returned to the buyer, positive), "usage_debit" (metered player usage in one app: the increase in what one dimension's period total costs since the last debit for it, markup included, negative), "purchase" (marketplace purchase, negative), "adjustment" (operator or dispute-clawback correction, signed). */
     transactionType: Scalars['String']['output'];
     /** The owning player user id. */
     userId: Scalars['BigInt']['output'];
@@ -6705,7 +6705,7 @@ export type Query = {
     billingCharges: Array<BillingCharge>;
     /** OPERATOR ONLY. Every organization currently marked billing_exempt. An exemption nobody can enumerate is an exemption that outlives its reason. */
     billingExemptOrgs: Array<BillingExemptOrgType>;
-    /** OPERATOR ONLY. The metered rate card for a scope: every priced dimension with its unit, price and hourly free allowance. SHARED is organization usage billed to the org wallet as "shared_usage"; PLAYER is player compute billed to the player wallet as "usage_debit". A dimension priced at 0 is metered but not charged. Read-only. Customers read the same rates through `meteredRateCard`, which is public and omits the operator note. */
+    /** OPERATOR ONLY. The metered rate card for a scope: every priced dimension with its unit, price, free allowance and the period that allowance resets on. SHARED is organization usage charged to the org wallet as "shared_usage"; PLAYER is a player's own metered usage charged to the player wallet as "usage_debit". A dimension priced at 0 is metered but not charged. Read-only. Customers read the same rates through `meteredRateCard`, which is public and omits the operator note. */
     billingRateCard: Array<RateCardEntryType>;
     /** Amounts the platform could not bill this org for, with the reason (an exempt org, a provider with no generation record, a process that died with metered usage in memory). Requires 'view_billing' on the org. */
     billingWriteOffs: Array<BillingWriteOff>;
@@ -6943,11 +6943,14 @@ export type Query = {
     playerRuntimeStates: Array<PlayerRuntimeState>;
     /** The caller's self-set spend caps (global and per-app) with running counters. The effective runtime limit is min(developer policy, self-cap, wallet balance). */
     playerSpendCaps: Array<PlayerSpendCap>;
-    /** The caller's posted hourly player-usage charges, newest first, optionally filtered by app. Each charge splits platformCents (base rate card) from markupCents (the studio's configured markup) with a per-metric snapshot — players always see what the platform charges and what the studio adds. */
+    /**
+     * The caller's hourly player-usage charges from the cents-era billing, newest first, optionally filtered by app. Nothing has been added since the lossless ledger took over; current usage charges are the "usage_debit" entries in playerWalletTransactions.
+     * @deprecated Reads the hourly cents-era charge rows, which the lossless ledger does not write. Read playerWalletTransactions: each "usage_debit" entry is one charge, per app, markup included.
+     */
     playerUsageCharges: Array<PlayerUsageCharge>;
     /** The caller's player wallet, created empty on first access (never null). Platform-scoped: one wallet, across every org and app, pays for the player's mods past their monthly trial and any Agentic Studio model requests charged to them; org billing never touches it. Fund it via createCheckout purpose PLAYER_WALLET_TOPUP. */
     playerWalletBalance: PlayerWallet;
-    /** The caller's player-wallet ledger, newest first: top-ups, hourly usage debits (per app), auto-recharges, refunds, and adjustments. Usage-debit hours are broken down by playerUsageCharges, whose snapshot splits the platform and studio-markup components. */
+    /** The caller's player-wallet ledger, newest first: top-ups, usage debits (per app, the app's markup included), auto-recharges, refunds, purchases, payouts and adjustments. Each usage debit names its dimension and period, and an over-charge credited back appears as an adjustment. */
     playerWalletTransactions: Array<PlayerWalletTransaction>;
     /** Whether portaling the calling user into an app needs a consent prompt. Trusted (first-party) apps and already-granted apps return consentRequired=false. The Overworld calls this before createPortalAuthorizationCode. Requires a SESSION token. */
     portalConsent: PortalConsentState;
@@ -7620,7 +7623,7 @@ export type RateCardBandType = {
     /** Exclusive upper edge of this band on the period's running total, in raw metric units, as a BigInt decimal string. A band covers units from the previous band's edge up to this one. Null on the last band, which has no upper edge. */
     upToUnits: Maybe<Scalars['BigInt']['output']>;
 };
-/** One priced dimension: its rate and, where it has one, its hourly free allowance. A dimension with a price of 0 is metered but not charged. */
+/** One priced dimension: its rate and, where it has one, its free allowance and the period that allowance resets on. A dimension with a price of 0 is metered but not charged. */
 export type RateCardEntryType = {
     __typename?: 'RateCardEntryType';
     /** ISO currency code. USD today. */
@@ -7660,7 +7663,7 @@ export type RateChangeType = {
     /** The value after this call, as a decimal string. */
     updated: Scalars['String']['output'];
 };
-/** Which rate card. SHARED prices organization metered usage for shared-environment apps (billed hourly to the org wallet as "shared_usage"). PLAYER prices player compute (billed hourly to the player wallet as "usage_debit"). */
+/** Which rate card. SHARED prices an organization's metered usage in shared-environment apps, charged to the org wallet as "shared_usage" entries. PLAYER prices a player's own metered usage (mod compute, egress, model storage and player-paid model tokens), charged to the player wallet as "usage_debit" entries with the app's markup added. Both settle about once a minute: each (payer, dimension, period) is charged what its running total now costs beyond what was already charged for it. */
 export declare enum RateScope {
     Player = "PLAYER",
     Shared = "SHARED"
@@ -8261,13 +8264,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'];
@@ -9182,7 +9185,7 @@ export type WalletTransaction = {
     referenceId: Maybe<Scalars['String']['output']>;
     /** Unique transaction id (BigInt as a decimal string). */
     transactionId: Scalars['BigInt']['output'];
-    /** What produced this transaction. The complete set of values this API writes: "topup" (wallet credit from a completed checkout, positive), "admin_credit" (operator credit applied without a payment provider, positive), "auto_recharge" (off-session automatic wallet recharge, positive), "shared_usage" (hourly shared-environment metered charge for one closed clock hour, negative), "agent_usage" (Crowdy Studio agent run charged at provider cost, negative), "reserved_throughput" (monthly or prorated reserved capacity -- realtime bytes/s or GraphQL operations/s -- charged in addition to metered usage rather than including any of it, negative), "markup_payout" (the app developer's markup on a player's compute bill, credited to the org in the same transaction as the player debit that produced it, positive), "refund" (a payment-provider refund of a top-up, the credited amount leaving the wallet again, negative), "chargeback" (a card dispute on an org top-up, clawed back from the org wallet, negative). No other value is written; earlier versions of this description also listed "usage" and "environment_usage", neither of which was ever produced. */
+    /** What produced this transaction. The complete set of values this API writes: "topup" (wallet credit from a completed checkout, positive), "admin_credit" (operator credit applied without a payment provider, positive), "auto_recharge" (off-session automatic wallet recharge, positive), "shared_usage" (metered shared-environment usage: the increase in what one dimension's period total costs since the last charge for it, negative), "agent_usage" (Crowdy Studio agent run charged at provider cost, negative), "reserved_throughput" (monthly or prorated reserved capacity -- realtime bytes/s or GraphQL operations/s -- charged in addition to metered usage rather than including any of it, negative), "markup_payout" (the app developer's markup on a player's metered usage, credited to the org in the same transaction as the player debit that produced it, positive), "refund" (a payment-provider refund of a top-up, the credited amount leaving the wallet again, negative), "chargeback" (a card dispute on an org top-up, clawed back from the org wallet, negative). No other value is written; earlier versions of this description also listed "usage" and "environment_usage", neither of which was ever produced. */
     transactionType: Scalars['String']['output'];
     /** Wallet this transaction belongs to (BigInt as a decimal string). */
     walletId: Scalars['BigInt']['output'];