@bluelibs/runner 5.1.0 → 5.2.1

package/dist/types/serializer/regexp-validator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RegExp pattern safety validation for ReDoS protection.
+ * Extracted from Serializer.ts as a standalone module.
+ */
+export interface RegExpPayload {
+    pattern: string;
+    flags: string;
+}
+export interface RegExpValidatorOptions {
+    maxPatternLength: number;
+    allowUnsafe: boolean;
+}
+/**
+ * Check if a character is a quantifier at the given position.
+ */
+export declare const isQuantifierAt: (pattern: string, index: number) => boolean;
+/**
+ * Check if a character represents a quantifier (*, +, ?, {n,m}).
+ */
+export declare const isQuantifierChar: (char: string, pattern: string, index: number) => boolean;
+/**
+ * Check if the pattern contains a bounded quantifier at the given position.
+ */
+export declare const isBoundedQuantifier: (pattern: string, index: number) => boolean;
+/**
+ * Check if a RegExp pattern is safe from ReDoS attacks.
+ * Detects nested quantifiers which are a common ReDoS vector.
+ */
+export declare const isRegExpPatternSafe: (pattern: string) => boolean;
+/**
+ * Validate and extract a RegExp payload from unknown data.
+ * Enforces pattern length limits and optional safety checks.
+ */
+export declare const assertRegExpPayload: (value: unknown, options: RegExpValidatorOptions) => RegExpPayload;

package/dist/types/serializer/serialize-utils.d.ts

@@ -0,0 +1,15 @@
+import type { TypeDefinition } from "./types";
+import type { SerializedTypeRecord, SerializedValue } from "./types";
+import type { TypeRegistry } from "./type-registry";
+export declare const serializeArrayItems: <TSerializedValue>(source: readonly unknown[], serializeNested: (value: unknown) => TSerializedValue) => TSerializedValue[];
+export declare const serializeRecordEntries: <TSerializedValue>(source: Record<string, unknown>, unsafeKeys: ReadonlySet<string>, serializeNested: (value: unknown) => TSerializedValue) => Record<string, TSerializedValue>;
+export declare function serializeTypeRecord(typeDef: TypeDefinition<unknown, unknown>, value: unknown, excludedTypeIds: string[], serializeNested: (value: unknown) => SerializedValue): SerializedTypeRecord;
+export declare function serializeTypeRecord<TSerializedValue>(typeDef: TypeDefinition<unknown, unknown>, value: unknown, excludedTypeIds: string[], serializeNested: (value: unknown) => TSerializedValue): {
+    __type: string;
+    value: TSerializedValue;
+};
+export declare function serializeSymbolValue(value: symbol, excludedTypeIds: string[], typeRegistry: TypeRegistry, serializeNested: (value: unknown) => SerializedValue): SerializedValue;
+export declare function serializeSymbolValue<TSerializedValue>(value: symbol, excludedTypeIds: string[], typeRegistry: TypeRegistry, serializeNested: (value: unknown) => TSerializedValue): {
+    __type: string;
+    value: TSerializedValue;
+};

package/dist/types/serializer/special-values.d.ts

@@ -0,0 +1,20 @@
+import type { SerializedValue } from "./types";
+export declare enum SpecialTypeId {
+    Undefined = "Undefined",
+    NonFiniteNumber = "NonFiniteNumber",
+    BigInt = "BigInt",
+    Symbol = "Symbol"
+}
+export declare enum NonFiniteNumberTag {
+    NaN = "NaN",
+    Infinity = "Infinity",
+    NegativeInfinity = "-Infinity"
+}
+export declare const serializeUndefined: () => SerializedValue;
+export type BigIntPayload = string;
+export declare const serializeBigIntPayload: (value: bigint) => BigIntPayload;
+export declare const assertBigIntPayload: (value: unknown) => BigIntPayload;
+export declare const serializeBigInt: (value: bigint) => SerializedValue;
+export declare const getNonFiniteNumberTag: (value: number) => NonFiniteNumberTag | null;
+export declare const serializeNonFiniteNumber: (value: number) => SerializedValue;
+export declare const assertNonFiniteNumberTag: (value: unknown) => NonFiniteNumberTag;

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

@@ -0,0 +1,20 @@
+/**
+ * Tree-mode serialization without circular reference support.
+ * Used by stringify() for simple JSON-compatible output.
+ * Extracted from Serializer.ts as a standalone module.
+ */
+import type { TypeRegistry } from "./type-registry";
+export interface TreeSerializeContext {
+    stack: WeakSet<object>;
+    serializingValueTypes: WeakSet<object>;
+    excludedTypeIds: string[];
+}
+export interface TreeSerializerOptions {
+    maxDepth: number;
+    unsafeKeys: ReadonlySet<string>;
+    typeRegistry: TypeRegistry;
+}
+/**
+ * Serialize a value in tree mode (throws on circular references).
+ */
+export declare const serializeTreeValue: (value: unknown, context: TreeSerializeContext, depth: number, options: TreeSerializerOptions) => unknown;

package/dist/types/serializer/type-registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Type registry for managing custom serialization types.
+ * Extracted from Serializer.ts as a standalone module.
+ */
+import type { TypeDefinition } from "./types";
+import { SymbolPolicy } from "./types";
+import { type RegExpValidatorOptions } from "./regexp-validator";
+export interface TypeRegistryOptions {
+    allowedTypes: ReadonlySet<string> | null;
+    regExpValidator: RegExpValidatorOptions;
+    symbolPolicy: SymbolPolicy;
+}
+/**
+ * Registry for managing custom type definitions.
+ */
+export declare class TypeRegistry {
+    private readonly typeRegistry;
+    private readonly typeMap;
+    private typeList;
+    private readonly allowedTypes;
+    private readonly regExpOptions;
+    private readonly symbolPolicy;
+    constructor(options: TypeRegistryOptions);
+    /**
+     * Get the list of registered types for iteration.
+     */
+    getTypeList(): readonly TypeDefinition<unknown, unknown>[];
+    /**
+     * @internal - Map-like get() for test compatibility.
+     */
+    get(typeId: string): TypeDefinition<unknown, unknown> | undefined;
+    /**
+     * Register a custom type definition.
+     */
+    addType<TInstance, TSerialized>(typeDef: TypeDefinition<TInstance, TSerialized>): void;
+    addType<TJson = unknown, TInstance = unknown>(name: string, factory: (json: TJson) => TInstance): void;
+    /**
+     * Find a type definition that matches the given value.
+     */
+    findTypeDefinition(value: unknown, excludedTypeIds: readonly string[]): TypeDefinition<unknown, unknown> | undefined;
+    /**
+     * Get a type definition by ID with allowed types enforcement.
+     */
+    getTypeDefinition(typeId: string): TypeDefinition<unknown, unknown>;
+    /**
+     * Deserialize typed data with special handling for RegExp.
+     */
+    deserializeType(typeDef: TypeDefinition<unknown, unknown>, typeId: string, data: unknown): unknown;
+    /**
+     * Check if a type's serialized payload matches the type itself.
+     * Used to prevent recursive type application.
+     */
+    shouldExcludeTypeFromPayload(typeDef: TypeDefinition<unknown, unknown>, serializedPayload: unknown): boolean;
+    private registerBuiltInTypes;
+    private refreshTypeCache;
+    private assertSymbolPolicyValue;
+    private assertSymbolPolicy;
+}

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

@@ -0,0 +1,126 @@
+/**
+ * Type definitions for the Serializer class
+ */
+/**
+ * Definition for a custom type that can be serialized/deserialized
+ */
+export interface TypeDefinition<TInstance = unknown, TSerialized = unknown> {
+    /** Unique identifier for the type */
+    id: string;
+    /** Predicate function to check if an object matches this type */
+    is: (obj: unknown) => obj is TInstance;
+    /** Function to serialize the object */
+    serialize: (obj: TInstance) => TSerialized;
+    /** Function to deserialize the data back to the original object */
+    deserialize: (data: TSerialized) => TInstance;
+    /** Optional factory used to create a placeholder during deserialization */
+    create?: () => TInstance;
+    /** Serialization strategy: 'value' (inline, no identity) or 'ref' (graph node, identity preserved). Default: 'ref' */
+    strategy?: "value" | "ref";
+}
+/** Reference to another object in the serialization */
+export interface ObjectReference {
+    /** Reference to object ID */
+    __ref: string;
+}
+/**
+ * Discriminated union describing the serialized graph payload.
+ * Each node captures either an array, plain object, or typed payload.
+ */
+export type SerializedNode = {
+    kind: "array";
+    value: SerializedValue[];
+} | {
+    kind: "object";
+    value: Record<string, SerializedValue>;
+} | {
+    kind: "type";
+    type: string;
+    value: SerializedValue;
+};
+/**
+ * Serialization context for tracking object references
+ */
+export interface SerializationContext {
+    /** Map of objects to their IDs */
+    objectIds: WeakMap<object, string>;
+    /** Counter for generating unique IDs */
+    idCounter: number;
+    /** Number of graph nodes recorded */
+    nodeCount: number;
+    /** Nodes collected during serialization (id -> serialized node) */
+    nodes: Record<string, SerializedNode>;
+}
+/**
+ * Deserialization context used when materialising a graph payload.
+ */
+export interface DeserializationContext {
+    nodes: Record<string, SerializedNode>;
+    resolved: Map<string, unknown>;
+    resolving: Set<string>;
+    /**
+     * Tracks reference ids that were requested while still being resolved.
+     * Used to detect circular references that rely on placeholders.
+     */
+    resolvingRefs: Set<string>;
+}
+/**
+ * Union type for serialized values
+ */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface SerializedTypeRecord {
+    __type: string;
+    value: SerializedValue;
+}
+export type SerializedValue = JsonPrimitive | ObjectReference | SerializedTypeRecord | SerializedValue[] | {
+    [key: string]: SerializedValue;
+};
+/**
+ * Envelope saved to disk/wire when serialising a graph payload.
+ */
+export interface SerializedGraph {
+    __graph: true;
+    version: number;
+    root: SerializedValue;
+    nodes: Record<string, SerializedNode>;
+}
+export declare enum SymbolPolicy {
+    AllowAll = "AllowAll",
+    WellKnownOnly = "WellKnownOnly",
+    Disabled = "Disabled"
+}
+export declare enum SymbolPolicyErrorMessage {
+    GlobalSymbolsNotAllowed = "Global symbols are not allowed",
+    SymbolsNotAllowed = "Symbols are not allowed",
+    UnsupportedSymbolPolicy = "Unsupported symbol policy"
+}
+/**
+ * Main serializer options
+ */
+export interface SerializerOptions {
+    /** Whether to pretty-print JSON (for debugging) */
+    pretty?: boolean;
+    /** Maximum recursion depth allowed during serialize/deserialize */
+    maxDepth?: number;
+    /** Restrict deserialization to this list of type IDs */
+    allowedTypes?: readonly string[];
+    /** Controls which Symbol payloads may be deserialized */
+    symbolPolicy?: SymbolPolicy;
+    /** Maximum accepted RegExp pattern length during deserialization */
+    maxRegExpPatternLength?: number;
+    /** Allow RegExp patterns that fail the safety heuristic */
+    allowUnsafeRegExp?: boolean;
+}
+/**
+ * Minimal serializer contract used across transports and persistence.
+ * Implementations must be able to round-trip JSON-compatible payloads and
+ * should support custom value types via `addType`.
+ */
+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;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Validation helpers and type guards for serialization.
+ * Extracted from Serializer.ts as a standalone module.
+ */
+import type { ObjectReference, SerializedGraph, SerializedNode } from "./types";
+/** Default keys to block for prototype pollution protection */
+export declare const DEFAULT_UNSAFE_KEYS: Set<string>;
+/**
+ * Check if a key is unsafe (can lead to prototype pollution).
+ */
+export declare const isUnsafeKey: (key: string, unsafeKeys?: ReadonlySet<string>) => boolean;
+/**
+ * Check if a value is an object reference (has __ref property).
+ */
+export declare const isObjectReference: (value: unknown) => value is ObjectReference;
+/**
+ * Check if a value is a serialized graph payload.
+ */
+export declare const isGraphPayload: (value: unknown) => value is SerializedGraph;
+/**
+ * Check if a value is a serialized type record ({ __type, value }).
+ */
+export declare const isSerializedTypeRecord: (value: unknown) => value is {
+    __type: string;
+    value: unknown;
+};
+/**
+ * Convert nodes object to a safe record with null prototype.
+ */
+export declare const toNodeRecord: (nodes: Record<string, SerializedNode>, unsafeKeys?: ReadonlySet<string>) => Record<string, SerializedNode>;
+/**
+ * Assert that recursion depth is within limits.
+ */
+export declare const assertDepth: (depth: number, maxDepth: number) => void;

package/dist/types/testing.d.ts

@@ -0,0 +1,19 @@
+import { IResource, IResourceWithConfig, ITaskMiddleware, IResourceMiddleware, ITask, RegisterableItems, DependencyMapType } from "./defs";
+import { EventManager, Logger, Store, TaskRunner } from "./models";
+export interface TestFacade {
+    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) => unknown;
+    taskRunner: TaskRunner;
+    store: Store;
+    logger: Logger;
+    eventManager: EventManager;
+}
+/**
+ * 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.
+ */
+export declare function createTestResource(root: RegisterableItems, options?: {
+    overrides?: Array<IResource | ITask | ITaskMiddleware | IResourceMiddleware | IResourceWithConfig>;
+}): IResource<void, Promise<TestFacade>>;

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

@@ -0,0 +1,9 @@
+import { RunnerMode } from "../types/runner";
+/**
+ * Detects the runner mode based on environment variables.
+ * If no mode is explicitly provided, it will auto-detect from NODE_ENV.
+ *
+ * @param explicitMode - Optional mode to use if provided (takes precedence over environment)
+ * @returns The detected runner mode
+ */
+export declare function detectRunnerMode(explicitMode?: RunnerMode): RunnerMode;

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

@@ -0,0 +1 @@
+export declare function getCallerFile(): string;

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

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

package/dist/types/tunnels/buildUniversalManifest.d.ts

@@ -0,0 +1,24 @@
+import type { Readable } from "stream";
+import type { InputFileMeta } from "../types/inputFile";
+export interface NodeCollectedFile {
+    id: string;
+    meta: InputFileMeta;
+    source: {
+        type: "buffer";
+        buffer: Buffer;
+    } | {
+        type: "stream";
+        stream: Readable;
+    };
+}
+export interface WebCollectedFile {
+    id: string;
+    meta: InputFileMeta;
+    blob: Blob;
+}
+export interface BuiltUniversalManifest<T = unknown> {
+    input: T;
+    nodeFiles: NodeCollectedFile[];
+    webFiles: WebCollectedFile[];
+}
+export declare function buildUniversalManifest<T = unknown>(input: T): BuiltUniversalManifest<T>;

package/dist/types/types/asyncContext.d.ts

@@ -0,0 +1,41 @@
+import { symbolAsyncContext, symbolFilePath } from "./symbols";
+import { ITaskMiddlewareConfigured } from "./taskMiddleware";
+import type { IValidationSchema, IOptionalDependency } from "./utilities";
+import type { IAsyncContextMeta } from "./meta";
+export interface IAsyncContextDefinition<T> {
+    id: string;
+    serialize?(data: T): string;
+    parse?(data: string): T;
+    /**
+     * When provided, context values will be validated when provide() is called.
+     */
+    configSchema?: IValidationSchema<T>;
+    meta?: IAsyncContextMeta;
+}
+/**
+ * The generic AsyncContext object returned by `defineAsyncContext`.
+ */
+export interface IAsyncContext<T> {
+    /** unique symbol used as key in the AsyncLocalStorage map */
+    readonly id: string;
+    /** Brand marker for registration and runtime checks */
+    [symbolAsyncContext]: true;
+    /** 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.
+     */
+    require(): ITaskMiddlewareConfigured<{
+        context: IAsyncContext<T>;
+    }>;
+    serialize(data: T): string;
+    parse(data: string): T;
+    /** Return an optional dependency wrapper for this context */
+    optional(): IOptionalDependency<IAsyncContext<T>>;
+    /** File path where this async context was defined */
+    [symbolFilePath]: string;
+}

package/dist/types/types/contracts.d.ts

@@ -0,0 +1,62 @@
+import { TagType } from "./tag";
+import type { UnionToIntersection } from "./utilities";
+export declare const CONTRACT: unique symbol;
+export type CONTRACT = typeof CONTRACT;
+export interface IContractable<TConfig = any, TInput = void, TOutput = void> {
+    readonly __containsContract: true;
+    readonly [CONTRACT]: {
+        config: TConfig;
+        input: TInput;
+        output: TOutput;
+    };
+}
+export type NonVoid<T> = [T] extends [void] ? never : T;
+export type IsTuple<T extends readonly unknown[]> = number extends T["length"] ? false : true;
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type IsUnknown<T> = unknown extends T ? [T] extends [unknown] ? true : false : false;
+export type UnknownToNever<T> = IsUnknown<T> extends true ? never : T;
+export type ExtractContractOf<T, Kind extends "input" | "output"> = T extends IContractable<any, infer I, infer O> ? UnknownToNever<Kind extends "input" ? NonVoid<I> : NonVoid<O>> : never;
+export 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;
+export type ExtractContractsFromCollection<TItems extends readonly unknown[], Kind extends "input" | "output"> = IsTuple<TItems> extends true ? FilterContractsKind<TItems, Kind> : Array<ExtractContractOf<TItems[number], Kind>>;
+export type ExtractInputTypeFromContracts<TItems extends readonly unknown[]> = ExtractContractsFromCollection<TItems, "input">;
+export type ExtractOutputTypeFromContracts<TItems extends readonly unknown[]> = ExtractContractsFromCollection<TItems, "output">;
+export type ContractsUnionInputs<TItems extends readonly unknown[]> = ExtractInputTypeFromContracts<TItems> extends readonly (infer U)[] ? U : never;
+export type ContractsUnionOutputs<TItems extends readonly unknown[]> = ExtractOutputTypeFromContracts<TItems> extends readonly (infer U)[] ? U : never;
+export type ContractsIntersectionInputs<TItems extends readonly unknown[]> = UnionToIntersection<ContractsUnionInputs<TItems>>;
+export type ContractsIntersectionOutputs<TItems extends readonly unknown[]> = UnionToIntersection<ContractsUnionOutputs<TItems>>;
+export type HasInputContracts<TItems extends readonly unknown[]> = [
+    ContractsUnionInputs<TItems>
+] extends [never] ? false : true;
+export type HasOutputContracts<TItems extends readonly unknown[]> = [
+    ContractsUnionOutputs<TItems>
+] extends [never] ? false : true;
+export type IsNever<T> = [T] extends [never] ? true : false;
+export type KeysWithNever<T> = T extends object ? {
+    [K in keyof T]-?: [T[K]] extends [never] ? K : never;
+}[keyof T] : never;
+export type HasNeverProperty<T> = KeysWithNever<T> extends never ? false : true;
+export type IsImpossibleIntersection<T> = IsNever<T> extends true ? true : HasNeverProperty<T> extends true ? true : false;
+export type InputContractViolationError<TItems extends readonly unknown[], TActual> = {
+    message: "Value does not satisfy all input contracts";
+    expected: Simplify<ContractsIntersectionInputs<TItems>>;
+    received: TActual;
+};
+export type OutputContractViolationError<TItems extends readonly unknown[], TActual> = {
+    message: "Value does not satisfy all output contracts";
+    expected: Simplify<ContractsIntersectionOutputs<TItems>>;
+    received: TActual;
+};
+export 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>;
+export 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>;
+export type InferInputOrViolationFromContracts<TItems extends readonly unknown[]> = HasInputContracts<TItems> extends false ? void : ContractsIntersectionInputs<TItems> extends infer I ? IsImpossibleIntersection<I> extends true ? InputContractViolationError<TItems, Simplify<I extends never ? never : I>> : Simplify<I> : never;
+export type InputArg<TItems extends readonly unknown[]> = [
+    InferInputOrViolationFromContracts<TItems>
+] extends [void] ? [] : [InferInputOrViolationFromContracts<TItems>];
+export type InputCollisionGuard<TItems extends readonly unknown[]> = IsImpossibleIntersection<ContractsIntersectionInputs<TItems>> extends true ? InputContractViolationError<TItems, Simplify<ContractsIntersectionInputs<TItems>>> : unknown;
+export type InferOutputOrViolationFromContracts<TItems extends readonly unknown[]> = HasOutputContracts<TItems> extends false ? unknown : ContractsIntersectionOutputs<TItems> extends infer O ? IsImpossibleIntersection<O> extends true ? OutputContractViolationError<TItems, Simplify<O extends never ? never : O>> : Simplify<O> : never;
+/** @deprecated Use ExtractOutputTypeFromContracts instead */
+export type ExtractTagsWithNonVoidReturnTypeFromTags<TTags extends TagType[]> = ExtractOutputTypeFromContracts<TTags>;
+/** @deprecated Use EnsureOutputSatisfiesContracts instead */
+export type EnsureResponseSatisfiesContracts<TTags extends TagType[], TResponse> = EnsureOutputSatisfiesContracts<TTags, TResponse>;

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

@@ -0,0 +1,39 @@
+import { symbolError, symbolFilePath } from "./symbols";
+import type { IOptionalDependency } from "./utilities";
+import type { IValidationSchema } from "./utilities";
+import type { IErrorMeta } from "./meta";
+export type ErrorReference = string | IErrorHelper<any>;
+export type ThrowsList = ReadonlyArray<ErrorReference>;
+export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorType> {
+    id: string;
+    serialize?: (data: TData) => string;
+    parse?: (data: string) => TData;
+    format?: (data: TData) => string;
+    /**
+     * Validate error data on throw(). If provided, data is parsed first.
+     */
+    dataSchema?: IValidationSchema<TData>;
+    meta?: IErrorMeta;
+}
+export interface IErrorDefinitionFinal<TData extends DefaultErrorType> extends IErrorDefinition<TData> {
+    format: (data: TData) => string;
+}
+export type DefaultErrorType = Record<string, unknown>;
+/**
+ * Runtime helper returned by defineError()/r.error().
+ * Contains helpers to throw typed errors and perform type-safe checks.
+ */
+export interface IErrorHelper<TData extends DefaultErrorType = DefaultErrorType> {
+    /** Unique id for registration and DI */
+    id: string;
+    /** Throw a typed error with the given data */
+    throw(data: TData): never;
+    /** Type guard for checking if an unknown error is this error */
+    is(error: unknown): boolean;
+    /** Brand symbol for runtime detection */
+    [symbolError]: true;
+    /** Return an optional dependency wrapper for this error */
+    optional(): IOptionalDependency<IErrorHelper<TData>>;
+    /** File path where this error was defined */
+    [symbolFilePath]: string;
+}

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

@@ -0,0 +1,79 @@
+import { IOptionalDependency, IValidationSchema } from "./utilities";
+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 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.
+ */
+export declare function isOneOf<TDefs extends readonly IEventDefinition<any>[]>(emission: IEventEmission<any>, defs: TDefs): emission is IEventEmission<CommonPayload<TDefs>>;
+export 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[];
+    /**
+     * If true, listeners with the same priority run concurrently within a batch.
+     * Batches (grouped by order) still execute sequentially in priority order.
+     */
+    parallel?: boolean;
+}
+/**
+ * The definioten of the event.
+ * This is different from the event emission.
+ */
+export 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
+ */
+export 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[];
+}

package/dist/types/types/executionJournal.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Typed key used to store/retrieve values from an ExecutionJournal.
+ * The `id` is used as the storage slot.
+ */
+declare const journalKeyBrand: unique symbol;
+export type JournalKey<T> = {
+    readonly id: string;
+    readonly [journalKeyBrand]?: (value: T) => T;
+};
+/**
+ * Options for setting values in the journal.
+ */
+export interface JournalSetOptions {
+    /**
+     * If true, allows overwriting an existing value.
+     * By default, attempting to set a key that already exists will throw an error.
+     */
+    override?: boolean;
+}
+/**
+ * Per-execution registry that allows middleware and tasks to share state.
+ * A new journal is created for each top-level task execution unless explicitly forwarded.
+ */
+export interface ExecutionJournal {
+    set<T>(key: JournalKey<T>, value: T, options?: JournalSetOptions): void;
+    get<T>(key: JournalKey<T>): T | undefined;
+    has<T>(key: JournalKey<T>): boolean;
+}
+export {};

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

@@ -0,0 +1,23 @@
+import { DependencyMapType, DependencyValuesType, ExtractEventPayload } from "./utilities";
+import { IEventDefinition, IEventEmission } from "./event";
+import { TagType } from "./tag";
+import { ITaskMeta } from "./meta";
+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> {
+    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> : ExtractEventPayload<TOn>>, dependencies: DependencyValuesType<TDependencies>) => Promise<any>;
+    tags?: TagType[];
+}
+export 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[];
+}