@trioforge/crucible 0.1.0 → 0.3.0

package/out/internal/data/session.luau

@@ -0,0 +1,234 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local bootClock = TS.import(script, script.Parent.Parent, "boot").bootClock
+local _graph = TS.import(script, script.Parent.Parent, "reactive", "graph")
+local createStateNode = _graph.createStateNode
+local update = _graph.update
+local call = TS.import(script, script.Parent.Parent, "runner").call
+local admitWrite = TS.import(script, script.Parent, "admission").admitWrite
+local jsonBytes = TS.import(script, script.Parent, "envelope").jsonBytes
+local PAYLOAD_MAX_BYTES = TS.import(script, script.Parent, "limits").PAYLOAD_MAX_BYTES
+--* @internal `confirmed` before any owned write with the session's token is confirmed (rule 37). 
+local NONE = -1
+--[[
+	*
+	 * @internal
+	 *   Loading --acquired, onLoad--> Active --leave / handoff / final phase / authority lost--> Sealed --release--> Ended
+	 *   Loading --failed, left or closed: abandon only--> Ended
+	 
+]]
+--* @internal 
+--* @internal How a release settled: its write committed, or it was fenced or gave up (rule 29). 
+local callbackThreads = {}
+--* Data never writes this state: its `update` frame is what makes reactive reject a nested write (rule 13, K7). 
+local transaction = createStateNode(0)
+local depth = 0
+--[[
+	*
+	 * @internal Runs a data callback on a no-yield worker whose thread may not write data, inside the `update` of a private
+	 * reactive state so a state, publish or apply write throws (rule 13); a yield or throw is thrown here.
+	 
+]]
+local function dataCallback(work, a, b)
+	local worker
+	depth += 1
+	local status, value = call(function(x, y)
+		worker = coroutine.running()
+		local _worker = worker
+		callbackThreads[_worker] = true
+		local result
+		update(transaction, function(current)
+			result = work(x, y)
+			return current
+		end)
+		return result
+	end, a, b)
+	depth -= 1
+	if worker ~= nil then
+		local _worker = worker
+		callbackThreads[_worker] = nil
+	end
+	if status ~= 0 then
+		error(value, 0)
+	end
+	return value
+end
+--[[
+	*
+	 * @internal True while any data callback runs. Callbacks never yield, so code running then was started inside one,
+	 * on its thread or a thread it spawned (rule 123).
+	 
+]]
+local function insideDataCallback()
+	return depth > 0
+end
+--* @internal Rule 13: no data write on a data callback's own thread. 
+local function assertOutsideCallback()
+	local _arg0 = coroutine.running()
+	if callbackThreads[_arg0] ~= nil then
+		error("a write inside a data callback; return the data instead", 3)
+	end
+end
+--* @internal One player's profile on this server, and the only writer of its data (rules 12 to 16). 
+local Session
+do
+	Session = setmetatable({}, {
+		__tostring = function()
+			return "Session"
+		end,
+	})
+	Session.__index = Session
+	function Session.new(...)
+		local self = setmetatable({}, Session)
+		return self:constructor(...) or self
+	end
+	function Session:constructor(schema, player, userId, token, hooks)
+		self.schema = schema
+		self.player = player
+		self.userId = userId
+		self.token = token
+		self.hooks = hooks
+		self.phase = 0
+		self.abandoned = false
+		self.epoch = 0
+		self.safeUntil = 0
+		self.revision = 0
+		self.confirmed = NONE
+		self.op = 0
+		self.busy = false
+		self.receipts = {}
+		self.durable = {}
+		self.effects = {}
+		self.acks = {}
+		self.marks = {}
+		self.inbox = {}
+		self.retryAt = {}
+		self.carrying = NONE
+		self.lost = NONE
+		self.releaseWanted = false
+		self.releaseAmbiguous = false
+		self.renewAt = 0
+	end
+	function Session:writable()
+		return self.phase == 1 and bootClock() < self.safeUntil
+	end
+	function Session:snapshot()
+		local applied = {}
+		for id, revision in self.acks do
+			local _arg0 = { id, revision }
+			table.insert(applied, _arg0)
+		end
+		table.sort(applied, function(a, b)
+			return a[2] < b[2]
+		end)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#applied)
+		local _callback = function(_param)
+			local id = _param[1]
+			return id
+		end
+		for _k, _v in applied do
+			_newValue[_k] = _callback(_v, _k - 1, applied)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local acks = _newValue
+		local marks = {}
+		for _, mark in self.marks do
+			table.insert(marks, mark)
+		end
+		local _object = {
+			revision = self.revision,
+			schemaVersion = self.schema.version,
+			payload = self.value,
+		}
+		local _left = "receipts"
+		local _array = {}
+		local _length = #_array
+		local _array_1 = self.receipts
+		table.move(_array_1, 1, #_array_1, _length + 1, _array)
+		_object[_left] = _array
+		_object.acks = acks
+		_object.marks = marks
+		return _object
+	end
+	function Session:uncertain()
+		local ticket = self.writing
+		local _result = ticket
+		if _result ~= nil then
+			_result = _result.dispatched
+		end
+		local _condition = _result == true
+		if _condition then
+			_condition = (ticket.inFlight or ticket.ambiguous)
+		end
+		local pending = if _condition then self.carrying else NONE
+		return math.max(pending, self.lost)
+	end
+	function Session:assertIdle()
+		if self.busy then
+			error(`{self.schema.name}: {self.userId}'s profile is inside a data callback; return the data instead`, 3)
+		end
+	end
+	function Session:transact(work)
+		self:assertIdle()
+		self.busy = true
+		local ok, result = pcall(work)
+		self.busy = false
+		self.hooks.changed()
+		if not ok then
+			error(result, 0)
+		end
+		return result
+	end
+	function Session:callback(work, a, b)
+		return dataCallback(work, a, b)
+	end
+	function Session:prepare(value)
+		local admitted = admitWrite(self.schema, value)
+		local bytes = jsonBytes(admitted)
+		if bytes > PAYLOAD_MAX_BYTES then
+			error(`{self.schema.name}: {self.userId}'s profile is {bytes} bytes, over {PAYLOAD_MAX_BYTES}`, 0)
+		end
+		local _result = self.schema.check
+		if _result ~= nil then
+			_result(admitted, self.value)
+		end
+		return admitted
+	end
+	function Session:commit(value, stage)
+		self.value = value
+		local _result = stage
+		if _result ~= nil then
+			_result()
+		end
+		self.revision += 1
+	end
+	function Session:write(change, stage)
+		return self:transact(function()
+			local current = self.value
+			local result = self:callback(change, current, nil)
+			if rawequal(result, current) and stage == nil then
+				return false
+			end
+			self:commit(self:prepare(result), stage)
+			self.hooks.publish(self.value)
+			return true
+		end)
+	end
+	function Session:stage(id)
+		local _receipts = self.receipts
+		local _id = id
+		if not (table.find(_receipts, _id) ~= nil) then
+			local _receipts_1 = self.receipts
+			local _id_1 = id
+			table.insert(_receipts_1, _id_1)
+		end
+	end
+end
+return {
+	dataCallback = dataCallback,
+	insideDataCallback = insideDataCallback,
+	assertOutsideCallback = assertOutsideCallback,
+	NONE = NONE,
+	Session = Session,
+}

package/out/internal/data/shutdown.d.ts

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

package/out/internal/data/shutdown.luau

@@ -0,0 +1,91 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _boot = TS.import(script, script.Parent.Parent, "boot")
+local bootClock = _boot.bootClock
+local shutdownProgress = _boot.shutdownProgress
+local _limits = TS.import(script, script.Parent, "limits")
+local DISPATCH_CUTOFF_SECONDS = _limits.DISPATCH_CUTOFF_SECONDS
+local FINAL_PHASE_SECONDS = _limits.FINAL_PHASE_SECONDS
+local SETTLE_MARGIN_SECONDS = _limits.SETTLE_MARGIN_SECONDS
+local SHUTDOWN_FALLBACK_SECONDS = _limits.SHUTDOWN_FALLBACK_SECONDS
+local function pending(engine)
+	for _, runtime in engine.profiles do
+		for _1, session in runtime.sessions do
+			if session.phase ~= 3 then
+				return true
+			end
+		end
+	end
+	return false
+end
+--[[
+	*
+	 * @internal DataRuntime's onShutdown (rules 50 to 56), against core's deadline through E-D1. `subsystem` is the hook's
+	 * own Subsystem, excluded from `pending`; with no visible sweep the window is SHUTDOWN_FALLBACK_SECONDS.
+	 
+]]
+local function shutdownData(engine, subsystem)
+	local port = engine.port
+	local progress = if subsystem == nil then nil else shutdownProgress(subsystem)
+	local _result = progress
+	if _result ~= nil then
+		_result = _result.deadline
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = bootClock() + SHUTDOWN_FALLBACK_SECONDS
+	end
+	local deadline = _condition
+	local finalAt = deadline - FINAL_PHASE_SECONDS
+	local cutoff = deadline - DISPATCH_CUTOFF_SECONDS
+	local settleAt = deadline - SETTLE_MARGIN_SECONDS
+	engine.scheduler:setDispatchCutoff(cutoff)
+	engine.closing = true
+	engine.receipts:close()
+	for _, runtime in engine.profiles do
+		for _1, session in runtime.sessions do
+			if session.phase == 0 then
+				session.abandoned = true
+			elseif session.phase == 1 and session.revision > session.confirmed then
+				runtime:flush(session)
+			end
+		end
+	end
+	engine:wake()
+	local others = function()
+		local _result_1
+		if subsystem == nil then
+			_result_1 = 0
+		else
+			local _result_2 = shutdownProgress(subsystem)
+			if _result_2 ~= nil then
+				_result_2 = _result_2.pending
+			end
+			local _condition_1 = _result_2
+			if _condition_1 == nil then
+				_condition_1 = 0
+			end
+			_result_1 = _condition_1
+		end
+		return _result_1
+	end
+	while bootClock() < finalAt and others() > 0 do
+		port.wait(0)
+	end
+	engine.finalPhase = true
+	for _, runtime in engine.profiles do
+		for _1, session in runtime.sessions do
+			if session.phase == 1 then
+				runtime:release(session, "shutdown")
+			end
+		end
+	end
+	while bootClock() < settleAt and pending(engine) do
+		port.wait(0)
+	end
+	engine.settled = true
+	engine:wake()
+end
+return {
+	shutdownData = shutdownData,
+}

package/out/internal/data/waiters.d.ts

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

package/out/internal/data/waiters.luau

@@ -0,0 +1,65 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local bootClock = TS.import(script, script.Parent.Parent, "boot").bootClock
+--[[
+	*
+	 * @internal Threads parked until a wake or their deadline. Callers re-check their condition in a loop, so a spurious
+	 * wake costs one check. A park id guards each resume, so a stale deadline timer never resumes a later park.
+	 
+]]
+local Waiters
+do
+	Waiters = setmetatable({}, {
+		__tostring = function()
+			return "Waiters"
+		end,
+	})
+	Waiters.__index = Waiters
+	function Waiters.new(...)
+		local self = setmetatable({}, Waiters)
+		return self:constructor(...) or self
+	end
+	function Waiters:constructor(port)
+		self.port = port
+		self.parked = {}
+		self.sequence = 0
+	end
+	function Waiters:park(deadline)
+		local thread = coroutine.running()
+		self.sequence += 1
+		local id = self.sequence
+		self.parked[thread] = id
+		local fired = false
+		local timer = if deadline == nil then nil else self.port.delay(math.max(deadline - bootClock(), 0), function()
+			fired = true
+			if self.parked[thread] ~= id then
+				return nil
+			end
+			self.parked[thread] = nil
+			self.port.resume(thread)
+		end)
+		coroutine.yield()
+		self.parked[thread] = nil
+		if timer ~= nil and not fired then
+			self.port.cancel(timer)
+		end
+	end
+	function Waiters:wake()
+		local threads = {}
+		for thread, id in self.parked do
+			local _arg0 = { thread, id }
+			table.insert(threads, _arg0)
+		end
+		table.clear(self.parked)
+		table.sort(threads, function(a, b)
+			return a[2] < b[2]
+		end)
+		for _, _binding in threads do
+			local thread = _binding[1]
+			self.port.resume(thread)
+		end
+	end
+end
+return {
+	Waiters = Waiters,
+}

package/out/internal/lifecycle.luau

@@ -73,6 +73,11 @@ local function stateOf(object)
 	local _object = object
 	return states[_object]
 end
+local enablingNow
+--* @internal The generation whose Enable step is running. What it creates belongs to its enable interval. 
+local function enabling()
+	return enablingNow
+end
 --* @internal Awake, not faulted, and not asked to go. `get` and queries see only live objects. 
 local function isLive(s)
 	return s.fault == nil and s.want ~= 2 and (s.phase == 2 or s.phase == 3 or s.phase == 4)
@@ -168,6 +173,10 @@ local function release(s)
 		local _object = s.object
 		states[_object] = nil
 	end
+	local disabled = effects().disabled
+	if disabled ~= nil then
+		pcall(disabled, s)
+	end
 	local subscriptions = s.subscriptions
 	s.subscriptions = nil
 	if subscriptions == nil then
@@ -247,7 +256,10 @@ local function perform(s, step)
 		end
 		if step == 2 then
 			s.phase = 3
+			local previous = enablingNow
+			enablingNow = s
 			run(s, 2)
+			enablingNow = previous
 			return nil
 		end
 		if step == 3 then
@@ -289,6 +301,10 @@ local function perform(s, step)
 		if step == 8 then
 			s.phase = 4
 			run(s, 4)
+			local _result = fx.disabled
+			if _result ~= nil then
+				_result(s)
+			end
 			return nil
 		end
 		if step == 9 then
@@ -386,6 +402,13 @@ do
 	function Reconciler:isDraining()
 		return self.depth > 0
 	end
+	function Reconciler:open()
+		self.depth += 1
+	end
+	function Reconciler:leave()
+		self.depth -= 1
+		return self.depth == 0 and (#self.stack > 0 or #self.fresh > 0 or self.pairsQueued)
+	end
 	function Reconciler:enter(callback, a, b, owner)
 		self.depth += 1
 		local result, value = call(callback, a, b, owner)
@@ -760,6 +783,20 @@ local reconciler = Reconciler.new()
 local function isDraining()
 	return reconciler:isDraining()
 end
+--[[
+	*
+	 * @internal
+	 * Opens a scope like `within` for a caller that runs its own worker: requests made until `closeScope` wait for it.
+	 * Pair the two, with nothing between them that can throw.
+	 
+]]
+local function openScope()
+	reconciler:open()
+end
+--* @internal Closes the scope `openScope` opened. True when it was the outermost and requests wait: call `drain`. 
+local function closeScope()
+	return reconciler:leave()
+end
 --[[
 	*
 	 * @internal
@@ -841,15 +878,22 @@ end
 local function abandon()
 	reconciler:abandon()
 end
+--* @internal Forwards to the installed effects' `defer`, so networking defers ClientReady cleanups as lifecycle does. 
+local function defer(callback)
+	effects().defer(callback)
+end
 return {
 	nextStep = nextStep,
 	useEffects = useEffects,
 	stateOf = stateOf,
+	enabling = enabling,
 	isLive = isLive,
 	hasEnded = hasEnded,
 	track = track,
 	current = current,
 	isDraining = isDraining,
+	openScope = openScope,
+	closeScope = closeScope,
 	drain = drain,
 	notePairs = notePairs,
 	within = within,
@@ -858,6 +902,7 @@ return {
 	finishStart = finishStart,
 	admit = admit,
 	abandon = abandon,
+	defer = defer,
 	MAX_TRANSITIONS = MAX_TRANSITIONS,
 	MAX_AWAKE_WAVES = MAX_AWAKE_WAVES,
 	MAX_BATCHES = MAX_BATCHES,

package/out/internal/network/catalog.d.ts

@@ -0,0 +1,26 @@
+import { type Codec } from "./codec";
+import type { Node } from "./schema";
+export type MessageKind = "to-server" | "to-client" | "ask-server";
+export interface MessageSpec {
+    readonly kind: MessageKind;
+    readonly name: string;
+    readonly input: Node;
+    readonly output?: Node;
+    readonly timeout?: number;
+}
+export interface Definition {
+    readonly kind: MessageKind;
+    readonly name: string;
+    readonly input: Codec;
+    readonly output?: Codec;
+    readonly timeout: number;
+    readonly index?: number;
+}
+export declare function define(spec: MessageSpec): Definition;
+export declare function seal(): string;
+export declare function adopt(catalog: string): void;
+export declare function definitionAt(index: number): Definition | undefined;
+export declare function definitionOf(token: unknown): Definition | undefined;
+export declare function discardIndices(): void;
+export declare function unpublished(): readonly Definition[];
+export declare function catalogSize(): number;

package/out/internal/network/catalog.luau

@@ -0,0 +1,182 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local compile = TS.import(script, script.Parent, "codec").compile
+local L = TS.import(script, script.Parent, "limits")
+local definitions = {}
+local tokens = {}
+--* The framework's own messages: the only names under the reserved `Crucible.` segment (NET 3, rule 55). 
+local FRAMEWORK_MESSAGES = {
+	["Crucible.State.Fault"] = true,
+	["Crucible.State.Frame"] = true,
+}
+local names = {}
+local indices = {}
+local sealed = false
+local function validName(name)
+	local _name = name
+	local _condition = type(_name) == "string"
+	if _condition then
+		_condition = #name > 0 and #name <= L.MESSAGE_NAME_MAX_BYTES
+	end
+	assert(_condition, "invalid message name")
+	local segments = string.split(name, ".")
+	local _condition_1 = segments[1] ~= "Crucible"
+	if not _condition_1 then
+		local _name_1 = name
+		_condition_1 = FRAMEWORK_MESSAGES[_name_1] ~= nil
+	end
+	assert(_condition_1, "reserved message name")
+	for _, segment in segments do
+		local _arg0 = (string.match(segment, "^[A-Za-z][A-Za-z0-9_]*$")) ~= nil
+		assert(_arg0, "invalid message name")
+	end
+end
+local register
+local function define(spec)
+	validName(spec.name)
+	local _name = spec.name
+	local _arg0 = not (FRAMEWORK_MESSAGES[_name] ~= nil)
+	assert(_arg0, "reserved message name")
+	return register(spec)
+end
+--* @internal The trusted path: a framework message under the reserved `Crucible.` segment that game names refuse. 
+local function defineFramework(spec)
+	local _name = spec.name
+	local _arg0 = FRAMEWORK_MESSAGES[_name] ~= nil
+	assert(_arg0, "not a framework message")
+	return register(spec)
+end
+function register(spec)
+	local _arg0 = not sealed
+	local _arg1 = `{spec.name} was declared after the network catalog sealed; declare messages in modules that boot loads.`
+	assert(_arg0, _arg1)
+	local _name = spec.name
+	local _arg0_1 = not (definitions[_name] ~= nil)
+	local _arg1_1 = `duplicate message {spec.name}`
+	assert(_arg0_1, _arg1_1)
+	local _arg0_2 = spec.kind == "to-server" or spec.kind == "to-client" or spec.kind == "ask-server"
+	assert(_arg0_2, "invalid message kind")
+	local _arg0_3 = if spec.kind == "ask-server" then spec.output ~= nil else spec.output == nil and spec.timeout == nil
+	assert(_arg0_3, "invalid message options")
+	local _condition = spec.timeout
+	if _condition == nil then
+		_condition = L.DEFAULT_ASK_TIMEOUT_SECONDS
+	end
+	local timeout = _condition
+	local _arg0_4 = timeout > 0 and timeout <= L.MAX_ASK_TIMEOUT_SECONDS
+	assert(_arg0_4, "invalid ask timeout")
+	local tally = {
+		nodes = 0,
+	}
+	local definition = table.freeze(setmetatable({
+		kind = spec.kind,
+		name = spec.name,
+		input = compile(spec.input, tally),
+		output = if spec.output == nil then nil else compile(spec.output, tally),
+		timeout = timeout,
+	}, {
+		__index = function(_, key)
+			local _result
+			if key == "index" then
+				local _indices = indices
+				local _name_1 = spec.name
+				_result = _indices[_name_1]
+			else
+				_result = nil
+			end
+			return _result
+		end,
+	}))
+	local _name_1 = spec.name
+	definitions[_name_1] = definition
+	tokens[definition] = true
+	return definition
+end
+local function setNames(ordered)
+	names = ordered
+	indices = {}
+	for i = 0, #names - 1 do
+		local _indices = indices
+		local _arg0 = names[i + 1]
+		local _i = i
+		_indices[_arg0] = _i
+	end
+end
+local function seal()
+	local _arg0 = not sealed
+	assert(_arg0, "catalog already sealed")
+	-- ▼ ReadonlyMap.size ▼
+	local _size = 0
+	for _ in definitions do
+		_size += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	local _arg0_1 = _size <= L.MAX_MESSAGES
+	assert(_arg0_1, "too many messages")
+	local ordered = {}
+	for name in definitions do
+		table.insert(ordered, name)
+	end
+	table.sort(ordered)
+	setNames(ordered)
+	sealed = true
+	return table.concat(names, "\n")
+end
+local function adopt(catalog)
+	local _condition = not sealed
+	if _condition then
+		local _catalog = catalog
+		_condition = type(_catalog) == "string"
+		if _condition then
+			_condition = #catalog < L.MAX_MESSAGES * (L.MESSAGE_NAME_MAX_BYTES + 1)
+		end
+	end
+	assert(_condition, "invalid catalog")
+	local ordered = if catalog == "" then {} else string.split(catalog, "\n")
+	local _arg0 = #ordered <= L.MAX_MESSAGES
+	assert(_arg0, "too many messages")
+	for i = 0, #ordered - 1 do
+		validName(ordered[i + 1])
+		local _arg0_1 = i == 0 or ordered[i] < ordered[i + 1]
+		assert(_arg0_1, "catalog not strictly ascending")
+	end
+	setNames(ordered)
+end
+local function definitionAt(index)
+	if index < 0 or index % 1 ~= 0 or index >= #names then
+		return nil
+	end
+	local _arg0 = names[index + 1]
+	return definitions[_arg0]
+end
+local function definitionOf(token)
+	local _token = token
+	return if tokens[_token] ~= nil then token else nil
+end
+local function discardIndices()
+	sealed = false
+	setNames({})
+end
+local function unpublished()
+	local result = {}
+	for _, definition in definitions do
+		if definition.index == nil then
+			table.insert(result, definition)
+		end
+	end
+	return result
+end
+local function catalogSize()
+	return #names
+end
+return {
+	define = define,
+	defineFramework = defineFramework,
+	seal = seal,
+	adopt = adopt,
+	definitionAt = definitionAt,
+	definitionOf = definitionOf,
+	discardIndices = discardIndices,
+	unpublished = unpublished,
+	catalogSize = catalogSize,
+}