@trioforge/crucible 0.1.0 → 0.3.0

package/out/internal/data/declarations.luau

@@ -0,0 +1,384 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _schema = TS.import(script, script.Parent.Parent, "network", "schema")
+local assertDescriptor = _schema.assertDescriptor
+local n = _schema.n
+local readState = TS.import(script, script.Parent.Parent, "reactive", "graph").readState
+local MAX_REPLICATED_DECLARATIONS = TS.import(script, script.Parent.Parent, "reactive", "limits").MAX_REPLICATED_DECLARATIONS
+local _declarations = TS.import(script, script.Parent.Parent, "sync", "declarations")
+local declarationOf = _declarations.declarationOf
+local declareFrameworkReplicated = _declarations.declareFrameworkReplicated
+local replicatedCapacity = _declarations.replicatedCapacity
+local _values = TS.import(script, script.Parent.Parent, "sync", "values")
+local admitReplicated = _values.admit
+local compilePlan = _values.compilePlan
+local sealSchema = TS.import(script, script.Parent, "admission").sealSchema
+local rootHandle = TS.import(script, script.Parent, "handles").rootHandle
+local _limits = TS.import(script, script.Parent, "limits")
+local LIVE_NAME_PREFIX = _limits.LIVE_NAME_PREFIX
+local MAX_DATA_DECLARATIONS = _limits.MAX_DATA_DECLARATIONS
+local MAX_PROFILE_STORES = _limits.MAX_PROFILE_STORES
+local VIEW_NAME_MAX_BYTES = _limits.VIEW_NAME_MAX_BYTES
+local VIEW_NAME_PREFIX = _limits.VIEW_NAME_PREFIX
+local _paths = TS.import(script, script.Parent, "paths")
+local fieldPaths = _paths.fieldPaths
+local getPath = _paths.getPath
+local pathLess = _paths.pathLess
+local samePath = _paths.samePath
+local showPath = _paths.showPath
+local _record_declarations = TS.import(script, script.Parent, "record-declarations")
+local checkStoreName = _record_declarations.checkStoreName
+local dataDeclarationCount = _record_declarations.dataDeclarationCount
+local dataRegistrySealed = _record_declarations.dataRegistrySealed
+local registerProfileName = _record_declarations.registerProfileName
+local storeNameTaken = _record_declarations.storeNameTaken
+--* @internal One top-level field the owner's client receives, and its view declaration (rules 125, 134). 
+--* @internal A profile store as both realms know it, built once at module evaluation (rule 4). 
+--* @internal What the server entry installs so a shared declaration reaches the durability engine (rule 115). 
+--[[
+	*
+	 * The record a store carries in its metatable. The key is a string, not a private table, so `replicatedPaths` reads a
+	 * declaration made by another module set (rule 131).
+	 
+]]
+local RECORD = "__crucibleProfileStore"
+local profiles = {}
+local clientRoots = {}
+local serverSide
+local markMeta = {}
+--* @internal `serverOnly(value)`: a frozen mark recognized by its private metatable (rule 129). 
+local function markServerOnly(value)
+	return table.freeze(setmetatable({
+		value = value,
+	}, markMeta))
+end
+local function isMark(value)
+	local _value = value
+	local _condition = type(_value) == "table"
+	if _condition then
+		_condition = getmetatable(value) == markMeta
+	end
+	return _condition
+end
+--* Replaces every mark by the value it wraps, recording where each one sat as an array of keys (rule 4). 
+local function unwrap(value, path, found)
+	if isMark(value) then
+		local _found = found
+		local _path = path
+		table.insert(_found, _path)
+		return unwrap(value.value, path, found)
+	end
+	local _value = value
+	local _condition = not (type(_value) == "table")
+	if not _condition then
+		_condition = getmetatable(value) ~= nil
+	end
+	if _condition then
+		return value
+	end
+	local copy
+	for key, entry in pairs(value) do
+		local _array = {}
+		local _length = #_array
+		local _pathLength = #path
+		table.move(path, 1, _pathLength, _length + 1, _array)
+		_length += _pathLength
+		_array[_length + 1] = tostring(key)
+		local inner = unwrap(entry, _array, found)
+		if rawequal(inner, entry) then
+			continue
+		end
+		if copy == nil then
+			copy = table.clone(value)
+		end
+		copy[key] = inner
+	end
+	return copy or value
+end
+local function checkMarks(name, found, expected)
+	local _array = {}
+	local _length = #_array
+	table.move(found, 1, #found, _length + 1, _array)
+	table.sort(_array, pathLess)
+	local marked = _array
+	local _array_1 = {}
+	local _length_1 = #_array_1
+	table.move(expected, 1, #expected, _length_1 + 1, _array_1)
+	table.sort(_array_1, pathLess)
+	local typed = _array_1
+	for _, path in marked do
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(other)
+			return samePath(other, path)
+		end
+		for _k, _v in typed do
+			if _callback(_v, _k - 1, typed) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		if not _result then
+			error(`{name} {showPath(path)} is marked serverOnly in its template value but not in its type`, 0)
+		end
+	end
+	for _, path in typed do
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(other)
+			return samePath(other, path)
+		end
+		for _k, _v in marked do
+			if _callback(_v, _k - 1, marked) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		if not _result then
+			error(`{name} {showPath(path)} is serverOnly in its type but its template value is not marked`, 0)
+		end
+	end
+end
+--* A field view's descriptor: the field's replica node admitting undefined (rule 125). 
+local function admittingUndefined(node)
+	if node.kind == "union" then
+		for _, branch in node.branches do
+			if branch.kind == "nil" then
+				return node
+			end
+		end
+		local _array = { n["nil"] }
+		local _length = #_array
+		local _array_1 = node.branches
+		table.move(_array_1, 1, #_array_1, _length + 1, _array)
+		return n.union(_array)
+	end
+	return n.union({ n["nil"], node })
+end
+--* Rules 2 and 134: every view name is checked, and the realm's room counted, before any is declared. 
+local function declareViews(name, replica)
+	local prefix = `{VIEW_NAME_PREFIX}{name}.`
+	for _, _binding in replica.fields do
+		local field = _binding[1]
+		if (string.match(field, "^[A-Za-z][A-Za-z0-9_]*$")) == nil then
+			error(`{name}["{field}"]: a field the owner's client receives is named by one segment, [A-Za-z][A-Za-z0-9_]*; rename it or mark it serverOnly`, 0)
+		end
+		local view = prefix .. field
+		if #view > VIEW_NAME_MAX_BYTES then
+			error(`{name}.{field}: its view name {view} is {#view} bytes, over {VIEW_NAME_MAX_BYTES}; this store allows field names of at most {VIEW_NAME_MAX_BYTES - #prefix} bytes`, 0)
+		end
+	end
+	local needed = 1 + #replica.fields
+	local room = replicatedCapacity()
+	if room < needed then
+		error(`{name} needs {needed} replicated declarations; {MAX_REPLICATED_DECLARATIONS - room} of {MAX_REPLICATED_DECLARATIONS} are in use`, 0)
+	end
+	local live = declareFrameworkReplicated(`{LIVE_NAME_PREFIX}{name}`, false, n.bool)
+	local _exp = replica.fields
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#_exp)
+	local _callback = function(_param)
+		local field = _param[1]
+		local node = _param[2]
+		local handle = declareFrameworkReplicated(prefix .. field, nil, admittingUndefined(node))
+		return {
+			name = field,
+			handle = handle,
+			declaration = declarationOf(handle),
+		}
+	end
+	for _k, _v in _exp do
+		_newValue[_k] = _callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local fields = _newValue
+	return {
+		live = live,
+		fields = fields,
+	}
+end
+local function clientSource(declaration)
+	local byName = {}
+	for _, field in declaration.fields do
+		local _name = field.name
+		byName[_name] = field
+	end
+	return {
+		name = declaration.name,
+		client = true,
+		beforeRead = function(self) end,
+		write = function(self)
+			error(`{declaration.name}() is read-only on the client`, 3)
+		end,
+		read = function(self, path)
+			local live = readState(declaration.liveDeclaration.node) == true
+			if #path == 0 then
+				if not live then
+					return declaration.clientTemplate
+				end
+				local root = {}
+				for _, field in declaration.fields do
+					root[field.name] = readState(field.declaration.node)
+				end
+				return table.freeze(root)
+			end
+			local _arg0 = path[1]
+			local field = byName[_arg0]
+			if live and field ~= nil then
+				return getPath(readState(field.declaration.node), path, 1)
+			end
+			return getPath(declaration.clientTemplate, path)
+		end,
+	}
+end
+--* @internal Rule 124: the local player's root handle, made once per realm. 
+local function clientRoot(declaration)
+	local _declaration = declaration
+	local root = clientRoots[_declaration]
+	if root == nil then
+		root = rootHandle(clientSource(declaration), declaration.replica)
+		local _declaration_1 = declaration
+		local _root = root
+		clientRoots[_declaration_1] = _root
+	end
+	return root
+end
+--* @internal Rule 126: tracked; the lifecycle is ready and true, and every field view is ready. 
+local function clientLoaded(declaration)
+	local live = declaration.liveDeclaration
+	if readState(live.status) ~= "ready" or readState(live.node) ~= true then
+		return false
+	end
+	for _, field in declaration.fields do
+		if readState(field.declaration.status) ~= "ready" then
+			return false
+		end
+	end
+	return true
+end
+local function storeMeta(declaration)
+	local name = declaration.name
+	local meta = {
+		__call = function(_, ...)
+			local args = { ... }
+			local player = args[1]
+			if serverSide ~= nil then
+				if player == nil then
+					error(`{name} is per player on the server; call {name}(player)`, 2)
+				end
+				return serverSide.root(declaration, player)
+			end
+			if #args > 0 then
+				error(`a client reads only its own profile; call {name}()`, 2)
+			end
+			return clientRoot(declaration)
+		end,
+		__index = function(_, key)
+			if serverSide ~= nil then
+				return serverSide.member(declaration, key)
+			end
+			if key == "loaded" then
+				return function(_store, player)
+					if player ~= nil then
+						error(`{name}.loaded(player) is server-only; the client reads {name}.loaded()`, 2)
+					end
+					return clientLoaded(declaration)
+				end
+			end
+			return function()
+				return error(`{name}.{tostring(key)} is server-only`, 2)
+			end
+		end,
+		__newindex = function()
+			return error(`{name} is a profile store; it has no fields to assign`, 2)
+		end,
+	}
+	meta[RECORD] = declaration
+	return meta
+end
+--[[
+	*
+	 * @internal The emitted `profileStore` (rules 1 to 4, 129, 131, 134). Shared-safe: it touches no service and starts
+	 * nothing, and every check runs before anything registers.
+	 
+]]
+local function declareProfileStore(name, template, migrations, persist, replica, serverOnlyPaths)
+	checkStoreName(name)
+	if dataRegistrySealed() then
+		error(`{name} was declared after the data registry sealed; declare stores in modules that boot loads`, 3)
+	end
+	if storeNameTaken(name) then
+		error(`{name} is already declared`, 3)
+	end
+	if #profiles >= MAX_PROFILE_STORES then
+		error(`{name}: more than {MAX_PROFILE_STORES} profile stores`, 3)
+	end
+	if dataDeclarationCount() >= MAX_DATA_DECLARATIONS then
+		error(`{name}: more than {MAX_DATA_DECLARATIONS} data declarations`, 3)
+	end
+	assertDescriptor(persist)
+	assertDescriptor(replica)
+	if replica.kind ~= "object" then
+		error(`{name}: a profile store's value is an object with declared fields`, 3)
+	end
+	local found = {}
+	local unwrapped = unwrap(template, {}, found)
+	checkMarks(name, found, serverOnlyPaths)
+	local _array = {}
+	local _length = #_array
+	local _array_1 = (migrations or {})
+	table.move(_array_1, 1, #_array_1, _length + 1, _array)
+	local steps = _array
+	local schema = sealSchema({
+		name = name,
+		version = #steps,
+		defaults = unwrapped,
+		node = persist,
+		migrations = steps,
+	})
+	local clientTemplate = admitReplicated(compilePlan(replica), name, schema.defaults)
+	local views = declareViews(name, replica)
+	local declaration = {
+		name = name,
+		persist = persist,
+		replica = replica,
+		schema = schema,
+		clientTemplate = clientTemplate,
+		live = views.live,
+		liveDeclaration = declarationOf(views.live),
+		fields = views.fields,
+		paths = fieldPaths(replica),
+	}
+	registerProfileName(name)
+	table.insert(profiles, declaration)
+	return table.freeze(setmetatable({}, storeMeta(declaration)))
+end
+--* @internal Rule 131: the replica's paths, read from the store's own metatable, never a registry. 
+local function replicatedPathsOf(store)
+	local _store = store
+	local meta = if type(_store) == "table" then (getmetatable(store)) else nil
+	local declaration = if type(meta) == "table" then (meta[RECORD]) else nil
+	if declaration == nil then
+		error("replicatedPaths takes a profile store", 2)
+	end
+	return declaration.paths
+end
+--* @internal This realm's profile stores, in registration order; DataRuntime binds each when it constructs (104). 
+local function profileDeclarations()
+	return profiles
+end
+--* @internal The server entry installs its side once per realm, when its module loads (rule 115). 
+local function installServerSide(side)
+	serverSide = side
+end
+return {
+	markServerOnly = markServerOnly,
+	clientRoot = clientRoot,
+	clientLoaded = clientLoaded,
+	declareProfileStore = declareProfileStore,
+	replicatedPathsOf = replicatedPathsOf,
+	profileDeclarations = profileDeclarations,
+	installServerSide = installServerSide,
+}

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

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

package/out/internal/data/envelope.luau

@@ -0,0 +1,318 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _limits = TS.import(script, script.Parent, "limits")
+local INBOX_MAX_MESSAGES = _limits.INBOX_MAX_MESSAGES
+local MAX_PURCHASE_IDS = _limits.MAX_PURCHASE_IDS
+local OPERATION_ID_MAX_BYTES = _limits.OPERATION_ID_MAX_BYTES
+local OPERATION_MARKERS_PER_KEY = _limits.OPERATION_MARKERS_PER_KEY
+local PURCHASE_ID_MAX_BYTES = _limits.PURCHASE_ID_MAX_BYTES
+local QUARANTINE_MAX_MESSAGES = _limits.QUARANTINE_MAX_MESSAGES
+local SEEN_MAX_MESSAGES = _limits.SEEN_MAX_MESSAGES
+--* @internal 
+--* @internal The last owned operation that committed (rule 28). 
+--* @internal 
+--* @internal 
+--* @internal 
+--* @internal One JSON value per key (rule 38). `payload` is the stored record exactly; bookkeeping is never inside it. 
+--* @internal 
+local UNREADABLE = {}
+local function fail(reason)
+	error({ UNREADABLE, reason })
+end
+local function counter(value, name)
+	local _value = value
+	local _condition = not (type(_value) == "number")
+	if not _condition then
+		_condition = value < 0 or value % 1 ~= 0
+	end
+	if _condition then
+		fail(`bad {name}`)
+	end
+	return value
+end
+local function time(value, name)
+	local _value = value
+	local _condition = not (type(_value) == "number")
+	if not _condition then
+		_condition = value ~= value or value < 0
+	end
+	if _condition then
+		fail(`bad {name}`)
+	end
+	return value
+end
+local function text(value, name, max)
+	if max == nil then
+		max = math.huge
+	end
+	local _value = value
+	local _condition = not (type(_value) == "string")
+	if not _condition then
+		_condition = #value == 0 or #value > max
+	end
+	if _condition then
+		fail(`bad {name}`)
+	end
+	return value
+end
+--* Counts entries before reading any, stopping at the first one past `cap`. 
+local function list(value, name, cap)
+	if value == nil then
+		return {}
+	end
+	local _value = value
+	if not (type(_value) == "table") then
+		fail(`bad {name}`)
+	end
+	local count = 0
+	for key in pairs(value) do
+		count += 1
+		if count > cap then
+			fail(`{name} over {cap}`)
+		end
+		if not (type(key) == "number") or key % 1 ~= 0 or key < 1 then
+			fail(`bad {name}`)
+		end
+	end
+	local items = value
+	if #items ~= count then
+		fail(`bad {name}`)
+	end
+	return items
+end
+local function ids(value, name, cap, max)
+	local _exp = list(value, name, cap)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#_exp)
+	local _callback = function(id)
+		return text(id, `{name} id`, max)
+	end
+	for _k, _v in _exp do
+		_newValue[_k] = _callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	return _newValue
+end
+local function item(raw, name)
+	local _raw = raw
+	if not (type(_raw) == "table") then
+		fail(`bad {name} item`)
+	end
+	local t = raw
+	return {
+		id = text(t.id, `{name} id`, OPERATION_ID_MAX_BYTES),
+		name = text(t.name, `{name} name`),
+		version = counter(t.version, `{name} version`),
+		payload = t.payload,
+		generation = counter(t.generation, `{name} generation`),
+		attempts = counter(t.attempts, `{name} attempts`),
+	}
+end
+local function readEnvelope(raw, kind)
+	local _raw = raw
+	if not (type(_raw) == "table") then
+		fail("not a table")
+	end
+	local t = raw
+	if t.format ~= 1 then
+		fail("bad format")
+	end
+	if t.kind ~= kind then
+		fail("bad kind")
+	end
+	local payload = t.payload
+	if payload ~= nil and not (type(payload) == "table") then
+		fail("bad payload")
+	end
+	local lease
+	if t.lease ~= nil then
+		local _lease = t.lease
+		if not (type(_lease) == "table") then
+			fail("bad lease")
+		end
+		local l = t.lease
+		local _object = {
+			token = text(l.token, "lease token"),
+			serverId = text(l.serverId, "lease server"),
+		}
+		local _left = "jobId"
+		local _jobId = l.jobId
+		_object[_left] = if type(_jobId) == "string" then l.jobId else fail("bad lease job")
+		_object.expiresAt = time(l.expiresAt, "lease expiry")
+		lease = _object
+	end
+	local commit
+	if t.commit ~= nil then
+		local _commit = t.commit
+		if not (type(_commit) == "table") then
+			fail("bad commit")
+		end
+		local c = t.commit
+		commit = {
+			token = text(c.token, "commit token"),
+			revision = counter(c.revision, "commit revision"),
+			op = counter(c.op, "commit op"),
+		}
+	end
+	local _object = {
+		format = 1,
+		kind = kind,
+		schemaVersion = counter(t.schemaVersion, "schemaVersion"),
+		payload = payload,
+		epoch = counter(t.epoch, "epoch"),
+		lease = lease,
+		commit = commit,
+		receipts = ids(t.receipts, "receipts", MAX_PURCHASE_IDS, PURCHASE_ID_MAX_BYTES),
+	}
+	local _left = "inbox"
+	local _exp = list(t.inbox, "inbox", INBOX_MAX_MESSAGES)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#_exp)
+	local _callback = function(raw)
+		return item(raw, "inbox")
+	end
+	for _k, _v in _exp do
+		_newValue[_k] = _callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	_object[_left] = _newValue
+	local _left_1 = "quarantine"
+	local _exp_1 = list(t.quarantine, "quarantine", QUARANTINE_MAX_MESSAGES)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue_1 = table.create(#_exp_1)
+	local _callback_1 = function(raw)
+		local reason = raw.reason
+		if reason ~= "payload" and reason ~= "attempts" then
+			fail("bad quarantine reason")
+		end
+		local _object_1 = table.clone(item(raw, "quarantine"))
+		setmetatable(_object_1, nil)
+		_object_1.reason = reason
+		return _object_1
+	end
+	for _k, _v in _exp_1 do
+		_newValue_1[_k] = _callback_1(_v, _k - 1, _exp_1)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	_object[_left_1] = _newValue_1
+	_object.seen = ids(t.seen, "seen", SEEN_MAX_MESSAGES, OPERATION_ID_MAX_BYTES)
+	local _left_2 = "seenFloor"
+	local _condition = t.seenFloor
+	if _condition == nil then
+		_condition = 0
+	end
+	_object[_left_2] = time(_condition, "seenFloor")
+	_object.operations = ids(t.operations, "operations", OPERATION_MARKERS_PER_KEY, OPERATION_ID_MAX_BYTES)
+	local _left_3 = "operationFloor"
+	local _condition_1 = t.operationFloor
+	if _condition_1 == nil then
+		_condition_1 = 0
+	end
+	_object[_left_3] = time(_condition_1, "operationFloor")
+	return _object
+end
+--* @internal Validates before anything is interpreted; a malformed envelope is never repaired (rule 40). 
+local function parseEnvelope(raw, kind)
+	if raw == nil then
+		return {
+			kind = "absent",
+		}
+	end
+	local ok, result = pcall(readEnvelope, raw, kind)
+	if ok then
+		return {
+			kind = "ok",
+			envelope = result,
+		}
+	end
+	local _binding = result
+	local marker = _binding[1]
+	local reason = _binding[2]
+	if marker == UNREADABLE then
+		return {
+			kind = "unreadable",
+			reason = reason,
+		}
+	end
+	error(result)
+end
+--* @internal An absent key: unopened, epoch 0, empty collections. 
+local function emptyEnvelope(kind)
+	return {
+		format = 1,
+		kind = kind,
+		schemaVersion = 0,
+		epoch = 0,
+		receipts = {},
+		inbox = {},
+		quarantine = {},
+		seen = {},
+		seenFloor = 0,
+		operations = {},
+		operationFloor = 0,
+	}
+end
+local SHORT_ESCAPES = {
+	['"'] = true,
+	["\\"] = true,
+	["\b"] = true,
+	["\f"] = true,
+	["\n"] = true,
+	["\r"] = true,
+	["\t"] = true,
+}
+local function stringBytes(value)
+	local bytes = #value + 2
+	for special in string.gmatch(value, '[%c"\\]') do
+		bytes += if SHORT_ESCAPES[special] ~= nil then 1 else 5
+	end
+	return bytes
+end
+--* @internal Encoded JSON bytes, an upper bound on what Roblox counts (rule 39). 
+local function jsonBytes(value)
+	local _value = value
+	if type(_value) == "string" then
+		return stringBytes(value)
+	end
+	local _value_1 = value
+	if type(_value_1) == "number" then
+		local _result
+		if value % 1 == 0 then
+			_result = tostring(value)
+		else
+			local _value_2 = value
+			_result = string.format("%.17g", _value_2)
+		end
+		return #_result
+	end
+	local _value_2 = value
+	if type(_value_2) == "boolean" then
+		return if value then 4 else 5
+	end
+	local _value_3 = value
+	if not (type(_value_3) == "table") then
+		return 4
+	end
+	local t = value
+	local size = #t
+	local entries = 0
+	local bytes = 2
+	for key, entry in pairs(t) do
+		entries += 1
+		bytes += jsonBytes(entry)
+		if size == 0 or not (type(key) == "number") then
+			bytes += stringBytes(tostring(key)) + 1
+		end
+	end
+	return bytes + math.max(entries - 1, 0)
+end
+--* @internal 
+local function envelopeBytes(envelope)
+	return jsonBytes(envelope)
+end
+return {
+	parseEnvelope = parseEnvelope,
+	emptyEnvelope = emptyEnvelope,
+	jsonBytes = jsonBytes,
+	envelopeBytes = envelopeBytes,
+}

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

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