@trioforge/crucible 0.0.0-stage → 0.2.0

package/out/internal/scheduler.luau

@@ -0,0 +1,207 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local runtimeDiagnostic = TS.import(script, script.Parent, "diagnostics").runtimeDiagnostic
+local DenseList = TS.import(script, script.Parent, "dense-list").DenseList
+local within = TS.import(script, script.Parent, "lifecycle").within
+--* @internal 
+--* @internal 
+--* @internal 
+--* @internal 
+local MAX_FIXED_STEPS = 4
+--* @internal 
+local MAX_FRAME_SECONDS = 0.25
+--* @internal 
+local function accumulate(carry, frameDt, step)
+	local total = carry + math.clamp(frameDt, 0, MAX_FRAME_SECONDS)
+	local whole = math.floor(total / step)
+	return math.min(whole, MAX_FIXED_STEPS), math.max(total - whole * step, 0)
+end
+local Lane
+do
+	Lane = setmetatable({}, {
+		__tostring = function()
+			return "Lane"
+		end,
+	})
+	Lane.__index = Lane
+	function Lane.new(...)
+		local self = setmetatable({}, Lane)
+		return self:constructor(...) or self
+	end
+	function Lane:constructor(hook, frame)
+		self.members = DenseList.new()
+		self.dt = 0
+		local caller = function(s, dt)
+			return frame[hook](s.object, dt)
+		end
+		self.visit = function(s)
+			return within(s, s, 6, caller, s, self.dt)
+		end
+	end
+	function Lane:run(dt)
+		self.dt = dt
+		self.members:forEach(self.visit)
+	end
+end
+--* @internal 
+local Scheduler
+do
+	Scheduler = setmetatable({}, {
+		__tostring = function()
+			return "Scheduler"
+		end,
+	})
+	Scheduler.__index = Scheduler
+	function Scheduler.new(...)
+		local self = setmetatable({}, Scheduler)
+		return self:constructor(...) or self
+	end
+	function Scheduler:constructor(port, config, frame)
+		self.port = port
+		self.config = config
+		self.frame = frame
+		self.renderLanes = {}
+		self.refusedClasses = {}
+		self.carry = 0
+		self.step = 1 / config.fixedRate
+		self.lanes = {
+			[0] = Lane.new(0, frame),
+			[1] = Lane.new(1, frame),
+			[2] = Lane.new(2, frame),
+			[3] = Lane.new(3, frame),
+		}
+	end
+	function Scheduler:add(s)
+		local record = s.record
+		local mask = record.hooks
+		if not self.config.renders and ((bit32.band(mask, (bit32.lshift(1, 0)))) ~= 0 or record.renderPriority ~= nil) then
+			local _refusedClasses = self.refusedClasses
+			local _id = record.id
+			if not (_refusedClasses[_id] ~= nil) then
+				local _refusedClasses_1 = self.refusedClasses
+				local _id_1 = record.id
+				_refusedClasses_1[_id_1] = true
+				runtimeDiagnostic("error", `Crucible server refuses preRender and renderPriority for {record.id}`)
+			end
+			return nil
+		end
+		if (bit32.band(mask, (bit32.lshift(1, 0)))) ~= 0 then
+			self:join(self:renderLaneOf(s), 0, s)
+		end
+		for _, hook in { 1, 2, 3 } do
+			if (bit32.band(mask, (bit32.lshift(1, hook)))) ~= 0 then
+				self:join(self.lanes[hook], hook, s)
+			end
+		end
+	end
+	function Scheduler:remove(s)
+		local priority = (s.record).renderPriority
+		local render = if priority == nil then self.lanes[0] else self.renderLanes[priority]
+		if render ~= nil and render.members:remove(s) and render.members:size() == 0 then
+			local _result = render.disconnect
+			if _result ~= nil then
+				_result()
+			end
+			render.disconnect = nil
+		end
+		local fixed = self.lanes[1]
+		if fixed.members:remove(s) and fixed.members:size() == 0 then
+			local _result = fixed.disconnect
+			if _result ~= nil then
+				_result()
+			end
+			fixed.disconnect = nil
+			self.carry = 0
+		end
+		local update = self.lanes[2]
+		local late = self.lanes[3]
+		local changed = update.members:remove(s)
+		if (late.members:remove(s) or changed) and update.members:size() == 0 and late.members:size() == 0 then
+			local _result = self.postSimulation
+			if _result ~= nil then
+				_result()
+			end
+			self.postSimulation = nil
+		end
+	end
+	function Scheduler:renderLaneOf(s)
+		local priority = (s.record).renderPriority
+		if priority == nil then
+			return self.lanes[0]
+		end
+		local lane = self.renderLanes[priority]
+		if lane == nil then
+			lane = Lane.new(0, self.frame)
+			local _renderLanes = self.renderLanes
+			local _lane = lane
+			_renderLanes[priority] = _lane
+		end
+		return lane
+	end
+	function Scheduler:join(lane, hook, s)
+		if not lane.members:add(s) then
+			return nil
+		end
+		local port = self.port
+		repeat
+			local _fallthrough = false
+			if hook == 0 then
+				if lane.disconnect ~= nil or not self.config.renders then
+					return nil
+				end
+				local priority = (s.record).renderPriority
+				local run = function(dt)
+					return lane:run(dt)
+				end
+				lane.disconnect = if priority == nil then port.onFrame(0, run) else port.bindRenderStep(`crucible:{priority}`, priority, run)
+				return nil
+			end
+			if hook == 1 then
+				if lane.disconnect ~= nil then
+					return nil
+				end
+				lane.disconnect = port.onFrame(1, function(dt)
+					local steps, carry = accumulate(self.carry, dt, self.step)
+					self.carry = carry
+					do
+						local i = 0
+						local _shouldIncrement = false
+						while true do
+							if _shouldIncrement then
+								i += 1
+							else
+								_shouldIncrement = true
+							end
+							if not (i < steps) then
+								break
+							end
+							lane:run(self.step)
+						end
+					end
+				end)
+				return nil
+			end
+			if hook == 2 then
+				_fallthrough = true
+			end
+			if _fallthrough or hook == 3 then
+				if self.postSimulation ~= nil then
+					return nil
+				end
+				local update = self.lanes[2]
+				local late = self.lanes[3]
+				self.postSimulation = port.onFrame(2, function(dt)
+					update:run(dt)
+					late:run(dt)
+				end)
+				return nil
+			end
+		until true
+	end
+end
+return {
+	accumulate = accumulate,
+	MAX_FIXED_STEPS = MAX_FIXED_STEPS,
+	MAX_FRAME_SECONDS = MAX_FRAME_SECONDS,
+	Scheduler = Scheduler,
+}

package/out/internal/state.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/state.luau

@@ -0,0 +1,41 @@
+-- Compiled with roblox-ts v3.0.0
+--* @internal Public API rule 1: a Subsystem has `awake` and `start` but no `onEnable`, `onDisable` or `onDestroy`. 
+--* @internal What lifecycle reads from a class record. The registry's records extend it. 
+--* @internal An object the `construct` effect built. Lifecycle never reads it. 
+--[[
+	*
+	 * @internal
+	 * Where one generation of an object is. A phase also records which inverse hooks are owed: from Awake on,
+	 * one `onDestroy`; in Enabled, one `onDisable`. Each step enters its phase before running its hook, so a
+	 * hook that throws part way still owes its inverse. Faulted and Destroyed are terminal.
+	 *
+	 *   Unconstructed --constructor--> Constructed --awake--> Awake --onEnable--> Enabled <--onDisable / onEnable--> Disabled
+	 *         |                             |                   |  \--(want Disabled, no hook)---------------------------^
+	 *         +--------Drop, no hooks-------+                   +--------onDestroy (from Awake or Disabled)--> Destroyed | Faulted
+	 
+]]
+--* @internal `start` runs once per generation, the first time the object is Enabled with the gate at Start. 
+--[[
+	*
+	 * @internal How far the object's batch has opened. A batch raises the gate on all its objects together, so
+	 * every object is awake before any is enabled and enabled before any starts. After its batch an object sits at Start.
+	 
+]]
+--* @internal What the outside world asked for. The latest request wins; Destroyed is absorbing. 
+--* @internal Where a failure happened. The first one is the object's primary diagnostic. 
+--* @internal One atomic move. Each runs at most one hook or changes one index. 
+--* @internal Discriminates the two kinds of entry on the work stack. 
+--* @internal The first failure, with every later failure during its cleanup attached. 
+--* @internal The inputs `nextStep` reads. Lifecycle owns every field; nothing else writes them. 
+--* @internal Runtime state of one generation. 
+--* @internal 
+--* @internal New generations going through construct, awake, enable and start together. 
+--[[
+	*
+	 * @internal
+	 * Everything a step does outside lifecycle state. Boot installs the real ones; specs install doubles.
+	 * Lifecycle runs `construct` and every hook caller through `runner.call` with the object as owner, so a throw
+	 * or a yield comes back as a failure, and `start` on its own thread.
+	 
+]]
+return nil

package/out/internal/sync/client-sync.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/sync/client-sync.luau

@@ -0,0 +1,157 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Subsystem = TS.import(script, script.Parent.Parent.Parent, "subsystem").Subsystem
+local runtimeDiagnostic = TS.import(script, script.Parent.Parent, "diagnostics").runtimeDiagnostic
+local claim = TS.import(script, script.Parent.Parent, "network", "claims").claim
+local commitPrepared = TS.import(script, script.Parent.Parent, "reactive", "graph").commitPrepared
+local define = TS.import(script, script.Parent.Parent, "registry").define
+local _declarations = TS.import(script, script.Parent, "declarations")
+local declarationNamed = _declarations.declarationNamed
+local declarations = _declarations.declarations
+local SyncFrameMessage = TS.import(script, script.Parent, "frame").SyncFrameMessage
+local reuse = TS.import(script, script.Parent, "values").reuse
+--* @internal How ClientSync reports its last applied revision: exactly `Network.send` on the fault message. 
+local sendFault = function() end
+local function ascending(keys)
+	for i = 1, #keys - 1 do
+		if not (keys[i] < keys[i + 1]) then
+			return false
+		end
+	end
+	return true
+end
+local function disjoint(values, failed)
+	local i = 0
+	local j = 0
+	while i < #values and j < #failed do
+		if values[i + 1] == failed[j + 1] then
+			return false
+		end
+		if values[i + 1] < failed[j + 1] then
+			i += 1
+		else
+			j += 1
+		end
+	end
+	return true
+end
+local ClientSync
+do
+	local super = Subsystem
+	ClientSync = setmetatable({}, {
+		__tostring = function()
+			return "ClientSync"
+		end,
+		__index = super,
+	})
+	ClientSync.__index = ClientSync
+	function ClientSync.new(...)
+		local self = setmetatable({}, ClientSync)
+		return self:constructor(...) or self
+	end
+	function ClientSync:constructor(...)
+		super.constructor(self, ...)
+		self.revision = 0
+		self.snapshotted = false
+		self.failed = false
+		self.frames = claim(self, "frames", SyncFrameMessage, function(frame)
+			return self:apply(frame)
+		end)
+	end
+	function ClientSync:apply(frame)
+		if self.failed then
+			return nil
+		end
+		if frame.kind == "failed" then
+			return self:latch(`the server stopped this client's sync at revision {frame.revision}`, false)
+		end
+		local _exp = frame.values
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#_exp)
+		local _callback = function(entry)
+			return entry.key
+		end
+		for _k, _v in _exp do
+			_newValue[_k] = _callback(_v, _k - 1, _exp)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local keys = _newValue
+		if if frame.kind == "snapshot" then self.snapshotted or frame.revision ~= 1 else not self.snapshotted then
+			return self:latch(`unexpected {frame.kind} at revision {frame.revision} after {self.revision}`, true)
+		end
+		if frame.kind == "update" and frame.revision ~= self.revision + 1 then
+			return self:latch(`revision {frame.revision} does not follow {self.revision}`, true)
+		end
+		if not ascending(keys) or not ascending(frame.failed) or not disjoint(keys, frame.failed) then
+			return self:latch(`revision {frame.revision} lists keys out of order or twice`, true)
+		end
+		local prepared, writes = pcall(function()
+			local out = {}
+			for _, entry in frame.values do
+				local declaration = declarationNamed(entry.key)
+				if declaration == nil then
+					continue
+				end
+				local reused = reuse(declaration.node.value, entry.value)
+				if not rawequal(reused, declaration.node.value) then
+					local _arg0 = { declaration.node, reused }
+					table.insert(out, _arg0)
+				end
+				local _arg0 = { declaration.status, "ready" }
+				table.insert(out, _arg0)
+			end
+			for _, key in frame.failed do
+				local declaration = declarationNamed(key)
+				if declaration ~= nil then
+					local _arg0 = { declaration.status, "failed" }
+					table.insert(out, _arg0)
+				end
+			end
+			return out
+		end)
+		if not prepared then
+			return self:latch(`internal error while preparing revision {frame.revision}: {tostring(writes)}`, true)
+		end
+		commitPrepared(writes)
+		self.snapshotted = true
+		self.revision = frame.revision
+	end
+	function ClientSync:latch(reason, fault)
+		self.failed = true
+		local _, err = pcall(function()
+			local _exp = declarations()
+			-- ▼ ReadonlyArray.map ▼
+			local _newValue = table.create(#_exp)
+			local _callback = function(declaration)
+				return { declaration.status, "failed" }
+			end
+			for _k, _v in _exp do
+				_newValue[_k] = _callback(_v, _k - 1, _exp)
+			end
+			-- ▲ ReadonlyArray.map ▲
+			return commitPrepared(_newValue)
+		end)
+		if fault then
+			pcall(sendFault, self.revision)
+		end
+		runtimeDiagnostic("error", `Crucible sync stopped: {reason}{if err == nil then "" else `; failing statuses: {tostring(err)}`}`)
+	end
+end
+local installed = false
+--* @internal Rule 56: the client entry defines ClientSync once per realm, constructed before every game Subsystem. 
+local function installClientSync(fault)
+	sendFault = fault
+	if installed then
+		return nil
+	end
+	installed = true
+	define(ClientSync, {
+		kind = "subsystem",
+		id = "Crucible.ClientSync",
+		deps = {},
+		provides = {},
+	}, true)
+end
+return {
+	installClientSync = installClientSync,
+}

package/out/internal/sync/declarations.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/sync/declarations.luau

@@ -0,0 +1,276 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local readClaim = TS.import(script, script.Parent.Parent, "construction-claim").readClaim
+local compile = TS.import(script, script.Parent.Parent, "network", "codec").compile
+local MESSAGE_NAME_MAX_BYTES = TS.import(script, script.Parent.Parent, "network", "limits").MESSAGE_NAME_MAX_BYTES
+local assertDescriptor = TS.import(script, script.Parent.Parent, "network", "schema").assertDescriptor
+local _graph = TS.import(script, script.Parent.Parent, "reactive", "graph")
+local createStateNode = _graph.createStateNode
+local guardPure = _graph.guardPure
+local readState = _graph.readState
+local readUntracked = _graph.readUntracked
+local write = _graph.write
+local MAX_REPLICATED_DECLARATIONS = TS.import(script, script.Parent.Parent, "reactive", "limits").MAX_REPLICATED_DECLARATIONS
+local _values = TS.import(script, script.Parent, "values")
+local admit = _values.admit
+local compilePlan = _values.compilePlan
+--* @internal 
+--* @internal 
+--* @internal One declaration's server write side (rules 47 to 54). 
+--* @internal 
+local byName = {}
+local handles = setmetatable({}, {
+	__mode = "k",
+})
+local ordered = {}
+local sealed = false
+local onRetired = function() end
+local function onServer()
+	return game:GetService("RunService"):IsServer()
+end
+local function perPlayer(declaration)
+	error(`{declaration.name} is per player; on the server, read the sources its publisher projects from`, 0)
+end
+local function checkName(name, framework)
+	local grammar = `use 1 to {MESSAGE_NAME_MAX_BYTES} bytes of dot-separated [A-Za-z][A-Za-z0-9_]* segments`
+	local _name = name
+	local _condition = not (type(_name) == "string")
+	if not _condition then
+		_condition = #name == 0 or #name > MESSAGE_NAME_MAX_BYTES
+	end
+	if _condition then
+		error(`Crucible replicated name {tostring(name)} is invalid: {grammar}`, 0)
+	end
+	local segments = string.split(name, ".")
+	for _, segment in segments do
+		if (string.match(segment, "^[A-Za-z][A-Za-z0-9_]*$")) == nil then
+			error(`Crucible replicated name {name} is invalid: {grammar}`, 0)
+		end
+	end
+	if (segments[1] == "Crucible") ~= framework then
+		error(if framework then `Crucible replicated name {name} is invalid: a framework declaration starts with Crucible.` else `Crucible replicated name {name} is invalid: Crucible. is reserved`, 0)
+	end
+end
+local function register(audience, name, initial, descriptor)
+	if sealed then
+		error(`{name} was declared after the replicated registry sealed; declare replicated state in modules that boot loads`, 0)
+	end
+	local _name = name
+	if byName[_name] ~= nil then
+		error(`Crucible replicated name {name} is declared twice`, 0)
+	end
+	-- ▼ ReadonlyMap.size ▼
+	local _size = 0
+	for _ in byName do
+		_size += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	if _size >= MAX_REPLICATED_DECLARATIONS then
+		error(`{name} would pass {MAX_REPLICATED_DECLARATIONS} replicated declarations in this realm`, 0)
+	end
+	assertDescriptor(descriptor)
+	compile(descriptor)
+	local plan = compilePlan(descriptor)
+	local admitted = admit(plan, name, initial)
+	local declaration = {
+		name = name,
+		audience = audience,
+		plan = plan,
+		initial = admitted,
+		node = createStateNode(admitted),
+		status = createStateNode("pending"),
+	}
+	local _name_1 = name
+	byName[_name_1] = declaration
+	table.insert(ordered, declaration)
+	table.sort(ordered, function(a, b)
+		return a.name < b.name
+	end)
+	local handle = if audience == "all" then function()
+		return readState(declaration.node)
+	end else function()
+		return if onServer() then perPlayer(declaration) else readState(declaration.node)
+	end
+	handles[handle] = declaration
+	return handle
+end
+--* @internal The emitted `replicated` and `replicatedPerPlayer` (rules 40, 41, 78). 
+local function declareReplicated(audience, name, initial, descriptor)
+	checkName(name, false)
+	return register(audience, name, initial, descriptor)
+end
+--[[
+	*
+	 * @internal
+	 * R-D1 (data rule 133): a per-player declaration only the framework makes, under the reserved `Crucible.` segment.
+	 * It counts against MAX_REPLICATED_DECLARATIONS and the duplicate check like any other.
+	 
+]]
+local function declareFrameworkReplicated(name, initial, descriptor)
+	checkName(name, true)
+	return register("player", name, initial, descriptor)
+end
+--* @internal How many more replicated declarations this realm admits (data rule 134). 
+local function replicatedCapacity()
+	-- ▼ ReadonlyMap.size ▼
+	local _size = 0
+	for _ in byName do
+		_size += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	return MAX_REPLICATED_DECLARATIONS - _size
+end
+--* @internal 
+local function declarationOf(handle)
+	local _handle = handle
+	return handles[_handle]
+end
+--* @internal 
+local function declarationNamed(name)
+	local _name = name
+	return byName[_name]
+end
+--* @internal Every declaration in this realm, by name in byte order. 
+local function declarations()
+	return ordered
+end
+--* @internal `syncStatus` (rule 45): a tracked read of the status node. 
+local function statusOf(handle)
+	local declaration = declarationOf(handle) or error("syncStatus takes a replicated declaration", 0)
+	if declaration.audience == "player" and onServer() then
+		perPlayer(declaration)
+	end
+	return readState(declaration.status)
+end
+--* @internal ServerSync registers how a retirement reaches every peer (rule 52). 
+local function useRetired(listener)
+	onRetired = listener
+end
+local function retire(declaration, publication)
+	if not publication.live then
+		return nil
+	end
+	publication.live = false
+	if declaration.audience == "all" then
+		write(declaration.status, "failed")
+	end
+	onRetired(declaration)
+end
+local function ended(declaration, publication)
+	error(`{declaration.name}'s publisher {publication.label} has ended`, 0)
+end
+local publishedMethods = {
+	set = function(self, value)
+		guardPure("write state")
+		local _binding = self
+		local declaration = _binding.declaration
+		local publication = _binding.publication
+		if not publication.live then
+			ended(declaration, publication)
+		end
+		write(declaration.node, admit(declaration.plan, declaration.name, value))
+	end,
+	update = function(self, change)
+		guardPure("write state")
+		local _binding = self
+		local declaration = _binding.declaration
+		local publication = _binding.publication
+		if not publication.live then
+			ended(declaration, publication)
+		end
+		local changed = readUntracked(function()
+			return change(declaration.node.value)
+		end, "update's callback")
+		if not publication.live then
+			ended(declaration, publication)
+		end
+		write(declaration.node, admit(declaration.plan, declaration.name, changed))
+	end,
+}
+local publishedMeta = {
+	__index = publishedMethods,
+	__call = function(handle)
+		return readState(handle.declaration.node)
+	end,
+}
+--* @internal `publish`'s runtime half (rules 47 to 50). 
+local function claimPublication(target, project)
+	local owner = readClaim()
+	if owner == nil or owner.record.kind ~= 0 then
+		error("publish runs while a server Subsystem is constructed; make it a field initializer", 0)
+	end
+	local declaration = declarationOf(target) or error("publish takes a replicated declaration", 0)
+	local label = (owner.record).id
+	local previous = declaration.publication
+	if previous ~= nil then
+		error(`{declaration.name} is published by {previous.label} and {label}; one Subsystem publishes each value`, 0)
+	end
+	if (declaration.audience == "player") ~= (project ~= nil) then
+		error(if declaration.audience == "player" then `{declaration.name} is per player; publish it with a projection` else `{declaration.name} is public; publish it without a projection`, 0)
+	end
+	local _condition = project ~= nil
+	if _condition then
+		local _project = project
+		_condition = not (type(_project) == "function")
+	end
+	if _condition then
+		error(`{declaration.name}: publish needs a projection function`, 0)
+	end
+	local publication = {
+		label = label,
+		project = project,
+		live = true,
+	}
+	declaration.publication = publication
+	if owner.subscriptions == nil then
+		owner.subscriptions = {}
+	end
+	local _exp = owner.subscriptions
+	table.insert(_exp, function()
+		return retire(declaration, publication)
+	end)
+	if declaration.audience == "player" then
+		return table.freeze({})
+	end
+	write(declaration.status, "ready")
+	return setmetatable({
+		declaration = declaration,
+		publication = publication,
+	}, publishedMeta)
+end
+--* @internal The server's registry seals with the catalog; the client's at its network commit (rule 41). 
+local function sealDeclarations()
+	sealed = true
+end
+--[[
+	*
+	 * @internal
+	 * Rule 74: retire every publication silently, restore every value to its admitted `initial` and status to
+	 * "pending", and unseal. Declarations stay registered, because their modules stay cached.
+	 
+]]
+local function rollbackDeclarations()
+	for _, declaration in ordered do
+		local publication = declaration.publication
+		if publication ~= nil then
+			publication.live = false
+		end
+		declaration.publication = nil
+		write(declaration.node, declaration.initial)
+		write(declaration.status, "pending")
+	end
+	sealed = false
+end
+return {
+	declareReplicated = declareReplicated,
+	declareFrameworkReplicated = declareFrameworkReplicated,
+	replicatedCapacity = replicatedCapacity,
+	declarationOf = declarationOf,
+	declarationNamed = declarationNamed,
+	declarations = declarations,
+	statusOf = statusOf,
+	useRetired = useRetired,
+	claimPublication = claimPublication,
+	sealDeclarations = sealDeclarations,
+	rollbackDeclarations = rollbackDeclarations,
+}

package/out/internal/sync/frame.d.ts

@@ -0,0 +1 @@
+export {};