@typetorch/framework 0.6.0 → 0.6.2

package/README.md

@@ -369,6 +369,9 @@ TypeTorch.runDetached(() => store.StartSessionAsync(`Player_${userId}`)).then((p
   // 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
+  // The kinds the player switched off in your settings: REPLACES their set ([] = all on), at most 32 names. The backend
+  // skips those intents whoever issued them (pref_off) and keeps them, so switching a kind back on resumes it.
+  notify.setOff(player, ["daily", "quests"]);
   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"
@@ -541,7 +544,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, joinLaunchPrefix } }` (`typetorch backend setup`) is the whole sink: DuckDB at `<url>/v1/ingest` with the one key (Basin
+recordShare, joinLaunchPrefix, joinData } }` (`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
@@ -564,6 +567,12 @@ there are no settings unless the game passes `new AnalyticsEngine({ settings })`
   Basin Pipelines Send permission, if the stream requires authentication). Without `recordings` nothing is recorded.
   The streams' schemas must match SCHEMA.md exactly: Basin drops rows that don't, silently.
 - `duckdb`: one `POST <events>` with `{"events":[...],"recordings":[...]}`, gzip, `Authorization: Bearer <token>`.
+- Join row settings (also in `backend.analytics`):
+
+  | Setting | Default | Meaning |
+  |---|---|---|
+  | `joinData` | `"full"` | `"full"`: the join row's summary props plus `jd`, a privacy-safe copy of the whole `GetJoinData()` (at most 1 KB: launch data up to 200 bytes, place / game ids, the join context as text, the TeleportData's size, type and keys but never its content, Members / referrer / followed user as pids or `"other"`, unknown fields by type; plans/30). `"summary"`: no `jd`. `"off"`: no `jd` and only the join props from before plans/29 (`from`, `ctx`, `tp`, `party`, age, prem, country, friends, ret). Anything else warns and means `"full"`. Games that put personal data in launch data should use `"summary"` |
+  | `joinLaunchPrefix` | `false` | `true`: the summary `launch` keeps the first 32 characters of the game's own launch data (`jd.LaunchData` follows `joinData`, not this) |
 - The token is write-only and never logged. Needs **Allow HTTP Requests** (Game Settings > Security). No key: the
   engine collects but keeps only the newest 1,000 rows until settings appear. Removing the key stops sending, live.
 

package/out/analytics/SCHEMA.md

@@ -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), `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 | `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); `jd?` (plans/30, with the settings' `joinData` `"full"`, the default: the raw join data, below). With `joinData` `"off"` only `from`, `ctx`, `tp`, `party`, `age`, `prem`, `country`, `friends`, `ret`, `late` are written. `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) |
@@ -162,10 +162,31 @@ 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 |
+| `joinData` | `"full"` | `"full"`: the join row carries `jd` (below); `"summary"`: no `jd`; `"off"`: no `jd` and only the pre-plans/29 join props (no pid lookups). Anything else is an error line (warned) and means `"full"`. In `backend.analytics` (or the old `analytics` value) |
 | `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).
 
+## The raw join data (`jd`, plans/30)
+
+The `session` / `join` row's `jd` prop mirrors `Player:GetJoinData()` field by field, privacy-safe, at most 1024 bytes of
+JSON (written by the framework's own encoder, so an empty table stays `{}` where the shape says object):
+
+| field | content |
+|---|---|
+| `keys` | The top-level keys Roblox returned, sorted (each cut to 32 characters) |
+| `LaunchData?`, `LaunchDataLen?` | The launch data cut to 200 bytes at a UTF-8 boundary, and its full byte length; present iff the key is |
+| `SourcePlaceId?`, `SourceGameId?` | Numbers, present iff the keys are |
+| `GameJoinContext?` | Present iff the key is: every field as text (EnumItems by name), `{}` when empty |
+| `TeleportData?` | `{ bytes?, type, keys? }`: its JSON size, type and top-level keys (at most 20, 32 characters each, sorted); never the content |
+| `Members?` | `{ count, pids? }`: each member's pid when this game knows them (players in the server, or one of the join's at most 2 budget-checked DataStore reads shared with the summary props), else `"other"`; the joining player by their own pid |
+| `ReferredByPlayerId?`, `FollowUserId?` | pid or `"other"`; absent for 0 |
+| `other?` | Any other top-level key: its type name only, never the value |
+| `trunc?` | `true` when cut to fit: TeleportData keys first (then the list), Members pids (then the list), LaunchData (shorter), GameJoinContext values (64 each), `other` |
+
+No other player's UserId is ever in `jd`. Example (Roblox dropped a notification's launch data):
+`{"keys":["GameJoinContext","LaunchData"],"LaunchData":"","LaunchDataLen":0,"GameJoinContext":{}}`.
+
 ## Transport
 
 - **basin:** `POST <events>` with a JSON array of event rows and `POST <recordings>` with a JSON array of recording

package/out/analytics/join.d.ts

@@ -55,7 +55,15 @@ export interface JoinOptions {
      * `joinLaunchPrefix`, default off: launch data can carry anything a link maker put there). `launch_len` is always kept.
      */
     launchPrefix?: boolean;
+    /**
+     * The analytics settings' `joinData` (plans/30). "off": only what the join row carried before plans/29 (`from`,
+     * `ctx`, `tp`, `party`; the engine adds age, prem, country, friends, ret). "full" / "summary": every summary prop.
+     */
+    mode?: JoinDataMode;
 }
+/** `joinData` (plans/30): "full" (default: the summary props + `jd`), "summary" (no `jd`), "off" (see JoinOptions.mode). */
+export type JoinDataMode = "full" | "summary" | "off";
+export declare const JOIN_DATA_MODES: ReadonlyArray<JoinDataMode>;
 /** Party pids kept at most. */
 export declare const PARTY_PIDS_MAX = 10;
 /** The game's own launch data: this many characters are kept. */
@@ -67,3 +75,60 @@ export declare function wantedUserIds(data: JoinDataLike | undefined, facts: Joi
  * undefined.
  */
 export declare function joinProps(data: JoinDataLike | undefined, facts: JoinFacts, pidOf: (userId: number) => string | undefined, launch: LaunchVerdict, options?: JoinOptions): Record<string, unknown>;
+/** Bytes of the `jd` JSON at most (props hold 4 KB; the join row's other props stay well under the rest). */
+export declare const JD_MAX_BYTES = 1024;
+/** LaunchData bytes kept (Roblox's own limit for launch data). */
+export declare const JD_LAUNCH_MAX = 200;
+/** TeleportData: top-level keys listed at most, and characters per key. */
+export declare const JD_TP_KEYS_MAX = 20;
+export declare const JD_KEY_CHARS = 32;
+/** GameJoinContext values are cut to this when `jd` is over the cap. */
+export declare const JD_CONTEXT_CUT = 64;
+/** `text` cut to at most `max` bytes without splitting a UTF-8 sequence. */
+export declare function cutUtf8(text: string, max: number): string;
+interface JdTeleport {
+    bytes?: number;
+    type: string;
+    keys?: string[];
+}
+interface JdMembers {
+    count: number;
+    pids?: string[];
+}
+/** The `jd` value (see plans/30-join-data-raw.md for the shape). */
+export interface JoinDataJson {
+    keys: string[];
+    LaunchData?: string;
+    LaunchDataLen?: number;
+    SourcePlaceId?: number;
+    SourceGameId?: number;
+    GameJoinContext?: Record<string, string>;
+    TeleportData?: JdTeleport;
+    Members?: JdMembers;
+    ReferredByPlayerId?: string;
+    FollowUserId?: string;
+    other?: Record<string, string>;
+    trunc?: boolean;
+}
+/**
+ * `Player:GetJoinData()` field by field, privacy-safe (plans/30): the launch data (200 bytes), place / game ids, the
+ * join context as text, the TeleportData's size, type and top-level keys (never its content), Members / referrer /
+ * followed user as pids from `pidOf` (the same lookups as the summary props) else "other", and unknown keys by type
+ * only. At most JD_MAX_BYTES of JSON as `encodeJoinData` writes it (`encode`: HttpService.JSONEncode in game, only to
+ * size the TeleportData; `quote`: a string as JSON), cut in the plan's order with `trunc`. Not a table (GetJoinData
+ * failed): undefined.
+ */
+export declare function joinDataJson(raw: unknown, followUserId: number, pidOf: (userId: number) => string | undefined, encode: (value: unknown) => string, quote: (text: string) => string): JoinDataJson | undefined;
+/**
+ * `jd` as JSON text, field order fixed. Written here rather than by HttpService.JSONEncode, which turns an empty table
+ * into `[]`: the plan's `GameJoinContext: {}` (present but empty, the evidence case) stays an object, and lists stay
+ * lists.
+ */
+export declare function encodeJoinData(jd: JoinDataJson, quote: (text: string) => string): string;
+/**
+ * Cuts `jd` to JD_MAX_BYTES of JSON, in the plan's order: TeleportData.keys (then the field), Members.pids (then the
+ * field), LaunchData (shorter), GameJoinContext values (each to 64), `other` (entry by entry); `trunc: true` once cut.
+ * Still over (an absurd join context): only `keys` (shortened), the ids, LaunchDataLen and `trunc` stay.
+ */
+export declare function capJoinData(jd: JoinDataJson, quote: (text: string) => string): JoinDataJson;
+export {};

package/out/analytics/join.luau

@@ -14,6 +14,10 @@
 --* 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. 
+--* `joinData` (plans/30): "full" (default: the summary props + `jd`), "summary" (no `jd`), "off" (see JoinOptions.mode). 
+local JOIN_DATA_MODES = { "full", "summary", "off" }
+--* The props the join row had before plans/29 (joinData "off" keeps only these from joinProps). 
+local LEGACY_PROPS = { "from", "ctx", "tp", "party" }
 --* Party pids kept at most. 
 local PARTY_PIDS_MAX = 10
 --* The game's own launch data: this many characters are kept. 
@@ -168,11 +172,427 @@ local function joinProps(data, facts, pidOf, launch, options)
 	if facts.membership ~= nil then
 		info.membership = facts.membership
 	end
+	if options.mode == "off" then
+		local legacy = {}
+		for _, name in LEGACY_PROPS do
+			if info[name] ~= nil then
+				legacy[name] = info[name]
+			end
+		end
+		return legacy
+	end
 	return info
 end
+-- The raw join data: `jd` (plans/30) -----------------------------------------------------------------------------------
+--* Bytes of the `jd` JSON at most (props hold 4 KB; the join row's other props stay well under the rest). 
+local JD_MAX_BYTES = 1024
+--* LaunchData bytes kept (Roblox's own limit for launch data). 
+local JD_LAUNCH_MAX = 200
+--* TeleportData: top-level keys listed at most, and characters per key. 
+local JD_TP_KEYS_MAX = 20
+local JD_KEY_CHARS = 32
+--* GameJoinContext values are cut to this when `jd` is over the cap. 
+local JD_CONTEXT_CUT = 64
+--* GetJoinData's keys this builder knows; anything else is reported by type only (`other`). 
+local KNOWN_KEYS = {
+	["LaunchData"] = true,
+	["SourcePlaceId"] = true,
+	["SourceGameId"] = true,
+	["GameJoinContext"] = true,
+	["TeleportData"] = true,
+	["Members"] = true,
+	["ReferredByPlayerId"] = true,
+}
+--* The value's type name: `typeof` in game (Instance, EnumItem, Vector3 ...), the Lua type under Lune. 
+local function typeName(value)
+	local _value = value
+	return typeof(_value)
+end
+--* `text` cut to at most `max` bytes without splitting a UTF-8 sequence. 
+local function cutUtf8(text, max)
+	if #text <= max then
+		return text
+	end
+	local size = math.max(0, max)
+	-- A continuation byte (10xxxxxx) right after the cut means the cut splits a character: step back to its lead byte.
+	while size > 0 do
+		local following = string.byte(text, size + 1)
+		if following == nil or bit32.band(following, 0xc0) ~= 0x80 then
+			break
+		end
+		size -= 1
+	end
+	local _text = text
+	local _size = size
+	return string.sub(_text, 1, _size)
+end
+--* A GameJoinContext field as text: EnumItems by `.Name`, strings as they are, everything else by tostring / its type. 
+local function fieldText(value)
+	local _value = value
+	if typeof(_value) == "EnumItem" then
+		return value.Name
+	end
+	local _value_1 = value
+	if type(_value_1) == "string" then
+		return value
+	end
+	local _value_2 = value
+	local _condition = type(_value_2) == "number"
+	if not _condition then
+		local _value_3 = value
+		_condition = type(_value_3) == "boolean"
+	end
+	if _condition then
+		return tostring(value)
+	end
+	return typeName(value)
+end
+local function sortedStringKeys(value)
+	local keys = {}
+	for key in pairs(value) do
+		if type(key) == "string" then
+			table.insert(keys, key)
+		end
+	end
+	table.sort(keys)
+	return keys
+end
+--* The `jd` value (see plans/30-join-data-raw.md for the shape). 
+--[[
+	*
+	 * `Player:GetJoinData()` field by field, privacy-safe (plans/30): the launch data (200 bytes), place / game ids, the
+	 * join context as text, the TeleportData's size, type and top-level keys (never its content), Members / referrer /
+	 * followed user as pids from `pidOf` (the same lookups as the summary props) else "other", and unknown keys by type
+	 * only. At most JD_MAX_BYTES of JSON as `encodeJoinData` writes it (`encode`: HttpService.JSONEncode in game, only to
+	 * size the TeleportData; `quote`: a string as JSON), cut in the plan's order with `trunc`. Not a table (GetJoinData
+	 * failed): undefined.
+	 
+]]
+local capJoinData
+local function joinDataJson(raw, followUserId, pidOf, encode, quote)
+	local _raw = raw
+	if not (type(_raw) == "table") then
+		return nil
+	end
+	local data = raw
+	local keys = {}
+	for key in pairs(data) do
+		local _arg0 = if type(key) == "string" then string.sub(key, 1, JD_KEY_CHARS) else typeName(key)
+		table.insert(keys, _arg0)
+	end
+	table.sort(keys)
+	local jd = {
+		keys = keys,
+	}
+	local mapped = function(userId)
+		local _condition = pidOf(userId)
+		if _condition == nil then
+			_condition = "other"
+		end
+		return _condition
+	end
+	local other = {}
+	local others = 0
+	for key, value in pairs(data) do
+		if not (type(key) == "string") or not (KNOWN_KEYS[key] ~= nil) then
+			other[if type(key) == "string" then string.sub(key, 1, JD_KEY_CHARS) else typeName(key)] = typeName(value)
+			others += 1
+		end
+	end
+	local launch = data.LaunchData
+	if launch ~= nil then
+		if type(launch) == "string" then
+			jd.LaunchData = cutUtf8(launch, JD_LAUNCH_MAX)
+			jd.LaunchDataLen = #launch
+		else
+			other.LaunchData = typeName(launch)
+			others += 1
+		end
+	end
+	for _, name in { "SourcePlaceId", "SourceGameId" } do
+		local value = data[name]
+		if value == nil then
+			continue
+		end
+		if type(value) == "number" then
+			jd[name] = value
+		else
+			other[name] = typeName(value)
+			others += 1
+		end
+	end
+	local context = data.GameJoinContext
+	if context ~= nil then
+		if type(context) == "table" then
+			local fields = {}
+			for name, value in pairs(context) do
+				fields[if type(name) == "string" then string.sub(name, 1, JD_KEY_CHARS) else typeName(name)] = fieldText(value)
+			end
+			jd.GameJoinContext = fields
+		else
+			other.GameJoinContext = typeName(context)
+			others += 1
+		end
+	end
+	local teleport = data.TeleportData
+	if teleport ~= nil then
+		local info = {
+			type = typeName(teleport),
+		}
+		local encodedOk, encoded = pcall(function()
+			return encode(teleport)
+		end)
+		if encodedOk and type(encoded) == "string" then
+			info.bytes = #encoded
+		end
+		if type(teleport) == "table" then
+			local names = sortedStringKeys(teleport)
+			local cut = {}
+			for _, name in names do
+				if #cut >= JD_TP_KEYS_MAX then
+					break
+				end
+				local _arg0 = string.sub(name, 1, JD_KEY_CHARS)
+				table.insert(cut, _arg0)
+			end
+			info.keys = cut
+		end
+		jd.TeleportData = info
+	end
+	local members = data.Members
+	if members ~= nil then
+		if type(members) == "table" then
+			local pids = {}
+			local count = 0
+			for _, member in pairs(members) do
+				count += 1
+				local _arg0 = if type(member) == "number" then mapped(member) else "other"
+				table.insert(pids, _arg0)
+			end
+			jd.Members = {
+				count = count,
+				pids = pids,
+			}
+		else
+			other.Members = typeName(members)
+			others += 1
+		end
+	end
+	local referrer = data.ReferredByPlayerId
+	if type(referrer) == "number" then
+		if referrer > 0 then
+			jd.ReferredByPlayerId = mapped(referrer)
+		end
+	elseif referrer ~= nil then
+		other.ReferredByPlayerId = typeName(referrer)
+		others += 1
+	end
+	if followUserId > 0 then
+		jd.FollowUserId = mapped(followUserId)
+	end
+	if others > 0 then
+		jd.other = other
+	end
+	return capJoinData(jd, quote)
+end
+local function jsonNumber(value)
+	if value == value and value % 1 == 0 and math.abs(value) < 2 ^ 53 then
+		return string.format("%d", value)
+	end
+	return if value == value and math.abs(value) ~= math.huge then string.format("%.17g", value) else "null"
+end
+local function jsonStrings(list, quote)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#list)
+	local _callback = function(item)
+		return quote(item)
+	end
+	for _k, _v in list do
+		_newValue[_k] = _callback(_v, _k - 1, list)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	return `[{table.concat(_newValue, ",")}]`
+end
+local function jsonObject(value, quote)
+	local names = sortedStringKeys(value)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#names)
+	local _callback = function(name)
+		return `{quote(name)}:{quote(value[name])}`
+	end
+	for _k, _v in names do
+		_newValue[_k] = _callback(_v, _k - 1, names)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	return `\{{table.concat(_newValue, ",")}\}`
+end
+--[[
+	*
+	 * `jd` as JSON text, field order fixed. Written here rather than by HttpService.JSONEncode, which turns an empty table
+	 * into `[]`: the plan's `GameJoinContext: {}` (present but empty, the evidence case) stays an object, and lists stay
+	 * lists.
+	 
+]]
+local function encodeJoinData(jd, quote)
+	local parts = {}
+	local _arg0 = `"keys":{jsonStrings(jd.keys, quote)}`
+	table.insert(parts, _arg0)
+	if jd.LaunchData ~= nil then
+		local _arg0_1 = `"LaunchData":{quote(jd.LaunchData)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.LaunchDataLen ~= nil then
+		local _arg0_1 = `"LaunchDataLen":{jsonNumber(jd.LaunchDataLen)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.SourcePlaceId ~= nil then
+		local _arg0_1 = `"SourcePlaceId":{jsonNumber(jd.SourcePlaceId)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.SourceGameId ~= nil then
+		local _arg0_1 = `"SourceGameId":{jsonNumber(jd.SourceGameId)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.GameJoinContext ~= nil then
+		local _arg0_1 = `"GameJoinContext":{jsonObject(jd.GameJoinContext, quote)}`
+		table.insert(parts, _arg0_1)
+	end
+	local teleport = jd.TeleportData
+	if teleport ~= nil then
+		local fields = {}
+		if teleport.bytes ~= nil then
+			local _arg0_1 = `"bytes":{jsonNumber(teleport.bytes)}`
+			table.insert(fields, _arg0_1)
+		end
+		local _arg0_1 = `"type":{quote(teleport.type)}`
+		table.insert(fields, _arg0_1)
+		if teleport.keys ~= nil then
+			local _arg0_2 = `"keys":{jsonStrings(teleport.keys, quote)}`
+			table.insert(fields, _arg0_2)
+		end
+		local _arg0_2 = `"TeleportData":\{{table.concat(fields, ",")}\}`
+		table.insert(parts, _arg0_2)
+	end
+	local members = jd.Members
+	if members ~= nil then
+		local pids = if members.pids ~= nil then `,"pids":{jsonStrings(members.pids, quote)}` else ""
+		local _arg0_1 = `"Members":\{"count":{jsonNumber(members.count)}{pids}\}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.ReferredByPlayerId ~= nil then
+		local _arg0_1 = `"ReferredByPlayerId":{quote(jd.ReferredByPlayerId)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.FollowUserId ~= nil then
+		local _arg0_1 = `"FollowUserId":{quote(jd.FollowUserId)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.other ~= nil then
+		local _arg0_1 = `"other":{jsonObject(jd.other, quote)}`
+		table.insert(parts, _arg0_1)
+	end
+	if jd.trunc == true then
+		local _arg0_1 = `"trunc":true`
+		table.insert(parts, _arg0_1)
+	end
+	return `\{{table.concat(parts, ",")}\}`
+end
+--[[
+	*
+	 * Cuts `jd` to JD_MAX_BYTES of JSON, in the plan's order: TeleportData.keys (then the field), Members.pids (then the
+	 * field), LaunchData (shorter), GameJoinContext values (each to 64), `other` (entry by entry); `trunc: true` once cut.
+	 * Still over (an absurd join context): only `keys` (shortened), the ids, LaunchDataLen and `trunc` stay.
+	 
+]]
+function capJoinData(jd, quote)
+	local bytes = function()
+		return #encodeJoinData(jd, quote)
+	end
+	local over = function()
+		return bytes() > JD_MAX_BYTES
+	end
+	if not over() then
+		return jd
+	end
+	jd.trunc = true
+	local teleport = jd.TeleportData
+	if teleport and teleport.keys then
+		while #teleport.keys > 0 and over() do
+			local _exp = teleport.keys
+			_exp[#_exp] = nil
+		end
+		if over() then
+			teleport.keys = nil
+		end
+	end
+	local members = jd.Members
+	if members and members.pids and over() then
+		while #members.pids > 0 and over() do
+			local _exp = members.pids
+			_exp[#_exp] = nil
+		end
+		if over() then
+			members.pids = nil
+		end
+	end
+	if jd.LaunchData ~= nil and over() then
+		local size = #jd.LaunchData
+		while size > 0 and over() do
+			size = math.max(0, size - math.max(8, math.min(64, bytes() - JD_MAX_BYTES)))
+			jd.LaunchData = cutUtf8(jd.LaunchData, size)
+			size = #jd.LaunchData
+		end
+	end
+	local context = jd.GameJoinContext
+	if context and over() then
+		for name, value in pairs(context) do
+			context[name] = cutUtf8(value, JD_CONTEXT_CUT)
+		end
+	end
+	local other = jd.other
+	if other and over() then
+		for name in pairs(other) do
+			if not over() then
+				break
+			end
+			other[name] = nil
+		end
+		if (next(other)) == nil then
+			jd.other = nil
+		end
+	end
+	if not over() then
+		return jd
+	end
+	local minimal = {
+		keys = {},
+		LaunchDataLen = jd.LaunchDataLen,
+		SourcePlaceId = jd.SourcePlaceId,
+		SourceGameId = jd.SourceGameId,
+		trunc = true,
+	}
+	for _, key in jd.keys do
+		if #minimal.keys >= 16 then
+			break
+		end
+		local _exp = minimal.keys
+		table.insert(_exp, key)
+	end
+	return minimal
+end
 return {
 	wantedUserIds = wantedUserIds,
 	joinProps = joinProps,
+	cutUtf8 = cutUtf8,
+	joinDataJson = joinDataJson,
+	encodeJoinData = encodeJoinData,
+	capJoinData = capJoinData,
+	JOIN_DATA_MODES = JOIN_DATA_MODES,
 	PARTY_PIDS_MAX = PARTY_PIDS_MAX,
 	LAUNCH_KEEP = LAUNCH_KEEP,
+	JD_MAX_BYTES = JD_MAX_BYTES,
+	JD_LAUNCH_MAX = JD_LAUNCH_MAX,
+	JD_TP_KEYS_MAX = JD_TP_KEYS_MAX,
+	JD_KEY_CHARS = JD_KEY_CHARS,
+	JD_CONTEXT_CUT = JD_CONTEXT_CUT,
 }

package/out/analytics/schema.d.ts

@@ -121,6 +121,11 @@ export interface AnalyticsSettings {
     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;
+    /**
+     * plans/30: "full" (default: the join row's summary props and `jd`, the raw join data privacy-safe), "summary" (no
+     * `jd`), "off" (no `jd` and only the join props from before plans/29). Anything else warns and means "full".
+     */
+    joinData?: "full" | "summary" | "off";
 }
 /** AnalyticsSettings with every default filled in. */
 export interface ResolvedSettings {
@@ -135,6 +140,7 @@ export interface ResolvedSettings {
     identity?: string;
     identityToken?: string;
     joinLaunchPrefix: boolean;
+    joinData: "full" | "summary" | "off";
 }
 export type AnalyticsValue = string | number | boolean;
 /** Event properties: a flat JSON object (nested tables work but are harder to query). */