@iworkflow/core 0.5.0 → 0.6.0

package/README.md

@@ -17,6 +17,8 @@ export const outreach: Flow = async (ctx, input: { id: string }) => {
 ```
 
 Шаг с прогрессом: `heartbeat(details)` и `lastHeartbeat()` из этого пакета внутри функции шага.
+Рантайм шага ставит адаптер на время шага (`stepScope`): в одном процессе могут жить оба движка.
+`@iworkflow/core` и адаптеры — одной версии: область шага общая через `Symbol.for`.
 
 Отказы одинаковы на обоих движках. Шаг бросает `nonRetryable(message, type, details)` или
 `new Failure(message, { type })`; порт бросает `FlowError` с `reason` (`failed`, `timeout`,
@@ -36,6 +38,6 @@ try {
 
 Приоритет: `client.start(..., { priority })` (1 — первым, 5 — последним) → `ctx.priority`; шаги и
 дети его наследуют, `StepOptions.priority` — свой. Срок повтора из отказа: `new Failure(msg, { type,
-retryAfterMs })`. Номер попытки в шаге — `stepAttempt()`. Время в процессе — `await ctx.now()`.
+retryAfterMs })`; `benign: true` — штатный отказ, Temporal не пишет его ошибкой. Номер попытки в шаге — `stepAttempt()`. Время в процессе — `await ctx.now()`.
 `client.signalWithStart(target, args, opts, topic, value)` — сигнал идущему или запуск с сигналом.
 Контракт обоих движков — `lab/test/contract.test.ts` репозитория.

package/dist/errors.d.ts

@@ -8,11 +8,14 @@ export declare class Failure extends Error {
     readonly nonRetryable: boolean;
     /** Следующая попытка шага не раньше чем через столько мс (FLOOD_WAIT): вместо паузы из StepOptions. */
     readonly retryAfterMs?: number;
+    /** Штатный отказ (флуд, тихие часы): Temporal не пишет его в журнал ошибкой (category BENIGN). */
+    readonly benign: boolean;
     constructor(message: string, opts: {
         type: string;
         details?: unknown;
         nonRetryable?: boolean;
         retryAfterMs?: number;
+        benign?: boolean;
     });
 }
 /** Отказ без повтора: `throw nonRetryable("нет такой фазы", "UnknownPhase")`. */

package/dist/heartbeat.d.ts

@@ -4,7 +4,16 @@ export interface StepRuntime {
     /** Номер попытки шага, с 1. */
     attempt(): number;
 }
-export declare function bindStepRuntime(rt: StepRuntime): void;
+/** Область шага: какой рантайм у шага, что идёт сейчас. Самый внутренний шаг — свой, без угадывания движка. */
+export interface StepScope {
+    run<T>(rt: StepRuntime, fn: () => T): T;
+    current(): StepRuntime | undefined;
+}
+/**
+ * Одна область на процесс; её создаёт первый адаптер (AsyncLocalStorage) — core читает песочница
+ * Temporal, и node:async_hooks ему импортировать нельзя.
+ */
+export declare function stepScope(make: () => StepScope): StepScope;
 /** Отметить, что шаг жив, и сохранить прогресс. */
 export declare const heartbeat: (details?: unknown) => Promise<void>;
 /** Прогресс прошлой попытки этого шага; undefined — первая попытка или прогресса не было. */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./types";
-export { bindStepRuntime, heartbeat, lastHeartbeat, stepAttempt, type StepRuntime } from "./heartbeat";
+export { heartbeat, lastHeartbeat, stepAttempt, stepScope, type StepRuntime, type StepScope } from "./heartbeat";
 export * from "./errors";
 export { exitSignal, type ExitSignal } from "./exit";

package/dist/index.js

@@ -1,12 +1,12 @@
 // src/heartbeat.ts
-var KEY = Symbol.for("@iworkflow/core.step-runtime");
-function bindStepRuntime(rt) {
-  globalThis[KEY] = rt;
+var KEY = Symbol.for("@iworkflow/core.step-scope");
+function stepScope(make) {
+  return globalThis[KEY] ??= make();
 }
 function current() {
-  const rt = globalThis[KEY];
+  const rt = globalThis[KEY]?.current();
   if (!rt)
-    throw new Error("heartbeat вне шага: движок процесса не запущен в этом процессе");
+    throw new Error("heartbeat вне шага: шаг движка процесса сейчас не идёт");
   return rt;
 }
 var heartbeat = (details) => current().heartbeat(details);
@@ -18,12 +18,14 @@ class Failure extends Error {
   details;
   nonRetryable;
   retryAfterMs;
+  benign;
   constructor(message, opts) {
     super(message);
     this.name = "Failure";
     this.type = opts.type;
     this.details = opts.details;
     this.nonRetryable = opts.nonRetryable ?? false;
+    this.benign = opts.benign ?? false;
     const after = opts.retryAfterMs;
     this.retryAfterMs = after !== undefined && Number.isFinite(after) && after >= 0 ? after : undefined;
   }
@@ -81,12 +83,12 @@ export {
   DEFAULT_PRIORITY,
   Failure,
   FlowError,
-  bindStepRuntime,
   checkPriority,
   exitSignal,
   heartbeat,
   isFlowError,
   lastHeartbeat,
   nonRetryable,
-  stepAttempt
+  stepAttempt,
+  stepScope
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Engine-neutral durable workflow port: flows, steps, child workflows, signals, queries, patches, heartbeat",
   "keywords": [
     "workflow",

package/src/errors.ts

@@ -10,15 +10,18 @@ export class Failure extends Error {
   readonly nonRetryable: boolean;
   /** Следующая попытка шага не раньше чем через столько мс (FLOOD_WAIT): вместо паузы из StepOptions. */
   readonly retryAfterMs?: number;
+  /** Штатный отказ (флуд, тихие часы): Temporal не пишет его в журнал ошибкой (category BENIGN). */
+  readonly benign: boolean;
   constructor(
     message: string,
-    opts: { type: string; details?: unknown; nonRetryable?: boolean; retryAfterMs?: number },
+    opts: { type: string; details?: unknown; nonRetryable?: boolean; retryAfterMs?: number; benign?: boolean },
   ) {
     super(message);
     this.name = "Failure";
     this.type = opts.type;
     this.details = opts.details;
     this.nonRetryable = opts.nonRetryable ?? false;
+    this.benign = opts.benign ?? false;
     // Неразобранный срок (NaN, отрицательный) — как не заданный: пауза из StepOptions.
     const after = opts.retryAfterMs;
     this.retryAfterMs = after !== undefined && Number.isFinite(after) && after >= 0 ? after : undefined;

package/src/heartbeat.ts

@@ -8,16 +8,26 @@ export interface StepRuntime {
   attempt(): number;
 }
 
-const KEY = Symbol.for("@iworkflow/core.step-runtime");
-type Slot = { [KEY]?: StepRuntime };
+/** Область шага: какой рантайм у шага, что идёт сейчас. Самый внутренний шаг — свой, без угадывания движка. */
+export interface StepScope {
+  run<T>(rt: StepRuntime, fn: () => T): T;
+  current(): StepRuntime | undefined;
+}
+
+const KEY = Symbol.for("@iworkflow/core.step-scope");
+type Slot = { [KEY]?: StepScope };
 
-export function bindStepRuntime(rt: StepRuntime): void {
-  (globalThis as Slot)[KEY] = rt;
+/**
+ * Одна область на процесс; её создаёт первый адаптер (AsyncLocalStorage) — core читает песочница
+ * Temporal, и node:async_hooks ему импортировать нельзя.
+ */
+export function stepScope(make: () => StepScope): StepScope {
+  return ((globalThis as Slot)[KEY] ??= make());
 }
 
 function current(): StepRuntime {
-  const rt = (globalThis as Slot)[KEY];
-  if (!rt) throw new Error("heartbeat вне шага: движок процесса не запущен в этом процессе");
+  const rt = (globalThis as Slot)[KEY]?.current();
+  if (!rt) throw new Error("heartbeat вне шага: шаг движка процесса сейчас не идёт");
   return rt;
 }
 

package/src/index.ts

@@ -1,4 +1,4 @@
 export * from "./types";
-export { bindStepRuntime, heartbeat, lastHeartbeat, stepAttempt, type StepRuntime } from "./heartbeat";
+export { heartbeat, lastHeartbeat, stepAttempt, stepScope, type StepRuntime, type StepScope } from "./heartbeat";
 export * from "./errors";
 export { exitSignal, type ExitSignal } from "./exit";