@typetorch/framework 0.3.4 → 0.3.5

package/README.md

@@ -57,16 +57,25 @@ swap. It needs the TypeTorch kernel in the place (`@typetorch/kernel`).
 
 ### Coming from Flamework
 
-Game code only changes imports: `@Service`, `@Controller`, constructor injection, the lifecycle interfaces and
-`createNetwork` are the same.
+Game code only changes imports: `@Service`, `@Controller`, constructor injection, `Dependency<T>()`, the lifecycle
+interfaces and `createNetwork` are the same.
 
 | Flamework | TypeTorch |
 |---|---|
 | `rbxts-transformer-flamework` plugin, `node_modules/@flamework` type root | `@typetorch/transformer` plugin, `node_modules/@typetorch` type root |
 | `import { Modding, Reflect } from "@flamework/core"` | `import { Modding, Reflect } from "@typetorch/framework"` |
+| `import { Dependency } from "@flamework/core"` | `import { Dependency } from "@typetorch/framework"` (from onInit/onStart on, not in constructors) |
+| `import type` + `Dependency<T>()` to break a cycle | the same, or `Lazy<T>` (below) |
+| `ClientEvents.x.predict(...)` | `network.client.x.emit(...)` |
+| `invokeWithTimeout(timeout, ...)` | `invokeWithTimeout(seconds, ...)` (seconds, 0.5 to 120) |
+| `Observers.observeCharacter` / `observeLocalCharacter` (@rbxts/observers) | still fine: put the stop function in the trove, `this.trove.add(observeCharacter(...))` |
 | `import { t } from "@rbxts/t"` (still fine) | also `import { t } from "@typetorch/framework"` |
 | `@metadata flamework:parameters` keys, `"flamework:parameters"` metadata | `@metadata typetorch:parameters`, `"typetorch:parameters"` |
 | `flamework.build`, `include/flamework`, the `@flamework` Rojo mapping | gone; delete them |
+| `Networking.createEvent` / `createFunction` and their call sites | `createFlameworkCompat` (below) keeps every call site; `createNetwork` is the native API |
+
+`typetorch migrate --from flamework` (CLI) does most of this, and the docs' `guides/from-flamework.md` has the whole
+mapping.
 
 ## Usage
 
@@ -99,6 +108,19 @@ export class CoinService extends Module implements OnStart {
 - **Modules:** `@Service()` (server) and `@Controller()` (client) classes extending `Module`. Constructor parameters
   are other modules, injected by type. Lifecycle: `OnInit` (sequential, dependencies first), `OnStart` (spawned),
   `OnStop` (reverse order), `OnTick`, `OnPhysics`, `OnRender`, `OnPlayerAdded` (replays players already in the server).
+- **Modules outside the constructor:** `Dependency<T>()` (or `TypeTorch.module<T>()`) returns the running module of
+  type T from anywhere: a method, a plain class a module built, a command handler. `TypeTorch.tryModule<T>()` returns
+  undefined instead of throwing. They work once every module is constructed (from onInit on); in a constructor, a
+  field initializer or module top-level code they throw `"ShopService isn't constructed yet: ..."`. Only this realm's
+  modules, and per generation: after a swap they return the new generation's instance. An `import type` of the class is
+  enough (no require cycle).
+- **Cycles:** two modules that need each other take one side as `Lazy<T>`, resolved on first use:
+  `constructor(private readonly team: Lazy<TeamService>)` (needs `@typetorch/transformer` 0.2.1+) or a field,
+  `private readonly team = Lazy<TeamService>()` (any transformer). `this.team.get()` works from onInit on (in a
+  constructor it throws), and the start order ignores lazy edges. A cycle error names the cycle and suggests this.
+- **Per-player state:** `this.ctx.playerState("cooldowns.v1", (player) => init)` (or `TypeTorch.playerState`) returns
+  `{ get, set, has, delete }` keyed by UserId. It survives swaps (persist), and a player's entry goes when they really
+  leave, never on a swap. The dev menu shows it under Modules > State > persist, `__playerState`.
 - **Bad deploys roll back (kernel 0.3.2):** a server `onStart` that throws is reported to the kernel, which rolls the
   server back to its last known good artifact when it happens within 30 s of start (so do 3 errors from the new
   code's scripts in that time). On a real shutdown every module's `onStop` runs too (the kernel's BindToClose).
@@ -106,6 +128,18 @@ export class CoinService extends Module implements OnStart {
   behind. `TypeTorch.persist(key, init)` (or `this.ctx.persist`) keeps plain data across swaps.
 - **Network:** `createNetwork<C2S, S2C>()` with nested namespaces. The server checks rate limits, shape limits and the
   generated type guard on every client message. `setNetworkLimits({ "chat.say": { maxString: 200 } })` tunes a leaf.
+  Requests wait 15 s for the answer: `invokeWithTimeout(5, ...args)` sets it per call, and a leaf's `timeout`
+  (`setNetworkLimits({ "vc.spawn": { timeout: 30 } })`, read by the client, so set it in shared code) per leaf; both in
+  seconds, 0.5 to 120. `network.client.x.emit(...args)` runs this client's own `on` handlers for a server -> client
+  leaf right away, with no traffic (Flamework's `predict`); `network.server.x.emit(player, ...args)` does the same on
+  the server, for tests. A request handler may return a Promise: the answer waits for it.
+- **Flamework networking names:** `createFlameworkCompat<C2SEvents, S2CEvents, C2SFunctions, S2CFunctions>()` returns
+  `{ ServerEvents, ClientEvents, ServerFunctions, ClientFunctions, GlobalEvents, GlobalFunctions }` with
+  `@flamework/networking` 1.x's methods (`connect` returning a connection, `fire(player | players)`, `broadcast`,
+  `except`, `predict`, `setCallback`, `invoke`, `invokeWithTimeout`, calling a leaf directly) on this same network:
+  same guards, limits and swap rules, so a Flamework game's call sites compile unchanged. Listeners run on their own
+  thread each, like Flamework's, and belong to the running generation (no trove needed). Not carried over: server ->
+  client requests, middleware, `Networking.Unreliable`. `typetorch build` notes a game still using it.
   Across a swap (0.3.0): what the server sends a player waits until that player's client runs the new generation
   (reliable messages are queued, unreliable ones dropped), and on kernel 0.3.2 a request the server can no longer
   answer fails at once ("The game is updating, try again.") instead of timing out.
@@ -182,6 +216,13 @@ this.trove.add(TypeTorch.onUpdatePending((update) => (hint.Visible = !update.can
 
 // State that survives swaps (plain data only)
 const scores = TypeTorch.persist("scores.v1", () => new Map<number, number>());
+// Per player, removed when the player really leaves (same as this.ctx.playerState)
+const cooldowns = TypeTorch.playerState("cooldowns.v1", () => ({ lastUse: 0 }));
+cooldowns.get(player).lastUse = os.clock();
+
+// The running module of a type (same as Dependency<T>()), from onInit/onStart on
+TypeTorch.module<ShopService>().open(player);
+TypeTorch.tryModule<ShopService>()?.open(player); // undefined instead of an error
 
 // Dev and roles (server: the kernel decides; client: only the local player, cosmetic)
 if (TypeTorch.isOwner(player)) showOwnerPanel(player);
@@ -198,6 +239,23 @@ TypeTorch.onLog((entry) => errors.push(entry)); // don't print from inside it
 
 // Hot assets (below): same as hotAsset(...)
 const shop = TypeTorch.asset("ui/shop");
+
+// Live values, server only (kernel 0.3.8): the signed settings record's `game` field (`typetorch settings set game.<key> <json>`).
+const price = TypeTorch.liveConfig("shop.price", { default: 50, parse: (raw) => (typeIs(raw, "number") ? raw : 50) });
+price.get();
+this.trove.add(price.onChanged((value) => this.reprice(value)));
+
+// Cross-server, server only. Kernel 0.3.8: game topics over ONE kernel-held MessagingService topic; listeners hear
+// prod servers and this branch by default (dev branches never reach prod); publish queues and retries, max 1 KiB.
+this.trove.add(TypeTorch.messaging.subscribe<Ban>("1guard", (ban, meta) => applyBan(ban, meta.jobId)));
+TypeTorch.messaging.publish("1guard", { kind: "ban", userId }, { to: "prod" });
+
+// The universe's live servers (the roll call; cached per server, yields up to ~3 s when stale) and this server's public fields
+TypeTorch.setServerInfo({ region: "eu", vc: true }); // JSON, at most 400 bytes, kept across swaps
+const list = TypeTorch.servers(); // [{ jobId, placeVersion, players, maxPlayers, serverType, branch, channel, uptime, here, info }]
+
+// A library call a swap must not cut off halfway (kernel 0.3.8): runs on a kernel thread; write what must survive into persist.
+TypeTorch.runDetached(() => store.StartSessionAsync(`Player_${userId}`)).then((profile) => attach(player, profile));
 ```
 
 - **`startInfo.reason`:** `boot`, `deploy`, `rollback`, `branch`, `pin`, `reload`, `server_rollback`,
@@ -214,6 +272,25 @@ const shop = TypeTorch.asset("ui/shop");
   reason and timings, the next artifact in `onSwapOut`, `onUpdatePending`, server-side `onPlayerDevChanged` and
   `requestReload`. On older kernels `startInfo` still knows boot vs swap, the previous artifact and branch (the
   framework records them), `onBranchChanged` still fires, and the reason of a swap is `unknown`.
+- **`messaging`** (kernel 0.3.8): `subscribe(topic, (data, meta) => ...)` returns a disconnect; `meta` = `{ channel,
+  branch, jobId, serverType, placeVersion, sentAt, self, replayed? }`; `{ from: "all" | "prod" | "branch" }` changes
+  who it hears. `publish(topic, data, { to })` throws on a bad topic, non-JSON data or a message over 1 KiB (with its
+  size), returns false when dropped at once (queue full). Studio loops back; the cloud test publishes nothing; older
+  kernels throw "needs kernel 0.3.8". `servers()` works on every kernel (0.3.8 holds the roll call topic, so a swap
+  doesn't subscribe again).
+- **`liveConfig(key, { default, parse? })`** (kernel 0.3.8, plans/20): reads `game[key]` of the signed settings record the
+  kernel verified (signed by both prod keys, so game code can't forge it); `get()` and `onChanged(fn)` (only on real
+  changes; generation-scoped). The default without a record or key, when `parse` throws (warned per value), and on older
+  kernels (warned once: "needs kernel 0.3.8"; no ConfigService fallback). `TypeTorch.settings()` is the whole copy
+  (`seq`, `at`, `game`, `analytics`, `fleet`, ...): server only, it holds tokens.
+- **`runDetached(fn)`** (kernel 0.3.8, server only): runs `fn` on a thread the kernel owns, so a deploy's hard stop
+  (which kills this generation's threads mid-call) can't cut it off: for ProfileStore / ProfileService loads, saves and
+  releases. Returns a Promise that settles while this generation runs; after a swap the result is dropped, so a job
+  whose result must survive writes it into `persist` itself. The job keeps this generation's closures alive until it
+  ends. Errors reject it and go to the kernel's log with the generation's name (never the health window); at most 256
+  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.
 - **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.
 
@@ -227,6 +304,8 @@ pieces that keep it safe across swaps:
 - **Session handles live in `persist`**, keyed by `UserId`. `onPlayerAdded` replays everyone after a swap, so it
   re-attaches to the open session instead of loading again.
 - **Release only on `Players.PlayerRemoving`**, never in `onStop` or `onSwapOut`.
+- **Library calls can't be cut off by a swap:** run them as DataHost jobs (any kernel) or with
+  `TypeTorch.runDetached` (kernel 0.3.8).
 - **Split store names by channel** (`TypeTorch.channel === "prod" ? "PlayerData" : "PlayerData_dev"`).
 
 Full example with ProfileStore: [Player data guide](https://github.com/typetorch/docs/blob/main/guides/player-data.md).
@@ -287,7 +366,7 @@ self-hosted DuckDB analytics server). Nothing runs until an engine is created: n
 ```ts
 import { AnalyticsEngine } from "@typetorch/framework";
 
-// A server module (onInit): reads the ConfigService key TypeTorchAnalytics.
+// A server module (onInit): the sink comes from the signed settings' `analytics` (kernel 0.3.8).
 const analytics = new AnalyticsEngine();
 analytics.track(player, "quest_done", { quest: "tutorial" }); // custom
 analytics.step(player, "onboarding", 3, "opened_shop"); // funnels
@@ -317,13 +396,13 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   `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),
   `identity` (one `{ pid, uid }` row per session to the dev's own server, below). `settings` (server only) replaces the
-  ConfigService key, for tests.
+  signed settings' `analytics`, for tests, Studio and kernels before 0.3.8.
 - **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`.
 - **Experiments:** `experiment(...)` is deterministic per player and name (they keep their variant in every session),
   may yield briefly the first time (until the player's id loads), and stamps the variant on the player's later events.
-  The settings key turns one off (`active: false`: everyone gets the first variant), sets `weights` or forces a
+  The settings turn one off (`active: false`: everyone gets the first variant), sets `weights` or forces a
   `variant`, live.
 - **First-ever session:** for new players (a share of them, `recordShare`), the client records character and camera
   about 10 times a second, every input (never while a TextBox or the chat has focus; text boxes only say which box was
@@ -333,7 +412,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 (`TypeTorchFleet` url + `/v1/identity`, or the `identity` / `identityToken` settings). The
+  games to the fleet API (the settings' `fleet` 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.
@@ -352,9 +431,10 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
 - **Friends in the server** (the join's `friends`): one `Players:GetFriendsAsync` per join (at most 10 pages, none
   when the player is alone) intersected with the players there, not a web call per player.
 
-**Settings** (server only, never sent to clients): the ConfigService key `TypeTorchAnalytics`, written with
-`writeSettings()` from `@typetorch/analytics` (Open Cloud, universe:write) or in Creator Hub (Configs); no CLI command
-writes it. Re-read live every few minutes:
+**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
+there are no settings unless the game passes `new AnalyticsEngine({ settings })`:
 
 ```json
 { "backend": "basin", "events": "https://<stream-id>.ingest.cloudflare.com",
@@ -392,6 +472,14 @@ bun run build   # rbxtsc --type package -> out/
   package.json.
   `scripts/test-layout.luau` checks the dev menu's pane layout core (`devtools/layout.ts`: splits and their limits,
   closing, pop out and dock, singleton pages, ratios, focus, and cleaning a remembered layout).
+  `scripts/test-modules.luau` runs the real `startServer`/`startClient` of `out/` (with RuntimeLib, Promise, trove and
+  t from node_modules) over several generations that share a persist store: `Dependency<T>()`, `TypeTorch.module` /
+  `tryModule` and their errors, `Lazy<T>` (parameters and fields, cycles, start order), network `emit` and request
+  timeouts and `playerState` (swaps, leaves).
+  `scripts/test-flamework-compat.luau` (same harness) drives `createFlameworkCompat` through each generation's
+  dispatcher: connect (one thread per call, guards, Disconnect, troves), fire / except / broadcast / the call
+  shorthand, setCallback with values and Promises, predict, a swap, and the client side (invoke, invokeWithTimeout,
+  `createClient({ defaultTimeout })`).
   `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

@@ -128,8 +128,10 @@ start, i.e. the row's `t`). Time is the running sum of `dt`.
 
 ## Sink settings
 
-ConfigService key `TypeTorchAnalytics` (server-only), a JSON object (or a JSON string of one). Re-read on
-`UpdateAvailable` and every 3 minutes, so dials change live. `new AnalyticsEngine({ settings })` replaces the key.
+The signed settings record's `analytics` field (kernel 0.3.8, plans/20; server-only; before 0.3.8 the ConfigService key
+`TypeTorchAnalytics`), a JSON object, written with `typetorch settings set analytics -` (JSON on stdin; the analytics
+repo's `bun run local` does it). Every new signed copy applies at once, so dials change live (the CLI pings servers).
+`new AnalyticsEngine({ settings })` replaces it (tests, Studio, kernels before 0.3.8).
 
 ```json
 {
@@ -154,8 +156,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 |
+| `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 |
 
 Unknown fields are ignored. Settings errors are warned once (never with the token).
 

package/out/analytics/engine.luau

@@ -10,7 +10,7 @@ local ServerAnalytics = TS.import(script, script.Parent, "server").ServerAnalyti
 	 * client. Nothing runs until one is created. Every engine created in a generation shares one core, which stops with
 	 * the generation; its unsent rows survive a hot swap in `persist`.
 	 *
-	 * The server sends rows to the sink in the settings (ConfigService key `TypeTorchAnalytics`, or `options.settings`).
+	 * The server sends rows to the sink in the settings (the signed settings' `analytics`, kernel 0.3.8; or `options.settings`).
 	 * The client sends everything through the server, never to the internet. See the README "Analytics" section and
 	 * src/analytics/SCHEMA.md.
 	 

package/out/analytics/schema.d.ts

@@ -5,10 +5,6 @@
  */
 /** Row format version (column `v`). */
 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>}`. */
@@ -91,7 +87,7 @@ export interface ExperimentOverride {
     /** Everyone gets this variant (must be one of the game's variants). */
     variant?: string;
 }
-/** The sink settings: ConfigService key `TypeTorchAnalytics` (server-only), or `new AnalyticsEngine({ settings })`. */
+/** The sink settings: the signed settings' `analytics` (kernel 0.3.8, server-only), or `new AnalyticsEngine({ settings })`. */
 export interface AnalyticsSettings {
     backend: "basin" | "duckdb";
     /** basin: the events stream's ingest URL; duckdb: the analytics server's ingest URL. */
@@ -109,12 +105,12 @@ export interface AnalyticsSettings {
     /** 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
+     * basin: where identity rows go (the fleet API's `POST /v1/identity` URL). Default: the settings' `fleet` 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. */
+    /** basin: the token for `identity` (default: the settings' `fleet` token). Never logged. */
     identityToken?: string;
 }
 /** AnalyticsSettings with every default filled in. */
@@ -147,7 +143,7 @@ export interface AnalyticsPurchase {
 }
 /** What the automatic collectors do. Everything is on by default. */
 export interface AnalyticsOptions {
-    /** Server only: the sink settings. When set, the ConfigService key isn't read (tests, Studio). */
+    /** Server only: the sink settings. When set, the signed settings aren't read (tests, Studio, kernels before 0.3.8). */
     settings?: AnalyticsSettings;
     /** Server: joins, leaves, device, join source, first-ever vs returning. Default true. */
     sessions?: boolean;

package/out/analytics/schema.luau

@@ -8,10 +8,6 @@
 ]]
 --* Row format version (column `v`). 
 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>}`. 
@@ -26,7 +22,7 @@ local PROPS_MAX_BYTES = 4096
 	 
 ]]
 --* Live overrides of one per-player experiment (settings key `experiments`). 
---* The sink settings: ConfigService key `TypeTorchAnalytics` (server-only), or `new AnalyticsEngine({ settings })`. 
+--* The sink settings: the signed settings' `analytics` (kernel 0.3.8, server-only), or `new AnalyticsEngine({ settings })`. 
 --* AnalyticsSettings with every default filled in. 
 --* Event properties: a flat JSON object (nested tables work but are harder to query). 
 --* What the automatic collectors do. Everything is on by default. 
@@ -35,8 +31,6 @@ local PROPS_MAX_BYTES = 4096
 --* Counters of the server engine (`AnalyticsEngine.stats()`). 
 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,7 +63,7 @@ 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). */
+    /** The settings' `fleet` value (Basin games send identities to the fleet API). */
     private fleetSettings?;
     private nextFlushAt;
     private backoffUntil;

package/out/analytics/server.luau

@@ -2,7 +2,6 @@
 local TS = _G[script]
 local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
 local CollectionService = _services.CollectionService
-local ConfigService = _services.ConfigService
 local DataStoreService = _services.DataStoreService
 local HttpService = _services.HttpService
 local LocalizationService = _services.LocalizationService
@@ -12,6 +11,10 @@ local Stats = _services.Stats
 local Workspace = _services.Workspace
 local maybeServerDispatcher = TS.import(script, script.Parent.Parent, "net", "runtime").maybeServerDispatcher
 local observePlayers = TS.import(script, script.Parent.Parent, "players").observePlayers
+local _settings = TS.import(script, script.Parent.Parent, "settings")
+local currentSettings = _settings.currentSettings
+local onSettings = _settings.onSettings
+local settingsSupported = _settings.settingsSupported
 local _typetorch = TS.import(script, script.Parent.Parent, "typetorch")
 local closeHooksSupported = _typetorch.closeHooksSupported
 local onGenerationClose = _typetorch.onGenerationClose
@@ -39,15 +42,13 @@ 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
+local _settings_1 = TS.import(script, script.Parent, "settings")
+local identityTarget = _settings_1.identityTarget
+local parseSettings = _settings_1.parseSettings
+local recordsSupported = _settings_1.recordsSupported
+local DEFAULT_TECH_EVERY = _settings_1.DEFAULT_TECH_EVERY
 local _sinks = TS.import(script, script.Parent, "sinks")
 local buildRequests = _sinks.buildRequests
 local estimateEventBytes = _sinks.estimateEventBytes
@@ -104,7 +105,6 @@ local RECORDING_MAX_CHUNKS = 80
 local RECORDING_MAX_SECONDS = 900
 --* The join event waits this long for the client's device info. 
 local DEVICE_WAIT = 8
-local SETTINGS_REFRESH = 180
 local ZONE_INTERVAL = 0.5
 local ZONE_TAG = "TTZone"
 --* One player's session. Plain data (persist), keyed by tostring(UserId). 
@@ -484,7 +484,7 @@ do
 	end
 	function ServerAnalytics:track(player, kind, name, props)
 		if not isEventName(name) then
-			warn("[src/analytics/server.ts:458]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
+			warn("[src/analytics/server.ts:455]", `[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
@@ -592,7 +592,7 @@ do
 		end
 		local control = _condition
 		if not isExperimentName(name) or not isVariantList(variants) then
-			warn("[src/analytics/server.ts:509]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
+			warn("[src/analytics/server.ts:506]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
 			return control
 		end
 		local session = self:sessionOf(player)
@@ -657,7 +657,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:544]", `[analytics] {SETTINGS_KEY}: {errorsText}`)
+			warn("[src/analytics/server.ts:541]", `[analytics] settings.analytics: {errorsText}`)
 		end
 		self.settingsErrors = parsed.errors
 		local hadSettings = self.settings ~= nil
@@ -682,91 +682,42 @@ do
 			self.settingsTried = true
 			return nil
 		end
+		-- Kernel 0.3.8 (plans/20): the signed settings record's `analytics` (the sink) and `fleet` (identities on Basin),
+		-- live through the kernel's change hook. Older kernels have no settings (no ConfigService fallback): pass
+		-- `new AnalyticsEngine({ settings })`.
+		if not settingsSupported() then
+			if self.kernel ~= nil and self.kernel.test ~= true then
+				warn("[src/analytics/server.ts:568]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch settings set analytics -"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
+			end
+			self.settingsTried = true
+			return nil
+		end
 		local lastRaw
-		local missing = false
-		local snapshot
-		local read = function(force)
-			if not snapshot or (missing and not force) then
-				return nil
+		local apply = function(settings)
+			local _result = settings
+			if _result ~= nil then
+				_result = _result.fleet
 			end
-			local fleetOk, fleetValue = pcall(function()
-				return snapshot:GetValue(FLEET_SETTINGS_KEY)
-			end)
-			if fleetOk then
-				self.fleetSettings = fleetValue
+			self.fleetSettings = _result
+			local _value = settings
+			if _value ~= nil then
+				_value = _value.analytics
 			end
-			local ok, value = pcall(function()
-				return snapshot:GetValue(SETTINGS_KEY)
-			end)
-			if not ok then
-				return nil
-			end
-			missing = value == nil
+			local value = _value
 			-- Compare without decoding twice; the text never reaches a log.
 			local encodedOk, raw = pcall(function()
-				return if type(value) == "string" then value else HttpService:JSONEncode(value)
+				return if value == nil then "" else HttpService:JSONEncode(value)
 			end)
-			local text = if value == nil then "" elseif encodedOk then raw else tostring(os.clock())
+			local text = if encodedOk then raw else tostring(os.clock())
 			if text == lastRaw then
 				return nil
 			end
 			lastRaw = text
 			self:applySettings(parseSettings(value, decode))
 		end
-		self.trove:add(task.spawn(function()
-			local delay = 2
-			do
-				local attempt = 1
-				local _shouldIncrement = false
-				while true do
-					if _shouldIncrement then
-						attempt += 1
-					else
-						_shouldIncrement = true
-					end
-					if not (attempt <= 6 and not snapshot) then
-						break
-					end
-					local ok, result = pcall(function()
-						return ConfigService:GetConfigAsync()
-					end)
-					if ok then
-						snapshot = result
-					else
-						if attempt == 1 then
-							warn("[src/analytics/server.ts:590]", `[analytics] ConfigService unavailable: {string.sub(tostring(result), 1, 120)}`)
-						end
-						task.wait(delay)
-						delay = math.min(delay * 2, 30)
-					end
-				end
-			end
-			if not snapshot then
-				self.settingsTried = true
-				return nil
-			end
-			local current = snapshot
-			self.trove:connect(current.UpdateAvailable, function()
-				pcall(function()
-					return current:Refresh()
-				end)
-				read(true)
-			end)
-			pcall(function()
-				return self.trove:connect(current:GetValueChangedSignal(SETTINGS_KEY), function()
-					return read(true)
-				end)
-			end)
-			read(true)
-			self.settingsTried = true
-			while true do
-				task.wait(SETTINGS_REFRESH)
-				pcall(function()
-					return current:Refresh()
-				end)
-				read(false)
-			end
-		end))
+		apply(currentSettings())
+		self.settingsTried = true
+		self.trove:add(onSettings(apply))
 	end
 	function ServerAnalytics:dataStore()
 		local ok, store = pcall(function()
@@ -1481,7 +1432,7 @@ do
 				end
 			end)
 			if not ok then
-				warn("[src/analytics/server.ts:1058]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
+				warn("[src/analytics/server.ts:1033]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
 			end
 		end)
 		self.trove:add(function()
@@ -1761,7 +1712,7 @@ do
 			return nil
 		end
 		self.lastWarnAt = now
-		warn("[src/analytics/server.ts:1247]", `[analytics] {message}`)
+		warn("[src/analytics/server.ts:1222]", `[analytics] {message}`)
 	end
 	function ServerAnalytics:post(request)
 		local ok, response = pcall(function()
@@ -1883,7 +1834,7 @@ do
 				end
 				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`)
+				self:warn(if outcome == "config" then `{what} got HTTP {status}: check the URL and token in settings.analytics (typetorch settings set analytics -); 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.

package/out/analytics/settings.d.ts

@@ -1,5 +1,5 @@
 /**
- * The sink settings (ConfigService key `TypeTorchAnalytics`, or `new AnalyticsEngine({ settings })`): parsing with
+ * The sink settings (the signed settings' `analytics`, kernel 0.3.8, or `new AnalyticsEngine({ settings })`): parsing with
  * defaults and clamps. Errors never repeat the token.
  *
  * Pure: no imports and no services, so it also runs offline under Lune (scripts/test-analytics.luau). The JSON
@@ -18,14 +18,14 @@ 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. */
+/** Where identity rows go on a Basin game: the fleet API (the settings' `fleet` = { 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.
+ * else the fleet API's /v1/identity from the settings' `fleet` 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. */

package/out/analytics/settings.luau

@@ -1,7 +1,7 @@
 -- Compiled with roblox-ts v3.0.0
 --[[
 	*
-	 * The sink settings (ConfigService key `TypeTorchAnalytics`, or `new AnalyticsEngine({ settings })`): parsing with
+	 * The sink settings (the signed settings' `analytics`, kernel 0.3.8, or `new AnalyticsEngine({ settings })`): parsing with
 	 * defaults and clamps. Errors never repeat the token.
 	 *
 	 * Pure: no imports and no services, so it also runs offline under Lune (scripts/test-analytics.luau). The JSON
@@ -215,11 +215,11 @@ local function parseSettings(raw, decode)
 		errors = errors,
 	}
 end
---* Where identity rows go on a Basin game: the fleet API (`TypeTorchFleet` = { url, token }) at /v1/identity. 
+--* Where identity rows go on a Basin game: the fleet API (the settings' `fleet` = { url, token }) at /v1/identity. 
 --[[
 	*
 	 * 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.
+	 * else the fleet API's /v1/identity from the settings' `fleet` value (a table or JSON `{ url, token }`), else none.
 	 
 ]]
 local function identityTarget(settings, fleetRaw, decode)

package/out/detached.d.ts

@@ -0,0 +1,26 @@
+import type { Trove } from "@rbxts/trove";
+/**
+ * `TypeTorch.runDetached(fn)` (server only, kernel 0.3.8): runs `fn` on a thread the KERNEL owns, so a deploy's swap
+ * (this generation's stop, and its hard stop, which kills the generation's own threads mid-call) never cuts it off.
+ * Made for library calls that must not stop halfway: a ProfileStore / ProfileService load, save or release cut off
+ * by a hard stop jams that player's profile on this server (docs: Player data, "Why the jobs").
+ *
+ *   TypeTorch.runDetached(() => store.StartSessionAsync(key)).then((profile) => ...);
+ *
+ * - The Promise settles on this generation's thread while it runs. A result that arrives after this generation
+ *   stopped is dropped: a job whose result must survive a swap writes it into `persist` itself.
+ * - A job keeps this generation's closures (and everything they reference) alive until it ends: keep jobs short.
+ * - Errors reject the Promise and go to the kernel's log with the generation's name; they never count toward the
+ *   build's health window. At most 256 jobs run at once per server (then it throws); one past 60 s is logged.
+ * - Older kernels: throws "needs kernel 0.3.8; use the DataHost job queue (Player data guide)". Clients: throws.
+ */
+/** The first kernel with `api:runDetached`. */
+export declare const DETACHED_KERNEL = "0.3.8";
+/** Called by bindTypeTorch. */
+export declare function bindDetached(realm: "server" | "client", kernel: unknown, trove: Trove, kernelVersion: string): void;
+/** Called by unbindTypeTorch. */
+export declare function unbindDetached(): void;
+/** `runDetached` reaches a kernel thread (a server on kernel 0.3.8+). */
+export declare function detachedSupported(): boolean;
+/** `TypeTorch.runDetached`. */
+export declare function runDetached<T>(fn: () => T): Promise<T>;