@typetorch/framework 0.3.0 → 0.3.4

package/README.md

@@ -115,13 +115,42 @@ export class CoinService extends Module implements OnStart {
   work the same way; see the transformer's README.
 - **UI:** `observeElement(trove, tag, (instance, elementTrove) => ...)`, `isRealFrame`, `popIn` / `popOut` / `bump`
   (UIScale, never Size tweens) and `PopupQueue` (one modal at a time).
-- **Dev menu:** devs (Studio, project members, dev badge) get a DEV button, `Ctrl+Shift+D` and `/tt dev`: artifact,
-  server status, logs (server, own client, other players' clients), client and server dex, network stats, module
-  state, a branch and artifact 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). Modules has
-  Overview, State and Assets (hot assets), each with a Server | Client toolbar. In the Dex,
-  right-click or long-press a property for Copy value / Copy name and a tree row for Copy path (Roblox has no
-  clipboard, so copying opens a small popup with the text selected: Ctrl+C, or long-press > Copy on touch).
+- **Dev menu:** devs (Studio, project members, dev badge) get a DEV button, `Ctrl+Shift+D` and `/tt dev`: artifact
+  (with how long the server and client generations have run, the server's uptime and the build's age), server status,
+  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:
+  strings (cut), numbers, booleans, nil, datatypes through `tostring`, an Instance as its full path, a Player as its
+  name, `function`, `thread`, buffer sizes. Nothing is ever called (raw reads only: no metamethods, no getters); a
+  value that is its own ancestor shows as a cycle. A key filter (open nodes stay listed), Refresh and Auto (every 2 s).
+  Server state comes from the op `state.inspect` (rate-limited, size-capped): devs on dev-channel servers, owners only
+  on prod-effective servers, since server state can hold player data.
+- **Logs > Upload:** sends the logs shown (Server: this server's log ring; Client: your own client's; Others: the
+  picked player's client) to the dev PC paired in the Claude tab, which saves them under `<repo>/.typetorch/logs/`.
+  No Claude run, no prompt quota. Not paired: "Pair in the Claude tab first".
+- **Switch a live server (kernel 0.3.4):** owners switch any server and load builds on it, public and prod ones too:
+  Server > Branch, "Switch" on a branch or "Load here" on a build, then the green Confirm. Everyone stays. These are
+  ordinary switches and pins: Reload and Rollback keep working, and going back to prod is Switch on the prod row (its
+  verified head). A public switch lasts for that server's lifetime and is never stored, so new servers still boot the
+  signed prod head. Others see "Join", which moves only them to a reserved server. Manage > Servers "Load a build..."
+  does the same for this server, the ticked servers or a share of one branch (A/B pins), with one status line under
+  the list.
+- **Owners and devs:** two roles (no admins: an older kernel's or typetorch.json's "admin" counts as a dev). The Manage
+  group (Players, Servers, Bans) is for owners only.
 - **Remote Claude** (dev-channel servers only): while `typetorch remote-claude` (`@typetorch/dev-server`) runs on a dev's machine, allowlisted
   devs prompt Claude Code from the Claude tab. Each dev pairs once by pasting the pairing code printed by
   typetorch-dev-server; the game server keeps the session URL and the tokens in memory and never sends them to clients.
@@ -155,13 +184,13 @@ this.trove.add(TypeTorch.onUpdatePending((update) => (hint.Visible = !update.can
 const scores = TypeTorch.persist("scores.v1", () => new Map<number, number>());
 
 // Dev and roles (server: the kernel decides; client: only the local player, cosmetic)
-if (TypeTorch.isAdmin(player)) showAdminPanel(player);
-TypeTorch.onPlayerDevChanged((player, info) => setAdminTools(player, info.dev));
+if (TypeTorch.isOwner(player)) showOwnerPanel(player);
+TypeTorch.onPlayerDevChanged((player, info) => setDevTools(player, info.dev));
 
 // Server only
 TypeTorch.status(); // uptime, players, memory, history: cheap
 TypeTorch.branches(); TypeTorch.artifacts(); // registry reads, cached ~30 s: may yield, don't call per frame
-TypeTorch.requestReload(player); // owner and admins only, checked by the kernel
+TypeTorch.requestReload(player); // owners only, checked by the kernel
 
 // Logs (the kernel's ring buffer)
 TypeTorch.logs(0, 50);
@@ -279,13 +308,16 @@ 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).
-  `settings` (server only) replaces the ConfigService key, for tests.
+  `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.
 - **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`.
@@ -297,16 +329,32 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   about 10 times a second, every input (never while a TextBox or the chat has focus; text boxes only say which box was
   used), buttons pressed and hovered, screens, prompts and deaths, from the join until 60 s after the first input.
   Packed into small binary chunks (10-20 KB a player) and sent through the server.
-- **Never collected:** chat or anything typed, usernames and display names (error texts have them replaced), UserIds.
+- **Never collected:** chat or anything typed, usernames and display names (error texts have them replaced). No event
+  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
+  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.
 - **Sending:** one queue on the server (10,000 events; over that the oldest are dropped and counted), a flush every
   `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 by the CLI or in
-Creator Hub (Configs), 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 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:
 
 ```json
 { "backend": "basin", "events": "https://<stream-id>.ingest.cloudflare.com",
@@ -335,9 +383,15 @@ bun run build   # rbxtsc --type package -> out/
   kernel's and the template's `rokit.toml`). `scripts/test-generations.luau` takes a game's built payload:
   `cd ../template && bun run payload && lune run ../framework/scripts/test-generations.luau build/payload.rbxm` boots
   two generations in one VM and checks fresh registries, DI and generated guards, then runs the real `startServer`
-  with stub kernels (onStart failures reported to kernel 0.3.2, raised on older ones; onClose) and the health lines.
+  with stub kernels (onStart failures reported to kernel 0.3.2, raised on older ones; onClose), the health lines and
+  the Branch tab / "Load a build" rules (`devtools/build-actions.ts`).
   To test framework changes before the template takes them, build the payload from a copy of the template whose
   `node_modules/@typetorch/framework/out` is this repo's `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-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
 
@@ -150,6 +154,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 |
 
 Unknown fields are ignored. Settings errors are warned once (never with the token).
 
@@ -158,7 +164,13 @@ Unknown fields are ignored. Settings errors are warned once (never with the toke
 - **basin:** `POST <events>` with a JSON array of event rows and `POST <recordings>` with a JSON array of recording
   rows. `Content-Type: application/json`, `Authorization: Bearer <token>` when set, no compression.
 - **duckdb:** `POST <events>` with `{"events":[...],"recordings":[...]}`, gzip (`Content-Encoding: gzip`, HttpService
-  `Compress`), `Content-Type: application/json`, `Authorization: Bearer <token>`.
+  `Compress`), `Content-Type: application/json`, `Authorization: Bearer <token>`. With identity rows waiting, the body
+  also has `"identities":[...]`.
+- **Identities** (engine option `identity`, default on): once a player's pid is known, one row `{ "pid", "uid", "t" }`
+  (the UserId as a number, unix ms; nothing else about the player) per session, so the dev's own server can map pids
+  and UserIds (support, Right to Erasure) and delete the link. Never part of the events table. duckdb: in the batch
+  body; basin: `POST <identity>` with `{"identities":[...]}` and `Authorization: Bearer <identityToken>` (Basin rows
+  can't be deleted, so they never go to Basin). At most 200 per request; 500 wait at most.
 - **Batches:** every `flushSeconds`, or at 500 queued events or 20 recordings. At most 500 event rows (fleet rows
   first) and 50 recording rows per request, about 900 KB each. At most ~10 requests a minute per server (burst 3).
 - **Answers:** 2xx sent; 413 the batch is halved and resent (a single row is dropped); 401/403/404 rows are kept and
@@ -166,6 +178,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).
@@ -174,7 +189,8 @@ Unknown fields are ignored. Settings errors are warned once (never with the toke
 
 DataStore `TypeTorchAnalytics`, key `p/<UserId>` -> `{ "pid": "<32 hex>", "first": <unix s>, "last": <unix s> }`.
 One read per join (with retries), a write on the first join (UpdateAsync, keeps a pid another server wrote first) and
-one at leave (`last`). A Right to Erasure request deletes the key, which leaves the player's rows anonymous.
+one at leave (`last`). A Right to Erasure request deletes the key, which leaves the player's rows anonymous. The
+analytics server also keeps pid -> UserId from identity rows (above), which its erasure webhook uses and deletes.
 
 ## Suggested Basin stream schemas
 

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

@@ -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

@@ -7,6 +7,8 @@
 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>}`. */
@@ -68,6 +70,18 @@ export interface RecordingRow {
     /** Position samples in the chunk. */
     n: number;
 }
+/**
+ * Which UserId a pid belongs to, sent once per session when the pid is known. Only to the dev's own server (the
+ * analytics server, or the fleet API for Basin games), never into the events table: it lets the dev map pids and
+ * UserIds (support, Right to Erasure) and delete the link.
+ */
+export interface IdentityRow {
+    pid: string;
+    /** The player's UserId. */
+    uid: number;
+    /** Unix ms. */
+    t: number;
+}
 /** Live overrides of one per-player experiment (settings key `experiments`). */
 export interface ExperimentOverride {
     /** false: everyone gets the first variant (control) and the experiment isn't stamped on events. */
@@ -94,6 +108,14 @@ export interface AnalyticsSettings {
     techEvery?: number;
     /** 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
+     * + /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. */
+    identityToken?: string;
 }
 /** AnalyticsSettings with every default filled in. */
 export interface ResolvedSettings {
@@ -105,6 +127,8 @@ export interface ResolvedSettings {
     recordShare: number;
     techEvery: number;
     experiments: Map<string, ExperimentOverride>;
+    identity?: string;
+    identityToken?: string;
 }
 export type AnalyticsValue = string | number | boolean;
 /** Event properties: a flat JSON object (nested tables work but are harder to query). */
@@ -140,6 +164,12 @@ export interface AnalyticsOptions {
      * one row per deploy report, kind "fleet". They go before analytics events. Default true.
      */
     fleet?: boolean;
+    /**
+     * Server: one identity row `{ pid, uid, t }` per session once the pid is known (UserId and pid, nothing else), so
+     * the dev's own server can map them. duckdb: in the batch body (`identities`); basin: to the fleet API (Basin rows
+     * can't be deleted). Never part of the events table. Default true.
+     */
+    identity?: boolean;
 }
 /** Kernel 0.3.2+ `fleetStatus()`: the server's heartbeat (sent as the props of a "fleet" / "heartbeat" row). */
 export type FleetStatus = {
@@ -159,6 +189,8 @@ export interface AnalyticsStats {
     queuedRecordings: number;
     /** Fleet rows waiting (they go first). */
     queuedFleet: number;
+    /** Identity rows waiting (pid -> UserId, for the dev's own server). */
+    queuedIdentities: number;
     /** Rows sent since the server started (across swaps). */
     sent: number;
     /** Rows dropped because the queue was full. */

package/out/analytics/schema.luau

@@ -10,12 +10,21 @@
 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>}`. 
 local PROPS_MAX_BYTES = 4096
 --* One row of the events table. Flat; every column is always present. 
 --* One row of the recordings table: one packed chunk of a player's first-ever session. 
+--[[
+	*
+	 * Which UserId a pid belongs to, sent once per session when the pid is known. Only to the dev's own server (the
+	 * analytics server, or the fleet API for Basin games), never into the events table: it lets the dev map pids and
+	 * UserIds (support, Right to Erasure) and delete the link.
+	 
+]]
 --* Live overrides of one per-player experiment (settings key `experiments`). 
 --* The sink settings: ConfigService key `TypeTorchAnalytics` (server-only), or `new AnalyticsEngine({ settings })`. 
 --* AnalyticsSettings with every default filled in. 
@@ -27,6 +36,7 @@ local PROPS_MAX_BYTES = 4096
 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,6 +63,8 @@ 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). */
+    private fleetSettings?;
     private nextFlushAt;
     private backoffUntil;
     private batchRows;
@@ -72,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;
@@ -107,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;
@@ -115,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;
@@ -128,6 +144,11 @@ export declare class ServerAnalytics {
     private post;
     /** Sends one batch per table. `final`: shutdown, ignore the budget. */
     private flushOnce;
+    private identityList;
+    private queueIdentity;
+    private takeIdentities;
+    /** Puts identity rows back in front (a failed or unsent request), keeping the cap. */
+    private requeueIdentities;
     private startFlushing;
     /** game code's flush(): send now (within the budget), on its own thread. */
     flushSoon(): void;