@typetorch/framework 0.5.7 → 0.6.0

package/README.md

@@ -360,6 +360,27 @@ TypeTorch.runDetached(() => store.StartSessionAsync(`Player_${userId}`)).then((p
   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.
+- **`notifications()`** (plans/29): native Roblox experience notifications through the TypeTorch backend (`backend.url`
+  / `backend.key`, the launch-token keys in `backend.notify` from `typetorch notify key rotate`; no kernel change).
+  The game says why a player should hear from it, the backend decides when and sends, the framework verifies the tap:
+
+  ```ts
+  const notify = TypeTorch.notifications();
+  // Server: intents (upsert by user + kind + key; offline players by UserId), batched and swap-safe.
+  notify.want(userIdOrPlayer, "gift_new", { key: letterId, until: expiresAt, params: { gift: "5 coins" }, data: `mail:${letterId}` });
+  notify.drop(userIdOrPlayer, "streak", "20034", "played"); // no key: every key of the kind
+  trove.add(notify.onOpen((player, open) => openMail(player, open.data))); // open: { nid, kind, data, ageSeconds, first }
+  // Client: Roblox's opt-in prompt, once per session (show your own explainer first). Yields until it closes.
+  const result = TypeTorch.notifications().promptOptIn("streak_2"); // "shown" | "unavailable" | "error" | "busy" | "already"
+  ```
+
+  Kinds are declared in typetorch.json `notifications` and pushed with the CLI. Intents go to
+  `<backend.url>/v1/notify/intents` every `flushSeconds` (and at 200); presence (`online` on join and every 3 h, `offline` on leave)
+  rides along while `backend.notify` is set. A join with `tt1n.` launch data is verified on the server (HMAC, the
+  player's UserId, 14 days; the previous key for 14 days after a rotation): `onOpen` gets only verified data, also for
+  players who joined before the callback connected. Rows (`kind = notify`): `want`, `drop`, `optin_check`,
+  `optin_shown`, `optin_closed`, `open`, `open_bad`, `played` (src/analytics/SCHEMA.md); the join row gets
+  `from = "notification"`. Without backend settings (Studio) nothing is posted; rows are still written.
 - **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.
 
@@ -520,7 +541,7 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   when the player is alone) intersected with the players there, not a web call per player.
 
 **Settings, framework 0.4.0 / kernel 0.4.0 (plans/21):** the record's `backend` = `{ url, key, analytics?: { flushSeconds,
-recordShare } }` (`typetorch backend setup`) is the whole sink: DuckDB at `<url>/v1/ingest` with the one key (Basin
+recordShare, joinLaunchPrefix } }` (`typetorch backend setup`) is the whole sink: DuckDB at `<url>/v1/ingest` with the one key (Basin
 identities to `<url>/v1/identity`). The old `analytics` value below is read while `backend` is missing, and stays the
 way to a Basin sink. The engine also tells the kernel each player's pid (`setAnalyticsId`: the kernel's error reports
 count affected players by pid, never by name) and counts its own DataStore and HTTP requests for the budget view (dev
@@ -589,8 +610,10 @@ bun run build   # rbxtsc --type package -> out/
   vouch, live-copy rules), `test-messaging` (messaging and the server list), `test-settings` (`liveConfig` and the
   settings lines), `test-detached` (`runDetached`), `test-dev-access` (the dev-only tools rule and every gate through
   it), `test-remote-debug` (the remote debug ops and their limits), `test-net-inspect` (packet capture),
-  `test-explorer-core` (Dex), `test-toolbox-sanitize` (the Creator Store sanitizer) and `test-sha256` (the pairing-code
-  fingerprint). `node scripts/check-self-calls.mjs out` flags compiled functions that call themselves on their first
+  `test-explorer-core` (Dex), `test-toolbox-sanitize` (the Creator Store sanitizer), `test-sha256` (SHA-256 / HMAC in util and the
+  pairing-code fingerprint), `test-notifications` (the launch token with the contract's shared vector, intent checks,
+  the queue: batches of 200, rev order, a swap's handover), `test-notify-server` (the notifications server against
+  mocked services) and `test-analytics-join` (the join row's metadata; no other player's UserId). `node scripts/check-self-calls.mjs out` flags compiled functions that call themselves on their first
   lines (after `bun run build`).
 - **Package contents:** only `out/` (no `.tsbuildinfo`), `README.md` and `LICENSE`; check with `bun pm pack --dry-run`.
 - **Explorer class icons:** `assets/class-icons.png` (kept locally, not in the repo: it is Roblox's own texture) is

package/out/analytics/SCHEMA.md

@@ -15,7 +15,7 @@ Integers are written with every digit (never exponent notation).
 |---|---|---|
 | `v` | int32 | Row format version: `1` |
 | `t` | int64 | Unix ms on the game server's clock. Client events are corrected by the server (`server now - age - ping/2`) |
-| `kind` | string | `session`, `tech`, `zone`, `funnel`, `purchase`, `currency`, `state`, `experiment`, `custom`, `recording_meta`, `fleet` |
+| `kind` | string | `session`, `tech`, `zone`, `funnel`, `purchase`, `currency`, `state`, `experiment`, `custom`, `recording_meta`, `fleet`, `notify` |
 | `name` | string | Event name (1-64 chars), see below |
 | `pid` | string | Random player id (32 hex chars; `t` + 31 hex = temporary, the player-id store couldn't be read). `""` for server-only events. Never the UserId |
 | `sid` | string | Session id (32 hex), new per join, kept across hot swaps. `""` for server-only events |
@@ -57,8 +57,11 @@ 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` (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 | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `notification` (a TypeTorch notification's launch data verified), `share` (other launch data), `follow` (followed someone); join metadata (plans/29): `src_place?`, `src_game?` (SourcePlaceId / SourceGameId), `ref?` / `follow?` (the referrer / followed user as their pid when this game knows them, else `"other"`: never a UserId; players in the server are free, others cost one DataStore read each, at most 2 per join and only with read budget to spare), `party?` (players teleported along) + `party_pids?` (the pids of those this game knows, at most 10), `ctx?`, `ctx_item?`, `ctx_asset?`, `ctx_outfit?`, `ctx_asset_type?` (GameJoinContext JoinSource / ItemType / AssetId / OutfitId / AssetType), `launch?` (`notification` + `nid`, `nk` (kind); `tt_bad` + `launch_bad` (`format`, `sig`, `user`, `old`); or the game's own launch data: `launch_len`, plus its first 32 chars in `launch` only with the settings' `joinLaunchPrefix`), `tp?` + `tp_bytes?` (TeleportData present, its JSON size; never the content), `age_days` (exact account age), `locale?`, `verified?` (HasVerifiedBadge), `membership` (MembershipType name); `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) | `dev?` (the device class, as the `dev` column; frameworks after 0.4.2, older ones leave it out), `input` (`kbm`, `touch`, `gamepad`, `vr`, `unknown`), `w`, `h` (viewport points), `touch`, `kb`, `mouse`, `pad`, `vr`. Once per session. The class (Roblox gives game scripts no OS): `vr` when VRService.VREnabled; `console` when GuiService:IsTenFootInterface(); touch without a keyboard: `tablet` when the viewport's short side is 600 points or more, else `phone` (the first hello waits up to 2 s for a real viewport); a keyboard or mouse: `desktop` (touch laptops, tablets with a keyboard); else `unknown` |
+| notify | `want`, `drop` | Notifications (plans/29), written by the game server: `k` (kind), `key?` (first 12 hex of SHA-256 of the intent's key; never the key), `at?`, `until?`, `offline` (want: the user isn't in this server; the row then has no pid), `why?` (drop) |
+| notify | `optin_check`, `optin_shown`, `optin_closed` | The client's opt-in prompt, checked and written by the server (at most 3 of each per session): `where`, `can` (check), `err?` (`timeout`, `swap` or the error's first 64 chars), `secs` (closed: how long it was up) |
+| notify | `open`, `open_bad`, `played` | A join from a notification: `open` (`nid`, `k`, `age` (secs since sent), `first`), `open_bad` (`why`: `format`, `sig`, `user`, `old`), `played` (`nid`, `k`, `secs`: the opened session's length, at its end). Backend rows of the same kind (`planned`, `sent`, ...) come from `src = "backend"` |
 | 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) |
 | tech | `client` (src client) | Every `techEvery` s: `fps`, `mem` (MB, 10s), `ping?` (ms) |
@@ -159,6 +162,7 @@ repo's `bun run local` does it). Every new signed copy applies at once, so dials
 | `experiments` | none | Per experiment: `active: false` (everyone gets the first variant, not stamped), `weights` (per variant, in the game's order), `variant` (force one), `players` (`{ [UserId or pid]: variant }`, at most 200: forces one player's variant over everything else, stamped `forced`; each client's hello gets only its own entry). The CLI writes them: `typetorch experiment` |
 | `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 |
+| `joinLaunchPrefix` | false | true: the join row's `launch` keeps the first 32 characters of the game's own launch data (off: only `launch_len`). Set it in `backend.analytics` (or the old `analytics` value) |
 
 Unknown fields are ignored. Settings errors are warned once (never with the token).
 

package/out/analytics/join.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The `session` / `join` row's join metadata (plans/29 "Native join metadata"): every field of `Player:GetJoinData()`
+ * and the player facts, as props. The engine reads the data (enum values as their names, the TeleportData's JSON size,
+ * other players' pids looked up beforehand) and this builds the props.
+ *
+ * Privacy: no other player's UserId ever lands in a prop. Referrer, followed user and party members become pids (the
+ * game's pseudonymous ids) when this game knows them, else "other" (ref / follow) or nothing (party_pids).
+ *
+ * Pure: no imports and no services, so it runs under Lune (scripts/test-analytics-join.luau).
+ */
+/** What the engine reads from GetJoinData (enums already turned into names). */
+export interface JoinDataLike {
+    SourcePlaceId?: number;
+    SourceGameId?: number;
+    ReferredByPlayerId?: number;
+    Members?: number[];
+    /** Whether TeleportData was present (its content never leaves the server). */
+    HasTeleportData?: boolean;
+    LaunchData?: string;
+    GameJoinContext?: {
+        JoinSource?: string;
+        ItemType?: string;
+        AssetId?: string;
+        OutfitId?: string;
+        AssetType?: string;
+    };
+}
+/** The joining player and this server. */
+export interface JoinFacts {
+    userId: number;
+    /** game.GameId (a teleport from another game is `teleport_game`). */
+    gameId: number;
+    followUserId: number;
+    /** Player.AccountAge (days). */
+    accountAge: number;
+    locale?: string;
+    verified?: boolean;
+    /** Enum.MembershipType name. */
+    membership?: string;
+    /** The TeleportData's JSON size in bytes (undefined: none or not encodable). */
+    tpBytes?: number;
+}
+/** The launch data's verdict (notifications/token.ts verifyToken): undefined when it isn't a TypeTorch token. */
+export type LaunchVerdict = {
+    ok: true;
+    nid: string;
+    kind: string;
+} | {
+    ok: false;
+    why: string;
+} | undefined;
+export interface JoinOptions {
+    /**
+     * Keep the first LAUNCH_KEEP chars of the game's own launch data in `launch` (the analytics settings'
+     * `joinLaunchPrefix`, default off: launch data can carry anything a link maker put there). `launch_len` is always kept.
+     */
+    launchPrefix?: boolean;
+}
+/** Party pids kept at most. */
+export declare const PARTY_PIDS_MAX = 10;
+/** The game's own launch data: this many characters are kept. */
+export declare const LAUNCH_KEEP = 32;
+/** UserIds whose pids the row wants (referrer, followed user, party members), without the player and duplicates. */
+export declare function wantedUserIds(data: JoinDataLike | undefined, facts: JoinFacts): number[];
+/**
+ * The join props. `pidOf(userId)` answers a known pid (a player in this server, or one this game's records know) or
+ * undefined.
+ */
+export declare function joinProps(data: JoinDataLike | undefined, facts: JoinFacts, pidOf: (userId: number) => string | undefined, launch: LaunchVerdict, options?: JoinOptions): Record<string, unknown>;

package/out/analytics/join.luau

@@ -0,0 +1,178 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * The `session` / `join` row's join metadata (plans/29 "Native join metadata"): every field of `Player:GetJoinData()`
+	 * and the player facts, as props. The engine reads the data (enum values as their names, the TeleportData's JSON size,
+	 * other players' pids looked up beforehand) and this builds the props.
+	 *
+	 * Privacy: no other player's UserId ever lands in a prop. Referrer, followed user and party members become pids (the
+	 * game's pseudonymous ids) when this game knows them, else "other" (ref / follow) or nothing (party_pids).
+	 *
+	 * Pure: no imports and no services, so it runs under Lune (scripts/test-analytics-join.luau).
+	 
+]]
+--* What the engine reads from GetJoinData (enums already turned into names). 
+--* The joining player and this server. 
+--* The launch data's verdict (notifications/token.ts verifyToken): undefined when it isn't a TypeTorch token. 
+--* Party pids kept at most. 
+local PARTY_PIDS_MAX = 10
+--* The game's own launch data: this many characters are kept. 
+local LAUNCH_KEEP = 32
+--* UserIds whose pids the row wants (referrer, followed user, party members), without the player and duplicates. 
+local function wantedUserIds(data, facts)
+	local seen = {}
+	local list = {}
+	local add = function(userId)
+		local _userId = userId
+		local _condition = not (type(_userId) == "number")
+		if not _condition then
+			_condition = userId <= 0 or userId == facts.userId
+			if not _condition then
+				local _userId_1 = userId
+				_condition = seen[_userId_1] ~= nil
+			end
+		end
+		if _condition then
+			return nil
+		end
+		local _userId_1 = userId
+		seen[_userId_1] = true
+		local _userId_2 = userId
+		table.insert(list, _userId_2)
+	end
+	local _result = data
+	if _result ~= nil then
+		_result = _result.ReferredByPlayerId
+	end
+	add(_result)
+	add(facts.followUserId)
+	local _result_1 = data
+	if _result_1 ~= nil then
+		_result_1 = _result_1.Members
+	end
+	if _result_1 ~= nil then
+		for _, member in data.Members do
+			add(member)
+		end
+	end
+	return list
+end
+--[[
+	*
+	 * The join props. `pidOf(userId)` answers a known pid (a player in this server, or one this game's records know) or
+	 * undefined.
+	 
+]]
+local function joinProps(data, facts, pidOf, launch, options)
+	if options == nil then
+		options = {}
+	end
+	local info = {}
+	local from = "direct"
+	local mapped = function(userId)
+		local _condition = pidOf(userId)
+		if _condition == nil then
+			_condition = "other"
+		end
+		return _condition
+	end
+	if data ~= nil then
+		if data.SourcePlaceId ~= nil and data.SourcePlaceId ~= 0 then
+			from = if data.SourceGameId ~= nil and data.SourceGameId ~= facts.gameId then "teleport_game" else "teleport"
+			info.src_place = data.SourcePlaceId
+			if data.SourceGameId ~= nil and data.SourceGameId ~= 0 then
+				info.src_game = data.SourceGameId
+			end
+		elseif data.ReferredByPlayerId ~= nil and data.ReferredByPlayerId ~= 0 then
+			from = "referral"
+		elseif launch ~= nil and launch.ok then
+			from = "notification"
+		elseif data.LaunchData ~= nil and data.LaunchData ~= "" then
+			from = "share"
+		end
+		if data.ReferredByPlayerId ~= nil and data.ReferredByPlayerId > 0 then
+			info.ref = mapped(data.ReferredByPlayerId)
+		end
+		local context = data.GameJoinContext
+		if context ~= nil then
+			if context.JoinSource ~= nil then
+				info.ctx = context.JoinSource
+			end
+			if context.ItemType ~= nil then
+				info.ctx_item = context.ItemType
+			end
+			if context.AssetId ~= nil and context.AssetId ~= "" then
+				info.ctx_asset = context.AssetId
+			end
+			if context.OutfitId ~= nil and context.OutfitId ~= "" then
+				info.ctx_outfit = context.OutfitId
+			end
+			if context.AssetType ~= nil then
+				info.ctx_asset_type = context.AssetType
+			end
+		end
+		if data.HasTeleportData == true then
+			info.tp = true
+			if facts.tpBytes ~= nil then
+				info.tp_bytes = facts.tpBytes
+			end
+		end
+		local members = data.Members
+		if members ~= nil and #members > 0 then
+			info.party = #members
+			local pids = {}
+			for _, member in members do
+				if member == facts.userId or #pids >= PARTY_PIDS_MAX then
+					continue
+				end
+				local pid = pidOf(member)
+				if pid ~= nil and not (table.find(pids, pid) ~= nil) then
+					table.insert(pids, pid)
+				end
+			end
+			if #pids > 0 then
+				info.party_pids = pids
+			end
+		end
+		local launchData = data.LaunchData
+		if launch ~= nil then
+			if launch.ok then
+				info.launch = "notification"
+				info.nid = launch.nid
+				info.nk = launch.kind
+			else
+				info.launch = "tt_bad"
+				info.launch_bad = launch.why
+			end
+		elseif launchData ~= nil and launchData ~= "" then
+			if options.launchPrefix == true then
+				info.launch = string.sub(launchData, 1, LAUNCH_KEEP)
+			end
+			info.launch_len = #launchData
+		end
+	end
+	if from == "direct" and facts.followUserId ~= 0 then
+		from = "follow"
+	end
+	if facts.followUserId > 0 then
+		info.follow = mapped(facts.followUserId)
+	end
+	info.from = from
+	info.age_days = math.max(0, math.floor(facts.accountAge))
+	if facts.locale ~= nil and facts.locale ~= "" then
+		info.locale = facts.locale
+	end
+	if facts.verified ~= nil then
+		info.verified = facts.verified
+	end
+	if facts.membership ~= nil then
+		info.membership = facts.membership
+	end
+	return info
+end
+return {
+	wantedUserIds = wantedUserIds,
+	joinProps = joinProps,
+	PARTY_PIDS_MAX = PARTY_PIDS_MAX,
+	LAUNCH_KEEP = LAUNCH_KEEP,
+}

package/out/analytics/rows.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How built-ins outside the engine (notifications) write rows into the running server engine's events: the engine
+ * registers a writer when it starts and removes it when its generation stops (the `status.ts` pattern). Module state is
+ * fresh in every generation. Types only, so importing this loads nothing else.
+ *
+ * `target`: a Player (their session's pid / sid), a UserId (the session of that player when they are in this server;
+ * otherwise a server row without a pid: never a raw UserId in `events`), or undefined (a server row).
+ */
+export type BuiltinRowKind = "notify";
+export type BuiltinRowWriter = (target: Player | number | undefined, kind: BuiltinRowKind, name: string, props: object) => void;
+/** Registers the engine's writer; the returned function removes it again (only if it is still the registered one). */
+export declare function registerBuiltinRows(fn: BuiltinRowWriter): () => void;
+/** The running server engine's writer, or undefined when no engine runs in this generation (yet). */
+export declare function builtinRowWriter(): BuiltinRowWriter | undefined;

package/out/analytics/rows.luau

@@ -0,0 +1,29 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * How built-ins outside the engine (notifications) write rows into the running server engine's events: the engine
+	 * registers a writer when it starts and removes it when its generation stops (the `status.ts` pattern). Module state is
+	 * fresh in every generation. Types only, so importing this loads nothing else.
+	 *
+	 * `target`: a Player (their session's pid / sid), a UserId (the session of that player when they are in this server;
+	 * otherwise a server row without a pid: never a raw UserId in `events`), or undefined (a server row).
+	 
+]]
+local writer
+--* Registers the engine's writer; the returned function removes it again (only if it is still the registered one). 
+local function registerBuiltinRows(fn)
+	writer = fn
+	return function()
+		if writer == fn then
+			writer = nil
+		end
+	end
+end
+--* The running server engine's writer, or undefined when no engine runs in this generation (yet). 
+local function builtinRowWriter()
+	return writer
+end
+return {
+	registerBuiltinRows = registerBuiltinRows,
+	builtinRowWriter = builtinRowWriter,
+}

package/out/analytics/schema.d.ts

@@ -9,7 +9,7 @@ export declare const SCHEMA_VERSION = 1;
 export declare const RECORDING_CODEC = "tt-rec-1";
 /** Most bytes of the `props` JSON text. Larger props become `{"_trunc":<bytes>}`. */
 export declare const PROPS_MAX_BYTES = 4096;
-export type EventKind = "session" | "tech" | "zone" | "funnel" | "purchase" | "currency" | "state" | "experiment" | "custom" | "recording_meta" | "fleet";
+export type EventKind = "session" | "tech" | "zone" | "funnel" | "purchase" | "currency" | "state" | "experiment" | "custom" | "recording_meta" | "fleet" | "notify";
 export type DeviceKind = "desktop" | "phone" | "tablet" | "console" | "vr" | "unknown";
 /** One row of the events table. Flat; every column is always present. */
 export interface EventRow {
@@ -119,6 +119,8 @@ export interface AnalyticsSettings {
     identity?: string;
     /** basin: the token for `identity` (default: the settings' `fleet` token). Never logged. */
     identityToken?: string;
+    /** Keep the first 32 chars of the game's own launch data on the join row (`launch`); default off (`launch_len` always). */
+    joinLaunchPrefix?: boolean;
 }
 /** AnalyticsSettings with every default filled in. */
 export interface ResolvedSettings {
@@ -132,6 +134,7 @@ export interface ResolvedSettings {
     experiments: Map<string, ExperimentOverride>;
     identity?: string;
     identityToken?: string;
+    joinLaunchPrefix: boolean;
 }
 export type AnalyticsValue = string | number | boolean;
 /** Event properties: a flat JSON object (nested tables work but are harder to query). */

package/out/analytics/server.d.ts

@@ -94,6 +94,8 @@ export declare class ServerAnalytics {
     private requeueEvents;
     /** A "fleet" row (server-only, src server) on the fleet queue. */
     private emitFleet;
+    /** A built-in's row (analytics/rows.ts): on the player's session when they are here, else a server row (no pid). */
+    private builtinRow;
     /** The player's session; created now if game code is faster than the engine's own join handler. */
     sessionOf(player: Player): PlayerSession | undefined;
     /** Game code's events. `player` undefined: a server-only event (no pid). */
@@ -126,6 +128,14 @@ export declare class ServerAnalytics {
     private tellKernelPid;
     /** Kernel 0.4.0: counts this engine's own requests for the budget view (older kernels: nothing). */
     private countBudget;
+    /** A player in this server's pid (free: their session), for the join row's ref / follow / party. */
+    private pidHere;
+    /**
+     * A player not in this server: this game's record of them (one GetAsync, no retries, only with read budget to
+     * spare). undefined when unknown (never seen by this game, no budget, or the store can't be read).
+     */
+    private pidFromRecord;
+    /** The join row's join metadata (analytics/join.ts): GetJoinData, the player facts, the launch data's verdict. */
     private joinSource;
     /**
      * How many of the player's friends are in this server: one `GetFriendsAsync` per join (at most FRIEND_PAGES_MAX