@trioforge/crucible 0.1.0 → 0.2.0

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 {};

package/out/internal/sync/frame.luau

@@ -0,0 +1,91 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local defineFramework = TS.import(script, script.Parent.Parent, "network", "catalog").defineFramework
+local n = TS.import(script, script.Parent.Parent, "network", "schema").n
+local _limits = TS.import(script, script.Parent.Parent, "reactive", "limits")
+local SYNC_FRAME_BYTES = _limits.SYNC_FRAME_BYTES
+local SYNC_FRAME_COLLECTION_ENTRIES = _limits.SYNC_FRAME_COLLECTION_ENTRIES
+local SYNC_FRAME_VALUE_VISITS = _limits.SYNC_FRAME_VALUE_VISITS
+local costOf = TS.import(script, script.Parent, "values").costOf
+--* @internal One declaration's whole value in a frame. A nil `value` is a real root `undefined`. 
+--* @internal One atomic observation unit for one peer. Both lists are strictly ascending by key. 
+--* @internal 
+local SyncFrameMessage = defineFramework({
+	kind = "to-client",
+	name = "Crucible.State.Frame",
+	input = n.object({ { "failed", n.array(n.string) }, { "kind", n.union({ n.literal("failed"), n.literal("snapshot"), n.literal("update") }) }, { "revision", n.u32 }, { "values", n.array(n.object({ { "key", n.string }, { "value", n.dynamic } })) } }),
+})
+--* @internal The last revision a client applied before its sync stopped. 
+local SyncFaultMessage = defineFramework({
+	kind = "to-server",
+	name = "Crucible.State.Fault",
+	input = n.u32,
+})
+local function varuintSize(value)
+	local size = 1
+	while value >= 128 do
+		value = math.floor(value / 128)
+		size += 1
+	end
+	return size
+end
+local function stringBytes(text)
+	return varuintSize(#text) + #text
+end
+--* @internal The whole EVENT packet `send` encodes for `frame`, with visits and entries as the decoder counts them. 
+--[[
+	*
+	 * @internal
+	 * Rule 69: the envelope (opcode, catalog index, slot count 0), then the frame object, `failed`, the kind's union
+	 * selection and literal, the u32 revision, and each value entry with its value's cached admission cost.
+	 
+]]
+local function frameCost(frame, catalogIndex)
+	local bytes = 1 + varuintSize(catalogIndex) + 1
+	local entries = #frame.failed + #frame.values
+	local visits = 1
+	visits += 1
+	bytes += varuintSize(#frame.failed)
+	for _, key in frame.failed do
+		visits += 1
+		bytes += stringBytes(key)
+	end
+	visits += 2
+	bytes += 1
+	visits += 1
+	bytes += 4
+	visits += 1
+	bytes += varuintSize(#frame.values)
+	for _, entry in frame.values do
+		visits += 2
+		bytes += stringBytes(entry.key)
+		local cost = costOf(entry.value)
+		bytes += cost.bytes
+		entries += cost.entries
+		visits += cost.visits
+	end
+	return {
+		bytes = bytes,
+		entries = entries,
+		visits = visits,
+	}
+end
+--* @internal The first frame budget `cost` passes, or undefined when it fits. 
+local function overBudget(cost)
+	if cost.bytes > SYNC_FRAME_BYTES then
+		return "SYNC_FRAME_BYTES"
+	end
+	if cost.entries > SYNC_FRAME_COLLECTION_ENTRIES then
+		return "SYNC_FRAME_COLLECTION_ENTRIES"
+	end
+	if cost.visits > SYNC_FRAME_VALUE_VISITS then
+		return "SYNC_FRAME_VALUE_VISITS"
+	end
+	return nil
+end
+return {
+	frameCost = frameCost,
+	overBudget = overBudget,
+	SyncFrameMessage = SyncFrameMessage,
+	SyncFaultMessage = SyncFaultMessage,
+}

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

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