@typetorch/framework 0.3.2 → 0.3.5

package/README.md

@@ -57,16 +57,25 @@ swap. It needs the TypeTorch kernel in the place (`@typetorch/kernel`).
 
 ### Coming from Flamework
 
-Game code only changes imports: `@Service`, `@Controller`, constructor injection, the lifecycle interfaces and
-`createNetwork` are the same.
+Game code only changes imports: `@Service`, `@Controller`, constructor injection, `Dependency<T>()`, the lifecycle
+interfaces and `createNetwork` are the same.
 
 | Flamework | TypeTorch |
 |---|---|
 | `rbxts-transformer-flamework` plugin, `node_modules/@flamework` type root | `@typetorch/transformer` plugin, `node_modules/@typetorch` type root |
 | `import { Modding, Reflect } from "@flamework/core"` | `import { Modding, Reflect } from "@typetorch/framework"` |
+| `import { Dependency } from "@flamework/core"` | `import { Dependency } from "@typetorch/framework"` (from onInit/onStart on, not in constructors) |
+| `import type` + `Dependency<T>()` to break a cycle | the same, or `Lazy<T>` (below) |
+| `ClientEvents.x.predict(...)` | `network.client.x.emit(...)` |
+| `invokeWithTimeout(timeout, ...)` | `invokeWithTimeout(seconds, ...)` (seconds, 0.5 to 120) |
+| `Observers.observeCharacter` / `observeLocalCharacter` (@rbxts/observers) | still fine: put the stop function in the trove, `this.trove.add(observeCharacter(...))` |
 | `import { t } from "@rbxts/t"` (still fine) | also `import { t } from "@typetorch/framework"` |
 | `@metadata flamework:parameters` keys, `"flamework:parameters"` metadata | `@metadata typetorch:parameters`, `"typetorch:parameters"` |
 | `flamework.build`, `include/flamework`, the `@flamework` Rojo mapping | gone; delete them |
+| `Networking.createEvent` / `createFunction` and their call sites | `createFlameworkCompat` (below) keeps every call site; `createNetwork` is the native API |
+
+`typetorch migrate --from flamework` (CLI) does most of this, and the docs' `guides/from-flamework.md` has the whole
+mapping.
 
 ## Usage
 
@@ -99,6 +108,19 @@ export class CoinService extends Module implements OnStart {
 - **Modules:** `@Service()` (server) and `@Controller()` (client) classes extending `Module`. Constructor parameters
   are other modules, injected by type. Lifecycle: `OnInit` (sequential, dependencies first), `OnStart` (spawned),
   `OnStop` (reverse order), `OnTick`, `OnPhysics`, `OnRender`, `OnPlayerAdded` (replays players already in the server).
+- **Modules outside the constructor:** `Dependency<T>()` (or `TypeTorch.module<T>()`) returns the running module of
+  type T from anywhere: a method, a plain class a module built, a command handler. `TypeTorch.tryModule<T>()` returns
+  undefined instead of throwing. They work once every module is constructed (from onInit on); in a constructor, a
+  field initializer or module top-level code they throw `"ShopService isn't constructed yet: ..."`. Only this realm's
+  modules, and per generation: after a swap they return the new generation's instance. An `import type` of the class is
+  enough (no require cycle).
+- **Cycles:** two modules that need each other take one side as `Lazy<T>`, resolved on first use:
+  `constructor(private readonly team: Lazy<TeamService>)` (needs `@typetorch/transformer` 0.2.1+) or a field,
+  `private readonly team = Lazy<TeamService>()` (any transformer). `this.team.get()` works from onInit on (in a
+  constructor it throws), and the start order ignores lazy edges. A cycle error names the cycle and suggests this.
+- **Per-player state:** `this.ctx.playerState("cooldowns.v1", (player) => init)` (or `TypeTorch.playerState`) returns
+  `{ get, set, has, delete }` keyed by UserId. It survives swaps (persist), and a player's entry goes when they really
+  leave, never on a swap. The dev menu shows it under Modules > State > persist, `__playerState`.
 - **Bad deploys roll back (kernel 0.3.2):** a server `onStart` that throws is reported to the kernel, which rolls the
   server back to its last known good artifact when it happens within 30 s of start (so do 3 errors from the new
   code's scripts in that time). On a real shutdown every module's `onStop` runs too (the kernel's BindToClose).
@@ -106,6 +128,18 @@ export class CoinService extends Module implements OnStart {
   behind. `TypeTorch.persist(key, init)` (or `this.ctx.persist`) keeps plain data across swaps.
 - **Network:** `createNetwork<C2S, S2C>()` with nested namespaces. The server checks rate limits, shape limits and the
   generated type guard on every client message. `setNetworkLimits({ "chat.say": { maxString: 200 } })` tunes a leaf.
+  Requests wait 15 s for the answer: `invokeWithTimeout(5, ...args)` sets it per call, and a leaf's `timeout`
+  (`setNetworkLimits({ "vc.spawn": { timeout: 30 } })`, read by the client, so set it in shared code) per leaf; both in
+  seconds, 0.5 to 120. `network.client.x.emit(...args)` runs this client's own `on` handlers for a server -> client
+  leaf right away, with no traffic (Flamework's `predict`); `network.server.x.emit(player, ...args)` does the same on
+  the server, for tests. A request handler may return a Promise: the answer waits for it.
+- **Flamework networking names:** `createFlameworkCompat<C2SEvents, S2CEvents, C2SFunctions, S2CFunctions>()` returns
+  `{ ServerEvents, ClientEvents, ServerFunctions, ClientFunctions, GlobalEvents, GlobalFunctions }` with
+  `@flamework/networking` 1.x's methods (`connect` returning a connection, `fire(player | players)`, `broadcast`,
+  `except`, `predict`, `setCallback`, `invoke`, `invokeWithTimeout`, calling a leaf directly) on this same network:
+  same guards, limits and swap rules, so a Flamework game's call sites compile unchanged. Listeners run on their own
+  thread each, like Flamework's, and belong to the running generation (no trove needed). Not carried over: server ->
+  client requests, middleware, `Networking.Unreliable`. `typetorch build` notes a game still using it.
   Across a swap (0.3.0): what the server sends a player waits until that player's client runs the new generation
   (reliable messages are queued, unreliable ones dropped), and on kernel 0.3.2 a request the server can no longer
   answer fails at once ("The game is updating, try again.") instead of timing out.
@@ -120,6 +154,17 @@ export class CoinService extends Module implements OnStart {
   logs (server, own client, other players' clients), client and server dex, network stats, module state, a branch and
   build picker (Server > Branch) and a Claude prompt. Prod-channel servers are read-only. The window can be dragged by
   its header and resized from its corner (double-tap the header to reset).
+- **Panes and windows (dev menu):** every page shows in a pane with a small header: tap the title to pick another
+  page, or use Split right, Split down, Open in new window and Close. Drag the line between two panes to resize them.
+  The sidebar opens pages in the focused pane (the highlighted one; tap a pane to focus it). Floating windows move by
+  their title bar and resize from their corner (double-tap the title bar to maximise); their title bar also has
+  Minimise, Dock (back into the main panel) and Close. Windows can be split too. The layout, the windows and each
+  pane's own settings (for example the open nodes of two Modules > State panes) survive swaps; a fresh join starts
+  with one pane. Claude, Server > Branch and the Manage pages open once (picking them again focuses their pane); every
+  other page can be open several times. Panes nobody sees (menu closed, window minimised) stop refreshing, and panes
+  on the same data share one request (Status, Overview, Assets, Network > Stats, server Logs, Packets); State panes
+  share one query budget. On phones and small screens panes only stack (two at most), and windows open maximised with
+  one pane each.
 - **State explorer (Modules > State, Server | Client):** every live module of the running generation (services on the
   server, controllers on the client) and the persist store. Tap a row to open it: the module's own fields (not its
   methods), then tables, arrays, Maps and Sets, 100 entries per page (Prev / Next). Each value has a short preview:
@@ -171,6 +216,13 @@ this.trove.add(TypeTorch.onUpdatePending((update) => (hint.Visible = !update.can
 
 // State that survives swaps (plain data only)
 const scores = TypeTorch.persist("scores.v1", () => new Map<number, number>());
+// Per player, removed when the player really leaves (same as this.ctx.playerState)
+const cooldowns = TypeTorch.playerState("cooldowns.v1", () => ({ lastUse: 0 }));
+cooldowns.get(player).lastUse = os.clock();
+
+// The running module of a type (same as Dependency<T>()), from onInit/onStart on
+TypeTorch.module<ShopService>().open(player);
+TypeTorch.tryModule<ShopService>()?.open(player); // undefined instead of an error
 
 // Dev and roles (server: the kernel decides; client: only the local player, cosmetic)
 if (TypeTorch.isOwner(player)) showOwnerPanel(player);
@@ -187,6 +239,23 @@ TypeTorch.onLog((entry) => errors.push(entry)); // don't print from inside it
 
 // Hot assets (below): same as hotAsset(...)
 const shop = TypeTorch.asset("ui/shop");
+
+// Live values, server only (kernel 0.3.8): the signed settings record's `game` field (`typetorch settings set game.<key> <json>`).
+const price = TypeTorch.liveConfig("shop.price", { default: 50, parse: (raw) => (typeIs(raw, "number") ? raw : 50) });
+price.get();
+this.trove.add(price.onChanged((value) => this.reprice(value)));
+
+// Cross-server, server only. Kernel 0.3.8: game topics over ONE kernel-held MessagingService topic; listeners hear
+// prod servers and this branch by default (dev branches never reach prod); publish queues and retries, max 1 KiB.
+this.trove.add(TypeTorch.messaging.subscribe<Ban>("1guard", (ban, meta) => applyBan(ban, meta.jobId)));
+TypeTorch.messaging.publish("1guard", { kind: "ban", userId }, { to: "prod" });
+
+// The universe's live servers (the roll call; cached per server, yields up to ~3 s when stale) and this server's public fields
+TypeTorch.setServerInfo({ region: "eu", vc: true }); // JSON, at most 400 bytes, kept across swaps
+const list = TypeTorch.servers(); // [{ jobId, placeVersion, players, maxPlayers, serverType, branch, channel, uptime, here, info }]
+
+// A library call a swap must not cut off halfway (kernel 0.3.8): runs on a kernel thread; write what must survive into persist.
+TypeTorch.runDetached(() => store.StartSessionAsync(`Player_${userId}`)).then((profile) => attach(player, profile));
 ```
 
 - **`startInfo.reason`:** `boot`, `deploy`, `rollback`, `branch`, `pin`, `reload`, `server_rollback`,
@@ -203,6 +272,25 @@ const shop = TypeTorch.asset("ui/shop");
   reason and timings, the next artifact in `onSwapOut`, `onUpdatePending`, server-side `onPlayerDevChanged` and
   `requestReload`. On older kernels `startInfo` still knows boot vs swap, the previous artifact and branch (the
   framework records them), `onBranchChanged` still fires, and the reason of a swap is `unknown`.
+- **`messaging`** (kernel 0.3.8): `subscribe(topic, (data, meta) => ...)` returns a disconnect; `meta` = `{ channel,
+  branch, jobId, serverType, placeVersion, sentAt, self, replayed? }`; `{ from: "all" | "prod" | "branch" }` changes
+  who it hears. `publish(topic, data, { to })` throws on a bad topic, non-JSON data or a message over 1 KiB (with its
+  size), returns false when dropped at once (queue full). Studio loops back; the cloud test publishes nothing; older
+  kernels throw "needs kernel 0.3.8". `servers()` works on every kernel (0.3.8 holds the roll call topic, so a swap
+  doesn't subscribe again).
+- **`liveConfig(key, { default, parse? })`** (kernel 0.3.8, plans/20): reads `game[key]` of the signed settings record the
+  kernel verified (signed by both prod keys, so game code can't forge it); `get()` and `onChanged(fn)` (only on real
+  changes; generation-scoped). The default without a record or key, when `parse` throws (warned per value), and on older
+  kernels (warned once: "needs kernel 0.3.8"; no ConfigService fallback). `TypeTorch.settings()` is the whole copy
+  (`seq`, `at`, `game`, `analytics`, `fleet`, ...): server only, it holds tokens.
+- **`runDetached(fn)`** (kernel 0.3.8, server only): runs `fn` on a thread the kernel owns, so a deploy's hard stop
+  (which kills this generation's threads mid-call) can't cut it off: for ProfileStore / ProfileService loads, saves and
+  releases. Returns a Promise that settles while this generation runs; after a swap the result is dropped, so a job
+  whose result must survive writes it into `persist` itself. The job keeps this generation's closures alive until it
+  ends. Errors reject it and go to the kernel's log with the generation's name (never the health window); at most 256
+  run at once per server (then it throws); one past 60 s is logged and flagged in Server > Status. Older kernels
+  throw "needs kernel 0.3.8; use the DataHost job queue (Player data guide)": the other option, which works on every
+  kernel. `features.runDetached` tells which one this server has.
 - **Edit mode** (UI Labs stories, no kernel): `running` is false, identity has defaults, `persist` keeps a local table,
   events never fire, and the server-only reads throw.
 
@@ -216,6 +304,8 @@ pieces that keep it safe across swaps:
 - **Session handles live in `persist`**, keyed by `UserId`. `onPlayerAdded` replays everyone after a swap, so it
   re-attaches to the open session instead of loading again.
 - **Release only on `Players.PlayerRemoving`**, never in `onStop` or `onSwapOut`.
+- **Library calls can't be cut off by a swap:** run them as DataHost jobs (any kernel) or with
+  `TypeTorch.runDetached` (kernel 0.3.8).
 - **Split store names by channel** (`TypeTorch.channel === "prod" ? "PlayerData" : "PlayerData_dev"`).
 
 Full example with ProfileStore: [Player data guide](https://github.com/typetorch/docs/blob/main/guides/player-data.md).
@@ -276,7 +366,7 @@ self-hosted DuckDB analytics server). Nothing runs until an engine is created: n
 ```ts
 import { AnalyticsEngine } from "@typetorch/framework";
 
-// A server module (onInit): reads the ConfigService key TypeTorchAnalytics.
+// A server module (onInit): the sink comes from the signed settings' `analytics` (kernel 0.3.8).
 const analytics = new AnalyticsEngine();
 analytics.track(player, "quest_done", { quest: "tutorial" }); // custom
 analytics.step(player, "onboarding", 3, "opened_shop"); // funnels
@@ -297,20 +387,22 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   and the next generation sends them. In edit mode (UI Labs) it is inert.
 - **Server calls take the player first** (`track(player, ...)`); without one an event is server-only (no player id).
   Client calls are always about the local player and are marked `src = "client"` (a client can lie). The server
-  checks their shape, size (props at most 4 KB) and rate.
+  checks their shape, size (props at most 4 KB) and rate. `purchase` and `currency` are server-only (revenue and the
+  economy are server-authoritative): on the client they warn once and send nothing, and the server refuses them from
+  clients.
 - **Options** (all on by default): `sessions` (joins, leaves, device, join source, account age bucket, Premium,
   country, friends in the server, first-ever vs returning, days since the last visit), `tech` (FPS, ping, memory, load
   time, client and server errors, swaps and rollbacks, leaves within 60 s of a swap), `zones` (parts or models tagged
   `TTZone`, named by a `Name` attribute or the instance name), `screens` (ScreenGuis in PlayerGui, GuiObjects tagged
   `TTScreen`), `recording` (the first-ever session in detail), `fleet` (kernel 0.3.2 heartbeats and deploy reports),
   `identity` (one `{ pid, uid }` row per session to the dev's own server, below). `settings` (server only) replaces the
-  ConfigService key, for tests.
+  signed settings' `analytics`, for tests, Studio and kernels before 0.3.8.
 - **Every row** carries the time (server clock), a random player id (never the UserId), the session, the server
   (JobId, type, place), the artifact (id, seq, branch, channel), the device, new vs returning, the player's state
   (`zone:Lobby|screen:Shop|activity:round`) and experiment variants. The exact rows: `src/analytics/SCHEMA.md`.
 - **Experiments:** `experiment(...)` is deterministic per player and name (they keep their variant in every session),
   may yield briefly the first time (until the player's id loads), and stamps the variant on the player's later events.
-  The settings key turns one off (`active: false`: everyone gets the first variant), sets `weights` or forces a
+  The settings turn one off (`active: false`: everyone gets the first variant), sets `weights` or forces a
   `variant`, live.
 - **First-ever session:** for new players (a share of them, `recordShare`), the client records character and camera
   about 10 times a second, every input (never while a TextBox or the chat has focus; text boxes only say which box was
@@ -320,7 +412,7 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   row carries a UserId.
 - **Identities** (option `identity`, default on): once the pid is known, one row `{ pid, uid, t }` (the UserId, nothing
   else) per session goes to the dev's own server only, never into the events: duckdb games in the batch body, Basin
-  games to the fleet API (`TypeTorchFleet` url + `/v1/identity`, or the `identity` / `identityToken` settings). The
+  games to the fleet API (the settings' `fleet` url + `/v1/identity`, or the `identity` / `identityToken` settings). The
   analytics server keeps pid -> UserId in a deletable table (support lookups, Right to Erasure).
 - **Player ids:** DataStore `TypeTorchAnalytics`, key `p/<UserId>` -> `{ pid, first, last }`: one read per join, a
   write on the first join and at leave. Deleting the key (Right to Erasure) leaves that player's rows anonymous.
@@ -328,10 +420,21 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   `flushSeconds` (15) or at 500 rows, at most ~10 HttpService requests a minute, retries with backoff, and a last
   flush on shutdown (kernel 0.3.2). Delivery is at least once (a swap mid-request sends that batch again).
   `analytics.stats()` (server) has the counters; `flush()` sends soon.
-
-**Settings** (server only, never sent to clients): the ConfigService key `TypeTorchAnalytics`, written with
-`writeSettings()` from `@typetorch/analytics` (Open Cloud, universe:write) or in Creator Hub (Configs); no CLI command
-writes it. Re-read live every few minutes:
+- **The cloud test sends nothing.** `typetorch test --cloud` boots the payload headless in a Luau Execution task where
+  HttpService works; there the engine (stub kernel `test = true`, or `workspace:GetAttribute("TypeTorchTest")`) collects
+  as usual but never uploads: no event rows, no identity rows, no HTTP request, so a prod deploy never puts a fake
+  server session into your analytics.
+- **Bounds on what a client can cause:** at most 32 experiments per session (each is stamped on every later row), and
+  a client's `exp` messages count against its event budget (120 a minute, 5,000 a session). Clients can't send
+  `purchase` or `currency` rows; the analytics server's ingest also refuses client-marked ones (older engines) and its
+  revenue queries count `purchase` rows the server sent.
+- **Friends in the server** (the join's `friends`): one `Players:GetFriendsAsync` per join (at most 10 pages, none
+  when the player is alone) intersected with the players there, not a web call per player.
+
+**Settings** (server only, never sent to clients): the signed settings record's `analytics` field (kernel 0.3.8,
+plans/20), written with `typetorch settings set analytics -` (JSON on stdin; `@typetorch/analytics`' `writeSettings()`
+and `bun run local` call it). Every new copy applies live within seconds (the CLI pings servers). Before kernel 0.3.8
+there are no settings unless the game passes `new AnalyticsEngine({ settings })`:
 
 ```json
 { "backend": "basin", "events": "https://<stream-id>.ingest.cloudflare.com",
@@ -367,6 +470,16 @@ bun run build   # rbxtsc --type package -> out/
   `scripts/test-state-inspect.luau` checks the state explorer's core (previews, raw reads only, cycles, paging,
   Maps/Sets with Instance keys, the depth limit, filters, request validation) and that `src/version.ts` matches
   package.json.
+  `scripts/test-layout.luau` checks the dev menu's pane layout core (`devtools/layout.ts`: splits and their limits,
+  closing, pop out and dock, singleton pages, ratios, focus, and cleaning a remembered layout).
+  `scripts/test-modules.luau` runs the real `startServer`/`startClient` of `out/` (with RuntimeLib, Promise, trove and
+  t from node_modules) over several generations that share a persist store: `Dependency<T>()`, `TypeTorch.module` /
+  `tryModule` and their errors, `Lazy<T>` (parameters and fields, cycles, start order), network `emit` and request
+  timeouts and `playerState` (swaps, leaves).
+  `scripts/test-flamework-compat.luau` (same harness) drives `createFlameworkCompat` through each generation's
+  dispatcher: connect (one thread per call, guards, Disconnect, troves), fire / except / broadcast / the call
+  shorthand, setCallback with values and Promises, predict, a swap, and the client side (invoke, invokeWithTimeout,
+  `createClient({ defaultTimeout })`).
   `scripts/test-analytics.luau` checks the analytics engine's pure parts (experiment assignment, settings, the queue
   and HTTP budget, tt-rec-1, the sink request bodies); `test-analytics-server.luau` and `test-analytics-client.luau`
   run the compiled server and client cores against mocked services (sessions, intake, retries, a swap with a request

package/out/analytics/SCHEMA.md

@@ -31,7 +31,7 @@ Integers are written with every digit (never exponent notation).
 | `state` | string | The player's state **after** this event: `zone:<z>\|screen:<s>\|activity:<a>`, empty parts left out (`""` when nothing is known). Server-only events: `activity:<server activity>` or `""` |
 | `exp` | string | JSON object of the player's active experiments, `{"onboarding":"short"}`; `{}` when none |
 | `sexp` | string | The server's experiment: the artifact id of a kernel A/B experiment pin, or `""` |
-| `src` | string | `server`, or `client` (sent by a client: it can lie; the server checked shapes and rate) |
+| `src` | string | `server`, or `client` (sent by a client: it can lie; the server checked shapes and rate). Never `client` on `purchase` or `currency` rows |
 | `props` | string | JSON object text, at most 4096 bytes. Too large: `{"_trunc":<bytes>}`; not encodable: `{"_err":"encode"}`; a non-object value `x`: `{"value":x}` |
 
 ### recordings
@@ -57,7 +57,7 @@ First-ever-session detail, one row per packed chunk.
 
 | kind | name | props |
 |---|---|---|
-| session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `share` (launch data), `follow` (followed someone); `ctx?` (GameJoinContext.JoinSource name); `tp?` (had teleport data); `party?` (players teleported along); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `friends` (friends in the server, at most 30 checked); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join). `t` is the join time |
+| session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `share` (launch data), `follow` (followed someone); `ctx?` (GameJoinContext.JoinSource name); `tp?` (had teleport data); `party?` (players teleported along); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `friends` (how many of the player's friends are in the server: one friend-list lookup per join, at most 10 pages, `0` when it fails); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join). `t` is the join time |
 | session | `device` (src client) | `input` (`kbm`, `touch`, `gamepad`, `vr`, `unknown`), `w`, `h` (viewport points), `touch`, `kb`, `mouse`, `pad`, `vr`. Once per session |
 | session | `leave` | `secs` (session length), `why`: `left`, `shutdown`, `gone` (left while no generation ran the engine), `swap60?` (left within 60 s of a hot swap) |
 | tech | `server` | Every `techEvery` s: `fps` (physics), `hb` (Heartbeat rate), `mem` (MB, 10s), `players`, `ping50?`, `ping90?` (ms), `q`, `qr` (queued events, recordings), `dropped`, `sent`, `fails`, `health?`, `errors?` (kernel 0.3.2 health) |
@@ -71,17 +71,21 @@ First-ever-session detail, one row per packed chunk.
 | zone | `leave` | `zone`, `to?`, `secs` |
 | state | `activity` | `to`, `from` (server or client src) |
 | state | `screen` | `to`, `from` (`""` = none). Client: ScreenGuis in PlayerGui (Enabled), GuiObjects tagged `TTScreen` (Visible), `screen()` |
-| experiment | `<experiment>` | `variant`, `variants` (count), `forced?`. Once per session when assigned or changed |
+| experiment | `<experiment>` | `variant`, `variants` (count), `forced?`. Once per session when assigned or changed. At most 32 experiments per session: a 33rd `experiment()` returns the control (the first variant) and warns. A client's experiment calls count against its event budget (below) |
 | recording_meta | `start` | `share` (the recorded share then) |
 | recording_meta | `end` | `chunks`, `bytes`, `why`: `window` (60 s after the first input), `cap` (10 min, or the server's 256 KB / 80 chunks), `left`, `end` |
 | fleet | `heartbeat` | The kernel's `fleetStatus()` (kernel 0.3.2+), every 60 ± 10 s and once at each generation start. pid `""` |
 | fleet | `deploy_report` | One kernel deploy report `{s, b, a, j, r, e?, d?, t, g, k, p}` (r: `swapped`, `failed`, `rolled_back`, `skipped`, `booted`), once per (s, j, r) per server, across generations. pid `""` |
 | custom | `<name>` | `track(name, props)`: the game's props |
 | funnel | `<funnel>` | `step(funnel, index, name?)`: `i`, `step?` |
-| purchase | `<kind>` | `purchase({product, robux, where?, kind?})`: name = `kind` (default `product`); `product`, `robux`, `where?` |
-| currency | `<currency>` | `currency(name, delta, reason)`: `delta`, `reason` |
+| purchase | `<kind>` | Server only. `purchase(player?, {product, robux, where?, kind?})`: name = `kind` (default `product`); `product`, `robux`, `where?` |
+| currency | `<currency>` | Server only. `currency(player?, name, delta, reason)`: `delta`, `reason` |
 
-Client-sent kinds are limited to `custom`, `funnel`, `purchase`, `currency`, `state`, `tech`.
+Client-sent kinds are limited to `custom`, `funnel`, `state`, `tech`, within a budget of 120 a minute and 5,000 a
+session per player. `purchase` and `currency` are server-only (revenue and the economy are server-authoritative): on
+the client `purchase()` and `currency()` warn once and send nothing, the server refuses those kinds from clients, and
+the analytics server's ingest refuses such rows marked `src = client` (older engines let clients send them). Revenue
+counts only server-sent `purchase` rows; rows from before `src` existed (no `src`) still count.
 
 ## tt-rec-1
 
@@ -124,8 +128,10 @@ start, i.e. the row's `t`). Time is the running sum of `dt`.
 
 ## Sink settings
 
-ConfigService key `TypeTorchAnalytics` (server-only), a JSON object (or a JSON string of one). Re-read on
-`UpdateAvailable` and every 3 minutes, so dials change live. `new AnalyticsEngine({ settings })` replaces the key.
+The signed settings record's `analytics` field (kernel 0.3.8, plans/20; server-only; before 0.3.8 the ConfigService key
+`TypeTorchAnalytics`), a JSON object, written with `typetorch settings set analytics -` (JSON on stdin; the analytics
+repo's `bun run local` does it). Every new signed copy applies at once, so dials change live (the CLI pings servers).
+`new AnalyticsEngine({ settings })` replaces it (tests, Studio, kernels before 0.3.8).
 
 ```json
 {
@@ -150,8 +156,8 @@ ConfigService key `TypeTorchAnalytics` (server-only), a JSON object (or a JSON s
 | `recordShare` | 1 | 0..1, share of new players recorded (stable per pid) |
 | `techEvery` | 60 | 15..3600 seconds between tech samples |
 | `experiments` | none | Per experiment: `active: false` (everyone gets the first variant, not stamped), `weights` (per variant, in the game's order), `variant` (force one) |
-| `identity` | `TypeTorchFleet` url + `/v1/identity` | basin: where identity rows go (below); none and no readable `TypeTorchFleet`: not sent. duckdb: unused |
-| `identityToken` | the `TypeTorchFleet` token | basin: the token for `identity`. Never logged |
+| `identity` | the settings' `fleet` url + `/v1/identity` | basin: where identity rows go (below); none and no `fleet` in the settings: not sent. duckdb: unused |
+| `identityToken` | the settings' `fleet` token | basin: the token for `identity`. Never logged |
 
 Unknown fields are ignored. Settings errors are warned once (never with the token).
 
@@ -174,6 +180,9 @@ Unknown fields are ignored. Settings errors are warned once (never with the toke
   other 4xx drop the batch (counted as rejected).
 - **Delivery is at least once:** a hot swap during a request sends its rows again. Readers may drop exact duplicate
   rows.
+- **The cloud test sends nothing:** inside `typetorch test --cloud` (the stub kernel's `test = true`, or the workspace
+  attribute `TypeTorchTest`) rows are collected as usual but dropped at each flush: no event, recording or identity
+  rows and no HTTP request, so a deploy never puts a fake server session into the analytics.
 - **Queue:** 10,000 events (1,000 while no settings are known), 2,000 fleet rows, 300 recording chunks; over a cap the
   oldest are dropped and counted (`tech/server` `dropped`). The queue lives in the kernel's persist store across hot
   swaps and is flushed on shutdown (kernel 0.3.2 onClose; older kernels: one BindToClose relay).

package/out/analytics/engine.d.ts

@@ -15,10 +15,16 @@ export declare class AnalyticsEngine {
     /** A funnel step, e.g. `step("onboarding", 3, "opened_shop")`. Indexes start at 1 by convention. */
     step(funnel: string, index: number, name?: string): void;
     step(player: Player, funnel: string, index: number, name?: string): void;
-    /** A Robux purchase (log it once the receipt is granted). The event name is `kind` ("product" by default). */
+    /**
+     * A Robux purchase (log it once the receipt is granted). The event name is `kind` ("product" by default). Server
+     * only: revenue is server-authoritative, so on the client this warns once and sends nothing.
+     */
     purchase(purchase: AnalyticsPurchase): void;
     purchase(player: Player, purchase: AnalyticsPurchase): void;
-    /** Currency in (+) or out (-), e.g. `currency("coins", 50, "round_reward")`. */
+    /**
+     * Currency in (+) or out (-), e.g. `currency(player, "coins", 50, "round_reward")`. Server only: the economy is
+     * server-authoritative, so on the client this warns once and sends nothing.
+     */
     currency(name: string, delta: number, reason: string): void;
     currency(player: Player, name: string, delta: number, reason: string): void;
     /**

package/out/analytics/engine.luau

@@ -10,7 +10,7 @@ local ServerAnalytics = TS.import(script, script.Parent, "server").ServerAnalyti
 	 * client. Nothing runs until one is created. Every engine created in a generation shares one core, which stops with
 	 * the generation; its unsent rows survive a hot swap in `persist`.
 	 *
-	 * The server sends rows to the sink in the settings (ConfigService key `TypeTorchAnalytics`, or `options.settings`).
+	 * The server sends rows to the sink in the settings (the signed settings' `analytics`, kernel 0.3.8; or `options.settings`).
 	 * The client sends everything through the server, never to the internet. See the README "Analytics" section and
 	 * src/analytics/SCHEMA.md.
 	 
@@ -26,6 +26,17 @@ local function isPlayer(value)
 	end
 	return _condition
 end
+--* Server-only calls made on the client: warned once each per generation; the server refuses these kinds from clients. 
+local warnedServerOnly = {}
+local function serverOnly(call)
+	local _call = call
+	if warnedServerOnly[_call] ~= nil then
+		return nil
+	end
+	local _call_1 = call
+	warnedServerOnly[_call_1] = true
+	warn("[src/analytics/engine.ts:31]", `[analytics] {call}() is server-only (revenue and currency are server-authoritative): the client sends nothing`)
+end
 local function currentServer(options)
 	if serverCore then
 		return serverCore
@@ -87,11 +98,11 @@ do
 			local existing = serverCore ~= nil
 			self.server = currentServer(options)
 			if existing and options.settings ~= nil then
-				warn("[src/analytics/engine.ts:67]", "[analytics] an engine already runs: its settings stay")
+				warn("[src/analytics/engine.ts:75]", "[analytics] an engine already runs: its settings stay")
 			end
 		else
 			if options.settings ~= nil then
-				warn("[src/analytics/engine.ts:69]", "[analytics] settings are read on the server only; the client ignores them")
+				warn("[src/analytics/engine.ts:77]", "[analytics] settings are read on the server only; the client ignores them")
 			end
 			self.client = currentClient(options)
 		end
@@ -150,6 +161,10 @@ do
 		end
 	end
 	function AnalyticsEngine:purchase(first, second)
+		if self.client then
+			serverOnly("purchase")
+			return nil
+		end
 		local player = if isPlayer(first) then first else nil
 		local info = (if player then second else first)
 		local _condition = not info
@@ -162,7 +177,7 @@ do
 			end
 		end
 		if _condition then
-			warn("[src/analytics/engine.ts:114]", "[analytics] purchase({ product, robux }) needs numbers")
+			warn("[src/analytics/engine.ts:129]", "[analytics] purchase({ product, robux }) needs numbers")
 			return nil
 		end
 		local _kind = info.kind
@@ -180,37 +195,27 @@ do
 		if _result ~= nil then
 			_result:track(player, "purchase", kind, props)
 		end
-		local _result_1 = self.client
-		if _result_1 ~= nil then
-			_result_1:track("purchase", kind, props)
-		end
 	end
 	function AnalyticsEngine:currency(first, second, third, fourth)
+		if self.client then
+			serverOnly("currency")
+			return nil
+		end
 		if isPlayer(first) then
-			local props = {
-				delta = third,
-				reason = fourth,
-			}
 			local _result = self.server
 			if _result ~= nil then
-				_result:track(first, "currency", second, props)
-			end
-			local _result_1 = self.client
-			if _result_1 ~= nil then
-				_result_1:track("currency", second, props)
+				_result:track(first, "currency", second, {
+					delta = third,
+					reason = fourth,
+				})
 			end
 		else
-			local props = {
-				delta = second,
-				reason = third,
-			}
 			local _result = self.server
 			if _result ~= nil then
-				_result:track(nil, "currency", first, props)
-			end
-			local _result_1 = self.client
-			if _result_1 ~= nil then
-				_result_1:track("currency", first, props)
+				_result:track(nil, "currency", first, {
+					delta = second,
+					reason = third,
+				})
 			end
 		end
 	end
@@ -281,7 +286,7 @@ do
 			return self.client:experiment(first, variants)
 		end
 		if self.server then
-			warn("[src/analytics/engine.ts:187]", `[analytics] experiment("{first}") on the server needs the player: experiment(player, name, variants)`)
+			warn("[src/analytics/engine.ts:204]", `[analytics] experiment("{first}") on the server needs the player: experiment(player, name, variants)`)
 		end
 		local _condition = variants[1]
 		if _condition == nil then

package/out/analytics/protocol.d.ts

@@ -52,7 +52,10 @@ export interface ServerHello {
     /** Live experiment overrides by name. */
     exps: Record<string, ExperimentOverride>;
 }
-/** Kinds a client may send in "ev". */
+/**
+ * Kinds a client may send in "ev". Never `purchase` or `currency`: revenue and the economy are server-authoritative
+ * (a client could otherwise add fake payers and Robux), so the server refuses them from clients.
+ */
 export declare const CLIENT_KINDS: Set<string>;
 /** A client's hello, checked field by field (it comes from an untrusted client). */
 export declare function cleanHello(value: unknown): HelloInfo | undefined;

package/out/analytics/protocol.luau

@@ -38,12 +38,15 @@ local INPUTS = {
 	["vr"] = true,
 	["unknown"] = true,
 }
---* Kinds a client may send in "ev". 
+--[[
+	*
+	 * Kinds a client may send in "ev". Never `purchase` or `currency`: revenue and the economy are server-authoritative
+	 * (a client could otherwise add fake payers and Robux), so the server refuses them from clients.
+	 
+]]
 local CLIENT_KINDS = {
 	["custom"] = true,
 	["funnel"] = true,
-	["purchase"] = true,
-	["currency"] = true,
 	["state"] = true,
 	["tech"] = true,
 }

package/out/analytics/schema.d.ts

@@ -5,10 +5,6 @@
  */
 /** Row format version (column `v`). */
 export declare const SCHEMA_VERSION = 1;
-/** The ConfigService key (server-only) that holds the sink settings. */
-export declare const SETTINGS_KEY = "TypeTorchAnalytics";
-/** The kernel's fleet API settings `{ url, token }` (server-only ConfigService key); identities can go there. */
-export declare const FLEET_SETTINGS_KEY = "TypeTorchFleet";
 /** The first-session recording codec (column `codec`). */
 export declare const RECORDING_CODEC = "tt-rec-1";
 /** Most bytes of the `props` JSON text. Larger props become `{"_trunc":<bytes>}`. */
@@ -91,7 +87,7 @@ export interface ExperimentOverride {
     /** Everyone gets this variant (must be one of the game's variants). */
     variant?: string;
 }
-/** The sink settings: ConfigService key `TypeTorchAnalytics` (server-only), or `new AnalyticsEngine({ settings })`. */
+/** The sink settings: the signed settings' `analytics` (kernel 0.3.8, server-only), or `new AnalyticsEngine({ settings })`. */
 export interface AnalyticsSettings {
     backend: "basin" | "duckdb";
     /** basin: the events stream's ingest URL; duckdb: the analytics server's ingest URL. */
@@ -109,12 +105,12 @@ export interface AnalyticsSettings {
     /** Live experiment overrides by experiment name. */
     experiments?: Record<string, ExperimentOverride>;
     /**
-     * basin: where identity rows go (the fleet API's `POST /v1/identity` URL). Default: the `TypeTorchFleet` key's url
+     * basin: where identity rows go (the fleet API's `POST /v1/identity` URL). Default: the settings' `fleet` url
      * + /v1/identity when the server can read it; without either, identities aren't sent. duckdb: unused (they go in
      * the batch body).
      */
     identity?: string;
-    /** basin: the token for `identity` (default: the `TypeTorchFleet` token). Never logged. */
+    /** basin: the token for `identity` (default: the settings' `fleet` token). Never logged. */
     identityToken?: string;
 }
 /** AnalyticsSettings with every default filled in. */
@@ -147,7 +143,7 @@ export interface AnalyticsPurchase {
 }
 /** What the automatic collectors do. Everything is on by default. */
 export interface AnalyticsOptions {
-    /** Server only: the sink settings. When set, the ConfigService key isn't read (tests, Studio). */
+    /** Server only: the sink settings. When set, the signed settings aren't read (tests, Studio, kernels before 0.3.8). */
     settings?: AnalyticsSettings;
     /** Server: joins, leaves, device, join source, first-ever vs returning. Default true. */
     sessions?: boolean;

package/out/analytics/schema.luau

@@ -8,10 +8,6 @@
 ]]
 --* Row format version (column `v`). 
 local SCHEMA_VERSION = 1
---* The ConfigService key (server-only) that holds the sink settings. 
-local SETTINGS_KEY = "TypeTorchAnalytics"
---* The kernel's fleet API settings `{ url, token }` (server-only ConfigService key); identities can go there. 
-local FLEET_SETTINGS_KEY = "TypeTorchFleet"
 --* The first-session recording codec (column `codec`). 
 local RECORDING_CODEC = "tt-rec-1"
 --* Most bytes of the `props` JSON text. Larger props become `{"_trunc":<bytes>}`. 
@@ -26,7 +22,7 @@ local PROPS_MAX_BYTES = 4096
 	 
 ]]
 --* Live overrides of one per-player experiment (settings key `experiments`). 
---* The sink settings: ConfigService key `TypeTorchAnalytics` (server-only), or `new AnalyticsEngine({ settings })`. 
+--* The sink settings: the signed settings' `analytics` (kernel 0.3.8, server-only), or `new AnalyticsEngine({ settings })`. 
 --* AnalyticsSettings with every default filled in. 
 --* Event properties: a flat JSON object (nested tables work but are harder to query). 
 --* What the automatic collectors do. Everything is on by default. 
@@ -35,8 +31,6 @@ local PROPS_MAX_BYTES = 4096
 --* Counters of the server engine (`AnalyticsEngine.stats()`). 
 return {
 	SCHEMA_VERSION = SCHEMA_VERSION,
-	SETTINGS_KEY = SETTINGS_KEY,
-	FLEET_SETTINGS_KEY = FLEET_SETTINGS_KEY,
 	RECORDING_CODEC = RECORDING_CODEC,
 	PROPS_MAX_BYTES = PROPS_MAX_BYTES,
 }

package/out/analytics/server.d.ts

@@ -63,7 +63,7 @@ export declare class ServerAnalytics {
     private settingsErrors;
     /** The first settings read finished (found or not), so experiment overrides are as known as they get. */
     private settingsTried;
-    /** The `TypeTorchFleet` value (Basin games send identities to the fleet API). */
+    /** The settings' `fleet` value (Basin games send identities to the fleet API). */
     private fleetSettings?;
     private nextFlushAt;
     private backoffUntil;
@@ -74,6 +74,12 @@ export declare class ServerAnalytics {
     private readonly identity;
     private sexp;
     private stopped;
+    /**
+     * `typetorch test --cloud`: the payload boots headless in a Luau Execution task, where HttpService works. The engine
+     * then collects as usual but sends nothing (no rows, no identity rows, no HTTP), or every prod deploy would put a
+     * fake server session into the owner's analytics. Set by the stub kernel's `test` or the TypeTorchTest attribute.
+     */
+    private readonly testMode;
     constructor(options: AnalyticsOptions, scope: GenerationScope, trove: Trove);
     private serverExperiment;
     private stateOf;
@@ -109,6 +115,12 @@ export declare class ServerAnalytics {
      */
     private resolve;
     private joinSource;
+    /**
+     * How many of the player's friends are in this server: one `GetFriendsAsync` per join (at most FRIEND_PAGES_MAX
+     * pages) intersected with the players here, instead of an IsFriendsWith call per player. Stops early once every
+     * other player was found; after each yield it stops with the count so far if the player left or the generation
+     * stopped. No call when the player is alone; a failed call counts what it read (0 at first).
+     */
     private friendsHere;
     private emitJoin;
     private onPlayer;
@@ -117,6 +129,8 @@ export declare class ServerAnalytics {
     private recordingAllowed;
     private sendHello;
     private onHello;
+    /** One client-sent event (or an "exp" message, which may add a row): within the player's budget and the session cap. */
+    private takeClientEvent;
     private onEvents;
     private onChunk;
     private startIntake;