moost 0.6.44 → 0.6.46

package/dist/index.cjs

@@ -48,7 +48,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.44",
+		version: "0.6.46",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
@@ -2323,6 +2323,7 @@ function _define_property(obj, key, value) {
 			}
 			if (typeof a.getProvideRegistry === "function") this.setProvideRegistry(a.getProvideRegistry());
 		}
+		this.initHookPhase = "pending";
 		this.unregisteredControllers.unshift({ controller: this });
 		let auditError;
 		try {
@@ -2337,16 +2338,36 @@ function _define_property(obj, key, value) {
 		this.initialized = true;
 	}
 	/**
-	* Runs every `@MoostInit`-decorated controller method exactly once, after all
-	* controllers are bound (complete `getControllersOverview()`) and before the
-	* `adapter.onInit` loop. Hooks run in ascending `priority`, then registration
-	* order. Each runs on its controller's SINGLETON instance inside a synthetic
-	* init context (no interceptors; params resolve via the RESOLVE pipe only).
-	* A throwing hook rejects `init()` (fail-fast).
+	* Runs every init hook exactly once, after all controllers are bound
+	* (complete `getControllersOverview()`) and before the `adapter.onInit`
+	* loop: `@MoostInit` controller methods and functions registered with
+	* {@link addInitHook}. Hooks run in ascending `priority`, then registration
+	* order. Each runs inside a synthetic init context (no interceptors; params
+	* of `@MoostInit` methods resolve via the RESOLVE pipe only). Hooks added
+	* while the pass runs are picked up. A throwing hook rejects `init()`
+	* (fail-fast).
 	*/ async runInitHooks() {
-		if (this.initHooks.length === 0) return;
-		const hooks = this.initHooks.toSorted((a, b) => a.priority - b.priority);
-		for (const hook of hooks) await (0, _wooksjs_event_core.createEventContext)({ logger: this.logger }, async () => {
+		this.initHookPhase = "running";
+		const done = /* @__PURE__ */ new Set();
+		try {
+			for (;;) {
+				let next;
+				for (const hook of this.initHooks) if (!done.has(hook) && (!next || hook.priority < next.priority)) next = hook;
+				if (!next) break;
+				done.add(next);
+				await this.runInitHook(next);
+			}
+		} finally {
+			this.initHookPhase = "done";
+		}
+	}
+	async runInitHook(hook) {
+		await (0, _wooksjs_event_core.createEventContext)({ logger: this.logger }, async () => {
+			if (hook.kind === "fn") {
+				setControllerContext(this, "init", "", { prefix: "" });
+				await hook.fn(this);
+				return;
+			}
 			const instance = await hook.getInstance();
 			setControllerContext(instance, hook.method, "", { prefix: hook.computedPrefix });
 			const args = hook.resolveArgs ? await hook.resolveArgs() : [];
@@ -2354,6 +2375,37 @@ function _define_property(obj, key, value) {
 		});
 	}
 	/**
+	* ### addInitHook
+	* Programmatic counterpart of `@MoostInit`: runs `fn` once during `init()`,
+	* after every controller is bound (complete `getControllersOverview()`) and
+	* before the adapters' `onInit`, in the same pass as `@MoostInit` hooks:
+	* ascending `priority` (default 0), then registration order. Runs inside the
+	* same synthetic init context (controller context = the app; no
+	* interceptors, no request composables). A throwing hook rejects `init()`.
+	*
+	* May be called at any time:
+	* - before the hook pass starts (including from a controller constructor
+	*   during binding) — queued;
+	* - while the pass runs (from another hook) — runs later in the same pass;
+	* - after the pass finished — runs immediately (asynchronously, in its own
+	*   init context); a failure is logged, since there is no `init()` left to
+	*   reject.
+	*
+	* No de-duplication: registering the same function twice runs it twice.
+	* Hooks re-run on re-init exactly like `@MoostInit` hooks.
+	* @since 0.6.46
+	*/ addInitHook(fn, opts) {
+		const hook = {
+			kind: "fn",
+			priority: opts?.priority ?? 0,
+			fn
+		};
+		this.initHooks.push(hook);
+		if (this.initHookPhase === "done") this.runInitHook(hook).catch((error) => {
+			this.logger.error(`Late init hook failed: ${errorMessage(error)}`);
+		});
+	}
+	/**
 	* ### dispose
 	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
 	* hook of every singleton this app can reach — DI registry singletons
@@ -2457,15 +2509,8 @@ function _define_property(obj, key, value) {
 		if (fatal.length > 0 && this.paramAuditMode === "error") return formatParamAuditError(fatal);
 	}
 	async bindControllers() {
-		const thisMeta = getMoostMate().read(this);
-		const provide = {
-			...thisMeta?.provide,
-			...this.provide
-		};
-		const replace = {
-			...thisMeta?.replace,
-			...this.replace
-		};
+		const provide = this.appProvideRegistry();
+		const replace = this.appReplaceRegistry();
 		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 = [];
@@ -2523,7 +2568,7 @@ function _define_property(obj, key, value) {
 				...classMeta.provide
 			};
 			const mergedReplace = {
-				...this.replace,
+				...this.appReplaceRegistry(),
 				...classMeta.replace
 			};
 			for (const ic of classMeta.importController) if (ic.typeResolver) {
@@ -2590,10 +2635,17 @@ function _define_property(obj, key, value) {
 	* controller — it flows parent → child through `@ImportController`, never
 	* to siblings.
 	* @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
+	* @param opts - `{ override: false }` registers a default: used only when neither `@Provide`
+	*   on the app subclass nor a normal `setProvideRegistry` entry exists for the token,
+	*   regardless of call order. @since 0.6.45
 	* @returns
-	*/ setProvideRegistry(provide) {
+	*/ setProvideRegistry(provide, opts) {
 		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 = {
+		if (opts?.override === false) this.defaultProvide = {
+			...this.defaultProvide,
+			...provide
+		};
+		else this.provide = {
 			...this.provide,
 			...provide
 		};
@@ -2606,16 +2658,61 @@ function _define_property(obj, key, value) {
 	* 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')
+	* @param opts - `{ override: false }` registers a default: used only when neither `@Replace`
+	*   on the app subclass nor a normal `setReplaceRegistry` entry exists for the class,
+	*   regardless of call order. @since 0.6.45
 	* @returns
-	*/ setReplaceRegistry(replace) {
+	*/ setReplaceRegistry(replace, opts) {
 		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 = {
+		if (opts?.override === false) this.defaultReplace = {
+			...this.defaultReplace,
+			...replace
+		};
+		else this.replace = {
 			...this.replace,
 			...replace
 		};
 		return this;
 	}
 	/**
+	* Effective app-level replace registry, lowest to highest precedence: defaults
+	* (`override: false`), `@Replace` on the app subclass, `setReplaceRegistry()` entries.
+	* A controller's own `@Replace` is NOT app-level (it only reaches that controller's direct imports).
+	*/ appReplaceRegistry() {
+		return {
+			...this.defaultReplace,
+			...getMoostMate().read(this)?.replace,
+			...this.replace
+		};
+	}
+	/** Effective app-level provide registry (same layering as `appReplaceRegistry`). */ appProvideRegistry() {
+		return {
+			...this.defaultProvide,
+			...getMoostMate().read(this)?.provide,
+			...this.provide
+		};
+	}
+	/**
+	* The class `type` is replaced with app-wide (one hop, like the DI container), or `undefined`.
+	* Works before and after `init()`; never warns. Per-controller `@Replace` is not reported.
+	* @since 0.6.45
+	*/ getReplacement(type) {
+		return this.appReplaceRegistry()[(0, _prostojs_infact.getClassKey)(type)];
+	}
+	/**
+	* `getReplacement(type) !== undefined`.
+	* @since 0.6.45
+	*/ hasReplacement(type) {
+		return this.getReplacement(type) !== void 0;
+	}
+	/**
+	* Frozen shallow copy of the effective app-level replace registry
+	* (keys are `getClassKey(Class)` symbols). Mutating it never affects the app.
+	* @since 0.6.45
+	*/ getReplaceRegistry() {
+		return Object.freeze(this.appReplaceRegistry());
+	}
+	/**
 	* Register controllers with the app (similar to the `@ImportController` decorator).
 	*
 	* Accepted forms (mixable in one call):
@@ -2666,7 +2763,7 @@ 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, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "singletonInstances", void 0), _define_property(this, "disposePromise", 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.singletonInstances = /* @__PURE__ */ new Set();
+		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, "initHookPhase", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "defaultProvide", void 0), _define_property(this, "defaultReplace", 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, "singletonInstances", void 0), _define_property(this, "disposePromise", 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.initHookPhase = "pending", this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.defaultProvide = {}, this.defaultReplace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
 		this.paramAuditMode = resolveParamAuditMode(options?.diagnostics?.paramTypes);
 		this.inheritanceAuditMode = options?.diagnostics?.inheritance || "warn";
 		this.logger = options?.logger || getDefaultLogger(`moost`);

package/dist/index.d.ts

@@ -468,17 +468,25 @@ interface TParamAuditFinding {
 type TParamAuditMode = 'error' | 'warn' | 'off';
 
 /**
- * A `@MoostInit`-decorated controller method, collected at bind time and run
- * once by `Moost.init()` after all controllers are bound. Interceptors are not
- * applied; params resolve through the RESOLVE pipe only.
- */
-interface TInitHook {
+ * An init hook collected for `Moost.init()`: either a `@MoostInit`-decorated
+ * controller method (collected at bind time) or a function registered with
+ * `Moost.addInitHook`. Interceptors are not applied; params of method hooks
+ * resolve through the RESOLVE pipe only.
+ */
+type TInitHook = TMethodInitHook | TFnInitHook;
+interface TMethodInitHook {
+    kind?: 'method';
     priority: number;
     method: string;
     computedPrefix: string;
     getInstance: () => Promise<TObject> | TObject;
     resolveArgs?: () => unknown[] | Promise<unknown[]>;
 }
+interface TFnInitHook {
+    kind: 'fn';
+    priority: number;
+    fn: (app: never) => unknown;
+}
 
 /** Mode for the bind-time inheritance audit (see `TMoostOptions['diagnostics']`). */
 type TInheritanceAuditMode = 'warn' | 'off';
@@ -623,6 +631,16 @@ interface TControllerRegistration {
      */
     prependPrefix?: string;
 }
+/** Options of `setProvideRegistry` / `setReplaceRegistry`. @since 0.6.45 */
+interface TRegistryMergeOptions {
+    /**
+     * `true` (default): entries replace existing ones for the same token.
+     * `false`: register a lowest-precedence default, used only when neither the app subclass's
+     * class-level decorator nor a normal `set*Registry()` entry exists for the token — regardless
+     * of call order.
+     */
+    override?: boolean;
+}
 /**
  * ## Moost
  * Main moostjs class that serves as a shell for Moost Adapters
@@ -682,8 +700,12 @@ declare class Moost extends Hookable {
     protected controllersOverview: TControllerOverview[];
     protected handlerOverviewIndex?: Map<TFunction, Map<string, THandlerOverview[]>>;
     protected initHooks: TInitHook[];
+    protected initHookPhase: 'pending' | 'running' | 'done';
     protected provide: TProvideRegistry;
     protected replace: TReplaceRegistry;
+    /** Lowest-precedence layers, filled by `set*Registry(reg, { override: false })`. */
+    protected defaultProvide: TProvideRegistry;
+    protected defaultReplace: TReplaceRegistry;
     protected unregisteredControllers: TControllerRegistration[];
     /** D1 param-audit findings collected while binding controllers, flushed by `init()`. */
     protected paramAuditFindings: TParamAuditFinding[];
@@ -731,14 +753,41 @@ declare class Moost extends Hookable {
      */
     init(): Promise<void>;
     /**
-     * Runs every `@MoostInit`-decorated controller method exactly once, after all
-     * controllers are bound (complete `getControllersOverview()`) and before the
-     * `adapter.onInit` loop. Hooks run in ascending `priority`, then registration
-     * order. Each runs on its controller's SINGLETON instance inside a synthetic
-     * init context (no interceptors; params resolve via the RESOLVE pipe only).
-     * A throwing hook rejects `init()` (fail-fast).
+     * Runs every init hook exactly once, after all controllers are bound
+     * (complete `getControllersOverview()`) and before the `adapter.onInit`
+     * loop: `@MoostInit` controller methods and functions registered with
+     * {@link addInitHook}. Hooks run in ascending `priority`, then registration
+     * order. Each runs inside a synthetic init context (no interceptors; params
+     * of `@MoostInit` methods resolve via the RESOLVE pipe only). Hooks added
+     * while the pass runs are picked up. A throwing hook rejects `init()`
+     * (fail-fast).
      */
     protected runInitHooks(): Promise<void>;
+    protected runInitHook(hook: TInitHook): Promise<void>;
+    /**
+     * ### addInitHook
+     * Programmatic counterpart of `@MoostInit`: runs `fn` once during `init()`,
+     * after every controller is bound (complete `getControllersOverview()`) and
+     * before the adapters' `onInit`, in the same pass as `@MoostInit` hooks:
+     * ascending `priority` (default 0), then registration order. Runs inside the
+     * same synthetic init context (controller context = the app; no
+     * interceptors, no request composables). A throwing hook rejects `init()`.
+     *
+     * May be called at any time:
+     * - before the hook pass starts (including from a controller constructor
+     *   during binding) — queued;
+     * - while the pass runs (from another hook) — runs later in the same pass;
+     * - after the pass finished — runs immediately (asynchronously, in its own
+     *   init context); a failure is logged, since there is no `init()` left to
+     *   reject.
+     *
+     * No de-duplication: registering the same function twice runs it twice.
+     * Hooks re-run on re-init exactly like `@MoostInit` hooks.
+     * @since 0.6.46
+     */
+    addInitHook(fn: (app: this) => unknown, opts?: {
+        priority?: number;
+    }): void;
     /**
      * ### dispose
      * Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
@@ -833,9 +882,12 @@ declare class Moost extends Hookable {
      * controller — it flows parent → child through `@ImportController`, never
      * to siblings.
      * @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
+     * @param opts - `{ override: false }` registers a default: used only when neither `@Provide`
+     *   on the app subclass nor a normal `setProvideRegistry` entry exists for the token,
+     *   regardless of call order. @since 0.6.45
      * @returns
      */
-    setProvideRegistry(provide: TProvideRegistry): this;
+    setProvideRegistry(provide: TProvideRegistry, opts?: TRegistryMergeOptions): this;
     /**
      * Register replace classes to provide as dependency injections
      *
@@ -843,9 +895,37 @@ declare class Moost extends Hookable {
      * 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')
+     * @param opts - `{ override: false }` registers a default: used only when neither `@Replace`
+     *   on the app subclass nor a normal `setReplaceRegistry` entry exists for the class,
+     *   regardless of call order. @since 0.6.45
      * @returns
      */
-    setReplaceRegistry(replace: TReplaceRegistry): this;
+    setReplaceRegistry(replace: TReplaceRegistry, opts?: TRegistryMergeOptions): this;
+    /**
+     * Effective app-level replace registry, lowest to highest precedence: defaults
+     * (`override: false`), `@Replace` on the app subclass, `setReplaceRegistry()` entries.
+     * A controller's own `@Replace` is NOT app-level (it only reaches that controller's direct imports).
+     */
+    protected appReplaceRegistry(): TReplaceRegistry;
+    /** Effective app-level provide registry (same layering as `appReplaceRegistry`). */
+    protected appProvideRegistry(): TProvideRegistry;
+    /**
+     * The class `type` is replaced with app-wide (one hop, like the DI container), or `undefined`.
+     * Works before and after `init()`; never warns. Per-controller `@Replace` is not reported.
+     * @since 0.6.45
+     */
+    getReplacement<T>(type: TClassConstructor<T>): TClassConstructor<T> | undefined;
+    /**
+     * `getReplacement(type) !== undefined`.
+     * @since 0.6.45
+     */
+    hasReplacement(type: TClassConstructor): boolean;
+    /**
+     * Frozen shallow copy of the effective app-level replace registry
+     * (keys are `getClassKey(Class)` symbols). Mutating it never affects the app.
+     * @since 0.6.45
+     */
+    getReplaceRegistry(): Readonly<TReplaceRegistry>;
     /**
      * Register controllers with the app (similar to the `@ImportController` decorator).
      *
@@ -1541,4 +1621,4 @@ declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogge
 declare const loggerConsoleTransport: _prostojs_logger.TProstoLoggerTransportFn<any>;
 
 export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, MOOST_ADAPTER_BRAND, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, disposeInstances, forkEventContext, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useOvertake, useScopeId, withControllerContext };
-export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TDisposeError, TDisposeOptions, TDisposeResult, TEmpty, TForkEventContextOptions, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TIsolatedSlot, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives, TWithControllerContextOptions };
+export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TDisposeError, TDisposeOptions, TDisposeResult, TEmpty, TForkEventContextOptions, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TIsolatedSlot, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives, TRegistryMergeOptions, TWithControllerContextOptions };

package/dist/index.mjs

@@ -47,7 +47,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.44",
+		version: "0.6.46",
 		path: typeof __filename === "string" ? __filename : import.meta.url
 	});
 }
@@ -2322,6 +2322,7 @@ function _define_property(obj, key, value) {
 			}
 			if (typeof a.getProvideRegistry === "function") this.setProvideRegistry(a.getProvideRegistry());
 		}
+		this.initHookPhase = "pending";
 		this.unregisteredControllers.unshift({ controller: this });
 		let auditError;
 		try {
@@ -2336,16 +2337,36 @@ function _define_property(obj, key, value) {
 		this.initialized = true;
 	}
 	/**
-	* Runs every `@MoostInit`-decorated controller method exactly once, after all
-	* controllers are bound (complete `getControllersOverview()`) and before the
-	* `adapter.onInit` loop. Hooks run in ascending `priority`, then registration
-	* order. Each runs on its controller's SINGLETON instance inside a synthetic
-	* init context (no interceptors; params resolve via the RESOLVE pipe only).
-	* A throwing hook rejects `init()` (fail-fast).
+	* Runs every init hook exactly once, after all controllers are bound
+	* (complete `getControllersOverview()`) and before the `adapter.onInit`
+	* loop: `@MoostInit` controller methods and functions registered with
+	* {@link addInitHook}. Hooks run in ascending `priority`, then registration
+	* order. Each runs inside a synthetic init context (no interceptors; params
+	* of `@MoostInit` methods resolve via the RESOLVE pipe only). Hooks added
+	* while the pass runs are picked up. A throwing hook rejects `init()`
+	* (fail-fast).
 	*/ async runInitHooks() {
-		if (this.initHooks.length === 0) return;
-		const hooks = this.initHooks.toSorted((a, b) => a.priority - b.priority);
-		for (const hook of hooks) await createEventContext$1({ logger: this.logger }, async () => {
+		this.initHookPhase = "running";
+		const done = /* @__PURE__ */ new Set();
+		try {
+			for (;;) {
+				let next;
+				for (const hook of this.initHooks) if (!done.has(hook) && (!next || hook.priority < next.priority)) next = hook;
+				if (!next) break;
+				done.add(next);
+				await this.runInitHook(next);
+			}
+		} finally {
+			this.initHookPhase = "done";
+		}
+	}
+	async runInitHook(hook) {
+		await createEventContext$1({ logger: this.logger }, async () => {
+			if (hook.kind === "fn") {
+				setControllerContext(this, "init", "", { prefix: "" });
+				await hook.fn(this);
+				return;
+			}
 			const instance = await hook.getInstance();
 			setControllerContext(instance, hook.method, "", { prefix: hook.computedPrefix });
 			const args = hook.resolveArgs ? await hook.resolveArgs() : [];
@@ -2353,6 +2374,37 @@ function _define_property(obj, key, value) {
 		});
 	}
 	/**
+	* ### addInitHook
+	* Programmatic counterpart of `@MoostInit`: runs `fn` once during `init()`,
+	* after every controller is bound (complete `getControllersOverview()`) and
+	* before the adapters' `onInit`, in the same pass as `@MoostInit` hooks:
+	* ascending `priority` (default 0), then registration order. Runs inside the
+	* same synthetic init context (controller context = the app; no
+	* interceptors, no request composables). A throwing hook rejects `init()`.
+	*
+	* May be called at any time:
+	* - before the hook pass starts (including from a controller constructor
+	*   during binding) — queued;
+	* - while the pass runs (from another hook) — runs later in the same pass;
+	* - after the pass finished — runs immediately (asynchronously, in its own
+	*   init context); a failure is logged, since there is no `init()` left to
+	*   reject.
+	*
+	* No de-duplication: registering the same function twice runs it twice.
+	* Hooks re-run on re-init exactly like `@MoostInit` hooks.
+	* @since 0.6.46
+	*/ addInitHook(fn, opts) {
+		const hook = {
+			kind: "fn",
+			priority: opts?.priority ?? 0,
+			fn
+		};
+		this.initHooks.push(hook);
+		if (this.initHookPhase === "done") this.runInitHook(hook).catch((error) => {
+			this.logger.error(`Late init hook failed: ${errorMessage(error)}`);
+		});
+	}
+	/**
 	* ### dispose
 	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
 	* hook of every singleton this app can reach — DI registry singletons
@@ -2456,15 +2508,8 @@ function _define_property(obj, key, value) {
 		if (fatal.length > 0 && this.paramAuditMode === "error") return formatParamAuditError(fatal);
 	}
 	async bindControllers() {
-		const thisMeta = getMoostMate().read(this);
-		const provide = {
-			...thisMeta?.provide,
-			...this.provide
-		};
-		const replace = {
-			...thisMeta?.replace,
-			...this.replace
-		};
+		const provide = this.appProvideRegistry();
+		const replace = this.appReplaceRegistry();
 		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 = [];
@@ -2522,7 +2567,7 @@ function _define_property(obj, key, value) {
 				...classMeta.provide
 			};
 			const mergedReplace = {
-				...this.replace,
+				...this.appReplaceRegistry(),
 				...classMeta.replace
 			};
 			for (const ic of classMeta.importController) if (ic.typeResolver) {
@@ -2589,10 +2634,17 @@ function _define_property(obj, key, value) {
 	* controller — it flows parent → child through `@ImportController`, never
 	* to siblings.
 	* @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
+	* @param opts - `{ override: false }` registers a default: used only when neither `@Provide`
+	*   on the app subclass nor a normal `setProvideRegistry` entry exists for the token,
+	*   regardless of call order. @since 0.6.45
 	* @returns
-	*/ setProvideRegistry(provide) {
+	*/ setProvideRegistry(provide, opts) {
 		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 = {
+		if (opts?.override === false) this.defaultProvide = {
+			...this.defaultProvide,
+			...provide
+		};
+		else this.provide = {
 			...this.provide,
 			...provide
 		};
@@ -2605,16 +2657,61 @@ function _define_property(obj, key, value) {
 	* 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')
+	* @param opts - `{ override: false }` registers a default: used only when neither `@Replace`
+	*   on the app subclass nor a normal `setReplaceRegistry` entry exists for the class,
+	*   regardless of call order. @since 0.6.45
 	* @returns
-	*/ setReplaceRegistry(replace) {
+	*/ setReplaceRegistry(replace, opts) {
 		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 = {
+		if (opts?.override === false) this.defaultReplace = {
+			...this.defaultReplace,
+			...replace
+		};
+		else this.replace = {
 			...this.replace,
 			...replace
 		};
 		return this;
 	}
 	/**
+	* Effective app-level replace registry, lowest to highest precedence: defaults
+	* (`override: false`), `@Replace` on the app subclass, `setReplaceRegistry()` entries.
+	* A controller's own `@Replace` is NOT app-level (it only reaches that controller's direct imports).
+	*/ appReplaceRegistry() {
+		return {
+			...this.defaultReplace,
+			...getMoostMate().read(this)?.replace,
+			...this.replace
+		};
+	}
+	/** Effective app-level provide registry (same layering as `appReplaceRegistry`). */ appProvideRegistry() {
+		return {
+			...this.defaultProvide,
+			...getMoostMate().read(this)?.provide,
+			...this.provide
+		};
+	}
+	/**
+	* The class `type` is replaced with app-wide (one hop, like the DI container), or `undefined`.
+	* Works before and after `init()`; never warns. Per-controller `@Replace` is not reported.
+	* @since 0.6.45
+	*/ getReplacement(type) {
+		return this.appReplaceRegistry()[getClassKey$1(type)];
+	}
+	/**
+	* `getReplacement(type) !== undefined`.
+	* @since 0.6.45
+	*/ hasReplacement(type) {
+		return this.getReplacement(type) !== void 0;
+	}
+	/**
+	* Frozen shallow copy of the effective app-level replace registry
+	* (keys are `getClassKey(Class)` symbols). Mutating it never affects the app.
+	* @since 0.6.45
+	*/ getReplaceRegistry() {
+		return Object.freeze(this.appReplaceRegistry());
+	}
+	/**
 	* Register controllers with the app (similar to the `@ImportController` decorator).
 	*
 	* Accepted forms (mixable in one call):
@@ -2665,7 +2762,7 @@ 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, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "singletonInstances", void 0), _define_property(this, "disposePromise", 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 = createProvideRegistry$1([Infact, getMoostInfact], [Mate, getMoostMate]), this.replace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
+		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, "initHookPhase", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "defaultProvide", void 0), _define_property(this, "defaultReplace", 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, "singletonInstances", void 0), _define_property(this, "disposePromise", 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.initHookPhase = "pending", this.provide = createProvideRegistry$1([Infact, getMoostInfact], [Mate, getMoostMate]), this.replace = {}, this.defaultProvide = {}, this.defaultReplace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
 		this.paramAuditMode = resolveParamAuditMode(options?.diagnostics?.paramTypes);
 		this.inheritanceAuditMode = options?.diagnostics?.inheritance || "warn";
 		this.logger = options?.logger || getDefaultLogger(`moost`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moost",
-  "version": "0.6.44",
+  "version": "0.6.46",
   "description": "moost",
   "keywords": [
     "composables",
@@ -49,7 +49,7 @@
     "@wooksjs/event-http": "^0.7.26",
     "@wooksjs/http-body": "^0.7.26",
     "vitest": "3.2.7",
-    "@moostjs/event-http": "^0.6.44"
+    "@moostjs/event-http": "^0.6.46"
   },
   "scripts": {
     "pub": "pnpm publish --access public",