@trioforge/crucible 0.1.0 → 0.3.0

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

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

package/out/internal/data/admission.luau

@@ -0,0 +1,673 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local call = TS.import(script, script.Parent.Parent, "runner").call
+local _schema = TS.import(script, script.Parent.Parent, "network", "schema")
+local admitsNil = _schema.admitsNil
+local n = _schema.n
+local runtimeKind = _schema.runtimeKind
+local _limits = TS.import(script, script.Parent, "limits")
+local PERSIST_ADMISSION_VISITS = _limits.PERSIST_ADMISSION_VISITS
+local PERSIST_DEPTH = _limits.PERSIST_DEPTH
+local PERSIST_STRING_BYTES = _limits.PERSIST_STRING_BYTES
+--* @internal A schema migration: a private copy of the stored record in, a patch out (rule 75). 
+--* @internal What the durability engine knows of a profile or record schema. 
+--* @internal 
+--* @internal 
+local OPEN = n.object({})
+local FAILURE = {}
+local JSON_NODE = {}
+local F32_MAX = 3.4028234663852886e38
+local UINT_MAX = {
+	u8 = 255,
+	u16 = 65_535,
+	u32 = 4_294_967_295,
+}
+--* A frozen table admitted under a node is not walked again (rule 15). 
+local admitted = setmetatable({}, {
+	__mode = "k",
+})
+local function fail(path, reason)
+	error({ FAILURE, path, reason })
+end
+--* The length of a table whose keys are exactly 1..n, and undefined for any other table. 
+local function denseLength(value)
+	local items = value
+	local length = #items
+	local count = 0
+	for key in pairs(value) do
+		if not (type(key) == "number") or key % 1 ~= 0 or key < 1 or key > length then
+			return nil
+		end
+		count += 1
+	end
+	return if count == length then length else nil
+end
+local function hasOnlyStringKeys(value)
+	for key in pairs(value) do
+		if not (type(key) == "string") then
+			return false
+		end
+	end
+	return true
+end
+local function describe(node)
+	local _exp = node.kind
+	repeat
+		local _fallthrough = false
+		if _exp == "bool" then
+			return "boolean"
+		end
+		if _exp == "string" then
+			return "string"
+		end
+		if _exp == "object" then
+			_fallthrough = true
+		end
+		if _fallthrough or _exp == "map" then
+			return "an object"
+		end
+		if _exp == "array" then
+			_fallthrough = true
+		end
+		if _fallthrough or _exp == "tuple" then
+			return "an array"
+		end
+		if _exp == "literal" then
+			return `the literal {tostring(node.value)}`
+		end
+		if _exp == "variant" then
+			return `the variant {node.key} = {tostring(node.value)}`
+		end
+		if _exp == "union" then
+			local _exp_1 = node.branches
+			-- ▼ ReadonlyArray.map ▼
+			local _newValue = table.create(#_exp_1)
+			for _k, _v in _exp_1 do
+				_newValue[_k] = describe(_v, _k - 1, _exp_1)
+			end
+			-- ▲ ReadonlyArray.map ▲
+			return table.concat(_newValue, " or ")
+		end
+		if _exp == "nil" then
+			return "nothing"
+		end
+		return "number"
+	until true
+end
+local function run(root, rootValue, rootDefault)
+	local visits = 0
+	--* Height of the subtree the last walk returned: 0 for a scalar, 1 plus its deepest child for a table. 
+	local height = 0
+	local open = {}
+	local function count(path)
+		visits += 1
+		if visits > PERSIST_ADMISSION_VISITS then
+			fail(path, `more than {PERSIST_ADMISSION_VISITS} values`)
+		end
+	end
+	local function enter(value, path, depth)
+		count(path)
+		if depth > PERSIST_DEPTH then
+			fail(path, `deeper than {PERSIST_DEPTH}`)
+		end
+		if getmetatable(value) ~= nil then
+			fail(path, "a table with a metatable")
+		end
+		local _value = value
+		if open[_value] ~= nil then
+			fail(path, "a cycle")
+		end
+		local _value_1 = value
+		open[_value_1] = true
+	end
+	--* Reuses a frozen table already admitted under `node`, at its cached cost and with its depth checked. 
+	local function known(value, node, path, depth)
+		local _value = value
+		local hit = admitted[_value]
+		if hit == nil or hit.node ~= node or not table.isfrozen(value) then
+			return false
+		end
+		visits += hit.visits
+		if visits > PERSIST_ADMISSION_VISITS then
+			fail(path, `more than {PERSIST_ADMISSION_VISITS} values`)
+		end
+		if depth + hit.height - 1 > PERSIST_DEPTH then
+			fail(path, `deeper than {PERSIST_DEPTH}`)
+		end
+		height = hit.height
+		return true
+	end
+	local function finish(source, copy, node, before, top, same)
+		local _source = source
+		open[_source] = nil
+		local result = if same and table.isfrozen(source) then source else table.freeze(copy)
+		height = top + 1
+		local _arg1 = {
+			node = node,
+			visits = visits - before,
+			height = height,
+		}
+		admitted[result] = _arg1
+		return result
+	end
+	local function scalar(value, path)
+		count(path)
+		height = 0
+		return value
+	end
+	local function text(value, path)
+		local _value = value
+		if not (type(_value) == "string") then
+			local _exp = path
+			local _value_1 = value
+			fail(_exp, `expected string, got {typeof(_value_1)}`)
+		end
+		if #value > PERSIST_STRING_BYTES then
+			fail(path, `a string over {PERSIST_STRING_BYTES} bytes`)
+		end
+		if (utf8.len(value)) == nil then
+			fail(path, "invalid UTF-8")
+		end
+		return value
+	end
+	local function number(value, path)
+		local _value = value
+		if not (type(_value) == "number") then
+			local _exp = path
+			local _value_1 = value
+			fail(_exp, `expected number, got {typeof(_value_1)}`)
+		end
+		if value ~= value or math.abs(value) == math.huge then
+			fail(path, "expected a finite number")
+		end
+		return value
+	end
+	--* An undeclared value: storable JSON, copied and frozen, never interpreted (rule 76). 
+	local function json(value, path, depth)
+		local _value = value
+		if type(_value) == "string" then
+			return scalar(text(value, path), path)
+		end
+		local _value_1 = value
+		if type(_value_1) == "number" then
+			return scalar(number(value, path), path)
+		end
+		local _value_2 = value
+		if type(_value_2) == "boolean" then
+			return scalar(value, path)
+		end
+		local _value_3 = value
+		if not (type(_value_3) == "table") then
+			local _exp = path
+			local _value_4 = value
+			fail(_exp, `expected JSON, got {typeof(_value_4)}`)
+		end
+		if known(value, JSON_NODE, path, depth) then
+			return value
+		end
+		local before = visits
+		enter(value, path, depth)
+		local length = denseLength(value)
+		local copy = {}
+		local top = 0
+		local same = true
+		if length ~= nil and length > 0 then
+			local items = value
+			do
+				local i = 0
+				local _shouldIncrement = false
+				while true do
+					if _shouldIncrement then
+						i += 1
+					else
+						_shouldIncrement = true
+					end
+					if not (i < length) then
+						break
+					end
+					local child = json(items[i + 1], `{path}[{i}]`, depth + 1)
+					top = math.max(top, height)
+					if not rawequal(child, items[i + 1]) then
+						same = false
+					end
+					copy[i + 1] = child
+				end
+			end
+		else
+			if not hasOnlyStringKeys(value) then
+				fail(path, "a table mixing array and object keys")
+			end
+			for key, entry in pairs(value) do
+				local child = json(entry, `{path}.{key}`, depth + 1)
+				top = math.max(top, height)
+				if not rawequal(child, entry) then
+					same = false
+				end
+				copy[key] = child
+			end
+		end
+		return finish(value, copy, JSON_NODE, before, top, same)
+	end
+	local function tableOf(value, path, expected)
+		local _value = value
+		if not (type(_value) == "table") then
+			local _exp = path
+			local _exp_1 = expected
+			local _value_1 = value
+			fail(_exp, `expected {_exp_1}, got {typeof(_value_1)}`)
+		end
+		return value
+	end
+	local walk
+	local function object(node, value, fallback, path, depth, discriminant)
+		local source = tableOf(value, path, "an object")
+		if known(source, node, path, depth) then
+			return source
+		end
+		local before = visits
+		enter(source, path, depth)
+		if not hasOnlyStringKeys(source) then
+			fail(path, "expected an object")
+		end
+		local _fallback = fallback
+		local defaults = if type(_fallback) == "table" then fallback else nil
+		local copy = {}
+		local declared = {}
+		local top = 0
+		local same = true
+		if discriminant ~= nil then
+			local _discriminant = discriminant
+			declared[_discriminant] = true
+			copy[discriminant] = source[discriminant]
+			count(`{path}.{discriminant}`)
+		end
+		for _, _binding in node.fields do
+			local name = _binding[1]
+			local child = _binding[2]
+			declared[name] = true
+			local field = source[name]
+			local fieldPath = `{path}.{name}`
+			local _fieldDefault = defaults
+			if _fieldDefault ~= nil then
+				_fieldDefault = _fieldDefault[name]
+			end
+			local fieldDefault = _fieldDefault
+			if field == nil then
+				if admitsNil(child) then
+					continue
+				end
+				if fieldDefault == nil then
+					fail(fieldPath, "missing; a field added to existing data needs a migration step that fills it")
+				end
+				copy[name] = fieldDefault
+				same = false
+				continue
+			end
+			local result = walk(child, field, fieldDefault, fieldPath, depth + 1)
+			top = math.max(top, height)
+			if not rawequal(result, field) then
+				same = false
+			end
+			copy[name] = result
+		end
+		for key, entry in pairs(source) do
+			if declared[key] ~= nil then
+				continue
+			end
+			local result = json(entry, `{path}.{key}`, depth + 1)
+			top = math.max(top, height)
+			if not rawequal(result, entry) then
+				same = false
+			end
+			copy[key] = result
+		end
+		return finish(source, copy, node, before, top, same)
+	end
+	function walk(node, value, fallback, path, depth)
+		local _exp = node.kind
+		repeat
+			local _fallthrough = false
+			if _exp == "nil" then
+				fail(path, "expected nothing")
+				_fallthrough = true
+			end
+			if _fallthrough or _exp == "bool" then
+				local _value = value
+				if not (type(_value) == "boolean") then
+					local _exp_1 = path
+					local _value_1 = value
+					fail(_exp_1, `expected boolean, got {typeof(_value_1)}`)
+				end
+				return scalar(value, path)
+			end
+			if _exp == "string" then
+				return scalar(text(value, path), path)
+			end
+			if _exp == "literal" then
+				if value ~= node.value then
+					fail(path, `expected {describe(node)}`)
+				end
+				return scalar(value, path)
+			end
+			if _exp == "f64" then
+				return scalar(number(value, path), path)
+			end
+			if _exp == "f32" then
+				if math.abs(number(value, path)) > F32_MAX then
+					fail(path, "out of f32 range")
+				end
+				return scalar(value, path)
+			end
+			if _exp == "u8" then
+				_fallthrough = true
+			end
+			if _fallthrough or _exp == "u16" then
+				_fallthrough = true
+			end
+			if _fallthrough or _exp == "u32" then
+				local amount = number(value, path)
+				local maximum = UINT_MAX[node.kind]
+				if amount % 1 ~= 0 or amount < 0 or amount > maximum then
+					fail(path, `expected an integer in [0, {maximum}]`)
+				end
+				return scalar(amount, path)
+			end
+			if _exp == "object" then
+				return object(node, value, fallback, path, depth)
+			end
+			if _exp == "array" then
+				_fallthrough = true
+			end
+			if _fallthrough or _exp == "tuple" then
+				local source = tableOf(value, path, "an array")
+				if known(source, node, path, depth) then
+					return source
+				end
+				local before = visits
+				enter(source, path, depth)
+				local length = denseLength(source)
+				if length == nil then
+					fail(path, "expected an array")
+				end
+				if node.kind == "tuple" and length ~= #node.elements then
+					fail(path, `expected {#node.elements} elements`)
+				end
+				local items = source
+				local copy = {}
+				local top = 0
+				local same = true
+				do
+					local i = 0
+					local _shouldIncrement = false
+					while true do
+						if _shouldIncrement then
+							i += 1
+						else
+							_shouldIncrement = true
+						end
+						if not (i < length) then
+							break
+						end
+						local element = if node.kind == "tuple" then node.elements[i + 1] else node.element
+						local result = walk(element, items[i + 1], nil, `{path}[{i}]`, depth + 1)
+						top = math.max(top, height)
+						if not rawequal(result, items[i + 1]) then
+							same = false
+						end
+						table.insert(copy, result)
+					end
+				end
+				return finish(source, copy, node, before, top, same)
+			end
+			if _exp == "map" then
+				local source = tableOf(value, path, "an object")
+				if known(source, node, path, depth) then
+					return source
+				end
+				local before = visits
+				enter(source, path, depth)
+				if not hasOnlyStringKeys(source) then
+					fail(path, "expected an object with string keys")
+				end
+				local keys = {}
+				local restricted = false
+				if node.key.kind == "union" then
+					restricted = true
+					for _, branch in node.key.branches do
+						local _arg0 = tostring(branch.value)
+						keys[_arg0] = true
+					end
+				elseif node.key.kind ~= "string" then
+					fail(path, "a saved map has string keys")
+				end
+				local copy = {}
+				local top = 0
+				local same = true
+				for key, entry in pairs(source) do
+					if not (type(key) == "string") then
+						fail(path, "expected an object with string keys")
+					end
+					if restricted and not (keys[key] ~= nil) then
+						fail(`{path}.{key}`, "not a key this map declares")
+					end
+					local result = walk(node.value, entry, nil, `{path}.{key}`, depth + 1)
+					top = math.max(top, height)
+					if not rawequal(result, entry) then
+						same = false
+					end
+					copy[key] = result
+				end
+				return finish(source, copy, node, before, top, same)
+			end
+			if _exp == "union" then
+				local _value = value
+				local kind = typeof(_value)
+				for _, branch in node.branches do
+					if branch.kind == "nil" then
+						continue
+					end
+					if branch.kind == "literal" then
+						if value == branch.value then
+							return scalar(value, path)
+						end
+					elseif branch.kind == "variant" then
+						local _value_1 = value
+						local _condition = not (type(_value_1) == "table")
+						if not _condition then
+							_condition = value[branch.key] ~= branch.value
+						end
+						if _condition then
+							continue
+						end
+						local _fallback = fallback
+						local _condition_1 = type(_fallback) == "table"
+						if _condition_1 then
+							_condition_1 = fallback[branch.key] == branch.value
+						end
+						local own = _condition_1
+						return object(branch.body, value, if own then fallback else nil, path, depth, branch.key)
+					elseif runtimeKind(branch) == kind then
+						return walk(branch, value, fallback, path, depth)
+					end
+				end
+				return fail(path, `expected {describe(node)}, got {kind}`)
+			end
+			return fail(path, `{node.kind} cannot be saved; a save holds JSON`)
+		until true
+	end
+	return walk(root, rootValue, rootDefault, "", 1)
+end
+--[[
+	*
+	 * @internal Rules 14 and 76: validates declared positions, keeps undeclared keys in place, and returns a deeply frozen
+	 * copy. `defaults` fills a missing required key only along object fields (rule 76). Never throws on bad data, and a
+	 * failure names the path and the reason, never the value.
+	 
+]]
+local function admit(node, value, defaults)
+	local ok, result = pcall(run, node, value, defaults)
+	if ok then
+		return {
+			ok = true,
+			value = result,
+		}
+	end
+	local _binding = result
+	local marker = _binding[1]
+	local path = _binding[2]
+	local reason = _binding[3]
+	if marker == FAILURE then
+		return {
+			ok = false,
+			path = path,
+			reason = reason,
+		}
+	end
+	error(result)
+end
+--* @internal The schema with its defaults admitted and frozen once (rule 4). 
+local function sealSchema(schema)
+	local node = schema.node or OPEN
+	local result = admit(node, schema.defaults)
+	if not result.ok then
+		error(`{schema.name}{result.path}: {result.reason}`, 0)
+	end
+	local _object = table.clone(schema)
+	setmetatable(_object, nil)
+	_object.node = node
+	_object.defaults = result.value
+	return _object
+end
+local function isObject(value)
+	local _value = value
+	local _condition = type(_value) == "table"
+	if _condition then
+		_condition = hasOnlyStringKeys(value)
+	end
+	return _condition
+end
+local function copyJson(value)
+	local _value = value
+	if not (type(_value) == "table") then
+		return value
+	end
+	local result = {}
+	for key, entry in pairs(value) do
+		result[key] = copyJson(entry)
+	end
+	return result
+end
+--* Rule 75: objects merge into the stored object, anything else replaces it verbatim. 
+local function merge(base, patch)
+	if not isObject(base) or not isObject(patch) then
+		return patch
+	end
+	local _object = table.clone(base)
+	setmetatable(_object, nil)
+	local result = _object
+	for key, entry in pairs(patch) do
+		result[key] = merge(base[key], entry)
+	end
+	return result
+end
+--[[
+	*
+	 * @internal Rules 74 to 77: a stored record at version v runs `migrations[v]` to the last step on a private copy, each
+	 * step merged as a patch, then the descriptor is applied (rule 76). An absent payload takes the defaults and runs no
+	 * migration (rule 18).
+	 
+]]
+local function loadRecord(schema, payload, version)
+	if payload == nil then
+		return {
+			kind = "ok",
+			value = schema.defaults,
+			migrated = false,
+		}
+	end
+	if version > schema.version then
+		return {
+			kind = "newer",
+			version = version,
+		}
+	end
+	local current = payload
+	local migrated = false
+	local steps = schema.migrations or {}
+	do
+		local index = version
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				index += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (index < schema.version) then
+				break
+			end
+			local step = steps[index + 1]
+			if step == nil then
+				continue
+			end
+			local status, patch = call(step, copyJson(current), nil)
+			local label = `{schema.name}: migrations[{index}]`
+			if status == 1 then
+				return {
+					kind = "unreadable",
+					code = "migration",
+					reason = `{label} threw`,
+				}
+			end
+			if status == 2 then
+				return {
+					kind = "unreadable",
+					code = "migration",
+					reason = `{label} yielded`,
+				}
+			end
+			if not (type(patch) == "table") or not isObject(patch) then
+				return {
+					kind = "unreadable",
+					code = "migration",
+					reason = `{label} returned {typeof(patch)}, not a record`,
+				}
+			end
+			current = merge(current, patch)
+			migrated = true
+		end
+	end
+	local result = admit(schema.node or OPEN, current, schema.defaults)
+	if not result.ok then
+		return {
+			kind = "unreadable",
+			code = "admission",
+			reason = `{schema.name}{result.path}: {result.reason}{if migrated then ` (after migrating from version {version})` else ""}`,
+		}
+	end
+	return {
+		kind = "ok",
+		value = result.value,
+		migrated = migrated,
+	}
+end
+--* @internal Rule 14's walk over a callback's result, without defaults. Throws naming the store and path, never the value. 
+local function admitWrite(schema, value)
+	local _value = value
+	if not (type(_value) == "table") then
+		local _exp = schema.name
+		local _value_1 = value
+		error(`{_exp}: a store's value is a record, got {typeof(_value_1)}`, 0)
+	end
+	local result = admit(schema.node or OPEN, value)
+	if not result.ok then
+		error(`{schema.name}{result.path}: {result.reason}`, 0)
+	end
+	return result.value
+end
+return {
+	admit = admit,
+	sealSchema = sealSchema,
+	loadRecord = loadRecord,
+	admitWrite = admitWrite,
+}

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

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