@bluelibs/runner 4.5.0-alpha → 4.5.0-alpha.2

package/dist/index.d.mts

@@ -0,0 +1,1734 @@
+declare const CONTRACT: unique symbol;
+type CONTRACT = typeof CONTRACT;
+interface IContractable<TConfig = any, TInput = void, TOutput = void> {
+    readonly __containsContract: true;
+    readonly [CONTRACT]: {
+        config: TConfig;
+        input: TInput;
+        output: TOutput;
+    };
+}
+type NonVoid<T> = [T] extends [void] ? never : T;
+type IsTuple<T extends readonly unknown[]> = number extends T["length"] ? false : true;
+type UnionToIntersection$1<U> = (U extends any ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type IsUnknown<T> = unknown extends T ? [T] extends [unknown] ? true : false : false;
+type UnknownToNever<T> = IsUnknown<T> extends true ? never : T;
+type ExtractContractOf<T, Kind extends "input" | "output"> = T extends IContractable<any, infer I, infer O> ? UnknownToNever<Kind extends "input" ? NonVoid<I> : NonVoid<O>> : never;
+type FilterContractsKind<TItems extends readonly unknown[], Kind extends "input" | "output", Acc extends readonly unknown[] = []> = TItems extends readonly [infer H, ...infer R] ? ExtractContractOf<H, Kind> extends never ? FilterContractsKind<R, Kind, Acc> : FilterContractsKind<R, Kind, [...Acc, ExtractContractOf<H, Kind>]> : Acc;
+type ExtractContractsFromCollection<TItems extends readonly unknown[], Kind extends "input" | "output"> = IsTuple<TItems> extends true ? FilterContractsKind<TItems, Kind> : Array<ExtractContractOf<TItems[number], Kind>>;
+type ExtractInputTypeFromContracts<TItems extends readonly unknown[]> = ExtractContractsFromCollection<TItems, "input">;
+type ExtractOutputTypeFromContracts<TItems extends readonly unknown[]> = ExtractContractsFromCollection<TItems, "output">;
+type ContractsUnionInputs<TItems extends readonly unknown[]> = ExtractInputTypeFromContracts<TItems> extends readonly (infer U)[] ? U : never;
+type ContractsUnionOutputs<TItems extends readonly unknown[]> = ExtractOutputTypeFromContracts<TItems> extends readonly (infer U)[] ? U : never;
+type ContractsIntersectionInputs<TItems extends readonly unknown[]> = UnionToIntersection$1<ContractsUnionInputs<TItems>>;
+type ContractsIntersectionOutputs<TItems extends readonly unknown[]> = UnionToIntersection$1<ContractsUnionOutputs<TItems>>;
+type HasInputContracts<TItems extends readonly unknown[]> = [
+    ContractsUnionInputs<TItems>
+] extends [never] ? false : true;
+type HasOutputContracts<TItems extends readonly unknown[]> = [
+    ContractsUnionOutputs<TItems>
+] extends [never] ? false : true;
+type InputContractViolationError<TItems extends readonly unknown[], TActual> = {
+    message: "Value does not satisfy all input contracts";
+    expected: Simplify<ContractsIntersectionInputs<TItems>>;
+    received: TActual;
+};
+type OutputContractViolationError<TItems extends readonly unknown[], TActual> = {
+    message: "Value does not satisfy all output contracts";
+    expected: Simplify<ContractsIntersectionOutputs<TItems>>;
+    received: TActual;
+};
+type EnsureInputSatisfiesContracts<TItems extends readonly unknown[], TValue> = [ContractsUnionInputs<TItems>] extends [never] ? TValue : TValue extends Promise<infer U> ? Promise<U extends ContractsIntersectionInputs<TItems> ? U : InputContractViolationError<TItems, U>> : TValue extends ContractsIntersectionInputs<TItems> ? TValue : InputContractViolationError<TItems, TValue>;
+type EnsureOutputSatisfiesContracts<TItems extends readonly unknown[], TResponse> = [ContractsUnionOutputs<TItems>] extends [never] ? TResponse : TResponse extends Promise<infer U> ? Promise<U extends ContractsIntersectionOutputs<TItems> ? U : OutputContractViolationError<TItems, U>> : TResponse extends ContractsIntersectionOutputs<TItems> ? TResponse : OutputContractViolationError<TItems, TResponse>;
+
+/**
+ * Common metadata you can attach to tasks/resources/events/middleware.
+ * Useful for docs, filtering and middleware decisions.
+ */
+interface IMeta {
+    title?: string;
+    description?: string;
+}
+interface ITaskMeta extends IMeta {
+}
+interface IResourceMeta extends IMeta {
+}
+interface IEventMeta extends IMeta {
+}
+interface IMiddlewareMeta extends IMeta {
+}
+interface ITagMeta extends IMeta {
+}
+
+interface ITaggable {
+    tags: TagType[];
+}
+interface ITagDefinition<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> {
+    id: string;
+    meta?: ITagMeta;
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * Utilizing config at definition level stores its defaults
+     */
+    config?: TConfig;
+}
+interface ITag<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> extends ITagDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    /**
+     * A special validation property.
+     * It resolves to `true` if TConfig only has optional keys, otherwise `false`.
+     */
+    readonly __configHasOnlyOptionalKeys: RequiredKeys<TConfig> extends never ? true : false;
+    config?: TConfig;
+    /**
+     * Checks if the tag exists in a taggable or a list of tags.
+     */
+    exists(target: ITaggable | TagType[]): boolean;
+    /**
+     * Creates a configured instance of the tag.
+     */
+    with(config: TConfig): ITagConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract>;
+    /**
+     * Extracts the configuration of the tag from a taggable or a list of tags.
+     */
+    extract(target: ITaggable | TagType[]): TConfig | undefined;
+    [symbolFilePath]: string;
+    [symbolTag]: true;
+}
+type ITagWithOptionalConfig<TValue, TEnforceInputContract, TEnforceOutputContract> = ITag<any, TEnforceInputContract, TEnforceOutputContract> & {
+    readonly __configHasOnlyOptionalKeys: true;
+};
+interface ITagConfigured<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> extends ITag<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    [symbolTagConfigured]: true;
+    config: TConfig;
+}
+type TagType = ITag<void, any, any> | ITagWithOptionalConfig<any, any, any> | ITagConfigured<any, any, any>;
+
+/**
+ * Internal brand symbols used to tag created objects at runtime and help with
+ * type‑narrowing. Prefer the `isTask`/`isResource`/`isEvent`/`isMiddleware`
+ * helpers instead of touching these directly.
+ * @internal
+ */
+declare const symbolTask: unique symbol;
+declare const symbolResource: unique symbol;
+declare const symbolResourceWithConfig: unique symbol;
+declare const symbolEvent: unique symbol;
+declare const symbolMiddleware: unique symbol;
+/** New brands for separated middleware kinds */
+declare const symbolTaskMiddleware: unique symbol;
+declare const symbolResourceMiddleware: unique symbol;
+declare const symbolMiddlewareConfigured: unique symbol;
+/** @internal Marks hook definitions (event listeners without middleware) */
+declare const symbolHook: unique symbol;
+/** @internal Marks a tag definition */
+declare const symbolTag: unique symbol;
+declare const symbolTagConfigured: unique symbol;
+/** @internal Marks an optional dependency wrapper */
+declare const symbolOptionalDependency: unique symbol;
+/** @internal Path to aid anonymous id generation and error messages */
+declare const symbolFilePath: unique symbol;
+/** @internal Marks disposable instances */
+declare const symbolDispose: unique symbol;
+/** @internal Link to internal Store */
+declare const symbolStore: unique symbol;
+/** @internal Brand used by index() resources */
+declare const symbolIndexResource: unique symbol;
+
+interface IResourceDefinition<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = {}, TContext = any, THooks = any, TRegisterableItems = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]> {
+    /** Stable identifier. */
+    id: string;
+    /** Static or lazy dependency map. Receives `config` when provided. */
+    dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * Register other registerables (resources/tasks/middleware/events). Accepts a
+     * static array or a function of `config` to support dynamic wiring.
+     */
+    register?: Array<RegisterableItems> | ((config: TConfig) => Array<RegisterableItems>);
+    /**
+     * Initialize and return the resource value. Called once during boot.
+     */
+    init?: (config: HasInputContracts<[...TTags, ...TMiddleware]> extends true ? EnsureInputSatisfiesContracts<[...TTags, ...TMiddleware], TConfig> : TConfig, dependencies: ResourceDependencyValuesType<TDependencies>, context: TContext) => HasOutputContracts<[...TTags, ...TMiddleware]> extends true ? EnsureOutputSatisfiesContracts<[...TTags, ...TMiddleware], TValue> : TValue;
+    /**
+     * Optional validation schema for the resource's resolved value.
+     * When provided, the value will be validated immediately after `init` resolves,
+     * without considering middleware.
+     */
+    resultSchema?: IValidationSchema<TValue extends Promise<infer U> ? U : TValue>;
+    /**
+     * Clean-up function for the resource. This is called when the resource is no longer needed.
+     *
+     * @param value The value of the resource (undefined if no init method)
+     * @param config The configuration it received
+     * @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>;
+    meta?: TMeta;
+    /**
+     * Optional validation schema for runtime config validation.
+     * When provided, resource config will be validated when .with() is called.
+     */
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * Safe overrides to swap behavior while preserving identities. See
+     * README: Overrides.
+     */
+    overrides?: Array<OverridableElements>;
+    /** Middleware applied around init/dispose. */
+    middleware?: TMiddleware;
+    /**
+     * Create a private, mutable context shared between `init` and `dispose`.
+     */
+    context?: () => TContext;
+    /**
+     * This is optional and used from an index resource to get the correct caller.
+     * This is the reason we allow it here as well.
+     */
+    [symbolFilePath]?: string;
+    /**
+     * This is used internally when creating index resources.
+     */
+    [symbolIndexResource]?: boolean;
+    tags?: TTags;
+}
+interface IResource<TConfig = void, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, TContext = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]> extends IResourceDefinition<TConfig, TValue, TDependencies, TContext, any, any, TMeta, TTags, TMiddleware> {
+    id: string;
+    with(config: TConfig): IResourceWithConfig<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+    register: Array<RegisterableItems> | ((config: TConfig) => Array<RegisterableItems>);
+    overrides: Array<OverridableElements>;
+    middleware: TMiddleware;
+    [symbolFilePath]: string;
+    [symbolIndexResource]: boolean;
+    [symbolResource]: true;
+    /** Return an optional dependency wrapper for this resource. */
+    optional: () => IOptionalDependency<IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>>;
+    tags: TTags;
+}
+interface IResourceWithConfig<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, TContext = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends IResourceMiddleware<any, any, any, any>[] = IResourceMiddleware[]> {
+    [symbolResourceWithConfig]: true;
+    /** The id of the underlying resource. */
+    id: string;
+    /** The underlying resource definition. */
+    resource: IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+    /** The configuration captured by `.with(config)`. */
+    config: TConfig;
+}
+
+interface ITaskDefinition<TInput = undefined, TOutput extends Promise<any> = any, 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
+     * you need late or config‑dependent resolution.
+     */
+    dependencies?: TDependencies | (() => TDependencies);
+    /** Middleware applied around task execution. */
+    middleware?: TMiddleware;
+    /** Optional metadata used for docs, filtering and tooling. */
+    meta?: TMeta;
+    /**
+     * Optional validation schema for runtime input validation.
+     * When provided, task input will be validated before execution.
+     */
+    inputSchema?: IValidationSchema<TInput>;
+    /**
+     * Optional validation schema for the task result.
+     * When provided, the result will be validated immediately after the task's
+     * `run` resolves, without considering middleware.
+     */
+    resultSchema?: IValidationSchema<TOutput extends Promise<infer U> ? U : never>;
+    run: (input: HasInputContracts<[...TTags, ...TMiddleware]> extends true ? EnsureInputSatisfiesContracts<[...TTags, ...TMiddleware], TInput> : TInput, dependencies: DependencyValuesType<TDependencies>) => HasOutputContracts<[...TTags, ...TMiddleware]> extends true ? EnsureOutputSatisfiesContracts<[...TTags, ...TMiddleware], TOutput> : TOutput;
+    /**
+     * Tags applied to the task that might define its behvaiour or impact the systems.
+     */
+    tags?: TTags;
+}
+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> {
+    [symbolFilePath]: string;
+    [symbolTask]: true;
+    id: string;
+    dependencies: TDependencies | (() => TDependencies);
+    computedDependencies?: DependencyValuesType<TDependencies>;
+    middleware: TMiddleware;
+    /** Return an optional dependency wrapper for this task. */
+    optional: () => IOptionalDependency<ITask<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware>>;
+    tags: TTags;
+}
+
+interface ITaskMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> {
+    id: string;
+    /** Static or lazy dependency map. */
+    dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * Optional validation schema for runtime config validation.
+     * When provided, middleware config will be validated when .with() is called.
+     */
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * The middleware body, called with task execution input.
+     */
+    run: (input: ITaskMiddlewareExecutionInput<TEnforceInputContract extends void ? any : TEnforceInputContract, TEnforceOutputContract extends void ? any : TEnforceOutputContract>, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
+    meta?: IMiddlewareMeta;
+    tags?: TagType[];
+    everywhere?: boolean | ((task: ITask<any, any, any, any>) => boolean);
+}
+interface ITaskMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends ITaskMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    [symbolTaskMiddleware]: true;
+    [symbolFilePath]: string;
+    id: string;
+    dependencies: TDependencies | (() => TDependencies);
+    /** Current configuration object (empty by default). */
+    config: TConfig;
+    /** Configure the middleware and return a marked, configured instance. */
+    with: (config: TConfig) => ITaskMiddlewareConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+    tags: TagType[];
+}
+interface ITaskMiddlewareConfigured<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends ITaskMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies> {
+    [symbolMiddlewareConfigured]: true;
+    config: TConfig;
+}
+interface ITaskMiddlewareExecutionInput<TTaskInput = any, TTaskOutput = any> {
+    /** Task hook */
+    task: {
+        definition: ITask<TTaskInput, any, any, any>;
+        input: TTaskInput;
+    };
+    next: (taskInput?: TTaskInput) => Promise<TTaskOutput>;
+}
+type TaskMiddlewareAttachmentType = ITaskMiddleware<void, any, any, any> | ITaskMiddleware<{
+    [K in any]?: any;
+}, any, any, any> | ITaskMiddlewareConfigured<any, any, any, any>;
+
+interface IResourceMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> {
+    id: string;
+    /** Static or lazy dependency map. */
+    dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * Optional validation schema for runtime config validation.
+     * When provided, middleware config will be validated when .with() is called.
+     */
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * The middleware body, called with resource execution input.
+     */
+    run: (input: IResourceMiddlewareExecutionInput<TEnforceInputContract extends void ? any : TEnforceInputContract, TEnforceOutputContract extends void ? any : TEnforceOutputContract>, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
+    meta?: IMiddlewareMeta;
+    tags?: TagType[];
+    everywhere?: boolean | ((resource: IResource<any, any, any, any, any>) => boolean);
+}
+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 | (() => TDependencies);
+    /** Current configuration object (empty by default). */
+    config: TConfig;
+    /** Configure the middleware and return a marked, configured instance. */
+    with: (config: TConfig) => IResourceMiddlewareConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+    [symbolFilePath]: string;
+    tags: TagType[];
+}
+interface IResourceMiddlewareConfigured<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends IResourceMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies> {
+    [symbolMiddlewareConfigured]: true;
+}
+interface IResourceMiddlewareExecutionInput<TResourceConfig = any, TResourceOutput = any> {
+    /** Resource hook */
+    resource: {
+        definition: IResource<TResourceConfig, any, any, any, any>;
+        config: TResourceConfig;
+    };
+    next: (resourceConfig?: TResourceConfig) => Promise<TResourceOutput>;
+}
+type ResourceMiddlewareAttachmentType = IResourceMiddleware<void, any, any, any> | IResourceMiddleware<{
+    [K in any]?: any;
+}, any, any, any> | IResourceMiddlewareConfigured<any, any, any, any>;
+
+type OnType = "*" | IEventDefinition<any> | readonly IEventDefinition<any>[];
+interface IHookDefinition<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> {
+    id: string;
+    dependencies?: TDependencies | (() => TDependencies);
+    on: TOn;
+    /** Listener execution order. Lower numbers run first. */
+    order?: number;
+    meta?: TMeta;
+    run: (event: IEventEmission<TOn extends "*" ? any : TOn extends readonly IEventDefinition<any>[] ? CommonPayload<TOn> : ExtractEventParams<TOn>>, dependencies: DependencyValuesType<TDependencies>) => Promise<any>;
+    tags?: TagType[];
+}
+interface IHook<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> extends IHookDefinition<TDependencies, TOn, TMeta> {
+    id: string;
+    dependencies: TDependencies | (() => TDependencies);
+    [symbolFilePath]: string;
+    [symbolHook]: true;
+    tags: TagType[];
+}
+
+type EventHandlerType<T = any> = (event: IEventEmission<T>) => any | Promise<any>;
+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.
+ * Narrows payload type to the intersection of the provided events' payloads.
+ */
+declare function isOneOf<TDefs extends readonly IEventDefinition<any>[]>(emission: IEventEmission<any>, defs: TDefs): emission is IEventEmission<CommonPayload<TDefs>>;
+interface IEventDefinition<TPayload = void> {
+    id: string;
+    meta?: IEventMeta;
+    /**
+     * Optional validation schema for runtime payload validation.
+     * When provided, event payload will be validated when emitted.
+     */
+    payloadSchema?: IValidationSchema<TPayload>;
+    tags?: TagType[];
+}
+/**
+ * The definioten of the event.
+ * This is different from the event emission.
+ */
+interface IEvent<TPayload = any> extends IEventDefinition<TPayload> {
+    id: string;
+    /**
+     * We use this event to discriminate between resources with just 'id' and 'events' as they collide. This is a workaround, should be redone using classes and instanceof.
+     */
+    [symbolEvent]: true;
+    [symbolFilePath]: string;
+    /** Return an optional dependency wrapper for this event. */
+    optional: () => IOptionalDependency<IEvent<TPayload>>;
+    tags: TagType[];
+}
+/**
+ * This represents the object that is passed to event handlers
+ */
+interface IEventEmission<TPayload = any> {
+    /**
+     * The ID of the event. This is the same as the event's ID.
+     * This is useful for global event listeners.
+     */
+    id: string;
+    /**
+     * The data that the event carries. It can be anything.
+     */
+    data: TPayload;
+    /**
+     * The timestamp when the event was created.
+     */
+    timestamp: Date;
+    /**
+     * The source of the event. This can be useful for debugging.
+     */
+    source: string;
+    /**
+     * Metadata associated with the event definition.
+     */
+    meta: IEventMeta;
+    /**
+     * Stops propagation to remaining event listeners.
+     */
+    stopPropagation(): void;
+    /**
+     * Returns true if propagation has been stopped.
+     */
+    isPropagationStopped(): boolean;
+    /**
+     * The tags that the event carries.
+     */
+    tags: TagType[];
+}
+
+/**
+ * Generic validation schema interface that can be implemented by any validation library.
+ * Compatible with Zod, Yup, Joi, and other validation libraries.
+ */
+interface IValidationSchema<T = any> {
+    /**
+     * Parse and validate the input data.
+     * Should throw an error if validation fails.
+     * Can transform the data if the schema supports transformations.
+     */
+    parse(input: unknown): T;
+}
+/**
+ * Core public TypeScript types for BlueLibs Runner.
+ *
+ * This file contains the strongly-typed contract for tasks, resources, events
+ * and middleware. It mirrors the mental model described in the README:
+ * - Tasks are functions
+ * - Resources are singletons (with init/dispose hooks)
+ * - Events are simple, strongly-typed emissions
+ * - Middleware can target both tasks and resources
+ *
+ * DX goals:
+ * - Crystal‑clear generics and helper types that infer dependency shapes
+ * - Friendly JSDoc you can hover in editors to understand usage instantly
+ * - Safe overrides and strong typing around config and register mechanics
+ */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+/**
+ * The reason we accept null and undefined is because we want to be able to offer beautiful DX:
+ * overrides: [
+ *    process.env.NODE_ENV === 'production' ? prodEmailer : null,
+ * ]
+ */
+type OverridableElements = IResource<any, any, any, any, any> | ITask<any, any, any, any> | ITaskMiddleware<any> | IResourceMiddleware<any, any> | IResourceWithConfig<any, any, any> | IHook<any, any> | undefined | null;
+/**
+ * A mapping of dependency keys to Runner definitions. Used in `dependencies`
+ * for tasks and resources. Values are later transformed into the actual
+ * callable/value shape by `DependencyValuesType`.
+ */
+type DependencyMapType = Record<string, ITask<any, any, any, any, any, any> | IResource<any, any, any, any, any, any, any> | IEvent<any> | IOptionalDependency<ITask<any, any, any, any, any, any>> | IOptionalDependency<IResource<any, any, any, any, any, any, any>> | IOptionalDependency<IEvent<any>>>;
+/** Wrapper type marking a dependency as optional at wiring time */
+interface IOptionalDependency<T> {
+    /** The wrapped dependency definition */
+    inner: T;
+    /** Brand symbol for optional dependency */
+    [symbolOptionalDependency]: true;
+}
+type ExtractTaskInput<T> = T extends ITask<infer I, any, infer D> ? I : never;
+type ExtractTaskOutput<T> = T extends ITask<any, infer O, infer D> ? O : never;
+type ExtractResourceValue<T> = T extends IResource<any, infer V, infer D> ? V extends Promise<infer U> ? U : V : never;
+type ExtractEventParams<T> = T extends IEventDefinition<infer P> ? P : T extends IEvent<infer P> ? P : never;
+type UnionToIntersection<U> = (U extends any ? (x: U) => any : never) extends (x: infer I) => any ? I : never;
+type CommonPayload<T extends readonly IEventDefinition<any>[] | IEventDefinition<any>> = T extends readonly IEventDefinition<any>[] ? {
+    [K in keyof ExtractEventParams<T[number]>]: UnionToIntersection<ExtractEventParams<T[number]> extends any ? ExtractEventParams<T[number]>[K] : never>;
+} : ExtractEventParams<T>;
+/**
+ * Task dependencies transform into callable functions: call with the task input
+ * and you receive the task output.
+ */
+type TaskDependency<I, O> = (...args: I extends null | void ? [] : [I]) => O;
+/**
+ * Resource dependencies resolve to the resource's value directly.
+ */
+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).
+ */
+type EventDependency<P> = P extends void ? (() => Promise<void>) & ((input?: Record<string, never>) => Promise<void>) : (input: P) => Promise<void>;
+/**
+ * Transforms a dependency definition into the usable shape inside `run`/`init`:
+ * - Task -> callable function
+ * - Resource -> resolved value
+ * - Event -> emit function
+ */
+type DependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventParams<T>> : T extends IOptionalDependency<infer U> ? DependencyValueType<U> | undefined : never;
+type DependencyValuesType<T extends DependencyMapType> = {
+    [K in keyof T]: DependencyValueType<T[K]>;
+};
+type TaskLocalInterceptor<TInput, TOutput> = (next: (input: TInput) => TOutput, input: TInput) => TOutput;
+type TaskDependencyWithIntercept<TInput, TOutput> = TaskDependency<TInput, TOutput> & {
+    intercept: (middleware: TaskLocalInterceptor<TInput, TOutput>) => void;
+};
+/** Resource-context dependency typing where tasks expose intercept() */
+type ResourceDependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependencyWithIntercept<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventParams<T>> : T extends IOptionalDependency<infer U> ? ResourceDependencyValueType<U> | undefined : never;
+type ResourceDependencyValuesType<T extends DependencyMapType> = {
+    [K in keyof T]: ResourceDependencyValueType<T[K]>;
+};
+/**
+ * Anything you can put inside a resource's `register: []`.
+ * - Resources (with or without `.with()`)
+ * - Tasks
+ * - Middleware
+ * - Events
+ */
+type RegisterableItems<T = any> = IResourceWithConfig<any, any, any, any, any, any, any> | IResource<void, any, any, any, any, any, any> | IResource<{
+    [K in any]?: any;
+}, any, any, any, any, any, any> | ITask<any, any, any, any> | IHook<any, any> | ITaskMiddleware<any, any, any, any> | IResourceMiddleware<any, any, any, any> | IEvent<any> | ITag<any, any, any>;
+
+type DebugConfig = {
+    logResourceConfig: boolean;
+    logResourceValue: boolean;
+    logResourceBeforeRun: boolean;
+    logResourceAfterRun: boolean;
+    logTaskBeforeRun: boolean;
+    logTaskInput: boolean;
+    logTaskOutput: boolean;
+    logTaskAfterRun: boolean;
+    logMiddlewareBeforeRun: boolean;
+    logMiddlewareAfterRun: boolean;
+    logEventEmissionOnRun: boolean;
+    logEventEmissionInput: boolean;
+    logHookTriggered: boolean;
+    logHookCompleted: boolean;
+};
+declare const allFalse: DebugConfig;
+declare const levelNormal: DebugConfig;
+declare const levelVerbose: DebugConfig;
+/**
+ * If you choose to specify your own config, all values will be set to false by default and extended by your config.
+ */
+type DebugFriendlyConfig = "normal" | "verbose" | Partial<DebugConfig>;
+declare const getConfig: (config: DebugFriendlyConfig, taggable?: ITaggable) => DebugConfig;
+
+type PrintStrategy$1 = "pretty" | "plain" | "json" | "json_pretty";
+type LogLevels$1 = "trace" | "debug" | "info" | "warn" | "error" | "critical";
+interface PrintableLog {
+    level: LogLevels$1;
+    source?: string;
+    message: any;
+    timestamp: Date;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    data?: Record<string, any>;
+    context?: Record<string, any>;
+}
+type ColorTheme = {
+    trace: string;
+    debug: string;
+    info: string;
+    warn: string;
+    error: string;
+    critical: string;
+    reset: string;
+    bold: string;
+    dim: string;
+    blue: string;
+    cyan: string;
+    gray: string;
+};
+declare class LogPrinter {
+    private strategy;
+    private colors;
+    constructor(options: {
+        strategy: PrintStrategy$1;
+        useColors: boolean;
+        colorTheme?: Partial<ColorTheme>;
+    });
+    print(log: PrintableLog): void;
+    private pickWriter;
+    private formatTime;
+    private formatLevel;
+    private formatSource;
+    private formatMessage;
+    private formatError;
+    private formatData;
+    private formatContext;
+    private normalizeForJson;
+    private static NO_COLORS;
+    private static writers;
+    static setWriters(writers: Partial<{
+        log: (msg: any) => void;
+        error?: (msg: any) => void;
+    }>): void;
+    static resetWriters(): void;
+}
+
+type LogLevels = "trace" | "debug" | "info" | "warn" | "error" | "critical";
+interface ILogInfo {
+    source?: string;
+    error?: unknown | Error;
+    data?: Record<string, any>;
+    context?: Record<string, any>;
+    [key: string]: any;
+}
+interface ILog {
+    level: LogLevels;
+    source?: string;
+    message: any;
+    timestamp: Date;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    data?: Record<string, any>;
+    context?: Record<string, any>;
+}
+type PrintStrategy = PrintStrategy$1;
+declare class Logger {
+    private printThreshold;
+    private printStrategy;
+    private bufferLogs;
+    private buffer;
+    private boundContext;
+    private isLocked;
+    private useColors;
+    private printer;
+    private source?;
+    private rootLogger?;
+    localListeners: Array<(log: ILog) => void | Promise<void>>;
+    static Severity: {
+        trace: number;
+        debug: number;
+        info: number;
+        warn: number;
+        error: number;
+        critical: number;
+    };
+    constructor(options: {
+        printThreshold: null | LogLevels;
+        printStrategy: PrintStrategy;
+        bufferLogs: boolean;
+        useColors?: boolean;
+    }, boundContext?: Record<string, any>, source?: string, printer?: LogPrinter);
+    private detectColorSupport;
+    /**
+     * Creates a new logger instance with additional bound context
+     */
+    with({ source, additionalContext: context, }: {
+        source?: string;
+        additionalContext?: Record<string, any>;
+    }): Logger;
+    /**
+     * Core logging method with structured LogInfo
+     */
+    log(level: LogLevels, message: any, logInfo?: ILogInfo): Promise<void>;
+    private extractErrorInfo;
+    info(message: any, logInfo?: ILogInfo): Promise<void>;
+    error(message: any, logInfo?: ILogInfo): Promise<void>;
+    warn(message: any, logInfo?: ILogInfo): Promise<void>;
+    debug(message: any, logInfo?: ILogInfo): Promise<void>;
+    trace(message: any, logInfo?: ILogInfo): Promise<void>;
+    critical(message: any, logInfo?: ILogInfo): Promise<void>;
+    /**
+     * Direct print for tests and advanced scenarios. Delegates to LogPrinter.
+     */
+    print(log: ILog): void;
+    /**
+     * @param listener - A listener that will be triggered for every log.
+     */
+    onLog(listener: (log: ILog) => any): void;
+    /**
+     * Marks the logger as ready.
+     * This is used to trigger the local listeners and print the buffered logs (if they exists)
+     * @returns A promise that resolves when the logger is ready.
+     */
+    lock(): Promise<void>;
+    private canPrint;
+    private triggerLogListeners;
+}
+
+type UnhandledErrorKind = "process" | "task" | "middleware" | "resourceInit" | "hook" | "run";
+interface OnUnhandledErrorInfo {
+    error: unknown;
+    kind?: UnhandledErrorKind;
+    source?: string;
+}
+type OnUnhandledError = (info: OnUnhandledErrorInfo) => void | Promise<void>;
+declare function createDefaultUnhandledError(logger: Logger): OnUnhandledError;
+declare function bindProcessErrorHandler(handler: OnUnhandledError): (error: unknown, source: "uncaughtException" | "unhandledRejection") => void | Promise<void>;
+declare function safeReportUnhandledError(handler: OnUnhandledError, info: OnUnhandledErrorInfo): Promise<void>;
+
+type RunOptions = {
+    /**
+     * Defaults to undefined. If true, we introduce logging to the console.
+     */
+    debug?: DebugFriendlyConfig;
+    /**
+     * Configure logging settings.
+     */
+    logs?: {
+        /**
+         * Defaults to info. Use null to disable logging.
+         */
+        printThreshold?: null | LogLevels;
+        /**
+         * Defaults to PRETTY. How to print the logs.
+         */
+        printStrategy?: PrintStrategy;
+        /**
+         * Defaults to false. If true, we buffer logs until the root resource is ready.
+         * This provides you with the chance to see the logs before the root resource is ready.
+         */
+        bufferLogs?: boolean;
+    };
+    /**
+     * When true (default), installs a central error boundary that catches uncaught errors
+     * from process-level events and routes them to `onUnhandledError`.
+     */
+    errorBoundary?: boolean;
+    /**
+     * When true (default), installs SIGINT/SIGTERM handlers that call dispose() on the root allowing for graceful shutdown.
+     */
+    shutdownHooks?: boolean;
+    /**
+     * Custom handler for any unhandled error caught by Runner. Defaults to logging via the created logger.
+     */
+    onUnhandledError?: OnUnhandledError;
+    /**
+     * Defaults to false.
+     *
+     * Dry run mode. When true, the runner will setup the system, ensure there are no errors, but will not start the system.
+     * Your resources will not be initialized, and no events will be emitted. This is useful for testing and debugging.
+     *
+     * Note: this cannot catch init() errors that happen within resources.
+     */
+    dryRun?: boolean;
+    /**
+     * Defaults to true.
+     * When set, forces runtime cycle detection for event emissions. Disable if you're sure
+     * you don't have event deadlocks to improve event emission performance.
+     */
+    runtimeCycleDetection?: boolean;
+};
+
+interface ICacheInstance {
+    set(key: string, value: any): void;
+    get(key: string): any;
+    clear(): void;
+}
+
+type ResourceStoreElementType<C = any, V extends Promise<any> = any, D extends DependencyMapType = {}, TContext = any> = {
+    resource: IResource<C, V, D>;
+    computedDependencies?: ResourceDependencyValuesType<D>;
+    config: C;
+    value: V;
+    context: TContext;
+    isInitialized?: boolean;
+};
+type TaskStoreElementType<Input = any, Output extends Promise<any> = any, D extends DependencyMapType = any> = {
+    task: ITask<Input, Output, D>;
+    computedDependencies: DependencyValuesType<D>;
+    isInitialized: boolean;
+    interceptors?: Array<TaskLocalInterceptor<any, any>>;
+};
+type HookStoreElementType<D extends DependencyMapType = any, TOn extends "*" | IEventDefinition = any> = {
+    hook: IHook<D, TOn>;
+    computedDependencies: DependencyValuesType<D>;
+};
+type TaskMiddlewareStoreElementType<TDeps extends DependencyMapType = any> = {
+    middleware: ITaskMiddleware<any, TDeps>;
+    computedDependencies: DependencyValuesType<TDeps>;
+    isInitialized: boolean;
+};
+type ResourceMiddlewareStoreElementType<TDeps extends DependencyMapType = any> = {
+    middleware: IResourceMiddleware<any, TDeps>;
+    computedDependencies: DependencyValuesType<TDeps>;
+    isInitialized: boolean;
+};
+type EventStoreElementType = {
+    event: IEvent<any>;
+};
+
+/**
+ * Core public TypeScript types for BlueLibs Runner.
+ *
+ * This file contains the strongly-typed contract for tasks, resources, events
+ * and middleware. It mirrors the mental model described in the README:
+ * - Tasks are functions
+ * - Resources are singletons (with init/dispose hooks)
+ * - Hooks are event listeners without middleware
+ * - Events are simple, strongly-typed emissions
+ * - Middleware can target both tasks and resources (taskMiddleware, resourceMiddleware)
+ *
+ * DX goals:
+ * - Crystal‑clear generics and helper types that infer dependency shapes
+ * - Friendly JSDoc you can hover in editors to understand usage instantly
+ * - Safe overrides and strong typing around config and register mechanics
+ */
+
+type defs_CommonPayload<T extends readonly IEventDefinition<any>[] | IEventDefinition<any>> = CommonPayload<T>;
+type defs_DependencyMapType = DependencyMapType;
+type defs_DependencyValueType<T> = DependencyValueType<T>;
+type defs_DependencyValuesType<T extends DependencyMapType> = DependencyValuesType<T>;
+type defs_EventHandlerType<T = any> = EventHandlerType<T>;
+type defs_EventStoreElementType = EventStoreElementType;
+type defs_ExtractEventParams<T> = ExtractEventParams<T>;
+type defs_HookStoreElementType<D extends DependencyMapType = any, TOn extends "*" | IEventDefinition = any> = HookStoreElementType<D, TOn>;
+type defs_ICacheInstance = ICacheInstance;
+type defs_IEvent<TPayload = any> = IEvent<TPayload>;
+type defs_IEventDefinition<TPayload = void> = IEventDefinition<TPayload>;
+type defs_IEventEmission<TPayload = any> = IEventEmission<TPayload>;
+type defs_IEventMeta = IEventMeta;
+type defs_IHook<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> = IHook<TDependencies, TOn, TMeta>;
+type defs_IHookDefinition<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> = IHookDefinition<TDependencies, TOn, TMeta>;
+type defs_IMeta = IMeta;
+type defs_IMiddlewareMeta = IMiddlewareMeta;
+type defs_IOptionalDependency<T> = IOptionalDependency<T>;
+type defs_IResource<TConfig = void, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, TContext = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]> = IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+type defs_IResourceDefinition<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = {}, TContext = any, THooks = any, TRegisterableItems = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]> = IResourceDefinition<TConfig, TValue, TDependencies, TContext, THooks, TRegisterableItems, TMeta, TTags, TMiddleware>;
+type defs_IResourceMeta = IResourceMeta;
+type defs_IResourceMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> = IResourceMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+type defs_IResourceMiddlewareConfigured<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> = IResourceMiddlewareConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+type defs_IResourceMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> = IResourceMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+type defs_IResourceMiddlewareExecutionInput<TResourceConfig = any, TResourceOutput = any> = IResourceMiddlewareExecutionInput<TResourceConfig, TResourceOutput>;
+type defs_IResourceWithConfig<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, TContext = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends IResourceMiddleware<any, any, any, any>[] = IResourceMiddleware[]> = IResourceWithConfig<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+type defs_ITag<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> = ITag<TConfig, TEnforceInputContract, TEnforceOutputContract>;
+type defs_ITagConfigured<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> = ITagConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract>;
+type defs_ITagDefinition<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> = ITagDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract>;
+type defs_ITagMeta = ITagMeta;
+type defs_ITaggable = ITaggable;
+type defs_ITask<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> = ITask<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware>;
+type defs_ITaskDefinition<TInput = undefined, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> = ITaskDefinition<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware>;
+type defs_ITaskMeta = ITaskMeta;
+type defs_ITaskMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> = ITaskMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+type defs_ITaskMiddlewareConfigured<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> = ITaskMiddlewareConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+type defs_ITaskMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> = ITaskMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+type defs_ITaskMiddlewareExecutionInput<TTaskInput = any, TTaskOutput = any> = ITaskMiddlewareExecutionInput<TTaskInput, TTaskOutput>;
+type defs_IValidationSchema<T = any> = IValidationSchema<T>;
+type defs_OverridableElements = OverridableElements;
+type defs_RegisterableItems<T = any> = RegisterableItems<T>;
+type defs_RequiredKeys<T> = RequiredKeys<T>;
+type defs_ResourceDependencyValueType<T> = ResourceDependencyValueType<T>;
+type defs_ResourceDependencyValuesType<T extends DependencyMapType> = ResourceDependencyValuesType<T>;
+type defs_ResourceMiddlewareAttachmentType = ResourceMiddlewareAttachmentType;
+type defs_ResourceMiddlewareStoreElementType<TDeps extends DependencyMapType = any> = ResourceMiddlewareStoreElementType<TDeps>;
+type defs_ResourceStoreElementType<C = any, V extends Promise<any> = any, D extends DependencyMapType = {}, TContext = any> = ResourceStoreElementType<C, V, D, TContext>;
+type defs_RunOptions = RunOptions;
+type defs_TagType = TagType;
+type defs_TaskDependencyWithIntercept<TInput, TOutput> = TaskDependencyWithIntercept<TInput, TOutput>;
+type defs_TaskLocalInterceptor<TInput, TOutput> = TaskLocalInterceptor<TInput, TOutput>;
+type defs_TaskMiddlewareAttachmentType = TaskMiddlewareAttachmentType;
+type defs_TaskMiddlewareStoreElementType<TDeps extends DependencyMapType = any> = TaskMiddlewareStoreElementType<TDeps>;
+type defs_TaskStoreElementType<Input = any, Output extends Promise<any> = any, D extends DependencyMapType = any> = TaskStoreElementType<Input, Output, D>;
+type defs_UnionToIntersection<U> = UnionToIntersection<U>;
+declare const defs_isOneOf: typeof isOneOf;
+declare const defs_onAnyOf: typeof onAnyOf;
+declare const defs_symbolDispose: typeof symbolDispose;
+declare const defs_symbolEvent: typeof symbolEvent;
+declare const defs_symbolFilePath: typeof symbolFilePath;
+declare const defs_symbolHook: typeof symbolHook;
+declare const defs_symbolIndexResource: typeof symbolIndexResource;
+declare const defs_symbolMiddleware: typeof symbolMiddleware;
+declare const defs_symbolMiddlewareConfigured: typeof symbolMiddlewareConfigured;
+declare const defs_symbolOptionalDependency: typeof symbolOptionalDependency;
+declare const defs_symbolResource: typeof symbolResource;
+declare const defs_symbolResourceMiddleware: typeof symbolResourceMiddleware;
+declare const defs_symbolResourceWithConfig: typeof symbolResourceWithConfig;
+declare const defs_symbolStore: typeof symbolStore;
+declare const defs_symbolTag: typeof symbolTag;
+declare const defs_symbolTagConfigured: typeof symbolTagConfigured;
+declare const defs_symbolTask: typeof symbolTask;
+declare const defs_symbolTaskMiddleware: typeof symbolTaskMiddleware;
+declare namespace defs {
+  export { type defs_CommonPayload as CommonPayload, type defs_DependencyMapType as DependencyMapType, type defs_DependencyValueType as DependencyValueType, type defs_DependencyValuesType as DependencyValuesType, type defs_EventHandlerType as EventHandlerType, type defs_EventStoreElementType as EventStoreElementType, type defs_ExtractEventParams as ExtractEventParams, type defs_HookStoreElementType as HookStoreElementType, type defs_ICacheInstance as ICacheInstance, type defs_IEvent as IEvent, type defs_IEventDefinition as IEventDefinition, type defs_IEventEmission as IEventEmission, type defs_IEventMeta as IEventMeta, type defs_IHook as IHook, type defs_IHookDefinition as IHookDefinition, type defs_IMeta as IMeta, type defs_IMiddlewareMeta as IMiddlewareMeta, type defs_IOptionalDependency as IOptionalDependency, type defs_IResource as IResource, type defs_IResourceDefinition as IResourceDefinition, type defs_IResourceMeta as IResourceMeta, type defs_IResourceMiddleware as IResourceMiddleware, type defs_IResourceMiddlewareConfigured as IResourceMiddlewareConfigured, type defs_IResourceMiddlewareDefinition as IResourceMiddlewareDefinition, type defs_IResourceMiddlewareExecutionInput as IResourceMiddlewareExecutionInput, type defs_IResourceWithConfig as IResourceWithConfig, type defs_ITag as ITag, type defs_ITagConfigured as ITagConfigured, type defs_ITagDefinition as ITagDefinition, type defs_ITagMeta as ITagMeta, type defs_ITaggable as ITaggable, type defs_ITask as ITask, type defs_ITaskDefinition as ITaskDefinition, type defs_ITaskMeta as ITaskMeta, type defs_ITaskMiddleware as ITaskMiddleware, type defs_ITaskMiddlewareConfigured as ITaskMiddlewareConfigured, type defs_ITaskMiddlewareDefinition as ITaskMiddlewareDefinition, type defs_ITaskMiddlewareExecutionInput as ITaskMiddlewareExecutionInput, type defs_IValidationSchema as IValidationSchema, type defs_OverridableElements as OverridableElements, type defs_RegisterableItems as RegisterableItems, type defs_RequiredKeys as RequiredKeys, type defs_ResourceDependencyValueType as ResourceDependencyValueType, type defs_ResourceDependencyValuesType as ResourceDependencyValuesType, type defs_ResourceMiddlewareAttachmentType as ResourceMiddlewareAttachmentType, type defs_ResourceMiddlewareStoreElementType as ResourceMiddlewareStoreElementType, type defs_ResourceStoreElementType as ResourceStoreElementType, type defs_RunOptions as RunOptions, type defs_TagType as TagType, type defs_TaskDependencyWithIntercept as TaskDependencyWithIntercept, type defs_TaskLocalInterceptor as TaskLocalInterceptor, type defs_TaskMiddlewareAttachmentType as TaskMiddlewareAttachmentType, type defs_TaskMiddlewareStoreElementType as TaskMiddlewareStoreElementType, type defs_TaskStoreElementType as TaskStoreElementType, type defs_UnionToIntersection as UnionToIntersection, defs_isOneOf as isOneOf, defs_onAnyOf as onAnyOf, defs_symbolDispose as symbolDispose, defs_symbolEvent as symbolEvent, defs_symbolFilePath as symbolFilePath, defs_symbolHook as symbolHook, defs_symbolIndexResource as symbolIndexResource, defs_symbolMiddleware as symbolMiddleware, defs_symbolMiddlewareConfigured as symbolMiddlewareConfigured, defs_symbolOptionalDependency as symbolOptionalDependency, defs_symbolResource as symbolResource, defs_symbolResourceMiddleware as symbolResourceMiddleware, defs_symbolResourceWithConfig as symbolResourceWithConfig, defs_symbolStore as symbolStore, defs_symbolTag as symbolTag, defs_symbolTagConfigured as symbolTagConfigured, defs_symbolTask as symbolTask, defs_symbolTaskMiddleware as symbolTaskMiddleware };
+}
+
+interface TimeoutMiddlewareConfig {
+    /**
+     * Maximum time in milliseconds before the wrapped operation is aborted
+     * and a timeout error is thrown. Defaults to 5000ms.
+     */
+    ttl: number;
+}
+
+/**
+ * Configuration options for the retry middleware
+ */
+interface RetryMiddlewareConfig {
+    /**
+     * Maximum number of retry attempts (default: 3)
+     */
+    retries?: number;
+    /**
+     * Callback to determine if retry should stop based on error
+     * @default () => false (retry all errors)
+     */
+    stopRetryIf?: (error: Error) => boolean;
+    /**
+     * Custom delay strategy function
+     * @default Exponential backoff starting at 100ms
+     */
+    delayStrategy?: (attempt: number, error: Error) => number;
+}
+
+/**
+ * Base error class for all BlueLibs Runner errors
+ */
+declare class RuntimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when attempting to register a component with a duplicate ID
+ */
+declare class DuplicateRegistrationError extends RuntimeError {
+    constructor(type: string, id: string);
+}
+/**
+ * Error thrown when a dependency is not found in the registry
+ */
+declare class DependencyNotFoundError extends RuntimeError {
+    constructor(key: string);
+}
+/**
+ * Error thrown when an unknown item type is encountered
+ */
+declare class UnknownItemTypeError extends RuntimeError {
+    constructor(item: any);
+}
+/**
+ * Error thrown whenever a requested context is not available.
+ */
+declare class ContextError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when circular dependencies are detected
+ */
+declare class CircularDependenciesError extends RuntimeError {
+    constructor(cycles: string[]);
+}
+/**
+ * Error thrown when an event is not found in the registry
+ */
+declare class EventNotFoundError extends RuntimeError {
+    constructor(id: string);
+}
+/**
+ * Error thrown when a resource is not found in the store
+ */
+declare class ResourceNotFoundError extends RuntimeError {
+    constructor(id: string);
+}
+declare class MiddlewareNotRegisteredError extends RuntimeError {
+    constructor(type: "task" | "resource", source: string, middlewareId: string);
+}
+/**
+ * Error thrown when a tag is not found in the registry
+ */
+declare class TagNotFoundError extends RuntimeError {
+    constructor(id: string);
+}
+/**
+ * Error thrown when attempting to modify a locked component
+ */
+declare class LockedError extends RuntimeError {
+    constructor(what: string);
+}
+/**
+ * Error thrown when attempting to initialize a store that's already initialized
+ */
+declare class StoreAlreadyInitializedError extends RuntimeError {
+    constructor();
+}
+/**
+ * Error thrown when validation fails for task input, resource config, middleware config, or event payload
+ */
+declare class ValidationError extends RuntimeError {
+    constructor(type: string, id: string, originalError: Error | string);
+}
+/**
+ * Error thrown when an event emission cycle is detected
+ */
+declare class EventCycleError extends RuntimeError {
+    constructor(path: Array<{
+        id: string;
+        source: string;
+    }>);
+}
+/**
+ * Error thrown when a compile-time event emission cycle is detected
+ */
+declare class EventEmissionCycleError extends RuntimeError {
+    constructor(cycles: string[]);
+}
+/**
+ * Error thrown when a platform function is not supported in the current environment.
+ */
+declare class PlatformUnsupportedFunction extends RuntimeError {
+    constructor(functionName: string);
+}
+
+type errors_CircularDependenciesError = CircularDependenciesError;
+declare const errors_CircularDependenciesError: typeof CircularDependenciesError;
+type errors_ContextError = ContextError;
+declare const errors_ContextError: typeof ContextError;
+type errors_DependencyNotFoundError = DependencyNotFoundError;
+declare const errors_DependencyNotFoundError: typeof DependencyNotFoundError;
+type errors_DuplicateRegistrationError = DuplicateRegistrationError;
+declare const errors_DuplicateRegistrationError: typeof DuplicateRegistrationError;
+type errors_EventCycleError = EventCycleError;
+declare const errors_EventCycleError: typeof EventCycleError;
+type errors_EventEmissionCycleError = EventEmissionCycleError;
+declare const errors_EventEmissionCycleError: typeof EventEmissionCycleError;
+type errors_EventNotFoundError = EventNotFoundError;
+declare const errors_EventNotFoundError: typeof EventNotFoundError;
+type errors_LockedError = LockedError;
+declare const errors_LockedError: typeof LockedError;
+type errors_MiddlewareNotRegisteredError = MiddlewareNotRegisteredError;
+declare const errors_MiddlewareNotRegisteredError: typeof MiddlewareNotRegisteredError;
+type errors_PlatformUnsupportedFunction = PlatformUnsupportedFunction;
+declare const errors_PlatformUnsupportedFunction: typeof PlatformUnsupportedFunction;
+type errors_ResourceNotFoundError = ResourceNotFoundError;
+declare const errors_ResourceNotFoundError: typeof ResourceNotFoundError;
+type errors_RuntimeError = RuntimeError;
+declare const errors_RuntimeError: typeof RuntimeError;
+type errors_StoreAlreadyInitializedError = StoreAlreadyInitializedError;
+declare const errors_StoreAlreadyInitializedError: typeof StoreAlreadyInitializedError;
+type errors_TagNotFoundError = TagNotFoundError;
+declare const errors_TagNotFoundError: typeof TagNotFoundError;
+type errors_UnknownItemTypeError = UnknownItemTypeError;
+declare const errors_UnknownItemTypeError: typeof UnknownItemTypeError;
+type errors_ValidationError = ValidationError;
+declare const errors_ValidationError: typeof ValidationError;
+declare namespace errors {
+  export { errors_CircularDependenciesError as CircularDependenciesError, errors_ContextError as ContextError, errors_DependencyNotFoundError as DependencyNotFoundError, errors_DuplicateRegistrationError as DuplicateRegistrationError, errors_EventCycleError as EventCycleError, errors_EventEmissionCycleError as EventEmissionCycleError, errors_EventNotFoundError as EventNotFoundError, errors_LockedError as LockedError, errors_MiddlewareNotRegisteredError as MiddlewareNotRegisteredError, errors_PlatformUnsupportedFunction as PlatformUnsupportedFunction, errors_ResourceNotFoundError as ResourceNotFoundError, errors_RuntimeError as RuntimeError, errors_StoreAlreadyInitializedError as StoreAlreadyInitializedError, errors_TagNotFoundError as TagNotFoundError, errors_UnknownItemTypeError as UnknownItemTypeError, errors_ValidationError as ValidationError };
+}
+
+/**
+ * The generic Context object returned by `createContext`.
+ */
+interface Context<T> {
+    /** unique symbol used as key in the AsyncLocalStorage map */
+    readonly id: symbol;
+    /** Retrieve the current context value or throw */
+    use(): T;
+    /**
+     * Provide a value for this context during the lifetime of `fn()`
+     */
+    provide<R>(value: T, fn: () => Promise<R> | R): Promise<R> | R;
+    /**
+     * Generates a middleware that guarantees the context exists (and optionally
+     * enforces that certain keys are present on the context object).
+     */
+    require<K extends keyof T = never>(keys?: K[]): ITaskMiddlewareConfigured<{
+        context: Context<T>;
+    }>;
+}
+/**
+ * Create a new typed Context. The result contains helpers similar to React’s
+ * Context API but adapted for async usage in Runner.
+ */
+declare function createContext<T>(name?: string): Context<T>;
+
+/**
+ * Options for configuring event listeners
+ */
+interface IEventHandlerOptions<T = any> {
+    order?: number;
+    filter?: (event: IEventEmission<T>) => boolean;
+    /**
+     * Represents the listener ID. Use this to avoid a listener calling himself.
+     */
+    id?: string;
+}
+/**
+ * Interceptor for event emissions
+ */
+type EventEmissionInterceptor = (next: (event: IEventEmission<any>) => Promise<void>, event: IEventEmission<any>) => Promise<void>;
+/**
+ * Interceptor for hook execution
+ */
+type HookExecutionInterceptor = (next: (hook: IHook<any, any>, event: IEventEmission<any>) => Promise<any>, hook: IHook<any, any>, event: IEventEmission<any>) => Promise<any>;
+/**
+ * EventManager handles event emission, listener registration, and event processing.
+ * It supports both specific event listeners and global listeners that handle all events.
+ * Listeners are processed in order based on their priority.
+ */
+declare class EventManager {
+    #private;
+    private listeners;
+    private globalListeners;
+    private cachedMergedListeners;
+    private globalListenersCacheValid;
+    private emissionInterceptors;
+    private hookInterceptors;
+    private readonly emissionStack;
+    private readonly currentHookIdContext;
+    private readonly runtimeCycleDetection;
+    constructor(options?: {
+        runtimeCycleDetection?: boolean;
+    });
+    /**
+     * Gets the current lock status of the EventManager
+     */
+    get isLocked(): boolean;
+    /**
+     * Locks the EventManager, preventing any further modifications to listeners
+     */
+    lock(): void;
+    /**
+     * Emits an event to all registered listeners for that event type.
+     * Listeners are processed in order of priority and can stop event propagation.
+     *
+     * @param eventDefinition - The event definition to emit
+     * @param data - The event payload data
+     * @param source - The source identifier of the event emitter
+     */
+    emit<TInput>(eventDefinition: IEvent<TInput>, data: TInput, source: string): Promise<void>;
+    /**
+     * Registers an event listener for specific event(s).
+     * Listeners are ordered by priority and executed in ascending order.
+     *
+     * @param event - The event definition(s) to listen for
+     * @param handler - The callback function to handle the event
+     * @param options - Configuration options for the listener
+     */
+    addListener<T>(event: IEvent<T> | Array<IEvent<T>>, handler: EventHandlerType<T>, options?: IEventHandlerOptions<T>): void;
+    /**
+     * Registers a global event listener that handles all events.
+     * Global listeners are mixed with specific listeners and ordered by priority.
+     *
+     * @param handler - The callback function to handle events
+     * @param options - Configuration options for the listener
+     */
+    addGlobalListener(handler: EventHandlerType, options?: IEventHandlerOptions): void;
+    /**
+     * Checks if there are any listeners registered for the given event
+     *
+     * @param eventDefinition - The event definition to check
+     * @returns true if listeners exist, false otherwise
+     */
+    hasListeners<T>(eventDefinition: IEvent<T>): boolean;
+    /**
+     * Adds an interceptor for all event emissions
+     * Interceptors are executed in the order they are added, with the ability to
+     * modify, log, or prevent event emissions
+     *
+     * @param interceptor - The interceptor function to add
+     */
+    intercept(interceptor: EventEmissionInterceptor): void;
+    /**
+     * Adds an interceptor for hook execution
+     * Interceptors are executed in the order they are added, with the ability to
+     * modify, log, or prevent hook execution
+     *
+     * @param interceptor - The interceptor function to add
+     */
+    interceptHook(interceptor: HookExecutionInterceptor): void;
+    /**
+     * Executes a hook with all registered hook interceptors applied
+     * This method should be used by TaskRunner when executing hooks
+     *
+     * @param hook - The hook to execute
+     * @param event - The event that triggered the hook
+     * @param computedDependencies - The computed dependencies for the hook
+     * @returns Promise resolving to the hook execution result
+     */
+    executeHookWithInterceptors(hook: IHook<any, any>, event: IEventEmission<any>, computedDependencies: DependencyValuesType<any>): Promise<any>;
+    /**
+     * Throws an error if the EventManager is locked
+     */
+    private checkLock;
+    /**
+     * Merges two sorted arrays of listeners while maintaining order.
+     * Used to combine event-specific listeners with global listeners.
+     *
+     * @param a - First array of listeners
+     * @param b - Second array of listeners
+     * @returns Merged and sorted array of listeners
+     */
+    private mergeSortedListeners;
+    /**
+     * Inserts a new listener into a sorted array using binary search.
+     * Maintains order based on listener priority.
+     *
+     * @param listeners - Array to insert into
+     * @param newListener - Listener to insert
+     */
+    private insertListener;
+    /**
+     * Returns true if the given emission carries the tag that marks
+     * it as excluded from global ("*") listeners.
+     *
+     * @param event - The event emission to check
+     * @returns true if event should exclude global listeners
+     */
+    private isExcludedFromGlobal;
+    /**
+     * Retrieves cached merged listeners for an event, or creates them if not cached.
+     * Combines event-specific listeners with global listeners and sorts them by priority.
+     *
+     * @param eventId - The event ID to get listeners for
+     * @returns Array of merged listeners sorted by priority
+     */
+    private getCachedMergedListeners;
+    /**
+     * Invalidates the cached merged listeners.
+     * If eventId is provided, only invalidates cache for that specific event.
+     * Otherwise, invalidates the global cache.
+     *
+     * @param eventId - Optional specific event ID to invalidate
+     */
+    private invalidateCache;
+}
+
+declare class TaskRunner {
+    protected readonly store: Store;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    protected readonly runnerStore: Map<string | symbol, (input: any) => Promise<any>>;
+    constructor(store: Store, eventManager: EventManager, logger: Logger);
+    private readonly middlewareManager;
+    /**
+     * Begins the execution of an task. These are registered tasks and all sanity checks have been performed at this stage to ensure consistency of the object.
+     * This function can throw only if any of the event listeners or run function throws
+     * @param task the task to be run
+     * @param input the input to be passed to the task
+     */
+    run<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>, input?: TInput): Promise<TOutput | undefined>;
+    /**
+     * Creates the function with the chain of middleware.
+     * @param task
+     * @param input
+     * @param taskDependencies
+     * @returns
+     */
+    protected createRunnerWithMiddleware<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>): (input: any) => Promise<TOutput | (TOutput extends Promise<infer U> ? U : never)>;
+}
+
+/**
+ * Interceptor for task middleware execution
+ */
+type TaskMiddlewareInterceptor = (next: (input: ITaskMiddlewareExecutionInput<any>) => Promise<any>, input: ITaskMiddlewareExecutionInput<any>) => Promise<any>;
+/**
+ * Interceptor for resource middleware execution
+ */
+type ResourceMiddlewareInterceptor = (next: (input: IResourceMiddlewareExecutionInput<any>) => Promise<any>, input: IResourceMiddlewareExecutionInput<any>) => Promise<any>;
+/**
+ * Centralizes middleware composition and execution for both tasks and resources.
+ * Keeps observability emissions and unhandled error routing consistent.
+ */
+declare class MiddlewareManager {
+    #private;
+    protected readonly store: Store;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    private taskMiddlewareInterceptors;
+    private resourceMiddlewareInterceptors;
+    private perMiddlewareInterceptors;
+    private perResourceMiddlewareInterceptors;
+    constructor(store: Store, eventManager: EventManager, logger: Logger);
+    /**
+     * Gets the current lock status of the MiddlewareManager
+     */
+    get isLocked(): boolean;
+    /**
+     * Locks the MiddlewareManager, preventing any further modifications to interceptors
+     */
+    lock(): void;
+    /**
+     * Throws an error if the MiddlewareManager is locked
+     */
+    private checkLock;
+    /**
+     * Adds an interceptor for task or resource middleware execution
+     * Interceptors are executed in the order they are added, with the ability to
+     * modify, log, or prevent middleware execution
+     *
+     * @param kind - The type of middleware to intercept ("task" or "resource")
+     * @param interceptor - The interceptor function to add
+     */
+    intercept(kind: "task" | "resource", interceptor: TaskMiddlewareInterceptor | ResourceMiddlewareInterceptor): void;
+    /**
+     * Adds an interceptor for a specific middleware instance with better type safety
+     * This method automatically determines the type and provides type-safe access
+     *
+     * @param middleware - The middleware instance to intercept
+     * @param interceptor - The interceptor function with proper typing
+     */
+    interceptMiddleware(middleware: ITaskMiddleware<any, any, any, any> | IResourceMiddleware<any, any, any, any>, interceptor: TaskMiddlewareInterceptor | ResourceMiddlewareInterceptor): void;
+    /**
+     * Wrap a middleware with its specific interceptors in onion style
+     */
+    private wrapMiddlewareWithInterceptors;
+    /**
+     * Wrap a resource middleware with its specific interceptors in onion style
+     */
+    private wrapResourceMiddlewareWithInterceptors;
+    /**
+     * Compose a runner for a task with its local interceptors and applicable middlewares.
+     * Returns a function that accepts the task input and resolves to the task output.
+     */
+    composeTaskRunner<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>): (input: any) => Promise<TOutput | (TOutput extends Promise<infer U> ? U : never)>;
+    /**
+     * Run a resource init wrapped with its applicable middlewares.
+     */
+    runResourceInit<C, V extends Promise<any>, D extends DependencyMapType, TContext>(resource: IResource<C, V, D, TContext>, config: C, dependencies: any, context: TContext): Promise<V | undefined>;
+    private getApplicableTaskMiddlewares;
+    private getApplicableResourceMiddlewares;
+    /**
+     * @param task
+     * @returns
+     */
+    getEverywhereMiddlewareForTasks(task: ITask<any, any, any, any>): ITaskMiddleware[];
+    /**
+     * Returns all global middleware for resource, which do not depend on the target resource.
+     */
+    getEverywhereMiddlewareForResources(target: IResource<any, any, any, any>): IResourceMiddleware[];
+}
+
+/**
+ * Store class which is used to store all the resources, tasks, middleware and events.
+ */
+declare class Store {
+    #private;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    readonly onUnhandledError: OnUnhandledError;
+    root: ResourceStoreElementType;
+    private registry;
+    private overrideManager;
+    private validator;
+    private taskRunner?;
+    private middlewareManager;
+    constructor(eventManager: EventManager, logger: Logger, onUnhandledError: OnUnhandledError);
+    get tasks(): Map<string, TaskStoreElementType>;
+    get hooks(): Map<string, HookStoreElementType>;
+    get resources(): Map<string, ResourceStoreElementType>;
+    get events(): Map<string, EventStoreElementType>;
+    get taskMiddlewares(): Map<string, TaskMiddlewareStoreElementType>;
+    get resourceMiddlewares(): Map<string, ResourceMiddlewareStoreElementType>;
+    get tags(): Map<string, ITag<void, void, void>>;
+    get overrides(): Map<string, IResourceMiddleware<any, void, void, any> | ITask<any, any, {}, any, TagType[], TaskMiddlewareAttachmentType[]> | IHook<{}, any, any> | IResource<void, Promise<any>, any, any, any, TagType[], ResourceMiddlewareAttachmentType[]> | ITaskMiddleware<any, void, void, any> | IResourceWithConfig<any, Promise<any>, any, any, any, TagType[], IResourceMiddleware<any, void, void, any>[]>>;
+    get overrideRequests(): Set<{
+        source: string;
+        override: RegisterableItems;
+    }>;
+    getMiddlewareManager(): MiddlewareManager;
+    get isLocked(): boolean;
+    lock(): void;
+    checkLock(): void;
+    private registerGlobalComponents;
+    setTaskRunner(taskRunner: TaskRunner): void;
+    private setupRootResource;
+    validateDependencyGraph(): void;
+    validateEventEmissionGraph(): void;
+    initializeStore(root: IResource<any, any, any, any, any>, config: any): void;
+    dispose(): Promise<void>;
+    processOverrides(): void;
+    storeGenericItem<C>(item: RegisterableItems): void;
+    /**
+     * Returns all tasks with the given tag.
+     * @param tag - The tag to filter by.
+     * @returns The tasks with the given tag.
+     */
+    getTasksWithTag(tag: string | ITag): ITask<any, any, any, any, TagType[], TaskMiddlewareAttachmentType[]>[];
+    getResourcesWithTag(tag: string | ITag): IResource<any, any, {}, any, any, TagType[], ResourceMiddlewareAttachmentType[]>[];
+}
+
+declare class ResourceInitializer {
+    protected readonly store: Store;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    constructor(store: Store, eventManager: EventManager, logger: Logger);
+    private readonly middlewareManager;
+    /**
+     * Begins the execution of an task. These are registered tasks and all sanity checks have been performed at this stage to ensure consistency of the object.
+     * This function can throw only if any of the event listeners or run function throws
+     */
+    initializeResource<TConfig = null, TValue extends Promise<any> = Promise<any>, TDeps extends DependencyMapType = {}, TContext = any>(resource: IResource<TConfig, TValue, TDeps>, config: TConfig, dependencies: ResourceDependencyValuesType<TDeps>): Promise<{
+        value: TValue;
+        context: TContext;
+    }>;
+    initWithMiddleware<C, V extends Promise<any>, D extends DependencyMapType, TContext>(resource: IResource<C, V, D, TContext>, config: C, dependencies: ResourceDependencyValuesType<D>, context: TContext): Promise<V | undefined>;
+}
+
+/**
+ * This class is responsible of setting up dependencies with their respective computedValues.
+ * Note that all elements must have been previously registered otherwise errors will be thrown
+ * when trying to depend on something not in the store.
+ */
+declare class DependencyProcessor {
+    protected readonly store: Store;
+    protected readonly eventManager: EventManager;
+    protected readonly taskRunner: TaskRunner;
+    protected readonly resourceInitializer: ResourceInitializer;
+    protected readonly logger: Logger;
+    constructor(store: Store, eventManager: EventManager, taskRunner: TaskRunner, logger: Logger);
+    /**
+     * This function is going to go through all the resources, tasks and middleware to compute their required dependencies.
+     */
+    computeAllDependencies(): Promise<void>;
+    private computeTaskDependencies;
+    initializeUninitializedResources(): Promise<void>;
+    /**
+     * Processes dependencies and hooks
+     * @param resource
+     */
+    protected processResourceDependencies<TD extends DependencyMapType>(resource: ResourceStoreElementType<any, any, TD>): Promise<void>;
+    private wrapResourceDependencies;
+    private makeTaskWithIntercept;
+    initializeRoot(): Promise<void>;
+    /**
+     * Processes all hooks, should run before emission of any event.
+     */
+    attachListeners(): void;
+    extractDependencies<T extends DependencyMapType>(map: T, source: string): Promise<DependencyValuesType<T>>;
+    extractDependency(object: any, source: string): Promise<any>;
+    /**
+     * Converts the event into a running functions with real inputs
+     * @param object
+     * @returns
+     */
+    extractEventDependency(object: IEvent<any>, source: string): (input: any) => Promise<void>;
+    extractTaskDependency(object: ITask<any, any, {}>): Promise<(input: unknown) => Promise<any>>;
+    extractResourceDependency(object: IResource<any, any, any>): Promise<any>;
+}
+
+/**
+ * A semaphore that limits the number of concurrent operations.
+ * Used to prevent connection pool exhaustion by limiting concurrent
+ * database operations to the pool size.
+ */
+declare class Semaphore {
+    private permits;
+    private readonly waitingQueue;
+    private disposed;
+    private readonly maxPermits;
+    constructor(maxPermits: number);
+    /**
+     * Acquire a permit. If no permits are available, waits until one becomes available.
+     */
+    acquire(options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Release a permit, allowing waiting operations to proceed.
+     */
+    release(): void;
+    private removeFromQueue;
+    /**
+     * Execute a function with a permit, automatically releasing it afterwards.
+     */
+    withPermit<T>(fn: () => Promise<T>, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /**
+     * Dispose the semaphore, rejecting all waiting operations and preventing new ones.
+     */
+    dispose(): void;
+    /**
+     * Get current number of available permits (for debugging)
+     */
+    getAvailablePermits(): number;
+    /**
+     * Get current number of waiting operations (for debugging)
+     */
+    getWaitingCount(): number;
+    /**
+     * Get maximum number of permits
+     */
+    getMaxPermits(): number;
+    /**
+     * Check if the semaphore has been disposed
+     */
+    isDisposed(): boolean;
+    /**
+     * Get metrics about the current state of the semaphore
+     */
+    getMetrics(): {
+        availablePermits: number;
+        waitingCount: number;
+        maxPermits: number;
+        utilization: number;
+        disposed: boolean;
+    };
+}
+
+/**
+ * Cooperative task queue.
+ *  • Tasks run one‑after‑another (FIFO ordering).
+ *  • Dead‑lock detection prevents nesting.
+ *  • dispose() drains or cancels outstanding tasks, then rejects new ones.
+ */
+declare class Queue {
+    private tail;
+    private disposed;
+    private abortController;
+    private readonly executionContext;
+    /**
+     * Schedule an asynchronous task.
+     * @param task – receives an AbortSignal so it can cancel early if desired.
+     */
+    run<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Disposes the queue.
+     * @param options.cancel – if true, broadcasts AbortSignal to running task.
+     *                         default: false (waits for tasks to finish).
+     */
+    dispose(options?: {
+        cancel?: boolean;
+    }): Promise<void>;
+}
+
+declare class RunResult<V> {
+    readonly value: V;
+    readonly logger: Logger;
+    readonly store: Store;
+    private readonly eventManager;
+    private readonly taskRunner;
+    private readonly disposeFn;
+    constructor(value: V, logger: Logger, store: Store, eventManager: EventManager, taskRunner: TaskRunner, disposeFn: () => Promise<void>);
+    /**
+     * Run a task within the context of the run result.
+     * @param task - The task to run.
+     * @param args - The arguments to pass to the task.
+     * @returns The result of the task.
+     */
+    runTask: <I = undefined, O extends Promise<any> = any, D extends DependencyMapType = any>(task: ITask<I, O, D> | string, ...args: I extends undefined | void ? [] : [I]) => Promise<O | undefined>;
+    /**
+     * Emit an event within the context of the run result.
+     * @param event - The event to emit.
+     * @param payload - The payload to emit.
+     */
+    emitEvent: <P>(event: IEvent<P> | string, payload?: P extends undefined | void ? undefined : P) => Promise<void>;
+    /**
+     * Get the value of a resource from the run result.
+     * @param resource - The resource to get the value of.
+     * @returns The value of the resource.
+     */
+    getResourceValue: <Output extends Promise<any>>(resource: string | IResource<any, Output, any, any, any>) => Output extends Promise<infer U> ? U : Output;
+    dispose: () => Promise<void>;
+}
+
+/**
+ * Define a task.
+ * Generates a strongly-typed task object with id, dependencies,
+ * middleware, and metadata.
+ *
+ * @typeParam Input - Input type accepted by the task's `run` function.
+ * @typeParam Output - Promise type returned by the `run` function.
+ * @typeParam Deps - Dependency map type this task requires.
+ * @typeParam TOn - Event type or "*" this task listens to.
+ * @typeParam TMeta - Arbitrary metadata type carried by the task.
+ * @param taskConfig - The task definition config.
+ * @returns A branded task definition usable by the runner.
+ */
+declare function defineTask<Input = undefined, Output extends Promise<any> = any, Deps extends DependencyMapType = any, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]>(taskConfig: ITaskDefinition<Input, Output, Deps, TMeta, TTags, TMiddleware>): ITask<Input, Output, Deps, TMeta, TTags, TMiddleware>;
+
+/**
+ * Define a hook (event listeners).
+ * Same shape as task with mandatory `on` and without `middleware`.
+ */
+declare function defineHook<D extends DependencyMapType = any, TOn extends "*" | IEventDefinition<any> | readonly IEventDefinition<any>[] = any, TMeta extends ITaskMeta = any>(hookDef: IHookDefinition<D, TOn, TMeta>): IHook<D, TOn, TMeta>;
+
+declare function defineResource<TConfig = void, TValue extends Promise<any> = Promise<any>, TDeps extends DependencyMapType = {}, TPrivate = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]>(constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate, any, any, TMeta, TTags, TMiddleware>): IResource<TConfig, TValue, TDeps, TPrivate, TMeta, TTags, TMiddleware>;
+
+declare function defineEvent<TPayload = void>(config: IEventDefinition<TPayload>): IEvent<TPayload>;
+
+declare function defineTaskMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any>(middlewareDef: ITaskMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>): ITaskMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+
+declare function defineResourceMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any>(middlewareDef: IResourceMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>): IResourceMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+
+/**
+ * Override helper that preserves the original `id` and returns the same type.
+ * You can override any property except `id`. The override is shallow-merged over the base.
+ *
+ * @param base - The base definition to override.
+ * @param patch - Properties to override (except `id`).
+ * @returns A definition of the same kind with overrides applied.
+ */
+declare function defineOverride<T extends ITask<any, any, any, any, any, any>>(base: T, patch: Omit<Partial<T>, "id"> & Pick<T, "run">): T;
+declare function defineOverride<T extends IResource<any, any, any, any, any, any>>(base: T, patch: Omit<Partial<T>, "id"> & Pick<T, "init">): T;
+declare function defineOverride<T extends ITaskMiddleware<any, any, any, any>>(base: T, patch: Omit<Partial<T>, "id">): T;
+declare function defineOverride<T extends IResourceMiddleware<any, any, any, any>>(base: T, patch: Omit<Partial<T>, "id"> & Pick<T, "run">): T;
+declare function defineOverride<T extends IHook<any, any, any>>(base: T, patch: Omit<Partial<T>, "id" | "on"> & Pick<T, "run">): T;
+
+/**
+ * Create a tag definition.
+ * - `.with(config)` to create configured instances
+ * - `.extract(tags)` to extract this tag from a list of tags or a taggable's meta
+ *
+ * @typeParam TConfig - Configuration type carried by configured tags.
+ * @typeParam TEnforceContract - Optional helper type to enforce a contract when tags are used.
+ * @param definition - The tag definition (id).
+ * @returns A tag object with helpers to configure and extract.
+ */
+declare function defineTag<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void>(definition: ITagDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract>): ITag<TConfig, TEnforceInputContract, TEnforceOutputContract>;
+
+/**
+ * This is the central function that kicks off you runner. You can run as many resources as you want in a single process, they will run in complete isolation.
+ *
+ * @param resourceOrResourceWithConfig - The resource or resource with config to run.
+ * @param options - The options for the run.
+ * @returns A promise that resolves to the result of the run.
+ */
+declare function run<C, V extends Promise<any>>(resourceOrResourceWithConfig: IResourceWithConfig<C, V> | IResource<void, V, any, any> | IResource<{
+    [K in any]?: any;
+}, V, any, any>, // For optional config
+options?: RunOptions): Promise<RunResult<V extends Promise<infer U> ? U : V>>;
+
+/**
+ * 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` instead with your testResource, as it provides the necessary toolkit.
+ */
+declare function createTestResource(root: RegisterableItems, options?: {
+    overrides?: Array<IResource | ITask | ITaskMiddleware | IResourceMiddleware | IResourceWithConfig>;
+}): IResource<void, Promise<ReturnType<typeof buildTestFacade>>>;
+declare function buildTestFacade(deps: {
+    taskRunner: TaskRunner;
+    store: Store;
+    logger: Logger;
+    eventManager: EventManager;
+}): {
+    runTask: <I, O extends Promise<any>, D extends DependencyMapType>(task: ITask<I, O, D>, ...args: I extends undefined ? [] : [I]) => Promise<Awaited<O> | undefined>;
+    getResource: (id: string) => any;
+    taskRunner: TaskRunner;
+    store: Store;
+    logger: Logger;
+    eventManager: EventManager;
+};
+
+declare const globals: {
+    events: {
+        readonly ready: IEvent<{
+            root: IResource<any, any, any, any>;
+        }>;
+        readonly unhandledError: IEvent<{
+            kind: "task" | "middleware" | "resourceInit" | "hook" | "process" | "run";
+            error: any;
+        }>;
+    };
+    resources: {
+        store: IResource<void, Promise<Store>, {}, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+        middlewareManager: IResource<void, Promise<MiddlewareManager>, {}, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+        eventManager: IResource<void, Promise<EventManager>, {}, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+        taskRunner: IResource<void, Promise<TaskRunner>, {}, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+        logger: IResource<void, Promise<Logger>, {}, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+        cache: IResource<{
+            defaultOptions?: any;
+        }, Promise<{
+            map: Map<string, ICacheInstance>;
+            cacheFactoryTask: TaskDependencyWithIntercept<any, Promise<ICacheInstance>>;
+            defaultOptions: any;
+        }>, {
+            cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, any, TagType[], TaskMiddlewareAttachmentType[]>;
+        }, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+        queue: IResource<void, Promise<{
+            map: Map<string, Queue>;
+            run: <T>(id: string, task: (signal: AbortSignal) => Promise<T>) => Promise<T>;
+        }>, {}, {
+            map: Map<string, Queue>;
+        }, {
+            title: string;
+            description: string;
+        }, TagType[], ResourceMiddlewareAttachmentType[]>;
+    };
+    middleware: {
+        requireContext: ITaskMiddleware<{
+            context: Context<any>;
+        }, void, void, any>;
+        task: {
+            requireContext: ITaskMiddleware<{
+                context: Context<any>;
+            }, void, void, any>;
+            cache: ITaskMiddleware<any, void, void, {
+                cache: IResource<{
+                    defaultOptions?: any;
+                }, Promise<{
+                    map: Map<string, ICacheInstance>;
+                    cacheFactoryTask: TaskDependencyWithIntercept<any, Promise<ICacheInstance>>;
+                    defaultOptions: any;
+                }>, {
+                    cacheFactoryTask: ITask<any, Promise<ICacheInstance>, any, any, TagType[], TaskMiddlewareAttachmentType[]>;
+                }, any, any, TagType[], ResourceMiddlewareAttachmentType[]>;
+            }>;
+            retry: ITaskMiddleware<RetryMiddlewareConfig, void, void, any>;
+            timeout: ITaskMiddleware<TimeoutMiddlewareConfig, void, void, any>;
+        };
+        resource: {
+            retry: IResourceMiddleware<RetryMiddlewareConfig, void, void, any>;
+            timeout: IResourceMiddleware<TimeoutMiddlewareConfig, void, void, any>;
+        };
+    };
+    tags: {
+        system: ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>;
+        excludeFromGlobalHooks: ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>;
+        debug: ITag<DebugFriendlyConfig, void, void>;
+    };
+};
+
+export { type Context, type DebugConfig, type DebugFriendlyConfig, DependencyProcessor, errors as Errors, type EventEmissionInterceptor, EventManager, type EventStoreElementType, type HookExecutionInterceptor, type IEventHandlerOptions, type ILog, type ILogInfo, type LogLevels, Logger, MiddlewareManager, type OnUnhandledError, type OnUnhandledErrorInfo, type PrintStrategy, Queue, ResourceInitializer, type ResourceMiddlewareInterceptor, type ResourceStoreElementType, RunResult, Semaphore, Store, type TaskMiddlewareInterceptor, TaskRunner, type TaskStoreElementType, type UnhandledErrorKind, allFalse, bindProcessErrorHandler, createContext, createDefaultUnhandledError, createTestResource, defs as definitions, defineEvent as event, getConfig, globals, defineHook as hook, levelNormal, levelVerbose, defineOverride as override, defineResource as resource, defineResourceMiddleware as resourceMiddleware, run, safeReportUnhandledError, defineTag as tag, defineTask as task, defineTaskMiddleware as taskMiddleware };