@iworkflow/core 0.4.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`,
@@ -33,4 +35,9 @@ try {
 
 Ещё: `ctx.startChild` (без ожидания), `ChildOptions.timeoutMs` и `onExisting`, `ctx.startedAt`,
 `ctx.parentId`, `AppDefinition.pools`, `handle.describe()` и `handle.terminate()`.
+
+Приоритет: `client.start(..., { priority })` (1 — первым, 5 — последним) → `ctx.priority`; шаги и
+дети его наследуют, `StepOptions.priority` — свой. Срок повтора из отказа: `new Failure(msg, { type,
+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

@@ -6,10 +6,16 @@ export declare class Failure extends Error {
     readonly type: string;
     readonly details?: unknown;
     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")`. */
@@ -38,3 +44,6 @@ export declare class FlowError extends Error {
 }
 /** FlowError по признакам, а не по классу: класс теряется при сериализации в DBOS. */
 export declare const isFlowError: (e: unknown) => e is FlowError;
+/** Приоритет порта — целое 1…5 (1 — первым); иное отвергается одинаково на обоих движках. */
+export declare function checkPriority(p: number | undefined): number | undefined;
+export declare const DEFAULT_PRIORITY = 3;

package/dist/heartbeat.d.ts

@@ -1,9 +1,22 @@
 export interface StepRuntime {
     heartbeat(details?: unknown): Promise<void>;
     lastHeartbeat(): Promise<unknown>;
+    /** Номер попытки шага, с 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 — первая попытка или прогресса не было. */
 export declare const lastHeartbeat: <T>() => Promise<T | undefined>;
+/** Номер попытки этого шага, с 1. DBOS считает заново после рестарта процесса, Temporal — нет. */
+export declare const stepAttempt: () => number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./types";
-export { bindStepRuntime, heartbeat, lastHeartbeat, 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,27 +1,33 @@
 // 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);
 var lastHeartbeat = async () => await current().lastHeartbeat() ?? undefined;
+var stepAttempt = () => current().attempt();
 // src/errors.ts
 class Failure extends Error {
   type;
   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;
   }
 }
 var nonRetryable = (message, type, details) => new Failure(message, { type, details, nonRetryable: true });
@@ -41,6 +47,14 @@ class FlowError extends Error {
   }
 }
 var isFlowError = (e) => e instanceof FlowError || e instanceof Error && e.name === "FlowError" && typeof e.reason === "string";
+function checkPriority(p) {
+  if (p === undefined)
+    return;
+  if (!Number.isInteger(p) || p < 1 || p > 5)
+    throw new Failure(`приоритет ${p}: нужно целое от 1 до 5`, { type: "InvalidPriority", nonRetryable: true });
+  return p;
+}
+var DEFAULT_PRIORITY = 3;
 // src/exit.ts
 function exitSignal() {
   let d = Promise.withResolvers();
@@ -66,12 +80,15 @@ function exitSignal() {
   };
 }
 export {
+  DEFAULT_PRIORITY,
   Failure,
   FlowError,
-  bindStepRuntime,
+  checkPriority,
   exitSignal,
   heartbeat,
   isFlowError,
   lastHeartbeat,
-  nonRetryable
+  nonRetryable,
+  stepAttempt,
+  stepScope
 };

package/dist/types.d.ts

@@ -21,6 +21,8 @@ export interface StepOptions {
     nonRetryableTypes?: string[];
     /** Пул шага из AppDefinition.pools — со своим пределом одновременных шагов. */
     pool?: string;
+    /** Приоритет шага в очереди пула: 1 — первым, 5 — последним. По умолчанию — приоритет процесса. */
+    priority?: number;
 }
 export interface ChildOptions {
     id: string;
@@ -44,6 +46,10 @@ export interface FlowContext {
     readonly parentId: string | undefined;
     /** Время запуска процесса: одно и то же при каждом переигрывании. */
     readonly startedAt: Date;
+    /** Приоритет процесса из start: 1 — первым, 5 — последним; не задан — 3. */
+    readonly priority: number;
+    /** Текущее время, мс: одно и то же при переигрывании. Date.now() в процессе DBOS не детерминирован. */
+    now(): Promise<number>;
     /** Шаг упал после повторов — FlowError reason "failed" или "timeout". */
     step<T>(name: string, args: unknown[], opts?: StepOptions): Promise<T>;
     /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
@@ -112,13 +118,22 @@ export interface EngineRuntime {
     /** Цикл start…stop: завершается со stop; отклоняется при сбое start и (Temporal) падении воркера. */
     done(): Promise<void>;
 }
+export interface StartOptions {
+    id: string;
+    /** Срок процесса. */
+    timeoutMs?: number;
+    /** 1 — первым, 5 — последним; шаги процесса наследуют его. */
+    priority?: number;
+}
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
 export interface EngineClient {
     /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
-    start<T>(target: FlowRef, args: unknown[], opts: {
-        id: string;
-        timeoutMs?: number;
-    }): Promise<FlowHandle<T>>;
+    start<T>(target: FlowRef, args: unknown[], opts: StartOptions): Promise<FlowHandle<T>>;
+    /**
+     * Сигнал процессу; нет идущего с этим id — запустить и отдать сигнал ему. Temporal заводит новый
+     * запуск и под id завершённого; DBOS id не переиспользует — сигнал уйдёт завершённому и пропадёт.
+     */
+    signalWithStart<T>(target: FlowRef, args: unknown[], opts: StartOptions, topic: string, value: unknown): Promise<FlowHandle<T>>;
     /** Уже запущенный процесс по id. */
     handle<T>(id: string): FlowHandle<T>;
     close(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/core",
-  "version": "0.4.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

@@ -8,12 +8,23 @@ export class Failure extends Error {
   readonly type: string;
   readonly details?: unknown;
   readonly nonRetryable: boolean;
-  constructor(message: string, opts: { type: string; details?: unknown; 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 },
+  ) {
     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;
   }
 }
 
@@ -53,3 +64,14 @@ export class FlowError extends Error {
 /** FlowError по признакам, а не по классу: класс теряется при сериализации в DBOS. */
 export const isFlowError = (e: unknown): e is FlowError =>
   e instanceof FlowError || (e instanceof Error && e.name === "FlowError" && typeof (e as FlowError).reason === "string");
+
+/** Приоритет порта — целое 1…5 (1 — первым); иное отвергается одинаково на обоих движках. */
+export function checkPriority(p: number | undefined): number | undefined {
+  if (p === undefined) return undefined;
+  // Failure, а не Error: в процессе Temporal Error — вечный повтор задачи процесса, а не отказ.
+  if (!Number.isInteger(p) || p < 1 || p > 5)
+    throw new Failure(`приоритет ${p}: нужно целое от 1 до 5`, { type: "InvalidPriority", nonRetryable: true });
+  return p;
+}
+
+export const DEFAULT_PRIORITY = 3;

package/src/heartbeat.ts

@@ -4,18 +4,30 @@
 export interface StepRuntime {
   heartbeat(details?: unknown): Promise<void>;
   lastHeartbeat(): Promise<unknown>;
+  /** Номер попытки шага, с 1. */
+  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;
 }
 
@@ -25,3 +37,6 @@ export const heartbeat = (details?: unknown): Promise<void> => current().heartbe
 /** Прогресс прошлой попытки этого шага; undefined — первая попытка или прогресса не было. */
 export const lastHeartbeat = async <T>(): Promise<T | undefined> =>
   ((await current().lastHeartbeat()) ?? undefined) as T | undefined;
+
+/** Номер попытки этого шага, с 1. DBOS считает заново после рестарта процесса, Temporal — нет. */
+export const stepAttempt = (): number => current().attempt();

package/src/index.ts

@@ -1,4 +1,4 @@
 export * from "./types";
-export { bindStepRuntime, heartbeat, lastHeartbeat, 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/src/types.ts

@@ -25,6 +25,8 @@ export interface StepOptions {
   nonRetryableTypes?: string[];
   /** Пул шага из AppDefinition.pools — со своим пределом одновременных шагов. */
   pool?: string;
+  /** Приоритет шага в очереди пула: 1 — первым, 5 — последним. По умолчанию — приоритет процесса. */
+  priority?: number;
 }
 
 export interface ChildOptions {
@@ -51,6 +53,10 @@ export interface FlowContext {
   readonly parentId: string | undefined;
   /** Время запуска процесса: одно и то же при каждом переигрывании. */
   readonly startedAt: Date;
+  /** Приоритет процесса из start: 1 — первым, 5 — последним; не задан — 3. */
+  readonly priority: number;
+  /** Текущее время, мс: одно и то же при переигрывании. Date.now() в процессе DBOS не детерминирован. */
+  now(): Promise<number>;
   /** Шаг упал после повторов — FlowError reason "failed" или "timeout". */
   step<T>(name: string, args: unknown[], opts?: StepOptions): Promise<T>;
   /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
@@ -127,10 +133,23 @@ export interface EngineRuntime {
   done(): Promise<void>;
 }
 
+export interface StartOptions {
+  id: string;
+  /** Срок процесса. */
+  timeoutMs?: number;
+  /** 1 — первым, 5 — последним; шаги процесса наследуют его. */
+  priority?: number;
+}
+
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
 export interface EngineClient {
   /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
-  start<T>(target: FlowRef, args: unknown[], opts: { id: string; timeoutMs?: number }): Promise<FlowHandle<T>>;
+  start<T>(target: FlowRef, args: unknown[], opts: StartOptions): Promise<FlowHandle<T>>;
+  /**
+   * Сигнал процессу; нет идущего с этим id — запустить и отдать сигнал ему. Temporal заводит новый
+   * запуск и под id завершённого; DBOS id не переиспользует — сигнал уйдёт завершённому и пропадёт.
+   */
+  signalWithStart<T>(target: FlowRef, args: unknown[], opts: StartOptions, topic: string, value: unknown): Promise<FlowHandle<T>>;
   /** Уже запущенный процесс по id. */
   handle<T>(id: string): FlowHandle<T>;
   close(): Promise<void>;