@flamework-experimental/core 2.0.0-alpha.2 → 2.0.0-alpha.4

package/out/lifecycle/lifecyclePlugin.luau

@@ -10,6 +10,7 @@ local extinguishesBegun = _threadWaits.extinguishesBegun
 local runsPromiseWork = _threadWaits.runsPromiseWork
 local threadWaits = _threadWaits.threadWaits
 local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local DEFAULT_LOAD_ORDER = TS.import(script, script.Parent.Parent, "module", "providerRegistration").DEFAULT_LOAD_ORDER
 local _pluginDefinition = TS.import(script, script.Parent.Parent, "plugin", "pluginDefinition")
 local LIFECYCLE_SLOT = _pluginDefinition.LIFECYCLE_SLOT
 local PluginDefinition = _pluginDefinition.PluginDefinition
@@ -144,6 +145,7 @@ do
 		self.onInit = {}
 		self.initMembers = {}
 		self.startOrder = {}
+		self.startLoadOrders = {}
 		self.onStart = {}
 		self.onTick = {}
 		self.onPhysics = {}
@@ -636,6 +638,12 @@ do
 			local _startOrder = self.startOrder
 			local _object_1 = object
 			table.insert(_startOrder, _object_1)
+			if context.loadOrder ~= nil and context.loadOrder ~= DEFAULT_LOAD_ORDER then
+				local _startLoadOrders = self.startLoadOrders
+				local _object_2 = object
+				local _loadOrder = context.loadOrder
+				_startLoadOrders[_object_2] = _loadOrder
+			end
 		else
 			self:scheduleLateProvider(object)
 		end
@@ -647,9 +655,12 @@ do
 		local _lateProviders = self.lateProviders
 		local _object_1 = object
 		_lateProviders[_object_1] = nil
-		local _startOrder = self.startOrder
+		local _startLoadOrders = self.startLoadOrders
 		local _object_2 = object
-		local index = (table.find(_startOrder, _object_2) or 0) - 1
+		_startLoadOrders[_object_2] = nil
+		local _startOrder = self.startOrder
+		local _object_3 = object
+		local index = (table.find(_startOrder, _object_3) or 0) - 1
 		if index ~= -1 then
 			table.remove(self.startOrder, index + 1)
 		end
@@ -698,11 +709,7 @@ do
 	end
 	function LifecycleProvider:start(module)
 		-- An `onStart` may extinguish the module; nothing starts or ticks after that.
-		local _array = {}
-		local _length = #_array
-		local _array_1 = self.startOrder
-		table.move(_array_1, 1, #_array_1, _length + 1, _array)
-		for _, object in _array do
+		for _, object in self:inLoadOrder(self.startOrder) do
 			if self:hasBegunExtinguishing() then
 				return nil
 			end
@@ -741,6 +748,58 @@ do
 		local _module = module
 		_moduleConnections[_module] = connections
 	end
+	function LifecycleProvider:inLoadOrder(objects)
+		local orders = self.startLoadOrders
+		if next(orders) == nil then
+			local _array = {}
+			local _length = #_array
+			table.move(objects, 1, #objects, _length + 1, _array)
+			return _array
+		end
+		self.startLoadOrders = {}
+		-- `table.sort` is not stable, so equals are ordered by their position.
+		local position = {}
+		-- ▼ ReadonlyArray.forEach ▼
+		local _callback = function(object, index)
+			local _object = object
+			local _index = index
+			position[_object] = _index
+			return position
+		end
+		for _k, _v in objects do
+			_callback(_v, _k - 1, objects)
+		end
+		-- ▲ ReadonlyArray.forEach ▲
+		local _array = {}
+		local _length = #_array
+		table.move(objects, 1, #objects, _length + 1, _array)
+		local sorted = _array
+		table.sort(sorted, function(a, b)
+			local _a = a
+			local _condition = orders[_a]
+			if _condition == nil then
+				_condition = DEFAULT_LOAD_ORDER
+			end
+			local orderA = _condition
+			local _b = b
+			local _condition_1 = orders[_b]
+			if _condition_1 == nil then
+				_condition_1 = DEFAULT_LOAD_ORDER
+			end
+			local orderB = _condition_1
+			local _result
+			if orderA ~= orderB then
+				_result = orderA < orderB
+			else
+				local _a_1 = a
+				local _exp = position[_a_1]
+				local _b_1 = b
+				_result = _exp < position[_b_1]
+			end
+			return _result
+		end)
+		return sorted
+	end
 	function LifecycleProvider:extinguished(module)
 		local _moduleConnections = self.moduleConnections
 		local _module = module
@@ -821,6 +880,7 @@ do
 	do
 		-- (Flamework) LifecycleProvider metadata
 		Reflect_1.defineMetadata(LifecycleProvider, "identifier", "$:lifecycle/lifecyclePlugin@LifecycleProvider")
+		Reflect_1.defineMetadata(LifecycleProvider, "flamework:module", script)
 		Reflect_1.defineMetadata(LifecycleProvider, "flamework:implements", {})
 		Reflect_1.defineMetadata(LifecycleProvider, "flamework:parameters", { "$:lifecycle/lifecyclePlugin@LifecyclePluginOptions" })
 		Reflect_1.defineMetadata(LifecycleProvider, "flamework:dependencies", { {

package/out/module/module.luau

@@ -5,14 +5,20 @@ local convertConciseDependencyInfo = TS.import(script, script.Parent.Parent, "ut
 local getClassImplements = TS.import(script, script.Parent.Parent, "utility", "getClassImplements").getClassImplements
 local getClassesInPath = TS.import(script, script.Parent.Parent, "utility", "getClassesInPath").getClassesInPath
 local getClassesInGlob = TS.import(script, script.Parent.Parent, "utility", "globs").getClassesInGlob
+local explainUnresolvedClass = TS.import(script, script.Parent.Parent, "utility", "explainUnresolved").explainUnresolvedClass
+local _leftOut = TS.import(script, script.Parent.Parent, "utility", "leftOut")
+local explainLeftOut = _leftOut.explainLeftOut
+local leftOutRegistration = _leftOut.leftOutRegistration
 local _threadWaits = TS.import(script, script.Parent.Parent, "utility", "threadWaits")
 local extinguishesBegun = _threadWaits.extinguishesBegun
 local threadWaits = _threadWaits.threadWaits
 local clearDefaultModule = TS.import(script, script.Parent, "defaultModule").clearDefaultModule
 local HookPriority = TS.import(script, script.Parent, "moduleHooks").HookPriority
 local _providerRegistration = TS.import(script, script.Parent, "providerRegistration")
+local DEFAULT_LOAD_ORDER = _providerRegistration.DEFAULT_LOAD_ORDER
 local getProviderClassId = _providerRegistration.getProviderClassId
 local getProviderClassScope = _providerRegistration.getProviderClassScope
+local getProviderLoadOrder = _providerRegistration.getProviderLoadOrder
 local normalizeProviderConfig = _providerRegistration.normalizeProviderConfig
 local _scopes = TS.import(script, script.Parent, "scopes")
 local NO_CONDITION = _scopes.NO_CONDITION
@@ -76,6 +82,12 @@ local function createModuleInstantiation(state, options)
 	local providers = {}
 	--* The registrations left out, by id, with the conditions that were judged: for the error a miss gets. 
 	local skipped = {}
+	--* The path and glob registrations left out by their own condition, the builder's and the plugins'. 
+	local _array_2 = {}
+	local _length_1 = #_array_2
+	local _array_3 = (state.leftOut or {})
+	table.move(_array_3, 1, #_array_3, _length_1 + 1, _array_2)
+	local leftOut = _array_2
 	--* Modules searched after this one's own providers, in order. Ignited before this one, and extinguished after. 
 	local _result = options
 	if _result ~= nil then
@@ -229,6 +241,67 @@ local function createModuleInstantiation(state, options)
 		end
 		providers = active
 	end
+	--[[
+		*
+		     * The registrations in ascending `loadOrder`, registration order among equals. The same list
+		     * when none sets one, which is every module that does not use it.
+		     
+	]]
+	local inLoadOrder = function(entries)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#entries)
+		local _callback = function(entry)
+			local _condition_1 = getProviderLoadOrder(entry.config)
+			if _condition_1 == nil then
+				_condition_1 = DEFAULT_LOAD_ORDER
+			end
+			return _condition_1
+		end
+		for _k, _v in entries do
+			_newValue[_k] = _callback(_v, _k - 1, entries)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local orders = _newValue
+		-- ▼ ReadonlyArray.every ▼
+		local _result_1 = true
+		local _callback_1 = function(order)
+			return order == DEFAULT_LOAD_ORDER
+		end
+		for _k, _v in orders do
+			if not _callback_1(_v, _k - 1, orders) then
+				_result_1 = false
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.every ▲
+		if _result_1 then
+			return entries
+		end
+		-- `table.sort` is not stable, so equals are ordered by their position.
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue_1 = table.create(#entries)
+		local _callback_2 = function(_, index)
+			return index
+		end
+		for _k, _v in entries do
+			_newValue_1[_k] = _callback_2(_v, _k - 1, entries)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local indices = _newValue_1
+		table.sort(indices, function(a, b)
+			return if orders[a + 1] ~= orders[b + 1] then orders[a + 1] < orders[b + 1] else a < b
+		end)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue_2 = table.create(#indices)
+		local _callback_3 = function(index)
+			return entries[index + 1]
+		end
+		for _k, _v in indices do
+			_newValue_2[_k] = _callback_3(_v, _k - 1, indices)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		return _newValue_2
+	end
 	local registerHook = function(phase, callback, priority)
 		local _object = {
 			phase = phase,
@@ -248,11 +321,11 @@ local function createModuleInstantiation(state, options)
 		local _callback = function(hook)
 			return hook.phase == phase
 		end
-		local _length_1 = 0
+		local _length_2 = 0
 		for _k, _v in hooks do
 			if _callback(_v, _k - 1, hooks) == true then
-				_length_1 += 1
-				_newValue[_length_1] = _v
+				_length_2 += 1
+				_newValue[_length_2] = _v
 			end
 		end
 		-- ▲ ReadonlyArray.filter ▲
@@ -311,7 +384,7 @@ local function createModuleInstantiation(state, options)
 		     * `dependencies`, what a provider's constructor was given, is handed to the observers with it.
 		     
 	]]
-	local registerClassInterfaces = function(instance, kind, dependencies)
+	local registerClassInterfaces = function(instance, kind, dependencies, loadOrder)
 		local interfaces = getClassImplements(instance)
 		-- How many observers have been told `onAdded`, in the order they were told: what a refusal
 		-- undoes. Counted rather than recorded, since an attachment that goes through -- every one,
@@ -330,6 +403,7 @@ local function createModuleInstantiation(state, options)
 							interfaceId = interfaceId,
 							kind = kind,
 							dependencies = dependencies,
+							loadOrder = loadOrder,
 						})
 					end
 					attached += 1
@@ -456,7 +530,7 @@ local function createModuleInstantiation(state, options)
 				-- not be cached either -- the next resolve handed it out with no lifecycle at all, and
 				-- `release` told every observer, the refusing one included, it was removed again.
 				local attached, err = pcall(function()
-					return registerClassInterfaces(instantiatedProvider, "provider", dependencies)
+					return registerClassInterfaces(instantiatedProvider, "provider", dependencies, getProviderLoadOrder(config))
 				end)
 				if not attached then
 					local _id_2 = info.id
@@ -510,6 +584,17 @@ local function createModuleInstantiation(state, options)
 			if inactive ~= nil then
 				error(`module '{state.debugName}' could not resolve dependency '{info.id}': it is registered but inactive ({describeConditions(inactive)}){searched}`)
 			end
+			-- A folder registration left out by its own condition registered nothing to be inactive.
+			local leftOutReason = explainLeftOut(info.id, leftOut)
+			if leftOutReason ~= nil then
+				error(`module '{state.debugName}' could not resolve dependency '{info.id}': {leftOutReason}{searched}`)
+			end
+			-- A class that has been loaded says why it is not here: a component, a provider nothing
+			-- registered, a class that is not a provider at all.
+			local explanation = explainUnresolvedClass(info.id, requestingOrigin)
+			if explanation ~= nil then
+				error(`module '{state.debugName}' could not resolve dependency '{info.id}': {explanation}{searched}`)
+			end
 			error(`module '{state.debugName}' could not resolve dependency '{info.id}'{searched}`)
 		end
 		return dependency
@@ -658,7 +743,10 @@ local function createModuleInstantiation(state, options)
 				registerClassInterfaces(instance, "provider")
 				unjoinedInstances[instance] = nil
 			end
-			for _, provider in providers do
+			-- In ascending `loadOrder`, each after what its constructor takes, which is the order the
+			-- lifecycle plugin runs `onInit` in: a low `loadOrder` goes first and pulls its
+			-- dependencies forward with it, and dependency order still wins over `loadOrder`.
+			for _, provider in inLoadOrder(providers) do
 				-- Lazy providers are constructed the first time they are resolved instead.
 				if provider.config.type == "class" and provider.config.lazy ~= true then
 					resolveDependency(provider.injectionId)
@@ -708,13 +796,13 @@ local function createModuleInstantiation(state, options)
 		-- extinguishing already, on another thread suspended in a handler that yields, is still
 		-- using this module's providers, so it is waited for: skipped, it had this module released
 		-- under it.
-		local _array_2 = {}
-		local _length_1 = #_array_2
+		local _array_4 = {}
+		local _length_2 = #_array_4
 		for _v in importers do
-			_length_1 += 1
-			_array_2[_length_1] = _v
+			_length_2 += 1
+			_array_4[_length_2] = _v
 		end
-		for _, importer in _array_2 do
+		for _, importer in _array_4 do
 			if not importer.isExtinguished() then
 				importer.extinguish()
 			else
@@ -743,13 +831,13 @@ local function createModuleInstantiation(state, options)
 			end)
 		end
 		-- Copied first: removal callbacks may themselves remove instances.
-		local _array_2 = {}
-		local _length_1 = #_array_2
+		local _array_4 = {}
+		local _length_2 = #_array_4
 		for _v in temporaryInstances do
-			_length_1 += 1
-			_array_2[_length_1] = _v
+			_length_2 += 1
+			_array_4[_length_2] = _v
 		end
-		for _, temporaryInstance in _array_2 do
+		for _, temporaryInstance in _array_4 do
 			guarded("removing an instance", function()
 				return removeClassInstance(temporaryInstance)
 			end)
@@ -907,21 +995,35 @@ local function createModuleInstantiation(state, options)
 		scope = if hasCondition(moduleScope) then moduleScope else nil,
 		isActive = function(...)
 			local conditions = { ... }
-			local _array_2 = { moduleScope }
-			local _length_1 = #_array_2
-			table.move(conditions, 1, #conditions, _length_1 + 1, _array_2)
-			return holdsEveryCondition(_array_2)
+			local _array_4 = { moduleScope }
+			local _length_2 = #_array_4
+			table.move(conditions, 1, #conditions, _length_2 + 1, _array_4)
+			return holdsEveryCondition(_array_4)
 		end,
 		registerClassProvider = registerClassProvider,
-		registerProviders = function(_path, registrationOptions, resolved)
+		registerProviders = function(path, registrationOptions, resolved)
 			local _arg0 = resolved ~= nil
 			assert(_arg0)
-			registerProviderClasses(getClassesInPath(resolved), registrationOptions)
+			if holdsCondition(registrationOptions) then
+				registerProviderClasses(getClassesInPath(resolved, `registerProviders("{path}")`), registrationOptions)
+			else
+				local _arg0_1 = leftOutRegistration(`registerProviders("{path}")`, registrationOptions, {
+					path = resolved,
+				})
+				table.insert(leftOut, _arg0_1)
+			end
 		end,
-		registerProvidersGlob = function(_glob, registrationOptions, resolved)
+		registerProvidersGlob = function(glob, registrationOptions, resolved)
 			local _arg0 = resolved ~= nil
 			assert(_arg0)
-			registerProviderClasses(getClassesInGlob(resolved), registrationOptions)
+			if holdsCondition(registrationOptions) then
+				registerProviderClasses(getClassesInGlob(resolved), registrationOptions)
+			else
+				local _arg0_1 = leftOutRegistration(`registerProvidersGlob("{glob}")`, registrationOptions, {
+					glob = resolved,
+				})
+				table.insert(leftOut, _arg0_1)
+			end
 		end,
 		registerProvider = function(config, injectionId)
 			local _arg0 = injectionId ~= nil

package/out/module/moduleBuilder.d.ts

@@ -2,7 +2,7 @@ import { Modding } from "../modding";
 import { ModuleDefinition, ProviderConfig, type IgniteOptions, type ProviderRegistrationOptions } from "./moduleDefinition";
 import type { Constructor } from "../utility/constructors";
 import { type PluginDefinition } from "../plugin/pluginDefinition";
-import type { ScopeCondition } from "./scopes";
+import { type ScopeCondition } from "./scopes";
 type GenericId<T> = string | Modding.Target.Id<T>;
 export declare class ModuleBuilder {
     /** A global count of the number of module builders. Used to disambiguate identical module debug names. */
@@ -36,10 +36,16 @@ export declare class ModuleBuilder {
     /**
      * Register all providers under the specified path and its descendants.
      *
-     * The providers must be exported, and must carry the `@Provider()` decorator themselves: an
-     * undecorated subclass of a provider is not registered.
+     * Every `@Provider()` class the modules there define at their top level is registered, exported
+     * or not, as v1 registered every decorated class it required, and so is one they export from
+     * elsewhere; each once. A class declared inside a function is registered only if its module
+     * exports it. A provider must carry the `@Provider()` decorator itself: an undecorated subclass
+     * of a provider is not registered.
      *
      * The options apply to every provider found: a scope condition here scopes the whole folder.
+     * When it does not hold, the folder is not touched at all -- not looked up, nothing under it
+     * required -- so a build can leave the folder out of the place (a release build without its
+     * tests, say).
      *
      * @metadata macro
      */
@@ -51,6 +57,9 @@ export declare class ModuleBuilder {
      * This is the v2 equivalent of v1's `Flamework.addPathsGlob`. Globs can match a large number of
      * paths, so keep them as specific as possible.
      *
+     * As with `registerProviders`, a scope condition that does not hold leaves every matched folder
+     * untouched.
+     *
      * @metadata macro
      */
     registerProvidersGlob<T extends string>(_glob: T, options?: ProviderRegistrationOptions, glob?: Modding.Intrinsic<"pathglob", [T], string>): this;

package/out/module/moduleBuilder.luau

@@ -8,6 +8,8 @@ local LIFECYCLE_SLOT = TS.import(script, script.Parent.Parent, "plugin", "plugin
 local _providerRegistration = TS.import(script, script.Parent, "providerRegistration")
 local getProviderClassId = _providerRegistration.getProviderClassId
 local normalizeProviderConfig = _providerRegistration.normalizeProviderConfig
+local holdsCondition = TS.import(script, script.Parent, "scopes").holdsCondition
+local leftOutRegistration = TS.import(script, script.Parent.Parent, "utility", "leftOut").leftOutRegistration
 local ModuleBuilder
 do
 	ModuleBuilder = setmetatable({}, {
@@ -28,6 +30,7 @@ do
 			debugName = "Anonymous",
 			providers = {},
 			plugins = {},
+			leftOut = {},
 		}
 	end
 	function ModuleBuilder:includePlugin(plugin, options)
@@ -107,11 +110,30 @@ do
 	function ModuleBuilder:registerProviders(_stringPath, options, path)
 		local _path = path
 		assert(_path)
-		return self:registerProviderClasses(getClassesInPath(path), options)
+		-- The active scopes are the ones the build was compiled with, so this is the answer
+		-- ignition would give; what it would register is only ever skipped there. Recorded, so that
+		-- a miss on a class under the folder can say why it is missing.
+		if not holdsCondition(options) then
+			local _leftOut = self.module.leftOut
+			local _arg0 = leftOutRegistration(`registerProviders("{_stringPath}")`, options, {
+				path = path,
+			})
+			table.insert(_leftOut, _arg0)
+			return self
+		end
+		return self:registerProviderClasses(getClassesInPath(path, `registerProviders("{_stringPath}")`), options)
 	end
 	function ModuleBuilder:registerProvidersGlob(_glob, options, glob)
 		local _arg0 = glob ~= nil
 		assert(_arg0)
+		if not holdsCondition(options) then
+			local _leftOut = self.module.leftOut
+			local _arg0_1 = leftOutRegistration(`registerProvidersGlob("{_glob}")`, options, {
+				glob = glob,
+			})
+			table.insert(_leftOut, _arg0_1)
+			return self
+		end
 		return self:registerProviderClasses(getClassesInGlob(glob), options)
 	end
 	function ModuleBuilder:registerProviderClasses(classes, options)

package/out/module/moduleDefinition.d.ts

@@ -2,6 +2,7 @@ import type { Modding } from "../modding";
 import type { PluginDefinition } from "../plugin/pluginDefinition";
 import { type Module } from "./module";
 import type { ScopeCondition } from "./scopes";
+import type { LeftOutRegistration } from "../utility/leftOut";
 /**
  * Options for one ignition of a module.
  *
@@ -44,6 +45,11 @@ export interface ModuleState {
     readonly providers: readonly ModuleProvider[];
     /** The plugins to set up on ignition, in inclusion order. */
     readonly plugins: readonly PluginInclusion[];
+    /**
+     * The path and glob registrations left out by their own scope condition, whose folders were
+     * never looked up: what a miss on a class under one of them names.
+     */
+    readonly leftOut?: readonly LeftOutRegistration[];
 }
 export declare class ModuleDefinition {
     private moduleState;

package/out/module/providerRegistration.d.ts

@@ -20,3 +20,11 @@ export declare function normalizeProviderConfig(config: ProviderConfig): Provide
  * parent's scope.
  */
 export declare function getProviderClassScope(config: ProviderConfig): ScopeCondition;
+/** v1's default, which a provider that does not set `loadOrder` has. */
+export declare const DEFAULT_LOAD_ORDER = 1;
+/**
+ * Where a registration sits in its module's startup: its class's `loadOrder`, or the default. A
+ * lazy one has none (`undefined`): it starts when it is first resolved, whatever its decorator says.
+ * Own metadata, as everywhere else.
+ */
+export declare function getProviderLoadOrder(config: ProviderConfig): number | undefined;

package/out/module/providerRegistration.luau

@@ -72,9 +72,38 @@ local function getProviderClassScope(config)
 		inactiveIn = decoratorConfig.inactiveIn,
 	}
 end
+--* v1's default, which a provider that does not set `loadOrder` has. 
+local DEFAULT_LOAD_ORDER = 1
+--[[
+	*
+	 * Where a registration sits in its module's startup: its class's `loadOrder`, or the default. A
+	 * lazy one has none (`undefined`): it starts when it is first resolved, whatever its decorator says.
+	 * Own metadata, as everywhere else.
+	 
+]]
+local function getProviderLoadOrder(config)
+	if config.type ~= "class" then
+		return DEFAULT_LOAD_ORDER
+	end
+	if config.lazy == true then
+		return nil
+	end
+	local decoratorConfig = Reflect.getOwnMetadata(config.value, "flamework:providerConfig")
+	local _result = decoratorConfig
+	if _result ~= nil then
+		_result = _result.loadOrder
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = DEFAULT_LOAD_ORDER
+	end
+	return _condition
+end
 return {
 	assertIsProviderClass = assertIsProviderClass,
 	getProviderClassId = getProviderClassId,
 	normalizeProviderConfig = normalizeProviderConfig,
 	getProviderClassScope = getProviderClassScope,
+	getProviderLoadOrder = getProviderLoadOrder,
+	DEFAULT_LOAD_ORDER = DEFAULT_LOAD_ORDER,
 }

package/out/plugin/pluginDefinition.d.ts

@@ -52,15 +52,18 @@ export interface PluginTarget {
      */
     registerClassProvider: (provider: Constructor, options?: ProviderRegistrationOptions) => void;
     /**
-     * Registers every exported `@Provider()` class under a source folder, as the module builder's
-     * `registerProviders` does. This is how a plugin ships a folder of providers. The options apply
-     * to every class found.
+     * Registers every `@Provider()` class the modules under a source folder define, exported or not,
+     * as the module builder's `registerProviders` does. This is how a plugin ships a folder of
+     * providers. The options apply to every class found; when their scope condition does not hold,
+     * the folder is not looked up and nothing under it is required.
      *
      * @metadata macro
      */
     registerProviders: <T extends string>(path: T, options?: ProviderRegistrationOptions, resolved?: Modding.Intrinsic<"path", [T], string[]>) => void;
     /**
-     * Registers every exported `@Provider()` class under every folder a compile-time glob matches.
+     * Registers every `@Provider()` class the modules under every folder a compile-time glob matches
+     * define, exported or not. As with `registerProviders`, a scope condition that does not hold
+     * leaves the folders untouched.
      *
      * @metadata macro
      */

package/out/provider.d.ts

@@ -11,6 +11,25 @@ export interface ProviderDecoratorConfig extends ScopeCondition {
      * Defaults to `false`.
      */
     lazy?: boolean;
+    /**
+     * Orders this provider's `onInit` and `onStart` against the other providers the same ignition
+     * constructs, as v1's `loadOrder` did: lower goes first. Defaults to `1`; any finite number,
+     * negative and fractional ones included. Providers with the same `loadOrder` keep the order
+     * they would have without one.
+     *
+     * Dependency order still wins. The module constructs its providers in ascending `loadOrder`,
+     * each after what its constructor takes, so a provider's dependencies are constructed and
+     * initialised before it even when theirs is higher: a low `loadOrder` pulls what the provider
+     * needs forward with it. `onInit` runs in that construction order. `onStart` runs in ascending
+     * `loadOrder` alone, each on its own thread as always, so a lower one runs up to its first yield
+     * before the next is started.
+     *
+     * Only within one module's ignition: imported modules ignite, and start, before it. Per-frame
+     * events (`onTick`, `onPhysics`, `onRender`) stay unordered. A lazy provider is not part of
+     * the order: it is initialised and started when it is first resolved, and its `loadOrder` is
+     * ignored.
+     */
+    loadOrder?: number;
 }
 /**
  * Register a class as a provider.

package/out/provider.luau

@@ -17,6 +17,14 @@ local Reflect = TS.import(script, script.Parent, "reflect").Reflect
 ]]
 local function Provider(config)
 	return function(constructor)
+		local _loadOrder = config
+		if _loadOrder ~= nil then
+			_loadOrder = _loadOrder.loadOrder
+		end
+		local loadOrder = _loadOrder
+		if loadOrder ~= nil and (not (type(loadOrder) == "number") or not (math.abs(loadOrder) < math.huge)) then
+			error(`@Provider() on '{constructor}': loadOrder must be a finite number, got {tostring(loadOrder)} ({typeof(loadOrder)})`)
+		end
 		Reflect.defineMetadata(constructor, "flamework:provider", true)
 		Reflect.defineMetadata(constructor, "flamework:providerConfig", config or {})
 	end

package/out/reflect.luau

@@ -1,6 +1,7 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 local forgetImplements = TS.import(script, script.Parent, "utility", "implementsCache").forgetImplements
+local recordModuleClass = TS.import(script, script.Parent, "utility", "moduleClasses").recordModuleClass
 --[[
 	*
 	 * Reflection/metadata API
@@ -66,6 +67,11 @@ do
 		if key == "flamework:implements" then
 			forgetImplements(obj)
 		end
+		-- The transformer records the module a class was defined in under this key, which is how
+		-- path registration finds a class its module does not export.
+		if key == "flamework:module" and property == nil then
+			recordModuleClass(value, obj)
+		end
 	end
 	_container.defineMetadata = defineMetadata
 	--[[

package/out/utility/explainUnresolved.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Why a dependency no module resolved cannot be resolved, when its id names a Flamework class that
+ * has been loaded -- one a module defined at its top level, which the module record knows -- with
+ * what to do about it. Nothing for any other id: an interface, a type registered nowhere, a class
+ * defined inside a function or never required, whose failure keeps the plain message.
+ *
+ * `origin` is the class whose constructor asked, when one did.
+ */
+export declare function explainUnresolvedClass(id: string, origin?: object): string | undefined;