@velajs/vela 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -1,6 +1,106 @@
 # Changelog
 
-## 1.11.0 (2026-07-04)
+## 1.14.0 (2026-07-04)
+
+First-party `QueueModule` (roadmap phase 3, "the openness proof"): a whole
+feature module authored on the public API alone — `defineModule` (+ `lazy`),
+`createDiscoverableDecorator`, `registerEntrypointKind`, `app.entrypoints`,
+`runInEntrypointScope`, `buildEntrypointExecutionContext`, `PipelineRunner` —
+machine-verified by an import audit test.
+
+### Added
+
+- **`@velajs/vela/queue`** — platform-agnostic queue subsystem (subpath-only;
+  deliberately NOT re-exported from the main barrel because
+  `@velajs/cloudflare` already exports an unrelated CF-binding `QueueModule`).
+  Producers: `QueueModule.forRoot({ queues: ['email'] })` + per-queue
+  `QueueClient` injected via `queueToken(name)` (`add(jobName, data,
+  { delayMs? })`). Consumers: `@Processor(queue)` classes with
+  `@Process(jobName?)` handlers (named wins over wildcard; duplicates warn,
+  first-wins). Dispatch runs each job in `runInEntrypointScope`
+  (request-scoped deps rebuild per job), re-resolves processors by token
+  through the async seam (lazy consumer modules — async init hooks included —
+  materialize on first job), and applies scoped
+  guards/interceptors/filters through the shared pipeline; unclaimed errors
+  rethrow for platform retry. App-wide `APP_*` components deliberately do NOT
+  run around queue jobs (cloudflare queue/scheduled parity; diverges from the
+  WebSocket dispatcher — revisit framework-wide). The in-core `inline()`
+  driver (edge-pure, no timers) delivers on a microtask (`immediate`) or via
+  `flush()` (`manual`, rejects with `AggregateError` on unclaimed handler
+  errors); platform drivers implement `QueueDriver` out-of-core and call
+  `dispatchQueueJob(container, app.entrypoints, job)`. The module is
+  `lazy: true` (dogfoods 1.13): consumer-only workers defer it entirely;
+  an eager producer's client injection materializes it at bootstrap.
+  `queues` is structural — `forRootAsync({ queues, useFactory })`.
+- **`resolveScopedComponents(type, class, method, container)`** — public
+  pipeline seam surfaced by the openness proof: scoped
+  `@UseGuards`/`@UsePipes`/`@UseInterceptors`/`@UseFilters` resolution for
+  custom dispatchers (declaration order preserved; conventions like
+  closest-first filter reversal stay with the caller).
+- **`EntrypointRegistry` is injectable** — the per-app registry registers
+  into the container (global token) at the end of
+  `callOnApplicationBootstrap()`, so providers that dispatch entrypoints
+  themselves (the queue module's in-process driver binding) resolve it
+  instead of needing a back-reference to the app; `container.has(...)` probes
+  it safely pre-bootstrap (the queue binding falls back to
+  `DiscoveryService` + `deferLazy` for deliveries during bootstrap).
+
+## 1.13.0 (2026-07-04)
+
+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,96 @@ 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
+        });
+        // Make the per-app registry injectable (global token): providers that
+        // dispatch entrypoints themselves (the queue module's in-process driver
+        // binding) resolve it instead of needing a back-reference to the app.
+        // Registered AFTER build so anything resolving it sees the final registry;
+        // pre-bootstrap resolution attempts fail the `has()` probe and defer.
+        this.container.register({
+            provide: EntrypointRegistry,
+            useValue: this.entrypointRegistry
+        });
+        this.container.markGlobalToken(EntrypointRegistry);
+    }
+    /**
+   * 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/index.d.ts

@@ -46,8 +46,8 @@ export type { AdapterContext, RuntimeAdapter } from './factory/adapter';
 export type { VelaCreateOptions } from './factory';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
 export type { Plugin } from './plugin/plugin';
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
-export type { PipelineRunOptions } from './pipeline/index';
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export type { PipelineRunOptions, ResolvedComponentMap } from './pipeline/index';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, ReflectableDecorator, CreateDecoratorOptions, } from './pipeline/index';
 export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, } from './registry/index';
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipeline/index';