@typetorch/framework 0.5.0 → 0.5.2

package/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2026 TypeTorch contributors
-Copyright (c) 2021 Flamework (src/reflection: the Reflect and Modding runtime, adapted from @flamework/core)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 TypeTorch contributors
+Copyright (c) 2021 Flamework (src/reflection: the Reflect and Modding runtime, adapted from @flamework/core)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -427,7 +427,7 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   row carries a UserId.
 - **Identities** (option `identity`, default on): once the pid is known, one row `{ pid, uid, t }` (the UserId, nothing
   else) per session goes to the dev's own server only, never into the events: duckdb games in the batch body, Basin
-  games to the fleet API (the settings' `fleet` url + `/v1/identity`, or the `identity` / `identityToken` settings). The
+  games to the backend (the record's `backend` 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.
@@ -465,8 +465,9 @@ count affected players by pid, never by name) and counts its own DataStore and H
 menu **Server > Budget**: bars per Roblox limit for the player count, who spends it, the DataStore budget left, memory).
 
 **Settings** (server only, never sent to clients): the signed settings record's `analytics` field (kernel 0.3.8,
-plans/20), written with `typetorch settings set analytics -` (JSON on stdin; `@typetorch/analytics`' `writeSettings()`
-and `bun run local` call it). Every new copy applies live within seconds (the CLI pings servers). Before kernel 0.3.8
+plans/20), derived from `backend` by `typetorch backend setup` (`writeBackendSettings()` in `@typetorch/backend` runs it, and
+`bun run local` too). Every new copy applies live within seconds (the CLI pings servers). A Basin sink has no CLI writer
+since CLI 0.9: `backend setup` replaces it. Before kernel 0.3.8
 there are no settings unless the game passes `new AnalyticsEngine({ settings })`:
 
 ```json

package/out/analytics/SCHEMA.md

@@ -142,7 +142,7 @@ repo's `bun run local` does it). Every new signed copy applies at once, so dials
   "flushSeconds": 15,
   "recordShare": 1,
   "techEvery": 60,
-  "experiments": { "onboarding": { "active": true, "weights": [1, 1], "variant": "short" } }
+  "experiments": { "onboarding": { "active": true, "weights": [1, 1], "variant": "short", "players": { "123456": "long" } } }
 }
 ```
 
@@ -155,7 +155,7 @@ repo's `bun run local` does it). Every new signed copy applies at once, so dials
 | `flushSeconds` | 15 | 5..300 |
 | `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) |
+| `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 |
 

package/out/analytics/experiments.d.ts

@@ -19,10 +19,16 @@ export interface Assignment {
 /**
  * The variant of experiment `name` for player `pid`. The first variant is the control: everyone gets it while the
  * experiment is switched off (`active: false`). `weights` split players unevenly (`[9, 1]`: 10% get the second);
- * `variant` forces one for everyone. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
+ * `variant` forces one for everyone; `player` (one player's entry of `players`, see `playerOverride`) forces one for
+ * this player and wins over the rest. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
  * players as possible.
  */
 export declare function assignVariant(pid: string, name: string, variants: string[], override?: ExperimentOverride): Assignment;
+/**
+ * One player's view of an override: `players` resolved to `player` (by UserId, else pid) and dropped, so a client's
+ * hello never carries other players' ids.
+ */
+export declare function playerOverride(override: ExperimentOverride | undefined, userId: number | undefined, pid: string): ExperimentOverride | undefined;
 /** Whether player `pid` is in the recorded share (0..1) of new players. Stable per player. */
 export declare function inShare(pid: string, share: number): boolean;
 /** A valid experiment name: 1-64 chars, letters, digits, `_`, `-`, `.`, `/`. */

package/out/analytics/experiments.luau

@@ -44,7 +44,8 @@ end
 	*
 	 * The variant of experiment `name` for player `pid`. The first variant is the control: everyone gets it while the
 	 * experiment is switched off (`active: false`). `weights` split players unevenly (`[9, 1]`: 10% get the second);
-	 * `variant` forces one for everyone. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
+	 * `variant` forces one for everyone; `player` (one player's entry of `players`, see `playerOverride`) forces one for
+	 * this player and wins over the rest. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
 	 * players as possible.
 	 
 ]]
@@ -61,6 +62,18 @@ local function assignVariant(pid, name, variants, override)
 			forced = false,
 		}
 	end
+	local _mine = override
+	if _mine ~= nil then
+		_mine = _mine.player
+	end
+	local mine = _mine
+	if type(mine) == "string" and table.find(variants, mine) ~= nil then
+		return {
+			variant = mine,
+			active = true,
+			forced = true,
+		}
+	end
 	local _result = override
 	if _result ~= nil then
 		_result = _result.active
@@ -129,6 +142,34 @@ local function assignVariant(pid, name, variants, override)
 		forced = false,
 	}
 end
+--[[
+	*
+	 * One player's view of an override: `players` resolved to `player` (by UserId, else pid) and dropped, so a client's
+	 * hello never carries other players' ids.
+	 
+]]
+local function playerOverride(override, userId, pid)
+	if override == nil then
+		return nil
+	end
+	local result = {
+		active = override.active,
+		weights = override.weights,
+		variant = override.variant,
+	}
+	local players = override.players
+	if players ~= nil then
+		local _condition = (if userId ~= nil then players[tostring(userId)] else nil)
+		if _condition == nil then
+			_condition = players[pid]
+		end
+		local mine = _condition
+		if mine ~= nil then
+			result.player = mine
+		end
+	end
+	return result
+end
 --* Whether player `pid` is in the recorded share (0..1) of new players. Stable per player. 
 local function inShare(pid, share)
 	if share >= 1 then
@@ -182,6 +223,7 @@ return {
 	hash32 = hash32,
 	unitHash = unitHash,
 	assignVariant = assignVariant,
+	playerOverride = playerOverride,
 	inShare = inShare,
 	isExperimentName = isExperimentName,
 	isVariantList = isVariantList,

package/out/analytics/schema.d.ts

@@ -86,6 +86,13 @@ export interface ExperimentOverride {
     weights?: number[];
     /** Everyone gets this variant (must be one of the game's variants). */
     variant?: string;
+    /**
+     * Per-player forced variants, keyed by UserId (`"123456"`) or pid (32 hex): wins over `active`, `variant` and
+     * `weights` for that player (QA, support). Server-only: a client gets only its own entry, as `player`.
+     */
+    players?: Record<string, string>;
+    /** This player's forced variant (resolved from `players` by `playerOverride`; what a client's hello carries). */
+    player?: string;
 }
 /** The sink settings: the signed settings' `analytics` (kernel 0.3.8, server-only), or `new AnalyticsEngine({ settings })`. */
 export interface AnalyticsSettings {

package/out/analytics/server.d.ts

@@ -101,6 +101,7 @@ export declare class ServerAnalytics {
     /** Activity: per player, or server-wide (every player without their own) when `player` is undefined. */
     setActivity(player: Player | undefined, activity: string | undefined): void;
     setScreen(session: PlayerSession, screen: string, src: "server" | "client", t?: number, props?: string): void;
+    /** The overrides as this player sees them (their own `players` entry only; hello). */
     private overrides;
     /** The player's variant (stamped on their later events while active). May yield until the player's pid loads. */
     experiment(player: Player, name: string, variants: string[]): string;

package/out/analytics/server.luau

@@ -28,6 +28,7 @@ local assignVariant = _experiments.assignVariant
 local inShare = _experiments.inShare
 local isExperimentName = _experiments.isExperimentName
 local isVariantList = _experiments.isVariantList
+local playerOverride = _experiments.playerOverride
 local _protocol = TS.import(script, script.Parent, "protocol")
 local CHANNEL = _protocol.CHANNEL
 local CHUNK_MAX_BYTES = _protocol.CHUNK_MAX_BYTES
@@ -586,11 +587,11 @@ do
 		end
 		_self:emit(_exp, "state", "screen", _condition, src, t)
 	end
-	function ServerAnalytics:overrides()
+	function ServerAnalytics:overrides(player, session)
 		local result = {}
 		if self.settings then
 			for name, override in self.settings.experiments do
-				result[name] = override
+				result[name] = playerOverride(override, player.UserId, session.pid)
 			end
 		end
 		return result
@@ -602,7 +603,7 @@ do
 		end
 		local control = _condition
 		if not isExperimentName(name) or not isVariantList(variants) then
-			warn("[src/analytics/server.ts:522]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
+			warn("[src/analytics/server.ts:523]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
 			return control
 		end
 		local session = self:sessionOf(player)
@@ -641,7 +642,7 @@ do
 			local _name_1 = name
 			_result = _experiments_1[_name_1]
 		end
-		local assignment = assignVariant(_exp_1, _exp_2, _exp_3, _result)
+		local assignment = assignVariant(_exp_1, _exp_2, _exp_3, playerOverride(_result, player.UserId, session.pid))
 		local _exp_4 = session.exp
 		local _name_1 = name
 		local current = _exp_4[_name_1]
@@ -667,7 +668,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:557]", `[analytics] the sink settings (settings.backend or settings.analytics): {errorsText}`)
+			warn("[src/analytics/server.ts:558]", `[analytics] the sink settings (settings.backend or settings.analytics): {errorsText}`)
 		end
 		self.settingsErrors = parsed.errors
 		local hadSettings = self.settings ~= nil
@@ -697,7 +698,7 @@ do
 		-- `new AnalyticsEngine({ settings })`.
 		if not settingsSupported() then
 			if self.kernel ~= nil and self.kernel.test ~= true then
-				warn("[src/analytics/server.ts:584]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch backend setup"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
+				warn("[src/analytics/server.ts:585]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch backend setup"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
 			end
 			self.settingsTried = true
 			return nil
@@ -1273,7 +1274,7 @@ do
 			_condition = DEFAULT_TECH_EVERY
 		end
 		_object[_left] = _condition
-		_object.exps = self:overrides()
+		_object.exps = self:overrides(player, session)
 		local hello = _object
 		dispatcher.kernel:send(player, CHANNEL, "hi", hello)
 	end
@@ -1499,7 +1500,7 @@ do
 				end
 			end)
 			if not ok then
-				warn("[src/analytics/server.ts:1077]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
+				warn("[src/analytics/server.ts:1078]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
 			end
 		end)
 		self.trove:add(function()
@@ -1782,7 +1783,7 @@ do
 		self.lastWarnAt = now
 		local more = if self.suppressed > 0 then ` (+{self.suppressed} more in the last minute)` else ""
 		self.suppressed = 0
-		warn("[src/analytics/server.ts:1272]", `[analytics] {message}{more}`)
+		warn("[src/analytics/server.ts:1273]", `[analytics] {message}{more}`)
 		return true
 	end
 	function ServerAnalytics:noteSuccess()

package/out/analytics/settings.d.ts

@@ -13,6 +13,8 @@ export interface ParsedSettings {
     settings?: ResolvedSettings;
     errors: string[];
 }
+/** Per-player overrides one experiment may hold (`players`). */
+export declare const EXPERIMENT_PLAYERS_MAX = 200;
 /**
  * Reads the settings value: a table (the configs API stores JSON objects) or a JSON string. `undefined` (no key) gives
  * no settings and no errors. Unknown fields are ignored.

package/out/analytics/settings.luau

@@ -35,6 +35,19 @@ local function clampNumber(value, fallback, low, high, label, errors)
 	end
 	return math.clamp(value, low, high)
 end
+--* Per-player overrides one experiment may hold (`players`). 
+local EXPERIMENT_PLAYERS_MAX = 200
+--* A `players` key: a UserId (digits) or a pid (32 lowercase hex). 
+local function isPlayerKey(key)
+	local _key = key
+	if not (type(_key) == "string") then
+		return false
+	end
+	if #key >= 1 and #key <= 19 and (string.match(key, "^%d+$")) ~= nil then
+		return true
+	end
+	return #key == 32 and (string.match(key, "^[0-9a-f]+$")) ~= nil
+end
 local function parseExperiments(value, errors)
 	local result = {}
 	if value == nil then
@@ -103,6 +116,29 @@ local function parseExperiments(value, errors)
 				table.insert(_errors, _arg0)
 			end
 		end
+		if entry.players ~= nil then
+			local players = {}
+			local _players = entry.players
+			local ok = type(_players) == "table"
+			local count = 0
+			if ok then
+				for key, variant in pairs(entry.players) do
+					count += 1
+					if not isPlayerKey(key) or not (type(variant) == "string") or #variant < 1 or #variant > 32 then
+						ok = false
+					else
+						players[key] = variant
+					end
+				end
+			end
+			if ok and count <= EXPERIMENT_PLAYERS_MAX then
+				override.players = players
+			else
+				local _errors = errors
+				local _arg0 = `experiments.{name}.players must map UserIds or pids to variant names (at most {EXPERIMENT_PLAYERS_MAX})`
+				table.insert(_errors, _arg0)
+			end
+		end
 		result[name] = override
 	end
 	return result
@@ -326,4 +362,5 @@ return {
 	recordsSupported = recordsSupported,
 	DEFAULT_FLUSH_SECONDS = DEFAULT_FLUSH_SECONDS,
 	DEFAULT_TECH_EVERY = DEFAULT_TECH_EVERY,
+	EXPERIMENT_PLAYERS_MAX = EXPERIMENT_PLAYERS_MAX,
 }

package/out/devtools/client.d.ts

@@ -5,9 +5,4 @@ export interface DevtoolsClient {
     /** Call once the client generation is up (all modules started). */
     readonly started: () => void;
 }
-/**
- * Starts the dev menu for this client generation. Everything it creates or connects lives in `trove`, so a swap
- * removes it; the open state, tab, sub-tab, window rectangle and options survive the swap through the kernel persist
- * store.
- */
 export declare function startDevtoolsClient(kernel: ClientKernel, dispatcher: ClientDispatcher, trove: Trove): DevtoolsClient;

package/out/devtools/client.luau

@@ -467,6 +467,52 @@ local function shareableLogs(entries)
 	return ordered
 end
 -- The menu ----------------------------------------------------------------------------------------------------------
+--[[
+	*
+	 * The channel in a Builds group heading: the branch's own channel, not its newest artifact's. A promoted prod artifact
+	 * keeps channel "prod" on a dev branch, and the heading used to say "(prod)" until the next dev deploy flipped it back.
+	 * This server's branch: `branchChannel` from its status (kernel 0.3.9); another branch: the branch list's
+	 * `branchChannel` (kernel 0.5.2), else its `channel`. "dev, prod artifact" when the newest artifact differs.
+	 
+]]
+local function buildsHeadingChannel(branchName, artifactChannel, branches, status)
+	local channel
+	if status ~= nil and status.branch == branchName and status.branchChannel ~= nil then
+		channel = status.branchChannel
+	end
+	if channel == nil then
+		-- ▼ ReadonlyArray.find ▼
+		local _callback = function(branch)
+			return branch.name == branchName
+		end
+		local _result
+		for _i, _v in branches do
+			if _callback(_v, _i - 1, branches) == true then
+				_result = _v
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.find ▲
+		local info = _result
+		local _result_1 = info
+		if _result_1 ~= nil then
+			_result_1 = _result_1.branchChannel
+		end
+		local _condition = _result_1
+		if _condition == nil then
+			local _result_2 = info
+			if _result_2 ~= nil then
+				_result_2 = _result_2.channel
+			end
+			_condition = _result_2
+		end
+		channel = _condition
+	end
+	if channel == nil or channel == artifactChannel then
+		return artifactChannel
+	end
+	return `{channel}, {artifactChannel} artifact`
+end
 --[[
 	*
 	 * Kernel 0.3.9: "dev" for a dev branch, plus the rules when they are stricter ("dev (prod rules)": a dev branch on a
@@ -488,7 +534,36 @@ end
 	 * store.
 	 
 ]]
+local DEV_GUI_NAME = "TypeTorchDev"
+--* The client generation that built a dev menu gui (an attribute on the ScreenGui). 
+local DEV_GUI_GENERATION = "TypeTorchGeneration"
+--[[
+	*
+	 * Destroys dev menus an older generation left behind. Its trove should have removed them, but a generation whose stop
+	 * was cut short (a throwing cleanup, before framework 0.5.2) left its menu on screen, dead, over the new one.
+	 * Menus without the attribute come from a framework before 0.5.2: always older, since this generation hasn't built one.
+	 
+]]
+local function sweepStaleMenus(playerGui, generation)
+	for _, child in playerGui:GetChildren() do
+		if child.Name ~= DEV_GUI_NAME or not child:IsA("ScreenGui") then
+			continue
+		end
+		local built = child:GetAttribute(DEV_GUI_GENERATION)
+		if type(built) == "number" and built >= generation then
+			continue
+		end
+		pcall(function()
+			return child:Destroy()
+		end)
+	end
+end
 local function startDevtoolsClient(kernel, dispatcher, trove)
+	-- Before anything else, so a leaked menu goes away even for players who never get the dev menu.
+	local startGui = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui")
+	if startGui then
+		sweepStaleMenus(startGui, kernel.generation)
+	end
 	local state = kernel:persist(PERSIST_KEY, function()
 		return {
 			open = false,
@@ -664,7 +739,7 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 					-- picks the file up on its PC).
 					local _devGui = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui")
 					if _devGui ~= nil then
-						_devGui = _devGui:FindFirstChild("TypeTorchDev")
+						_devGui = _devGui:FindFirstChild(DEV_GUI_NAME)
 					end
 					local devGui = _devGui
 					local taken = takeScreenshot(if devGui ~= nil and devGui:IsA("ScreenGui") then { devGui } else {})
@@ -2080,7 +2155,7 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 			end
 			for _, branchName in order do
 				local group = groups[branchName]
-				local heading = body:text(`{branchName}  ({group[1].channel})`, COLORS.text)
+				local heading = body:text(`{branchName}  ({buildsHeadingChannel(branchName, group[1].channel, data.branches, status)})`, COLORS.text)
 				heading.Font = Enum.Font.BuilderSansBold
 				local showAll = expanded[branchName] ~= nil
 				-- ▼ ReadonlyArray.forEach ▼
@@ -2472,7 +2547,7 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 			})
 		end)
 		if not ok then
-			warn("[src/devtools/client.ts:1725]", `[devtools] {key} tab failed: {err}`)
+			warn("[src/devtools/client.ts:1768]", `[devtools] {key} tab failed: {err}`)
 			page:text(`This tab failed: {err}`, COLORS.bad)
 		end
 	end
@@ -2543,13 +2618,15 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 	local open
 	local build = function()
 		local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
+		sweepStaleMenus(playerGui, kernel.generation)
 		local gui = trove:add(make("ScreenGui", {
-			Name = "TypeTorchDev",
+			Name = DEV_GUI_NAME,
 			ResetOnSpawn = false,
 			DisplayOrder = DEV_MENU_DISPLAY_ORDER,
 			IgnoreGuiInset = true,
 			ZIndexBehavior = Enum.ZIndexBehavior.Sibling,
 		}))
+		gui:SetAttribute(DEV_GUI_GENERATION, kernel.generation)
 		local toggle = style(make("TextButton", {
 			Name = "Toggle",
 			AutoButtonColor = true,
@@ -3077,7 +3154,7 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 					return playReloadSound()
 				end)
 				if not ok then
-					warn("[src/devtools/client.ts:2144]", `[devtools] reload sound failed: {err}`)
+					warn("[src/devtools/client.ts:2189]", `[devtools] reload sound failed: {err}`)
 				end
 			end))
 		end,

package/out/devtools/health.d.ts

@@ -2,7 +2,7 @@ import type { AnalyticsStats } from "../analytics/schema";
 import type { AssetFacts } from "../assets/manifest";
 import type { DetachedStatus, ErrorReportsStatus, FleetSenderInfo, HealthInfo, KernelStatus, PerfSummary, SettingsStatus } from "../kernel";
 /** The newest kernel this framework release knows about. Bump it with every kernel release. */
-export declare const LATEST_KERNEL = "0.4.2";
+export declare const LATEST_KERNEL = "0.5.1";
 /**
  * The live health window while it is open (kernel 0.3.7 thresholds; older kernels: 3): "1/3 errors, 24 s left", plus
  * ", no rollback" when a failure would only mark the server degraded. Undefined once the window closed.

package/out/devtools/health.luau

@@ -2,7 +2,7 @@
 local TS = _G[script]
 local describeFleetError = TS.import(script, script.Parent.Parent, "analytics", "hints").describeFleetError
 --* The newest kernel this framework release knows about. Bump it with every kernel release. 
-local LATEST_KERNEL = "0.4.2"
+local LATEST_KERNEL = "0.5.1"
 --* Kernels before 0.3.7 use fixed thresholds: 3 errors within 30 s of ready roll back. 
 local OLD_HEALTH_ERRORS = 3
 local OLD_HEALTH_WINDOW = 30

package/out/kernel.d.ts

@@ -353,7 +353,10 @@ export interface ArtifactEntry {
 }
 export interface BranchInfo {
     name: string;
+    /** The head artifact's channel when the settings don't configure the branch (a promoted prod build: "prod"). */
     channel: Channel;
+    /** Kernel 0.5.2: what the branch is ("prod": the default branch or one configured prod; else "dev"). */
+    branchChannel?: Channel;
     artifactId?: string;
     /** Kernel 0.2+. */
     assetId?: number;

package/out/runtime/safe-clean.d.ts

@@ -0,0 +1,11 @@
+import type { Trove } from "@rbxts/trove";
+/**
+ * `trove.clean()`, but every object is cleaned in its own pcall: a cleanup that throws warns (`<label> cleanup threw`)
+ * and the rest still run. `trove.clean()` stops at the first error and leaves the trove stuck "cleaning", so one
+ * `trove.remove(x)` inside a cleanup ("Cannot call trove.remove() while cleaning") used to abort the whole generation
+ * stop: later modules' troves, the network and the dev menu stayed alive. Child troves (`trove.extend()`) are swept the
+ * same way. Falls back to a pcalled `trove.clean()` for a trove it doesn't recognize.
+ */
+export declare function cleanTrove(trove: Trove, label: string): void;
+/** Runs one step of a generation stop; a step that throws warns and the stop goes on. */
+export declare function stopStep(label: string, step: () => void): void;

package/out/runtime/safe-clean.luau

@@ -0,0 +1,57 @@
+-- Compiled with roblox-ts v3.0.0
+--* The parts of @rbxts/trove 1.x that `trove.clean()` uses; read so one throwing cleanup can't skip the rest. 
+--[[
+	*
+	 * `trove.clean()`, but every object is cleaned in its own pcall: a cleanup that throws warns (`<label> cleanup threw`)
+	 * and the rest still run. `trove.clean()` stops at the first error and leaves the trove stuck "cleaning", so one
+	 * `trove.remove(x)` inside a cleanup ("Cannot call trove.remove() while cleaning") used to abort the whole generation
+	 * stop: later modules' troves, the network and the dev menu stayed alive. Child troves (`trove.extend()`) are swept the
+	 * same way. Falls back to a pcalled `trove.clean()` for a trove it doesn't recognize.
+	 
+]]
+local function cleanTrove(trove, label)
+	local internals = trove
+	local objects = internals.objects
+	local cleanupObj = internals.cleanupObj
+	if not (type(objects) == "table") or not (type(cleanupObj) == "function") then
+		local ok, err = pcall(function()
+			return trove:clean()
+		end)
+		if not ok then
+			warn("[src/runtime/safe-clean.ts:28]", `{label} cleanup threw: {err}`)
+		end
+		return nil
+	end
+	-- Already being cleaned further up the stack (a cleanup that cleans its own trove): leave it to that clean.
+	if internals.cleaning == true then
+		return nil
+	end
+	internals.cleaning = true
+	local troveClass = getmetatable(trove)
+	for _, track in objects do
+		local obj = track.obj
+		local ok, err = pcall(function()
+			if type(obj) == "table" and getmetatable(obj) == troveClass then
+				cleanTrove(obj, label)
+			else
+				cleanupObj(internals, track)
+			end
+		end)
+		if not ok then
+			warn("[src/runtime/safe-clean.ts:41]", `{label} cleanup threw: {err}`)
+		end
+	end
+	table.clear(objects)
+	internals.cleaning = false
+end
+--* Runs one step of a generation stop; a step that throws warns and the stop goes on. 
+local function stopStep(label, step)
+	local ok, err = pcall(step)
+	if not ok then
+		warn("[src/runtime/safe-clean.ts:50]", `TypeTorch stop: {label} threw: {err}`)
+	end
+end
+return {
+	cleanTrove = cleanTrove,
+	stopStep = stopStep,
+}

package/out/runtime/start.luau

@@ -36,6 +36,9 @@ local _registry = TS.import(script, script.Parent, "registry")
 local persistKeys = _registry.persistKeys
 local registered = _registry.registered
 local runningModules = _registry.runningModules
+local _safe_clean = TS.import(script, script.Parent, "safe-clean")
+local cleanTrove = _safe_clean.cleanTrove
+local stopStep = _safe_clean.stopStep
 local function has(instance, method)
 	local _arg0 = instance[method]
 	return type(_arg0) == "function"
@@ -305,14 +308,29 @@ local function start(realm, kernel, options)
 					return (running.instance):onStop()
 				end)
 				if not ok then
-					warn("[src/runtime/start.ts:205]", `{running.name}.onStop threw: {err}`)
+					warn("[src/runtime/start.ts:206]", `{running.name}.onStop threw: {err}`)
 				end
 			end
-			root:remove(running.trove)
+			-- Object by object, each pcalled: a cleanup that throws (e.g. trove.remove inside a cleanup) can't skip the
+			-- rest of this module, the modules after it, or the rest of the stop.
+			cleanTrove(running.trove, running.name)
+			stopStep(`{running.name} trove`, function()
+				return root:remove(running.trove)
+			end)
 		end
 		table.clear(runningModules)
 		setModulePhase("stopped")
 	end
+	--* Every step runs even when an earlier one throws (each warns), so a bad cleanup can't keep a dead generation alive. 
+	local stopGeneration = function()
+		stopStep("stopping modules", stopModules)
+		stopStep("stopping the network", stopNetwork)
+		stopStep("unbinding TypeTorch", unbindTypeTorch)
+		cleanTrove(root, "TypeTorch generation")
+		stopStep("destroying the generation trove", function()
+			return root:destroy()
+		end)
+	end
 	setModulePhase("constructing")
 	local initialized, initError = pcall(function()
 		for _, mod in ordered do
@@ -377,10 +395,7 @@ local function start(realm, kernel, options)
 		end
 	end)
 	if not initialized then
-		stopModules()
-		stopNetwork()
-		unbindTypeTorch()
-		root:destroy()
+		stopGeneration()
 		error(`TypeTorch {realm} failed to start: {initError}`, 0)
 	end
 	for _, running in runningModules do
@@ -446,14 +461,13 @@ local function start(realm, kernel, options)
 		_result()
 	end
 	startedTypeTorch()
-	print("[src/runtime/start.ts:296]", `TypeTorch {realm} started {#runningModules} modules in {math.floor((os.clock() - startedAt) * 1000)} ms (artifact {kernel.artifact.id}, generation {kernel.generation})`)
+	print("[src/runtime/start.ts:305]", `TypeTorch {realm} started {#runningModules} modules in {math.floor((os.clock() - startedAt) * 1000)} ms (artifact {kernel.artifact.id}, generation {kernel.generation})`)
 	return function(info)
 		-- TypeTorch.onSwapOut first, while every module still runs (so they can save into persist).
-		swapOutTypeTorch(info)
-		stopModules()
-		stopNetwork()
-		unbindTypeTorch()
-		root:destroy()
+		stopStep("onSwapOut", function()
+			return swapOutTypeTorch(info)
+		end)
+		stopGeneration()
 	end
 end
 --* Call from the game's `src/server/boot.ts`: `export function boot(kernel) { return startServer(kernel, {...}) }`. 

package/out/settings.luau

@@ -168,13 +168,14 @@ do
 		if _result == "client" then
 			error(`TypeTorch.liveConfig("{self.key}") is server-only`, 2)
 		end
+		-- `typetorch test --cloud` runs a stub kernel with no signed settings at all: the default is expected there.
 		local _result_1 = current
 		if _result_1 ~= nil then
 			_result_1 = _result_1.kernel
 		end
 		local _condition = _result_1 ~= nil
 		if _condition then
-			_condition = not settingsSupported()
+			_condition = current.kernel.test ~= true and not settingsSupported()
 		end
 		if _condition then
 			warnOnce(`old:{self.key}`, `TypeTorch.liveConfig("{self.key}") needs kernel {SETTINGS_KERNEL} (signed settings; this server runs {current.kernelVersion}): using the default`)

package/out/version.d.ts

@@ -2,4 +2,4 @@
  * This framework's version, as package.json says (scripts/test-state-inspect.luau checks they match). Shown in
  * uploaded log headers (Logs > Upload); bump it with package.json.
  */
-export declare const FRAMEWORK_VERSION = "0.5.0";
+export declare const FRAMEWORK_VERSION = "0.5.2";

package/out/version.luau

@@ -5,7 +5,7 @@
 	 * uploaded log headers (Logs > Upload); bump it with package.json.
 	 
 ]]
-local FRAMEWORK_VERSION = "0.5.0"
+local FRAMEWORK_VERSION = "0.5.2"
 return {
 	FRAMEWORK_VERSION = FRAMEWORK_VERSION,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@typetorch/framework",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"description": "TypeTorch framework for roblox-ts: hot-swappable modules (dependency injection, lifecycle, troves), guarded networking, hot assets and the in-game dev menu. Ships inside every TypeTorch artifact.",
 	"license": "MIT",
 	"author": "TypeTorch",