@velajs/vela 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## Unreleased
+
+A sanctioned per-request injectable lands as a framework primitive, and the metadata-store unification finally has its regression tests.
+
+### New
+
+- **`REQUEST_CONTEXT` injectable.** A request-scoped primitive carrying a stable `id` (mirrored from inbound `x-request-id` if present, else `crypto.randomUUID()`), `receivedAt`, the raw `Request`, the Hono `Context`, and a typed `set/get/has` bag for cross-cutting metadata. Seeded by `RouteManager` into each per-request child container; resolves through `@Inject(REQUEST_CONTEXT)` from any request-scoped service. No `AsyncLocalStorage` — edge-runtime contract intact (verified live under workerd via `pnpm test:workers`).
+
+  ```ts
+  import { Inject, Injectable, Scope, REQUEST_CONTEXT } from '@velajs/vela';
+  import type { RequestContext } from '@velajs/vela';
+
+  @Injectable({ scope: Scope.REQUEST })
+  class TenantResolver {
+    constructor(@Inject(REQUEST_CONTEXT) private readonly ctx: RequestContext) {}
+    resolve() {
+      return this.ctx.hono.req.header('x-tenant') ?? 'default';
+    }
+  }
+  ```
+
+### Internal cleanup
+
+- **Metadata stacking + funnel coverage** (audit #8 follow-up). New `metadata-stacking.test.ts` asserts `appendCustomHandlerMeta` is order-deterministic, `Reflect.defineMetadata` round-trips through `MetadataRegistry`'s typed slots, `MetadataRegistry.reset()` clears `classMeta`/`handlerMeta`, and class+handler `@SetMetadata` on the same key remain independent.
+- **Stale `WeakMap` comment removed** from `MetadataRegistry.reset()` — the WeakMap fallback was retired in 1.1.0; the comment was documentation drift.
+- **`Container.setRequestInstance(token, value)`** — public method to pre-seed the per-request cache. Used by `RouteManager` to populate `REQUEST_CONTEXT` before any handler resolution runs.
+
+## 1.3.0
+
+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,24 @@
 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;
+    setRequestInstance(token: Token, value: unknown): 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 +33,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,80 @@ 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);
+        }
     }
-    resolve(token) {
+    markGlobalToken(token) {
+        this.globals.add(token);
+    }
+    // Pre-seed the per-request cache. Only meaningful on a child container
+    // produced by createChild() — the root's requestInstances map is unused.
+    // Used by RouteManager to populate framework-provided request-scope
+    // values (REQUEST_CONTEXT) before any handler resolution runs, so the
+    // provider's factory never fires on the request path.
+    setRequestInstance(token, value) {
+        this.requestInstances.set(token, value);
+    }
+    getDiagnostics() {
+        return this.diagnostics;
+    }
+    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 +145,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 +206,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 +226,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 +249,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 +269,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 +292,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,76 @@
+import { Scope } from "../constants.js";
+import { Container } from "../container/container.js";
+import { ModuleRef } from "../container/module-ref.js";
+import { REQUEST_CONTEXT } from "../http/request-context.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);
+    }
+    // REQUEST_CONTEXT is seeded into each request-scoped child by RouteManager
+    // before any handler resolves it (see route.manager.ts:getRequestContainer).
+    // The factory throws so misuse outside the request path surfaces immediately
+    // instead of materializing a phantom context.
+    container.register({
+        provide: REQUEST_CONTEXT,
+        scope: Scope.REQUEST,
+        useFactory: ()=>{
+            throw new Error('REQUEST_CONTEXT can only be resolved inside a request — ' + 'it is seeded by RouteManager when the request enters the pipeline.');
+        }
+    });
+    container.markGlobalToken(REQUEST_CONTEXT);
+    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>;
 };