@velajs/vela 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # Changelog
 
+## 1.11.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
+entirely on the public API. See `MODULE_AUTHORING.md` for the author contract.
+Contains deliberate breaking changes (no deprecation shims); coordinated
+releases of `@velajs/{storage,better-auth,testing,crud,cloudflare}` accompany
+this version.
+
+### Added
+
+- **`defineModule`** — the single module-authoring engine: generates `forRoot`
+  AND `forRootAsync` (typed `inject` inference), derives deterministic
+  `stableHash` keys (`key(options)` override + explicit `key` passthrough),
+  and accepts contributions (providers/controllers/imports/exports) **as
+  functions of the options** plus a standardized `global:` component slot.
+  `ConfigurableModuleBuilder` is now a thin adapter over it (unchanged API).
+- **Authoring primitives**: `lazyProvider` (memoized deferred thunk — replaces
+  the hand-rolled `(...deps)=>()=>fn(...deps)` closures), `provideGlobal`
+  (the one `APP_*` wiring idiom), `sideEffectModule` (first-class
+  contribution-only modules; supported form of the i18n empty-marker trick),
+  `moduleToken`, `moduleKey`.
+- **`DiscoveryService` + `createDiscoverableDecorator`** — public
+  decorator-driven discovery (`providersWithMeta`, `methodsWithMeta`,
+  `getProviders`) backed by a reverse metadata index inside
+  `MetadataRegistry`; honors container diagnostics in one place;
+  request-scoped providers are surfaced but not materialized (opt in with
+  `includeRequestScoped`). The event-emitter, schedule, and websocket
+  bootstrap scans now all run through it.
+- **Open entrypoint registry** — `registerEntrypointKind({ kind, metaKey,
+  level })`, the `ContributesEntrypoints` interface, and per-application
+  `app.entrypoints` (`ofKind`/`kinds`/`all`), built at the end of
+  `callOnApplicationBootstrap()` so slim bootstrap paths (Cloudflare Durable
+  Objects) get it too. Transports query entrypoints instead of module
+  internals; a new kind (queue, cron, CLI) needs **zero core changes**.
+- **`RouteContributor`** — public metadata-claimed route generation
+  (`registerRouteContributor`), consulted after explicit routes and during
+  OpenAPI generation with verb-level merge. Replaces the internal CrudBridge.
+- **`RuntimeAdapter`** — `VelaFactory.create(module, { adapters: [...] })`
+  with `requestMiddleware` (prepended to the global chain), `onBootstrap`
+  (after lifecycle + entrypoints, before routes) and `onRoutesBuilt` hooks.
+- **`PipelineRunner`** — the shared guard → pipe → interceptor execution core
+  used by HTTP and WebSocket dispatch (and any custom dispatcher);
+  configurable args/guards order, transport-specific guard-rejection error.
+- **`Container.replaceProvider(provider, { buckets })`** — supported
+  force-replace across module buckets (what test harnesses need).
+- **`buildEntrypointExecutionContext(kind, class, handler, payload)`** — the
+  entrypoint sibling of the HTTP/WS execution contexts, so guards/
+  interceptors/filters written against `getClass()`/`getHandler()`/`getType()`
+  run unchanged around queue batches, scheduled ticks, and custom kinds
+  (`EntrypointExecutionContext.getPayload()`). `@velajs/cloudflare` dispatches
+  queue/scheduled handlers through `PipelineRunner` with consumer-scoped
+  components (HTTP-global components deliberately do not apply; unclaimed
+  errors rethrow to preserve platform retry semantics).
+- **`runInEntrypointScope(container, fn)`** — the non-HTTP dispatch scope
+  primitive: runs one unit of work (queue batch, scheduled tick, RPC call) in
+  a fresh request-scoped child with LIFO disposal — the per-request-child
+  equivalent for entrypoint dispatchers. `@velajs/cloudflare`'s queue and
+  scheduled handlers run on it (request-scoped consumer deps rebuild per
+  batch/tick instead of capturing boot instances).
+
+### Changed
+
+- **Factory dependency visibility**: `useFactory`/`forRootAsync` `inject`
+  deps now resolve from the declaring module's scope FIRST (imports and
+  exports are honored), with the legacy no-requester lookup kept as fallback.
+- **All in-core configurable modules are on the one engine**: `CorsModule` and
+  `SeederModule` rebuilt on `defineModule` (Cors gains `forRootAsync`; both
+  keep their token/key identities), `ScheduleModule`/`ScheduleNodeModule`
+  normalized to zero-config `@Module` bags with parity `forRoot()` sugar.
+  Builder-based modules (Config/Cache/I18n/Throttler/Http) already run on it
+  through the `ConfigurableModuleBuilder` adapter.
+- **Unhandled handler errors are logged**: an error no exception filter claims
+  still maps to the generic 500 response, but the cause now lands in the logs
+  (`console.error`, gated on container diagnostics ≠ `silent`) — closing the
+  silent-500 gap.
+- **`WebSocketModule`** rebuilt on `defineModule`: registry → driver → server
+  construction moved into chained provider factories (single shared registry
+  preserved; everything materializes at bootstrap), deterministic key
+  `ws#<sync-kind>` — **two identical `forRoot()` calls now dedup**
+  (HMR-idempotent; pass explicit `key` for exotic multi-instance),
+  `forRootAsync` available. `WsDispatcher` contributes `'websocket'`
+  entrypoints; `registerWebSocketGateways` consumes
+  `app.entrypoints.ofKind('websocket')`.
+
+### Breaking
+
+- **`WS_MODULE_OPTIONS`** is now a typed `InjectionToken` (was the raw string
+  `'vela:ws-module-options'`).
+- **`ComponentManager`** is stateless: `init()` and the process-global
+  container are gone; `resolve*` methods require an explicit container;
+  `getComponents` replaced by `getScopedComponents` (controller + handler
+  only — app-wide components have one source: `RouteManager`).
+  `registerGlobal`/`MetadataRegistry.getGlobal` (a dead tier with no readers
+  on the request path) are removed; `MetadataRegistry.clear()` is now a
+  no-op.
+- **CrudBridge removed** (`registerCrudBridge`/`getCrudBridge` and the
+  `/internal` exports): use `registerRouteContributor`. `@velajs/crud`
+  migrates in its coordinated release.
+- `forRootAsync` structural fields (non-async keys passed alongside
+  `useFactory`) now merge under the resolved options.
+
 ## 1.10.0 (2026-07-01)
 
 ### Added

package/dist/application.d.ts

@@ -1,6 +1,7 @@
 import type { Hono } from 'hono';
 import type { Container } from './container/container';
 import type { Token } from './container/types';
+import { EntrypointRegistry } from './entrypoint/entrypoint.registry';
 import type { RouteManager } from './http/route.manager';
 import type { MountOpenApiOptions } from './openapi/types';
 import type { FilterType, GuardType, InterceptorType, PipeType } from './registry/types';
@@ -9,6 +10,7 @@ export declare class VelaApplication {
     private readonly routeManager;
     private instances;
     private honoApp;
+    private entrypointRegistry;
     private disposed;
     constructor(container: Container, routeManager: RouteManager);
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */
@@ -44,6 +46,12 @@ export declare class VelaApplication {
     mountOpenApi(options: MountOpenApiOptions): this;
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
+    /**
+     * Every entrypoint contributed by the module graph, grouped by kind —
+     * what runtime adapters/transports query instead of re-scanning providers:
+     * `app.entrypoints.ofKind('websocket')`.
+     */
+    get entrypoints(): EntrypointRegistry;
     close(signal?: string): Promise<void>;
     /**
      * Full teardown: run shutdown lifecycle hooks ({@link close}) then dispose

package/dist/application.js

@@ -1,3 +1,5 @@
+import { DiscoveryService } from "./discovery/discovery.service.js";
+import { EntrypointRegistry } from "./entrypoint/entrypoint.registry.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";
@@ -7,6 +9,7 @@ export class VelaApplication {
     routeManager;
     instances = [];
     honoApp = null;
+    entrypointRegistry = null;
     disposed = false;
     constructor(container, routeManager){
         this.container = container;
@@ -137,6 +140,23 @@ export class VelaApplication {
                 await instance.onApplicationBootstrap();
             }
         }
+        // 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`.
+        const discovery = this.container.has(DiscoveryService) ? this.container.resolve(DiscoveryService) : new DiscoveryService(this.container);
+        this.entrypointRegistry = await EntrypointRegistry.build(discovery, this.instances);
+    }
+    /**
+   * Every entrypoint contributed by the module graph, grouped by kind —
+   * what runtime adapters/transports query instead of re-scanning providers:
+   * `app.entrypoints.ofKind('websocket')`.
+   */ get entrypoints() {
+        if (!this.entrypointRegistry) {
+            throw new Error('Entrypoints are not built yet — they are assembled at the end of ' + 'callOnApplicationBootstrap(). Finish bootstrapping before querying them.');
+        }
+        return this.entrypointRegistry;
     }
     async close(signal) {
         const reversed = [

package/dist/container/container.d.ts

@@ -52,6 +52,21 @@ export declare class Container {
     has(token: Token): boolean;
     /** True if the specified module's bucket has a registration for `token`. */
     hasInScope(token: Token, moduleId: string): boolean;
+    /** Module buckets that hold a registration for `token` (registration order). */
+    getOwnerModuleIds(token: Token): string[];
+    /**
+     * Force-replace a provider across module scopes — the supported form of the
+     * override loop test harnesses need (module-scoped resolution consults the
+     * module's own bucket first, so a root-only override would never win there).
+     *
+     * - `'all-existing'` (default): every non-root bucket that already holds the
+     *   token, plus `__root__` (so framework-internal lookups see it too).
+     * - `'root'`: only the `__root__` bucket.
+     * - `string[]`: exactly these bucket ids.
+     */
+    replaceProvider<T>(provider: Type<T> | ProviderOptions<T>, options?: {
+        buckets?: 'all-existing' | 'root' | string[];
+    }): this;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
     /**
@@ -95,6 +110,16 @@ export declare class Container {
     dispose(): Promise<void>;
     private resolveRegistration;
     private resolveClass;
+    /**
+     * Resolve one factory `inject` dependency. Since 1.11 the declaring module's
+     * scope is consulted FIRST (proper visibility semantics — a `forRootAsync`
+     * factory can inject providers reachable through its module's imports); on
+     * any failure the legacy no-requester lookup (root bucket, then first
+     * exporter) is kept as fallback, so every previously-resolving graph still
+     * resolves.
+     */
+    private resolveFactoryDependency;
+    private resolveFactoryDependencyAsync;
     private resolveFactory;
     resolveAsync<T>(token: Token<T>, requestingModuleId?: string): Promise<T>;
     private createLazyProxy;

package/dist/container/container.js

@@ -288,6 +288,39 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     /** True if the specified module's bucket has a registration for `token`. */ hasInScope(token, moduleId) {
         return this.providers.get(moduleId)?.has(token) ?? false;
     }
+    /** Module buckets that hold a registration for `token` (registration order). */ getOwnerModuleIds(token) {
+        return [
+            ...this.exporterIndex.get(token) ?? []
+        ];
+    }
+    /**
+   * Force-replace a provider across module scopes — the supported form of the
+   * override loop test harnesses need (module-scoped resolution consults the
+   * module's own bucket first, so a root-only override would never win there).
+   *
+   * - `'all-existing'` (default): every non-root bucket that already holds the
+   *   token, plus `__root__` (so framework-internal lookups see it too).
+   * - `'root'`: only the `__root__` bucket.
+   * - `string[]`: exactly these bucket ids.
+   */ replaceProvider(provider, options = {}) {
+        const buckets = options.buckets ?? 'all-existing';
+        if (buckets === 'root') {
+            return this.register(provider);
+        }
+        if (Array.isArray(buckets)) {
+            for (const moduleId of buckets)this.register(provider, moduleId);
+            return this;
+        }
+        const token = typeof provider === 'function' ? provider : provider.provide;
+        if (!token) {
+            throw new Error('replaceProvider requires a token (`provide`)');
+        }
+        for (const [moduleId, bucket] of this.providers){
+            if (moduleId === ROOT_MODULE_ID) continue;
+            if (bucket.has(token)) this.register(provider, moduleId);
+        }
+        return this.register(provider);
+    }
     getProviderScope(token) {
         const exporters = this.exporterIndex.get(token);
         if (!exporters) return undefined;
@@ -516,10 +549,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         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 from the
-                // declaring module's POV — same escape-hatch shape as ModuleRef.
+                // Factory inject deps resolve from the declaring module's scope first
+                // (visibility-correct for forRootAsync), with the legacy no-requester
+                // lookup kept as fallback — see resolveFactoryDependency.
                 instance = this.resolveFactory(registration);
             } else if (registration.useClass) {
                 instance = this.resolveClass(registration.useClass, registration.declaringModuleId);
@@ -578,16 +610,40 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         });
         return new target(...dependencies);
     }
+    /**
+   * Resolve one factory `inject` dependency. Since 1.11 the declaring module's
+   * scope is consulted FIRST (proper visibility semantics — a `forRootAsync`
+   * factory can inject providers reachable through its module's imports); on
+   * any failure the legacy no-requester lookup (root bucket, then first
+   * exporter) is kept as fallback, so every previously-resolving graph still
+   * resolves.
+   */ resolveFactoryDependency(token, declaringModuleId) {
+        if (declaringModuleId !== ROOT_MODULE_ID && this.scopes.has(declaringModuleId)) {
+            try {
+                return this.resolve(token, declaringModuleId);
+            } catch  {
+            // Fall through to the legacy escape hatch below.
+            }
+        }
+        return this.resolve(token);
+    }
+    async resolveFactoryDependencyAsync(token, declaringModuleId) {
+        if (declaringModuleId !== ROOT_MODULE_ID && this.scopes.has(declaringModuleId)) {
+            try {
+                return await this.resolveAsync(token, declaringModuleId);
+            } catch  {
+            // Fall through to the legacy escape hatch below.
+            }
+        }
+        return this.resolveAsync(token);
+    }
     resolveFactory(registration) {
         if (!registration.useFactory) {
             throw new Error('Factory function is missing');
         }
-        // Factory inject deps resolve without a requester — Vela has no
-        // `forRootAsync({ imports })` surface to track which module the factory
-        // resolves from, so it uses the same escape-hatch shape as ModuleRef.
         const dependencies = (registration.inject || []).map((token)=>{
             const resolved = token instanceof ForwardRef ? token.factory() : token;
-            return this.resolve(resolved);
+            return this.resolveFactoryDependency(resolved, registration.declaringModuleId);
         });
         const result = registration.useFactory(...dependencies);
         if (result instanceof Promise) {
@@ -618,11 +674,11 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             if (scope === Scope.SINGLETON && registration.instance !== undefined) {
                 return registration.instance;
             }
-            // Factory inject deps resolve without a requester (same escape hatch as
-            // sync resolveFactory).
+            // Module scope first, legacy no-requester fallback — same policy as the
+            // sync resolveFactory path.
             const dependencies = await Promise.all((registration.inject || []).map((t)=>{
                 const resolved = t instanceof ForwardRef ? t.factory() : t;
-                return this.resolveAsync(resolved);
+                return this.resolveFactoryDependencyAsync(resolved, registration.declaringModuleId);
             }));
             const instance = await registration.useFactory(...dependencies);
             if (scope === Scope.SINGLETON) {

package/dist/container/disposable.js

@@ -1,4 +1,4 @@
-// Edge-safe disposal contract (mirrors stratal's). Precedence:
+// Edge-safe disposal contract. Precedence:
 //   Symbol.asyncDispose > Symbol.dispose > .dispose()
 // Symbol.asyncDispose/Symbol.dispose are resolved at runtime (they are not in
 // the ES2022 lib the project targets), so nothing here depends on the

package/dist/cors/cors.module.d.ts

@@ -1,7 +1,7 @@
-import type { DynamicModule } from '../module/types';
 import type { CorsOptions } from './cors.types';
-export declare class CorsModule {
-    static forRoot(options?: CorsOptions & {
-        key?: string;
-    }): DynamicModule;
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<CorsOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class CorsModule extends ConfigurableModuleClass {
 }
+export {};

package/dist/cors/cors.module.js

@@ -1,36 +1,37 @@
 import { cors } from "hono/cors";
-import { stableHash } from "../module/stable-hash.js";
+import { defineModule } from "../module/define-module.js";
 import { APP_MIDDLEWARE } from "../pipeline/tokens.js";
 import { CORS_OPTIONS } from "./cors.tokens.js";
-export class CorsModule {
-    static forRoot(options = {}) {
-        const corsMiddleware = cors({
-            origin: options.origin ?? '*',
-            allowMethods: options.allowMethods,
-            allowHeaders: options.allowHeaders,
-            exposeHeaders: options.exposeHeaders,
-            credentials: options.credentials,
-            maxAge: options.maxAge
-        });
-        const middleware = {
-            use: (c, next)=>corsMiddleware(c, next)
-        };
-        return {
-            module: CorsModule,
-            key: options.key ?? stableHash(options),
+function buildCorsMiddleware(options) {
+    const corsMiddleware = cors({
+        origin: options.origin ?? '*',
+        allowMethods: options.allowMethods,
+        allowHeaders: options.allowHeaders,
+        exposeHeaders: options.exposeHeaders,
+        credentials: options.credentials,
+        maxAge: options.maxAge
+    });
+    return {
+        use: (c, next)=>corsMiddleware(c, next)
+    };
+}
+const { ConfigurableModuleClass } = defineModule({
+    name: 'Cors',
+    optionsToken: CORS_OPTIONS,
+    setup: ({ OPTIONS })=>({
             providers: [
-                {
-                    provide: CORS_OPTIONS,
-                    useValue: options
-                },
                 {
                     provide: APP_MIDDLEWARE,
-                    useValue: middleware
+                    useFactory: (options)=>buildCorsMiddleware(options),
+                    inject: [
+                        OPTIONS
+                    ]
                 }
             ],
             exports: [
-                CORS_OPTIONS
+                OPTIONS
             ]
-        };
-    }
+        })
+});
+export class CorsModule extends ConfigurableModuleClass {
 }

package/dist/discovery/discoverable.decorator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A decorator whose annotated classes/methods are findable through
+ * `DiscoveryService` by the decorator itself (no string key at the call site).
+ */
+export interface DiscoverableDecorator<T> {
+    (value: T): ClassDecorator & MethodDecorator;
+    /** The metadata key backing this decorator — stable across HMR re-evals. */
+    KEY: string;
+}
+export interface CreateDiscoverableDecoratorOptions {
+    /**
+     * Append to a class-level list instead of overwriting a single slot —
+     * for stackable method decorators (`@Cron`-style: each application pushes
+     * `{ methodName, ...value }` onto the class's list, which
+     * `DiscoveryService.methodsWithMeta` flattens back to per-method entries).
+     */
+    append?: boolean;
+}
+/**
+ * Mint a discoverable decorator for a module's extension surface:
+ *
+ * ```ts
+ * export interface QueueConsumerMeta { queue: string }
+ * export const QueueConsumer = createDiscoverableDecorator<QueueConsumerMeta>('vela:queue:consumer');
+ *
+ * @QueueConsumer({ queue: 'emails' })
+ * @Injectable()
+ * class EmailConsumer { ... }
+ *
+ * // At bootstrap, anywhere:
+ * discovery.providersWithMeta(QueueConsumer)  // typed { meta: QueueConsumerMeta }
+ * ```
+ *
+ * Unlike `Reflector.createDecorator`, the key is required and caller-chosen:
+ * a random key would mint a fresh identity on every HMR re-eval and orphan
+ * previously-decorated classes. Namespace it (`'<pkg>:<area>:<thing>'`).
+ */
+export declare function createDiscoverableDecorator<T>(key: string, options?: CreateDiscoverableDecoratorOptions): DiscoverableDecorator<T>;

package/dist/discovery/discoverable.decorator.js

@@ -0,0 +1,42 @@
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+/**
+ * Mint a discoverable decorator for a module's extension surface:
+ *
+ * ```ts
+ * export interface QueueConsumerMeta { queue: string }
+ * export const QueueConsumer = createDiscoverableDecorator<QueueConsumerMeta>('vela:queue:consumer');
+ *
+ * @QueueConsumer({ queue: 'emails' })
+ * @Injectable()
+ * class EmailConsumer { ... }
+ *
+ * // At bootstrap, anywhere:
+ * discovery.providersWithMeta(QueueConsumer)  // typed { meta: QueueConsumerMeta }
+ * ```
+ *
+ * Unlike `Reflector.createDecorator`, the key is required and caller-chosen:
+ * a random key would mint a fresh identity on every HMR re-eval and orphan
+ * previously-decorated classes. Namespace it (`'<pkg>:<area>:<thing>'`).
+ */ export function createDiscoverableDecorator(key, options = {}) {
+    const decorator = (value)=>{
+        return (target, propertyKey)=>{
+            const ctor = propertyKey !== undefined ? target.constructor : target;
+            if (options.append) {
+                if (propertyKey !== undefined) {
+                    MetadataRegistry.appendCustomClassMeta(ctor, key, {
+                        methodName: propertyKey,
+                        ...value
+                    });
+                } else {
+                    MetadataRegistry.appendCustomClassMeta(ctor, key, value);
+                }
+            } else if (propertyKey !== undefined) {
+                MetadataRegistry.setCustomHandlerMeta(ctor, propertyKey, key, value);
+            } else {
+                MetadataRegistry.setCustomClassMeta(ctor, key, value);
+            }
+        };
+    };
+    decorator.KEY = key;
+    return decorator;
+}

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

@@ -0,0 +1,94 @@
+import { Scope } from '../constants';
+import { Container } from '../container/container';
+import type { Token, Type } from '../container/types';
+import type { Constructor } from '../registry/types';
+import type { DiscoverableDecorator } from './discoverable.decorator';
+/** A container-registered class provider surfaced by discovery. */
+export interface DiscoveredClass<T = unknown> {
+    token: Token;
+    metatype: Type<T>;
+    /** Module buckets holding this token (registration order; first = primary). */
+    moduleIds: string[];
+    scope: Scope;
+    /**
+     * Resolved instance. `undefined` only when the provider is request-scoped
+     * and `includeRequestScoped` was not set — request-scoped providers cannot
+     * be materialized at bootstrap without fabricating a phantom request.
+     */
+    instance: T | undefined;
+}
+export interface DiscoveredMethodMeta<M = unknown> {
+    class: DiscoveredClass;
+    methodName: string | symbol;
+    meta: M;
+}
+export interface DiscoveryFilter {
+    /** Restrict to providers declared by these module buckets. */
+    moduleId?: string | string[];
+    /**
+     * Resolve request-scoped providers too (constructs an instance outside any
+     * request — only for callers that know what they're doing). Default false:
+     * request-scoped hits are skipped with a diagnostics warning.
+     */
+    includeRequestScoped?: boolean;
+}
+/**
+ * Decorator-driven provider discovery — the public replacement for the
+ * bootstrap scan every subsystem used to hand-roll (`container.getTokens()` +
+ * `MetadataRegistry.getCustomClassMeta` + `resolve` + diagnostics handling).
+ *
+ * Registered globally by `bootstrap()`, so any provider can inject it:
+ *
+ * ```ts
+ * @Injectable()
+ * class MyRegistry implements OnApplicationBootstrap {
+ *   constructor(private readonly discovery: DiscoveryService) {}
+ *   onApplicationBootstrap() {
+ *     for (const { instance, meta } of this.discovery.providersWithMeta<MyMeta>(MY_KEY)) {
+ *       this.register(instance, meta);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Discovery is kernel-level, not encapsulation-scoped: module visibility
+ * protects modules from *each other*, never from the framework's own
+ * dispatchers. Use `DiscoveryFilter.moduleId` for the rare narrowing case.
+ *
+ * The resolve-failure policy honors the container's diagnostics mode exactly
+ * like the legacy loops: `throw` rethrows, `log` warns and skips, `silent`
+ * skips — so a broken provider never silently changes discovery semantics.
+ */
+export declare class DiscoveryService {
+    private readonly container;
+    constructor(container: Container);
+    /** Every class-token provider registered in the container. */
+    getProviders(filter?: DiscoveryFilter): DiscoveredClass[];
+    /**
+     * Providers whose class carries class-level metadata under `key` — both
+     * class decorators (single value) and method decorators that append
+     * class-level lists (`@Cron`, `@OnEvent`, `@SubscribeMessage`).
+     */
+    providersWithMeta<M>(key: string | DiscoverableDecorator<M>, filter?: DiscoveryFilter): Array<DiscoveredClass & {
+        meta: M;
+    }>;
+    /**
+     * Handler methods carrying metadata under `key`. Merges the two storage
+     * conventions:
+     *  - class-level appended lists whose items carry `methodName`
+     *    (`@Cron`/`@OnEvent`-style method decorators), and
+     *  - true handler-level metadata (`@SetMetadata`/`createDiscoverableDecorator`
+     *    applied to a method).
+     */
+    methodsWithMeta<M>(key: string | DiscoverableDecorator<M>, filter?: DiscoveryFilter): DiscoveredMethodMeta<M>[];
+    /**
+     * Index-first candidate walk with a legacy full-scan fallback: when the
+     * reverse index knows nothing about a key, an older copy of the registry
+     * module may have taken the writes (mixed dist/src or package versions in
+     * one process) — fall back to scanning container tokens the way the
+     * pre-DiscoveryService loops did.
+     */
+    private candidatesWithClassMeta;
+    private buildEntry;
+}
+export type { Constructor };