@trioforge/crucible 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trio Forge Studio
+
+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/client/package.json

@@ -0,0 +1,4 @@
+{
+	"main": "../out/client/init.luau",
+	"types": "../out/client/index.d.ts"
+}

package/emit/package.json

@@ -0,0 +1,4 @@
+{
+	"main": "../out/emit/init.luau",
+	"types": "../out/emit/index.d.ts"
+}

package/out/all.d.ts

@@ -0,0 +1,7 @@
+export interface All<T extends object> {
+    size(): number;
+    has(item: T): boolean;
+    first(): T | undefined;
+    forEach(visit: (item: T) => void): void;
+    observe(added: (item: T) => void, removed?: (item: T) => void): () => void;
+}

package/out/all.luau

@@ -0,0 +1,2 @@
+-- Compiled with roblox-ts v3.0.0
+return nil

package/out/attribute.d.ts

@@ -0,0 +1,7 @@
+type AttributeValue = string | number | boolean | Vector3 | Color3;
+export declare function attribute<T extends AttributeValue>(): T;
+export declare function attribute(fallback: number): number;
+export declare function attribute(fallback: string): string;
+export declare function attribute(fallback: boolean): boolean;
+export declare function attribute<T extends AttributeValue | undefined>(fallback: T): T;
+export {};

package/out/attribute.luau

@@ -0,0 +1,7 @@
+-- Compiled with roblox-ts v3.0.0
+local function attribute(_fallback)
+	error("attribute() was not replaced; add the Crucible transformer to the compiler plugins")
+end
+return {
+	attribute = attribute,
+}

package/out/client/index.d.ts

@@ -0,0 +1,10 @@
+import type { BootOptions } from "../index";
+import type { AskResult, AskServer, PayloadArgs, ToServer } from "../network";
+export declare const BOOTED_ATTRIBUTE = "CrucibleBooted";
+export declare function boot(options: BootOptions): void;
+export declare namespace Network {
+    /** True when accepted locally: fired now, or queued until this client is ready. Never delivery. */
+    function send<P>(message: ToServer<P>, ...payload: PayloadArgs<NoInfer<P>>): boolean;
+    /** Yields until the reply, the declared timeout or the session ending. */
+    function ask<Request, Response>(message: AskServer<Request, Response>, ...request: PayloadArgs<NoInfer<Request>>): AskResult<Response>;
+}

package/out/client/init.luau

@@ -0,0 +1,55 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local bootSide = TS.import(script, script.Parent, "internal", "boot").boot
+local ClientSession = TS.import(script, script.Parent, "internal", "network", "client-session").ClientSession
+local networkPort = TS.import(script, script.Parent, "internal", "network", "port").networkPort
+local installClientSync = TS.import(script, script.Parent, "internal", "sync", "client-sync").installClientSync
+local SyncFaultMessage = TS.import(script, script.Parent, "internal", "sync", "frame").SyncFaultMessage
+if not game:GetService("RunService"):IsClient() then
+	error("@trioforge/crucible/client loaded on the server")
+end
+local BOOTED_ATTRIBUTE = "CrucibleBooted"
+local session
+local function active()
+	return session or error("Crucible networking is not ready; send from a constructor, a hook, or later", 0)
+end
+local function boot(options)
+	local network = ClientSession.new(networkPort())
+	session = network
+	installClientSync(function(revision)
+		return active():send(SyncFaultMessage, revision)
+	end)
+	bootSide({
+		name = "client",
+		renders = true,
+		booted = function()
+			local player = game:GetService("Players").LocalPlayer
+			player:SetAttribute(BOOTED_ATTRIBUTE, true)
+			return function()
+				return player:SetAttribute(BOOTED_ATTRIBUTE, nil)
+			end
+		end,
+		network = network,
+	}, options)
+end
+local Network = {}
+do
+	local _container = Network
+	--* True when accepted locally: fired now, or queued until this client is ready. Never delivery. 
+	local function send(message, ...)
+		local payload = { ... }
+		return active():send(message, payload[1])
+	end
+	_container.send = send
+	--* Yields until the reply, the declared timeout or the session ending. 
+	local function ask(message, ...)
+		local request = { ... }
+		return active():ask(message, request[1])
+	end
+	_container.ask = ask
+end
+return {
+	boot = boot,
+	BOOTED_ATTRIBUTE = BOOTED_ATTRIBUTE,
+	Network = Network,
+}

package/out/configs.d.ts

@@ -0,0 +1,37 @@
+declare const configKind: unique symbol;
+/** An experience-wide config. Calling it reads the global snapshot's value; it never yields or throws. */
+export interface Config<T> {
+    (): T;
+    readonly [configKind]: {
+        readonly scope: "global";
+        readonly value: (value: T) => T;
+    };
+}
+/** A targeted config. Calling it reads that player's value; it never yields or throws. */
+export interface PlayerConfig<T> {
+    (player: Player): T;
+    readonly [configKind]: {
+        readonly scope: "player";
+        readonly value: (value: T) => T;
+    };
+}
+/**
+ * Declares an experience config by its dashboard key, read from the global snapshot. It must initialize an exported
+ * top-level const in a server module, with `T` explicit. The fallback is the value before the first fetch and for a
+ * missing key.
+ */
+export declare function config<T = never>(_name: string, _fallback: NoInfer<T>): Config<T>;
+/** Declares a targeted config by its dashboard key, read from each player's snapshot. Same form as `config`. */
+export declare function playerConfig<T = never>(_name: string, _fallback: NoInfer<T>): PlayerConfig<T>;
+/**
+ * With no argument, true once the global snapshot has been applied. With a player, true once that player's snapshot
+ * has been applied, and false before and after they leave.
+ */
+export declare function configReady(player?: Player): boolean;
+/**
+ * Refreshes every snapshot with newer values, fetches every snapshot that has not loaded, and applies them all in
+ * one pass. Yields, at most 10 seconds. True when every snapshot is current; false keeps the last good values.
+ * Concurrent calls share one refresh. Crucible never calls it.
+ */
+export declare function refreshConfigs(): boolean;
+export {};

package/out/configs.luau

@@ -0,0 +1,46 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _runtime = TS.import(script, script.Parent, "internal", "configs", "runtime")
+local ready = _runtime.ready
+local refresh = _runtime.refresh
+--* An experience-wide config. Calling it reads the global snapshot's value; it never yields or throws. 
+--* A targeted config. Calling it reads that player's value; it never yields or throws. 
+--[[
+	*
+	 * Declares an experience config by its dashboard key, read from the global snapshot. It must initialize an exported
+	 * top-level const in a server module, with `T` explicit. The fallback is the value before the first fetch and for a
+	 * missing key.
+	 
+]]
+local function config(_name, _fallback)
+	error("Crucible configs need the @trioforge/crucible/transformer plugin")
+end
+--* Declares a targeted config by its dashboard key, read from each player's snapshot. Same form as `config`. 
+local function playerConfig(_name, _fallback)
+	error("Crucible configs need the @trioforge/crucible/transformer plugin")
+end
+--[[
+	*
+	 * With no argument, true once the global snapshot has been applied. With a player, true once that player's snapshot
+	 * has been applied, and false before and after they leave.
+	 
+]]
+local function configReady(player)
+	return ready(player)
+end
+--[[
+	*
+	 * Refreshes every snapshot with newer values, fetches every snapshot that has not loaded, and applies them all in
+	 * one pass. Yields, at most 10 seconds. True when every snapshot is current; false keeps the last good values.
+	 * Concurrent calls share one refresh. Crucible never calls it.
+	 
+]]
+local function refreshConfigs()
+	return refresh()
+end
+return {
+	config = config,
+	playerConfig = playerConfig,
+	configReady = configReady,
+	refreshConfigs = refreshConfigs,
+}

package/out/crucible-behaviour.d.ts

@@ -0,0 +1,16 @@
+import { CrucibleObject } from "./crucible-object";
+export type BehaviourClass<T extends CrucibleBehaviour<string>> = new (...args: never[]) => T;
+export declare abstract class CrucibleBehaviour<Tag extends string, I extends Instance = Instance> extends CrucibleObject {
+    static accepts(instance: Instance): boolean;
+    static refresh(instance: Instance): void;
+    static get<T extends CrucibleBehaviour<string>>(this: BehaviourClass<T>, instance: Instance): T | undefined;
+    readonly instance: I;
+    readonly tag: Tag;
+    constructor();
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    remove(): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    protected onDestroy(): void;
+}

package/out/crucible-behaviour.luau

@@ -0,0 +1,78 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local CrucibleObject = TS.import(script, script.Parent, "crucible-object").CrucibleObject
+local _binding = TS.import(script, script.Parent, "internal", "binding")
+local boundTo = _binding.boundTo
+local defaultAccepts = _binding.defaultAccepts
+local refresh = _binding.refresh
+local remove = _binding.remove
+local readClaim = TS.import(script, script.Parent, "internal", "construction-claim").readClaim
+local installBehaviourHooks = TS.import(script, script.Parent, "internal", "hooks").installBehaviourHooks
+local _lifecycle = TS.import(script, script.Parent, "internal", "lifecycle")
+local isLive = _lifecycle.isLive
+local request = _lifecycle.request
+local stateOf = _lifecycle.stateOf
+local CrucibleBehaviour
+do
+	local super = CrucibleObject
+	CrucibleBehaviour = setmetatable({}, {
+		__tostring = function()
+			return "CrucibleBehaviour"
+		end,
+		__index = super,
+	})
+	CrucibleBehaviour.__index = CrucibleBehaviour
+	function CrucibleBehaviour:constructor()
+		super.constructor(self)
+		local state = readClaim() or error("CrucibleBehaviour constructed outside Crucible")
+		self.instance = state.instance
+	end
+	function CrucibleBehaviour:accepts(instance)
+		return defaultAccepts(instance)
+	end
+	function CrucibleBehaviour:refresh(instance)
+		refresh(instance)
+	end
+	function CrucibleBehaviour:get(instance)
+		local state = boundTo(self, instance)
+		return if state ~= nil and isLive(state) then (state.object) else nil
+	end
+	function CrucibleBehaviour:isEnabled()
+		local state = stateOf(self)
+		return state ~= nil and state.phase == 3 and isLive(state)
+	end
+	function CrucibleBehaviour:setEnabled(enabled)
+		local state = stateOf(self)
+		if state ~= nil then
+			request(state, if enabled then 0 else 1)
+		end
+	end
+	function CrucibleBehaviour:remove()
+		local state = stateOf(self)
+		if state ~= nil then
+			remove(state)
+		end
+	end
+	function CrucibleBehaviour:onEnable()
+	end
+	function CrucibleBehaviour:onDisable()
+	end
+	function CrucibleBehaviour:onDestroy()
+	end
+	do
+		installBehaviourHooks({
+			onEnable = function(b)
+				return b:onEnable()
+			end,
+			onDisable = function(b)
+				return b:onDisable()
+			end,
+			onDestroy = function(b)
+				return b:onDestroy()
+			end,
+		})
+	end
+end
+return {
+	CrucibleBehaviour = CrucibleBehaviour,
+}

package/out/crucible-object.d.ts

@@ -0,0 +1,10 @@
+export declare abstract class CrucibleObject {
+    static readonly renderPriority?: number;
+    constructor();
+    protected awake(): void;
+    protected start(): void;
+    protected fixedUpdate(_dt: number): void;
+    protected update(_dt: number): void;
+    protected lateUpdate(_dt: number): void;
+    protected preRender(_dt: number): void;
+}

package/out/crucible-object.luau

@@ -0,0 +1,69 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local readClaim = TS.import(script, script.Parent, "internal", "construction-claim").readClaim
+local _hooks = TS.import(script, script.Parent, "internal", "hooks")
+local FRAME_HOOK_NAMES = _hooks.FRAME_HOOK_NAMES
+local installObjectHooks = _hooks.installObjectHooks
+local CrucibleObject
+do
+	CrucibleObject = {}
+	function CrucibleObject:constructor()
+		local state = readClaim() or error("CrucibleObject constructed outside Crucible")
+		state.object = self
+	end
+	function CrucibleObject:awake()
+	end
+	function CrucibleObject:start()
+	end
+	function CrucibleObject:fixedUpdate(_dt)
+	end
+	function CrucibleObject:update(_dt)
+	end
+	function CrucibleObject:lateUpdate(_dt)
+	end
+	function CrucibleObject:preRender(_dt)
+	end
+	do
+		installObjectHooks({
+			awake = function(o)
+				return o:awake()
+			end,
+			start = function(o)
+				return o:start()
+			end,
+			frame = {
+				[0] = function(o, dt)
+					return o:preRender(dt)
+				end,
+				[1] = function(o, dt)
+					return o:fixedUpdate(dt)
+				end,
+				[2] = function(o, dt)
+					return o:update(dt)
+				end,
+				[3] = function(o, dt)
+					return o:lateUpdate(dt)
+				end,
+			},
+			overrides = function(klass)
+				local methods = klass
+				local defaults = CrucibleObject
+				local mask = 0
+				-- ▼ ReadonlyArray.forEach ▼
+				local _callback = function(name, hook)
+					if methods[name] ~= defaults[name] then
+						mask = bit32.bor(mask, bit32.lshift(1, hook))
+					end
+				end
+				for _k, _v in FRAME_HOOK_NAMES do
+					_callback(_v, _k - 1, FRAME_HOOK_NAMES)
+				end
+				-- ▲ ReadonlyArray.forEach ▲
+				return mask
+			end,
+		})
+	end
+end
+return {
+	CrucibleObject = CrucibleObject,
+}

package/out/data.d.ts

@@ -0,0 +1,224 @@
+import type { Readable } from "./reactive";
+declare const operationKind: unique symbol;
+declare const storeKind: unique symbol;
+declare const messageKind: unique symbol;
+declare const claimKind: unique symbol;
+declare const serverOnlyKind: unique symbol;
+/** A value a save can hold: JSON, with absent keys for values that admit `undefined`. */
+export type Json = boolean | number | string | readonly Json[] | JsonRecord;
+/** A saved record: string keys to JSON. */
+export interface JsonRecord {
+    readonly [key: string]: Json | undefined;
+}
+/**
+ * One schema step. It gets a private copy of the stored record, unknown keys included, as plain JSON, and returns a
+ * patch: an object merges into the stored object, any other value replaces the stored one, and an omitted key is kept.
+ * A step cannot delete a key. Steps are append-only and must be pure.
+ */
+export type Migration = (old: JsonRecord) => JsonRecord;
+/**
+ * The identity of one logical operation, kept across its retries. Only `operationId()` makes one; a plain string does
+ * not type-check. It carries its creation time, which bounds how long it deduplicates.
+ */
+export type OperationId = string & {
+    readonly [operationKind]: true;
+};
+/** Why a store call did not complete. */
+export type StoreFailure = "unavailable" | "timeout" | "uncertain" | "overloaded" | "full" | "expired" | "reused" | "closing";
+/** A store call's result: narrow `ok` before reading `value`. */
+export type StoreResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: StoreFailure;
+};
+/**
+ * A template field the owner's client never receives. The brand is phantom; `serverOnly(value)` also marks the value at
+ * runtime, and the declaration checks that the two agree.
+ */
+export interface ServerOnly<V> {
+    readonly [serverOnlyKind]: V;
+}
+type Scalar = string | number | boolean;
+/** What the server reads and writes: the template's type with every `ServerOnly` unwrapped, deeply readonly. */
+export type ProfileData<T> = T extends ServerOnly<infer V> ? ProfileData<V> : T extends Scalar | undefined ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<K, ProfileData<V>> : {
+    readonly [K in keyof T]: ProfileData<T[K]>;
+};
+type IsUnion<V, C = V> = V extends unknown ? ([C] extends [V] ? false : true) : never;
+/** A `ServerOnly` field, or a plain object field whose every field is server-only in turn. */
+type ServerOnlyField<V> = [V] extends [ServerOnly<unknown>] ? true : [V] extends [Scalar | undefined] ? false : [V] extends [ReadonlyMap<unknown, unknown> | readonly unknown[]] ? false : true extends IsUnion<V> ? false : string extends keyof V ? false : [keyof V] extends [never] ? false : false extends {
+    [K in keyof V]-?: ServerOnlyField<NonNullable<V[K]>>;
+}[keyof V] ? false : true;
+/**
+ * What the owner's client reads: every `ServerOnly` field removed, and every plain object left with no field, at any
+ * depth. Deeply readonly.
+ */
+export type ClientData<T> = T extends Scalar | undefined ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<K, ClientData<V>> : T extends readonly unknown[] ? {
+    readonly [K in keyof T]: ClientData<T[K]>;
+} : {
+    readonly [K in keyof T as ServerOnlyField<NonNullable<T[K]>> extends true ? never : K]: ClientData<T[K]>;
+};
+/** A store's server data type, for helper signatures: `export type PlayerData = Profile<typeof PlayerData>`. */
+export type Profile<S> = S extends ProfileStore<infer T> ? ProfileData<T> : never;
+/** A store's client data type. */
+export type ClientProfile<S> = S extends ProfileStore<infer T> ? ClientData<T> : never;
+/**
+ * A server handle's own members. `h()` reads, tracked and frozen; while the profile is not writable it returns the
+ * template's value at the path. `set` and `update` are one write each through the store's gate and return its result.
+ */
+export interface WriteHandle<V, A> extends Readable<V | A> {
+    set(value: V): boolean;
+    update(change: (current: V) => V): boolean;
+}
+/** An array handle's writes. Indices are TypeScript's, from 0. */
+export interface ArrayWrites<E> {
+    /** Inserts at `index`, from 0 to the length, or appends without one. */
+    insert(value: E, index?: number): boolean;
+    /** Removes the element at `index`, from 0 to length - 1. */
+    remove(index: number): boolean;
+}
+type DataChildren<V, A> = [V] extends [Scalar] ? unknown : [V] extends [readonly (infer E)[]] ? ArrayWrites<E> & {
+    readonly [index: number]: DataHandle<E, undefined>;
+} : true extends IsUnion<V> ? unknown : [V] extends [ReadonlyMap<string, infer E>] ? {
+    readonly [key: string]: DataHandle<E | undefined, A>;
+} : string extends keyof V ? {
+    readonly [key: string]: DataHandle<V[string & keyof V] | undefined, A>;
+} : {
+    readonly [K in keyof V]-?: DataHandle<V[K], A>;
+};
+/** A server handle at a position of type `V`: reads `V | A`, writes `V`, and reaches its children by key. */
+export type DataHandle<V, A = never> = WriteHandle<V, A> & DataChildren<NonNullable<V>, A | Extract<V, undefined>>;
+type ReadChildren<V, A> = [V] extends [Scalar] ? unknown : [V] extends [readonly (infer E)[]] ? {
+    readonly [index: number]: ReadHandle<E, undefined>;
+} : true extends IsUnion<V> ? unknown : [V] extends [ReadonlyMap<string, infer E>] ? {
+    readonly [key: string]: ReadHandle<E | undefined, A>;
+} : string extends keyof V ? {
+    readonly [key: string]: ReadHandle<V[string & keyof V] | undefined, A>;
+} : {
+    readonly [K in keyof V]-?: ReadHandle<V[K], A>;
+};
+/** A client handle: the same paths and reads as the server's, and no writes. */
+export type ReadHandle<V, A = never> = Readable<V | A> & ReadChildren<NonNullable<V>, A | Extract<V, undefined>>;
+/** Why a profile loaded. */
+export type LoadReason = "join" | "resume";
+/** Why a profile is releasing. */
+export type ReleaseReason = "leave" | "handoff" | "shutdown";
+/** A developer product purchase, read from Roblox's receipt. */
+export interface Purchase {
+    readonly id: string;
+    readonly productId: number;
+    readonly currencySpent: number;
+}
+/**
+ * A grant callback's fourth argument. It stages an effect that runs once, on a fresh thread, after the grant is durably
+ * saved and before the purchase is acknowledged; never after a refused grant.
+ */
+export type AfterGrant = (effect: () => void) => void;
+/** A field holding it is the claim. Not callable. */
+export interface ProfileClaim {
+    readonly [claimKind]: true;
+}
+/** A durable message to one player's profile, declared in a server module. Invariant in `P`. */
+export interface ProfileMessage<P> {
+    readonly [messageKind]: {
+        readonly payload: (value: P) => P;
+    };
+}
+/** One quarantined message, for recovery tooling. The payload is the stored JSON, unknown keys included. */
+export interface QuarantinedMessage {
+    readonly id: OperationId;
+    readonly name: string;
+    readonly reason: "payload" | "attempts";
+    readonly attempts: number;
+    /** The id's creation time, in wall-clock seconds. */
+    readonly sentAt: number;
+    readonly payload: Json;
+}
+/** Why a save or handoff did not confirm. */
+export type SaveFailure = "unavailable" | "timeout" | "uncertain";
+/** A save or handoff result: narrow `ok` first. */
+export type SaveResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: SaveFailure;
+};
+/**
+ * A profile store: one shared declaration, callable on both sides. The server calls it with a player for that player's
+ * writable handle; the client calls it with nothing for the local player's read-only handle.
+ */
+export interface ProfileStore<T> {
+    readonly [storeKind]: {
+        readonly kind: "profiles";
+        readonly value: (value: T) => T;
+    };
+    /** Server: the player's root handle, the same one while they are present. */
+    (player: Player): DataHandle<ProfileData<T>>;
+    /** Client: the local player's read-only root handle. */
+    (): ReadHandle<ClientData<T>>;
+    /** Server. Tracked: whether a write to the player's profile would be accepted now. */
+    loaded(player: Player): boolean;
+    /** Client. Tracked: whether the server has published this player's profile and the client holds all of it. */
+    loaded(): boolean;
+    /** Server. Tracked: the players whose profiles are writable; it changes only when one starts or stops being. */
+    players(): readonly Player[];
+    /** Server. Yields until the profile is writable (true), or its load fails, the player leaves or the server closes. */
+    await(player: Player): boolean;
+    /** Server. Yields until the current revision is durably saved, for a rare critical point. */
+    save(player: Player, timeoutSeconds?: number): SaveResult;
+    /** Server. Seals and durably releases the profile while the player stays, before a teleport. */
+    handoff(player: Player): SaveResult;
+    /** Server. After a failed teleport: waits for the handoff's release to settle, then loads again. */
+    resume(player: Player): boolean;
+    /** Server. Reads any user's saved data, with no lock and no write. */
+    inspect(userId: number): StoreResult<ProfileData<T> | undefined>;
+    /** Server. Appends a message to a user's inbox, online or not, and waits until it is durable. */
+    send<P>(userId: number, message: ProfileMessage<P>, payload: NoInfer<P>, id?: OperationId): StoreResult<undefined>;
+    /** Server. A user's quarantined messages, read with no lock. */
+    quarantined(userId: number): StoreResult<readonly QuarantinedMessage[]>;
+    /** Server. Moves listed quarantined messages back to the inbox ("retry") or drops them for good ("discard"). */
+    clearQuarantined(userId: number, ids: readonly OperationId[], action: "retry" | "discard"): StoreResult<number>;
+    /** Server claim, a Subsystem field initializer: changes a profile as it loads, before anything reads it. */
+    onLoad(transform: (player: Player, data: ProfileData<T>, reason: LoadReason) => ProfileData<T>): ProfileClaim;
+    /** Server claim: changes a profile as it releases. A claim that throws is skipped. */
+    onRelease(transform: (player: Player, data: ProfileData<T>, reason: ReleaseReason) => ProfileData<T>): ProfileClaim;
+    /** Server claim: applies a message to its target's profile, once per message id. */
+    receive<P>(message: ProfileMessage<P>, apply: (player: Player, data: ProfileData<T>, payload: P) => ProfileData<T>): ProfileClaim;
+    /** Server claim: grants a developer product. The purchase is acknowledged only after the change is saved. */
+    grant(productId: number, apply: (player: Player, data: ProfileData<T>, purchase: Purchase, afterGrant: AfterGrant) => ProfileData<T>): ProfileClaim;
+}
+/** A profile store's options. */
+export interface ProfileOptions<T> {
+    /**
+     * The store's type, by inference, and a new profile's value. A missing required key on an object path from the root
+     * takes its value from here. Admitted and frozen once, with every `serverOnly` mark unwrapped.
+     */
+    readonly template: T;
+    /** Append-only. Removing or reordering a step changes what every older record becomes. */
+    readonly migrations?: readonly Migration[];
+}
+/** The handle member names. A template key with one of these names, at any depth, does not compile. */
+export type ReservedName = "set" | "update" | "insert" | "remove";
+type ReservedKeys<T> = T extends ServerOnly<infer V> ? ReservedKeys<V> : T extends Scalar | undefined ? never : T extends ReadonlyMap<unknown, infer V> ? ReservedKeys<V> : T extends readonly (infer E)[] ? ReservedKeys<E> : string extends keyof T ? ReservedKeys<T[string & keyof T]> : (keyof T & ReservedName) | {
+    [K in keyof T]-?: ReservedKeys<T[K]>;
+}[keyof T];
+type ReservedKeyCheck<T> = [ReservedKeys<T>] extends [never] ? unknown : {
+    readonly template: {
+        readonly [K in ReservedKeys<T> as `"${K & string}" is a handle method; rename it`]: never;
+    };
+};
+/**
+ * Declares a profile store by its DataStore name. It must initialize an exported top-level const in a shared module.
+ * The type comes from `template`; annotate empty collections and optional fields with `as`.
+ */
+export declare function profileStore<T extends object>(_name: string, _options: ProfileOptions<T> & ReservedKeyCheck<T>): ProfileStore<T>;
+/** Marks a template field server-only: the owner's client never receives it. */
+export declare function serverOnly<V>(value: V): ServerOnly<V>;
+/**
+ * The exact field paths the owner's client receives, each an array of segments: an object field's key, "[]" for an
+ * array element and "*" for a map value. A key that is "[]" or "*", or starts with a backslash, gets one more backslash.
+ * Sorted segment by segment, by bytes.
+ */
+export declare function replicatedPaths<T>(store: ProfileStore<T>): readonly (readonly string[])[];
+export {};