@bluelibs/runner 5.2.0 → 5.3.0

package/dist/node/node.cjs

@@ -221,6 +221,7 @@ function toTunnelError(input, fallbackMessage) {
       const pe = input;
       const msg = pe.message || fallbackMessage || "Tunnel error";
       return new TunnelError(pe.code, msg, pe.details, {
+        httpCode: pe.httpCode,
         id: pe.id,
         data: pe.data
       });
@@ -266,6 +267,7 @@ var init_protocol = __esm({
         this.name = "TunnelError";
         this.code = code;
         this.details = details;
+        this.httpCode = extras?.httpCode;
         this.id = extras?.id;
         this.data = extras?.data;
       }
@@ -28615,9 +28617,7 @@ var symbolPhantomTask = Symbol.for(
   "runner.task.phantom"
 );
 var symbolResource = Symbol.for("runner.resource");
-var symbolResourceForkedFrom = Symbol.for(
-  "runner.resourceForkedFrom"
-);
+var symbolForkedFrom = Symbol.for("runner.forkedFrom");
 var symbolResourceWithConfig = Symbol.for(
   "runner.resourceWithConfig"
 );
@@ -28684,13 +28684,13 @@ __export(defs_exports, {
   symbolError: () => symbolError,
   symbolEvent: () => symbolEvent,
   symbolFilePath: () => symbolFilePath,
+  symbolForkedFrom: () => symbolForkedFrom,
   symbolHook: () => symbolHook,
   symbolMiddleware: () => symbolMiddleware,
   symbolMiddlewareConfigured: () => symbolMiddlewareConfigured,
   symbolOptionalDependency: () => symbolOptionalDependency,
   symbolPhantomTask: () => symbolPhantomTask,
   symbolResource: () => symbolResource,
-  symbolResourceForkedFrom: () => symbolResourceForkedFrom,
   symbolResourceMiddleware: () => symbolResourceMiddleware,
   symbolResourceWithConfig: () => symbolResourceWithConfig,
   symbolTag: () => symbolTag,
@@ -28895,12 +28895,26 @@ __export(errors_exports, {
 });
 
 // src/definers/defineError.ts
+var isValidHttpCode = /* @__PURE__ */ __name((value) => Number.isInteger(value) && value >= 100 && value <= 599, "isValidHttpCode");
+var assertHttpCode = /* @__PURE__ */ __name((value) => {
+  if (!isValidHttpCode(value)) {
+    throw new Error(
+      `Error httpCode must be an integer between 100 and 599. Received: ${value}`
+    );
+  }
+}, "assertHttpCode");
 var RunnerError = class extends Error {
-  constructor(id2, message, data) {
-    super(message);
+  constructor(id2, message, data, httpCode, remediation) {
+    super(
+      remediation !== void 0 ? `${message}
+
+Remediation: ${remediation}` : message
+    );
     this.id = id2;
     this.data = data;
     this.name = id2;
+    this.httpCode = httpCode;
+    this.remediation = remediation;
   }
   static {
     __name(this, "RunnerError");
@@ -28920,10 +28934,20 @@ var ErrorHelper = class {
   get id() {
     return this.definition.id;
   }
+  get httpCode() {
+    return this.definition.httpCode;
+  }
   throw(data) {
     const parsed = this.definition.dataSchema ? this.definition.dataSchema.parse(data) : data;
     const message = this.definition.format(parsed);
-    throw new RunnerError(this.definition.id, message, parsed);
+    const remediation = typeof this.definition.remediation === "function" ? this.definition.remediation(parsed) : this.definition.remediation;
+    throw new RunnerError(
+      this.definition.id,
+      message,
+      parsed,
+      this.definition.httpCode,
+      remediation
+    );
   }
   is(error2) {
     return error2 instanceof RunnerError && error2.name === this.definition.id;
@@ -28936,6 +28960,9 @@ var ErrorHelper = class {
   }
 };
 function defineError(definition, filePath) {
+  if (definition.httpCode !== void 0) {
+    assertHttpCode(definition.httpCode);
+  }
   if (!definition.format) {
     definition.format = (data) => `${JSON.stringify(data)}`;
   }
@@ -28957,9 +28984,22 @@ function clone(s, patch) {
 __name(clone, "clone");
 
 // src/definers/builders/error/fluent-builder.ts
+var isValidHttpCode2 = /* @__PURE__ */ __name((value) => Number.isInteger(value) && value >= 100 && value <= 599, "isValidHttpCode");
+var assertHttpCode2 = /* @__PURE__ */ __name((value) => {
+  if (!isValidHttpCode2(value)) {
+    throw new Error(
+      `Error httpCode must be an integer between 100 and 599. Received: ${value}`
+    );
+  }
+}, "assertHttpCode");
 function makeErrorBuilder(state) {
   const builder = {
     id: state.id,
+    httpCode(code) {
+      assertHttpCode2(code);
+      const next = clone(state, { httpCode: code });
+      return makeErrorBuilder(next);
+    },
     serialize(fn) {
       const next = clone(state, { serialize: fn });
       return makeErrorBuilder(next);
@@ -28976,6 +29016,10 @@ function makeErrorBuilder(state) {
       const next = clone(state, { format: fn });
       return makeErrorBuilder(next);
     },
+    remediation(advice) {
+      const next = clone(state, { remediation: advice });
+      return makeErrorBuilder(next);
+    },
     meta(m) {
       const next = clone(state, { meta: m });
       return makeErrorBuilder(next);
@@ -28984,10 +29028,12 @@ function makeErrorBuilder(state) {
       return defineError(
         {
           id: state.id,
+          httpCode: state.httpCode,
           serialize: state.serialize,
           parse: state.parse,
           dataSchema: state.dataSchema,
           format: state.format,
+          remediation: state.remediation,
           meta: state.meta
         },
         state.filePath
@@ -29004,6 +29050,7 @@ function errorBuilder(id2) {
   const initial = Object.freeze({
     id: id2,
     filePath,
+    httpCode: void 0,
     serialize: void 0,
     parse: void 0,
     dataSchema: void 0,
@@ -29012,7 +29059,13 @@ function errorBuilder(id2) {
   return makeErrorBuilder(initial);
 }
 __name(errorBuilder, "errorBuilder");
-var error = errorBuilder;
+function isRunnerError(error2) {
+  return error2 instanceof RunnerError;
+}
+__name(isRunnerError, "isRunnerError");
+var error = Object.assign(errorBuilder, {
+  is: isRunnerError
+});
 
 // src/platform/adapters/node-als.ts
 async function loadAsyncLocalStorageClass() {
@@ -29443,9 +29496,13 @@ var PlatformAdapter = class {
 // src/errors.ts
 var duplicateRegistrationError = error("runner.errors.duplicateRegistration").format(
   ({ type, id: id2 }) => `${type} "${id2.toString()}" already registered. You might have used the same 'id' in two different components or you may have registered the same element twice.`
+).remediation(
+  ({ type }) => `Ensure each ${type} has a unique id. If you need the same definition in multiple places, use .fork() to create a copy with a new id.`
 ).build();
 var dependencyNotFoundError = error("runner.errors.dependencyNotFound").format(
   ({ key }) => `Dependency ${key.toString()} not found. Did you forget to register it through a resource?`
+).remediation(
+  ({ key }) => `Register the dependency "${key.toString()}" in a parent resource using .register([${key.toString()}]). If the dependency is optional, use .optional() when declaring it.`
 ).build();
 var unknownItemTypeError = error(
   "runner.errors.unknownItemType"
@@ -29453,10 +29510,14 @@ var unknownItemTypeError = error(
   ({ item }) => `Unknown item type: ${String(
     item
   )}. Please ensure you are not using different versions of '@bluelibs/runner'`
+).remediation(
+  "Check that all packages depend on the same version of '@bluelibs/runner'. Run 'npm ls @bluelibs/runner' to detect duplicates."
 ).build();
 var contextError = error(
   "runner.errors.context"
-).format(({ details }) => details ?? "Context error").build();
+).format(({ details }) => details ?? "Context error").remediation(
+  "Verify the async context is registered in a parent resource and that .provide() was called before .use(). If the context is optional, use .optional() when declaring the dependency."
+).build();
 var circularDependenciesError = error("runner.errors.circularDependencies").format(({ cycles }) => {
   const cycleDetails = cycles.map((cycle) => `  \u2022 ${cycle}`).join("\n");
   const hasMiddleware = cycles.some((cycle) => cycle.includes("middleware"));
@@ -29469,36 +29530,54 @@ var circularDependenciesError = error("runner.errors.circularDependencies").form
   }
   return `Circular dependencies detected:
 ${cycleDetails}${guidance}`;
-}).build();
+}).remediation(
+  "Break the cycle by extracting shared state into a new resource that both sides depend on, or use events for indirect communication."
+).build();
 var eventNotFoundError = error(
   "runner.errors.eventNotFound"
 ).format(
   ({ id: id2 }) => `Event "${id2.toString()}" not found. Did you forget to register it?`
+).remediation(
+  ({ id: id2 }) => `Add the event "${id2.toString()}" to a parent resource via .register([yourEvent]). Ensure the event definition is built with r.event("${id2.toString()}").build().`
 ).build();
 var resourceNotFoundError = error(
   "runner.errors.resourceNotFound"
 ).format(
   ({ id: id2 }) => `Resource "${id2.toString()}" not found. Did you forget to register it or are you using the correct id?`
+).remediation(
+  ({ id: id2 }) => `Register the resource "${id2.toString()}" in a parent resource via .register([yourResource]). Verify the id string matches exactly (ids are case-sensitive).`
 ).build();
 var middlewareNotRegisteredError = error("runner.errors.middlewareNotRegistered").format(
   ({ type, source, middlewareId }) => `Middleware inside ${type} "${source}" depends on "${middlewareId}" but it's not registered. Did you forget to register it?`
+).remediation(
+  ({ middlewareId }) => `Register the middleware "${middlewareId}" alongside its consumer in a parent resource via .register([yourMiddleware]).`
 ).build();
 var tagNotFoundError = error(
   "runner.errors.tagNotFound"
 ).format(
   ({ id: id2 }) => `Tag "${id2}" not registered. Did you forget to register it inside a resource?`
+).remediation(
+  ({ id: id2 }) => `Register the tag "${id2}" in a parent resource via .register([yourTag]). Tags must be registered before they can be queried.`
 ).build();
 var lockedError = error(
   "runner.errors.locked"
 ).format(
   ({ what }) => `Cannot modify the ${what.toString()} when it is locked.`
+).remediation(
+  ({ what }) => `The ${what.toString()} is locked after initialization. Perform all modifications before calling run().`
 ).build();
 var storeAlreadyInitializedError = error(
   "runner.errors.storeAlreadyInitialized"
-).format(() => "Store already initialized. Cannot reinitialize.").build();
+).format(() => "Store already initialized. Cannot reinitialize.").remediation(
+  "Do not call run() more than once on the same resource tree. Create a fresh resource if you need a separate runtime."
+).build();
 var validationError = error("runner.errors.validation").format(({ subject, id: id2, originalError }) => {
   const errorMessage2 = originalError instanceof Error ? originalError.message : String(originalError);
   return `${subject} validation failed for ${id2.toString()}: ${errorMessage2}`;
+}).remediation(({ subject, id: id2 }) => {
+  const lower = subject.toLowerCase();
+  const schemaHint = lower.includes("input") ? "inputSchema" : lower.includes("config") ? "configSchema" : lower.includes("result") ? "resultSchema" : "schema";
+  return `Check the ${subject} passed to "${id2.toString()}". Ensure it matches the schema defined via .${schemaHint}().`;
 }).build();
 var eventCycleError = error("runner.errors.eventCycle").format(({ path: path4 }) => {
   const chain = path4.map((p) => `${p.id}\u2190${p.source}`).join("  ->  ");
@@ -29506,33 +29585,49 @@ var eventCycleError = error("runner.errors.eventCycle").format(({ path: path4 })
   ${chain}
 
 Break the cycle by changing hook logic (avoid mutual emits) or gate with conditions/tags.`;
-}).build();
+}).remediation(
+  "Refactor hooks to avoid circular event emissions. Use conditional guards, split events into finer-grained signals, or introduce an intermediate task to break the cycle."
+).build();
 var eventEmissionCycleError = error("runner.errors.eventEmissionCycle").format(({ cycles }) => {
   const list = cycles.map((c) => `  \u2022 ${c}`).join("\n");
   return `Event emission cycles detected between hooks and events:
 ${list}
 
 This was detected at compile time (dry-run). Break the cycle by avoiding mutual emits between hooks or scoping hooks using tags.`;
-}).build();
+}).remediation(
+  "Redesign the event/hook graph so no hook emits an event that eventually triggers itself. Use tags or conditional logic to prevent re-entrant emissions."
+).build();
 var platformUnsupportedFunctionError = error("runner.errors.platformUnsupportedFunction").format(
   ({ functionName }) => `Platform function not supported in this environment: ${functionName}. Detected platform: ${detectEnvironment()}.`
+).remediation(
+  ({ functionName }) => `The function "${functionName}" requires a Node.js environment. If running in a browser or edge runtime, use a platform-compatible alternative or guard the call with a platform check.`
 ).build();
 var cancellationError = error(
   "runner.errors.cancellation"
-).format(({ reason }) => reason || "Operation cancelled").build();
+).format(({ reason }) => reason || "Operation cancelled").remediation(
+  "The operation was cancelled, typically via an AbortController signal. If this is unexpected, check timeout middleware settings or ensure the caller is not aborting prematurely."
+).build();
 var tunnelOwnershipConflictError = error("runner.errors.tunnelOwnershipConflict").format(
   ({ taskId, currentOwnerId, attemptedOwnerId }) => `Task "${taskId}" is already tunneled by resource "${currentOwnerId}". Resource "${attemptedOwnerId}" cannot tunnel it again. Ensure each task is owned by a single tunnel client.`
+).remediation(
+  ({ taskId }) => `Each task can only be tunneled by one client. Remove the duplicate tunnel registration for "${taskId}" or split the task into separate definitions with distinct ids.`
 ).build();
 var phantomTaskNotRoutedError = error("runner.errors.phantomTaskNotRouted").format(
   ({ taskId }) => `Phantom task "${taskId}" is not routed through any tunnel. Ensure a tunnel client selects this task id (or avoid calling the phantom task directly).`
+).remediation(
+  ({ taskId }) => `Configure a tunnel client resource to select "${taskId}" so it routes to a remote server. Phantom tasks cannot be executed locally \u2014 they only serve as local proxies for remote tasks.`
 ).build();
 var taskNotRegisteredError = error("runner.errors.taskNotRegistered").format(
   ({ taskId }) => `Task "${taskId}" is not registered in the Store. This is an internal error\u2014ensure the task is registered before execution.`
+).remediation(
+  ({ taskId }) => `Register the task "${taskId}" in a parent resource via .register([yourTask]) before calling run(). If this error persists, it may indicate an internal framework bug.`
 ).build();
 var builderIncompleteError = error("runner.errors.builderIncomplete").format(({ type, builderId, missingFields }) => {
   const typeLabel = type === "hook" ? "Hook" : type === "task-middleware" ? "Task middleware" : "Resource middleware";
   return `${typeLabel} "${builderId}" is incomplete. Missing required: ${missingFields.join(", ")}. Call ${missingFields.map((f) => `.${f}()`).join(" and ")} before .build().`;
-}).build();
+}).remediation(
+  ({ missingFields }) => `Add the missing builder steps: ${missingFields.map((f) => `.${f}()`).join(", ")} before calling .build().`
+).build();
 function isCancellationError(err) {
   return cancellationError.is(err);
 }
@@ -29766,6 +29861,7 @@ function defineResource(constConfig) {
       };
     },
     fork(newId, options) {
+      const forkCallerFilePath = getCallerFile();
       const forkedParts = resolveForkedRegisterAndDependencies({
         register: constConfig.register,
         dependencies: constConfig.dependencies,
@@ -29777,11 +29873,10 @@ function defineResource(constConfig) {
         id: newId,
         register: forkedParts.register,
         dependencies: forkedParts.dependencies,
-        [symbolFilePath]: filePath
+        [symbolFilePath]: forkCallerFilePath
       });
-      forked[symbolResourceForkedFrom] = {
-        fromId: id2,
-        forkedAtFilePath: getCallerFile()
+      forked[symbolForkedFrom] = {
+        fromId: id2
       };
       return forked;
     }
@@ -30012,7 +30107,7 @@ __name(defineTag, "defineTag");
 
 // src/globals/middleware/requireContext.middleware.ts
 var requireContextTaskMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.requireContext",
+  id: "globals.middleware.task.requireContext",
   async run({ task: task2, next }, _deps, config) {
     if (!config.context) {
       throw new Error(
@@ -31656,7 +31751,7 @@ var cacheFactoryTask = defineTask({
 });
 var journalKeys = {
   /** Whether the result was served from cache (true) or freshly computed (false) */
-  hit: journal.createKey("globals.middleware.cache.hit")
+  hit: journal.createKey("globals.middleware.task.cache.hit")
 };
 var cacheResource = defineResource({
   id: "globals.resources.cache",
@@ -31686,7 +31781,7 @@ var cacheResource = defineResource({
 });
 var defaultKeyBuilder = /* @__PURE__ */ __name((taskId, input) => `${taskId}-${JSON.stringify(input)}`, "defaultKeyBuilder");
 var cacheMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.cache",
+  id: "globals.middleware.task.cache",
   dependencies: { cache: cacheResource },
   async run({ task: task2, next, journal: journal2 }, deps, config) {
     const { cache } = deps;
@@ -31737,11 +31832,11 @@ var CircuitBreakerOpenError = class extends Error {
 var journalKeys2 = {
   /** Current state of the circuit breaker (CLOSED, OPEN, or HALF_OPEN) */
   state: journal.createKey(
-    "globals.middleware.circuitBreaker.state"
+    "globals.middleware.task.circuitBreaker.state"
   ),
   /** Current failure count */
   failures: journal.createKey(
-    "globals.middleware.circuitBreaker.failures"
+    "globals.middleware.task.circuitBreaker.failures"
   )
 };
 var circuitBreakerResource = defineResource({
@@ -31754,7 +31849,7 @@ var circuitBreakerResource = defineResource({
   }, "init")
 });
 var circuitBreakerMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.circuitBreaker",
+  id: "globals.middleware.task.circuitBreaker",
   dependencies: { state: circuitBreakerResource },
   async run({ task: task2, next, journal: journal2 }, { state }, config) {
     const taskId = task2.definition.id;
@@ -32334,12 +32429,12 @@ var EventManager = class {
 
 // src/models/Semaphore.ts
 var SemaphoreEvents = {
-  queued: defineEvent({ id: "semaphore.queued" }),
-  acquired: defineEvent({ id: "semaphore.acquired" }),
-  released: defineEvent({ id: "semaphore.released" }),
-  timeout: defineEvent({ id: "semaphore.timeout" }),
-  aborted: defineEvent({ id: "semaphore.aborted" }),
-  disposed: defineEvent({ id: "semaphore.disposed" })
+  queued: defineEvent({ id: "semaphore.events.queued" }),
+  acquired: defineEvent({ id: "semaphore.events.acquired" }),
+  released: defineEvent({ id: "semaphore.events.released" }),
+  timeout: defineEvent({ id: "semaphore.events.timeout" }),
+  aborted: defineEvent({ id: "semaphore.events.aborted" }),
+  disposed: defineEvent({ id: "semaphore.events.disposed" })
 };
 var Semaphore = class {
   constructor(maxPermits) {
@@ -32612,7 +32707,7 @@ var concurrencyResource = defineResource({
   }), "init")
 });
 var concurrencyTaskMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.concurrency",
+  id: "globals.middleware.task.concurrency",
   dependencies: { state: concurrencyResource },
   async run({ task: task2, next }, { state }, config) {
     let semaphore = config.semaphore;
@@ -32691,14 +32786,16 @@ var RateLimitError = class extends Error {
 var journalKeys3 = {
   /** Number of remaining requests in the current window */
   remaining: journal.createKey(
-    "globals.middleware.rateLimit.remaining"
+    "globals.middleware.task.rateLimit.remaining"
   ),
   /** Timestamp when the current window resets */
   resetTime: journal.createKey(
-    "globals.middleware.rateLimit.resetTime"
+    "globals.middleware.task.rateLimit.resetTime"
   ),
   /** Maximum requests allowed per window */
-  limit: journal.createKey("globals.middleware.rateLimit.limit")
+  limit: journal.createKey(
+    "globals.middleware.task.rateLimit.limit"
+  )
 };
 var rateLimitResource = defineResource({
   id: "globals.resources.rateLimit",
@@ -32710,7 +32807,7 @@ var rateLimitResource = defineResource({
   }, "init")
 });
 var rateLimitTaskMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.rateLimit",
+  id: "globals.middleware.task.rateLimit",
   configSchema: rateLimitConfigSchema,
   dependencies: { state: rateLimitResource },
   async run({ task: task2, next, journal: journal2 }, { state }, config) {
@@ -32758,7 +32855,7 @@ var temporalResource = defineResource({
   }, "init")
 });
 var debounceTaskMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.debounce",
+  id: "globals.middleware.task.debounce",
   dependencies: { state: temporalResource },
   async run({ task: task2, next }, { state }, config) {
     const { debounceStates } = state;
@@ -32795,7 +32892,7 @@ var debounceTaskMiddleware = defineTaskMiddleware({
   }
 });
 var throttleTaskMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.throttle",
+  id: "globals.middleware.task.throttle",
   dependencies: { state: temporalResource },
   async run({ task: task2, next }, { state }, config) {
     const { throttleStates } = state;
@@ -32867,12 +32964,12 @@ var throttleTaskMiddleware = defineTaskMiddleware({
 
 // src/models/Queue.ts
 var QueueEvents = {
-  enqueue: defineEvent({ id: "queue.enqueue" }),
-  start: defineEvent({ id: "queue.start" }),
-  finish: defineEvent({ id: "queue.finish" }),
-  error: defineEvent({ id: "queue.error" }),
-  cancel: defineEvent({ id: "queue.cancel" }),
-  disposed: defineEvent({ id: "queue.disposed" })
+  enqueue: defineEvent({ id: "queue.events.enqueue" }),
+  start: defineEvent({ id: "queue.events.start" }),
+  finish: defineEvent({ id: "queue.events.finish" }),
+  error: defineEvent({ id: "queue.events.error" }),
+  cancel: defineEvent({ id: "queue.events.cancel" }),
+  disposed: defineEvent({ id: "queue.events.disposed" })
 };
 var Queue = class {
   constructor() {
@@ -33481,13 +33578,15 @@ var retryResourceMiddleware = defineResourceMiddleware({
 var journalKeys6 = {
   /** Whether the fallback path was taken (true) or primary succeeded (false) */
   active: journal.createKey(
-    "globals.middleware.fallback.active"
+    "globals.middleware.task.fallback.active"
   ),
   /** The error that triggered the fallback (only set when active is true) */
-  error: journal.createKey("globals.middleware.fallback.error")
+  error: journal.createKey(
+    "globals.middleware.task.fallback.error"
+  )
 };
 var fallbackTaskMiddleware = defineTaskMiddleware({
-  id: "globals.middleware.fallback",
+  id: "globals.middleware.task.fallback",
   dependencies: {
     taskRunner: globalResources.taskRunner
   },
@@ -36167,21 +36266,11 @@ var Store = class {
   storeGenericItem(item) {
     return this.registry.storeGenericItem(item);
   }
-  /**
-   * Returns all tasks with the given tag.
-   * @param tag - The tag to filter by.
-   * @returns The tasks with the given tag.
-   */
   getTasksWithTag(tag2) {
-    return this.registry.getTasksWithTag(tag2);
+    return typeof tag2 === "string" ? this.registry.getTasksWithTag(tag2) : this.registry.getTasksWithTag(tag2);
   }
-  /**
-   * Returns all resources with the given tag.
-   * @param tag - The tag to filter by.
-   * @returns The resources with the given tag.
-   */
   getResourcesWithTag(tag2) {
-    return this.registry.getResourcesWithTag(tag2);
+    return typeof tag2 === "string" ? this.registry.getResourcesWithTag(tag2) : this.registry.getResourcesWithTag(tag2);
   }
 };
 
@@ -39418,6 +39507,7 @@ var UNSAFE_ERROR_FIELDS = /* @__PURE__ */ new Set([
 var isRecord2 = /* @__PURE__ */ __name((value) => !!value && typeof value === "object", "isRecord");
 var isJsonBody = /* @__PURE__ */ __name((value) => isRecord2(value) && typeof value.ok === "boolean", "isJsonBody");
 var toErrorRecord = /* @__PURE__ */ __name((value) => isRecord2(value) ? value : void 0, "toErrorRecord");
+var isValidHttpCode3 = /* @__PURE__ */ __name((value) => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599, "isValidHttpCode");
 var sanitizeErrorResponse = /* @__PURE__ */ __name((response) => {
   const asRecord = isRecord2(response) ? response : void 0;
   const statusRaw = asRecord?.status ?? asRecord?.statusCode;
@@ -39459,6 +39549,9 @@ var sanitizeErrorResponse = /* @__PURE__ */ __name((response) => {
       if (bodyError.data !== void 0) {
         safeError.data = bodyError.data;
       }
+      if (isValidHttpCode3(bodyError.httpCode)) {
+        safeError.httpCode = bodyError.httpCode;
+      }
       return {
         ok: false,
         error: safeError
@@ -39480,11 +39573,19 @@ var resolveAppErrorExtra = /* @__PURE__ */ __name((store2, error2) => {
   try {
     for (const helper of store2.errors.values()) {
       if (helper.is(error2)) {
-        if (!isRecord2(error2)) return { id: void 0, data: void 0 };
+        if (!isRecord2(error2)) {
+          return {
+            id: void 0,
+            data: void 0,
+            httpCode: isValidHttpCode3(helper.httpCode) ? helper.httpCode : void 0
+          };
+        }
         const name = error2["name" /* Name */];
         const id2 = typeof name === "string" ? name : void 0;
         const data = error2["data" /* Data */];
-        return { id: id2, data };
+        const runtimeHttpCode = error2["httpCode" /* HttpCode */];
+        const httpCode = isValidHttpCode3(runtimeHttpCode) ? runtimeHttpCode : isValidHttpCode3(helper.httpCode) ? helper.httpCode : void 0;
+        return { id: id2, data, httpCode };
       }
     }
   } catch {
@@ -39494,6 +39595,7 @@ var resolveAppErrorExtra = /* @__PURE__ */ __name((store2, error2) => {
 var handleRequestError = /* @__PURE__ */ __name((options) => {
   const { error: error2, req, res, store: store2, logger, cors, serializer: serializer3, logKey } = options;
   const appErrorExtra = resolveAppErrorExtra(store2, error2);
+  const responseStatus = appErrorExtra?.httpCode ?? 500;
   const displayMessage = appErrorExtra && error2 instanceof Error && error2.message ? error2.message : "Internal Error" /* InternalError */;
   safeLogError(logger, logKey, { error: errorMessage(error2) });
   applyCorsActual(req, res, cors);
@@ -39501,7 +39603,7 @@ var handleRequestError = /* @__PURE__ */ __name((options) => {
     res,
     sanitizeErrorResponse(
       jsonErrorResponse(
-        500,
+        responseStatus,
         displayMessage,
         "INTERNAL_ERROR" /* InternalError */,
         appErrorExtra
@@ -39513,7 +39615,7 @@ var handleRequestError = /* @__PURE__ */ __name((options) => {
 
 // src/node/exposure/requestContext.ts
 var ExposureRequestContext = defineAsyncContext({
-  id: "platform.node.exposure.request"
+  id: "platform.node.ctx.exposureRequest"
 });
 function useExposureContext() {
   return ExposureRequestContext.use();
@@ -40460,6 +40562,15 @@ async function recordFlowShape(descriptor) {
 }
 __name(recordFlowShape, "recordFlowShape");
 
+// src/node/durable/tags/durableWorkflow.tag.ts
+var durableWorkflowTag = defineTag({
+  id: "globals.tags.durableWorkflow",
+  meta: {
+    title: "Durable Workflow",
+    description: "Marks tasks intended to run as durable workflows so they can be discovered at runtime."
+  }
+});
+
 // src/node/durable/core/DurableResource.ts
 var DurableResource = class _DurableResource {
   constructor(service, contextStorage, store2, runnerStore) {
@@ -40516,6 +40627,14 @@ var DurableResource = class _DurableResource {
       await effectiveTask.run(input, depsWithRecorder);
     });
   }
+  getWorkflows() {
+    if (!this.runnerStore) {
+      throw new Error(
+        "Durable workflow discovery is not available: runner store was not provided to DurableResource. Use a Runner durable resource (durableResource/memoryDurableResource/redisDurableResource) instead of manually constructing DurableResource."
+      );
+    }
+    return this.runnerStore.getTasksWithTag(durableWorkflowTag);
+  }
   injectRecorderIntoDurableDeps(deps, ctx) {
     const next = { ...deps };
     for (const [key, value] of Object.entries(deps)) {
@@ -40533,8 +40652,11 @@ var DurableResource = class _DurableResource {
     }
     return next;
   }
-  startExecution(task2, input, options) {
-    return this.service.startExecution(task2, input, options);
+  start(task2, input, options) {
+    if (typeof task2 === "string") {
+      return this.service.start(task2, input, options);
+    }
+    return this.service.start(task2, input, options);
   }
   cancelExecution(executionId, reason) {
     return this.service.cancelExecution(executionId, reason);
@@ -40542,16 +40664,22 @@ var DurableResource = class _DurableResource {
   wait(executionId, options) {
     return this.service.wait(executionId, options);
   }
-  execute(task2, input, options) {
-    return this.service.execute(task2, input, options);
-  }
-  executeStrict(task2, input, options) {
-    return this.service.executeStrict(task2, input, options);
+  startAndWait(task2, input, options) {
+    if (typeof task2 === "string") {
+      return this.service.startAndWait(task2, input, options);
+    }
+    return this.service.startAndWait(task2, input, options);
   }
   schedule(task2, input, options) {
+    if (typeof task2 === "string") {
+      return this.service.schedule(task2, input, options);
+    }
     return this.service.schedule(task2, input, options);
   }
   ensureSchedule(task2, input, options) {
+    if (typeof task2 === "string") {
+      return this.service.ensureSchedule(task2, input, options);
+    }
     return this.service.ensureSchedule(task2, input, options);
   }
   pauseSchedule(scheduleId) {
@@ -41074,10 +41202,11 @@ var ScheduleManager = class {
   static {
     __name(this, "ScheduleManager");
   }
-  async ensureSchedule(task2, input, options) {
+  async ensureSchedule(taskRef, input, options) {
     if (!options.cron && options.interval === void 0) {
       throw new Error("ensureSchedule() requires cron or interval");
     }
+    const task2 = this.resolveTaskReference(taskRef, "ensureSchedule");
     this.taskRegistry.register(task2);
     const scheduleId = options.id;
     const lockTtlMs = 1e4;
@@ -41140,7 +41269,8 @@ var ScheduleManager = class {
       }
     }
   }
-  async schedule(task2, input, options) {
+  async schedule(taskRef, input, options) {
+    const task2 = this.resolveTaskReference(taskRef, "schedule");
     this.taskRegistry.register(task2);
     const id2 = options.id ?? createExecutionId();
     if (options.cron || options.interval !== void 0) {
@@ -41223,6 +41353,18 @@ var ScheduleManager = class {
   async remove(id2) {
     await this.store.deleteSchedule(id2);
   }
+  resolveTaskReference(taskRef, apiMethod) {
+    if (typeof taskRef !== "string") {
+      return taskRef;
+    }
+    const resolved = this.taskRegistry.find(taskRef);
+    if (!resolved) {
+      throw new Error(
+        `DurableService.${apiMethod}() could not resolve task id "${taskRef}". Ensure the task is registered in the runtime store.`
+      );
+    }
+    return resolved;
+  }
 };
 
 // src/node/durable/core/managers/SignalHandler.ts
@@ -42113,99 +42255,117 @@ var ExecutionManager = class {
   static {
     __name(this, "ExecutionManager");
   }
-  async startExecution(task2, input, options) {
+  async start(taskRef, input, options) {
+    const task2 = this.resolveTaskReference(taskRef, "start");
     this.taskRegistry.register(task2);
+    this.assertCanExecute();
+    if (options?.idempotencyKey) {
+      return this.startWithIdempotencyKey(
+        task2,
+        input,
+        options.idempotencyKey,
+        options
+      );
+    }
+    const executionId = await this.persistNewExecution(task2, input, options);
+    await this.kickoffWithFailsafe(executionId);
+    return executionId;
+  }
+  // ─── Idempotent start ──────────────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  async startWithIdempotencyKey(task2, input, idempotencyKey, options) {
+    this.assertStoreSupportsIdempotency();
+    return this.withIdempotencyLock(task2.id, idempotencyKey, async () => {
+      const existingId = await this.config.store.getExecutionIdByIdempotencyKey({
+        taskId: task2.id,
+        idempotencyKey
+      });
+      if (existingId) return existingId;
+      const executionId = createExecutionId();
+      const claimed = await this.config.store.setExecutionIdByIdempotencyKey({
+        taskId: task2.id,
+        idempotencyKey,
+        executionId
+      });
+      if (!claimed) {
+        return this.resolveRacedIdempotencyKey(task2.id, idempotencyKey);
+      }
+      await this.persistNewExecution(task2, input, options, executionId);
+      await this.kickoffExecution(executionId);
+      return executionId;
+    });
+  }
+  assertCanExecute() {
     if (!this.config.queue && !this.config.taskExecutor) {
       throw new Error(
         "DurableService requires `taskExecutor` to execute Runner tasks (when no queue is configured). Use `durableResource.fork(...).with(...)` in a Runner runtime, or provide a custom executor in config."
       );
     }
-    const idempotencyKey = options?.idempotencyKey;
-    if (idempotencyKey) {
-      if (!this.config.store.getExecutionIdByIdempotencyKey || !this.config.store.setExecutionIdByIdempotencyKey) {
-        throw new Error(
-          "Durable store does not support execution idempotency keys. Implement getExecutionIdByIdempotencyKey/setExecutionIdByIdempotencyKey on the store to use ExecuteOptions.idempotencyKey."
-        );
-      }
-      const lockTtlMs = 1e4;
-      const lockResource = `idempotency:${task2.id}:${idempotencyKey}`;
-      const canLock = !!this.config.store.acquireLock && !!this.config.store.releaseLock;
-      let lockId = null;
-      if (canLock) {
-        const maxAttempts = 50;
-        for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-          lockId = await this.config.store.acquireLock(
-            lockResource,
-            lockTtlMs
-          );
-          if (lockId !== null) break;
-          await sleepMs(5);
-        }
-        if (lockId === null) {
-          throw new Error(
-            `Failed to acquire idempotency lock for '${task2.id}:${idempotencyKey}'`
-          );
-        }
-      }
+  }
+  assertStoreSupportsIdempotency() {
+    if (!this.config.store.getExecutionIdByIdempotencyKey || !this.config.store.setExecutionIdByIdempotencyKey) {
+      throw new Error(
+        "Durable store does not support execution idempotency keys. Implement getExecutionIdByIdempotencyKey/setExecutionIdByIdempotencyKey on the store to use ExecuteOptions.idempotencyKey."
+      );
+    }
+  }
+  /**
+   * Acquires a distributed lock around the idempotency check-and-set,
+   * falling back to lock-free operation when the store has no locking support.
+   */
+  async withIdempotencyLock(taskId, idempotencyKey, fn) {
+    const canLock = !!this.config.store.acquireLock && !!this.config.store.releaseLock;
+    if (!canLock) return fn();
+    const lockResource = `idempotency:${taskId}:${idempotencyKey}`;
+    const lockTtlMs = 1e4;
+    const maxAttempts = 50;
+    let lockId = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      lockId = await this.config.store.acquireLock(lockResource, lockTtlMs);
+      if (lockId !== null) break;
+      await sleepMs(5);
+    }
+    if (lockId === null) {
+      throw new Error(
+        `Failed to acquire idempotency lock for '${taskId}:${idempotencyKey}'`
+      );
+    }
+    try {
+      return await fn();
+    } finally {
       try {
-        const existing = await this.config.store.getExecutionIdByIdempotencyKey(
-          {
-            taskId: task2.id,
-            idempotencyKey
-          }
-        );
-        if (existing) return existing;
-        const executionId2 = createExecutionId();
-        const setOk = await this.config.store.setExecutionIdByIdempotencyKey({
-          taskId: task2.id,
-          idempotencyKey,
-          executionId: executionId2
-        });
-        if (!setOk) {
-          const raced = await this.config.store.getExecutionIdByIdempotencyKey({
-            taskId: task2.id,
-            idempotencyKey
-          });
-          if (raced) return raced;
-          throw new Error(
-            "Failed to set idempotency mapping but no existing mapping found."
-          );
-        }
-        const execution2 = {
-          id: executionId2,
-          taskId: task2.id,
-          input,
-          status: ExecutionStatus.Pending,
-          attempt: 1,
-          maxAttempts: this.config.execution?.maxAttempts ?? 3,
-          timeout: options?.timeout ?? this.config.execution?.timeout,
-          createdAt: /* @__PURE__ */ new Date(),
-          updatedAt: /* @__PURE__ */ new Date()
-        };
-        await this.config.store.saveExecution(execution2);
-        await this.auditLogger.log({
-          kind: DurableAuditEntryKind.ExecutionStatusChanged,
-          executionId: executionId2,
-          taskId: task2.id,
-          attempt: execution2.attempt,
-          from: null,
-          to: ExecutionStatus.Pending,
-          reason: "created"
-        });
-        await this.kickoffExecution(executionId2);
-        return executionId2;
-      } finally {
-        if (canLock && lockId !== null) {
-          try {
-            await this.config.store.releaseLock(lockResource, lockId);
-          } catch {
-          }
-        }
+        await this.config.store.releaseLock(lockResource, lockId);
+      } catch {
       }
     }
-    const executionId = createExecutionId();
+  }
+  /**
+   * Recovery path: `setExecutionIdByIdempotencyKey` returned false (another
+   * writer won the race), so we re-read the mapping to get their executionId.
+   */
+  async resolveRacedIdempotencyKey(taskId, idempotencyKey) {
+    const racedId = await this.config.store.getExecutionIdByIdempotencyKey({
+      taskId,
+      idempotencyKey
+    });
+    if (racedId) return racedId;
+    throw new Error(
+      "Failed to set idempotency mapping but no existing mapping found."
+    );
+  }
+  // ─── Execution persistence ─────────────────────────────────────────────────
+  /**
+   * Creates a new execution record, persists it to the store, and logs an
+   * audit entry. Returns the executionId.
+   */
+  async persistNewExecution(task2, input, options, executionId) {
+    const id2 = executionId ?? createExecutionId();
     const execution = {
-      id: executionId,
+      id: id2,
       taskId: task2.id,
       input,
       status: ExecutionStatus.Pending,
@@ -42218,37 +42378,40 @@ var ExecutionManager = class {
     await this.config.store.saveExecution(execution);
     await this.auditLogger.log({
       kind: DurableAuditEntryKind.ExecutionStatusChanged,
-      executionId,
+      executionId: id2,
       taskId: task2.id,
       attempt: execution.attempt,
       from: null,
       to: ExecutionStatus.Pending,
       reason: "created"
     });
-    const kickoffTimerId = `kickoff:${executionId}`;
-    const kickoffFailsafeDelayMs = this.config.execution?.kickoffFailsafeDelayMs ?? 1e4;
-    const shouldArmKickoffFailsafe = Boolean(this.config.queue) && kickoffFailsafeDelayMs > 0;
-    if (shouldArmKickoffFailsafe) {
+    return id2;
+  }
+  /**
+   * 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.
+   */
+  async kickoffWithFailsafe(executionId) {
+    const failsafeDelayMs = this.config.execution?.kickoffFailsafeDelayMs ?? 1e4;
+    const shouldArmFailsafe = Boolean(this.config.queue) && failsafeDelayMs > 0;
+    if (shouldArmFailsafe) {
+      const timerId = `kickoff:${executionId}`;
       await this.config.store.createTimer({
-        id: kickoffTimerId,
+        id: timerId,
         executionId,
         type: TimerType.Retry,
-        fireAt: new Date(Date.now() + kickoffFailsafeDelayMs),
+        fireAt: new Date(Date.now() + failsafeDelayMs),
         status: TimerStatus.Pending
       });
-    }
-    try {
       await this.kickoffExecution(executionId);
-      if (shouldArmKickoffFailsafe) {
-        try {
-          await this.config.store.deleteTimer(kickoffTimerId);
-        } catch {
-        }
+      try {
+        await this.config.store.deleteTimer(timerId);
+      } catch {
       }
-    } catch (error2) {
-      throw error2;
+      return;
     }
-    return executionId;
+    await this.kickoffExecution(executionId);
   }
   async cancelExecution(executionId, reason) {
     const execution = await this.config.store.getExecution(executionId);
@@ -42279,16 +42442,16 @@ var ExecutionManager = class {
       timestamp: /* @__PURE__ */ new Date()
     });
   }
-  async execute(task2, input, options) {
-    const executionId = await this.startExecution(task2, input, options);
-    return await this.waitManager.waitForResult(executionId, {
+  async startAndWait(taskRef, input, options) {
+    const executionId = await this.start(taskRef, input, options);
+    const data = await this.waitManager.waitForResult(executionId, {
       timeout: options?.timeout,
       waitPollIntervalMs: options?.waitPollIntervalMs
     });
-  }
-  async executeStrict(task2, input, options) {
-    const actualTask = task2;
-    return await this.execute(actualTask, input, options);
+    return {
+      durable: { executionId },
+      data
+    };
   }
   async processExecution(executionId) {
     const execution = await this.config.store.getExecution(executionId);
@@ -42497,6 +42660,18 @@ var ExecutionManager = class {
       });
     }
   }
+  resolveTaskReference(taskRef, apiMethod) {
+    if (typeof taskRef !== "string") {
+      return taskRef;
+    }
+    const resolved = this.taskRegistry.find(taskRef);
+    if (!resolved) {
+      throw new Error(
+        `DurableService.${apiMethod}() could not resolve task id "${taskRef}". Ensure the task is registered in the runtime store.`
+      );
+    }
+    return resolved;
+  }
 };
 var PollingManager = class {
   constructor(workerId, config, store2, queue, maxAttempts, defaultTimeout, taskRegistry, auditLogger, scheduleManager, callbacks) {
@@ -42691,16 +42866,26 @@ var DurableService = class {
     this.config = config;
     this.workerId = config.workerId ?? createExecutionId();
     this.taskRegistry = new TaskRegistry(config.taskResolver);
-    if (config.schedules) {
-      for (const schedule of config.schedules) {
-        this.taskRegistry.register(schedule.task);
-      }
-    }
     if (config.tasks) {
       for (const task2 of config.tasks) {
         this.taskRegistry.register(task2);
       }
     }
+    if (config.schedules) {
+      for (const schedule of config.schedules) {
+        if (typeof schedule.task === "string") {
+          const resolved = this.taskRegistry.find(schedule.task);
+          if (!resolved) {
+            throw new Error(
+              `Cannot initialize durable schedule "${schedule.id}": task "${schedule.task}" is not registered.`
+            );
+          }
+          this.taskRegistry.register(resolved);
+          continue;
+        }
+        this.taskRegistry.register(schedule.task);
+      }
+    }
     this.auditLogger = new AuditLogger(
       { enabled: config.audit?.enabled, emitter: config.audit?.emitter },
       config.store
@@ -42760,17 +42945,18 @@ var DurableService = class {
   findTask(taskId) {
     return this.taskRegistry.find(taskId);
   }
-  async startExecution(task2, input, options) {
-    return this.executionManager.startExecution(task2, input, options);
+  start(task2, input, options) {
+    if (task2 === void 0) {
+      this.pollingManager.start();
+      return;
+    }
+    return this.executionManager.start(task2, input, options);
   }
   async cancelExecution(executionId, reason) {
     await this.executionManager.cancelExecution(executionId, reason);
   }
-  async execute(task2, input, options) {
-    return this.executionManager.execute(task2, input, options);
-  }
-  async executeStrict(task2, input, options) {
-    return this.executionManager.executeStrict(task2, input, options);
+  async startAndWait(task2, input, options) {
+    return this.executionManager.startAndWait(task2, input, options);
   }
   wait(executionId, options) {
     return this.waitManager.waitForResult(executionId, options);
@@ -42789,9 +42975,6 @@ var DurableService = class {
       }
     }
   }
-  start() {
-    this.pollingManager.start();
-  }
   async stop() {
     await this.pollingManager.stop();
   }
@@ -42927,10 +43110,7 @@ async function createRunnerDurableRuntime(config, deps) {
     },
     taskExecutor: {
       run: /* @__PURE__ */ __name(async (task2, input) => {
-        const outputPromise = await deps.taskRunner.run(
-          task2,
-          input
-        );
+        const outputPromise = await deps.taskRunner.run(task2, input);
         if (outputPromise === void 0) {
           throw new Error(
             `Durable task '${task2.id}' completed without a result promise.`
@@ -42958,7 +43138,7 @@ async function createRunnerDurableRuntime(config, deps) {
 __name(createRunnerDurableRuntime, "createRunnerDurableRuntime");
 
 // src/node/durable/core/resource.ts
-var durableResource = r.resource("base.durable").register(durableEventsArray).dependencies({
+var durableResource = r.resource("base.durable").register([durableWorkflowTag, ...durableEventsArray]).dependencies({
   taskRunner: globals.resources.taskRunner,
   eventManager: globals.resources.eventManager,
   runnerStore: globals.resources.store
@@ -44100,7 +44280,7 @@ async function waitUntil(predicate, options) {
 __name(waitUntil, "waitUntil");
 
 // src/node/durable/resources/memoryDurableResource.ts
-var memoryDurableResource = r.resource("base.durable.memory").register(durableEventsArray).dependencies({
+var memoryDurableResource = r.resource("base.durable.memory").register([durableWorkflowTag, ...durableEventsArray]).dependencies({
   taskRunner: globals.resources.taskRunner,
   eventManager: globals.resources.eventManager,
   runnerStore: globals.resources.store
@@ -44159,7 +44339,7 @@ function deriveDurableIsolation(params) {
 __name(deriveDurableIsolation, "deriveDurableIsolation");
 
 // src/node/durable/resources/redisDurableResource.ts
-var redisDurableResource = r.resource("base.durable.redis").register(durableEventsArray).dependencies({
+var redisDurableResource = r.resource("base.durable.redis").register([durableWorkflowTag, ...durableEventsArray]).dependencies({
   taskRunner: globals.resources.taskRunner,
   eventManager: globals.resources.eventManager,
   runnerStore: globals.resources.store
@@ -44554,6 +44734,7 @@ exports.MemoryEventBus = MemoryEventBus;
 exports.MemoryQueue = MemoryQueue;
 exports.MemoryStore = MemoryStore;
 exports.MiddlewareManager = MiddlewareManager;
+exports.NodeInputFile = NodeInputFile;
 exports.NoopEventBus = NoopEventBus;
 exports.PlatformAdapter = PlatformAdapter;
 exports.Queue = Queue;
@@ -44562,6 +44743,7 @@ exports.RedisEventBus = RedisEventBus;
 exports.RedisStore = RedisStore;
 exports.ResourceInitializer = ResourceInitializer;
 exports.RunResult = RunResult;
+exports.RunnerError = RunnerError;
 exports.ScheduleStatus = ScheduleStatus;
 exports.ScheduleType = ScheduleType;
 exports.Semaphore = Semaphore;
@@ -44598,6 +44780,7 @@ exports.disposeDurableService = disposeDurableService;
 exports.durableEvents = durableEvents;
 exports.durableEventsArray = durableEventsArray;
 exports.durableResource = durableResource;
+exports.durableWorkflowTag = durableWorkflowTag;
 exports.event = defineEvent;
 exports.getConfig = getConfig;
 exports.globals = globals2;