moost 0.6.31 → 0.6.33

package/dist/index.cjs

@@ -6,6 +6,55 @@ let _prostojs_logger = require("@prostojs/logger");
 let hookable = require("hookable");
 let wooks = require("wooks");
 
+//#region packages/moost/src/module-identity.ts
+/**
+* Duplicate-copy detection for moost
+*
+* Mate stores decorator metadata in WeakMaps keyed by constructor
+* reference, and moost keeps module-scoped DI singletons
+* (`sharedMoostInfact`, `moostMate`). If a bundler loads two copies of
+* moost, decorators run against one copy while lookups hit the other,
+* and DI fails with distant "Class is not Injectable" errors. The first
+* loaded copy stamps `globalThis` under a global symbol; any subsequent
+* copy finds the stamp and warns.
+*/ const MOOST_MODULE_IDENTITY_KEY = Symbol.for("moost:module-identity");
+function describeCopy(identity) {
+	return `${identity.version || "unknown version"} at ${identity.path || "unknown path"}`;
+}
+/**
+* Stamps the global object with this module's identity and warns when
+* another copy of moost was already loaded — decorator metadata and DI
+* singletons do not interoperate between copies.
+*
+* Exported for testability; invoked once at module scope.
+*/ function stampModuleIdentity(identity, globalObject = globalThis) {
+	const holder = globalObject;
+	const existing = holder[MOOST_MODULE_IDENTITY_KEY];
+	if (existing) console.warn(`[moost] A second copy of moost was loaded (${describeCopy(existing)}, now ${describeCopy(identity)}). Decorator metadata and DI singletons will NOT interoperate between copies. Check your bundler config / dedupe settings.`);
+	else holder[MOOST_MODULE_IDENTITY_KEY] = identity;
+}
+let stamped = false;
+/**
+* One-shot wrapper around `stampModuleIdentity` for this module copy.
+*
+* Invoked at module scope AND from `getMoostMate()`: the package ships
+* `"sideEffects": false`, so a tree-shaking bundler may drop the
+* module-scope invocation when nothing imports from this file — the
+* `getMoostMate()` call keeps the duplicate check reachable in bundled
+* apps (it fires on first decorator use, exactly when per-copy metadata
+* divergence begins), which are the environments that produce duplicate
+* copies in the first place.
+*/ function stampOnce() {
+	if (stamped) return;
+	stamped = true;
+	stampModuleIdentity({
+		version: "0.6.33",
+		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
+	});
+}
+stampOnce();
+
+//#endregion
 //#region packages/moost/src/logger.ts
 let defaultLogger;
 function setDefaultLogger(logger) {
@@ -63,6 +112,74 @@ function runPipes(pipes, initialValue, metas, level) {
 	return v;
 }
 
+//#endregion
+//#region packages/moost/src/metadata/diagnostics.ts
+let sourceRefs = [];
+/** Dereferences the registered sources, pruning refs whose target was collected. */ function scanLiveSources() {
+	const live = [];
+	const keep = [];
+	for (const ref of sourceRefs) {
+		const source = ref.deref();
+		if (source) {
+			live.push(source);
+			keep.push(ref);
+		}
+	}
+	sourceRefs = keep;
+	return live;
+}
+/**
+* Registers a Moost app as a source for DI diagnostics scans (D4 scope
+* hints). Held via `WeakRef` so a dropped app never leaks; registering the
+* same app again is a no-op.
+*/ function registerDiagnosticsSource(source) {
+	if (scanLiveSources().includes(source)) return;
+	sourceRefs.push(new WeakRef(source));
+}
+/**
+* Scans the registered apps' controllers for a class-scoped `@Provide`
+* carrying `token` and returns the provider controller class names. Both
+* string and symbol keys are checked — symbol class-tokens match by identity
+* because infact keys them via `Symbol.for` (same class source, same symbol).
+*/ function findTokenProviders(token) {
+	const providers = [];
+	for (const source of scanLiveSources()) for (const entry of source.getControllersOverview()) if (Reflect.ownKeys(entry.meta?.provide ?? {}).includes(token) && !providers.includes(entry.type.name)) providers.push(entry.type.name);
+	return providers;
+}
+const CLASS_SOURCE_RE = /^class\s+([\w$]+)/;
+/** Renders a provide token readably: strings as-is, class-source symbols by class name. */ function stringifyToken(token) {
+	if (typeof token === "string") return token;
+	const description = token.description ?? token.toString();
+	const match = CLASS_SOURCE_RE.exec(description);
+	return match ? match[1] : description;
+}
+/**
+* D4: when an unresolved `@Inject(token)` IS provided somewhere — via a
+* class-scoped `@Provide` on a sibling controller — teaches the actual
+* scoping rule (providers flow parent → child, never to siblings) and names
+* both remedies. Returns `undefined` when no provider was found.
+*/ function formatScopeHint(token, providerNames) {
+	if (providerNames.length === 0) return;
+	const subject = providerNames.length === 1 ? `sibling controller ${providerNames[0]}` : `sibling controllers ${providerNames.join(", ")}`;
+	return `Token "${stringifyToken(token)}" is provided on ${subject} via class-scoped @Provide, which is only visible to that controller's own subtree (providers flow parent → child through @ImportController, never to siblings). Move it to app.setProvideRegistry(...) or to a common parent @ImportController.`;
+}
+/**
+* D2: renders an infact instantiation error with the consumer-side context
+* carried by `detail` — parameter position/label/type plus the resolution
+* hierarchy — as one multi-line message (single `logger.error` call). The
+* `import type` hint is already appended to `message` upstream by infact and
+* is deliberately not duplicated here.
+*/ function formatInfactErrorContext(targetClassName, message, detail) {
+	let head = `Failed to instantiate ${targetClassName}`;
+	if (typeof detail.paramIndex === "number") {
+		const qualifiers = [detail.paramLabel === void 0 ? "" : `label "${detail.paramLabel}"`, detail.paramTypeName === void 0 ? "" : `type ${detail.paramTypeName}`].filter(Boolean).join(", ");
+		head += `: constructor parameter #${detail.paramIndex}${qualifiers ? ` (${qualifiers})` : ""}`;
+	}
+	const lines = [`${head} — ${message}`];
+	if (detail.hierarchy && detail.hierarchy.length > 0) lines.push(`  Hierarchy: ${detail.hierarchy.join(" → ")}`);
+	return lines.join("\n");
+}
+
 //#endregion
 //#region packages/moost/src/metadata/moost-metadata.ts
 const METADATA_WORKSPACE = "moost";
@@ -86,6 +203,7 @@ const moostMate = new _prostojs_mate.Mate(METADATA_WORKSPACE, {
 	}
 });
 /** Returns the shared `Mate` instance operating in the `'moost'` metadata workspace. */ function getMoostMate() {
+	stampOnce();
 	return moostMate;
 }
 
@@ -125,6 +243,66 @@ const scopeVarsMap = /* @__PURE__ */ new Map();
 */ function getInfactScopeVars(name) {
 	return scopeVarsMap.get(name);
 }
+/** Applies the `setInfactLoggingOptions` filters to an Infact event. */ function shouldLogInfactEvent(event, targetClass) {
+	if (event === "warn") return !!loggingOptions.warn;
+	if (event === "error") return !!loggingOptions.error;
+	const scope = getMoostMate().read(targetClass)?.injectable || "SINGLETON";
+	return loggingOptions.newInstance !== false && (loggingOptions.newInstance === scope || loggingOptions.newInstance === "SINGLETON" && scope === true);
+}
+/** Renders the DI resolution-hierarchy breadcrumb (`⋱ A → B`). */ function formatHierarchy(args) {
+	return `⋱ ${args?.map(String).join(" → ") || ""}`;
+}
+function formatNewInstanceArg(a) {
+	switch (typeof a) {
+		case "number":
+		case "boolean": return `${a}`;
+		case "string": return `"${a.slice(0, 1)}..."`;
+		case "object":
+			if (Array.isArray(a)) return `[${a.length}]`;
+			if ((0, _prostojs_mate.getConstructor)(a)) return (0, _prostojs_mate.getConstructor)(a).name;
+			return "{}";
+		default: return "*";
+	}
+}
+/** Renders the resolved constructor args for the `new-instance` log line. */ function formatNewInstanceParams(args) {
+	return args?.map((a) => `${formatNewInstanceArg(a)}`).join(", ") || "";
+}
+/**
+* Renders an `'error'` event. Without `detail` (everything the installed
+* @prostojs/infact@0.4.1 ever produces) the output is exactly the legacy
+* format. With `detail` (newer infact) the D2 consumer context is rendered
+* and, when the failing `@Inject` token is class-provided on a sibling
+* controller of a registered app, the D4 scope hint is appended.
+*/ function renderInfactError(targetClass, message, args, detail) {
+	if (!detail) return `Failed to instantiate ${`${targetClass.name}`}. ${message} ${formatHierarchy(args)}`;
+	let text = formatInfactErrorContext(targetClass.name, message, detail);
+	if (detail.injectToken !== void 0) {
+		const hint = formatScopeHint(detail.injectToken, findTokenProviders(detail.injectToken));
+		if (hint) text += `\n  ${hint}`;
+	}
+	return text;
+}
+/**
+* Infact event sink. Declared with the forward-compatible 5-param signature:
+* the installed @prostojs/infact (0.4.1) calls it with 4 args (never passes
+* `detail`), while newer infact versions pass a `detail` payload on `'error'`
+* events that unlocks the rich D2/D4 rendering (see `renderInfactError`).
+*
+* Exported for tests — since 0.4.1 never passes `detail` at runtime, the
+* detail-driven path is exercised by invoking this function directly.
+*/ function onInfactEvent(event, targetClass, message, args, detail) {
+	if (!shouldLogInfactEvent(event, targetClass)) return;
+	let logger;
+	try {
+		logger = event === "error" ? getDefaultLogger(INFACT_BANNER) : (0, _wooksjs_event_core.useLogger)(INFACT_BANNER);
+	} catch {
+		logger = getDefaultLogger(INFACT_BANNER);
+	}
+	const instance = `${targetClass.name}`;
+	if (event === "new-instance") logger.info(`new ${instance}(${formatNewInstanceParams(args)})`);
+	else if (event === "warn") logger.warn(`${instance} - ${message} ${formatHierarchy(args)}`);
+	else logger.error(renderInfactError(targetClass, message, args, detail));
+}
 /**
 * Get Infact instance (used for Dependency Injections)
 */ function getNewMoostInfact() {
@@ -168,58 +346,7 @@ const scopeVarsMap = /* @__PURE__ */ new Map();
 			}, "PROP");
 		},
 		storeProvideRegByInstance: true,
-		on: (event, targetClass, message, args) => {
-			switch (event) {
-				case "new-instance": {
-					const scope = getMoostMate().read(targetClass)?.injectable || "SINGLETON";
-					if (loggingOptions.newInstance === false || !(loggingOptions.newInstance === scope || loggingOptions.newInstance === "SINGLETON" && scope === true)) return;
-					break;
-				}
-				case "warn":
-					if (!loggingOptions.warn) return;
-					break;
-				case "error":
-					if (!loggingOptions.error) return;
-					break;
-				default:
-			}
-			let logger;
-			try {
-				logger = event === "error" ? getDefaultLogger(INFACT_BANNER) : (0, _wooksjs_event_core.useLogger)(INFACT_BANNER);
-			} catch {
-				logger = getDefaultLogger(INFACT_BANNER);
-			}
-			const instance = `${targetClass.name}`;
-			switch (event) {
-				case "new-instance": {
-					const params = args?.map((a) => {
-						switch (typeof a) {
-							case "number":
-							case "boolean": return `${a}`;
-							case "string": return `"${a.slice(0, 1)}..."`;
-							case "object":
-								if (Array.isArray(a)) return `[${a.length}]`;
-								if ((0, _prostojs_mate.getConstructor)(a)) return (0, _prostojs_mate.getConstructor)(a).name;
-								return "{}";
-							default: return "*";
-						}
-					}).map((a) => `${a}`).join(", ") || "";
-					logger.info(`new ${instance}(${params})`);
-					break;
-				}
-				case "warn": {
-					const hier = `⋱ ${args?.map(String).join(" → ") || ""}`;
-					logger.warn(`${instance} - ${message} ${hier}`);
-					break;
-				}
-				case "error": {
-					const hier = `⋱ ${args?.map(String).join(" → ") || ""}`;
-					logger.error(`Failed to instantiate ${instance}. ${message} ${hier}`);
-					break;
-				}
-				default: break;
-			}
-		}
+		on: onInfactEvent
 	});
 }
 
@@ -482,11 +609,20 @@ function nextScopeId() {
 		...Object.getOwnPropertyNames(instance)
 	])].filter((m) => typeof instance[m] !== "function");
 }
-const fnProto = Object.getPrototypeOf(Function);
+/**
+* Walks the user-defined ancestor classes of a constructor, closest first.
+* Terminates at `Function.prototype` (it is a function but has no `.prototype`).
+*/ function* ancestorsOf(classConstructor) {
+	let parent = Object.getPrototypeOf(classConstructor);
+	while (typeof parent === "function" && parent.prototype) {
+		yield parent;
+		parent = Object.getPrototypeOf(parent);
+	}
+}
 function getParentProps(constructor) {
-	const parent = Object.getPrototypeOf(constructor);
-	if (typeof parent === "function" && parent !== fnProto && parent !== constructor && parent.prototype) return [...getParentProps(parent), ...Object.getOwnPropertyNames(parent.prototype)];
-	return [];
+	const props = [];
+	for (const parent of ancestorsOf(constructor)) props.unshift(...Object.getOwnPropertyNames(parent.prototype));
+	return props;
 }
 
 //#endregion
@@ -644,11 +780,20 @@ function ImportController(prefix, controller, provide) {
 	return getMoostMate().apply(getMoostMate().decorate("paramSource", "ROUTE"), getMoostMate().decorate("paramName", name), Resolve(() => (0, _wooksjs_event_core.useRouteParams)().get(name), name));
 }
 /**
-* Get Parsed Params from url parh
+* Get Parsed Params from url path
+*
+* Stamps `paramSource: 'ROUTE'` metadata (like `@Param(name)` does), so
+* source-aware pipes (e.g. coercion pipes that only coerce string-transport
+* input) recognize the whole params object as route input.
+*
+* Tip: type the argument with an interface-based DTO (e.g. an atscript `.as`
+* interface) — interfaces emit as `declare class`, so the design type survives
+* every metadata toolchain, unlike scalar type aliases which only survive
+* syntactic emitters.
 * @decorator
 * @paramType object
 */ function Params() {
-	return Resolve(() => (0, _wooksjs_event_core.useRouteParams)().params, "params");
+	return getMoostMate().apply(getMoostMate().decorate("paramSource", "ROUTE"), Resolve(() => (0, _wooksjs_event_core.useRouteParams)().params, "params"));
 }
 /**
 * Provide Const Value
@@ -1381,6 +1526,51 @@ function getIterceptorHandlerFactory(interceptors, getTargetInstance, pipes) {
 	return () => new InterceptorHandler(precomputedHandlers);
 }
 
+//#endregion
+//#region packages/moost/src/binding/param-audit.ts
+/**
+* Resolves the effective param-audit mode: an explicit setting wins; otherwise
+* `'error'` in dev (`NODE_ENV !== 'production'`) and `'warn'` in production.
+*/ function resolveParamAuditMode(setting) {
+	if (setting) return setting;
+	return process.env.NODE_ENV === "production" ? "warn" : "error";
+}
+/**
+* True when the param carries no explicit resolution (`@Resolve`-based
+* decorators, `@Inject`, `@Circular`) and its emitted design type is unusable
+* for DI — `Object` (class erased by `import type`, or an interface/union) or
+* `undefined` (circular import). Such a param falls through to
+* `infact.get(param.type)` and fails there or silently injects `undefined`.
+*/ function isBrokenFallThrough(param) {
+	return !param.resolver && !param.inject && !param.circular && (param.type === Object || param.type === void 0);
+}
+function buildMessage(ctx, index, param) {
+	const where = `[moost] ${ctx.className}.${ctx.methodName ?? "constructor"} parameter #${index}`;
+	if (!ctx.methodName) return param.type === void 0 ? `${where} has no emitted design type — usually a circular import. Use @Circular(() => Type).` : `${where} has type Object — its class was likely imported with 'import type', or it is an interface/union type. Use a value import, an explicit @Inject(token) or @Resolve(), or mark it @Optional() to silence.`;
+	return param.type === void 0 ? `${where} has no emitted design type (usually a circular import) and no param decorator — it will resolve to undefined at event time. Add a param decorator (e.g. @Param/@Body) or @Resolve().` : `${where} has type Object and no param decorator — it will resolve to undefined at event time. Add a param decorator (e.g. @Param/@Body) or @Resolve(); if the type is a class imported with 'import type', use a value import.`;
+}
+function severityOf(ctx, param) {
+	if (ctx.methodName) return "warn-only";
+	return param.optional || param.nullable ? "warn-only" : "fatal-capable";
+}
+/**
+* D1 bind-time param audit: returns a finding for every param that will fall
+* through to DI class-instantiation with a broken emitted type (`Object` or
+* `undefined`) and no explicit resolution. Pure — the caller decides how to
+* log/throw (see `Moost.init()`).
+*/ function auditParams(params, ctx) {
+	const findings = [];
+	for (const [index, param] of (params || []).entries()) if (param && isBrokenFallThrough(param)) findings.push({
+		message: buildMessage(ctx, index, param),
+		severity: severityOf(ctx, param)
+	});
+	return findings;
+}
+/** Formats the aggregate error thrown by `init()` when fatal-capable findings exist. */ function formatParamAuditError(findings) {
+	const list = findings.map((f) => `  - ${f.message}`).join("\n");
+	return `[moost] DI param audit failed (${findings.length} finding${findings.length === 1 ? "" : "s"}):\n${list}\nSet diagnostics: { paramTypes: 'warn' } (or 'off') on Moost options to downgrade.`;
+}
+
 //#endregion
 //#region packages/moost/src/binding/bind-controller.ts
 async function bindControllerMethods(options) {
@@ -1403,6 +1593,10 @@ async function bindControllerMethods(options) {
 	};
 	for (const method of methods) {
 		const methodMeta = getMoostMate().read(fakeInstance, method) || {};
+		if (options.reportParamAudit && (methodMeta.moostInit || methodMeta.handlers?.length)) options.reportParamAudit(auditParams(methodMeta.params, {
+			className: classConstructor.name,
+			methodName: method
+		}));
 		if (methodMeta.moostInit) {
 			if (meta.injectable === "FOR_EVENT") throw new Error(`@MoostInit is not allowed on a FOR_EVENT controller (${classConstructor.name}.${String(method)}). Init hooks run once at boot on the SINGLETON instance; FOR_EVENT controllers have no init-time instance.`);
 			const initArgsPipes = (methodMeta.params || []).map((p) => ({
@@ -1473,6 +1667,93 @@ async function bindControllerMethods(options) {
 	return controllerOverview;
 }
 
+//#endregion
+//#region packages/moost/src/binding/inheritance-audit.ts
+/** Counts handler metas on the class' own prototype methods (its inherit rules applied). */ function countHandlers(classConstructor) {
+	const mate = getMoostMate();
+	let count = 0;
+	for (const name of Object.getOwnPropertyNames(classConstructor.prototype)) if (name !== "constructor") count += mate.read(classConstructor, name)?.handlers?.length ?? 0;
+	return count;
+}
+/**
+* Names the classes strictly between `classConstructor` and `ancestor` that
+* carry no truthy `@Inherit` — the links that break the metadata bridge
+* (both `@Inherit()` and the parent-params fallback cross one level at a time).
+*/ function brokenLinksBetween(classConstructor, ancestor) {
+	const mate = getMoostMate();
+	const links = [];
+	for (const parent of ancestorsOf(classConstructor)) {
+		if (parent === ancestor) break;
+		if (!mate.read(parent)?.inherit) links.push(parent.name);
+	}
+	return links;
+}
+/**
+* Route-drop trap: the registered class contributed 0 handlers while an
+* ancestor defines some — its routes silently 404. Fires when the class
+* carries no `@Inherit` decision (routes never flow by default) AND when it
+* carries `@Inherit()` but nothing flowed (that combination is always a bridge
+* broken by intermediate classes without `@Inherit()` of their own). An
+* explicit `@Inherit(false)` is a deliberate opt-out and stays silent.
+*/ function auditRouteDrop(input) {
+	if (input.ownHandlersCount > 0 || input.classMeta?.inherit === false) return;
+	for (const ancestor of ancestorsOf(input.classConstructor)) {
+		const count = countHandlers(ancestor);
+		if (count > 0) return {
+			severity: "warn-only",
+			message: routeDropMessage(input, ancestor, count)
+		};
+	}
+}
+function routeDropMessage(input, ancestor, count) {
+	const name = input.classConstructor.name;
+	if (input.classMeta?.inherit) {
+		const links = brokenLinksBetween(input.classConstructor, ancestor);
+		const brokenBy = links.length > 0 ? `the intermediate class(es) ${links.join(", ")} carry no @Inherit()` : "the inherit chain between them is broken";
+		return `[moost] ${name} has @Inherit() but registered 0 route handler(s) while its ancestor ${ancestor.name} defines ${count} — @Inherit() bridges one level at a time and ${brokenBy}. Add @Inherit() to each intermediate class or re-declare the routes.`;
+	}
+	return `[moost] ${name} extends ${ancestor.name} which defines ${count} route handler(s), but ${name} registered 0 and has no @Inherit() — parent routes are not inherited without it. Add @Inherit() or re-declare the routes.`;
+}
+/**
+* Lost-constructor-params trap: a DI-instantiated class whose effective params
+* metadata is absent while a decorated ancestor declares constructor params.
+* Covers two shapes:
+* - the class carries no Moost metadata at all (undecorated subclass registered
+*   as a controller) — it is not even seen as injectable;
+* - the class is decorated but an undecorated intermediate class breaks the
+*   automatic parent-params fallback (metadata reads walk one level only).
+* An own zero-param constructor emits `params: []` and is a deliberate choice —
+* only truly absent params fire.
+*/ function auditLostCtorParams(input) {
+	if (!input.diInstantiated || input.classMeta?.params) return;
+	const mate = getMoostMate();
+	for (const ancestor of ancestorsOf(input.classConstructor)) {
+		const count = mate.read(ancestor)?.params?.length ?? 0;
+		if (count > 0) return {
+			severity: "warn-only",
+			message: lostCtorParamsMessage(input, ancestor, count)
+		};
+	}
+}
+function lostCtorParamsMessage(input, ancestor, count) {
+	const name = input.classConstructor.name;
+	if (input.classMeta) {
+		const links = brokenLinksBetween(input.classConstructor, ancestor);
+		const intermediates = links.length > 0 ? ` (${links.join(", ")})` : "";
+		return `[moost] ${name} has no constructor param metadata, but its ancestor ${ancestor.name} declares ${count} constructor param(s) — the inherited constructor would be invoked with zero resolved arguments (dependencies undefined). The parent-params fallback crosses one level at a time: add @Inherit() to the intermediate class(es)${intermediates} or re-declare the constructor with its param decorators.`;
+	}
+	return `[moost] ${name} extends ${ancestor.name} whose constructor declares ${count} DI param(s), but ${name} carries no Moost metadata of its own — it is not seen as injectable and the constructor params will not resolve. Add @Inherit() to ${name} or re-declare the constructor.`;
+}
+/**
+* Bind-time inheritance audit (IMPROVEMENTS.md §3): detects the two real traps
+* of subclassing decorated classes — parent routes silently dropping without a
+* working `@Inherit()` bridge, and parent constructor params silently not
+* resolving. Pure and warn-only: findings join the D1 collector and
+* `Moost.init()` logs them as warnings (they never reject `init()`).
+*/ function auditInheritance(input) {
+	return [auditRouteDrop(input), auditLostCtorParams(input)].filter((f) => f !== void 0);
+}
+
 //#endregion
 //#region packages/moost/src/moost.ts
 function _define_property(obj, key, value) {
@@ -1486,6 +1767,16 @@ function _define_property(obj, key, value) {
 	return obj;
 }
 /**
+* Detects the object registration form of `registerControllers`: a plain
+* object (no class prototype) carrying a `controllers` array. Controller
+* instances are class instances and never match, so all pre-existing
+* registration forms bind unchanged.
+*/ function isControllersGroup(entry) {
+	if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return false;
+	const proto = Object.getPrototypeOf(entry);
+	return (proto === Object.prototype || proto === null) && Array.isArray(entry.controllers);
+}
+/**
 * ## Moost
 * Main moostjs class that serves as a shell for Moost Adapters
 *
@@ -1595,10 +1886,18 @@ function _define_property(obj, key, value) {
 			if (constructor) this.setProvideRegistry((0, _prostojs_infact.createProvideRegistry)([constructor, () => a]));
 			if (typeof a.getProvideRegistry === "function") this.setProvideRegistry(a.getProvideRegistry());
 		}
-		this.unregisteredControllers.unshift(this);
-		await this.bindControllers();
+		this.unregisteredControllers.unshift({ controller: this });
+		let auditError;
+		try {
+			await this.bindControllers();
+		} finally {
+			registerDiagnosticsSource(this);
+			auditError = this.flushParamAudit();
+		}
+		if (auditError) throw new Error(auditError);
 		await this.runInitHooks();
 		for (const a of this.adapters) await (a.onInit && a.onInit(this));
+		this.initialized = true;
 	}
 	/**
 	* Runs every `@MoostInit`-decorated controller method exactly once, after all
@@ -1617,6 +1916,31 @@ function _define_property(obj, key, value) {
 			await instance[hook.method](...args);
 		});
 	}
+	/**
+	* D1 audit of a DI-instantiated controller class' constructor params.
+	* Findings are collected for `init()` to flush. Returns `true` when the
+	* bind-time SINGLETON instantiation must be skipped: in `'error'` mode a
+	* fatal-capable finding guarantees `init()` rejects with the aggregated
+	* audit error (naming class and param), which the generic infact
+	* instantiation error would otherwise preempt.
+	*/ collectConstructorAudit(className, classMeta) {
+		if (this.paramAuditMode === "off" || !classMeta?.injectable) return false;
+		const findings = auditParams(classMeta.params, { className });
+		this.paramAuditFindings.push(...findings);
+		return this.paramAuditMode === "error" && findings.some((f) => f.severity === "fatal-capable");
+	}
+	/**
+	* Flushes D1 findings collected during binding: every finding is logged as a
+	* warning; in `'error'` mode, fatal-capable findings are folded into one
+	* aggregate error message listing all of them, returned for `init()` to
+	* throw (`init()` owns the precedence between this and a bind error).
+	*/ flushParamAudit() {
+		const findings = this.paramAuditFindings;
+		this.paramAuditFindings = [];
+		for (const f of findings) this.logger.warn(f.message);
+		const fatal = findings.filter((f) => f.severity === "fatal-capable");
+		if (fatal.length > 0 && this.paramAuditMode === "error") return formatParamAuditError(fatal);
+	}
 	async bindControllers() {
 		const thisMeta = getMoostMate().read(this);
 		const provide = {
@@ -1627,15 +1951,8 @@ function _define_property(obj, key, value) {
 			...thisMeta?.replace,
 			...this.replace
 		};
-		for (const _controller of this.unregisteredControllers) {
-			let newPrefix;
-			let controller = _controller;
-			if (Array.isArray(_controller) && typeof _controller[0] === "string") {
-				newPrefix = _controller[0];
-				controller = _controller[1];
-			}
-			await this.bindController(controller, provide, replace, this.options?.globalPrefix || "", newPrefix);
-		}
+		const globalPrefix = this.options?.globalPrefix || "";
+		for (const { controller, prependPrefix, replaceOwnPrefix } of this.unregisteredControllers) await this.bindController(controller, provide, replace, prependPrefix ? `${globalPrefix}/${prependPrefix}` : globalPrefix, replaceOwnPrefix);
 		this.unregisteredControllers = [];
 	}
 	async bindController(controller, provide, replace, globalPrefix, replaceOwnPrefix) {
@@ -1650,7 +1967,7 @@ function _define_property(obj, key, value) {
 			replace,
 			customData: { pipes }
 		};
-		if (isControllerConsructor && (classMeta?.injectable === "SINGLETON" || classMeta?.injectable === true)) await (0, _wooksjs_event_core.createEventContext)({ logger: this.logger }, async () => {
+		if (!(isControllerConsructor && this.collectConstructorAudit(controller.name, classMeta)) && isControllerConsructor && (classMeta?.injectable === "SINGLETON" || classMeta?.injectable === true)) await (0, _wooksjs_event_core.createEventContext)({ logger: this.logger }, async () => {
 			setControllerContext(this, "bindController", "", { prefix: computedPrefix });
 			instance = await infact.get(controller, infactOpts);
 		});
@@ -1660,7 +1977,7 @@ function _define_property(obj, key, value) {
 		}
 		const getInstance = instance ? () => instance : async () => await infact.get(controller, { ...infactOpts });
 		const classConstructor = (0, _prostojs_mate.isConstructor)(controller) ? controller : (0, _prostojs_mate.getConstructor)(controller);
-		this.controllersOverview.push(await bindControllerMethods({
+		const controllerOverview = await bindControllerMethods({
 			getInstance,
 			classConstructor,
 			adapters: this.adapters,
@@ -1672,7 +1989,15 @@ function _define_property(obj, key, value) {
 			replace: classMeta?.replace,
 			logger: this.logger,
 			moostInstance: this,
-			registerInitHook: (hook) => this.initHooks.push(hook)
+			registerInitHook: (hook) => this.initHooks.push(hook),
+			reportParamAudit: this.paramAuditMode === "off" ? void 0 : (findings) => this.paramAuditFindings.push(...findings)
+		});
+		this.controllersOverview.push(controllerOverview);
+		if (this.inheritanceAuditMode !== "off") this.paramAuditFindings.push(...auditInheritance({
+			classConstructor,
+			classMeta,
+			ownHandlersCount: controllerOverview.handlers.length,
+			diInstantiated: isControllerConsructor
 		}));
 		this.handlerOverviewIndex = void 0;
 		if (classMeta?.importController) {
@@ -1740,9 +2065,18 @@ function _define_property(obj, key, value) {
 	}
 	/**
 	* Register new entries to provide as dependency injections
+	*
+	* Ordering rule: call this **before `init()`**. `init()` snapshots the
+	* provide registry once when binding controllers, so entries added later are
+	* never seen by already-bound controllers (sibling registration order does
+	* not matter — only the before/after-`init()` boundary does). To scope
+	* providers to part of the app, use class-level `@Provide` on a parent
+	* controller — it flows parent → child through `@ImportController`, never
+	* to siblings.
 	* @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
 	* @returns
 	*/ setProvideRegistry(provide) {
+		if (this.initialized) this.logger.warn("[moost] setProvideRegistry() called after init() — already-bound controllers will not see these providers. Register providers before init(), or provide them via @Provide on a parent controller.");
 		this.provide = {
 			...this.provide,
 			...provide
@@ -1751,9 +2085,14 @@ function _define_property(obj, key, value) {
 	}
 	/**
 	* Register replace classes to provide as dependency injections
+	*
+	* Ordering rule: call this **before `init()`**. `init()` snapshots the
+	* replace registry once when binding controllers, so replacements added
+	* later are never seen by already-bound controllers.
 	* @param replace - Replace Registry (use createReplaceRegistry from '\@prostojs/infact')
 	* @returns
 	*/ setReplaceRegistry(replace) {
+		if (this.initialized) this.logger.warn("[moost] setReplaceRegistry() called after init() — already-bound controllers will not see these replacements. Register replacements before init().");
 		this.replace = {
 			...this.replace,
 			...replace
@@ -1761,11 +2100,48 @@ function _define_property(obj, key, value) {
 		return this;
 	}
 	/**
-	* Register controllers (similar to @ImportController decorator)
-	* @param controllers - list of target controllers (instances)
+	* Register controllers with the app (similar to the `@ImportController` decorator).
+	*
+	* Accepted forms (mixable in one call):
+	*
+	* 1. **Class or instance** — `registerControllers(UsersController)`.
+	*    Mounted at `globalPrefix + '/' + own @Controller prefix`.
+	*
+	* 2. **Tuple `[prefix, controller]`** — `registerControllers(['api/users', UsersController])`.
+	*    **IMPORTANT: the string REPLACES the controller's own `@Controller(...)` prefix — it does
+	*    NOT prepend to it.** `['api', UsersController]` mounts a `@Controller('users')` class at
+	*    `/api`, not `/api/users`, so every tuple registration must repeat the full path.
+	*    To compose prefixes instead, use the object form below.
+	*
+	* 3. **Object group `{ prefix, controllers, mode? }`** —
+	*    `registerControllers({ prefix: 'api', controllers: [UsersController] })`.
+	*    Registers every entry of `controllers` under `prefix`:
+	*    - `mode: 'prepend'` (default) composes the prefixes:
+	*      `globalPrefix + '/' + prefix + '/' + own @Controller prefix`
+	*      (a `@Controller('users')` class mounts at `/api/users`);
+	*    - `mode: 'replace'` replaces each controller's own prefix with `prefix`
+	*      (same semantics as the tuple form).
+	*
+	* The object form is detected only for plain objects with a `controllers` array, so
+	* controller classes, instances and tuples keep working unchanged. To mount the whole
+	* app under one segment, prefer the `globalPrefix` option (see {@link TMoostOptions}).
+	*
+	* @param controllers - controllers to register: classes, instances,
+	*   `[prefix, controller]` tuples or `{ prefix, controllers, mode? }` groups
 	* @returns
 	*/ registerControllers(...controllers) {
-		this.unregisteredControllers.push(...controllers);
+		for (const entry of controllers) if (Array.isArray(entry) && typeof entry[0] === "string") this.unregisteredControllers.push({
+			controller: entry[1],
+			replaceOwnPrefix: entry[0]
+		});
+		else if (isControllersGroup(entry)) for (const controller of entry.controllers) this.unregisteredControllers.push(entry.mode === "replace" ? {
+			controller,
+			replaceOwnPrefix: entry.prefix
+		} : {
+			controller,
+			prependPrefix: entry.prefix
+		});
+		else this.unregisteredControllers.push({ controller: entry });
 		return this;
 	}
 	logMappedHandler(eventName, classConstructor, method, stroke, prefix) {
@@ -1774,7 +2150,9 @@ function _define_property(obj, key, value) {
 		this.logger.info(`${prefix || ""}${c}${eventName} ${"\x1B[0m\x1B[2m\x1B[32m" + c}→ ${classConstructor.name}.${"\x1B[36m" + c}${method}()${coff}`);
 	}
 	constructor(options) {
-		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [];
+		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false;
+		this.paramAuditMode = resolveParamAuditMode(options?.diagnostics?.paramTypes);
+		this.inheritanceAuditMode = options?.diagnostics?.inheritance || "warn";
 		this.logger = options?.logger || getDefaultLogger(`moost`);
 		setDefaultLogger(this.logger);
 		const mate = getMoostMate();
@@ -1880,6 +2258,7 @@ exports.Interceptor = Interceptor;
 exports.InterceptorHandler = InterceptorHandler;
 exports.Label = Label;
 exports.LoggerTopic = LoggerTopic;
+exports.MOOST_MODULE_IDENTITY_KEY = MOOST_MODULE_IDENTITY_KEY;
 exports.Moost = Moost;
 exports.MoostInit = MoostInit;
 exports.OnError = OnError;
@@ -2017,6 +2396,8 @@ exports.setControllerContext = setControllerContext;
 exports.setInfactLoggingOptions = setInfactLoggingOptions;
 exports.setInterceptResult = setInterceptResult;
 exports.setOvertake = setOvertake;
+exports.stampModuleIdentity = stampModuleIdentity;
+exports.stampOnce = stampOnce;
 exports.useControllerContext = useControllerContext;
 exports.useHandlerPaths = useHandlerPaths;
 exports.useInterceptResult = useInterceptResult;