@bluelibs/runner 5.2.0 → 5.3.0

package/dist/types/definers/builders/error/fluent-builder.interface.d.ts

@@ -1,10 +1,16 @@
 import type { DefaultErrorType, IErrorMeta, IValidationSchema, IErrorHelper } from "../../../defs";
 export interface ErrorFluentBuilder<TData extends DefaultErrorType = DefaultErrorType> {
     id: string;
+    httpCode(code: number): ErrorFluentBuilder<TData>;
     serialize(fn: (data: TData) => string): ErrorFluentBuilder<TData>;
     parse(fn: (raw: string) => TData): ErrorFluentBuilder<TData>;
     dataSchema(schema: IValidationSchema<TData>): ErrorFluentBuilder<TData>;
     build(): IErrorHelper<TData>;
     format(fn: (data: TData) => string): ErrorFluentBuilder<TData>;
+    /**
+     * Attach remediation advice that explains how to fix this error.
+     * Appears in the stringified error after the main message.
+     */
+    remediation(advice: string | ((data: TData) => string)): ErrorFluentBuilder<TData>;
     meta<TNewMeta extends IErrorMeta>(m: TNewMeta): ErrorFluentBuilder<TData>;
 }

package/dist/types/definers/builders/error/index.d.ts

@@ -1,5 +1,6 @@
 import type { DefaultErrorType } from "../../../defs";
 import type { ErrorFluentBuilder } from "./fluent-builder.interface";
+import { RunnerError } from "../../defineError";
 export * from "./fluent-builder.interface";
 export * from "./fluent-builder";
 export * from "./types";
@@ -8,4 +9,12 @@ export * from "./utils";
  * Entry point for creating an error builder.
  */
 export declare function errorBuilder<TData extends DefaultErrorType = DefaultErrorType>(id: string): ErrorFluentBuilder<TData>;
-export declare const error: typeof errorBuilder;
+/**
+ * Check if an error is any Runner error (not just a specific one).
+ * @param error - The error to check
+ * @returns true if the error is a RunnerError instance
+ */
+declare function isRunnerError(error: unknown): error is RunnerError;
+export declare const error: typeof errorBuilder & {
+    is: typeof isRunnerError;
+};

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

@@ -6,7 +6,9 @@ import type { DefaultErrorType, IErrorMeta, IValidationSchema } from "../../../d
 export type BuilderState<TData extends DefaultErrorType> = Readonly<{
     id: string;
     filePath: string;
+    httpCode?: number;
     format?: (data: TData) => string;
+    remediation?: string | ((data: TData) => string);
     serialize?: (data: TData) => string;
     parse?: (raw: string) => TData;
     dataSchema?: IValidationSchema<TData>;

package/dist/types/definers/defineError.d.ts

@@ -1,9 +1,11 @@
 import { DefaultErrorType, IErrorDefinition, IErrorHelper, IErrorDefinitionFinal } from "../types/error";
 import { symbolError, symbolFilePath, symbolOptionalDependency } from "../types/symbols";
-declare class RunnerError<TData extends DefaultErrorType = DefaultErrorType> extends Error {
+export declare class RunnerError<TData extends DefaultErrorType = DefaultErrorType> extends Error {
     readonly id: string;
     readonly data: TData;
-    constructor(id: string, message: string, data: TData);
+    readonly httpCode?: number;
+    readonly remediation?: string;
+    constructor(id: string, message: string, data: TData, httpCode?: number, remediation?: string);
 }
 export declare class ErrorHelper<TData extends DefaultErrorType = DefaultErrorType> implements IErrorHelper<TData> {
     private readonly definition;
@@ -11,6 +13,7 @@ export declare class ErrorHelper<TData extends DefaultErrorType = DefaultErrorTy
     [symbolFilePath]: string;
     constructor(definition: IErrorDefinitionFinal<TData>, filePath: string);
     get id(): string;
+    get httpCode(): number | undefined;
     throw(data: TData): never;
     is(error: unknown): error is RunnerError<TData>;
     optional(): {
@@ -24,4 +27,3 @@ export declare class ErrorHelper<TData extends DefaultErrorType = DefaultErrorTy
  * @returns
  */
 export declare function defineError<TData extends DefaultErrorType = DefaultErrorType>(definition: IErrorDefinition<TData>, filePath?: string): ErrorHelper<TData>;
-export {};

package/dist/types/defs.d.ts

@@ -28,5 +28,7 @@ export * from "./types/runner";
 export * from "./types/asyncContext";
 export * from "./types/error";
 export * from "./types/contracts";
+export * from "./types/tagged";
+export * from "./types/inputFile";
 export type { ICacheInstance } from "./globals/middleware/cache.middleware";
 export * from "./types/storeTypes";

package/dist/types/globals/resources/tunnel/protocol.d.ts

@@ -3,6 +3,7 @@ export interface ProtocolErrorShape {
     code: string;
     message: string;
     details?: unknown;
+    httpCode?: number;
     id?: string;
     data?: unknown;
 }
@@ -33,11 +34,13 @@ export interface EventRequest {
 export declare class TunnelError extends Error {
     readonly code: string;
     readonly details?: unknown;
+    readonly httpCode?: number;
     readonly id?: string;
     readonly data?: unknown;
     constructor(code: string, message: string, details?: unknown, extras?: {
         id?: string;
         data?: unknown;
+        httpCode?: number;
     });
 }
 export declare function toTunnelError(input: unknown, fallbackMessage?: string): TunnelError;

package/dist/types/models/Store.d.ts

@@ -1,4 +1,4 @@
-import { IResource, RegisterableItems, ITag, ITaskMiddleware, IResourceMiddleware } from "../defs";
+import { IResource, RegisterableItems, ITag, AnyTask, ITaskMiddleware, IResourceMiddleware, TaggedTask, TaggedResource, AnyResource } from "../defs";
 import { EventManager } from "./EventManager";
 import { Logger } from "./Logger";
 import { ResourceStoreElementType, TaskStoreElementType, EventStoreElementType } from "../types/storeTypes";
@@ -66,11 +66,13 @@ export declare class Store {
      * @param tag - The tag to filter by.
      * @returns The tasks with the given tag.
      */
-    getTasksWithTag(tag: string | ITag<any, any, any>): import("..").ITask<any, any, any, any, import("..").TagType[], import("..").TaskMiddlewareAttachmentType[]>[];
+    getTasksWithTag<TTag extends ITag<any, any, any>>(tag: TTag): TaggedTask<TTag>[];
+    getTasksWithTag(tag: string): AnyTask[];
     /**
      * Returns all resources with the given tag.
      * @param tag - The tag to filter by.
      * @returns The resources with the given tag.
      */
-    getResourcesWithTag(tag: string | ITag<any, any, any>): IResource<any, any, {}, any, any, import("..").TagType[], import("..").ResourceMiddlewareAttachmentType[]>[];
+    getResourcesWithTag<TTag extends ITag<any, any, any>>(tag: TTag): TaggedResource<TTag>[];
+    getResourcesWithTag(tag: string): AnyResource[];
 }

package/dist/types/models/StoreRegistry.d.ts

@@ -1,4 +1,4 @@
-import { IResource, ITask, IResourceWithConfig, RegisterableItems, ITaskMiddleware, IResourceMiddleware, IEvent, ITag, IHook } from "../defs";
+import { IResource, ITask, AnyTask, IResourceWithConfig, RegisterableItems, ITaskMiddleware, IResourceMiddleware, IEvent, ITag, IHook, TaggedTask, TaggedResource, AnyResource } from "../defs";
 import { TaskStoreElementType, TaskMiddlewareStoreElementType, ResourceMiddlewareStoreElementType, ResourceStoreElementType, EventStoreElementType, HookStoreElementType } from "../defs";
 import { StoreValidator } from "./StoreValidator";
 import { Store } from "./Store";
@@ -39,8 +39,10 @@ export declare class StoreRegistry {
      */
     buildEventEmissionGraph(): IDependentNode[];
     private setupBlankNodes;
-    getTasksWithTag(tag: string | ITag): ITask<any, any, any, any, import("..").TagType[], import("..").TaskMiddlewareAttachmentType[]>[];
-    getResourcesWithTag(tag: string | ITag): IResource<any, any, {}, any, any, import("..").TagType[], import("..").ResourceMiddlewareAttachmentType[]>[];
+    getTasksWithTag<TTag extends ITag<any, any, any>>(tag: TTag): TaggedTask<TTag>[];
+    getTasksWithTag(tag: string): AnyTask[];
+    getResourcesWithTag<TTag extends ITag<any, any, any>>(tag: TTag): TaggedResource<TTag>[];
+    getResourcesWithTag(tag: string): AnyResource[];
     /**
      * Used to fetch the value cloned, and if we're dealing with an override, we need to extend the previous value.
      */

package/dist/types/node/durable/core/DurableResource.d.ts

@@ -1,9 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Store } from "../../../models/Store";
 import type { IEventDefinition } from "../../../types/event";
-import type { ITask } from "../../../types/task";
+import type { AnyTask, ITask } from "../../../types/task";
 import type { IDurableContext } from "./interfaces/context";
-import type { DurableTask, ExecuteOptions, IDurableService, ScheduleOptions } from "./interfaces/service";
+import type { DurableStartAndWaitResult, ExecuteOptions, IDurableService, ScheduleOptions } from "./interfaces/service";
 import type { Schedule } from "./types";
 import type { IDurableStore } from "./interfaces/store";
 import { DurableOperator } from "./DurableOperator";
@@ -11,7 +11,11 @@ import { type DurableFlowShape } from "./flowShape";
 export interface DurableResourceConfig {
     worker?: boolean;
 }
-export interface IDurableResource extends Pick<IDurableService, "startExecution" | "cancelExecution" | "wait" | "execute" | "executeStrict" | "schedule" | "ensureSchedule" | "pauseSchedule" | "resumeSchedule" | "getSchedule" | "listSchedules" | "updateSchedule" | "removeSchedule" | "recover" | "signal"> {
+export interface IDurableResource extends Pick<IDurableService, "cancelExecution" | "wait" | "schedule" | "ensureSchedule" | "pauseSchedule" | "resumeSchedule" | "getSchedule" | "listSchedules" | "updateSchedule" | "removeSchedule" | "recover" | "signal"> {
+    start<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start(task: string, input?: unknown, options?: ExecuteOptions): Promise<string>;
+    startAndWait<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
+    startAndWait<TResult = unknown>(task: string, input?: unknown, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
     /**
      * Reads the durable context for the currently running workflow execution.
      * Throws if called outside of a durable execution.
@@ -34,10 +38,14 @@ export interface IDurableResource extends Pick<IDurableService, "startExecution"
      * (steps/audit/history and operator actions where supported by the store).
      */
     readonly operator: DurableOperator;
+    /**
+     * Returns all tasks tagged as durable workflows in the current runtime.
+     */
+    getWorkflows(): AnyTask[];
 }
 /**
  * A Runner-facing wrapper around `DurableService` that exposes a per-instance
- * context store and the public durable API (`execute`, `signal`, `wait`, etc.).
+ * context store and the public durable API (`start`, `startAndWait`, `signal`, `wait`, etc.).
  *
  * This enables tasks to depend on a specific durable instance and call
  * `durable.use()` to access the per-execution durable context.
@@ -52,17 +60,23 @@ export declare class DurableResource implements IDurableResource {
     get operator(): DurableOperator;
     use(): IDurableContext;
     describe<TInput>(task: ITask<TInput, any, any, any, any, any>, input?: TInput): Promise<DurableFlowShape>;
+    getWorkflows(): AnyTask[];
     private injectRecorderIntoDurableDeps;
-    startExecution<TInput>(task: DurableTask<TInput, unknown>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start(task: string, input?: unknown, options?: ExecuteOptions): Promise<string>;
     cancelExecution(executionId: string, reason?: string): Promise<void>;
     wait<TResult>(executionId: string, options?: {
         timeout?: number;
         waitPollIntervalMs?: number;
     }): Promise<TResult>;
-    execute<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
-    executeStrict<TInput, TResult>(task: undefined extends TResult ? never : DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
-    schedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
-    ensureSchedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions & {
+    startAndWait<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
+    startAndWait<TResult = unknown>(task: string, input?: unknown, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
+    schedule<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    schedule(task: string, input: unknown, options: ScheduleOptions): Promise<string>;
+    ensureSchedule<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input: TInput | undefined, options: ScheduleOptions & {
+        id: string;
+    }): Promise<string>;
+    ensureSchedule(task: string, input: unknown, options: ScheduleOptions & {
         id: string;
     }): Promise<string>;
     pauseSchedule(scheduleId: string): Promise<void>;

package/dist/types/node/durable/core/DurableService.d.ts

@@ -1,7 +1,8 @@
 import { NoopEventBus } from "../bus/NoopEventBus";
-import type { DurableServiceConfig, DurableTask, ExecuteOptions, IDurableService, ScheduleOptions } from "./interfaces/service";
+import type { DurableStartAndWaitResult, DurableServiceConfig, ExecuteOptions, IDurableService, ScheduleOptions } from "./interfaces/service";
 import { type Schedule } from "./types";
 import type { IEventDefinition } from "../../../types/event";
+import type { ITask } from "../../../types/task";
 import { ExecutionManager, PollingManager } from "./managers";
 export { DurableExecutionError } from "./utils";
 /**
@@ -32,22 +33,27 @@ export declare class DurableService implements IDurableService {
     /** Unique worker ID for distributed timer coordination */
     private readonly workerId;
     constructor(config: DurableServiceConfig);
-    registerTask<TInput, TResult>(task: DurableTask<TInput, TResult>): void;
-    findTask(taskId: string): DurableTask<any, any> | undefined;
-    startExecution<TInput>(task: DurableTask<TInput, unknown>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    registerTask<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>): void;
+    findTask(taskId: string): ITask<any, Promise<any>, any, any, any, any> | undefined;
+    start<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start(task: string, input?: unknown, options?: ExecuteOptions): Promise<string>;
+    start(): void;
     cancelExecution(executionId: string, reason?: string): Promise<void>;
-    execute<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
-    executeStrict<TInput, TResult>(task: undefined extends TResult ? never : DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
+    startAndWait<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
+    startAndWait<TResult = unknown>(task: string, input?: unknown, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
     wait<TResult>(executionId: string, options?: {
         timeout?: number;
         waitPollIntervalMs?: number;
     }): Promise<TResult>;
-    schedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
-    ensureSchedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions & {
+    schedule<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    schedule(task: string, input: unknown, options: ScheduleOptions): Promise<string>;
+    ensureSchedule<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input: TInput | undefined, options: ScheduleOptions & {
+        id: string;
+    }): Promise<string>;
+    ensureSchedule(task: string, input: unknown, options: ScheduleOptions & {
         id: string;
     }): Promise<string>;
     recover(): Promise<void>;
-    start(): void;
     stop(): Promise<void>;
     pauseSchedule(id: string): Promise<void>;
     resumeSchedule(id: string): Promise<void>;

package/dist/types/node/durable/core/interfaces/service.d.ts

@@ -1,20 +1,17 @@
 import type { IEventDefinition } from "../../../../types/event";
+import type { ITask } from "../../../../types/task";
 import type { IDurableStore } from "./store";
 import type { IDurableQueue } from "./queue";
 import type { IEventBus } from "./bus";
 import type { IDurableContext } from "./context";
 import type { Schedule } from "../types";
 import type { DurableAuditEmitter } from "../audit";
-export interface DurableTask<TInput = unknown, TResult = unknown> {
-    id: string;
-    run(input: TInput, ...args: any[]): Promise<TResult>;
-}
 export interface ITaskExecutor {
-    run<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput): Promise<TResult>;
+    run<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput): Promise<TResult>;
 }
 export interface ScheduleConfig<TInput = unknown> {
     id: string;
-    task: DurableTask<TInput, unknown>;
+    task: ITask<TInput, Promise<any>, any, any, any, any> | string;
     cron?: string;
     interval?: number;
     input: TInput;
@@ -51,7 +48,7 @@ export interface DurableServiceConfig {
      * Resolves tasks by id for resuming/recovering executions.
      * Useful in Runner environments where tasks are registered in the Store registry.
      */
-    taskResolver?: (taskId: string) => DurableTask<any, any> | undefined;
+    taskResolver?: (taskId: string) => ITask<any, Promise<any>, any, any, any, any> | undefined;
     audit?: {
         enabled?: boolean;
         emitter?: DurableAuditEmitter;
@@ -66,7 +63,7 @@ export interface DurableServiceConfig {
         maxAttempts?: number;
         timeout?: number;
         /**
-         * When a queue is configured, `startExecution()` persists the execution and then enqueues it.
+         * When a queue is configured, `start()` persists the execution and then enqueues it.
          * If enqueue fails (eg. broker outage), the execution would otherwise remain "pending" forever.
          *
          * This delay arms a small store-backed timer as a failsafe so workers can retry resuming it
@@ -75,7 +72,7 @@ export interface DurableServiceConfig {
         kickoffFailsafeDelayMs?: number;
     };
     schedules?: ScheduleConfig[];
-    tasks?: Array<DurableTask<any, any>>;
+    tasks?: Array<ITask<any, Promise<any>, any, any, any, any>>;
 }
 export interface ExecuteOptions {
     timeout?: number;
@@ -94,8 +91,15 @@ export interface ScheduleOptions {
     cron?: string;
     interval?: number;
 }
+export interface DurableStartAndWaitResult<TResult = unknown> {
+    durable: {
+        executionId: string;
+    };
+    data: TResult;
+}
 export interface IDurableService {
-    startExecution<TInput>(task: DurableTask<TInput, unknown>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start(task: string, input?: unknown, options?: ExecuteOptions): Promise<string>;
     /**
      * Request cancellation for an execution.
      * Cancellation is cooperative: it marks the execution as cancelled and unblocks waiters,
@@ -106,24 +110,28 @@ export interface IDurableService {
         timeout?: number;
         waitPollIntervalMs?: number;
     }): Promise<TResult>;
-    execute<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
     /**
-     * A stricter alternative to `execute()` that rejects tasks whose result type
-     * includes `undefined` (including `void`, `unknown`, and `any`).
-     *
-     * This mirrors the runtime contract where `wait()`/`execute()` treat
-     * "completed without result" as an error.
+     * Starts a workflow and waits for completion.
+     * Returns the started execution id together with the workflow result payload.
      */
-    executeStrict<TInput, TResult>(task: undefined extends TResult ? never : DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
-    schedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    startAndWait<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input?: TInput, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
+    startAndWait<TResult = unknown>(task: string, input?: unknown, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<TResult>>;
+    schedule<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    schedule(task: string, input: unknown, options: ScheduleOptions): Promise<string>;
     /**
      * Idempotently create (or update) a recurring schedule (cron/interval) with a stable id.
      * Safe to call concurrently from multiple processes.
      */
-    ensureSchedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions & {
+    ensureSchedule<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>, input: TInput | undefined, options: ScheduleOptions & {
+        id: string;
+    }): Promise<string>;
+    ensureSchedule(task: string, input: unknown, options: ScheduleOptions & {
         id: string;
     }): Promise<string>;
     recover(): Promise<void>;
+    /**
+     * Starts the durable polling loop (timers/schedules processing).
+     */
     start(): void;
     stop(): Promise<void>;
     pauseSchedule(scheduleId: string): Promise<void>;

package/dist/types/node/durable/core/interfaces/store.d.ts

@@ -13,7 +13,7 @@ export interface IDurableStore {
     listIncompleteExecutions(): Promise<Execution[]>;
     /**
      * Optional execution-level idempotency mapping.
-     * If supported, allows `startExecution(..., { idempotencyKey })` to dedupe workflow starts.
+     * If supported, allows `start(..., { idempotencyKey })` to dedupe workflow starts.
      */
     getExecutionIdByIdempotencyKey?(params: {
         taskId: string;

package/dist/types/node/durable/core/managers/ExecutionManager.d.ts

@@ -1,7 +1,8 @@
 import type { IDurableStore } from "../interfaces/store";
 import type { IDurableQueue } from "../interfaces/queue";
 import type { IEventBus } from "../interfaces/bus";
-import type { DurableServiceConfig, DurableTask, ExecuteOptions, ITaskExecutor } from "../interfaces/service";
+import type { DurableStartAndWaitResult, DurableServiceConfig, ExecuteOptions, ITaskExecutor } from "../interfaces/service";
+import type { ITask } from "../../../../types/task";
 import { type Execution } from "../types";
 import type { TaskRegistry } from "./TaskRegistry";
 import type { AuditLogger } from "./AuditLogger";
@@ -37,12 +38,41 @@ export declare class ExecutionManager {
     private readonly auditLogger;
     private readonly waitManager;
     constructor(config: ExecutionManagerConfig, taskRegistry: TaskRegistry, auditLogger: AuditLogger, waitManager: WaitManager);
-    startExecution<TInput>(task: DurableTask<TInput, unknown>, input?: TInput, options?: ExecuteOptions): Promise<string>;
+    start(taskRef: string | ITask<any, Promise<any>, any, any, any, any>, input?: unknown, options?: ExecuteOptions): Promise<string>;
+    /**
+     * Start a workflow with deduplication: if the same (taskId, idempotencyKey)
+     * was already started, returns the existing executionId instead of creating
+     * a duplicate. Uses a distributed lock to prevent concurrent races.
+     */
+    private startWithIdempotencyKey;
+    private assertCanExecute;
+    private assertStoreSupportsIdempotency;
+    /**
+     * Acquires a distributed lock around the idempotency check-and-set,
+     * falling back to lock-free operation when the store has no locking support.
+     */
+    private withIdempotencyLock;
+    /**
+     * Recovery path: `setExecutionIdByIdempotencyKey` returned false (another
+     * writer won the race), so we re-read the mapping to get their executionId.
+     */
+    private resolveRacedIdempotencyKey;
+    /**
+     * Creates a new execution record, persists it to the store, and logs an
+     * audit entry. Returns the executionId.
+     */
+    private persistNewExecution;
+    /**
+     * Kicks off an execution with a failsafe timer for queue mode.
+     * If the queue enqueue succeeds, the timer is cleaned up immediately.
+     * If enqueue fails, the timer remains so the polling loop can retry later.
+     */
+    private kickoffWithFailsafe;
     cancelExecution(executionId: string, reason?: string): Promise<void>;
-    execute<TInput, TResult>(task: DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
-    executeStrict<TInput, TResult>(task: undefined extends TResult ? never : DurableTask<TInput, TResult>, input?: TInput, options?: ExecuteOptions): Promise<TResult>;
+    startAndWait(taskRef: string | ITask<any, Promise<any>, any, any, any, any>, input?: unknown, options?: ExecuteOptions): Promise<DurableStartAndWaitResult<unknown>>;
     processExecution(executionId: string): Promise<void>;
     kickoffExecution(executionId: string): Promise<void>;
     notifyExecutionFinished(execution: Execution): Promise<void>;
     private runExecutionAttempt;
+    private resolveTaskReference;
 }

package/dist/types/node/durable/core/managers/ScheduleManager.d.ts

@@ -1,7 +1,8 @@
 import type { IDurableStore } from "../interfaces/store";
-import type { DurableTask, ScheduleOptions } from "../interfaces/service";
+import type { ScheduleOptions } from "../interfaces/service";
 import { type Schedule } from "../types";
 import type { TaskRegistry } from "./TaskRegistry";
+import type { ITask } from "../../../../types/task";
 /**
  * Creates and maintains durable schedules.
  *
@@ -13,10 +14,10 @@ export declare class ScheduleManager {
     private readonly store;
     private readonly taskRegistry;
     constructor(store: IDurableStore, taskRegistry: TaskRegistry);
-    ensureSchedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions & {
+    ensureSchedule(taskRef: string | ITask<any, Promise<any>, any, any, any, any>, input: unknown, options: ScheduleOptions & {
         id: string;
     }): Promise<string>;
-    schedule<TInput>(task: DurableTask<TInput, unknown>, input: TInput | undefined, options: ScheduleOptions): Promise<string>;
+    schedule(taskRef: string | ITask<any, Promise<any>, any, any, any, any>, input: unknown, options: ScheduleOptions): Promise<string>;
     reschedule(schedule: Schedule, options?: {
         lastRunAt?: Date;
     }): Promise<void>;
@@ -30,4 +31,5 @@ export declare class ScheduleManager {
         input?: unknown;
     }): Promise<void>;
     remove(id: string): Promise<void>;
+    private resolveTaskReference;
 }

package/dist/types/node/durable/core/managers/TaskRegistry.d.ts

@@ -1,16 +1,16 @@
-import type { DurableTask } from "../interfaces/service";
+import type { ITask } from "../../../../types/task";
 /**
  * In-memory durable task registry.
  *
  * Durable executions persist only a `taskId` in the store, so the runtime needs a way
- * to resolve `taskId -> DurableTask` when resuming. This registry holds tasks that
+ * to resolve `taskId -> ITask` when resuming. This registry holds tasks that
  * were registered on the current process and optionally delegates to an external
  * resolver for tasks defined elsewhere (useful for modular apps).
  */
 export declare class TaskRegistry {
     private readonly externalResolver?;
     private readonly tasks;
-    constructor(externalResolver?: ((taskId: string) => DurableTask<any, any> | undefined) | undefined);
-    register<TInput, TResult>(task: DurableTask<TInput, TResult>): void;
-    find(taskId: string): DurableTask<any, any> | undefined;
+    constructor(externalResolver?: ((taskId: string) => ITask<any, Promise<any>, any, any, any, any> | undefined) | undefined);
+    register<TInput, TResult>(task: ITask<TInput, Promise<TResult>, any, any, any, any>): void;
+    find(taskId: string): ITask<any, Promise<any>, any, any, any, any> | undefined;
 }

package/dist/types/node/durable/core/managers/WaitManager.d.ts

@@ -12,7 +12,7 @@ export interface WaitConfig {
  * - otherwise (or on bus issues) fall back to polling the store
  *
  * The durable store remains the source of truth; this manager is purely a convenience layer
- * for callers that want `await durable.wait(...)` / `await durable.execute(...)`.
+ * for callers that want `await durable.wait(...)` / `await durable.startAndWait(...)`.
  */
 export declare class WaitManager {
     private readonly store;

package/dist/types/node/durable/index.d.ts

@@ -28,6 +28,7 @@ export { NoopEventBus } from "./bus/NoopEventBus";
 export { RedisEventBus } from "./bus/RedisEventBus";
 export { createDurableTestSetup, waitUntil } from "./test-utils";
 export type { DurableTestSetup, DurableTestSetupOptions } from "./test-utils";
+export { durableWorkflowTag, type DurableWorkflowTagConfig, } from "./tags/durableWorkflow.tag";
 export { memoryDurableResource } from "./resources/memoryDurableResource";
 export type { MemoryDurableResourceConfig } from "./resources/memoryDurableResource";
 export { redisDurableResource } from "./resources/redisDurableResource";

package/dist/types/node/durable/tags/durableWorkflow.tag.d.ts

@@ -0,0 +1,14 @@
+export interface DurableWorkflowTagConfig {
+    /**
+     * Optional domain/category to group workflows (eg. "orders", "billing").
+     */
+    category?: string;
+    /**
+     * Optional metadata for dashboards/tooling.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Marks a task as a durable workflow for runtime discovery.
+ */
+export declare const durableWorkflowTag: import("../..").ITag<DurableWorkflowTagConfig, void, void>;

package/dist/types/node/node.d.ts

@@ -4,7 +4,8 @@ import type { SerializerLike } from "../serializer";
 export { nodeExposure } from "./exposure";
 export { hasExposureContext, useExposureContext, } from "./exposure/requestContext";
 export type * from "./exposure/resourceTypes";
-export { createNodeFile } from "./files";
+export { createNodeFile, NodeInputFile } from "./files";
+export type { NodeReadable } from "./files";
 export { readInputFileToBuffer, writeInputFileToPath } from "./files";
 export { createHttpSmartClient, createHttpMixedClient } from "./http";
 export type { HttpSmartClient, HttpSmartClientAuthConfig, HttpSmartClientConfig, MixedHttpClient, MixedHttpClientAuthConfig, MixedHttpClientConfig, Readable, } from "./http";

package/dist/types/public.d.ts

@@ -193,7 +193,9 @@ export declare const r: Readonly<{
     tag: typeof import("./definers/builders/tag").tagBuilder;
     override: typeof overrideBuilder;
     asyncContext: typeof import("./definers/builders/asyncContext").asyncContextBuilder;
-    error: typeof import("./definers/builders/error").errorBuilder;
+    error: typeof import("./definers/builders/error").errorBuilder & {
+        is: (error: unknown) => error is import("./public").RunnerError;
+    };
     middleware: Readonly<{
         task: typeof import("./definers/builders/middleware").taskMiddlewareBuilder;
         resource: typeof import("./definers/builders/middleware").resourceMiddlewareBuilder;
@@ -204,6 +206,7 @@ export * from "./models";
 export * from "./globals/types";
 export * as Errors from "./errors";
 export { PlatformAdapter, setPlatform } from "./platform";
+export { RunnerError } from "./definers/defineError";
 export * from "./http-client";
 export * from "./http-fetch-tunnel.resource";
 export { Serializer, SymbolPolicy, SymbolPolicyErrorMessage, } from "./serializer";

package/dist/types/testing.d.ts

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

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

@@ -6,9 +6,16 @@ export type ErrorReference = string | IErrorHelper<any>;
 export type ThrowsList = ReadonlyArray<ErrorReference>;
 export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorType> {
     id: string;
+    httpCode?: number;
     serialize?: (data: TData) => string;
     parse?: (data: string) => TData;
     format?: (data: TData) => string;
+    /**
+     * Optional advice on how to fix the error. Appears in the stringified
+     * error message after the main message. Can be a static string or a
+     * function that receives the error data and returns a string.
+     */
+    remediation?: string | ((data: TData) => string);
     /**
      * Validate error data on throw(). If provided, data is parsed first.
      */
@@ -17,8 +24,20 @@ export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorT
 }
 export interface IErrorDefinitionFinal<TData extends DefaultErrorType> extends IErrorDefinition<TData> {
     format: (data: TData) => string;
+    httpCode?: number;
+    remediation?: string | ((data: TData) => string);
 }
 export type DefaultErrorType = Record<string, unknown>;
+/**
+ * Runtime error shape thrown by r.error()/defineError() helpers.
+ * Consumers can use helper.is(error) to narrow unknown values to this type.
+ */
+export interface IRunnerError<TData extends DefaultErrorType = DefaultErrorType> extends Error {
+    id: string;
+    httpCode?: number;
+    data: TData;
+    remediation?: string;
+}
 /**
  * Runtime helper returned by defineError()/r.error().
  * Contains helpers to throw typed errors and perform type-safe checks.
@@ -26,10 +45,12 @@ export type DefaultErrorType = Record<string, unknown>;
 export interface IErrorHelper<TData extends DefaultErrorType = DefaultErrorType> {
     /** Unique id for registration and DI */
     id: string;
+    /** Optional HTTP status code associated with this error helper */
+    httpCode?: number;
     /** 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;
+    is(error: unknown): error is IRunnerError<TData>;
     /** Brand symbol for runtime detection */
     [symbolError]: true;
     /** Return an optional dependency wrapper for this error */