@venizia/ignis-kernel 0.2.0-2 → 0.2.0-21

package/dist/cjs/base/applications/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./abstract"), exports);
+__exportStar(require("./boot-sequence"), exports);
+__exportStar(require("./common"), exports);
 __exportStar(require("./rest"), exports);
-__exportStar(require("./types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/base/applications/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/applications/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,yCAAuB;AACvB,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/applications/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,kDAAgC;AAChC,2CAAyB;AACzB,yCAAuB"}

package/dist/cjs/base/applications/rest.d.ts

@@ -1,17 +1,18 @@
 import type { TBindingNamespace } from '../../common/bindings';
 import type { Binding } from '../../helpers/inversion';
-import type { BaseComponent } from '../components';
-import type { IDataSource } from '../datasources';
-import type { IRepository } from '../repositories';
-import type { IService } from '../services';
-import type { TMixinOpts } from '../mixins/types';
 import { OpenAPIHono } from '@hono/zod-openapi';
-import type { AnyObject, IConfigurable, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';
+import type { IConfigurable, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';
 import { RequestIdGenerator } from '@venizia/ignis-helpers/core';
 import type { Env, Schema } from 'hono';
+import type { BaseComponent } from '../components';
+import type { IDataSource } from '../datasources';
 import { BaseAppErrorMiddleware } from '../middlewares/app-error/app-error.middleware';
+import type { TMixinOpts } from '../mixins/common';
+import type { IRepository } from '../repositories';
+import type { IService } from '../services';
 import { AbstractApplication } from './abstract';
-import type { IApplicationConfigs } from './types';
+import type { IBootSequenceStep } from './boot-sequence';
+import type { IApplicationConfigs, TArtifactIndexInput } from './common';
 interface IRegisterDynamicBindingsOptions<T extends IConfigurable = IConfigurable> {
     namespace: TBindingNamespace;
     onBeforeConfigure?: (opts: {
@@ -43,40 +44,70 @@ export declare abstract class RestApplication<AppEnv extends Env = Env, AppSchem
     /** The error handler the default stack installs. `@venizia/ignis` overrides it to swap in the `ErrorPrettier`-backed formatter, which reaches `node:util` and so cannot live here. */
     protected buildErrorMiddleware(): BaseAppErrorMiddleware;
     /**
-     * The three registrations every host needs, in one place, so a server and a browser Worker cannot
-     * drift: a request id, the framework's error envelope, and a JSON 404.
-     *
-     * None is optional. Hono's own defaults answer a thrown `ApplicationError` with a generic 500 and
-     * an unrouted path with `text/plain` - a caller doing `response.json()` on that 404 gets a
-     * `SyntaxError` instead of an error envelope. And without `requestId()`, `context.get(REQUEST_ID_KEY)`
-     * is `undefined`, so `context.json` drops the one field that ties a response to a log line.
-     *
-     * Registered before `initialize()`, so an application installing its own handlers still wins.
+     * The three registrations every host needs: request id, error envelope, JSON 404 - without them a
+     * thrown `ApplicationError` is a generic 500, a 404 is `text/plain`, and no response carries a request id.
+     * Registered before `initialize()`, so an application's own handlers still win.
      */
     protected registerDefaultMiddlewares(): ValueOrPromise<void>;
     /**
-     * The artifact ordering, stated ONCE: datasources before repositories can auto-resolve them, and
-     * components before controllers because a component may contribute either.
-     *
-     * A browser Worker application inherits this and writes none of it. `BaseApplication` in
-     * `@venizia/ignis` is the one deliberate override - it interleaves phases only a server has
-     * (start-up banner, env validation, secret hydration and rotation) between these steps.
+     * The artifact order, stated once: datasources before the repositories that auto-resolve them,
+     * components before the controllers they may contribute. `BaseApplication` splices its server-only
+     * steps around these by name instead of rewriting the list.
      */
+    protected getBootSequence(): IBootSequenceStep[];
     initialize(): Promise<void>;
+    /** The application hook currently running, so `registerArtifact` can tell a hand registration inside `preConfigure`/`postConfigure` from one the index step made. */
+    private runningApplicationHook;
+    private runApplicationHook;
+    /** `bootChecks.binding.doVerify`: resolve every service and repository once, collect every failure, throw once with the whole list - a made-up `@inject` key or a dependency a `when` excluded then fails the boot, not the first request. */
+    protected verifyBindings(): void;
+    /** One measured log line per step, and a failure names its step before rethrowing, so a hung or failed boot is attributable without reading the sequence. */
+    protected runBootSequence(opts: {
+        steps: IBootSequenceStep[];
+    }): Promise<void>;
     protected inspectRoutes(): void;
+    /**
+     * `configured` is the drain's state, mutated in place: a fresh `Set` gives a one-shot complete
+     * drain (`RestComponent`); `registerDynamicBindings` passes its persistent per-namespace `Set`,
+     * which is why a second sweep touches only what the first one missed.
+     */
+    drainByTag<T>(opts: {
+        tag: string;
+        configured: Set<string>;
+        onEach: (opts: {
+            binding: Binding<T>;
+        }) => Promise<void>;
+    }): Promise<void>;
     protected registerDynamicBindings<T extends IConfigurable = IConfigurable>(opts: IRegisterDynamicBindingsOptions<T>): Promise<void>;
-    component<Base extends BaseComponent, Args extends AnyObject = any>(ctor: TClass<Base>, opts?: TMixinOpts<Args>): Binding<Base>;
+    /** The same-key guard behind every artifact registration (`component`/`controller`/`service`/`repository`/`dataSource`). `allowOverride` defaults true to match `bind()`'s overwrite behavior; `allowOverride: false` on one registration, or `bootChecks.binding.allowOverride: false` for the whole application, opts into strict mode. */
+    protected assertNoBindingCollision(opts: {
+        key: string;
+        allowOverride?: boolean;
+        caller: string;
+    }): void;
+    /** Resolution order for every registration: explicit `opts` > the class's `@injectable` defaults > the derived key and the kind's default scope. `order` and `when` are `registerArtifacts`' concern, not this one. */
+    private registerArtifact;
+    component<Base extends BaseComponent>(ctor: TClass<Base>, opts?: TMixinOpts): Binding<Base>;
     registerComponents(): Promise<void>;
     /**
-     * Handles the REST branch only - the kernel has no notion of gRPC (it reaches `node:module` via
-     * `AbstractGrpcController`, core-only). `BaseApplication` extends this with the gRPC branch, the
-     * unsupported-transport error and the orphaned-gRPC-controller warning.
+     * Second DATASOURCE sweep, for datasources components contributed at any depth. Calls
+     * `registerDynamicBindings` directly: `this.registerDataSources()` is polymorphic and an override
+     * would run twice. Runs after every component, so a component a datasource registers is never configured.
      */
+    registerContributedDataSources(): Promise<void>;
+    /** REST only - the kernel has no gRPC (it reaches `node:module`). `BaseApplication` adds the gRPC branch on top. */
     registerControllers(): Promise<void>;
-    controller<Base, Args extends AnyObject = any>(ctor: TClass<Base>, opts?: TMixinOpts<Args>): Binding<Base>;
-    service<Base extends IService, Args extends AnyObject = any>(ctor: TClass<Base>, opts?: TMixinOpts<Args>): Binding<Base>;
-    repository<Base extends IRepository, Args extends AnyObject = any>(ctor: TClass<Base>, opts?: TMixinOpts<Args>): Binding<Base>;
-    dataSource<Base extends IDataSource, Args extends AnyObject = any>(ctor: TClass<Base>, opts?: TMixinOpts<Args>): Binding<Base>;
+    /** SINGLETON like `component()`: `RestComponent` mounts the one instance it resolves, so a second resolution must be that instance, not an unmounted twin. */
+    controller<Base>(ctor: TClass<Base>, opts?: TMixinOpts): Binding<Base>;
+    service<Base extends IService>(ctor: TClass<Base>, opts?: TMixinOpts): Binding<Base>;
+    repository<Base extends IRepository>(ctor: TClass<Base>, opts?: TMixinOpts): Binding<Base>;
+    dataSource<Base extends IDataSource>(ctor: TClass<Base>, opts?: TMixinOpts): Binding<Base>;
+    /** The boot step body behind `configs.artifacts`, also callable by hand: registers every kind in dependency order across the given indexes. */
+    registerArtifacts(index: TArtifactIndexInput): Promise<void>;
+    /** The boot step behind `configs.artifacts`; an application with none configured registers nothing here. */
+    protected registerConfiguredArtifacts(): Promise<void>;
+    /** Each `@provide` method becomes a lazy provider: the component is resolved (SINGLETON) and the method called on first `get`, so a provided value may depend on datasources or secrets that do not exist yet at registration time. */
+    private bindProvidedKeys;
     registerDataSources(): Promise<void>;
 }
 export {};

package/dist/cjs/base/applications/rest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../../../src/base/applications/rest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,MAAM,EACN,cAAc,EACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAiC,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAChG,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,UAAU,+BAA+B,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IAC/E,SAAS,EAAE,iBAAiB,CAAC;IAE7B,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,QAAQ,EAAE,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF;AAED,4NAA4N;AAC5N,8BAAsB,eAAe,CACnC,MAAM,SAAS,GAAG,GAAG,GAAG,EACxB,SAAS,SAAS,MAAM,GAAG,EAAE,EAC7B,QAAQ,SAAS,MAAM,GAAG,GAAG,CAC7B,SAAQ,mBAAmB;IAC3B,OAAO,CAAC,kBAAkB,CAAmC;IAE7D,sPAAsP;IACtP,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;KAAE,CAAC;IAErE,SAAS,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/D,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;gBAE9C,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,mBAAmB,CAAA;KAAE;IAehE,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC;IAIzD,SAAS,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC;cAIlC,oBAAoB;IAWvC,oHAAoH;IACpH,SAAS,CAAC,iBAAiB,IAAI,MAAM;IAIrC,sLAAsL;IACtL,SAAS,CAAC,oBAAoB,IAAI,sBAAsB;IAYxD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,0BAA0B,IAAI,cAAc,CAAC,IAAI,CAAC;IAQ5D;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjC,SAAS,CAAC,aAAa;cAeP,uBAAuB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAC7E,IAAI,EAAE,+BAA+B,CAAC,CAAC,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC;IA4ChB,SAAS,CAAC,IAAI,SAAS,aAAa,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG,EAChE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAClB,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC;IAUV,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBzC;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB1C,UAAU,CAAC,IAAI,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG,EAC3C,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAClB,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC;IAWhB,OAAO,CAAC,IAAI,SAAS,QAAQ,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG,EACzD,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAClB,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC;IAWhB,UAAU,CAAC,IAAI,SAAS,WAAW,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG,EAC/D,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAClB,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC;IAWhB,UAAU,CAAC,IAAI,SAAS,WAAW,EAAE,IAAI,SAAS,SAAS,GAAG,GAAG,EAC/D,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAClB,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC;IAaV,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;CAU3C"}
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../../../src/base/applications/rest.ts"],"names":[],"mappings":"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"}

package/dist/cjs/base/applications/rest.js

@@ -3,20 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RestApplication = void 0;
 const bindings_1 = require("../../common/bindings");
 const inversion_1 = require("../../helpers/inversion");
-const rest_component_1 = require("../components/controller/rest/rest.component");
-const constants_1 = require("../controllers/common/constants");
 const zod_openapi_1 = require("@hono/zod-openapi");
 const core_1 = require("@venizia/ignis-helpers/core");
 const dev_1 = require("hono/dev");
 const request_id_1 = require("hono/request-id");
+const rest_component_1 = require("../components/controller/rest/rest.component");
+const constants_1 = require("../controllers/common/constants");
 const app_error_middleware_1 = require("../middlewares/app-error/app-error.middleware");
 const not_found_middleware_1 = require("../middlewares/not-found/not-found.middleware");
 const abstract_1 = require("./abstract");
+const artifact_index_1 = require("./artifact-index");
+const boot_sequence_1 = require("./boot-sequence");
 /** Adds the `OpenAPIHono` router surface on top of `AbstractApplication` - no listening server, so this is the layer a browser Worker or gRPC-only host can extend without pulling in `Bun.serve` / `@hono/node-server`. */
 class RestApplication extends abstract_1.AbstractApplication {
     constructor(opts) {
         super(opts);
         this.registeredBindings = {};
+        // A config built from the environment can lose `path.base` at run time; the router would only fail later, inside `route()`, with a message that names nothing.
+        if (typeof this.configs.path?.base !== 'string') {
+            throw (0, core_1.getError)({
+                message: `[${opts.scope}] configs.path.base must be a string | value: ${String(this.configs.path?.base)} | an empty string mounts the application at the root`,
+            });
+        }
         this.requestIdGenerator = new core_1.RequestIdGenerator({ scope: opts.scope });
         const honoServer = new zod_openapi_1.OpenAPIHono({
             strict: this.configs.strictPath ?? true,
@@ -57,15 +65,9 @@ class RestApplication extends abstract_1.AbstractApplication {
         });
     }
     /**
-     * The three registrations every host needs, in one place, so a server and a browser Worker cannot
-     * drift: a request id, the framework's error envelope, and a JSON 404.
-     *
-     * None is optional. Hono's own defaults answer a thrown `ApplicationError` with a generic 500 and
-     * an unrouted path with `text/plain` - a caller doing `response.json()` on that 404 gets a
-     * `SyntaxError` instead of an error envelope. And without `requestId()`, `context.get(REQUEST_ID_KEY)`
-     * is `undefined`, so `context.json` drops the one field that ties a response to a log line.
-     *
-     * Registered before `initialize()`, so an application installing its own handlers still wins.
+     * The three registrations every host needs: request id, error envelope, JSON 404 - without them a
+     * thrown `ApplicationError` is a generic 500, a 404 is `text/plain`, and no response carries a request id.
+     * Registered before `initialize()`, so an application's own handlers still win.
      */
     registerDefaultMiddlewares() {
         const server = this.getServer();
@@ -74,20 +76,98 @@ class RestApplication extends abstract_1.AbstractApplication {
         server.notFound((0, not_found_middleware_1.notFoundHandler)({ logger: this.logger }));
     }
     /**
-     * The artifact ordering, stated ONCE: datasources before repositories can auto-resolve them, and
-     * components before controllers because a component may contribute either.
-     *
-     * A browser Worker application inherits this and writes none of it. `BaseApplication` in
-     * `@venizia/ignis` is the one deliberate override - it interleaves phases only a server has
-     * (start-up banner, env validation, secret hydration and rotation) between these steps.
+     * The artifact order, stated once: datasources before the repositories that auto-resolve them,
+     * components before the controllers they may contribute. `BaseApplication` splices its server-only
+     * steps around these by name instead of rewriting the list.
      */
+    getBootSequence() {
+        return [
+            { name: boot_sequence_1.BootSteps.STATIC_CONFIGURE, run: () => this.staticConfigure() },
+            { name: boot_sequence_1.BootSteps.REGISTER_ARTIFACTS, run: () => this.registerConfiguredArtifacts() },
+            {
+                name: boot_sequence_1.BootSteps.PRE_CONFIGURE,
+                run: () => this.runApplicationHook({
+                    name: boot_sequence_1.BootSteps.PRE_CONFIGURE,
+                    hook: () => this.preConfigure(),
+                }),
+            },
+            { name: boot_sequence_1.BootSteps.REGISTER_DATA_SOURCES, run: () => this.registerDataSources() },
+            { name: boot_sequence_1.BootSteps.REGISTER_COMPONENTS, run: () => this.registerComponents() },
+            {
+                name: boot_sequence_1.BootSteps.REGISTER_CONTRIBUTED_DATA_SOURCES,
+                run: () => this.registerContributedDataSources(),
+            },
+            { name: boot_sequence_1.BootSteps.REGISTER_CONTROLLERS, run: () => this.registerControllers() },
+            {
+                name: boot_sequence_1.BootSteps.POST_CONFIGURE,
+                run: () => this.runApplicationHook({
+                    name: boot_sequence_1.BootSteps.POST_CONFIGURE,
+                    hook: () => this.postConfigure(),
+                }),
+            },
+            { name: boot_sequence_1.BootSteps.VERIFY_BINDINGS, run: () => this.verifyBindings() },
+        ];
+    }
     async initialize() {
-        this.staticConfigure();
-        await this.preConfigure();
-        await this.registerDataSources();
-        await this.registerComponents();
-        await this.registerControllers();
-        await this.postConfigure();
+        await this.runBootSequence({ steps: this.getBootSequence() });
+    }
+    async runApplicationHook(opts) {
+        this.runningApplicationHook = opts.name;
+        try {
+            await opts.hook();
+        }
+        finally {
+            this.runningApplicationHook = undefined;
+        }
+    }
+    /** `bootChecks.binding.doVerify`: resolve every service and repository once, collect every failure, throw once with the whole list - a made-up `@inject` key or a dependency a `when` excluded then fails the boot, not the first request. */
+    verifyBindings() {
+        if (!this.configs.bootChecks?.binding?.doVerify) {
+            return;
+        }
+        const logger = this.logger.for(this.verifyBindings.name);
+        const tags = [bindings_1.BindingNamespaces.SERVICE, bindings_1.BindingNamespaces.REPOSITORY];
+        const failures = [];
+        let verified = 0;
+        for (const tag of tags) {
+            const bindings = this.findByTag({ tag });
+            for (const binding of bindings) {
+                try {
+                    this.get({ key: binding.key });
+                    verified += 1;
+                }
+                catch (error) {
+                    failures.push(`${binding.key}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        if (failures.length > 0) {
+            throw (0, core_1.getError)({
+                message: `[${this.verifyBindings.name}] ${failures.length} binding(s) cannot be resolved | ${failures.join(' | ')}`,
+            });
+        }
+        logger.info('Every service and repository binding resolves | verified: %d', verified);
+    }
+    /** One measured log line per step, and a failure names its step before rethrowing, so a hung or failed boot is attributable without reading the sequence. */
+    async runBootSequence(opts) {
+        const { steps } = opts;
+        const logger = this.logger.for(this.initialize.name);
+        const t = performance.now();
+        for (const [index, step] of steps.entries()) {
+            try {
+                await (0, core_1.executeWithPerformanceMeasure)({
+                    logger: this.logger,
+                    scope: this.initialize.name,
+                    description: `Boot step ${index + 1}/${steps.length} ${step.name}`,
+                    task: () => step.run(),
+                });
+            }
+            catch (error) {
+                logger.error('Boot step failed | step: %s (%d/%d) | error: %s', step.name, index + 1, steps.length, error);
+                throw error;
+            }
+        }
+        logger.info('Boot sequence complete | %d step(s) | Took: %s (ms) | %s', steps.length, performance.now() - t, steps.map(step => step.name).join(' -> '));
     }
     inspectRoutes() {
         const t = performance.now();
@@ -101,48 +181,101 @@ class RestApplication extends abstract_1.AbstractApplication {
             .for(this.inspectRoutes.name)
             .info('DONE | Inspect all application route(s) | Took: %s (ms)', performance.now() - t);
     }
-    async registerDynamicBindings(opts) {
-        const logger = this.logger.for(this.registerDynamicBindings.name);
-        const { namespace, onBeforeConfigure, onAfterConfigure } = opts;
-        if (!this.registeredBindings[namespace]) {
-            this.registeredBindings[namespace] = new Set();
-        }
-        const configured = this.registeredBindings[namespace];
+    /**
+     * `configured` is the drain's state, mutated in place: a fresh `Set` gives a one-shot complete
+     * drain (`RestComponent`); `registerDynamicBindings` passes its persistent per-namespace `Set`,
+     * which is why a second sweep touches only what the first one missed.
+     */
+    async drainByTag(opts) {
+        const { tag, configured, onEach } = opts;
         // A whole batch is drained before re-scanning: the re-scan exists only to pick up bindings a
         // `configure()` added, and asking after every single item makes boot N+1 full scans of the
         // binding map - 3.5ms at 200 controllers, against 0.04ms for this shape.
-        let bindings = this.findByTag({ tag: namespace, exclude: configured });
+        let bindings = this.findByTag({ tag, exclude: configured });
         while (bindings.length > 0) {
             for (const binding of bindings) {
                 // Within a batch a nested `configure()` may already have taken this one.
                 if (configured.has(binding.key)) {
                     continue;
                 }
+                await onEach({ binding });
+                configured.add(binding.key);
+            }
+            // Re-fetch excluding already configured - picks up dynamically added bindings
+            bindings = this.findByTag({ tag, exclude: configured });
+        }
+    }
+    async registerDynamicBindings(opts) {
+        const logger = this.logger.for(this.registerDynamicBindings.name);
+        const { namespace, onBeforeConfigure, onAfterConfigure } = opts;
+        if (!this.registeredBindings[namespace]) {
+            this.registeredBindings[namespace] = new Set();
+        }
+        const configured = this.registeredBindings[namespace];
+        await this.drainByTag({
+            tag: namespace,
+            configured,
+            onEach: async ({ binding }) => {
                 if (onBeforeConfigure) {
                     await onBeforeConfigure({ binding });
                 }
                 const instance = this.get({ key: binding.key, isOptional: false });
                 if (!instance) {
                     logger.debug('No binding instance | namespace: %s | key: %s', namespace, binding.key);
-                    configured.add(binding.key);
-                    continue;
+                    return;
                 }
                 await instance.configure();
+                // Marked before the after-hook runs, so the hook sees its own binding as configured.
                 configured.add(binding.key);
                 if (onAfterConfigure) {
                     await onAfterConfigure({ binding, instance });
                 }
-            }
-            // Re-fetch excluding already configured - picks up dynamically added bindings
-            bindings = this.findByTag({ tag: namespace, exclude: configured });
+            },
+        });
+    }
+    /** The same-key guard behind every artifact registration (`component`/`controller`/`service`/`repository`/`dataSource`). `allowOverride` defaults true to match `bind()`'s overwrite behavior; `allowOverride: false` on one registration, or `bootChecks.binding.allowOverride: false` for the whole application, opts into strict mode. */
+    assertNoBindingCollision(opts) {
+        const { key, caller } = opts;
+        const allowOverride = opts.allowOverride ?? this.configs.bootChecks?.binding?.allowOverride ?? true;
+        if (allowOverride || !this.isBound({ key })) {
+            return;
         }
+        const reason = opts.allowOverride === false
+            ? `'allowOverride: false' was set and this key collides with an existing binding | Use a distinct 'opts.binding' key, or drop 'allowOverride: false' if overriding is intentional`
+            : `'bootChecks.binding.allowOverride' is false and this key collides with an existing binding | Use a distinct 'opts.binding' key, or set 'allowOverride: true' on this registration if overriding is intentional`;
+        throw (0, core_1.getError)({
+            message: `[${caller}] Binding key already registered: '${key}' | ${reason}`,
+        });
     }
-    component(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? { namespace: bindings_1.BindingNamespaces.COMPONENT, key: ctor.name }),
-        })
+    /** Resolution order for every registration: explicit `opts` > the class's `@injectable` defaults > the derived key and the kind's default scope. `order` and `when` are `registerArtifacts`' concern, not this one. */
+    registerArtifact(opts) {
+        const { ctor, namespace, defaultScope, caller } = opts;
+        const declared = inversion_1.MetadataRegistry.getInstance().getArtifactMetadata({ target: ctor });
+        if (this.runningApplicationHook &&
+            this.configs.artifacts &&
+            this.configs.bootChecks?.binding?.allowManual === false) {
+            throw (0, core_1.getError)({
+                message: `[${caller}] '${ctor.name}' is registered by hand inside ${this.runningApplicationHook}() while 'configs.artifacts' is set and 'bootChecks.binding.allowManual' is false | Move the class into the generated index (or an explicit entry of 'configs.artifacts'), or allow manual registration`,
+            });
+        }
+        const key = inversion_1.BindingKeys.build(opts.opts?.binding ?? declared?.binding ?? { namespace, key: ctor.name });
+        this.assertNoBindingCollision({
+            key,
+            allowOverride: opts.opts?.allowOverride ?? declared?.allowOverride,
+            caller,
+        });
+        return this.bind({ key })
             .toClass(ctor)
-            .setScope(inversion_1.BindingScopes.SINGLETON);
+            .setScope(declared?.scope ?? defaultScope);
+    }
+    component(ctor, opts) {
+        return this.registerArtifact({
+            ctor,
+            namespace: bindings_1.BindingNamespaces.COMPONENT,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.component.name,
+            opts,
+        });
     }
     async registerComponents() {
         await (0, core_1.executeWithPerformanceMeasure)({
@@ -150,21 +283,26 @@ class RestApplication extends abstract_1.AbstractApplication {
             scope: this.registerComponents.name,
             description: 'Register application components',
             task: async () => {
-                await this.registerDynamicBindings({
-                    namespace: bindings_1.BindingNamespaces.COMPONENT,
-                    onAfterConfigure: async () => {
-                        // Register any datasources dynamically added by this component
-                        await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.DATASOURCE });
-                    },
-                });
+                await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.COMPONENT });
             },
         });
     }
     /**
-     * Handles the REST branch only - the kernel has no notion of gRPC (it reaches `node:module` via
-     * `AbstractGrpcController`, core-only). `BaseApplication` extends this with the gRPC branch, the
-     * unsupported-transport error and the orphaned-gRPC-controller warning.
+     * Second DATASOURCE sweep, for datasources components contributed at any depth. Calls
+     * `registerDynamicBindings` directly: `this.registerDataSources()` is polymorphic and an override
+     * would run twice. Runs after every component, so a component a datasource registers is never configured.
      */
+    async registerContributedDataSources() {
+        await (0, core_1.executeWithPerformanceMeasure)({
+            logger: this.logger,
+            scope: this.registerContributedDataSources.name,
+            description: 'Register application contributed data sources',
+            task: async () => {
+                await this.registerDynamicBindings({ namespace: bindings_1.BindingNamespaces.DATASOURCE });
+            },
+        });
+    }
+    /** REST only - the kernel has no gRPC (it reaches `node:module`). `BaseApplication` adds the gRPC branch on top. */
     async registerControllers() {
         await (0, core_1.executeWithPerformanceMeasure)({
             logger: this.logger,
@@ -180,39 +318,94 @@ class RestApplication extends abstract_1.AbstractApplication {
             },
         });
     }
+    /** SINGLETON like `component()`: `RestComponent` mounts the one instance it resolves, so a second resolution must be that instance, not an unmounted twin. */
     controller(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.CONTROLLER,
-                key: ctor.name,
-            }),
-        }).toClass(ctor);
+        return this.registerArtifact({
+            ctor,
+            namespace: bindings_1.BindingNamespaces.CONTROLLER,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.controller.name,
+            opts,
+        });
     }
     service(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.SERVICE,
-                key: ctor.name,
-            }),
-        }).toClass(ctor);
+        return this.registerArtifact({
+            ctor,
+            namespace: bindings_1.BindingNamespaces.SERVICE,
+            defaultScope: inversion_1.BindingScopes.TRANSIENT,
+            caller: this.service.name,
+            opts,
+        });
     }
     repository(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.REPOSITORY,
-                key: ctor.name,
-            }),
-        }).toClass(ctor);
+        return this.registerArtifact({
+            ctor,
+            namespace: bindings_1.BindingNamespaces.REPOSITORY,
+            defaultScope: inversion_1.BindingScopes.TRANSIENT,
+            caller: this.repository.name,
+            opts,
+        });
     }
     dataSource(ctor, opts) {
-        return this.bind({
-            key: inversion_1.BindingKeys.build(opts?.binding ?? {
-                namespace: bindings_1.BindingNamespaces.DATASOURCE,
-                key: ctor.name,
-            }),
-        })
-            .toClass(ctor)
-            .setScope(inversion_1.BindingScopes.SINGLETON);
+        return this.registerArtifact({
+            ctor,
+            namespace: bindings_1.BindingNamespaces.DATASOURCE,
+            defaultScope: inversion_1.BindingScopes.SINGLETON,
+            caller: this.dataSource.name,
+            opts,
+        });
+    }
+    /** The boot step body behind `configs.artifacts`, also callable by hand: registers every kind in dependency order across the given indexes. */
+    async registerArtifacts(index) {
+        const resolved = await artifact_index_1.ArtifactIndexHelper.getInstance().resolve({
+            input: index,
+            application: this,
+        });
+        for (const ctor of resolved.dataSources) {
+            this.dataSource(ctor);
+        }
+        for (const ctor of resolved.components) {
+            this.component(ctor);
+            this.bindProvidedKeys({ ctor });
+        }
+        for (const ctor of resolved.repositories) {
+            this.repository(ctor);
+        }
+        for (const ctor of resolved.services) {
+            this.service(ctor);
+        }
+        for (const ctor of resolved.controllers) {
+            this.controller(ctor);
+        }
+    }
+    /** The boot step behind `configs.artifacts`; an application with none configured registers nothing here. */
+    async registerConfiguredArtifacts() {
+        const artifacts = this.configs.artifacts;
+        if (!artifacts) {
+            return;
+        }
+        await this.registerArtifacts(artifacts);
+    }
+    /** Each `@provide` method becomes a lazy provider: the component is resolved (SINGLETON) and the method called on first `get`, so a provided value may depend on datasources or secrets that do not exist yet at registration time. */
+    bindProvidedKeys(opts) {
+        const { ctor } = opts;
+        const registry = inversion_1.MetadataRegistry.getInstance();
+        const provides = registry.getProvideMetadata({ target: ctor });
+        if (provides.length === 0) {
+            return;
+        }
+        const declared = registry.getArtifactMetadata({ target: ctor });
+        const componentKey = inversion_1.BindingKeys.build(declared?.binding ?? { namespace: bindings_1.BindingNamespaces.COMPONENT, key: ctor.name });
+        for (const entry of provides) {
+            this.bind({ key: entry.key })
+                .toProvider(container => {
+                const instance = container.get({
+                    key: componentKey,
+                });
+                return instance[entry.methodName]();
+            })
+                .setScope(entry.scope ?? inversion_1.BindingScopes.SINGLETON);
+        }
     }
     async registerDataSources() {
         await (0, core_1.executeWithPerformanceMeasure)({