@bluelibs/runner 5.3.0 → 5.5.0

package/dist/types/serializer/types.d.ts

@@ -87,11 +87,12 @@ export interface SerializedGraph {
     root: SerializedValue;
     nodes: Record<string, SerializedNode>;
 }
-export declare enum SymbolPolicy {
-    AllowAll = "AllowAll",
-    WellKnownOnly = "WellKnownOnly",
-    Disabled = "Disabled"
-}
+export declare const SymbolPolicy: {
+    readonly AllowAll: "allow-all";
+    readonly WellKnownOnly: "well-known-only";
+    readonly Disabled: "disabled";
+};
+export type SymbolPolicy = (typeof SymbolPolicy)[keyof typeof SymbolPolicy];
 export declare enum SymbolPolicyErrorMessage {
     GlobalSymbolsNotAllowed = "Global symbols are not allowed",
     SymbolsNotAllowed = "Symbols are not allowed",
@@ -122,5 +123,5 @@ export interface SerializerOptions {
 export interface SerializerLike {
     stringify(value: unknown): string;
     parse<T = unknown>(text: string): T;
-    addType?<TJson = unknown, TInstance = unknown>(name: string, factory: (json: TJson) => TInstance): void;
+    addType?<TInstance, TSerialized>(typeDef: TypeDefinition<TInstance, TSerialized>): void;
 }

package/dist/types/testing.d.ts

@@ -12,6 +12,7 @@ export interface TestFacade {
  * Helper to create a minimal test harness resource that wraps a root app (or any registerable)
  * and exposes convenient testing utilities while running the full ecosystem
  * (registration, overrides, middleware, events) without modifying the core API.
+ * @deprecated Use run() in your tests instead, which provides the same benefits with a more flexible API and better type safety.
  */
 export declare function createTestResource(root: RegisterableItems, options?: {
     overrides?: Array<IResource | ITask | ITaskMiddleware | IResourceMiddleware | IResourceWithConfig>;

package/dist/types/tools/LockableMap.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A Map that can be permanently locked to prevent further mutations.
+ *
+ * Before locking it behaves exactly like a regular `Map`.
+ * After `lock()` is called, any call to `set`, `delete` or `clear`
+ * throws immediately — enforcing immutability at the data-structure level.
+ */
+export declare class LockableMap<K, V> extends Map<K, V> {
+    #private;
+    constructor(name?: string);
+    /** Whether the map is currently locked. */
+    get locked(): boolean;
+    /** Permanently lock the map — no further mutations allowed. */
+    lock(): void;
+    /** @throws if the map is locked */
+    private throwIfLocked;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+}

package/dist/types/tools/getAllThrows.d.ts

@@ -0,0 +1,13 @@
+import type { ITask } from "../types/task";
+import type { IResource } from "../types/resource";
+import type { StoreRegistry } from "../models/StoreRegistry";
+/**
+ * Collects all declared error ids from a task or resource definition and its
+ * entire dependency chain: own throws, middleware throws (local + everywhere),
+ * resource dependency throws (with their middleware), and — for tasks — hook
+ * throws on events the task can emit.
+ *
+ * Designed for introspection, documentation, and error-contract tooling.
+ * Returns a deduplicated list of normalized error id strings.
+ */
+export declare function getAllThrows(registry: StoreRegistry, target: ITask<any, any, any, any, any, any> | IResource<any, any, any, any>): readonly string[];

package/dist/types/tools/throws.d.ts

@@ -1,6 +1,6 @@
 import type { ThrowsList } from "../types/error";
 type ThrowOwner = {
-    kind: "task" | "resource";
+    kind: "task" | "resource" | "hook" | "task-middleware" | "resource-middleware";
     id: string;
 };
 export declare function normalizeThrows(owner: ThrowOwner, throwsList: ThrowsList | undefined): readonly string[] | undefined;

package/dist/types/types/error.d.ts

@@ -2,6 +2,7 @@ import { symbolError, symbolFilePath } from "./symbols";
 import type { IOptionalDependency } from "./utilities";
 import type { IValidationSchema } from "./utilities";
 import type { IErrorMeta } from "./meta";
+import type { TagType } from "./tag";
 export type ErrorReference = string | IErrorHelper<any>;
 export type ThrowsList = ReadonlyArray<ErrorReference>;
 export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorType> {
@@ -21,6 +22,7 @@ export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorT
      */
     dataSchema?: IValidationSchema<TData>;
     meta?: IErrorMeta;
+    tags?: TagType[];
 }
 export interface IErrorDefinitionFinal<TData extends DefaultErrorType> extends IErrorDefinition<TData> {
     format: (data: TData) => string;
@@ -28,6 +30,10 @@ export interface IErrorDefinitionFinal<TData extends DefaultErrorType> extends I
     remediation?: string | ((data: TData) => string);
 }
 export type DefaultErrorType = Record<string, unknown>;
+type RequiredKeys<T extends object> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+export type ErrorThrowArgs<TData extends DefaultErrorType> = RequiredKeys<TData> extends never ? [data?: TData] : [data: TData];
 /**
  * Runtime error shape thrown by r.error()/defineError() helpers.
  * Consumers can use helper.is(error) to narrow unknown values to this type.
@@ -47,10 +53,26 @@ export interface IErrorHelper<TData extends DefaultErrorType = DefaultErrorType>
     id: string;
     /** Optional HTTP status code associated with this error helper */
     httpCode?: number;
+    /** Metadata attached to this error */
+    meta: IErrorMeta;
+    /** Tags attached to this error */
+    tags: TagType[];
+    /** Construct a typed error with the given data without throwing it */
+    "new"(...args: ErrorThrowArgs<TData>): IRunnerError<TData>;
+    /** Alias for .new() */
+    create(...args: ErrorThrowArgs<TData>): IRunnerError<TData>;
     /** Throw a typed error with the given data */
-    throw(data: TData): never;
-    /** Type guard for checking if an unknown error is this error */
+    throw(...args: ErrorThrowArgs<TData>): never;
+    /**
+     * Type guard for checking if an unknown error is this error.
+     * Optionally provide a partial data object to require shallow strict matches.
+     */
     is(error: unknown): error is IRunnerError<TData>;
+    /**
+     * Type guard for checking if an unknown error is this error,
+     * with shallow strict matching (`===`) on provided data keys.
+     */
+    is(error: unknown, partialData: Partial<TData>): error is IRunnerError<TData>;
     /** Brand symbol for runtime detection */
     [symbolError]: true;
     /** Return an optional dependency wrapper for this error */
@@ -58,3 +80,4 @@ export interface IErrorHelper<TData extends DefaultErrorType = DefaultErrorType>
     /** File path where this error was defined */
     [symbolFilePath]: string;
 }
+export {};

package/dist/types/types/event.d.ts

@@ -3,6 +3,41 @@ import { TagType } from "./tag";
 import { IEventMeta } from "./meta";
 import { CommonPayload, symbolEvent, symbolFilePath } from "./utilities";
 export type EventHandlerType<T = any> = (event: IEventEmission<T>) => any | Promise<any>;
+export declare const EventEmissionFailureMode: {
+    readonly FailFast: "fail-fast";
+    readonly Aggregate: "aggregate";
+};
+export type EventEmissionFailureMode = (typeof EventEmissionFailureMode)[keyof typeof EventEmissionFailureMode];
+export interface IEventListenerError extends Error {
+    listenerId?: string;
+    listenerOrder?: number;
+}
+export interface IEventEmitReport {
+    totalListeners: number;
+    attemptedListeners: number;
+    skippedListeners: number;
+    succeededListeners: number;
+    failedListeners: number;
+    propagationStopped: boolean;
+    errors: IEventListenerError[];
+}
+export interface IEventEmitOptions {
+    /**
+     * Controls error behavior during listener execution.
+     * - fail-fast (default): throw on first failure.
+     * - aggregate: continue execution and collect listener errors.
+     */
+    failureMode?: EventEmissionFailureMode;
+    /**
+     * When false, suppress throwing even if listener errors occurred.
+     * Defaults to true.
+     */
+    throwOnError?: boolean;
+    /**
+     * When true, `emit(...)`/dependency event emitter returns `IEventEmitReport`.
+     */
+    report?: boolean;
+}
 export declare function onAnyOf<T extends readonly IEventDefinition<any>[]>(...defs: T): T;
 /**
  * Runtime guard that checks if an emission belongs to one of the given event defs.

package/dist/types/types/hook.d.ts

@@ -2,6 +2,7 @@ import { DependencyMapType, DependencyValuesType, ExtractEventPayload } from "./
 import { IEventDefinition, IEventEmission } from "./event";
 import { TagType } from "./tag";
 import { ITaskMeta } from "./meta";
+import type { ThrowsList } from "./error";
 import { CommonPayload, symbolFilePath, symbolHook } from "./utilities";
 export type OnType = "*" | IEventDefinition<any> | readonly IEventDefinition<any>[];
 export interface IHookDefinition<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> {
@@ -11,6 +12,11 @@ export interface IHookDefinition<TDependencies extends DependencyMapType = {}, T
     /** Listener execution order. Lower numbers run first. */
     order?: number;
     meta?: TMeta;
+    /**
+     * Declares which typed errors are part of this hook's contract.
+     * Declarative only — does not imply DI or enforcement.
+     */
+    throws?: ThrowsList;
     run: (event: IEventEmission<TOn extends "*" ? any : TOn extends readonly IEventDefinition<any>[] ? CommonPayload<TOn> : ExtractEventPayload<TOn>>, dependencies: DependencyValuesType<TDependencies>) => Promise<any>;
     tags?: TagType[];
 }
@@ -19,5 +25,7 @@ export interface IHook<TDependencies extends DependencyMapType = {}, TOn extends
     dependencies: TDependencies | (() => TDependencies);
     [symbolFilePath]: string;
     [symbolHook]: true;
+    /** Normalized list of error ids declared via `throws`. */
+    throws?: readonly string[];
     tags: TagType[];
 }

package/dist/types/types/resource.d.ts

@@ -58,7 +58,7 @@ export interface IResourceDefinition<TConfig = any, TValue extends Promise<any>
      * @param dependencies The dependencies it needed
      * @returns Promise<void>
      */
-    dispose?: (this: any, value: TValue extends Promise<infer U> ? U : TValue, config: TConfig, dependencies: ResourceDependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
+    dispose?: (this: unknown, value: TValue extends Promise<infer U> ? U : TValue, config: TConfig, dependencies: ResourceDependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
     meta?: TMeta;
     /**
      * Declares which typed errors are part of this resource's contract.
@@ -86,6 +86,13 @@ export interface IResourceDefinition<TConfig = any, TValue extends Promise<any>
      * Create a private, mutable context shared between `init` and `dispose`.
      */
     context?: () => TContext;
+    /**
+     * Declares which registered items are visible outside this resource's
+     * registration subtree. When present, only listed items (and items registered
+     * by child resources that also export them) are accessible from outside.
+     * Omitting `exports` means everything is public (default).
+     */
+    exports?: Array<RegisterableItems>;
     /**
      * This is optional and used from an index resource to get the correct caller.
      * This is the reason we allow it here as well.
@@ -110,6 +117,11 @@ export interface IResource<TConfig = void, TValue extends Promise<any> = Promise
     [symbolForkedFrom]?: ResourceForkInfo;
     /** Normalized list of error ids declared via `throws`. */
     throws?: readonly string[];
+    /**
+     * Items visible outside this resource's subtree. When set, only listed items
+     * can be referenced from outside.
+     */
+    exports?: Array<RegisterableItems>;
     /** Return an optional dependency wrapper for this resource. */
     optional: () => IOptionalDependency<IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>>;
     tags: TTags;

package/dist/types/types/resourceMiddleware.d.ts

@@ -4,6 +4,7 @@ import { TagType } from "./tag";
 import { IMiddlewareMeta } from "./meta";
 import { symbolFilePath, symbolMiddlewareConfigured, symbolResourceMiddleware } from "./symbols";
 import { IContractable } from "./contracts";
+import type { ThrowsList } from "./error";
 export interface IResourceMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> {
     id: string;
     /** Static or lazy dependency map. */
@@ -19,12 +20,19 @@ export interface IResourceMiddlewareDefinition<TConfig = any, TEnforceInputContr
     run: (input: IResourceMiddlewareExecutionInput<TEnforceInputContract extends void ? any : TEnforceInputContract, TEnforceOutputContract extends void ? any : TEnforceOutputContract>, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
     meta?: IMiddlewareMeta;
     tags?: TagType[];
+    /**
+     * Declares which typed errors are part of this middleware's contract.
+     * Declarative only — does not imply DI or enforcement.
+     */
+    throws?: ThrowsList;
     everywhere?: boolean | ((resource: IResource<any, any, any, any, any>) => boolean);
 }
 export interface IResourceMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends IResourceMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
     [symbolResourceMiddleware]: true;
     id: string;
     dependencies: TDependencies | ((config: TConfig) => TDependencies);
+    /** Normalized list of error ids declared via `throws`. */
+    throws?: readonly string[];
     /** Current configuration object (empty by default). */
     config: TConfig;
     /** Configure the middleware and return a marked, configured instance. */

package/dist/types/types/runner.d.ts

@@ -1,6 +1,44 @@
 import { DebugFriendlyConfig } from "../globals/resources/debug";
 import { LogLevels, PrintStrategy } from "../models/Logger";
 import { OnUnhandledError } from "../models/UnhandledError";
+import { IEvent, IEventEmitOptions, IEventEmitReport } from "../defs";
+import { IResource } from "./resource";
+import { ITask } from "./task";
+import { TaskCallOptions } from "./utilities";
+/**
+ * Common interface for the Runner runtime instance.
+ * Provides access to tasks, events, resources, and lifecycle management.
+ */
+export interface IRuntime<V = unknown> {
+    /**
+     * Executes a registered task.
+     */
+    runTask<TTask extends ITask<any, Promise<any>, any> | string>(task: TTask, ...args: TTask extends ITask<infer I, any, any> ? I extends undefined | void ? [input?: I, options?: TaskCallOptions] : [input: I, options?: TaskCallOptions] : [input?: unknown, options?: TaskCallOptions]): TTask extends ITask<any, infer O, any> ? O : Promise<any>;
+    /**
+     * Emits an event to trigger hooks.
+     */
+    emitEvent<P>(event: IEvent<P> | string, payload?: P extends undefined | void ? undefined : P, options?: IEventEmitOptions): Promise<void | IEventEmitReport>;
+    /**
+     * Synchronously retrieves an initialized resource value.
+     */
+    getResourceValue<Output extends Promise<any>>(resource: string | IResource<any, Output, any, any, any>): Output extends Promise<infer U> ? U : Output;
+    /**
+     * Initializes and returns a resource value on-demand (lazy mode only).
+     */
+    getLazyResourceValue<Output extends Promise<any>>(resource: string | IResource<any, Output, any, any, any>): Promise<Output extends Promise<infer U> ? U : Output>;
+    /**
+     * Retrieves the configuration passed to a resource.
+     */
+    getResourceConfig<Config>(resource: string | IResource<Config, any, any, any, any>): Config;
+    /** Returns the ID of the root resource. */
+    getRootId(): string;
+    /** Returns the configuration passed to the root resource. */
+    getRootConfig<Config = unknown>(): Config;
+    /** Returns the initialized value of the root resource. */
+    getRootValue<Value = V>(): Value;
+    /** Disposes the runtime and all resources. */
+    dispose(): Promise<void>;
+}
 export type RunOptions = {
     /**
      * Defaults to undefined. If true, we introduce logging to the console.
@@ -52,6 +90,17 @@ export type RunOptions = {
      * you don't have event deadlocks to improve event emission performance.
      */
     runtimeEventCycleDetection?: boolean;
+    /**
+     * Defaults to false.
+     * When true, startup skips initializing resources that are not used during bootstrap.
+     * Such resources can be initialized on-demand via `runResult.getLazyResourceValue(...)`.
+     */
+    lazy?: boolean;
+    /**
+     * Defaults to `sequential`.
+     * Controls how resources are initialized during startup.
+     */
+    initMode?: ResourceInitMode | "sequential" | "parallel";
     /**
      * Specify in which mode to run "dev", "prod" or "test".
      * If inside Node this is automatically detected from the NODE_ENV environment variable if not provided.
@@ -66,3 +115,10 @@ export declare enum RunnerMode {
     DEV = "dev",
     PROD = "prod"
 }
+/**
+ * Resource initialization strategy during run() bootstrap.
+ */
+export declare enum ResourceInitMode {
+    Sequential = "sequential",
+    Parallel = "parallel"
+}

package/dist/types/types/storeTypes.d.ts

@@ -24,7 +24,11 @@ export type TaskStoreElementType<Input = any, Output extends Promise<any> = any,
     task: ITask<Input, Output, D>;
     computedDependencies: DependencyValuesType<D>;
     isInitialized: boolean;
-    interceptors?: Array<TaskLocalInterceptor<any, any>>;
+    interceptors?: Array<TaskLocalInterceptorRecord<any, any>>;
+};
+export type TaskLocalInterceptorRecord<TInput = any, TOutput = any> = {
+    interceptor: TaskLocalInterceptor<TInput, TOutput>;
+    ownerResourceId?: string;
 };
 export type HookStoreElementType<D extends DependencyMapType = any, TOn extends "*" | IEventDefinition = any> = {
     hook: IHook<D, TOn>;

package/dist/types/types/symbols.d.ts

@@ -5,7 +5,7 @@
  * @internal
  */
 export declare const symbolTask: unique symbol;
-/** Marks a task as a phantom task (no-op run; meant to be tunneled/routed). */
+/** Marks a task as a phantom task (throws when unrouted; meant to be tunneled/routed). */
 export declare const symbolPhantomTask: unique symbol;
 export declare const symbolResource: unique symbol;
 /** @internal Generic fork provenance metadata for definitions that support `.fork()` */

package/dist/types/types/tag.d.ts

@@ -20,6 +20,7 @@ export interface ITag<TConfig = void, TEnforceInputContract = void, TEnforceOutp
      */
     readonly __configHasOnlyOptionalKeys: RequiredKeys<TConfig> extends never ? true : false;
     config?: TConfig;
+    meta: ITagMeta;
     /**
      * Checks if the tag exists in a taggable or a list of tags.
      */

package/dist/types/types/tagged.d.ts

@@ -2,8 +2,8 @@ import type { HasInputContracts, HasOutputContracts, InferInputOrViolationFromCo
 import type { IResource } from "./resource";
 import type { ITask } from "./task";
 import type { ITag } from "./tag";
-type TagInputContract<TTag extends ITag<any, any, any>> = HasInputContracts<[TTag]> extends true ? InferInputOrViolationFromContracts<[TTag]> : any;
-type TagOutputContract<TTag extends ITag<any, any, any>> = HasOutputContracts<[TTag]> extends true ? InferOutputOrViolationFromContracts<[TTag]> : any;
+type TagInputContract<TTag extends ITag<any, any, any>> = HasInputContracts<[TTag]> extends true ? InferInputOrViolationFromContracts<[TTag]> : unknown;
+type TagOutputContract<TTag extends ITag<any, any, any>> = HasOutputContracts<[TTag]> extends true ? InferOutputOrViolationFromContracts<[TTag]> : unknown;
 export type AnyResource = IResource<any, any, any, any, any, any, any>;
 /**
  * A task discovered by a concrete tag. If the tag carries contracts,

package/dist/types/types/task.d.ts

@@ -10,7 +10,7 @@ export type { DependencyMapType, DependencyValuesType, IOptionalDependency, } fr
 export type { TaskMiddlewareAttachmentType } from "./taskMiddleware";
 export type { TagType } from "./tag";
 export type { ITaskMeta } from "./meta";
-export interface ITaskDefinition<TInput = undefined, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> {
+export interface ITaskDefinition<TInput = undefined, TOutput extends Promise<unknown> = Promise<unknown>, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> {
     id: string;
     /**
      * Access other tasks/resources/events. Can be an object or a function when
@@ -50,7 +50,7 @@ export interface ITaskDefinition<TInput = undefined, TOutput extends Promise<any
      */
     tags?: TTags;
 }
-export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> extends ITaskDefinition<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware> {
+export interface ITask<TInput = any, TOutput extends Promise<unknown> = Promise<unknown>, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> extends ITaskDefinition<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware> {
     [symbolFilePath]: string;
     [symbolTask]: true;
     /** Present only for phantom tasks. */
@@ -70,7 +70,7 @@ export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDepend
     tags: TTags;
 }
 export type AnyTask = ITask<any, any, any, any, any, any>;
-/** Narrowed type for phantom tasks (no-op run by default). */
+/** Narrowed type for phantom tasks (throws unless routed through a tunnel). */
 export type IPhantomTask<TInput = any, TResolved = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> = ITask<TInput, Promise<TResolved>, TDependencies, TMeta, TTags, TMiddleware> & {
     [symbolPhantomTask]: true;
 };

package/dist/types/types/taskMiddleware.d.ts

@@ -5,6 +5,7 @@ import { TagType } from "./tag";
 import { IMiddlewareMeta } from "./meta";
 import { symbolFilePath, symbolMiddlewareConfigured, symbolTaskMiddleware } from "./symbols";
 import { IContractable } from "./contracts";
+import type { ThrowsList } from "./error";
 export type { DependencyMapType, DependencyValuesType } from "./utilities";
 export type { TagType } from "./tag";
 export type { IMiddlewareMeta } from "./meta";
@@ -23,6 +24,11 @@ export interface ITaskMiddlewareDefinition<TConfig = any, TEnforceInputContract
     run: (input: ITaskMiddlewareExecutionInput<TEnforceInputContract extends void ? any : TEnforceInputContract, TEnforceOutputContract extends void ? any : TEnforceOutputContract>, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
     meta?: IMiddlewareMeta;
     tags?: TagType[];
+    /**
+     * Declares which typed errors are part of this middleware's contract.
+     * Declarative only — does not imply DI or enforcement.
+     */
+    throws?: ThrowsList;
     everywhere?: boolean | ((task: ITask<any, any, any, any>) => boolean);
 }
 export interface ITaskMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends ITaskMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
@@ -30,6 +36,8 @@ export interface ITaskMiddleware<TConfig = any, TEnforceInputContract = void, TE
     [symbolFilePath]: string;
     id: string;
     dependencies: TDependencies | ((config: TConfig) => TDependencies);
+    /** Normalized list of error ids declared via `throws`. */
+    throws?: readonly string[];
     /** Current configuration object (empty by default). */
     config: TConfig;
     /** Configure the middleware and return a marked, configured instance. */

package/dist/types/types/utilities.d.ts

@@ -3,7 +3,7 @@ import { ITask } from "./task";
 import { ITaskMiddleware } from "./taskMiddleware";
 import { IResourceMiddleware } from "./resourceMiddleware";
 import { IHook } from "./hook";
-import { IEvent, IEventDefinition } from "./event";
+import { IEvent, IEventDefinition, IEventEmitOptions, IEventEmitReport } from "./event";
 import { ITag } from "./tag";
 import { symbolOptionalDependency } from "./symbols";
 import { IErrorHelper } from "./error";
@@ -14,7 +14,7 @@ export * from "./symbols";
  * Generic validation schema interface that can be implemented by any validation library.
  * Compatible with Zod, Yup, Joi, and other validation libraries.
  */
-export interface IValidationSchema<T = any> {
+export interface IValidationSchema<T = unknown> {
     /**
      * Parse and validate the input data.
      * Should throw an error if validation fails.
@@ -93,7 +93,28 @@ export type ResourceDependency<V> = V;
  * Event dependencies resolve to an emitter function. If the payload type is
  * `void`, the function can be called with zero args (or an empty object).
  */
-export type EventDependency<P> = P extends void ? (() => Promise<void>) & ((input?: Record<string, never>) => Promise<void>) : (input: P) => Promise<void>;
+type EventEmitVoidDependency = {
+    (): Promise<void>;
+    (input?: Record<string, never>): Promise<void>;
+    (input: Record<string, never> | undefined, options: IEventEmitOptions & {
+        report: true;
+    }): Promise<IEventEmitReport>;
+    (input: Record<string, never> | undefined, options?: IEventEmitOptions & {
+        report?: false | undefined;
+    }): Promise<void>;
+    (input: Record<string, never> | undefined, options?: IEventEmitOptions): Promise<void | IEventEmitReport>;
+};
+type EventEmitPayloadDependency<P> = {
+    (input: P): Promise<void>;
+    (input: P, options: IEventEmitOptions & {
+        report: true;
+    }): Promise<IEventEmitReport>;
+    (input: P, options?: IEventEmitOptions & {
+        report?: false | undefined;
+    }): Promise<void>;
+    (input: P, options?: IEventEmitOptions): Promise<void | IEventEmitReport>;
+};
+export type EventDependency<P> = P extends void ? EventEmitVoidDependency : EventEmitPayloadDependency<P>;
 /**
  * Transforms a dependency definition into the usable shape inside `run`/`init`:
  * - Task -> callable function
@@ -107,6 +128,7 @@ export type DependencyValuesType<T extends DependencyMapType> = {
 export type TaskLocalInterceptor<TInput, TOutput> = (next: (input: TInput) => TOutput, input: TInput) => TOutput;
 export type TaskDependencyWithIntercept<TInput, TOutput> = TaskDependency<TInput, TOutput> & {
     intercept: (middleware: TaskLocalInterceptor<TInput, TOutput>) => void;
+    getInterceptingResourceIds: () => readonly string[];
 };
 /** Resource-context dependency typing where tasks expose intercept() */
 export type ResourceDependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependencyWithIntercept<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IErrorHelper<any> ? T : T extends IAsyncContext<any> ? T : T extends IEventDefinition<any> ? EventDependency<ExtractEventPayload<T>> : T extends IOptionalDependency<infer U> ? ResourceDependencyValueType<U> | undefined : never;