@typetorch/framework 0.3.0 → 0.3.2

package/README.md

@@ -115,13 +115,31 @@ 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).
+- **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 +173,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);
@@ -284,8 +302,9 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   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,7 +316,12 @@ 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
@@ -305,8 +329,9 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   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:
+**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 +360,13 @@ 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-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

@@ -150,6 +150,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 +160,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
@@ -174,7 +182,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/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;
@@ -128,6 +130,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;

package/out/analytics/server.luau

@@ -39,10 +39,12 @@ local newQueueState = _queue.newQueueState
 local RowQueue = _queue.RowQueue
 local takeToken = _queue.takeToken
 local _schema = TS.import(script, script.Parent, "schema")
+local FLEET_SETTINGS_KEY = _schema.FLEET_SETTINGS_KEY
 local RECORDING_CODEC = _schema.RECORDING_CODEC
 local SCHEMA_VERSION = _schema.SCHEMA_VERSION
 local SETTINGS_KEY = _schema.SETTINGS_KEY
 local _settings = TS.import(script, script.Parent, "settings")
+local identityTarget = _settings.identityTarget
 local parseSettings = _settings.parseSettings
 local recordsSupported = _settings.recordsSupported
 local DEFAULT_TECH_EVERY = _settings.DEFAULT_TECH_EVERY
@@ -77,6 +79,9 @@ local BATCH_BYTES = 900000
 --* HTTP budget: a burst of 3, refilled at 10 a minute (Roblox: 500 a minute per server for everything). 
 local HTTP_BURST = 3
 local HTTP_PER_MINUTE = 10
+--* Identity rows (pid -> UserId) waiting; past this the oldest go. 
+local IDENTITIES_CAP = 500
+local BATCH_IDENTITIES = 200
 --* Rows kept per player while their pid loads. 
 local PENDING_MAX = 200
 --* Client events: burst and refill per minute, and the most per session. 
@@ -165,6 +170,8 @@ local function newStore()
 		fleetSeen = {},
 		inflightEvents = {},
 		inflightRecordings = {},
+		identities = {},
+		inflightIdentities = {},
 		budget = {
 			tokens = HTTP_BURST,
 			last = os.clock(),
@@ -235,6 +242,15 @@ do
 		if #self.store.inflightRecordings > 0 then
 			self.recordings:requeue(self.store.inflightRecordings)
 		end
+		-- Stores from before identities existed (a hot swap from an older framework) have neither list.
+		if self.store.identities == nil then
+			self.store.identities = {}
+		end
+		local handedOver = self.store.inflightIdentities or {}
+		if #handedOver > 0 then
+			self:requeueIdentities(handedOver)
+		end
+		self.store.inflightIdentities = {}
 		self.store.inflightEvents = {}
 		self.store.inflightRecordings = {}
 		trove:add(function()
@@ -440,7 +456,7 @@ do
 	end
 	function ServerAnalytics:track(player, kind, name, props)
 		if not isEventName(name) then
-			warn("[src/analytics/server.ts:418]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
+			warn("[src/analytics/server.ts:435]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
 			return nil
 		end
 		local session = if player then self:sessionOf(player) else nil
@@ -548,7 +564,7 @@ do
 		end
 		local control = _condition
 		if not isExperimentName(name) or not isVariantList(variants) then
-			warn("[src/analytics/server.ts:469]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
+			warn("[src/analytics/server.ts:486]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
 			return control
 		end
 		local session = self:sessionOf(player)
@@ -597,7 +613,7 @@ do
 	function ServerAnalytics:applySettings(parsed)
 		local errorsText = table.concat(parsed.errors, "; ")
 		if errorsText ~= table.concat(self.settingsErrors, "; ") and errorsText ~= "" then
-			warn("[src/analytics/server.ts:500]", `[analytics] {SETTINGS_KEY}: {errorsText}`)
+			warn("[src/analytics/server.ts:517]", `[analytics] {SETTINGS_KEY}: {errorsText}`)
 		end
 		self.settingsErrors = parsed.errors
 		local hadSettings = self.settings ~= nil
@@ -629,6 +645,12 @@ do
 			if not snapshot or (missing and not force) then
 				return nil
 			end
+			local fleetOk, fleetValue = pcall(function()
+				return snapshot:GetValue(FLEET_SETTINGS_KEY)
+			end)
+			if fleetOk then
+				self.fleetSettings = fleetValue
+			end
 			local ok, value = pcall(function()
 				return snapshot:GetValue(SETTINGS_KEY)
 			end)
@@ -668,7 +690,7 @@ do
 						snapshot = result
 					else
 						if attempt == 1 then
-							warn("[src/analytics/server.ts:544]", `[analytics] ConfigService unavailable: {string.sub(tostring(result), 1, 120)}`)
+							warn("[src/analytics/server.ts:563]", `[analytics] ConfigService unavailable: {string.sub(tostring(result), 1, 120)}`)
 						end
 						task.wait(delay)
 						delay = math.min(delay * 2, 30)
@@ -856,6 +878,9 @@ do
 		session.first = first
 		session.ret = ret
 		session.ready = true
+		if self.options.identity ~= false then
+			self:queueIdentity(player.UserId, pid)
+		end
 		for _, row in session.pending do
 			row.pid = session.pid
 			row.newp = session.newp
@@ -1355,7 +1380,7 @@ do
 				end
 			end)
 			if not ok then
-				warn("[src/analytics/server.ts:988]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
+				warn("[src/analytics/server.ts:1008]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
 			end
 		end)
 		self.trove:add(function()
@@ -1635,7 +1660,7 @@ do
 			return nil
 		end
 		self.lastWarnAt = now
-		warn("[src/analytics/server.ts:1177]", `[analytics] {message}`)
+		warn("[src/analytics/server.ts:1197]", `[analytics] {message}`)
 	end
 	function ServerAnalytics:post(request)
 		local ok, response = pcall(function()
@@ -1672,7 +1697,12 @@ do
 			end
 		end
 		local recordings = if recordsSupported(settings) then self.recordings:take(BATCH_RECORDINGS, BATCH_BYTES, estimateRecordingBytes) else {}
-		if #events == 0 and #recordings == 0 then
+		local waiting = self.store.identities or {}
+		local identities = if #waiting > 0 then self:takeIdentities() else {}
+		-- Basin without a fleet API to send them to: identities are dropped (they never go into Basin).
+		local target = if settings.backend == "basin" and #identities > 0 then identityTarget(settings, self.fleetSettings, decode) else nil
+		local sendIdentities = if settings.backend == "duckdb" or target ~= nil then identities else {}
+		if #events == 0 and #recordings == 0 and #sendIdentities == 0 then
 			self.flushing = false
 			return nil
 		end
@@ -1680,7 +1710,8 @@ do
 		-- to the next generation (sent again: at least once).
 		self.store.inflightEvents = events
 		self.store.inflightRecordings = recordings
-		local requests = buildRequests(settings, events, recordings, quote)
+		self.store.inflightIdentities = sendIdentities
+		local requests = buildRequests(settings, events, recordings, quote, sendIdentities, target)
 		local settle = function(request, giveBack)
 			if request.events > 0 then
 				if giveBack then
@@ -1694,6 +1725,12 @@ do
 				end
 				self.store.inflightRecordings = {}
 			end
+			if request.identities > 0 then
+				if giveBack then
+					self:requeueIdentities(sendIdentities)
+				end
+				self.store.inflightIdentities = {}
+			end
 		end
 		local failed = false
 		for _, request in requests do
@@ -1703,9 +1740,10 @@ do
 			end
 			local status = self:post(request)
 			local outcome = classifyStatus(status)
-			local rows = request.events + request.recordings
+			local rows = request.events + request.recordings + request.identities
 			if outcome == "sent" then
-				self.store.sent += rows
+				-- Identity rows aren't analytics rows: "sent" counts events and recordings.
+				self.store.sent += request.events + request.recordings
 				self.store.failures = 0
 				self.batchRows = BATCH_ROWS
 				settle(request, false)
@@ -1715,33 +1753,77 @@ do
 			elseif outcome == "drop" or outcome == "split" then
 				self.store.rejected += rows
 				settle(request, false)
-				self:warn(`the {request.table} sink refused {rows} rows (HTTP {status}); they were dropped`)
+				self:warn(`analytics upload refused {rows} rows (HTTP {status}); they were dropped`)
 			else
 				settle(request, true)
 				failed = true
 				self.store.failures += 1
 				local wait = if outcome == "config" then 300 else backoffSeconds(self.store.failures, math.random())
 				self.backoffUntil = os.clock() + wait
-				local _self = self
+				-- "both" = one batch with events and recordings (the DuckDB sink); say "analytics upload" instead.
+				local what = if request.table == "both" then "analytics upload" else `analytics upload ({request.table})`
 				local _result
-				if outcome == "config" then
-					_result = `the {request.table} sink answered HTTP {status}: check the URL and token in {SETTINGS_KEY}; retrying in {math.floor(wait)} s`
+				if status > 0 then
+					_result = `HTTP {status}`
 				else
-					local _exp = request.table
 					local _condition = self.store.lastError
 					if _condition == nil then
-						_condition = `HTTP {status}`
+						_condition = "no response"
 					end
-					_result = `the {_exp} sink failed ({_condition}); retrying in {math.floor(wait)} s`
+					_result = _condition
 				end
-				_self:warn(_result)
+				local reason = _result
+				local fix = if status == 530 then ": the tunnel is down, run bun run local on the dev PC" else ""
+				self:warn(if outcome == "config" then `{what} got HTTP {status}: check the URL and token in {SETTINGS_KEY}; retrying in {math.floor(wait)} s` else `{what} failed ({reason}{fix}); retrying in {math.floor(wait)} s`)
 			end
 		end
 		-- Recordings without a request (basin without a recordings URL) were never taken; nothing else is left.
 		self.store.inflightEvents = {}
 		self.store.inflightRecordings = {}
+		self.store.inflightIdentities = {}
 		self.flushing = false
 	end
+	function ServerAnalytics:identityList()
+		if self.store.identities == nil then
+			self.store.identities = {}
+		end
+		return self.store.identities
+	end
+	function ServerAnalytics:queueIdentity(userId, pid)
+		local list = self:identityList()
+		local _arg0 = {
+			pid = pid,
+			uid = userId,
+			t = nowMs(),
+		}
+		table.insert(list, _arg0)
+		while #list > IDENTITIES_CAP do
+			table.remove(list, 1)
+		end
+	end
+	function ServerAnalytics:takeIdentities()
+		local list = self:identityList()
+		local taken = {}
+		while #list > 0 and #taken < BATCH_IDENTITIES do
+			local _arg0 = table.remove(list, 1)
+			table.insert(taken, _arg0)
+		end
+		return taken
+	end
+	function ServerAnalytics:requeueIdentities(rows)
+		local list = self:identityList()
+		local _array = {}
+		local _length = #_array
+		table.move(rows, 1, #rows, _length + 1, _array)
+		local merged = _array
+		for _, row in list do
+			table.insert(merged, row)
+		end
+		while #merged > IDENTITIES_CAP do
+			table.remove(merged, 1)
+		end
+		self.store.identities = merged
+	end
 	function ServerAnalytics:startFlushing()
 		self.nextFlushAt = os.clock() + 5
 		self.trove:add(task.spawn(function()
@@ -1843,17 +1925,27 @@ do
 		_object.queued = self.events:size()
 		_object.queuedRecordings = self.recordings:size()
 		_object.queuedFleet = self.fleet:size()
+		local _left_1 = "queuedIdentities"
+		local _result_1 = self.store.identities
+		if _result_1 ~= nil then
+			_result_1 = #_result_1
+		end
+		local _condition = _result_1
+		if _condition == nil then
+			_condition = 0
+		end
+		_object[_left_1] = _condition
 		_object.sent = self.store.sent
 		_object.dropped = self.store.events.dropped + self.store.recordings.dropped + self.store.fleet.dropped
 		_object.rejected = self.store.rejected
 		_object.failures = self.store.failures
 		_object.lastError = self.store.lastError
-		local _left_1 = "settingsErrors"
+		local _left_2 = "settingsErrors"
 		local _array = {}
 		local _length = #_array
 		local _array_1 = self.settingsErrors
 		table.move(_array_1, 1, #_array_1, _length + 1, _array)
-		_object[_left_1] = _array
+		_object[_left_2] = _array
 		return _object
 	end
 end

package/out/analytics/settings.d.ts

@@ -18,5 +18,15 @@ export interface ParsedSettings {
  * no settings and no errors. Unknown fields are ignored.
  */
 export declare function parseSettings(raw: unknown, decode: (text: string) => unknown): ParsedSettings;
+/** Where identity rows go on a Basin game: the fleet API (`TypeTorchFleet` = { url, token }) at /v1/identity. */
+export interface IdentityTarget {
+    url: string;
+    token?: string;
+}
+/**
+ * The identity target for these settings: duckdb none (identities ride in the batch body); basin the `identity` URL,
+ * else the fleet API's /v1/identity from the `TypeTorchFleet` value (a table or JSON `{ url, token }`), else none.
+ */
+export declare function identityTarget(settings: ResolvedSettings, fleetRaw: unknown, decode: (text: string) => unknown): IdentityTarget | undefined;
 /** Whether recordings can be sent at all: duckdb always (one body), basin only with a recordings stream URL. */
 export declare function recordsSupported(settings: ResolvedSettings): boolean;