@trioforge/crucible 0.1.0 → 0.3.0

package/out/index.d.ts

@@ -10,3 +10,11 @@ export interface BootOptions {
 }
 export { Logging, LogLevel } from "./logging";
 export type { Logger, LogRecord, LogSink, SinkSubscription, LogContext, LogProperties } from "./logging";
+export { state, computed, effect, watch, untracked, scope, onCleanup, own } from "./reactive";
+export type { Readable, State, Ownable } from "./reactive";
+export { replicated, replicatedPerPlayer, syncStatus } from "./replicated";
+export type { Replicated, ReplicatedPerPlayer, SyncStatus } from "./replicated";
+export { toServer, toClient, askServer, receive, ClientReady } from "./network";
+export type { ToServer, ToClient, AskServer, Receiver, ReceiveTarget, ReceiveCallback, AskResult, AskFailure, AskOptions, PayloadArgs, f32, f64, u8, u16, u32, } from "./network";
+export { profileStore, serverOnly, replicatedPaths } from "./data";
+export type { ProfileStore, ProfileOptions, ServerOnly, ProfileData, ClientData, Profile, ClientProfile, DataHandle, ReadHandle, WriteHandle, ArrayWrites, ReservedName, Json, JsonRecord, Migration, } from "./data";

package/out/init.luau

@@ -8,4 +8,27 @@ exports.CrucibleBehaviour = TS.import(script, script, "crucible-behaviour").Cruc
 local _logging = TS.import(script, script, "logging")
 exports.Logging = _logging.Logging
 exports.LogLevel = _logging.LogLevel
+local _reactive = TS.import(script, script, "reactive")
+exports.state = _reactive.state
+exports.computed = _reactive.computed
+exports.effect = _reactive.effect
+exports.watch = _reactive.watch
+exports.untracked = _reactive.untracked
+exports.scope = _reactive.scope
+exports.onCleanup = _reactive.onCleanup
+exports.own = _reactive.own
+local _replicated = TS.import(script, script, "replicated")
+exports.replicated = _replicated.replicated
+exports.replicatedPerPlayer = _replicated.replicatedPerPlayer
+exports.syncStatus = _replicated.syncStatus
+local _network = TS.import(script, script, "network")
+exports.toServer = _network.toServer
+exports.toClient = _network.toClient
+exports.askServer = _network.askServer
+exports.receive = _network.receive
+exports.ClientReady = _network.ClientReady
+local _data = TS.import(script, script, "data")
+exports.profileStore = _data.profileStore
+exports.serverOnly = _data.serverOnly
+exports.replicatedPaths = _data.replicatedPaths
 return exports

package/out/internal/binding.luau

@@ -27,6 +27,10 @@ local scopeTarget
 local function port()
 	return installed or error("Crucible binding used before boot")
 end
+--* @internal The port boot installed, for framework Subsystems that connect engine events. 
+local function enginePort()
+	return port()
+end
 --* @internal 
 local function useEngine(engine)
 	installed = engine
@@ -597,6 +601,7 @@ local function forget(state)
 	end
 end
 return {
+	enginePort = enginePort,
 	useEngine = useEngine,
 	defaultAccepts = defaultAccepts,
 	construct = construct,

package/out/internal/boot.luau

@@ -26,6 +26,16 @@ local records = _registry.records
 local seal = _registry.seal
 local robloxPort = TS.import(script, script.Parent, "roblox-port").robloxPort
 local Scheduler = TS.import(script, script.Parent, "scheduler").Scheduler
+local _flush = TS.import(script, script.Parent, "reactive", "flush")
+local holdBarrier = _flush.holdBarrier
+local releaseBarrier = _flush.releaseBarrier
+local useReactivePort = _flush.useReactivePort
+local endInterval = TS.import(script, script.Parent, "reactive", "ownership").endInterval
+local _declarations = TS.import(script, script.Parent, "sync", "declarations")
+local rollbackDeclarations = _declarations.rollbackDeclarations
+local sealDeclarations = _declarations.sealDeclarations
+local Logging = TS.import(script, script.Parent.Parent, "logging").Logging
+local log = Logging:getLogger("Crucible.Boot")
 --* @internal 
 local BOOT_CLASSES = { Subsystem, CrucibleBehaviour }
 --* @internal 
@@ -35,6 +45,45 @@ local PATTERN_PREFIX = "crucible-path:"
 local SHUTDOWN_DEADLINE_SECONDS = 25
 --* @internal 
 local SHUTDOWN_TIMEOUT_SECONDS = 28
+local clock
+local sweep
+--* @internal 
+--* @internal The one monotonic clock, core's and data's (data rules 25, 105). 
+local function bootClock()
+	return (clock or os.clock)()
+end
+--* @internal Undefined until the sweep has begun. 
+local function shutdownProgress(subsystem)
+	if sweep == nil then
+		return nil
+	end
+	local pending = 0
+	local notStarted = 0
+	for _, record in sweep.order do
+		local _condition = sweep.finished[record] ~= nil
+		if not _condition then
+			local _result = record.state
+			if _result ~= nil then
+				_result = _result.object
+			end
+			_condition = _result == subsystem
+		end
+		if _condition then
+			continue
+		end
+		pending += 1
+		if not (sweep.started[record] ~= nil) then
+			notStarted += 1
+		end
+	end
+	return {
+		startedAt = sweep.startTime,
+		forceStartAt = sweep.startTime + SHUTDOWN_DEADLINE_SECONDS,
+		deadline = sweep.startTime + SHUTDOWN_TIMEOUT_SECONDS,
+		pending = pending,
+		notStarted = notStarted,
+	}
+end
 --* @internal 
 local function parsePattern(pattern)
 	local _pattern = pattern
@@ -214,6 +263,12 @@ local function shutdown(port, order)
 		end
 	end
 	local startTime = port.clock()
+	sweep = {
+		startTime = startTime,
+		order = order,
+		started = started,
+		finished = finished,
+	}
 	while true do
 		-- ▼ ReadonlySet.size ▼
 		local _size = 0
@@ -287,6 +342,8 @@ local function shutdown(port, order)
 end
 --* @internal 
 local function ignite(port, side, options)
+	clock = port.clock
+	sweep = nil
 	local singletons = seal({
 		renders = side.renders,
 	})
@@ -330,6 +387,8 @@ local function ignite(port, side, options)
 		end
 	end
 	useEngine(port)
+	holdBarrier()
+	useReactivePort(port)
 	useImplementerPort(port)
 	useEffects({
 		construct = function(s)
@@ -391,6 +450,7 @@ local function ignite(port, side, options)
 		diagnose = function(s, hook, err)
 			return runtimeDiagnostic("error", `{where(port, s)} {HOOK_NAMES[hook + 1]} failed: {tostring(err)}`)
 		end,
+		disabled = endInterval,
 	})
 	local ok, err = pcall(function()
 		local _exp_1 = records()
@@ -427,6 +487,36 @@ local function ignite(port, side, options)
 	if not ok then
 		reject(tostring(err))
 	end
+	if failure == nil then
+		local unbooted = nil
+		local finalized, finalizeErr = pcall(function()
+			-- Roblox cannot unbind BindToClose, so the callback checks that this boot committed.
+			if side.name == "server" then
+				port.bindToClose(function()
+					if stage ~= "committed" then
+						return nil
+					end
+					shutdown(port, singletons)
+					side.network:close()
+				end)
+			end
+			unbooted = side.booted()
+			if side.name == "client" then
+				sealDeclarations()
+			end
+			side.network:commit()
+		end)
+		if not finalized then
+			local undo = unbooted
+			if undo ~= nil then
+				local undone, undoErr = pcall(undo)
+				if not undone then
+					runtimeDiagnostic("error", `Crucible: undoing booted failed: {tostring(undoErr)}`)
+				end
+			end
+			reject(`boot finalization failed: {tostring(finalizeErr)}`)
+		end
+	end
 	if failure ~= nil then
 		for s in owned do
 			if not hasEnded(s) then
@@ -435,23 +525,37 @@ local function ignite(port, side, options)
 		end
 		drain()
 		table.clear(owned)
+		releaseBarrier()
 		error(`Crucible boot failed: {failure}`, 0)
 	end
 	stage = "committed"
 	table.clear(owned)
-	if side.name == "server" then
-		port.bindToClose(function()
-			return shutdown(port, singletons)
-		end)
-	end
-	side.booted()
+	releaseBarrier()
 end
 --* @internal 
 local function boot(side, options)
-	load(options.load)
-	ignite(robloxPort(), side, options)
+	local ok, err = pcall(function()
+		side.network:open()
+		load(options.load)
+		side.network:loaded()
+		if side.name == "server" then
+			sealDeclarations()
+		end
+		ignite(robloxPort(), side, options)
+	end)
+	if ok then
+		log:debug("Crucible booted on the {side}", {
+			side = side.name,
+		})
+		return nil
+	end
+	side.network:close()
+	rollbackDeclarations()
+	error(err, 0)
 end
 return {
+	bootClock = bootClock,
+	shutdownProgress = shutdownProgress,
 	parsePattern = parsePattern,
 	load = load,
 	ignite = ignite,

package/out/internal/configs/limits.d.ts

@@ -0,0 +1,10 @@
+export declare const MAX_CONFIG_DECLARATIONS = 1000;
+export declare const CONFIG_NAME_MAX_BYTES = 64;
+export declare const CONFIG_VALUE_MAX_BYTES = 100000;
+export declare const CONFIG_ADMISSION_VISITS = 100000;
+export declare const CONFIG_REQUEST_CONCURRENCY = 4;
+export declare const CONFIG_FETCH_RETRY_BASE_SECONDS = 1;
+export declare const CONFIG_FETCH_RETRY_CAP_SECONDS = 30;
+export declare const CONFIG_REFRESH_TIMEOUT_SECONDS = 10;
+export declare const CONFIG_VALUE_DEPTH = 28;
+export declare const CONFIG_STRING_MAX_BYTES = 65536;

package/out/internal/configs/limits.luau

@@ -0,0 +1,25 @@
+-- Compiled with roblox-ts v3.0.0
+local MAX_CONFIG_DECLARATIONS = 1_000
+local CONFIG_NAME_MAX_BYTES = 64
+local CONFIG_VALUE_MAX_BYTES = 100_000
+local CONFIG_ADMISSION_VISITS = 100_000
+local CONFIG_REQUEST_CONCURRENCY = 4
+local CONFIG_FETCH_RETRY_BASE_SECONDS = 1
+local CONFIG_FETCH_RETRY_CAP_SECONDS = 30
+local CONFIG_REFRESH_TIMEOUT_SECONDS = 10
+-- Rule 97 admits configs by rule 76's walk, whose depth and string bounds are data's PERSIST_DEPTH and
+-- PERSIST_STRING_BYTES. Data's limits module is not under configs yet, so the values are restated here.
+local CONFIG_VALUE_DEPTH = 28
+local CONFIG_STRING_MAX_BYTES = 65_536
+return {
+	MAX_CONFIG_DECLARATIONS = MAX_CONFIG_DECLARATIONS,
+	CONFIG_NAME_MAX_BYTES = CONFIG_NAME_MAX_BYTES,
+	CONFIG_VALUE_MAX_BYTES = CONFIG_VALUE_MAX_BYTES,
+	CONFIG_ADMISSION_VISITS = CONFIG_ADMISSION_VISITS,
+	CONFIG_REQUEST_CONCURRENCY = CONFIG_REQUEST_CONCURRENCY,
+	CONFIG_FETCH_RETRY_BASE_SECONDS = CONFIG_FETCH_RETRY_BASE_SECONDS,
+	CONFIG_FETCH_RETRY_CAP_SECONDS = CONFIG_FETCH_RETRY_CAP_SECONDS,
+	CONFIG_REFRESH_TIMEOUT_SECONDS = CONFIG_REFRESH_TIMEOUT_SECONDS,
+	CONFIG_VALUE_DEPTH = CONFIG_VALUE_DEPTH,
+	CONFIG_STRING_MAX_BYTES = CONFIG_STRING_MAX_BYTES,
+}

package/out/internal/configs/port.d.ts

@@ -0,0 +1,29 @@
+import type { Disconnect } from "../port";
+export interface ConfigSnapshotPort {
+    /** `GetValue`: nil for a missing key. A JSON config may arrive as a table or as its text. */
+    readonly get: (key: string) => unknown;
+    /** `Refresh`. Yields and may throw. */
+    readonly refresh: () => void;
+    /** Unmeasured in Studio: whether this turns true without `UpdateAvailable`. Runtime treats the two as independent. */
+    readonly outdated: () => boolean;
+    /** `Error` is `LoadFailed`. */
+    readonly failed: () => boolean;
+    readonly onUpdateAvailable: (listener: () => void) => Disconnect;
+}
+/** What configs ask of the engine. Requests yield and may throw. */
+export interface ConfigPort {
+    readonly global: () => ConfigSnapshotPort;
+    readonly forPlayer: (player: Player) => ConfigSnapshotPort;
+    readonly players: () => readonly Player[];
+    readonly onPlayerAdded: (listener: (player: Player) => void) => Disconnect;
+    readonly onPlayerRemoving: (listener: (player: Player) => void) => Disconnect;
+    readonly wait: (seconds: number) => void;
+    /** Uniform in [0, 1). */
+    readonly random: () => number;
+    readonly decodeJson: (text: string) => unknown;
+    /** The JSON text length of a decoded value. Throws for a value JSON cannot hold. */
+    readonly jsonBytes: (value: object) => number;
+}
+export declare function installConfigPort(value: ConfigPort): void;
+export declare function configPort(): ConfigPort;
+export declare function createRobloxConfigPort(): ConfigPort;

package/out/internal/configs/port.luau

@@ -0,0 +1,99 @@
+-- Compiled with roblox-ts v3.0.0
+--* What configs ask of the engine. Requests yield and may throw. 
+local port
+local function installConfigPort(value)
+	local _arg0 = port == nil
+	assert(_arg0, "Config port already selected")
+	port = value
+end
+local createRobloxConfigPort
+local function configPort()
+	if port == nil then
+		port = createRobloxConfigPort()
+	end
+	return port
+end
+local EMPTY = table.freeze({
+	get = function()
+		return nil
+	end,
+	refresh = function() end,
+	outdated = function()
+		return false
+	end,
+	failed = function()
+		return false
+	end,
+	onUpdateAvailable = function()
+		return function() end
+	end,
+})
+local function snapshotPort(snapshot)
+	return {
+		get = function(key)
+			return snapshot:GetValue(key)
+		end,
+		refresh = function()
+			return snapshot:Refresh()
+		end,
+		outdated = function()
+			return snapshot.Outdated
+		end,
+		failed = function()
+			return snapshot.Error == Enum.ConfigSnapshotErrorState.LoadFailed
+		end,
+		onUpdateAvailable = function(listener)
+			local connection = snapshot.UpdateAvailable:Connect(listener)
+			return function()
+				return connection:Disconnect()
+			end
+		end,
+	}
+end
+function createRobloxConfigPort()
+	local players = game:GetService("Players")
+	local http = game:GetService("HttpService")
+	local live = not game:GetService("RunService"):IsStudio() or game:GetService("ServerStorage"):GetAttribute("CrucibleLiveData") == true
+	local service = if live then game:GetService("ConfigService") else nil
+	local random = Random.new()
+	return {
+		global = function()
+			return if service == nil then EMPTY else snapshotPort(service:GetConfigAsync())
+		end,
+		forPlayer = function(player)
+			return if service == nil then EMPTY else snapshotPort(service:GetConfigForPlayerAsync(player))
+		end,
+		players = function()
+			return players:GetPlayers()
+		end,
+		onPlayerAdded = function(listener)
+			local connection = players.PlayerAdded:Connect(listener)
+			return function()
+				return connection:Disconnect()
+			end
+		end,
+		onPlayerRemoving = function(listener)
+			local connection = players.PlayerRemoving:Connect(listener)
+			return function()
+				return connection:Disconnect()
+			end
+		end,
+		wait = function(seconds)
+			task.wait(seconds)
+		end,
+		random = function()
+			return random:NextNumber()
+		end,
+		decodeJson = function(text)
+			return http:JSONDecode(text)
+		end,
+		jsonBytes = function(value)
+			return #http:JSONEncode(value)
+		end,
+	}
+end
+return {
+	installConfigPort = installConfigPort,
+	configPort = configPort,
+	createRobloxConfigPort = createRobloxConfigPort,
+}

package/out/internal/configs/runtime.d.ts

@@ -0,0 +1,21 @@
+import { type Node } from "../network/schema";
+import { type StateNode } from "../reactive/graph";
+export type ConfigKind = "global" | "player";
+/** One value a reader sees. Commit is its only writer. */
+/** A config value as reactive state, so a read is tracked (rule 93) and a commit wakes its readers once. */
+type Cell = StateNode;
+export interface Declaration {
+    readonly name: string;
+    readonly kind: ConfigKind;
+    readonly node: Node;
+    readonly fallback: unknown;
+    /** The value admitted from the global snapshot. */
+    readonly global: Cell;
+}
+export declare function declare(name: string, kind: ConfigKind, fallback: unknown, node: Node): Declaration;
+export declare function readGlobal(declaration: Declaration): unknown;
+export declare function readPlayer(declaration: Declaration, player: Player): unknown;
+export declare function ready(player?: Player): boolean;
+export declare function refresh(): boolean;
+export declare function installConfigRuntime(): void;
+export {};