@velajs/vela 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,6 +1,61 @@
 # Changelog
 
-## 1.11.0 (2026-07-04)
+## Unreleased
+
+Cold-start laziness (roadmap phase 3): modules can defer their entire init to
+first use, and the in-core subsystems an HTTP-only worker doesn't touch now
+cost it nothing at bootstrap.
+
+### Added
+
+- **Lazy modules** — `@Module({ lazy: true })`, `DynamicModule.lazy`, and
+  `defineModule({ lazy: true })` (also recognized per call site like
+  `isGlobal`) defer a module *instance*'s entire provider/controller group:
+  nothing constructs during `VelaFactory.create`. The first resolution of any
+  of its tokens (injection, `app.get()`, a request hitting its controller, a
+  dispatcher re-resolving an entrypoint token) claims the module; when the
+  resolution stack unwinds, the group materializes and its
+  `onModuleInit`/`onApplicationBootstrap` hooks replay in registration order,
+  exactly once (memoized). Materialized instances join the instance flow so
+  shutdown hooks stay symmetric; untouched modules get neither init nor
+  shutdown hooks. Triggers during bootstrap absorb the group into the normal
+  hook phases, ordered dependency-before-consumer. `useValue` reads (options
+  tokens) do not trigger. Sync seams (`app.get`, the request pipeline) throw
+  a descriptive error for lazy modules with async providers/hooks — reach
+  those through `app.materializeLazyModules()` (the new warmup escape hatch)
+  or keep them sync. Authoring contract: MODULE_AUTHORING.md "Lazy modules".
+- **`app.materializeLazyModules()`** — materialize every still-pending lazy
+  module (async-safe); warmup/eager-everything escape hatch.
+- **`Container.isLazyPending(token)` / `Container.isInstantiated(token)`** —
+  non-triggering diagnostics (build-time probes, cold-start regression tests).
+- **`DiscoveryFilter.deferLazy`** — discovery returns providers of
+  unmaterialized lazy modules as metadata-only entries (`instance:
+  undefined`, mirroring the request-scoped convention) instead of forcing the
+  group. `EntrypointRegistry.build` uses it: declared-kind entrypoints of
+  lazy modules are metadata-only in `app.entrypoints`; dispatchers that
+  re-resolve by token (cloudflare cron/queue/scheduled already do)
+  materialize the owning module at dispatch time. `ContributesEntrypoints`
+  providers in lazy modules are materialized right before the snapshot —
+  computed contributions can't defer (documented cost).
+
+### Changed
+
+- **`EventEmitterModule`, `ScheduleModule`, `SeederModule`, `I18nModule` are
+  now lazy.** An HTTP-only worker that imports them but never emits an event,
+  reads the schedule registry, runs seeders, or translates pays zero
+  cold-start cost for them — no subscriber wiring pass, no `@Cron` discovery
+  walk, no merged-message snapshot. Every consumer path is a trigger, so
+  observable behavior is unchanged (`app.get(EventEmitter).emit(...)` wires
+  subscribers first; `runSeeders()` populates the registry via hook replay).
+  `WebSocketModule` and `ScheduleNodeModule` deliberately stay eager (gateway
+  injection drags the WS chain in anyway; the node executor is self-driving).
+- `ModuleLoader.resolveAllInstances()` skips tokens owned exclusively by lazy
+  module instances; a token also registered by a non-lazy module stays on the
+  eager pass. Route building no longer instantiate-probes middleware tokens
+  that are lazy-pending (default priority 0) — the probe would have defeated
+  i18n's deferral at route build.
+
+## 1.12.0 (2026-07-04)
 
 The module-model release: one blessed authoring path plus public kernel
 extension points, so feature modules (websocket, storage, queue, …) are built

package/dist/application.d.ts

@@ -12,7 +12,10 @@ export declare class VelaApplication {
     private honoApp;
     private entrypointRegistry;
     private disposed;
+    private readonly lazyManager;
+    private readonly knownInstances;
     constructor(container: Container, routeManager: RouteManager);
+    private trackNew;
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */
     initRoutes(): Promise<void>;
     private getApp;
@@ -44,8 +47,22 @@ export declare class VelaApplication {
      * ```
      */
     mountOpenApi(options: MountOpenApiOptions): this;
+    /**
+     * Pull instances materialized during the bootstrap phase (lazy modules
+     * dragged in by eager consumers) into the front of the instance list —
+     * dependency-before-consumer: a group absorbed because an eager provider
+     * injected it must be initialized before that consumer's hooks read it.
+     */
+    private absorbLazyInstances;
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
+    /**
+     * Materialize every still-pending lazy module (async-safe): construct the
+     * groups, replay their lifecycle hooks, and add their instances to the
+     * shutdown flow. Warmup escape hatch for tests and node runtimes that want
+     * eager-everything semantics back after bootstrap.
+     */
+    materializeLazyModules(): Promise<void>;
     /**
      * Every entrypoint contributed by the module graph, grouped by kind —
      * what runtime adapters/transports query instead of re-scanning providers:

package/dist/application.js

@@ -1,5 +1,6 @@
 import { DiscoveryService } from "./discovery/discovery.service.js";
 import { EntrypointRegistry } from "./entrypoint/entrypoint.registry.js";
+import { LazyModuleManager } from "./module/lazy-modules.js";
 import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
 import { renderScalarUi } from "./openapi/scalar-ui.js";
 import { renderSwaggerUi } from "./openapi/swagger-ui.js";
@@ -11,9 +12,27 @@ export class VelaApplication {
     honoApp = null;
     entrypointRegistry = null;
     disposed = false;
+    lazyManager;
+    // Identity guard for the instance flow: a token registered by BOTH a lazy
+    // and an eager module reaches us through the eager pass AND the absorbed
+    // batch — without dedup its hooks would run twice.
+    knownInstances = new Set();
     constructor(container, routeManager){
         this.container = container;
         this.routeManager = routeManager;
+        // bootstrap() registers the manager; a hand-built container may not have
+        // one (container unit tests) — lazy semantics simply don't engage then.
+        this.lazyManager = container.has(LazyModuleManager) ? container.resolve(LazyModuleManager) : undefined;
+        // Live-phase materializations join the instance flow so close()/dispose()
+        // run shutdown hooks over them (LIFO — appended last, destroyed first).
+        this.lazyManager?.setOnMaterialized((instances)=>{
+            this.instances.push(...this.trackNew(instances));
+        });
+    }
+    trackNew(batch) {
+        const fresh = batch.filter((i)=>!this.knownInstances.has(i));
+        for (const i of fresh)this.knownInstances.add(i);
+        return fresh;
     }
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */ async initRoutes() {
         this.honoApp = await this.routeManager.build();
@@ -35,6 +54,8 @@ export class VelaApplication {
     }
     setInstances(instances) {
         this.instances = instances;
+        this.knownInstances.clear();
+        for (const i of instances)this.knownInstances.add(i);
     }
     get(token) {
         return this.container.resolve(token);
@@ -127,26 +148,86 @@ export class VelaApplication {
         return this;
     }
     // Lifecycle hooks
+    /**
+   * Pull instances materialized during the bootstrap phase (lazy modules
+   * dragged in by eager consumers) into the front of the instance list —
+   * dependency-before-consumer: a group absorbed because an eager provider
+   * injected it must be initialized before that consumer's hooks read it.
+   */ absorbLazyInstances(prepend) {
+        const batch = this.trackNew(this.lazyManager?.takeAbsorbed() ?? []);
+        if (batch.length === 0) return batch;
+        if (prepend) {
+            this.instances = [
+                ...batch,
+                ...this.instances
+            ];
+        } else {
+            this.instances.push(...batch);
+        }
+        return batch;
+    }
     async callOnModuleInit() {
-        for (const instance of this.instances){
+        this.absorbLazyInstances(true);
+        // Index loop: hooks can trigger further absorptions, which append —
+        // the loop naturally covers them.
+        for(let i = 0; i < this.instances.length; i++){
+            const instance = this.instances[i];
             if (hasOnModuleInit(instance)) {
                 await instance.onModuleInit();
             }
+            this.absorbLazyInstances(false);
         }
     }
     async callOnApplicationBootstrap() {
-        for (const instance of this.instances){
+        for(let i = 0; i < this.instances.length; i++){
+            const instance = this.instances[i];
             if (hasOnApplicationBootstrap(instance)) {
                 await instance.onApplicationBootstrap();
             }
+            // Instances absorbed mid-phase already missed the init pass — run
+            // onModuleInit now; the loop then reaches them for the bootstrap hook.
+            for (const late of this.absorbLazyInstances(false)){
+                if (hasOnModuleInit(late)) await late.onModuleInit();
+            }
+        }
+        // Computed-entrypoint contributors (ContributesEntrypoints) in lazy
+        // modules must exist before the snapshot below — materialize them now
+        // (the documented cost of contributing computed entrypoints), then run
+        // their hooks through the same absorb loop.
+        if (this.lazyManager) {
+            await this.lazyManager.materializeContributors();
+            let batch;
+            while((batch = this.absorbLazyInstances(false)).length > 0){
+                for (const late of batch){
+                    if (hasOnModuleInit(late)) await late.onModuleInit();
+                }
+                for (const late of batch){
+                    if (hasOnApplicationBootstrap(late)) await late.onApplicationBootstrap();
+                }
+            }
+            // From here on, materializations replay their hooks at the trigger.
+            this.lazyManager.setPhaseLive();
         }
         // Build the per-app entrypoint registry AFTER the hooks: dispatchers that
         // implement ContributesEntrypoints (WsDispatcher) finish their own
         // discovery inside onApplicationBootstrap. Built here — not in
         // VelaFactory/initRoutes — so slim bootstrap paths that never build HTTP
         // routes (the Cloudflare Durable Object) still get `app.entrypoints`.
+        // Lazy-pending providers of declared kinds yield metadata-only entries
+        // (instance: undefined) — dispatchers re-resolve by token per event,
+        // which materializes the owning module at dispatch time.
         const discovery = this.container.has(DiscoveryService) ? this.container.resolve(DiscoveryService) : new DiscoveryService(this.container);
-        this.entrypointRegistry = await EntrypointRegistry.build(discovery, this.instances);
+        this.entrypointRegistry = await EntrypointRegistry.build(discovery, this.instances, {
+            deferLazy: true
+        });
+    }
+    /**
+   * Materialize every still-pending lazy module (async-safe): construct the
+   * groups, replay their lifecycle hooks, and add their instances to the
+   * shutdown flow. Warmup escape hatch for tests and node runtimes that want
+   * eager-everything semantics back after bootstrap.
+   */ async materializeLazyModules() {
+        await this.lazyManager?.materializeAll();
     }
     /**
    * Every entrypoint contributed by the module graph, grouped by kind —

package/dist/container/container.d.ts

@@ -1,5 +1,5 @@
 import { Scope } from '../constants';
-import type { ContainerOptions, Diagnostics, ModuleScope, ProviderOptions, Token, Type } from './types';
+import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleScope, ProviderOptions, Token, Type } from './types';
 /**
  * Per-module provider buckets. Each module instance owns its providers under
  * its `moduleId`; the same logical token can have distinct registrations in
@@ -19,7 +19,13 @@ export declare class Container {
     private diagnostics;
     private root;
     private disposables;
+    private lazyHook?;
+    private asyncDepth;
     constructor(options?: ContainerOptions);
+    /** Install the lazy-module seam (bootstrap-time; root container only). */
+    setLazyHook(hook: LazyResolutionHook): void;
+    private claimLazyModule;
+    private maybeDrainSync;
     register<T>(provider: Type<T> | ProviderOptions<T>, declaringModuleId?: string): this;
     private registerClass;
     private registerOptions;
@@ -67,6 +73,19 @@ export declare class Container {
     replaceProvider<T>(provider: Type<T> | ProviderOptions<T>, options?: {
         buckets?: 'all-existing' | 'root' | string[];
     }): this;
+    /**
+     * True when the token belongs exclusively to lazy modules that have not
+     * been materialized yet — resolving it would trigger materialization.
+     * Build-time probes (route-manager middleware priority, entrypoint
+     * snapshots) use this to defer instead of forcing the group.
+     */
+    isLazyPending(token: Token): boolean;
+    /**
+     * True when any registration of the token holds a constructed instance.
+     * Diagnostic helper (cold-start tests): checks WITHOUT resolving, so it
+     * never triggers lazy materialization.
+     */
+    isInstantiated(token: Token): boolean;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
     /**
@@ -122,6 +141,7 @@ export declare class Container {
     private resolveFactoryDependencyAsync;
     private resolveFactory;
     resolveAsync<T>(token: Token<T>, requestingModuleId?: string): Promise<T>;
+    private resolveAsyncInner;
     private createLazyProxy;
     private tokenToString;
 }

package/dist/container/container.js

@@ -33,9 +33,40 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     // Container-constructed instances in creation order, for LIFO disposal.
     // useValue providers are never tracked (they return before construction).
     disposables = [];
+    // Lazy-module seam (root-owned; children reach it via this.root). A
+    // resolution of a deferred registration CLAIMS its module; claimed groups
+    // are completed (constructed + hooks replayed) only when the resolution
+    // stack has unwound and no resolveAsync cascade is in flight — running the
+    // replay mid-construction could force-resolve a class currently on the
+    // resolution stack (discovery cascades) and mint a spurious
+    // circular-dependency error.
+    lazyHook;
+    asyncDepth = 0;
     constructor(options = {}){
         this.diagnostics = options.diagnostics ?? 'log';
     }
+    /** Install the lazy-module seam (bootstrap-time; root container only). */ setLazyHook(hook) {
+        this.root.lazyHook = hook;
+    }
+    claimLazyModule(declaringModuleId) {
+        const hook = this.root.lazyHook;
+        if (hook?.isPending(declaringModuleId)) {
+            hook.claim(declaringModuleId);
+        }
+    }
+    maybeDrainSync() {
+        const root = this.root;
+        const hook = root.lazyHook;
+        if (!hook?.hasClaimed()) return;
+        // Never replay hooks while construction is in flight; an async cascade
+        // drains (with await) at its own end instead. A running drain picks
+        // pending claims up itself — re-entering it is at best a no-op and on
+        // the async path a self-deadlock.
+        if (this.resolutionStack.size > 0) return;
+        if (root.asyncDepth > 0) return;
+        if (hook.isDraining()) return;
+        hook.drainSync();
+    }
     register(provider, declaringModuleId) {
         const moduleId = declaringModuleId ?? ROOT_MODULE_ID;
         if (typeof provider === 'function') {
@@ -125,7 +156,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     resolve(token, requestingModuleId) {
         const registration = this.findRegistration(token, requestingModuleId);
         if (registration) {
-            return this.resolveRegistration(registration, requestingModuleId);
+            const instance = this.resolveRegistration(registration, requestingModuleId);
+            this.maybeDrainSync();
+            return instance;
         }
         // Visibility error fires first when the token exists in some bucket but
         // isn't reachable from the requester's scope — the user wants to know
@@ -155,7 +188,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     }
     resolveAll(token, requestingModuleId) {
         const registrations = this.findAllRegistrations(token, requestingModuleId);
-        return registrations.map((r)=>this.resolveRegistration(r, requestingModuleId));
+        const instances = registrations.map((r)=>this.resolveRegistration(r, requestingModuleId));
+        this.maybeDrainSync();
+        return instances;
     }
     /**
    * Find a single reachable registration for a token, applying the visibility
@@ -321,6 +356,32 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         }
         return this.register(provider);
     }
+    /**
+   * True when the token belongs exclusively to lazy modules that have not
+   * been materialized yet — resolving it would trigger materialization.
+   * Build-time probes (route-manager middleware priority, entrypoint
+   * snapshots) use this to defer instead of forcing the group.
+   */ isLazyPending(token) {
+        const hook = this.root.lazyHook;
+        if (!hook) return false;
+        const owners = this.exporterIndex.get(token);
+        if (!owners || owners.size === 0) return false;
+        for (const owner of owners){
+            if (!hook.isPending(owner)) return false;
+        }
+        return true;
+    }
+    /**
+   * True when any registration of the token holds a constructed instance.
+   * Diagnostic helper (cold-start tests): checks WITHOUT resolving, so it
+   * never triggers lazy materialization.
+   */ isInstantiated(token) {
+        for (const owner of this.exporterIndex.get(token) ?? []){
+            const reg = this.providers.get(owner)?.get(token);
+            if (reg && reg.instance !== undefined) return true;
+        }
+        return false;
+    }
     getProviderScope(token) {
         const exporters = this.exporterIndex.get(token);
         if (!exporters) return undefined;
@@ -467,6 +528,13 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         child.exporterIndex = clonedIndex;
         child.scopes = this.scopes;
         child.globals = this.globals;
+        // Registration objects are shallow-shared, so a sandbox resolve of a lazy
+        // module's singleton caches onto the SHARED registration. Point the
+        // sandbox at the real root so that resolution claims the module and
+        // replays its hooks like any other trigger — otherwise ModuleRef.create
+        // would leave a hook-less instance poisoning the shared cache (and its
+        // disposables tracked on an ephemeral root).
+        child.root = this.root;
         return child;
     }
     clear() {
@@ -517,8 +585,12 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     }
     resolveRegistration(registration, requestingModuleId) {
         if (registration.useValue !== undefined) {
+            // Deliberately BEFORE the lazy claim: reading a lazy module's useValue
+            // (options tokens) has no construction cost to defer and must not
+            // materialize the group.
             return registration.useValue;
         }
+        this.claimLazyModule(registration.declaringModuleId);
         if (registration.useExisting) {
             // Pass through the original requester to catch alias leaks
             return this.resolve(registration.useExisting, requestingModuleId);
@@ -652,6 +724,20 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         return result;
     }
     async resolveAsync(token, requestingModuleId) {
+        const root = this.root;
+        root.asyncDepth++;
+        let result;
+        try {
+            result = await this.resolveAsyncInner(token, requestingModuleId);
+        } finally{
+            root.asyncDepth--;
+        }
+        if (root.asyncDepth === 0 && root.lazyHook?.hasClaimed() && !root.lazyHook.isDraining()) {
+            await root.lazyHook.drainAsync();
+        }
+        return result;
+    }
+    async resolveAsyncInner(token, requestingModuleId) {
         const registration = this.findRegistration(token, requestingModuleId);
         if (!registration) {
             if (requestingModuleId !== undefined && this.scopes.has(requestingModuleId) && this.exporterIndex.has(token)) {
@@ -674,6 +760,7 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             if (scope === Scope.SINGLETON && registration.instance !== undefined) {
                 return registration.instance;
             }
+            this.claimLazyModule(registration.declaringModuleId);
             // Module scope first, legacy no-requester fallback — same policy as the
             // sync resolveFactory path.
             const dependencies = await Promise.all((registration.inject || []).map((t)=>{

package/dist/container/types.d.ts

@@ -85,6 +85,33 @@ export interface ModuleScope {
     importedModules: Set<string>;
     exportedTokens: Set<Token>;
     isGlobal: boolean;
+    /** Module instance opted into deferred (first-use) materialization. */
+    lazy?: boolean;
+}
+/**
+ * The container's seam into lazy-module materialization (implemented by
+ * `LazyModuleManager`). The container only ever *claims* a pending module at
+ * a resolution trigger and *drains* completed claims when the resolution
+ * stack has fully unwound — construction and hook replay live behind this
+ * interface so the container stays module-system-agnostic.
+ */
+export interface LazyResolutionHook {
+    /** Is this module instance still deferred (untriggered)? */
+    isPending(moduleId: string): boolean;
+    /** Mark a pending module as triggered; idempotent. */
+    claim(moduleId: string): void;
+    /** Any claimed-but-unmaterialized groups? (cheap fast-path check) */
+    hasClaimed(): boolean;
+    /**
+     * A drain loop is currently running. The container must NOT start (or
+     * await) another drain from inside it — the running loop picks pending
+     * claims up; awaiting would self-deadlock on the async path.
+     */
+    isDraining(): boolean;
+    /** Complete claimed groups synchronously; throws if async work surfaces. */
+    drainSync(): void;
+    /** Complete claimed groups, awaiting async construction and hooks. */
+    drainAsync(): Promise<void>;
 }
 export type Diagnostics = 'silent' | 'log' | 'throw';
 export interface ContainerOptions {

package/dist/discovery/discovery.service.d.ts

@@ -31,6 +31,14 @@ export interface DiscoveryFilter {
      * request-scoped hits are skipped with a diagnostics warning.
      */
     includeRequestScoped?: boolean;
+    /**
+     * Return providers of not-yet-materialized lazy modules as metadata-only
+     * entries (`instance: undefined`, mirroring the request-scoped convention)
+     * instead of resolving them — which would force the whole module group.
+     * Used by `EntrypointRegistry.build`; default false so every existing
+     * scanner keeps its transparent cascade-materialization semantics.
+     */
+    deferLazy?: boolean;
 }
 /**
  * Decorator-driven provider discovery — the public replacement for the

package/dist/discovery/discovery.service.js

@@ -124,6 +124,17 @@ export class DiscoveryService {
             if (!moduleIds.some((id)=>wanted.includes(id))) return undefined;
         }
         const scope = this.container.getProviderScope(metatype) ?? Scope.SINGLETON;
+        if (filter?.deferLazy && this.container.isLazyPending(metatype)) {
+            // Deliberate deferral — no diagnostics warning: the entry is complete
+            // metadata-wise and consumers re-resolve by token at dispatch time.
+            return {
+                token: metatype,
+                metatype,
+                moduleIds,
+                scope,
+                instance: undefined
+            };
+        }
         if (scope === Scope.REQUEST && !filter?.includeRequestScoped) {
             if (this.container.getDiagnostics() === 'log') {
                 console.warn(`[vela] ${label}: ${metatype.name} is request-scoped and cannot be ` + `materialized at bootstrap — skipped. Pass { includeRequestScoped: true } to override.`);

package/dist/entrypoint/entrypoint.registry.d.ts

@@ -32,7 +32,9 @@ export declare function _resetEntrypointKinds(): void;
  */
 export declare class EntrypointRegistry {
     private readonly byKind;
-    static build(discovery: DiscoveryService, eagerInstances: readonly unknown[]): Promise<EntrypointRegistry>;
+    static build(discovery: DiscoveryService, eagerInstances: readonly unknown[], options?: {
+        deferLazy?: boolean;
+    }): Promise<EntrypointRegistry>;
     private add;
     ofKind<M = unknown>(kind: string): Entrypoint<M>[];
     kinds(): string[];

package/dist/entrypoint/entrypoint.registry.js

@@ -44,11 +44,17 @@ function kindStore() {
  * own registry from their own container.
  */ export class EntrypointRegistry {
     byKind = new Map();
-    static async build(discovery, eagerInstances) {
+    static async build(discovery, eagerInstances, options = {}) {
         const registry = new EntrypointRegistry();
+        // With deferLazy, providers of unmaterialized lazy modules yield
+        // metadata-only entries (instance: undefined). Dispatchers re-resolve by
+        // token per event, so the owning module materializes at dispatch time.
+        const filter = options.deferLazy ? {
+            deferLazy: true
+        } : undefined;
         for (const kind of getEntrypointKinds()){
             if (kind.level === 'class') {
-                for (const found of discovery.providersWithMeta(kind.metaKey)){
+                for (const found of discovery.providersWithMeta(kind.metaKey, filter)){
                     registry.add({
                         kind: kind.kind,
                         token: found.token,
@@ -57,7 +63,7 @@ function kindStore() {
                     });
                 }
             } else {
-                for (const found of discovery.methodsWithMeta(kind.metaKey)){
+                for (const found of discovery.methodsWithMeta(kind.metaKey, filter)){
                     registry.add({
                         kind: kind.kind,
                         token: found.class.token,

package/dist/event-emitter/event-emitter.module.js

@@ -11,6 +11,7 @@ export class EventEmitterModule {
 }
 EventEmitterModule = _ts_decorate([
     Module({
+        lazy: true,
         providers: [
             EventEmitter,
             EventEmitterSubscriber

package/dist/factory/bootstrap.js

@@ -71,6 +71,10 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
     });
     container.markGlobalToken(RouteManager);
     const loader = new ModuleLoader(container, routeManager);
+    // loader.load() also arms the deferred-init seam (LazyModuleManager) — kept
+    // inside the loader so hand-rolled bootstrap paths that never call this
+    // function (@velajs/testing's TestingModuleBuilder.compile) get identical
+    // lazy semantics.
     loader.load(rootModule);
     bindAppProviders(routeManager, container, loader);
     routeManager.registerConsumerMiddleware(loader.getConsumerMiddlewareDefinitions());

package/dist/http/route.manager.js

@@ -177,6 +177,11 @@ export class RouteManager {
             if (typeof inst.priority === 'number') return inst.priority;
             if (typeof inst.constructor?.priority === 'number') return inst.constructor.priority;
         }
+        // A token owned exclusively by unmaterialized lazy modules must not be
+        // instantiate-probed here — the probe at route build would defeat the
+        // module's deferral (i18n's APP_MIDDLEWARE). Default priority instead;
+        // the middleware still materializes on its first request.
+        if (this.container.isLazyPending(entry)) return 0;
         try {
             const resolved = instantiate(entry, this.container);
             if (resolved && typeof resolved === 'object') {

package/dist/i18n/i18n.module.js

@@ -44,6 +44,11 @@ export class I18nModule extends ConfigurableModuleClass {
 }
 I18nModule = _ts_decorate([
     Module({
+        // Lazy: the merged-message snapshot (MessageLoaderService constructor) and
+        // locale middleware materialize on the first request that reaches them —
+        // message registration itself is import-time and unaffected. Safe because
+        // the route-build priority probe skips lazy-pending APP_MIDDLEWARE tokens.
+        lazy: true,
         providers: [
             MessageRegistry,
             MessageLoaderService,

package/dist/module/decorators.js

@@ -16,7 +16,8 @@ export function Module(options = {}) {
             providers: options.providers,
             controllers: options.controllers,
             exports: options.exports,
-            isGlobal: options.isGlobal
+            isGlobal: options.isGlobal,
+            lazy: options.lazy
         });
     };
 }
@@ -40,6 +41,7 @@ export function getModuleMetadata(target) {
         controllers: options.controllers ?? [],
         imports: options.imports ?? [],
         exports: options.exports ?? [],
-        isGlobal: options.isGlobal === true
+        isGlobal: options.isGlobal === true,
+        lazy: options.lazy === true
     };
 }

package/dist/module/define-module.d.ts

@@ -66,6 +66,13 @@ export interface DefineModuleSpec<Opts, Extras extends ConfigurableModuleExtras
     methodName?: MethodKey;
     /** Method a `useClass`/`useExisting` options factory must implement (default `create`). */
     factoryMethodName?: FactoryMethodKey;
+    /**
+     * Default every generated module instance to deferred (first-use)
+     * materialization. Call sites can also opt in per instance by passing
+     * `lazy: true` alongside the options (recognized like `isGlobal`).
+     * See MODULE_AUTHORING.md "Lazy modules".
+     */
+    lazy?: boolean;
 }
 /**
  * The one blessed module-authoring engine. Generates `forRoot` AND

package/dist/module/define-module.js

@@ -76,6 +76,11 @@ const ASYNC_OPTION_KEYS = new Set([
     const extrasDefaults = spec.extras ?? DEFAULT_EXTRAS;
     const transform = spec.transform ?? DEFAULT_TRANSFORM;
     const deriveKey = (explicit, structural)=>explicit ?? spec.key?.(structural) ?? stableHash(structural);
+    // Laziness is OR-composed: the spec defaults it, a call site can add it.
+    const applyLazy = (definition, callSiteLazy)=>spec.lazy === true || callSiteLazy === true ? {
+            ...definition,
+            lazy: true
+        } : definition;
     const applyContributions = (definition, structural, key)=>{
         if (!spec.setup) return definition;
         const contributions = spec.setup({
@@ -127,10 +132,10 @@ const ASYNC_OPTION_KEYS = new Set([
                     }
                 ]
             };
-            return transform(applyContributions(definition, rest, key), {
+            return applyLazy(transform(applyContributions(definition, rest, key), {
                 ...extrasDefaults,
                 ...rest
-            });
+            }), rest.lazy);
         }
     });
     Object.defineProperty(GeneratedModuleClass, asyncName, {
@@ -159,10 +164,10 @@ const ASYNC_OPTION_KEYS = new Set([
                 imports: bag.imports ?? [],
                 providers: buildAsyncOptionsProviders(optionsToken, factoryMethodName, bag, structural)
             };
-            return transform(applyContributions(definition, structural, key), {
+            return applyLazy(transform(applyContributions(definition, structural, key), {
                 ...extrasDefaults,
                 ...structural
-            });
+            }), structural.lazy);
         }
     });
     return {

package/dist/module/lazy-modules.d.ts

@@ -0,0 +1,82 @@
+import type { Container } from '../container/container';
+import type { LazyResolutionHook, Token } from '../container/types';
+/** One lazy module instance's deferral unit: its own tokens, in registration order. */
+export interface LazyModuleGroup {
+    moduleId: string;
+    tokens: Token[];
+    /**
+     * A class provider's prototype declares `collectEntrypoints` — the module
+     * must be materialized before the entrypoint registry snapshot or its
+     * computed contributions would be silently absent.
+     */
+    hasEntrypointContributor: boolean;
+}
+/**
+ * Owns deferred-module state for one application: which module instances are
+ * still pending, which have been claimed by a container trigger, and how
+ * claimed groups get completed (construction + lifecycle-hook replay).
+ *
+ * Phases:
+ * - `'bootstrap'` (until the end of `callOnApplicationBootstrap`): completed
+ *   groups are *absorbed* — their instances queue up for the application's
+ *   normal hook phases, so a lazy module dragged in by an eager consumer gets
+ *   today-identical semantics.
+ * - `'live'`: hooks replay at drain time (memoized, exactly once), then the
+ *   instances are handed to the application for shutdown-hook symmetry.
+ *
+ * Sync/async duality: sync drains throw a descriptive error when a member
+ * factory or hook yields a thenable — lazy modules with async providers or
+ * hooks must be reached through an async seam (`materializeLazyModules()`,
+ * `resolveAsync`) or stay eager.
+ */
+export declare class LazyModuleManager implements LazyResolutionHook {
+    private readonly container;
+    private readonly pending;
+    private readonly claimed;
+    private readonly absorbed;
+    private phase;
+    private draining;
+    private drainPromise?;
+    private onMaterialized?;
+    constructor(container: Container);
+    registerGroup(group: LazyModuleGroup): void;
+    /** Application sink for live-phase materializations (shutdown symmetry). */
+    setOnMaterialized(sink: (instances: unknown[]) => void): void;
+    setPhaseLive(): void;
+    isPending(moduleId: string): boolean;
+    /** Tokens whose owning modules are ALL still pending are deferred. */
+    hasPendingModules(): boolean;
+    claim(moduleId: string): void;
+    hasClaimed(): boolean;
+    /**
+     * A drain loop is running. The container consults this before its
+     * post-resolution drain: `constructGroupAsync` resolves members through
+     * `resolveAsync`, whose end-of-cascade check would otherwise re-enter and
+     * AWAIT the very drain promise it is executing inside — a self-referential
+     * await that never settles (with ≥2 claimed groups). Claims made while
+     * draining are picked up by the running loop instead.
+     */
+    isDraining(): boolean;
+    /** Instances constructed during the bootstrap phase, owed their hooks. */
+    takeAbsorbed(): unknown[];
+    drainSync(): void;
+    drainAsync(): Promise<void>;
+    /**
+     * Materialize every still-pending group whose providers compute entrypoints
+     * (`collectEntrypoints` on a class prototype). Called by the application
+     * right before the entrypoint-registry snapshot so computed contributions
+     * are never silently absent. The cost — those modules are effectively
+     * eager — is the documented price of contributing computed entrypoints.
+     */
+    materializeContributors(): Promise<void>;
+    /** Materialize everything still pending (warmup / tests / node runtimes). */
+    materializeAll(): Promise<void>;
+    private groupTokensToConstruct;
+    private constructGroupSync;
+    private constructGroupAsync;
+    /** Reversed batch = dependency-before-consumer (see drainSync comment). */
+    private orderBatch;
+    private finishBatchSync;
+    private finishBatchAsync;
+    private describeSyncFailure;
+}

package/dist/module/lazy-modules.js

@@ -0,0 +1,231 @@
+import { Scope } from "../constants.js";
+import { hasOnApplicationBootstrap, hasOnModuleInit } from "../lifecycle/index.js";
+function isThenable(x) {
+    return x !== null && (typeof x === 'object' || typeof x === 'function') && typeof x.then === 'function';
+}
+/**
+ * Owns deferred-module state for one application: which module instances are
+ * still pending, which have been claimed by a container trigger, and how
+ * claimed groups get completed (construction + lifecycle-hook replay).
+ *
+ * Phases:
+ * - `'bootstrap'` (until the end of `callOnApplicationBootstrap`): completed
+ *   groups are *absorbed* — their instances queue up for the application's
+ *   normal hook phases, so a lazy module dragged in by an eager consumer gets
+ *   today-identical semantics.
+ * - `'live'`: hooks replay at drain time (memoized, exactly once), then the
+ *   instances are handed to the application for shutdown-hook symmetry.
+ *
+ * Sync/async duality: sync drains throw a descriptive error when a member
+ * factory or hook yields a thenable — lazy modules with async providers or
+ * hooks must be reached through an async seam (`materializeLazyModules()`,
+ * `resolveAsync`) or stay eager.
+ */ export class LazyModuleManager {
+    container;
+    pending = new Map();
+    claimed = [];
+    absorbed = [];
+    phase = 'bootstrap';
+    draining = false;
+    // In-flight async drain: concurrent drainAsync callers must await the SAME
+    // completion (the running loop picks their claims up), never resolve early
+    // with a group's hooks still pending.
+    drainPromise;
+    onMaterialized;
+    constructor(container){
+        this.container = container;
+    }
+    registerGroup(group) {
+        this.pending.set(group.moduleId, group);
+    }
+    /** Application sink for live-phase materializations (shutdown symmetry). */ setOnMaterialized(sink) {
+        this.onMaterialized = sink;
+    }
+    setPhaseLive() {
+        this.phase = 'live';
+    }
+    isPending(moduleId) {
+        return this.pending.has(moduleId);
+    }
+    /** Tokens whose owning modules are ALL still pending are deferred. */ hasPendingModules() {
+        return this.pending.size > 0;
+    }
+    claim(moduleId) {
+        const group = this.pending.get(moduleId);
+        if (!group) return;
+        this.pending.delete(moduleId);
+        this.claimed.push(group);
+    }
+    hasClaimed() {
+        return this.claimed.length > 0;
+    }
+    /**
+   * A drain loop is running. The container consults this before its
+   * post-resolution drain: `constructGroupAsync` resolves members through
+   * `resolveAsync`, whose end-of-cascade check would otherwise re-enter and
+   * AWAIT the very drain promise it is executing inside — a self-referential
+   * await that never settles (with ≥2 claimed groups). Claims made while
+   * draining are picked up by the running loop instead.
+   */ isDraining() {
+        return this.draining;
+    }
+    /** Instances constructed during the bootstrap phase, owed their hooks. */ takeAbsorbed() {
+        if (this.absorbed.length === 0) return [];
+        return this.absorbed.splice(0, this.absorbed.length);
+    }
+    drainSync() {
+        if (this.draining) return;
+        this.draining = true;
+        try {
+            // Construct-all-then-hook, batch by batch: a cascade's groups arrive in
+            // consumer-before-dependency claim order (the consumer's token resolves
+            // first; constructing it claims its deps), so hook phases run over the
+            // REVERSED batch — dependency-before-consumer, matching what the eager
+            // bootstrap would have produced. Hooks can claim further groups
+            // (discovery cascades) → outer loop.
+            while(this.claimed.length > 0){
+                const batch = [];
+                while(this.claimed.length > 0){
+                    const group = this.claimed.shift();
+                    batch.push({
+                        group,
+                        instances: this.constructGroupSync(group)
+                    });
+                }
+                this.finishBatchSync(batch);
+            }
+        } finally{
+            this.draining = false;
+        }
+    }
+    drainAsync() {
+        if (this.draining) {
+            // External concurrent callers await the in-flight completion (its loop
+            // picks their claims up). Callers INSIDE the drain's own await chain
+            // never reach here — the container skips its post-resolution drain
+            // while isDraining() (self-await would deadlock).
+            return this.drainPromise ?? Promise.resolve();
+        }
+        this.draining = true;
+        const run = (async ()=>{
+            try {
+                while(this.claimed.length > 0){
+                    const batch = [];
+                    while(this.claimed.length > 0){
+                        const group = this.claimed.shift();
+                        batch.push({
+                            group,
+                            instances: await this.constructGroupAsync(group)
+                        });
+                    }
+                    await this.finishBatchAsync(batch);
+                }
+            } finally{
+                this.draining = false;
+                this.drainPromise = undefined;
+            }
+        })();
+        this.drainPromise = run;
+        return run;
+    }
+    /**
+   * Materialize every still-pending group whose providers compute entrypoints
+   * (`collectEntrypoints` on a class prototype). Called by the application
+   * right before the entrypoint-registry snapshot so computed contributions
+   * are never silently absent. The cost — those modules are effectively
+   * eager — is the documented price of contributing computed entrypoints.
+   */ async materializeContributors() {
+        for (const group of [
+            ...this.pending.values()
+        ]){
+            if (group.hasEntrypointContributor) this.claim(group.moduleId);
+        }
+        await this.drainAsync();
+    }
+    /** Materialize everything still pending (warmup / tests / node runtimes). */ async materializeAll() {
+        for (const moduleId of [
+            ...this.pending.keys()
+        ])this.claim(moduleId);
+        await this.drainAsync();
+    }
+    groupTokensToConstruct(group) {
+        return group.tokens.filter((token)=>this.container.getProviderScope(token) !== Scope.REQUEST);
+    }
+    constructGroupSync(group) {
+        const out = new Set();
+        for (const token of this.groupTokensToConstruct(group)){
+            try {
+                out.add(this.container.resolve(token, group.moduleId));
+            } catch (error) {
+                // Only the sync-resolution-of-async-factory error is a seam problem;
+                // genuine provider failures must surface untouched.
+                if (error instanceof Error && error.message.includes('returned a Promise')) {
+                    throw this.describeSyncFailure(group.moduleId, error);
+                }
+                throw error;
+            }
+        }
+        return [
+            ...out
+        ];
+    }
+    async constructGroupAsync(group) {
+        const out = new Set();
+        for (const token of this.groupTokensToConstruct(group)){
+            out.add(await this.container.resolveAsync(token, group.moduleId));
+        }
+        return [
+            ...out
+        ];
+    }
+    /** Reversed batch = dependency-before-consumer (see drainSync comment). */ orderBatch(batch) {
+        return [
+            ...batch
+        ].reverse();
+    }
+    finishBatchSync(batch) {
+        const ordered = this.orderBatch(batch);
+        if (this.phase === 'bootstrap') {
+            for (const { instances } of ordered)this.absorbed.push(...instances);
+            return;
+        }
+        for (const { group, instances } of ordered){
+            for (const instance of instances){
+                if (hasOnModuleInit(instance) && isThenable(instance.onModuleInit())) {
+                    throw this.describeSyncFailure(group.moduleId);
+                }
+            }
+        }
+        for (const { group, instances } of ordered){
+            for (const instance of instances){
+                if (hasOnApplicationBootstrap(instance) && isThenable(instance.onApplicationBootstrap())) {
+                    throw this.describeSyncFailure(group.moduleId);
+                }
+            }
+        }
+        this.onMaterialized?.(ordered.flatMap((b)=>b.instances));
+    }
+    async finishBatchAsync(batch) {
+        const ordered = this.orderBatch(batch);
+        if (this.phase === 'bootstrap') {
+            for (const { instances } of ordered)this.absorbed.push(...instances);
+            return;
+        }
+        for (const { instances } of ordered){
+            for (const instance of instances){
+                if (hasOnModuleInit(instance)) await instance.onModuleInit();
+            }
+        }
+        for (const { instances } of ordered){
+            for (const instance of instances){
+                if (hasOnApplicationBootstrap(instance)) await instance.onApplicationBootstrap();
+            }
+        }
+        this.onMaterialized?.(ordered.flatMap((b)=>b.instances));
+    }
+    describeSyncFailure(moduleId, cause) {
+        return new Error(`[vela] lazy module '${moduleId}' has async providers or lifecycle hooks and was ` + `triggered through a synchronous resolution path. Reach it through an async seam ` + `first (app.materializeLazyModules(), an async provider) or remove lazy: true.`, cause !== undefined ? {
+            cause
+        } : undefined);
+    }
+}

package/dist/module/module-loader.d.ts

@@ -2,6 +2,12 @@ import type { Container } from "../container/container";
 import type { Token, Type } from "../container/types";
 import type { RouteManager } from "../http/route.manager";
 import type { MiddlewareRouteDefinition } from "./middleware";
+/** What the loader records per lazy module instance (see LazyModuleManager). */
+export interface LazyModuleGroupSpec {
+    moduleId: string;
+    tokens: Token[];
+    hasEntrypointContributor: boolean;
+}
 export declare class ModuleLoader {
     private container;
     private router;
@@ -16,6 +22,8 @@ export declare class ModuleLoader {
     private appProviderTokens;
     private moduleIdByClassKey;
     private seenModuleIds;
+    private lazyModuleIds;
+    private lazyGroups;
     constructor(container: Container, router: RouteManager);
     load(rootModule: Type): void;
     private getModuleId;
@@ -25,6 +33,7 @@ export declare class ModuleLoader {
     private cacheExports;
     private processModule;
     private warnOnMixedDefaultAndKeyed;
+    /** Registers the provider and returns the token it was registered under. */
     private registerProvider;
     private isAppToken;
     private buildExportSet;
@@ -32,6 +41,18 @@ export declare class ModuleLoader {
     getRegisteredProviders(): Token[];
     getAppProviderTokens(token: Token): Token[];
     getConsumerMiddlewareDefinitions(): MiddlewareRouteDefinition[];
+    /**
+     * Every lazy module instance recorded during load. Handed to the
+     * LazyModuleManager at bootstrap; empty when no module opted in.
+     */
+    getLazyGroups(): LazyModuleGroupSpec[];
+    /**
+     * A token is deferred iff EVERY module bucket holding it belongs to a lazy
+     * module instance — a token also registered by a non-lazy module stays on
+     * the eager pass (and resolving it there claims the lazy sibling, which is
+     * the "any use = init" semantic, not a bug).
+     */
+    private isLazyOnlyToken;
     resolveAllInstances(): Promise<unknown[]>;
     private routeError;
 }

package/dist/module/module-loader.js

@@ -4,6 +4,7 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { getOrCreateArray } from "../registry/util.js";
 import { getModuleMetadata, isModule } from "./decorators.js";
+import { LazyModuleManager } from "./lazy-modules.js";
 import { MiddlewareBuilder } from "./middleware.js";
 const APP_TOKENS = new Set([
     APP_GUARD,
@@ -13,6 +14,16 @@ const APP_TOKENS = new Set([
     APP_MIDDLEWARE
 ]);
 const DEFAULT_KEY = "default";
+/**
+ * Structural check for `ContributesEntrypoints` on a provider's class —
+ * deliberately string-coupled to the interface's method name so the loader
+ * does not import from `entrypoint/` (layering).
+ */ function declaresEntrypointContributor(provider) {
+    const cls = typeof provider === "function" ? provider : provider.useClass;
+    if (typeof cls !== "function") return false;
+    const proto = cls.prototype;
+    return typeof proto?.collectEntrypoints === "function";
+}
 function isDynamicModule(value) {
     // TS 4.9+ narrows `'module' in value` so `value.module` is typed `unknown`
     // — no cast required for the typeof check below.
@@ -78,6 +89,10 @@ export class ModuleLoader {
     // (class, key) → composed moduleId (cached for stable identity within a load)
     moduleIdByClassKey = new Map();
     seenModuleIds = new Set();
+    // Lazy (deferred-init) module instances: moduleId → its own tokens in
+    // registration order. Consumed by LazyModuleManager via getLazyGroups().
+    lazyModuleIds = new Set();
+    lazyGroups = new Map();
     constructor(container, router){
         this.container = container;
         this.router = router;
@@ -87,6 +102,23 @@ export class ModuleLoader {
         for (const controller of this.collectedControllers){
             this.router.registerController(controller);
         }
+        // Arm the deferred-init seam HERE — at the end of load(), not in
+        // bootstrap() — so every consumer of the loader gets identical lazy
+        // semantics, including hand-rolled bootstrap paths that never call
+        // bootstrap() (@velajs/testing's TestingModuleBuilder.compile builds its
+        // own container). Still after all module-load-time resolutions
+        // (NestModule.configure), so load-time resolution never claims a group.
+        // Registered as a provider so VelaApplication can drive the phase
+        // transitions from any of those paths.
+        const lazyManager = new LazyModuleManager(this.container);
+        for (const group of this.getLazyGroups()){
+            lazyManager.registerGroup(group);
+        }
+        this.container.setLazyHook(lazyManager);
+        this.container.register({
+            provide: LazyModuleManager,
+            useValue: lazyManager
+        });
     }
     getModuleId(moduleClass, key) {
         let perClass = this.moduleIdByClassKey.get(moduleClass);
@@ -238,21 +270,38 @@ export class ModuleLoader {
             // include it in its own scope.
             localProviders.add(moduleClass);
             const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
+            const isLazy = metadata.lazy || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.lazy === true;
             this.container.registerScope({
                 moduleId,
                 localProviders,
                 importedModules: importedModuleIds,
                 exportedTokens: new Set(allExports),
-                isGlobal
+                isGlobal,
+                lazy: isLazy
             });
+            const lazyTokens = [];
+            let hasEntrypointContributor = false;
             for (const provider of allProviders){
-                this.registerProvider(provider, moduleId);
+                const registered = this.registerProvider(provider, moduleId);
+                if (isLazy && registered !== undefined) {
+                    lazyTokens.push(registered);
+                    hasEntrypointContributor ||= declaresEntrypointContributor(provider);
+                }
             }
             for (const controller of allControllers){
                 // Register the controller in its owning module's bucket so its
                 // dependencies resolve from the module's POV (vs `__root__`'s).
                 this.container.register(controller, moduleId);
                 this.collectedControllers.add(controller);
+                if (isLazy) lazyTokens.push(controller);
+            }
+            if (isLazy) {
+                this.lazyModuleIds.add(moduleId);
+                this.lazyGroups.set(moduleId, {
+                    moduleId,
+                    tokens: lazyTokens,
+                    hasEntrypointContributor
+                });
             }
             // Propagate module-level Use* decorators (@UseGuards, @UseInterceptors, etc.) to each controller
             for (const controller of allControllers){
@@ -293,35 +342,36 @@ export class ModuleLoader {
             console.warn(message);
         }
     }
-    registerProvider(provider, moduleId) {
+    /** Registers the provider and returns the token it was registered under. */ registerProvider(provider, moduleId) {
         if (typeof provider === "function") {
             // Per-module bucket: the same class can be registered in multiple
             // modules' buckets simultaneously without collision.
             this.container.register(provider, moduleId);
             this.registeredProviders.push(provider);
-        } else {
-            const token = provider.provide;
-            if (!token) {
-                this.container.register(provider, moduleId);
-                return;
-            }
-            if (this.isAppToken(token)) {
-                // Multiple APP_* providers within the same module bucket need
-                // distinct tokens so they don't overwrite each other in the bucket
-                // Map. Across buckets, `container.resolveAll(APP_GUARD)` walks
-                // every bucket — no need to mark synthetic tokens global.
-                const syntheticToken = new InjectionToken(`${token.toString()}:${this.appProviderCounter++}`);
-                this.container.register({
-                    ...provider,
-                    provide: syntheticToken
-                }, moduleId);
-                this.registeredProviders.push(syntheticToken);
-                getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
-                return;
-            }
+            return provider;
+        }
+        const token = provider.provide;
+        if (!token) {
             this.container.register(provider, moduleId);
-            this.registeredProviders.push(token);
+            return undefined;
         }
+        if (this.isAppToken(token)) {
+            // Multiple APP_* providers within the same module bucket need
+            // distinct tokens so they don't overwrite each other in the bucket
+            // Map. Across buckets, `container.resolveAll(APP_GUARD)` walks
+            // every bucket — no need to mark synthetic tokens global.
+            const syntheticToken = new InjectionToken(`${token.toString()}:${this.appProviderCounter++}`);
+            this.container.register({
+                ...provider,
+                provide: syntheticToken
+            }, moduleId);
+            this.registeredProviders.push(syntheticToken);
+            getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
+            return syntheticToken;
+        }
+        this.container.register(provider, moduleId);
+        this.registeredProviders.push(token);
+        return token;
     }
     isAppToken(token) {
         return APP_TOKENS.has(token);
@@ -364,6 +414,25 @@ export class ModuleLoader {
             ...this.consumerMiddlewareDefinitions
         ];
     }
+    /**
+   * Every lazy module instance recorded during load. Handed to the
+   * LazyModuleManager at bootstrap; empty when no module opted in.
+   */ getLazyGroups() {
+        return [
+            ...this.lazyGroups.values()
+        ];
+    }
+    /**
+   * A token is deferred iff EVERY module bucket holding it belongs to a lazy
+   * module instance — a token also registered by a non-lazy module stays on
+   * the eager pass (and resolving it there claims the lazy sibling, which is
+   * the "any use = init" semantic, not a bug).
+   */ isLazyOnlyToken(token) {
+        if (this.lazyModuleIds.size === 0) return false;
+        const owners = this.container.getOwnerModuleIds(token);
+        if (owners.length === 0) return false;
+        return owners.every((id)=>this.lazyModuleIds.has(id));
+    }
     async resolveAllInstances() {
         const instanceSet = new Set();
         for (const token of this.registeredProviders){
@@ -371,6 +440,9 @@ export class ModuleLoader {
                 if (this.container.getProviderScope(token) === Scope.REQUEST) {
                     continue;
                 }
+                if (this.isLazyOnlyToken(token)) {
+                    continue;
+                }
                 const instance = await this.container.resolveAsync(token);
                 instanceSet.add(instance);
             } catch (err) {
@@ -385,6 +457,9 @@ export class ModuleLoader {
                 if (this.container.getProviderScope(controller) === Scope.REQUEST) {
                     continue;
                 }
+                if (this.isLazyOnlyToken(controller)) {
+                    continue;
+                }
                 const instance = await this.container.resolveAsync(controller);
                 instanceSet.add(instance);
             } catch (err) {

package/dist/registry/types.d.ts

@@ -81,6 +81,13 @@ export interface DynamicModule {
     controllers?: Type[];
     exports?: Array<Type | InjectionToken>;
     global?: boolean;
+    /**
+     * Defer this module instance's providers/controllers to first use: nothing
+     * constructs at bootstrap; the first resolution of any of its tokens
+     * materializes the whole group and replays its lifecycle hooks (memoized).
+     * See MODULE_AUTHORING.md "Lazy modules" for the contract.
+     */
+    lazy?: boolean;
 }
 export interface ModuleOptions {
     providers?: Array<Type | ProviderOptions>;
@@ -88,6 +95,8 @@ export interface ModuleOptions {
     imports?: ModuleImport[];
     exports?: Array<Type | InjectionToken>;
     isGlobal?: boolean;
+    /** Defer to first use (see {@link DynamicModule.lazy}). */
+    lazy?: boolean;
 }
 export interface ModuleMetadata {
     providers: Array<Type | ProviderOptions>;
@@ -95,4 +104,5 @@ export interface ModuleMetadata {
     imports: ModuleImport[];
     exports: Array<Type | InjectionToken>;
     isGlobal: boolean;
+    lazy: boolean;
 }

package/dist/schedule/schedule.module.js

@@ -15,6 +15,9 @@ export class ScheduleModule {
 }
 ScheduleModule = _ts_decorate([
     Module({
+        // Lazy: the @Cron/@Interval discovery pass runs when ScheduleRegistry is
+        // first resolved (executor bootstrap, introspection, first dispatch).
+        lazy: true,
         providers: [
             ScheduleRegistry
         ],

package/dist/seeder/seeder.module.js

@@ -28,6 +28,9 @@ export class SeederModule extends ConfigurableModuleClass {
 }
 SeederModule = _ts_decorate([
     Module({
+        // Lazy: the @Seeder metadata scan runs when SeederRegistry is first
+        // resolved (runSeeders) — hook replay repopulates it correctly.
+        lazy: true,
         providers: [
             SeederRegistry
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",