@trioforge/crucible 0.0.0-stage → 0.2.0

package/out/server/data.d.ts

@@ -0,0 +1,54 @@
+import type { Migration, OperationId, ProfileMessage, StoreFailure, StoreResult } from "../data";
+declare const recordKind: unique symbol;
+export interface StoreOptions<T> {
+    /**
+     * A new record's value, and the value of a missing required key on an object path from the root. It never fills an
+     * array element, a map value or an optional key of an existing record. Admitted and frozen once.
+     */
+    readonly defaults: T;
+    /** Append-only. Removing or reordering a step changes what every older record becomes. */
+    readonly migrations?: readonly Migration[];
+}
+/**
+ * A generic update's result. `replayed` is true when the operation id was already recorded for the key: `change` did
+ * not run, and `value` is the current stored record (the defaults when the key holds no payload), which may include
+ * later writers' changes. A marker stores no result, so the original one cannot be returned.
+ */
+export type UpdateResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly replayed: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: StoreFailure;
+};
+/**
+ * Keyed records with no session. Each call is one DataStore request that yields and may fail, so the surface is two
+ * calls with result unions, not live handles.
+ */
+export interface DataStore<T> {
+    readonly [recordKind]: {
+        readonly kind: "records";
+        readonly value: (value: T) => T;
+    };
+    /** Yields. The stored record, migrated and admitted, or undefined when the key has none. */
+    read(key: string): StoreResult<T | undefined>;
+    /**
+     * Yields. One atomic change; `change` may run more than once, so it must be pure. A replayed id returns the current
+     * record with `replayed: true`. A throw in `change` cancels the write and is rethrown here.
+     */
+    update(key: string, change: (current: T) => T, id?: OperationId): UpdateResult<T>;
+}
+/**
+ * Declares keyed records by their DataStore name. It must initialize an exported top-level const in a server module,
+ * with `T` explicit. `T` is an object or a string-keyed record at its root.
+ */
+export declare function dataStore<T extends object>(_name: string, _options: StoreOptions<NoInfer<T>>): DataStore<T>;
+/** A fresh operation identity. Create it once per logical operation and reuse it for that operation's retries. */
+export declare function operationId(): OperationId;
+/**
+ * Declares a durable message to a player's profile. It must initialize an exported top-level const in a server module,
+ * with the payload type explicit. A payload type changes only by adding optional fields.
+ */
+export declare function profileMessage<P>(_name: string): ProfileMessage<P>;
+export {};

package/out/server/data.luau

@@ -0,0 +1,44 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local newOperationId = TS.import(script, script.Parent.Parent, "internal", "data", "operation-id").newOperationId
+local dataPort = TS.import(script, script.Parent.Parent, "internal", "data", "port").dataPort
+--[[
+	*
+	 * A generic update's result. `replayed` is true when the operation id was already recorded for the key: `change` did
+	 * not run, and `value` is the current stored record (the defaults when the key holds no payload), which may include
+	 * later writers' changes. A marker stores no result, so the original one cannot be returned.
+	 
+]]
+--[[
+	*
+	 * Keyed records with no session. Each call is one DataStore request that yields and may fail, so the surface is two
+	 * calls with result unions, not live handles.
+	 
+]]
+--[[
+	*
+	 * Declares keyed records by their DataStore name. It must initialize an exported top-level const in a server module,
+	 * with `T` explicit. `T` is an object or a string-keyed record at its root.
+	 
+]]
+local function dataStore(_name, _options)
+	error("Crucible data needs the @trioforge/crucible/transformer plugin")
+end
+--* A fresh operation identity. Create it once per logical operation and reuse it for that operation's retries. 
+local function operationId()
+	return newOperationId(dataPort())
+end
+--[[
+	*
+	 * Declares a durable message to a player's profile. It must initialize an exported top-level const in a server module,
+	 * with the payload type explicit. A payload type changes only by adding optional fields.
+	 
+]]
+local function profileMessage(_name)
+	error("Crucible data needs the @trioforge/crucible/transformer plugin")
+end
+return {
+	dataStore = dataStore,
+	operationId = operationId,
+	profileMessage = profileMessage,
+}

package/out/server/index.d.ts

@@ -0,0 +1,18 @@
+import type { BootOptions } from "../index";
+import type { PayloadArgs, ToClient } from "../network";
+import "../internal/data/record-bindings";
+export { config, playerConfig, configReady, refreshConfigs } from "../configs";
+export type { Config, PlayerConfig } from "../configs";
+export { publish } from "./publish";
+export type { Publication } from "./publish";
+export { dataStore, operationId, profileMessage } from "./data";
+export type { DataStore, StoreOptions, UpdateResult } from "./data";
+export type { OperationId, StoreFailure, StoreResult } from "../data";
+export type { ProfileMessage, ProfileClaim, LoadReason, ReleaseReason, Purchase, AfterGrant, QuarantinedMessage, SaveResult, SaveFailure, } from "../data";
+export declare function boot(options: BootOptions): void;
+export declare namespace Network {
+    /** True when accepted locally: fired now, or queued before the player's client is ready. Never delivery. */
+    function send<P>(player: Player, message: ToClient<P>, ...payload: PayloadArgs<NoInfer<P>>): boolean;
+    /** Encodes once and delivers the same packet to every player in the game now. */
+    function broadcast<P>(message: ToClient<P>, ...payload: PayloadArgs<NoInfer<P>>): void;
+}

package/out/server/init.luau

@@ -0,0 +1,62 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local bootSide = TS.import(script, script.Parent, "internal", "boot").boot
+local installConfigRuntime = TS.import(script, script.Parent, "internal", "configs", "runtime").installConfigRuntime
+local networkPort = TS.import(script, script.Parent, "internal", "network", "port").networkPort
+local ServerSession = TS.import(script, script.Parent, "internal", "network", "server-session").ServerSession
+local SyncFrameMessage = TS.import(script, script.Parent, "internal", "sync", "frame").SyncFrameMessage
+local installServerSync = TS.import(script, script.Parent, "internal", "sync", "server-sync").installServerSync
+TS.import(script, script.Parent, "internal", "data", "record-bindings")
+local installDataRuntime = TS.import(script, script.Parent, "internal", "data", "runtime").installDataRuntime
+if not game:GetService("RunService"):IsServer() then
+	error("@trioforge/crucible/server loaded on the client")
+end
+local session
+local _configs = TS.import(script, script.Parent, "configs")
+exports.config = _configs.config
+exports.playerConfig = _configs.playerConfig
+exports.configReady = _configs.configReady
+exports.refreshConfigs = _configs.refreshConfigs
+exports.publish = TS.import(script, script, "publish").publish
+local _data = TS.import(script, script, "data")
+exports.dataStore = _data.dataStore
+exports.operationId = _data.operationId
+exports.profileMessage = _data.profileMessage
+local function active()
+	return session or error("Crucible networking is not ready; send from a constructor, a hook, or later", 0)
+end
+installConfigRuntime()
+installDataRuntime()
+local function boot(options)
+	local network = ServerSession.new(networkPort())
+	session = network
+	installServerSync(function(player, frame)
+		return active():send(player, SyncFrameMessage, frame)
+	end)
+	bootSide({
+		name = "server",
+		renders = false,
+		booted = function() end,
+		network = network,
+	}, options)
+end
+local Network = {}
+do
+	local _container = Network
+	--* True when accepted locally: fired now, or queued before the player's client is ready. Never delivery. 
+	local function send(player, message, ...)
+		local payload = { ... }
+		return active():send(player, message, payload[1])
+	end
+	_container.send = send
+	--* Encodes once and delivers the same packet to every player in the game now. 
+	local function broadcast(message, ...)
+		local payload = { ... }
+		active():broadcast(message, payload[1])
+	end
+	_container.broadcast = broadcast
+end
+exports.boot = boot
+exports.Network = Network
+return exports

package/out/server/publish.d.ts

@@ -0,0 +1,20 @@
+import type { State } from "../reactive";
+import type { Replicated, ReplicatedPerPlayer } from "../replicated";
+declare const publication: unique symbol;
+/** What a per-player `publish` returns: an opaque claim that holds nothing callable. */
+export interface Publication {
+    readonly [publication]: true;
+}
+/**
+ * Takes the write side of a value every client sees. Call it while a server Subsystem is constructed, as a field
+ * initializer: `private readonly phase = publish(JobPhase)`. `set` and `update` drop fields the type does not
+ * declare, check and freeze the rest, and throw at a write that cannot replicate. One Subsystem publishes each value.
+ */
+export declare function publish<T>(target: Replicated<T>): State<T>;
+/**
+ * Supplies a per-player value as a projection. For each player whose client is ready, it is evaluated like a
+ * `computed`, admitted on every pull and sent to that player alone. It must be pure and must not yield. A throw or a
+ * rejected value marks that player's value failed until it next changes.
+ */
+export declare function publish<T>(target: ReplicatedPerPlayer<T>, project: (player: Player) => T): Publication;
+export {};

package/out/server/publish.luau

@@ -0,0 +1,24 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local claimPublication = TS.import(script, script.Parent.Parent, "internal", "sync", "declarations").claimPublication
+--* What a per-player `publish` returns: an opaque claim that holds nothing callable. 
+--[[
+	*
+	 * Takes the write side of a value every client sees. Call it while a server Subsystem is constructed, as a field
+	 * initializer: `private readonly phase = publish(JobPhase)`. `set` and `update` drop fields the type does not
+	 * declare, check and freeze the rest, and throw at a write that cannot replicate. One Subsystem publishes each value.
+	 
+]]
+--[[
+	*
+	 * Supplies a per-player value as a projection. For each player whose client is ready, it is evaluated like a
+	 * `computed`, admitted on every pull and sent to that player alone. It must be pure and must not yield. A throw or a
+	 * rejected value marks that player's value failed until it next changes.
+	 
+]]
+local function publish(target, project)
+	return claimPublication(target, project)
+end
+return {
+	publish = publish,
+}

package/out/subsystem.d.ts

@@ -0,0 +1,4 @@
+import { CrucibleObject } from "./crucible-object";
+export declare abstract class Subsystem extends CrucibleObject {
+    protected onShutdown(): void;
+}

package/out/subsystem.luau

@@ -0,0 +1,30 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local CrucibleObject = TS.import(script, script.Parent, "crucible-object").CrucibleObject
+local installSubsystemHooks = TS.import(script, script.Parent, "internal", "hooks").installSubsystemHooks
+local Subsystem
+do
+	local super = CrucibleObject
+	Subsystem = setmetatable({}, {
+		__tostring = function()
+			return "Subsystem"
+		end,
+		__index = super,
+	})
+	Subsystem.__index = Subsystem
+	function Subsystem:constructor(...)
+		super.constructor(self, ...)
+	end
+	function Subsystem:onShutdown()
+	end
+	do
+		installSubsystemHooks({
+			onShutdown = function(o)
+				return o:onShutdown()
+			end,
+		})
+	end
+end
+return {
+	Subsystem = Subsystem,
+}

package/out/vide/index.d.ts

@@ -0,0 +1,7 @@
+import { type Readable } from "../reactive";
+/**
+ * A Vide source that follows `readable`. It holds the value read now, untracked, and takes each change on the
+ * reactive flush, through a `watch` that ends with the current Vide owner. Outside a Vide component or `root` it
+ * throws.
+ */
+export declare function useReadable<T>(readable: Readable<T>): () => T;

package/out/vide/init.luau

@@ -0,0 +1,50 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _vide = TS.import(script, TS.getModule(script, "@rbxts", "vide").src)
+local cleanup = _vide.cleanup
+local source = _vide.source
+local untracked = TS.import(script, script.Parent, "reactive").untracked
+local createWatchFrom = TS.import(script, script.Parent, "internal", "reactive", "flush").createWatchFrom
+local createRootScope = TS.import(script, script.Parent, "internal", "reactive", "ownership").createRootScope
+local NO_OWNER = "useReadable() needs a Vide owner: call it inside a component or root()"
+--[[
+	*
+	 * A Vide source that follows `readable`. It holds the value read now, untracked, and takes each change on the
+	 * reactive flush, through a `watch` that ends with the current Vide owner. Outside a Vide component or `root` it
+	 * throws.
+	 
+]]
+local function useReadable(readable)
+	local dispose
+	-- Vide's cleanup is the only public test for an owner, and registering first leaves nothing to undo.
+	local owned = pcall(cleanup, function()
+		local _result = dispose
+		if _result ~= nil then
+			_result = _result()
+		end
+		return _result
+	end)
+	if not owned then
+		error(NO_OWNER, 2)
+	end
+	local initial = untracked(readable)
+	local value = source(initial)
+	local latest = initial
+	local write = function()
+		value(latest)
+		return nil
+	end
+	-- A root, so a component mounted from inside a Crucible run or callback does not end with it.
+	dispose = createRootScope(function()
+		return createWatchFrom(readable, initial, function(current)
+			latest = current
+			-- Vide runs its effects inside the write. Across gsub's C call a yield in one throws where it yields, so
+			-- Vide's own error path pops its scope stack. Without it the runner cancels the yielded worker mid-effect.
+			string.gsub("x", "x", write)
+		end)
+	end)
+	return value
+end
+return {
+	useReadable = useReadable,
+}

package/package.json

@@ -1,6 +1,53 @@
 {
-  "name": "@trioforge/crucible",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@trioforge/crucible",
+	"version": "0.2.0",
+	"license": "MIT",
+	"main": "out/init.luau",
+	"types": "out/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./out/index.d.ts",
+			"default": "./out/init.luau"
+		},
+		"./server": {
+			"types": "./out/server/index.d.ts",
+			"default": "./out/server/init.luau"
+		},
+		"./emit": {
+			"types": "./out/emit/index.d.ts",
+			"default": "./out/emit/init.luau"
+		},
+		"./client": {
+			"types": "./out/client/index.d.ts",
+			"default": "./out/client/init.luau"
+		},
+		"./vide": {
+			"types": "./out/vide/index.d.ts",
+			"default": "./out/vide/init.luau"
+		},
+		"./transformer": "./transformer/index.js"
+	},
+	"peerDependencies": {
+		"typescript": "5.5.3",
+		"@rbxts/vide": "^0.6.1"
+	},
+	"peerDependenciesMeta": {
+		"@rbxts/vide": {
+			"optional": true
+		}
+	},
+	"files": [
+		"out",
+		"transformer",
+		"server",
+		"client",
+		"emit",
+		"vide",
+		"LICENSE"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Trio-Forge-Studio/crucible.git",
+		"directory": "packages/crucible"
+	}
+}

package/server/package.json

@@ -0,0 +1,4 @@
+{
+	"main": "../out/server/init.luau",
+	"types": "../out/server/index.d.ts"
+}

package/transformer/data.cjs

@@ -0,0 +1,72 @@
+function createDataChecks({ ts, program, checker, api }) {
+	const unwrap = (expression) => {
+		while (ts.isParenthesizedExpression(expression) || ts.isNonNullExpression(expression))
+			expression = expression.expression;
+		return expression;
+	};
+	const member = (expression) => {
+		if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+		if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression))
+			return expression.argumentExpression.text;
+	};
+	const store = (expression) => api(checker.getTypeAtLocation(expression).getSymbol()) === "ProfileStore";
+	const marketplace = (expression) => {
+		const symbol = checker.getTypeAtLocation(expression).getSymbol();
+		return (
+			symbol?.name === "MarketplaceService" &&
+			symbol.declarations?.some((d) =>
+				d.getSourceFile().fileName.replaceAll("\\", "/").includes("/@rbxts/types/"),
+			)
+		);
+	};
+	const storeCall = (node) => {
+		const callee = unwrap(node.expression);
+		if (store(callee)) return { store: callee };
+		const name = member(callee);
+		if (name !== undefined && store(callee.expression)) return { store: callee.expression, member: name };
+	};
+	let granted;
+	const grants = () => {
+		if (granted === undefined) {
+			granted = false;
+			const walk = (node) => {
+				if (granted) return;
+				if (ts.isCallExpression(node) && storeCall(node)?.member === "grant") granted = true;
+				else ts.forEachChild(node, walk);
+			};
+			for (const source of program.getSourceFiles()) if (!source.isDeclarationFile) walk(source);
+		}
+		return granted;
+	};
+	return ({ report, side }) =>
+		(node) => {
+			if (ts.isCallExpression(node)) {
+				const call = storeCall(node);
+				if (call) {
+					const text = call.store.getText();
+					const client =
+						call.member === undefined || call.member === "loaded" ? !node.arguments.length : false;
+					const required = client ? "client" : "server";
+					if (side(node) !== required)
+						report(
+							node,
+							"CRU027",
+							client
+								? `${text}${call.member ? ".loaded" : ""}() reads the local player's profile; on the server call ${text}${call.member ? ".loaded" : ""}(player).`
+								: `${text}${call.member === undefined ? "(player)" : `.${call.member}`} is server-only; the client reads ${text}().`,
+						);
+				}
+			}
+			if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+				const target = unwrap(node.left);
+				if (member(target) === "ProcessReceipt" && marketplace(target.expression) && grants())
+					report(
+						node,
+						"CRU025",
+						"Crucible's data module owns ProcessReceipt; register grants with a profile store's grant(productId, ...).",
+					);
+			}
+		};
+}
+
+module.exports = { createDataChecks };

package/transformer/declarations.cjs

@@ -0,0 +1,153 @@
+const limits = Object.freeze({
+	MESSAGE_NAME_MAX_BYTES: 64,
+	MAX_ASK_TIMEOUT_SECONDS: 120,
+	MAX_UNION_BRANCHES: 256,
+	MAX_SCHEMA_NODES: 4096,
+	MAX_DEPTH: 32,
+});
+const reactiveLimits = Object.freeze({
+	MESSAGE_NAME_MAX_BYTES: 64,
+	SYNC_VALUE_DEPTH: 28,
+});
+const dataLimits = Object.freeze({
+	STORE_NAME_MAX_BYTES: 50,
+	MESSAGE_NAME_MAX_BYTES: 64,
+	CONFIG_NAME_MAX_BYTES: 64,
+	PERSIST_DEPTH: 28,
+	VIEW_NAME_PREFIX: "Crucible.Data.",
+	LIVE_NAME_PREFIX: "Crucible.Live.",
+	VIEW_NAME_MAX_BYTES: 64,
+	RESERVED_HANDLE_NAMES: Object.freeze(["set", "update", "insert", "remove"]),
+});
+
+const message = {
+	label: "messages",
+	side: "shared",
+	names: "Message",
+	maxBytes: limits.MESSAGE_NAME_MAX_BYTES,
+	typeArguments: 1,
+	arguments: 1,
+	passed: [],
+	position: "payload",
+};
+const replicated = {
+	label: "replicated state",
+	side: "shared",
+	names: "Replicated",
+	maxBytes: reactiveLimits.MESSAGE_NAME_MAX_BYTES,
+	typeArguments: 1,
+	arguments: 2,
+	passed: [1],
+	position: "state",
+};
+const config = {
+	label: "configs",
+	side: "server",
+	names: "Config",
+	maxBytes: dataLimits.CONFIG_NAME_MAX_BYTES,
+	typeArguments: 1,
+	arguments: 2,
+	passed: [1],
+	position: "persist",
+};
+const kinds = Object.freeze({
+	toServer: message,
+	toClient: message,
+	askServer: { ...message, typeArguments: 2, arguments: 2 },
+	replicated,
+	replicatedPerPlayer: replicated,
+	profileStore: {
+		label: "profile stores",
+		side: "shared",
+		names: "Store",
+		maxBytes: dataLimits.STORE_NAME_MAX_BYTES,
+		typeArguments: "optional",
+		arguments: 2,
+		passed: [1],
+		position: "persist",
+		store: true,
+		handles: true,
+	},
+	dataStore: {
+		label: "data stores",
+		side: "server",
+		names: "Store",
+		maxBytes: dataLimits.STORE_NAME_MAX_BYTES,
+		typeArguments: 1,
+		arguments: 2,
+		passed: [1],
+		position: "persist",
+		store: true,
+	},
+	profileMessage: {
+		label: "profile messages",
+		side: "server",
+		names: "Profile message",
+		maxBytes: dataLimits.MESSAGE_NAME_MAX_BYTES,
+		typeArguments: 1,
+		arguments: 1,
+		passed: [],
+		position: "persist",
+	},
+	config,
+	playerConfig: config,
+});
+const depthLimits = Object.freeze({
+	payload: limits.MAX_DEPTH,
+	state: reactiveLimits.SYNC_VALUE_DEPTH,
+	persist: dataLimits.PERSIST_DEPTH,
+});
+
+// Marks sit only on object fields from the root, so only object fields can lose every field.
+function replica(node) {
+	if (node.kind !== "object") return node;
+	const fields = [];
+	for (const [key, child] of node.fields) {
+		if (child.serverOnly) continue;
+		const kept = replica(child);
+		if (kept.kind === "object" && !kept.fields.length) continue;
+		fields.push([key, kept]);
+	}
+	return { kind: "object", fields };
+}
+// Object fields are sorted by bytes, so a depth-first walk lists paths in rule 131 order, a prefix first.
+function serverOnlyPaths(node, prefix = []) {
+	if (node.kind !== "object") return [];
+	return node.fields.flatMap(([key, child]) =>
+		child.serverOnly ? [[...prefix, key]] : serverOnlyPaths(child, [...prefix, key]),
+	);
+}
+const SEGMENT = /^[A-Za-z][A-Za-z0-9_]*$/;
+function viewNameProblems(store, node) {
+	if (node.kind !== "object") return [];
+	const prefix = `${dataLimits.VIEW_NAME_PREFIX}${store}.`;
+	return node.fields.flatMap(([field]) => {
+		const name = prefix + field;
+		if (!SEGMENT.test(field))
+			return [
+				[
+					`value[${JSON.stringify(field)}]`,
+					"a field the owner's client receives is named by one declaration segment, [A-Za-z][A-Za-z0-9_]*; rename it or mark it serverOnly",
+				],
+			];
+		if (Buffer.byteLength(name) > dataLimits.VIEW_NAME_MAX_BYTES)
+			return [
+				[
+					`value.${field}`,
+					`its view name ${name} is ${Buffer.byteLength(name)} bytes, over ${dataLimits.VIEW_NAME_MAX_BYTES}; this store allows field names of at most ${dataLimits.VIEW_NAME_MAX_BYTES - Buffer.byteLength(prefix)} bytes; rename the field, shorten the store name, or mark it serverOnly`,
+				],
+			];
+		return [];
+	});
+}
+
+module.exports = {
+	limits,
+	reactiveLimits,
+	dataLimits,
+	kinds,
+	depthLimits,
+	replica,
+	serverOnlyPaths,
+	viewNameProblems,
+};

package/transformer/diagnostics.cjs

@@ -0,0 +1,19 @@
+function createReporter(ts, addDiagnostic) {
+	const seen = new Set();
+	return (node, code, message) => {
+		const key = `${node.getSourceFile().fileName}:${node.getStart()}:${code}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		return addDiagnostic({
+			category: ts.DiagnosticCategory.Error,
+			code: 90000 + (/^CRU\d+$/.test(code) ? Number(code.slice(3)) : 0),
+			source: "crucible",
+			file: node.getSourceFile(),
+			start: node.getStart(),
+			length: node.getWidth(),
+			messageText: `${code}: ${message}`,
+		});
+	};
+}
+
+module.exports = { createReporter };