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

package/README.md

@@ -1,15 +1,17 @@
 # Flamework
 
-Flamework is an extensible framework for roblox-ts designed around portable, isolated and testable modules.
+Flamework is an extensible framework for roblox-ts. It is built around modules that are portable,
+isolated and easy to test.
 
 ## Documentation
 
-**[docs/](docs/README.md)** -- start there. A ten-part guide that builds up from a working entry
-point to plugins and project layout, plus reference material:
+Start with **[docs/](docs/README.md)**. It holds a twelve-part guide, which starts from a working
+entry point and builds up to plugins, project layout, scopes and testing. It also holds reference
+material:
 
 | | |
 |---|---|
-| [Guide](docs/README.md#guide) | Getting started, modules, providers, lifecycle events, components, networking, macros, plugins, project structure, migrating from v1. |
+| [Guide](docs/README.md#guide) | Getting started, modules, providers, lifecycle events, components, networking, macros, plugins, project structure, migrating from v1, scopes, testing in the place. |
 | [Internals](docs/reference/internals.md) | What the transformer does to your code and what the runtime does with the result. |
 | [Transformer plugins](docs/reference/transformer-plugins.md) | Adding macro types of your own. |
 
@@ -37,36 +39,36 @@ bun run test:place     # the in-place suite in Roblox Studio (tests/place); need
 | `packages/core` | Modules, dependency injection, plugins and lifecycle events |
 | `packages/components` | CollectionService components, built on the core plugin system |
 | `packages/networking` | Remote events and functions |
-| `packages/testing` | In-place tests: sections, cleanup, a bindable and a remote to run them, a cloud entry; and `flamework-test`, the CLI that runs them in Roblox Studio on this machine or through Open Cloud (`cli/`) |
+| `packages/testing` | Tests that run inside a place: sections, cleanup, a bindable and a remote that run them, and a cloud entry point. Also `flamework-test` (`cli/`), the CLI that runs them in Roblox Studio on this machine or through Open Cloud |
 | `packages/transformer` | The roblox-ts transformer |
 | `packages/transformer-plugin` | Public API for writing transformer plugins |
-| `packages/specs` | Runtime specs, compiled by `rbxtsc` and executed under Lune |
+| `packages/specs` | Runtime specs, built by `rbxtsc` and run under Lune |
 
 ### Tests
 
-Two suites, both run by `bun run test`:
-
-- **Transformer tests** (`bun run test:unit`) compile a fixture project with the real `rbxtsc` and
-  assert on the emitted Luau — guard generation, identifiers, nested macros and the plugin system.
-- **Runtime specs** (`bun run test:runtime`) execute compiled `@flamework-experimental/core`, `components` and
-  `networking` under Lune using the harness in [`tests/runtime`](tests/runtime), which models
-  roblox-ts's `TS.import` tree over the filesystem and stubs the Roblox API surface Flamework
-  touches (Instances, attributes, CollectionService, RemoteEvents, Players, signals, `task`,
-  `Enum`, and a `Heartbeat` pump so `Promise.delay` -- and therefore request timeouts -- runs).
-  They cover dependency injection, modules, hooks and the per-frame lifecycle events, component
-  construction, dependencies and streaming, and both halves of networking: events, functions,
-  middleware and the generated guards.
-
-  They run twice, once as `Server` and once as `Client`, because realm-dependent code paths --
-  `@Provider`'s metadata, component streaming, and the client/server halves of networking -- differ
-  between them. Where a spec asserts something realm-specific, running it from both sides is what
-  proves the two agree: a function receives on `$name` and sends on `@name` from the server and the
-  mirror image from the client, so the pair of runs pins the wire format down from both ends.
-
-Specs live in [`packages/specs`](packages/specs) and are compiled by `rbxtsc` like any other
-Flamework consumer, so they exercise the transformer and the runtime together.
-
-A third suite runs against the real engine and is left out of `bun run test`: the
-[test place](tests/place/README.md), a small game linked to the packages' builds, whose
-`@flamework-experimental/testing` sections `bun run test:place` runs in Roblox Studio, both realms,
-under four Rojo projects (see [Testing in Roblox Studio](docs/testing/studio.md)).
+`bun run test` runs two suites:
+
+- **Transformer tests** (`bun run test:unit`) build a fixture project with the real `rbxtsc` and
+  check the Luau it emits: guard generation, identifiers, nested macros and the plugin system.
+- **Runtime specs** (`bun run test:runtime`) run the built `@flamework-experimental/core`,
+  `components` and `networking` packages under Lune. The harness in [`tests/runtime`](tests/runtime)
+  models roblox-ts's `TS.import` tree over the filesystem. It also stubs the parts of the Roblox API
+  that Flamework uses: Instances, attributes, CollectionService, RemoteEvents, Players, signals,
+  `task`, `Enum`, and a `Heartbeat` pump so that `Promise.delay` runs (and with it, request
+  timeouts). The specs cover dependency injection, modules, hooks and the per-frame lifecycle
+  events; component construction, dependencies and streaming; and both halves of networking:
+  events, functions, middleware and the generated guards.
+
+  The specs run twice, once as `Server` and once as `Client`, because some code paths depend on the
+  realm: `@Provider`'s metadata, component streaming, and the client and server halves of
+  networking. Running a realm-specific spec from both sides proves that the two sides agree. For
+  example, from the server a function receives on `$name` and sends on `@name`, and from the client
+  it does the reverse, so the two runs pin down the wire format from both ends.
+
+Specs live in [`packages/specs`](packages/specs). `rbxtsc` builds them like any other project that
+uses Flamework, so they test the transformer and the runtime together.
+
+A third suite runs against the real engine, and `bun run test` leaves it out. It lives in the
+[test place](tests/place/README.md), a small game linked to the packages' builds.
+`bun run test:place` runs its `@flamework-experimental/testing` sections in Roblox Studio, on both
+realms, under four Rojo projects (see [Testing in Roblox Studio](docs/testing/studio.md)).

package/flamework.build

@@ -1,6 +1,6 @@
 {
 	"version": 1,
-	"flameworkVersion": "2.0.0-alpha.3",
+	"flameworkVersion": "2.0.0-alpha.4",
 	"identifiers": {
 		"@flamework-experimental/core:out/module/module@Module": "$:module/module@Module",
 		"@flamework-experimental/core:out/lifecycle/lifecyclePlugin@LifecycleProvider": "$:lifecycle/lifecyclePlugin@LifecycleProvider",

package/out/dependency.d.ts

@@ -10,6 +10,10 @@ import type { Module } from "./module/module";
  * handed to something outside Flamework. Inside a provider, take a constructor parameter instead:
  * it declares the dependency where it can be read, and it orders construction.
  *
+ * It resolves what the module registers -- providers, and what plugins provide -- and nothing else:
+ * unlike v1, it does not build an unregistered class on demand. A component is never one; the
+ * transformer refuses `Dependency<T>()` on a `@Component()` class, which `Components` hands out.
+ *
  * Raises if no module was given and none has been ignited yet, or if the default has since been
  * extinguished.
  *

package/out/dependency.luau

@@ -12,6 +12,10 @@ local getDefaultModule = TS.import(script, script.Parent, "module", "defaultModu
 	 * handed to something outside Flamework. Inside a provider, take a constructor parameter instead:
 	 * it declares the dependency where it can be read, and it orders construction.
 	 *
+	 * It resolves what the module registers -- providers, and what plugins provide -- and nothing else:
+	 * unlike v1, it does not build an unregistered class on demand. A component is never one; the
+	 * transformer refuses `Dependency<T>()` on a `@Component()` class, which `Components` hands out.
+	 *
 	 * Raises if no module was given and none has been ignited yet, or if the default has since been
 	 * extinguished.
 	 *

package/out/index.d.ts

@@ -13,7 +13,7 @@ export { HookPriority } from "./module/moduleHooks";
 export type { Module, ProviderLookup } from "./module/module";
 export type { IgniteOptions, InjectionContext, ModuleProvider, ModuleState, PluginInclusion, ProviderConfig, ProviderRegistrationOptions, } from "./module/moduleDefinition";
 export type { HookOptions } from "./module/moduleHooks";
-export { describeConditions, holdsCondition, holdsEveryCondition, __setActiveScopes } from "./module/scopes";
+export { describeConditions, holdsCondition, holdsEveryCondition } from "./module/scopes";
 export type { ScopeCondition } from "./module/scopes";
 export { PluginDefinition } from "./plugin/pluginDefinition";
 export { LifecyclePlugin, LifecycleProvider, createLifecyclePlugin } from "./lifecycle/lifecyclePlugin";
@@ -22,7 +22,9 @@ export type { InterfaceConfiguration, InterfaceContext, InterfaceTargetKind, Plu
 export type { OnExtinguished, OnInit, OnPhysics, OnRender, OnStart, OnTick } from "./lifecycle/lifecycleInterfaces";
 export { getClassesInPath, importModule, requireModulesInPath } from "./utility/getClassesInPath";
 export { getClassesInGlob, getGlobPaths } from "./utility/globs";
-export { getPathRoot, resolveRbxPath, __setPathRoot } from "./utility/pathRoot";
+export { getPathRoot, resolveRbxPath } from "./utility/pathRoot";
+export { explainLeftOut, leftOutRegistration } from "./utility/leftOut";
+export type { LeftOutRegistration } from "./utility/leftOut";
 export { getRuntimeConfig } from "./utility/runtimeConfig";
 export type { ComponentsRuntimeConfig, CoreRuntimeConfig, NetworkingRuntimeConfig, RuntimeConfig, ScopesRuntimeConfig, TestingRuntimeConfig, } from "./utility/runtimeConfig";
 export type { AbstractConstructor, Constructor } from "./utility/constructors";

package/out/init.luau

@@ -16,7 +16,6 @@ local _scopes = TS.import(script, script, "module", "scopes")
 exports.describeConditions = _scopes.describeConditions
 exports.holdsCondition = _scopes.holdsCondition
 exports.holdsEveryCondition = _scopes.holdsEveryCondition
-exports.__setActiveScopes = _scopes.__setActiveScopes
 -- Plugins
 exports.PluginDefinition = TS.import(script, script, "plugin", "pluginDefinition").PluginDefinition
 local _lifecyclePlugin = TS.import(script, script, "lifecycle", "lifecyclePlugin")
@@ -35,6 +34,15 @@ exports.getGlobPaths = _globs.getGlobPaths
 local _pathRoot = TS.import(script, script, "utility", "pathRoot")
 exports.getPathRoot = _pathRoot.getPathRoot
 exports.resolveRbxPath = _pathRoot.resolveRbxPath
-exports.__setPathRoot = _pathRoot.__setPathRoot
+local _leftOut = TS.import(script, script, "utility", "leftOut")
+exports.explainLeftOut = _leftOut.explainLeftOut
+exports.leftOutRegistration = _leftOut.leftOutRegistration
 exports.getRuntimeConfig = TS.import(script, script, "utility", "runtimeConfig").getRuntimeConfig
+-- The test harness's hooks: exported for the Luau it reaches through the package entry, and marked
+-- @internal like their declarations so that stripInternal leaves them out of the typings as well
+-- (a re-export of a stripped declaration would not type-check).
+--* @internal 
+exports.__setActiveScopes = TS.import(script, script, "module", "scopes").__setActiveScopes
+--* @internal 
+exports.__setPathRoot = TS.import(script, script, "utility", "pathRoot").__setPathRoot
 return exports

package/out/lifecycle/lifecyclePlugin.d.ts

@@ -22,8 +22,13 @@ export declare class LifecycleProvider {
     /** In attachment order, which for providers is dependency order. */
     private onInit;
     private initMembers;
-    /** The providers `postIgnite` starts, in attachment order; `onStart` is every member. */
+    /** The providers `start` starts, in attachment order; `onStart` is every member. */
     private startOrder;
+    /**
+     * The `loadOrder` of each provider in `startOrder` that has one other than the default, which
+     * `start` orders them by. Empty unless a provider sets one, and emptied once they have started.
+     */
+    private startLoadOrders;
     onStart: Set<OnStart>;
     onTick: Set<OnTick>;
     onPhysics: Set<OnPhysics>;
@@ -228,6 +233,13 @@ export declare class LifecycleProvider {
      * extinguished while an `onInit` yielded had the providers started against it first.
      */
     start(module: Module): void;
+    /**
+     * A copy of the providers to start, in ascending `loadOrder`: each on its own thread, so a lower
+     * one runs up to its first yield before the next is started. Attachment order -- dependency order
+     * -- among equals, and unchanged when no provider sets one. Sorted once, at ignition: nothing per
+     * frame is ordered.
+     */
+    private inLoadOrder;
     extinguished(module: Module): void;
     private tellExtinguished;
 }

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), 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)
+		-- 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), 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)