@velajs/vela 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## Unreleased
+
+Module boundaries are enforced. NestJS-shape: a service cannot resolve dependencies from a module it didn't import. Bootstrap is consolidated into a single primitive, discovery failures are diagnostically routed, and a generic plugin composer is included.
+
+### New
+
+- **Module visibility enforcement.** `VelaFactory.create(Mod)` checks every constructor injection: the token must be declared locally, exported by an imported module, marked `@Global`, or be an `InjectionToken` with a default factory. Throws `ModuleVisibilityError` with an actionable message on violation. Auto-registration of unknown class tokens is gone — declare every dependency in a module's `providers`. There is no opt-out flag; `ModuleRef.create()` is the sandbox escape hatch for transient instantiation.
+
+- **`bootstrap(rootModule, options)`** — the wiring primitive shared by `VelaFactory.create`, `@velajs/testing`, and any non-HTTP consumer (CLI tools, custom runtimes). Returns `{ container, routeManager, loader }` without running lifecycle hooks or building the Hono app. `VelaFactory.create` is now a thin wrapper that calls `bootstrap()` then runs `OnModuleInit` / `OnApplicationBootstrap` and builds routes. Exported from `@velajs/vela` and `@velajs/vela/internal`.
+
+- **Module visibility primitives.** `Container({ diagnostics })`, `ModuleScope`, `Container.registerScope`, `Container.markGlobalToken`, and `ModuleVisibilityError`. `useExisting` aliases honor visibility (alias targets the caller can't see are rejected).
+
+- **Self-providing tokens stay visible.** `new InjectionToken('X', { factory: () => Y })` is implicitly globally visible — the token's factory IS its provider, so no explicit declaration is required.
+
+- **Factory inject is a framework-level escape hatch.** `useFactory` provider deps (including `forRootAsync`, `registerAsync`) resolve without a module-visibility requester, so factory `inject: [...]` arrays can pull from the importing module's scope. A future `forRootAsync({ imports })` will tighten this; for now it's permissive by design.
+
+- **Discovery diagnostics: `{ diagnostics: 'silent' | 'log' | 'throw' }`** (default `'log'`). Failed provider/controller resolution at `loader.resolveAllInstances`, schedule discovery, event-emitter discovery, and runtime job execution route through one dispatcher. `ModuleVisibilityError` always propagates regardless of mode.
+
+- **Live Cloudflare Workers smoke tests.** `pnpm test:workers` runs vela inside workerd via `@cloudflare/vitest-pool-workers` (driven by a test-only `wrangler.toml`). Validates the edge-runtime contract end-to-end — boot, request lifecycle, per-request DI without `AsyncLocalStorage`, handler-chain order, OpenAPI mount — beyond what the static edge-audit can catch. Wired into CI alongside `pnpm test`.
+
+- **Framework primitives are globally visible.** `Container`, `ModuleRef`, and `APP_GUARD`/`APP_PIPE`/`APP_INTERCEPTOR`/`APP_FILTER`/`APP_MIDDLEWARE` are marked global at boot — resolvable from any module without explicit imports, in both strict and non-strict mode. `ModuleRef.create()` continues to be the sandbox escape hatch (visibility check skipped for transient instantiation).
+
+- **Plugin manifest + composer** — `definePlugin({ id, version, module, dependsOn?, metadata? })` and `composePlugins(plugins): DynamicModule` with topological sort, cycle detection, and missing-dep detection. Produces a global module that exposes a queryable `PluginRegistry` via `PLUGIN_REGISTRY_TOKEN` (`list`, `get(id)`, `dependents(id)`).
+
+- **New types**: `ModuleScope`, `ContainerOptions`, `BootstrapOptions`, `BootstrapResult`, `Diagnostics`, `Plugin` — exported from both root and `/internal`.
+
+### Internal cleanup
+
+- **`Container` constructor accepts `ContainerOptions`** (`{ diagnostics? }`). Threads `requestingModuleId` through `resolve` / `resolveAsync` / `resolveAll`. Per-module scopes are tracked via `registerScope`; framework-internal globals via `markGlobalToken`. `providerOrigin: Map<Token, string>` records each provider's declaring module so constructor injections resolve from the *class's* module, not the caller's. Visibility enforcement runs whenever a `requestingModuleId` is supplied — there is no on/off switch.
+
+- **`ModuleLoader` registers a `ModuleScope` per module** before recursing into imports — `localProviders` includes the module class itself (so `NestModule.configure()` resolution stays inside its own scope), controllers, and every provider token. Synthetic `APP_*` tokens are marked global at mint time so RouteManager's request-time resolutions (no requester) keep working.
+
+- **`createChild()` shares container state by reference** (providers, scopes, globals, providerOrigin); `createDetached()` copies providers + providerOrigin and shares scopes + globals. Re-registering a token on a detached container without a moduleId clears any stale `providerOrigin` so sandbox-local registrations don't inherit a misleading owner.
+
+- **`resolveAsync` factory branch now unwraps `ForwardRef` in `inject`** (mirroring the sync `resolveFactory`). Previously asymmetric — sync path worked, async path silently failed during `loader.resolveAllInstances` and was swallowed by the discovery `try/catch`.
+
+- **Dropped unused `Container.parent` field** (audit #10). Was assigned in `createChild()` but never read.
+
+- **Bootstrap consolidated into `src/factory/bootstrap.ts`** — `VelaFactory.create` no longer hand-rolls the APP_* / consumer-middleware / global-prefix wiring sequence. Net code reduction in `factory.ts`.
+
 ## 1.1.0 (2026-04-30)
 
 Architectural remodel: one metadata model, one storage, public surface trimmed, internal primitives exposed via a stable subpath.

package/dist/__tests__/workers/entry.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+    fetch(request: Request, _env: unknown, _ctx: unknown): Promise<Response>;
+};
+export default _default;
+declare global {
+    interface ExportedHandler<Env = unknown> {
+        fetch?(request: Request, env: Env, ctx: unknown): Response | Promise<Response>;
+    }
+}

package/dist/container/container.d.ts

@@ -1,14 +1,23 @@
 import { Scope } from '../constants';
-import type { ProviderOptions, Token, Type } from './types';
+import type { ContainerOptions, Diagnostics, ModuleScope, ProviderOptions, Token, Type } from './types';
 export declare class Container {
     private providers;
     private resolutionStack;
-    private parent;
     private requestInstances;
-    register<T>(provider: Type<T> | ProviderOptions<T>): this;
+    private scopes;
+    private globals;
+    private providerOrigin;
+    private diagnostics;
+    constructor(options?: ContainerOptions);
+    register<T>(provider: Type<T> | ProviderOptions<T>, declaringModuleId?: string): this;
     private registerClass;
     private registerOptions;
-    resolve<T>(token: Token<T>): T;
+    private recordOrigin;
+    registerScope(scope: ModuleScope): void;
+    markGlobalToken(token: Token): void;
+    getDiagnostics(): Diagnostics;
+    resolve<T>(token: Token<T>, requestingModuleId?: string): T;
+    resolveAll<T>(token: Token<T>, requestingModuleId?: string): T[];
     has(token: Token): boolean;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
@@ -23,7 +32,9 @@ export declare class Container {
     private resolveRegistration;
     private resolveClass;
     private resolveFactory;
-    resolveAsync<T>(token: Token<T>): Promise<T>;
+    resolveAsync<T>(token: Token<T>, requestingModuleId?: string): Promise<T>;
     private createLazyProxy;
+    private assertVisible;
+    private isExportedFromImports;
     private tokenToString;
 }

package/dist/container/container.js

@@ -1,21 +1,27 @@
 import { Scope } from "../constants.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
-import { ForwardRef, InjectionToken } from "./types.js";
+import { ForwardRef, InjectionToken, ModuleVisibilityError } from "./types.js";
 const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
 export class Container {
     providers = new Map();
     resolutionStack = new Set();
-    parent = null;
     requestInstances = new Map();
-    register(provider) {
+    scopes = new Map();
+    globals = new Set();
+    providerOrigin = new Map();
+    diagnostics;
+    constructor(options = {}){
+        this.diagnostics = options.diagnostics ?? 'log';
+    }
+    register(provider, declaringModuleId) {
         if (typeof provider === 'function') {
-            this.registerClass(provider);
+            this.registerClass(provider, declaringModuleId);
         } else {
-            this.registerOptions(provider);
+            this.registerOptions(provider, declaringModuleId);
         }
         return this;
     }
-    registerClass(target) {
+    registerClass(target, declaringModuleId) {
         if (!isInjectable(target)) {
             console.warn(`Warning: ${target.name} is not decorated with @Injectable(). ` + `It will be registered but dependency resolution may not work correctly.`);
         }
@@ -25,8 +31,9 @@ export class Container {
             scope,
             useClass: target
         });
+        this.recordOrigin(target, declaringModuleId);
     }
-    registerOptions(options) {
+    registerOptions(options, declaringModuleId) {
         const token = options.provide;
         if (!token) {
             throw new Error('Provider registration requires a token');
@@ -49,30 +56,72 @@ export class Container {
             registration.useClass = token;
         }
         this.providers.set(token, registration);
+        this.recordOrigin(token, declaringModuleId);
+        // For aliases like `{ provide: Foo, useClass: Bar }`, also record Bar's
+        // origin so `resolveClass(Bar)` resolves Bar's deps from the alias's
+        // declaring module. Idempotent if Bar === Foo.
+        if (options.useClass !== undefined) {
+            this.recordOrigin(options.useClass, declaringModuleId);
+        }
+    }
+    recordOrigin(token, moduleId) {
+        if (moduleId !== undefined) {
+            this.providerOrigin.set(token, moduleId);
+        } else {
+            // Sandbox containers (createDetached) re-register tokens with no
+            // moduleId; clearing keeps the token "module-less" so it's only
+            // resolvable when the requester is also undefined.
+            this.providerOrigin.delete(token);
+        }
+    }
+    registerScope(scope) {
+        this.scopes.set(scope.moduleId, scope);
+        if (scope.isGlobal) {
+            // Match NestJS / the loader's existing globalExports semantic: only
+            // exported tokens become globally visible. Non-exported providers of
+            // a @Global module still need explicit imports.
+            for (const token of scope.exportedTokens)this.globals.add(token);
+        }
+    }
+    markGlobalToken(token) {
+        this.globals.add(token);
+    }
+    getDiagnostics() {
+        return this.diagnostics;
     }
-    resolve(token) {
+    resolve(token, requestingModuleId) {
+        if (requestingModuleId !== undefined) {
+            this.assertVisible(requestingModuleId, token);
+        }
         const registration = this.providers.get(token);
         if (!registration) {
             // `Object`/undefined at a token position is the fingerprint of a
-            // type-only import that TypeScript stripped — emit the hint BEFORE
-            // auto-registering Object as a provider (which would silently "succeed").
+            // type-only import that TypeScript stripped — emit the hint before
+            // attempting any other recovery.
             if (token === Object || token == null) {
                 throw new Error(`No provider found for token: ${this.tokenToString(token)}. ` + IMPORT_TYPE_HINT);
             }
             if (typeof token === 'function') {
-                this.register(token);
-                return this.resolve(token);
+                throw new Error(`No provider found for token: ${this.tokenToString(token)}. ` + `Declare it in a module's providers.`);
             }
+            // InjectionToken default factories are explicit user declarations
+            // attached to the token at construction — self-providing singletons.
             if (token instanceof InjectionToken && token.options?.factory) {
                 this.register({
                     provide: token,
                     useFactory: token.options.factory
                 });
-                return this.resolve(token);
+                return this.resolve(token, requestingModuleId);
             }
             throw new Error(`No provider found for token: ${this.tokenToString(token)}`);
         }
-        return this.resolveRegistration(registration);
+        return this.resolveRegistration(registration, requestingModuleId);
+    }
+    resolveAll(token, requestingModuleId) {
+        if (!this.has(token)) return [];
+        return [
+            this.resolve(token, requestingModuleId)
+        ];
     }
     has(token) {
         return this.providers.has(token);
@@ -88,27 +137,44 @@ export class Container {
    * The child shares the parent's providers but caches REQUEST-scoped
    * instances separately per child (per request).
    */ createChild() {
-        const child = new Container();
-        child.parent = this;
-        child.providers = this.providers; // share provider registrations
+        const child = new Container({
+            diagnostics: this.diagnostics
+        });
+        // Share state by reference — request-scope children must see the same
+        // module graph as the root.
+        child.providers = this.providers;
+        child.scopes = this.scopes;
+        child.globals = this.globals;
+        child.providerOrigin = this.providerOrigin;
         return child;
     }
     createDetached() {
-        const child = new Container();
-        child.providers = new Map(this.providers); // copy, not share
+        const child = new Container({
+            diagnostics: this.diagnostics
+        });
+        // Copy mutable per-resolution state; share static module-graph metadata
+        // so sandbox resolutions can still see exported providers.
+        child.providers = new Map(this.providers);
+        child.providerOrigin = new Map(this.providerOrigin);
+        child.scopes = this.scopes;
+        child.globals = this.globals;
         return child;
     }
     clear() {
         this.providers.clear();
         this.resolutionStack.clear();
         this.requestInstances.clear();
+        this.scopes.clear();
+        this.globals.clear();
+        this.providerOrigin.clear();
     }
-    resolveRegistration(registration) {
+    resolveRegistration(registration, requestingModuleId) {
         if (registration.useValue !== undefined) {
             return registration.useValue;
         }
         if (registration.useExisting) {
-            return this.resolve(registration.useExisting);
+            // Pass through the original requester to catch alias leaks
+            return this.resolve(registration.useExisting, requestingModuleId);
         }
         // Singleton: return cached from registration (shared across all containers)
         if (registration.scope === Scope.SINGLETON && registration.instance !== undefined) {
@@ -132,6 +198,10 @@ export class Container {
         try {
             let instance;
             if (registration.useFactory) {
+                // Factories (forRootAsync, useFactory) commonly inject deps from the
+                // importing module's scope. Vela has no `forRootAsync({ imports })`
+                // surface to track that, so factory inject deps resolve without a
+                // requester — same escape-hatch shape as ModuleRef.
                 instance = this.resolveFactory(registration);
             } else if (registration.useClass) {
                 instance = this.resolveClass(registration.useClass);
@@ -148,7 +218,9 @@ export class Container {
             this.resolutionStack.delete(registration.provide);
         }
     }
-    resolveClass(target) {
+    resolveClass(target, callerModuleId) {
+        // The class's dependencies resolve from ITS module's POV, not the caller's.
+        const ownerModuleId = this.providerOrigin.get(target) ?? callerModuleId;
         const paramTypes = getConstructorDependencies(target);
         const injectMetadata = getInjectMetadata(target);
         const injectMap = new Map(injectMetadata.map((m)=>[
@@ -169,19 +241,19 @@ export class Container {
             }
             // forwardRef with circular dep — break the cycle with a lazy Proxy
             if (isForwardRef && this.resolutionStack.has(token)) {
-                return this.createLazyProxy(token);
+                return this.createLazyProxy(token, ownerModuleId);
             }
-            return this.resolve(token);
+            return this.resolve(token, ownerModuleId);
         });
         return new target(...dependencies);
     }
-    resolveFactory(registration) {
+    resolveFactory(registration, requestingModuleId) {
         if (!registration.useFactory) {
             throw new Error('Factory function is missing');
         }
         const dependencies = (registration.inject || []).map((token)=>{
             const resolved = token instanceof ForwardRef ? token.factory() : token;
-            return this.resolve(resolved);
+            return this.resolve(resolved, requestingModuleId);
         });
         const result = registration.useFactory(...dependencies);
         if (result instanceof Promise) {
@@ -189,12 +261,22 @@ export class Container {
         }
         return result;
     }
-    async resolveAsync(token) {
+    async resolveAsync(token, requestingModuleId) {
+        if (requestingModuleId !== undefined) {
+            this.assertVisible(requestingModuleId, token);
+        }
         const registration = this.providers.get(token);
         if (!registration) {
             if (typeof token === 'function') {
-                this.register(token);
-                return this.resolveAsync(token);
+                throw new Error(`No provider found for token: ${this.tokenToString(token)}. ` + `Declare it in a module's providers.`);
+            }
+            if (token instanceof InjectionToken && token.options?.factory) {
+                // Self-providing token — register on demand from its declared factory.
+                this.register({
+                    provide: token,
+                    useFactory: token.options.factory
+                });
+                return this.resolveAsync(token, requestingModuleId);
             }
             throw new Error(`No provider found for token: ${this.tokenToString(token)}`);
         }
@@ -202,31 +284,58 @@ export class Container {
             if (registration.scope === Scope.SINGLETON && registration.instance !== undefined) {
                 return registration.instance;
             }
-            const dependencies = await Promise.all((registration.inject || []).map((t)=>this.resolveAsync(t)));
+            // Factory inject deps resolve without a requester (escape hatch — see
+            // resolveRegistration's useFactory branch).
+            const dependencies = await Promise.all((registration.inject || []).map((t)=>{
+                const resolved = t instanceof ForwardRef ? t.factory() : t;
+                return this.resolveAsync(resolved);
+            }));
             const instance = await registration.useFactory(...dependencies);
             if (registration.scope === Scope.SINGLETON) {
                 registration.instance = instance;
             }
             return instance;
         }
-        return this.resolve(token);
+        return this.resolve(token, requestingModuleId);
     }
-    createLazyProxy(token) {
+    createLazyProxy(token, requestingModuleId) {
         const container = this;
         const target = Object.create(null);
         return new Proxy(target, {
             get (_target, prop) {
-                const instance = container.resolve(token);
+                const instance = container.resolve(token, requestingModuleId);
                 const value = instance[prop];
                 return typeof value === 'function' ? value.bind(instance) : value;
             },
             set (_target, prop, value) {
-                const instance = container.resolve(token);
+                const instance = container.resolve(token, requestingModuleId);
                 instance[prop] = value;
                 return true;
             }
         });
     }
+    assertVisible(moduleId, token) {
+        if (this.globals.has(token)) return;
+        // InjectionTokens with a default factory are self-providing singletons —
+        // visible from any module without requiring explicit declaration.
+        if (token instanceof InjectionToken && token.options?.factory) return;
+        const scope = this.scopes.get(moduleId);
+        if (!scope) {
+            // No scope registered for this moduleId — typically synthetic /
+            // framework-internal callers. Allow rather than break primitives.
+            return;
+        }
+        if (scope.localProviders.has(token)) return;
+        if (this.isExportedFromImports(scope, token)) return;
+        throw new ModuleVisibilityError(moduleId, token);
+    }
+    isExportedFromImports(scope, token) {
+        for (const importedId of scope.importedModules){
+            const imported = this.scopes.get(importedId);
+            if (imported?.exportedTokens.has(token)) return true;
+        }
+        return false;
+    }
     tokenToString(token) {
         if (token instanceof InjectionToken) {
             return token.toString();

package/dist/container/index.d.ts

@@ -1,6 +1,6 @@
 export { Container } from './container';
 export { Injectable, Inject, Optional, isInjectable, getScope } from './decorators';
-export { InjectionToken, ForwardRef, forwardRef } from './types';
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError } from './types';
 export { ModuleRef } from './module-ref';
 export { mixin } from './mixin';
-export type { Type, Token, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, } from './types';
+export type { Type, Token, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ContainerOptions, Diagnostics, } from './types';

package/dist/container/index.js

@@ -1,5 +1,5 @@
 export { Container } from "./container.js";
 export { Injectable, Inject, Optional, isInjectable, getScope } from "./decorators.js";
-export { InjectionToken, ForwardRef, forwardRef } from "./types.js";
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError } from "./types.js";
 export { ModuleRef } from "./module-ref.js";
 export { mixin } from "./mixin.js";

package/dist/container/types.d.ts

@@ -43,3 +43,19 @@ export interface ProviderRegistration<T = unknown> {
     inject?: Token[];
     useExisting?: Token<T>;
 }
+export interface ModuleScope {
+    moduleId: string;
+    localProviders: Set<Token>;
+    importedModules: Set<string>;
+    exportedTokens: Set<Token>;
+    isGlobal: boolean;
+}
+export type Diagnostics = 'silent' | 'log' | 'throw';
+export interface ContainerOptions {
+    diagnostics?: Diagnostics;
+}
+export declare class ModuleVisibilityError extends Error {
+    readonly moduleId: string;
+    readonly token: Token;
+    constructor(moduleId: string, token: Token);
+}

package/dist/container/types.js

@@ -18,3 +18,17 @@ export class ForwardRef {
 export function forwardRef(factory) {
     return new ForwardRef(factory);
 }
+function describeToken(token) {
+    if (token instanceof InjectionToken) return token.toString();
+    if (typeof token === 'function') return token.name;
+    if (typeof token === 'symbol') return token.toString();
+    return String(token);
+}
+export class ModuleVisibilityError extends Error {
+    moduleId;
+    token;
+    constructor(moduleId, token){
+        super(`Module '${moduleId}' cannot resolve '${describeToken(token)}': ` + `not declared in providers, not imported from another module's exports, not @Global. ` + `Either add to imports/exports or mark as @Global.`), this.moduleId = moduleId, this.token = token;
+        this.name = 'ModuleVisibilityError';
+    }
+}

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

@@ -34,7 +34,12 @@ export class EventEmitterSubscriber {
             let instance;
             try {
                 instance = this.container.resolve(token);
-            } catch  {
+            } catch (err) {
+                const mode = this.container.getDiagnostics();
+                if (mode === 'throw') throw err;
+                if (mode === 'log') {
+                    console.warn(`[vela] event subscriber discovery: cannot resolve ${token.name || String(token)}:`, err);
+                }
                 continue;
             }
             for (const { event, methodName } of metadata){

package/dist/factory/bootstrap.d.ts

@@ -0,0 +1,23 @@
+import { Container } from '../container/container';
+import type { Diagnostics, Type } from '../container/types';
+import { RouteManager } from '../http/route.manager';
+import type { RouteManagerOptions } from '../http/route.manager';
+import { ModuleLoader } from '../module/module-loader';
+export interface BootstrapOptions extends RouteManagerOptions {
+    diagnostics?: Diagnostics;
+}
+export interface BootstrapResult {
+    container: Container;
+    routeManager: RouteManager;
+    loader: ModuleLoader;
+}
+/**
+ * Wire the DI graph for `rootModule` and prepare the route manager — without
+ * running lifecycle hooks or building the Hono app. The single primitive
+ * shared by `VelaFactory.create` (HTTP), `@velajs/testing` (test), and any
+ * non-HTTP consumer (CLI tools, custom runtimes).
+ *
+ * Framework-internal tokens (`Container`, `ModuleRef`, `APP_*`) are marked
+ * global so they are resolvable from any module.
+ */
+export declare function bootstrap(rootModule: Type, options?: BootstrapOptions): Promise<BootstrapResult>;

package/dist/factory/bootstrap.js

@@ -0,0 +1,62 @@
+import { Container } from "../container/container.js";
+import { ModuleRef } from "../container/module-ref.js";
+import { RouteManager } from "../http/route.manager.js";
+import { ModuleLoader } from "../module/module-loader.js";
+import { bindAppProviders } from "../pipeline/app-providers.js";
+import { ComponentManager } from "../pipeline/component.manager.js";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
+/**
+ * Wire the DI graph for `rootModule` and prepare the route manager — without
+ * running lifecycle hooks or building the Hono app. The single primitive
+ * shared by `VelaFactory.create` (HTTP), `@velajs/testing` (test), and any
+ * non-HTTP consumer (CLI tools, custom runtimes).
+ *
+ * Framework-internal tokens (`Container`, `ModuleRef`, `APP_*`) are marked
+ * global so they are resolvable from any module.
+ */ export async function bootstrap(rootModule, options = {}) {
+    const container = new Container({
+        diagnostics: options.diagnostics
+    });
+    container.register({
+        provide: Container,
+        useValue: container
+    });
+    container.markGlobalToken(Container);
+    container.register({
+        provide: ModuleRef,
+        useFactory: (c)=>new ModuleRef(c),
+        inject: [
+            Container
+        ]
+    });
+    container.markGlobalToken(ModuleRef);
+    for (const t of [
+        APP_GUARD,
+        APP_PIPE,
+        APP_INTERCEPTOR,
+        APP_FILTER,
+        APP_MIDDLEWARE
+    ]){
+        container.markGlobalToken(t);
+    }
+    const routeManager = new RouteManager(container, options);
+    ComponentManager.init(container);
+    const loader = new ModuleLoader(container, routeManager);
+    loader.load(rootModule);
+    bindAppProviders(routeManager, container, loader);
+    routeManager.registerConsumerMiddleware(loader.getConsumerMiddlewareDefinitions());
+    if (options.globalPrefix) {
+        routeManager.setGlobalPrefix(options.globalPrefix);
+    }
+    for (const handler of options.middleware ?? []){
+        const mw = {
+            use: handler
+        };
+        routeManager.useGlobalMiddleware(mw);
+    }
+    return {
+        container,
+        routeManager,
+        loader
+    };
+}

package/dist/factory.d.ts

@@ -1,6 +1,6 @@
 import { VelaApplication } from './application';
 import type { Type } from './container/types';
-import type { RouteManagerOptions } from './http/route.manager';
+import type { BootstrapOptions } from './factory/bootstrap';
 export declare const VelaFactory: {
-    create(rootModule: Type, options?: RouteManagerOptions): Promise<VelaApplication>;
+    create(rootModule: Type, options?: BootstrapOptions): Promise<VelaApplication>;
 };

package/dist/factory.js

@@ -1,39 +1,8 @@
 import { VelaApplication } from "./application.js";
-import { Container } from "./container/container.js";
-import { ModuleRef } from "./container/module-ref.js";
-import { bindAppProviders } from "./pipeline/app-providers.js";
-import { RouteManager } from "./http/route.manager.js";
-import { ModuleLoader } from "./module/module-loader.js";
-import { ComponentManager } from "./pipeline/component.manager.js";
+import { bootstrap } from "./factory/bootstrap.js";
 export const VelaFactory = {
     async create (rootModule, options = {}) {
-        const container = new Container();
-        container.register({
-            provide: Container,
-            useValue: container
-        });
-        container.register({
-            provide: ModuleRef,
-            useFactory: (c)=>new ModuleRef(c),
-            inject: [
-                Container
-            ]
-        });
-        const routeManager = new RouteManager(container, options);
-        ComponentManager.init(container);
-        const loader = new ModuleLoader(container, routeManager);
-        loader.load(rootModule);
-        bindAppProviders(routeManager, container, loader);
-        routeManager.registerConsumerMiddleware(loader.getConsumerMiddlewareDefinitions());
-        if (options.globalPrefix) {
-            routeManager.setGlobalPrefix(options.globalPrefix);
-        }
-        for (const handler of options.middleware ?? []){
-            const mw = {
-                use: handler
-            };
-            routeManager.useGlobalMiddleware(mw);
-        }
+        const { container, routeManager, loader } = await bootstrap(rootModule, options);
         const app = new VelaApplication(container, routeManager);
         const instances = await loader.resolveAllInstances();
         app.setInstances(instances);

package/dist/index.d.ts

@@ -2,10 +2,12 @@ import './metadata';
 export { defineMetadata, getMetadata } from './metadata';
 export { VelaFactory } from './factory';
 export { VelaApplication } from './application';
+export { bootstrap } from './factory/bootstrap';
+export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema, } from './openapi/index';
 export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from './container/index';
-export type { Type, Token, InjectableOptions, ProviderOptions, } from './container/index';
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, mixin, } from './container/index';
+export type { Type, Token, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, } from './http/index';
 export { Logger, LogLevel } from './services/index';
@@ -29,6 +31,8 @@ export type { ThrottlerModuleOptions, ThrottleConfig, ThrottlerStore, ThrottlerS
 export { Global, Module, createModuleRef } from './module/index';
 export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport } from './module/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
+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, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } 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';

package/dist/index.js

@@ -3,10 +3,11 @@ export { defineMetadata, getMetadata } from "./metadata.js";
 // Factory & Application
 export { VelaFactory } from "./factory.js";
 export { VelaApplication } from "./application.js";
+export { bootstrap } from "./factory/bootstrap.js";
 // OpenAPI
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from "./container/index.js";
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, mixin } from "./container/index.js";
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
@@ -31,6 +32,8 @@ export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthInd
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA } from "./throttler/index.js";
 // Module
 export { Global, Module, createModuleRef } from "./module/index.js";
+// Plugin manifest + composer
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
 // Built-in Pipes

package/dist/internal.d.ts

@@ -1,5 +1,7 @@
 export { Container } from './container/container';
 export { ModuleRef } from './container/module-ref';
+export { ModuleVisibilityError } from './container/types';
+export type { ModuleScope, ContainerOptions, Diagnostics, } from './container/types';
 export { bindAppProviders } from './pipeline/app-providers';
 export { RouteManager } from './http/route.manager';
 export type { RouteManagerOptions } from './http/route.manager';
@@ -9,3 +11,7 @@ export { VelaApplication } from './application';
 export { MetadataRegistry } from './registry/metadata.registry';
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/tokens';
 export { getModuleMetadata, isModule } from './module/decorators';
+export { bootstrap } from './factory/bootstrap';
+export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
+export type { Plugin } from './plugin/plugin';

package/dist/internal.js

@@ -3,6 +3,7 @@
 // to the same degree as the public surface (./index).
 export { Container } from "./container/container.js";
 export { ModuleRef } from "./container/module-ref.js";
+export { ModuleVisibilityError } from "./container/types.js";
 export { bindAppProviders } from "./pipeline/app-providers.js";
 export { RouteManager } from "./http/route.manager.js";
 export { ModuleLoader } from "./module/module-loader.js";
@@ -11,3 +12,8 @@ export { VelaApplication } from "./application.js";
 export { MetadataRegistry } from "./registry/metadata.registry.js";
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/tokens.js";
 export { getModuleMetadata, isModule } from "./module/decorators.js";
+// Bootstrap primitive — used by VelaFactory.create, @velajs/testing, and any
+// non-HTTP consumer (CLI tools, custom runtimes).
+export { bootstrap } from "./factory/bootstrap.js";
+// Plugin manifest + composer
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";

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

@@ -14,8 +14,11 @@ export declare class ModuleLoader {
     private consumerMiddlewareDefinitions;
     private appProviderCounter;
     private appProviderTokens;
+    private moduleIdByClass;
+    private seenModuleIds;
     constructor(container: Container, router: RouteManager);
     load(rootModule: Type): void;
+    private getModuleId;
     private processModule;
     private registerProvider;
     private isAppToken;
@@ -25,4 +28,5 @@ export declare class ModuleLoader {
     getAppProviderTokens(token: Token): Token[];
     getConsumerMiddlewareDefinitions(): MiddlewareRouteDefinition[];
     resolveAllInstances(): Promise<unknown[]>;
+    private routeError;
 }

package/dist/module/module-loader.js

@@ -1,5 +1,5 @@
 import { Scope } from "../constants.js";
-import { ForwardRef, InjectionToken } from "../container/types.js";
+import { ForwardRef, InjectionToken, ModuleVisibilityError } from "../container/types.js";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { getOrCreateArray } from "../registry/util.js";
@@ -18,6 +18,9 @@ function isDynamicModule(value) {
 function implementsNestModule(cls) {
     return typeof cls.prototype?.configure === "function";
 }
+function tokenOfProvider(provider) {
+    return typeof provider === "function" ? provider : provider.provide;
+}
 export class ModuleLoader {
     container;
     router;
@@ -51,6 +54,8 @@ export class ModuleLoader {
             []
         ]
     ]);
+    moduleIdByClass = new Map();
+    seenModuleIds = new Set();
     constructor(container, router){
         this.container = container;
         this.router = router;
@@ -61,6 +66,19 @@ export class ModuleLoader {
             this.router.registerController(controller);
         }
     }
+    getModuleId(moduleClass) {
+        const cached = this.moduleIdByClass.get(moduleClass);
+        if (cached) return cached;
+        const baseName = moduleClass.name || "AnonModule";
+        let id = baseName;
+        let counter = 0;
+        while(this.seenModuleIds.has(id)){
+            id = `${baseName}#${++counter}`;
+        }
+        this.seenModuleIds.add(id);
+        this.moduleIdByClass.set(moduleClass, id);
+        return id;
+    }
     processModule(moduleClassOrDynamic) {
         // Handle dynamic modules ({ module, imports, controllers, providers })
         let moduleClass;
@@ -103,8 +121,12 @@ export class ModuleLoader {
             throw new Error(`Failed to get module metadata for ${moduleClass.name}`);
         }
         this.processingStack.add(moduleClass);
+        const moduleId = this.getModuleId(moduleClass);
         try {
             const importedProviders = new Set(this.globalExports);
+            // Determine importedModuleIds eagerly (before recursing) so child
+            // modules can be referenced in our scope's importedModules set.
+            const importedModuleIds = new Set();
             for (const entry of [
                 ...metadata.imports,
                 ...extraImports
@@ -113,6 +135,7 @@ export class ModuleLoader {
                 const isForwardRef = entry instanceof ForwardRef;
                 const importedModule = isForwardRef ? entry.factory() : entry;
                 const importedModuleClass = isDynamicModule(importedModule) ? importedModule.module : importedModule;
+                importedModuleIds.add(this.getModuleId(importedModuleClass));
                 // If this forwardRef-wrapped import is currently being processed, skip it to
                 // break the circular chain. Non-forwardRef circular imports still throw.
                 if (isForwardRef && this.processingStack.has(importedModuleClass)) {
@@ -123,19 +146,42 @@ export class ModuleLoader {
                     importedProviders.add(token);
                 }
             }
-            // Register metadata providers + dynamic module extra providers
             const allProviders = [
                 ...metadata.providers,
                 ...extraProviders
             ];
-            for (const provider of allProviders){
-                this.registerProvider(provider);
-            }
-            // Collect metadata controllers + dynamic module extra controllers
             const allControllers = [
                 ...metadata.controllers,
                 ...extraControllers
             ];
+            const allExports = [
+                ...metadata.exports,
+                ...extraExports
+            ];
+            // Build the ModuleScope BEFORE registering providers so the visibility
+            // check sees the local-provider set as we register.
+            const localProviders = new Set();
+            for (const provider of allProviders){
+                const tk = tokenOfProvider(provider);
+                if (tk !== undefined) localProviders.add(tk);
+            }
+            for (const controller of allControllers){
+                localProviders.add(controller);
+            }
+            // The module class itself can be DI-resolved (NestModule.configure path);
+            // include it in its own scope.
+            localProviders.add(moduleClass);
+            const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
+            this.container.registerScope({
+                moduleId,
+                localProviders,
+                importedModules: importedModuleIds,
+                exportedTokens: new Set(allExports),
+                isGlobal
+            });
+            for (const provider of allProviders){
+                this.registerProvider(provider, moduleId);
+            }
             for (const controller of allControllers){
                 this.collectedControllers.add(controller);
             }
@@ -144,13 +190,8 @@ export class ModuleLoader {
                 MetadataRegistry.propagateControllerComponents(moduleClass, controller);
             }
             this.processedModules.add(moduleClass);
-            const allExports = [
-                ...metadata.exports,
-                ...extraExports
-            ];
             const exports = this.buildExportSet(allExports, allProviders, importedProviders);
             this.moduleExportsCache.set(moduleClass, exports);
-            const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
             if (isGlobal) {
                 for (const token of exports){
                     this.globalExports.add(token);
@@ -160,9 +201,9 @@ export class ModuleLoader {
             // resolved through the container so it can have its own DI dependencies.
             if (implementsNestModule(moduleClass)) {
                 if (!this.container.has(moduleClass)) {
-                    this.container.register(moduleClass);
+                    this.container.register(moduleClass, moduleId);
                 }
-                const instance = this.container.resolve(moduleClass);
+                const instance = this.container.resolve(moduleClass, moduleId);
                 const builder = new MiddlewareBuilder();
                 instance.configure(builder);
                 this.consumerMiddlewareDefinitions.push(...builder.getDefinitions());
@@ -172,16 +213,16 @@ export class ModuleLoader {
             this.processingStack.delete(moduleClass);
         }
     }
-    registerProvider(provider) {
+    registerProvider(provider, moduleId) {
         if (typeof provider === "function") {
             if (!this.container.has(provider)) {
-                this.container.register(provider);
+                this.container.register(provider, moduleId);
                 this.registeredProviders.push(provider);
             }
         } else {
             const token = provider.provide;
             if (!token) {
-                this.container.register(provider);
+                this.container.register(provider, moduleId);
                 return;
             }
             if (this.isAppToken(token)) {
@@ -189,13 +230,16 @@ export class ModuleLoader {
                 this.container.register({
                     ...provider,
                     provide: syntheticToken
-                });
+                }, moduleId);
+                // Synthetic APP_* tokens are resolved at request time by RouteManager
+                // with no requester; mark them global so the visibility check passes.
+                this.container.markGlobalToken(syntheticToken);
                 this.registeredProviders.push(syntheticToken);
                 getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
                 return;
             }
             if (!this.container.has(token)) {
-                this.container.register(provider);
+                this.container.register(provider, moduleId);
                 this.registeredProviders.push(token);
             }
         }
@@ -207,7 +251,7 @@ export class ModuleLoader {
         const exportSet = new Set();
         const providerTokens = new Set();
         for (const p of providers){
-            const token = typeof p === "function" ? p : p.provide;
+            const token = tokenOfProvider(p);
             if (token !== undefined) providerTokens.add(token);
         }
         for (const exported of exports){
@@ -250,8 +294,11 @@ export class ModuleLoader {
                 }
                 const instance = await this.container.resolveAsync(token);
                 instanceSet.add(instance);
-            } catch  {
-            // Skip unresolvable tokens
+            } catch (err) {
+                // Module visibility errors must always propagate — they indicate a
+                // genuine wiring bug, not something to swallow as a discovery skip.
+                if (err instanceof ModuleVisibilityError) throw err;
+                this.routeError(err, `resolve provider`);
             }
         }
         for (const controller of this.collectedControllers){
@@ -261,12 +308,22 @@ export class ModuleLoader {
                 }
                 const instance = await this.container.resolveAsync(controller);
                 instanceSet.add(instance);
-            } catch  {
-            // Skip unresolvable controllers
+            } catch (err) {
+                if (err instanceof ModuleVisibilityError) throw err;
+                this.routeError(err, `resolve controller ${controller.name}`);
             }
         }
         return [
             ...instanceSet
         ];
     }
+    routeError(err, context) {
+        const mode = this.container.getDiagnostics();
+        if (mode === "silent") return;
+        if (mode === "throw") {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+        // 'log'
+        console.warn(`[vela] ${context} failed:`, err);
+    }
 }

package/dist/plugin/plugin.d.ts

@@ -0,0 +1,31 @@
+import { InjectionToken } from '../container/types';
+import type { Type } from '../container/types';
+import type { DynamicModule } from '../registry/types';
+export interface Plugin {
+    id: string;
+    version: string;
+    module: Type | DynamicModule;
+    dependsOn?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Freeze and validate a plugin manifest. Returns the same object so it can
+ * be used in `composePlugins([definePlugin(...), ...])`.
+ */
+export declare function definePlugin(plugin: Plugin): Plugin;
+export declare class PluginRegistry {
+    private byId;
+    constructor(plugins: readonly Plugin[]);
+    list(): Plugin[];
+    get(id: string): Plugin | undefined;
+    dependents(id: string): Plugin[];
+}
+export declare const PLUGIN_REGISTRY_TOKEN: InjectionToken<PluginRegistry>;
+export declare class PluginRootModule {
+}
+/**
+ * Compose a list of plugins into a single dynamic module that imports each
+ * plugin's module in dependency order, registers a `PluginRegistry`, and
+ * exposes it globally so any plugin can introspect peers.
+ */
+export declare function composePlugins(plugins: readonly Plugin[]): DynamicModule;

package/dist/plugin/plugin.js

@@ -0,0 +1,111 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { InjectionToken } from "../container/types.js";
+import { Module } from "../module/decorators.js";
+/**
+ * Freeze and validate a plugin manifest. Returns the same object so it can
+ * be used in `composePlugins([definePlugin(...), ...])`.
+ */ export function definePlugin(plugin) {
+    if (!plugin.id) throw new Error('Plugin requires an id');
+    if (!plugin.version) throw new Error('Plugin requires a version');
+    if (!plugin.module) throw new Error('Plugin requires a module');
+    return Object.freeze({
+        ...plugin
+    });
+}
+export class PluginRegistry {
+    byId;
+    constructor(plugins){
+        this.byId = new Map();
+        for (const p of plugins){
+            if (this.byId.has(p.id)) {
+                throw new Error(`Duplicate plugin id: '${p.id}'`);
+            }
+            this.byId.set(p.id, p);
+        }
+    }
+    list() {
+        return [
+            ...this.byId.values()
+        ];
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    dependents(id) {
+        return this.list().filter((p)=>p.dependsOn?.includes(id) ?? false);
+    }
+}
+export const PLUGIN_REGISTRY_TOKEN = new InjectionToken('PLUGIN_REGISTRY');
+export class PluginRootModule {
+}
+PluginRootModule = _ts_decorate([
+    Module({})
+], PluginRootModule);
+/**
+ * Topologically sort plugins so each plugin's dependencies appear first.
+ * Throws on missing dependencies and cycles.
+ */ function topologicalSort(plugins) {
+    const byId = new Map();
+    for (const p of plugins){
+        if (byId.has(p.id)) {
+            throw new Error(`Duplicate plugin id: '${p.id}'`);
+        }
+        byId.set(p.id, p);
+    }
+    const result = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (p, path)=>{
+        if (visited.has(p.id)) return;
+        if (visiting.has(p.id)) {
+            const cycle = [
+                ...path,
+                p.id
+            ].join(' -> ');
+            throw new Error(`Plugin cycle detected: ${cycle}`);
+        }
+        visiting.add(p.id);
+        for (const depId of p.dependsOn ?? []){
+            const dep = byId.get(depId);
+            if (!dep) {
+                throw new Error(`Plugin '${p.id}' depends on missing plugin '${depId}'`);
+            }
+            visit(dep, [
+                ...path,
+                p.id
+            ]);
+        }
+        visiting.delete(p.id);
+        visited.add(p.id);
+        result.push(p);
+    };
+    for (const p of plugins)visit(p, []);
+    return result;
+}
+/**
+ * Compose a list of plugins into a single dynamic module that imports each
+ * plugin's module in dependency order, registers a `PluginRegistry`, and
+ * exposes it globally so any plugin can introspect peers.
+ */ export function composePlugins(plugins) {
+    const sorted = topologicalSort(plugins);
+    const registry = new PluginRegistry(sorted);
+    return {
+        module: PluginRootModule,
+        imports: sorted.map((p)=>p.module),
+        providers: [
+            {
+                provide: PLUGIN_REGISTRY_TOKEN,
+                useValue: registry
+            }
+        ],
+        exports: [
+            PLUGIN_REGISTRY_TOKEN
+        ],
+        global: true
+    };
+}

package/dist/schedule/schedule.registry.js

@@ -33,7 +33,12 @@ export class ScheduleRegistry {
             let instance;
             try {
                 instance = this.container.resolve(token);
-            } catch  {
+            } catch (err) {
+                const mode = this.container.getDiagnostics();
+                if (mode === 'throw') throw err;
+                if (mode === 'log') {
+                    console.warn(`[vela] schedule discovery: cannot resolve ${token.name || String(token)}:`, err);
+                }
                 continue;
             }
             if (cronMeta) {

package/dist/schedule-node/schedule.executor.d.ts

@@ -1,13 +1,15 @@
+import { Container } from '../container/container';
 import type { OnApplicationBootstrap, OnModuleDestroy } from '../lifecycle/index';
 import { ScheduleRegistry } from '../schedule/schedule.registry';
 export declare class ScheduleExecutor implements OnApplicationBootstrap, OnModuleDestroy {
     private registry;
+    private container;
     private intervalTimers;
     private cronTimers;
     private cronMatcherCache;
     private lastCronMinute;
     private running;
-    constructor(registry: ScheduleRegistry);
+    constructor(registry: ScheduleRegistry, container: Container);
     onApplicationBootstrap(): void;
     private scheduleInterval;
     private scheduleCron;

package/dist/schedule-node/schedule.executor.js

@@ -7,18 +7,26 @@ function _ts_decorate(decorators, target, key, desc) {
 function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-import { Injectable } from "../container/index.js";
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable } from "../container/index.js";
+import { Container } from "../container/container.js";
 import { parseCron } from "../schedule/cron-matcher.js";
 import { ScheduleRegistry } from "../schedule/schedule.registry.js";
 export class ScheduleExecutor {
     registry;
+    container;
     intervalTimers = [];
     cronTimers = [];
     cronMatcherCache = new Map();
     lastCronMinute = new Map();
     running = true;
-    constructor(registry){
+    constructor(registry, container){
         this.registry = registry;
+        this.container = container;
     }
     onApplicationBootstrap() {
         if (typeof setInterval !== 'function') {
@@ -61,8 +69,14 @@ export class ScheduleExecutor {
             if (typeof method === 'function') {
                 await method.call(instance);
             }
-        } catch  {
-        // Swallow errors so the scheduler keeps running
+        } catch (err) {
+            // Runtime job error — keep the scheduler running by default. Users
+            // can opt into rethrowing by setting diagnostics: 'throw'.
+            const mode = this.container.getDiagnostics();
+            if (mode === 'throw') throw err;
+            if (mode === 'log') {
+                console.warn(`[vela] scheduled job ${methodName} failed:`, err);
+            }
         }
     }
     getMatcher(expression) {
@@ -84,8 +98,10 @@ export class ScheduleExecutor {
 }
 ScheduleExecutor = _ts_decorate([
     Injectable(),
+    _ts_param(1, Inject(Container)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof ScheduleRegistry === "undefined" ? Object : ScheduleRegistry
+        typeof ScheduleRegistry === "undefined" ? Object : ScheduleRegistry,
+        typeof Container === "undefined" ? Object : Container
     ])
 ], ScheduleExecutor);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -61,17 +61,21 @@
     "hono": "^4"
   },
   "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.15.2",
     "@swc/cli": "^0.8.0",
     "@swc/core": "^1.15.11",
     "@types/bun": "latest",
+    "@vitest/runner": "^4.1.5",
+    "@vitest/snapshot": "^4.1.5",
     "typescript": "^5",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.5",
     "zod": "^4.3.6"
   },
   "scripts": {
     "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
     "test": "vitest run",
+    "test:workers": "vitest run --config vitest.config.workers.ts",
     "typecheck": "tsc --noEmit"
   }
 }