@iworkflow/dbos 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type EngineClient, type EngineRuntime } from "@iworkflow/core";
+export declare function dbosRuntime(): EngineRuntime;
+export declare function dbosClient(): Promise<EngineClient>;

package/dist/index.js

@@ -0,0 +1,362 @@
+// src/index.ts
+import { DBOS, DBOSClient, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import {
+  bindStepRuntime,
+  checkPriority,
+  DEFAULT_PRIORITY,
+  exitSignal,
+  Failure,
+  FlowError,
+  isFlowError
+} from "@iworkflow/core";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Pool } from "pg";
+var resultPoll = () => ({ pollingIntervalMs: Number(process.env.DBOS_RESULT_POLL_MS) || undefined });
+var sysDb = () => process.env.DBOS_SYSTEM_DATABASE_URL ?? "postgres://iworkflow:iworkflow@localhost:55432/iworkflow";
+var HEARTBEAT_DDL = [
+  "CREATE SCHEMA IF NOT EXISTS iwf",
+  `CREATE TABLE IF NOT EXISTS iwf.birth (
+    workflow_id text PRIMARY KEY, app text NOT NULL, patches text[] NOT NULL, at timestamptz NOT NULL DEFAULT now())`,
+  `CREATE TABLE IF NOT EXISTS iwf.heartbeat (
+    workflow_id text NOT NULL, step_id integer NOT NULL, details jsonb, at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (workflow_id, step_id))`
+];
+var LAUNCH_LOCK = "hashtext('iworkflow/dbos launch')";
+async function underLaunchLock(pool, fn) {
+  const c = await pool.connect();
+  try {
+    while (!(await c.query(`SELECT pg_try_advisory_lock(${LAUNCH_LOCK}) AS ok`)).rows[0].ok)
+      await sleepMs(200);
+    for (const sql of HEARTBEAT_DDL)
+      await c.query(sql);
+    return await fn();
+  } finally {
+    await c.query(`SELECT pg_advisory_unlock(${LAUNCH_LOCK})`).catch(() => {});
+    c.release();
+  }
+}
+function patchBook(db, app, declared) {
+  const births = new Map;
+  return {
+    async patched(workflowId, id) {
+      if (!declared.includes(id))
+        throw new Error(`патч "${id}" не объявлен в AppDefinition.patches модуля ${app}`);
+      let set = births.get(workflowId);
+      if (!set) {
+        await db.query("INSERT INTO iwf.birth (workflow_id, app, patches) VALUES ($1, $2, $3) ON CONFLICT (workflow_id) DO NOTHING", [workflowId, app, declared]);
+        const r = await db.query("SELECT patches FROM iwf.birth WHERE workflow_id = $1", [workflowId]);
+        set = new Set(r.rows[0].patches);
+        births.set(workflowId, set);
+      }
+      return set.has(id);
+    },
+    async born(workflowId) {
+      if (births.has(workflowId))
+        return;
+      await db.query("INSERT INTO iwf.birth (workflow_id, app, patches) VALUES ($1, $2, $3) ON CONFLICT (workflow_id) DO NOTHING", [workflowId, app, declared]);
+    }
+  };
+}
+function stepKey() {
+  const wf = DBOS.workflowID;
+  const step = DBOS.stepID;
+  if (!wf || step === undefined)
+    throw new Error("heartbeat вне шага DBOS");
+  return [wf, step];
+}
+var typeOf = (e) => e instanceof Failure ? e.type : e instanceof Error ? e.name : "Error";
+function revive(e) {
+  if (e instanceof FlowError || !isFlowError(e))
+    return e;
+  return new FlowError(e.message, { reason: e.reason, type: e.type, details: e.details, exhausted: e.exhausted });
+}
+var CANCELLED = new DBOSErrors.DBOSAwaitedWorkflowCancelledError("").dbosErrorCode;
+var isCancelled = (e) => e instanceof Error && DBOSErrors.getDBOSErrorCode(e) === CANCELLED;
+var cancelReason = (st) => st?.deadlineEpochMS !== undefined && (st.updatedAt ?? 0) >= st.deadlineEpochMS ? "timeout" : "terminated";
+async function flowFailure(e, status) {
+  if (isCancelled(e)) {
+    const reason = cancelReason(await status());
+    return new FlowError(reason === "timeout" ? "срок процесса вышел" : "процесс прерван", { reason });
+  }
+  if (isFlowError(e))
+    return new FlowError(e.message, { reason: "failed", type: e.type ?? e.reason, details: e.details });
+  if (e instanceof Error)
+    return new FlowError(e.message, { reason: "failed", type: e.type ?? e.name, details: e.details });
+  return e;
+}
+var alreadyStarted = (id) => (e) => {
+  if (DBOSErrors.isWorkflowIDInUseError(e))
+    throw new FlowError(`процесс ${id} уже есть`, { reason: "already-started" });
+  throw e;
+};
+
+class Semaphore {
+  free;
+  queue = [];
+  constructor(free) {
+    this.free = free;
+  }
+  async run(fn, priority = DEFAULT_PRIORITY) {
+    if (this.free > 0)
+      this.free--;
+    else
+      await new Promise((go) => {
+        const i = this.queue.findIndex((w) => w.priority > priority);
+        this.queue.splice(i < 0 ? this.queue.length : i, 0, { priority, go });
+      });
+    try {
+      return await fn();
+    } finally {
+      const next = this.queue.shift();
+      if (next)
+        next.go();
+      else
+        this.free++;
+    }
+  }
+}
+
+class AttemptTimeout extends Error {
+}
+var sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+var attemptNo = new AsyncLocalStorage;
+async function withTimeout(p, ms) {
+  let timer;
+  try {
+    return await Promise.race([
+      p,
+      new Promise((_, reject) => timer = setTimeout(() => reject(new AttemptTimeout(`попытка дольше ${ms} мс`)), ms))
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function attempts(fn, args, opts, pool, alive, priority) {
+  const max = opts.attempts ?? 3;
+  const started = Date.now();
+  let interval = opts.retryIntervalMs ?? 200;
+  for (let n = 1;; n++) {
+    try {
+      const attempt = () => attemptNo.run(n, () => withTimeout(fn(...args), opts.timeoutMs ?? 60000));
+      return await (pool ? pool.run(attempt, priority) : attempt());
+    } catch (e) {
+      const stop = e instanceof Failure && e.nonRetryable || (opts.nonRetryableTypes ?? []).includes(typeOf(e));
+      if (stop || n >= max) {
+        const exhausted = !stop;
+        if (e instanceof AttemptTimeout)
+          throw new FlowError(e.message, { reason: "timeout", exhausted });
+        throw new FlowError(e instanceof Error ? e.message : String(e), {
+          reason: "failed",
+          type: typeOf(e),
+          details: e instanceof Failure ? e.details : undefined,
+          exhausted
+        });
+      }
+      const wait = e instanceof Failure && e.retryAfterMs !== undefined ? e.retryAfterMs : interval;
+      if (opts.totalTimeoutMs !== undefined && Date.now() - started + wait >= opts.totalTimeoutMs)
+        throw new FlowError(e instanceof Error ? e.message : String(e), {
+          reason: "timeout",
+          type: typeOf(e),
+          details: e instanceof Failure ? e.details : undefined
+        });
+      let left = wait;
+      do {
+        await sleepMs(Math.min(Math.max(left, 0), 5000));
+        if (!await alive().catch(() => true))
+          throw new FlowError("процесс прерван — повторы шага остановлены", { reason: "terminated" });
+        left -= 5000;
+      } while (left > 0);
+      interval = Math.min(interval * (opts.backoff ?? 1), opts.maxRetryIntervalMs ?? Infinity);
+    }
+  }
+}
+var FINISHED = new Set(["SUCCESS", "ERROR", "CANCELLED", "MAX_RECOVERY_ATTEMPTS_EXCEEDED"]);
+var STATUS = {
+  SUCCESS: "completed",
+  ERROR: "failed",
+  MAX_RECOVERY_ATTEMPTS_EXCEEDED: "failed"
+};
+var describeStatus = (st) => st.status === "CANCELLED" ? cancelReason(st) === "timeout" ? "timed-out" : "terminated" : STATUS[st.status] ?? "running";
+function dbosRuntime() {
+  let pool;
+  const exit = exitSignal();
+  async function launch(def) {
+    pool = new Pool({ connectionString: sysDb(), max: 2 });
+    const db = pool;
+    const patches = patchBook(db, def.app, def.patches ?? []);
+    bindStepRuntime({
+      async heartbeat(details) {
+        await db.query(`INSERT INTO iwf.heartbeat (workflow_id, step_id, details) VALUES ($1, $2, $3)
+           ON CONFLICT (workflow_id, step_id) DO UPDATE SET details = EXCLUDED.details, at = now()`, [...stepKey(), JSON.stringify(details ?? null)]);
+      },
+      async lastHeartbeat() {
+        const r = await db.query("SELECT details FROM iwf.heartbeat WHERE workflow_id = $1 AND step_id = $2", stepKey());
+        return r.rows[0]?.details ?? undefined;
+      },
+      attempt: () => {
+        const n = attemptNo.getStore();
+        if (n === undefined)
+          throw new Error("stepAttempt вне шага");
+        return n;
+      }
+    });
+    const pools = Object.fromEntries(Object.entries(def.pools ?? {}).map(([p, n]) => [p, new Semaphore(n)]));
+    const enqueue = (target, args, opts, reject, priority) => DBOS.enqueueWorkflowWithOptions({
+      queueName: target.app,
+      workflowName: target.flow,
+      workflowID: opts.id,
+      applicationName: target.app,
+      ...opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {},
+      ...reject ? { workflowIDReusePolicy: "reject" } : {},
+      priority: priority ?? DEFAULT_PRIORITY
+    }, ...args).catch(alreadyStarted(opts.id));
+    const waitChild = async (h, id) => {
+      try {
+        return await h.getResult(resultPoll());
+      } catch (e) {
+        throw await flowFailure(e, () => DBOS.getWorkflowStatus(id).then((st) => st ?? undefined));
+      }
+    };
+    for (const [name, flow] of Object.entries(def.flows)) {
+      const run = async (...args) => {
+        const workflowId = DBOS.workflowID;
+        await patches.born(workflowId);
+        const row = (await db.query("SELECT created_at, parent_workflow_id, priority FROM dbos.workflow_status WHERE workflow_uuid = $1", [
+          workflowId
+        ])).rows[0];
+        const ctx = {
+          workflowId,
+          parentId: row?.parent_workflow_id ?? undefined,
+          startedAt: new Date(Number(row?.created_at)),
+          priority: row?.priority || DEFAULT_PRIORITY,
+          now: () => DBOS.now(),
+          step: (step, stepArgs, opts = {}) => {
+            const pool = opts.pool ? pools[opts.pool] : undefined;
+            if (opts.pool && !pool)
+              throw new Error(`пул "${opts.pool}" не объявлен в AppDefinition.pools модуля ${def.app}`);
+            const alive = async () => {
+              for (;; ) {
+                const st = (await db.query("SELECT status, workflow_deadline_epoch_ms AS deadline FROM dbos.workflow_status WHERE workflow_uuid = $1", [workflowId])).rows[0];
+                if (!st || !["PENDING", "ENQUEUED"].includes(st.status))
+                  return false;
+                if (st.deadline === null || Number(st.deadline) > Date.now())
+                  return true;
+                if (Date.now() - Number(st.deadline) > 60000)
+                  return false;
+                await sleepMs(100);
+              }
+            };
+            return DBOS.runStep(() => attempts(def.activities[step], stepArgs, opts, pool, alive, checkPriority(opts.priority) ?? ctx.priority), {
+              name: step,
+              retriesAllowed: false
+            }).catch((e) => {
+              throw revive(e);
+            });
+          },
+          child: async (target, childArgs, opts) => waitChild(await enqueue(target, childArgs, opts, opts.onExisting === "reject", ctx.priority), opts.id),
+          async startChild(target, childArgs, opts) {
+            const h = await enqueue(target, childArgs, opts, true, ctx.priority);
+            return { id: opts.id, result: () => waitChild(h, opts.id) };
+          },
+          sleep: (ms) => DBOS.sleep(ms),
+          recv: (topic, timeoutMs) => DBOS.recv(topic, { timeoutSeconds: timeoutMs / 1000, ...resultPoll() }),
+          async signal(target, topic, value) {
+            const status = await DBOS.runStep(async () => (await db.query("SELECT status FROM dbos.workflow_status WHERE workflow_uuid = $1", [target])).rows[0]?.status ?? null, { name: "iwf.signalTarget" });
+            if (status === null || FINISHED.has(status))
+              throw new FlowError(`процесса ${target} нет или он завершён`, { reason: "not-found" });
+            await DBOS.send(target, value, topic);
+          },
+          setState: (key, value) => DBOS.setEvent(key, value),
+          patched: (id) => patches.patched(workflowId, id),
+          deprecatePatch: async () => {}
+        };
+        return flow(ctx, ...args);
+      };
+      DBOS.registerWorkflow(run, { name });
+    }
+    DBOS.setConfig({
+      name: def.app,
+      systemDatabaseUrl: sysDb(),
+      logLevel: "warn",
+      applicationVersion: process.env.DBOS_APPLICATION_VERSION ?? `${def.app}-patching`
+    });
+    await underLaunchLock(db, () => DBOS.launch());
+    const poll = Number(process.env.DBOS_QUEUE_POLL_MS) || undefined;
+    await DBOS.registerQueue(def.app, { minPollingIntervalMs: poll, onConflict: "always_update" });
+  }
+  return {
+    done: () => exit.promise(),
+    async start(def) {
+      exit.arm();
+      try {
+        await launch(def);
+      } catch (e) {
+        await pool?.end().catch(() => {});
+        pool = undefined;
+        exit.reject(e);
+        throw e;
+      }
+    },
+    async stop() {
+      try {
+        await DBOS.shutdown();
+        await pool?.end();
+      } finally {
+        exit.resolve();
+      }
+    }
+  };
+}
+async function dbosClient() {
+  const client = await DBOSClient.create({ systemDatabaseUrl: sysDb() });
+  const status = (id) => client.getWorkflow(id);
+  const exists = async (id) => {
+    const st = await status(id);
+    if (!st)
+      throw new FlowError(`процесса ${id} нет`, { reason: "not-found" });
+    return st;
+  };
+  const wrap = (id) => ({
+    id,
+    result: () => client.retrieveWorkflow(id).getResult(resultPoll()).catch(async (e) => {
+      throw await flowFailure(e, () => status(id));
+    }),
+    signal: (topic, value) => client.send(id, value, topic),
+    query: async (key) => await client.getEvent(id, key, { timeoutSeconds: 0 }) ?? undefined,
+    async describe() {
+      const st = await exists(id);
+      return { id, status: describeStatus(st), startedAt: new Date(st.createdAt) };
+    },
+    async terminate() {
+      await exists(id);
+      await client.cancelWorkflow(id);
+    }
+  });
+  const self = {
+    async start(target, args, opts) {
+      const h = await client.enqueue({
+        queueName: target.app,
+        workflowName: target.flow,
+        workflowID: opts.id,
+        applicationName: target.app,
+        ...opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {},
+        priority: checkPriority(opts.priority) ?? DEFAULT_PRIORITY
+      }, ...args);
+      return wrap(h.workflowID);
+    },
+    async signalWithStart(target, args, opts, topic, value) {
+      const h = await self.start(target, args, opts);
+      if (FINISHED.has((await status(h.id))?.status ?? ""))
+        throw new FlowError(`процесс ${h.id} уже завершён — id не переиспользуется`, { reason: "already-started" });
+      await client.send(h.id, value, topic);
+      return h;
+    },
+    handle: (id) => wrap(id),
+    close: () => client.destroy()
+  };
+  return self;
+}
+export {
+  dbosClient,
+  dbosRuntime
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/dbos",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "DBOS adapter for @iworkflow/core",
   "keywords": [
     "workflow",
@@ -14,22 +14,30 @@
     "directory": "packages/dbos"
   },
   "files": [
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
   ],
   "type": "module",
   "sideEffects": false,
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
     "type-check": "tsc --noEmit -p tsconfig.json",
-    "test": "bun test"
+    "test": "bun test",
+    "prepack": "bun run build"
   },
   "dependencies": {
-    "@iworkflow/core": "^0.3.0",
+    "@iworkflow/core": "^0.5.0",
     "pg": "^8.0.0"
   },
   "peerDependencies": {
@@ -38,5 +46,8 @@
   "devDependencies": {
     "@dbos-inc/dbos-sdk": "^5.3.0",
     "@types/pg": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/src/index.ts

@@ -3,6 +3,9 @@
 import { DBOS, DBOSClient, Error as DBOSErrors, type WorkflowStatus } from "@dbos-inc/dbos-sdk";
 import {
   bindStepRuntime,
+  checkPriority,
+  DEFAULT_PRIORITY,
+  exitSignal,
   Failure,
   FlowError,
   isFlowError,
@@ -13,9 +16,12 @@ import {
   type EngineRuntime,
   type FlowContext,
   type FlowHandle,
+  type FlowRef,
   type FlowStatus,
+  type StartOptions,
   type StepOptions,
 } from "@iworkflow/core";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Pool } from "pg";
 
 // Ожидание результата дочернего процесса — опрос базы, по умолчанию раз в секунду: это и есть
@@ -45,7 +51,7 @@ const LAUNCH_LOCK = "hashtext('iworkflow/dbos launch')";
 async function underLaunchLock<T>(pool: Pool, fn: () => Promise<T>): Promise<T> {
   const c = await pool.connect();
   try {
-    while (!(await c.query(`SELECT pg_try_advisory_lock(${LAUNCH_LOCK}) AS ok`)).rows[0].ok) await Bun.sleep(200);
+    while (!(await c.query(`SELECT pg_try_advisory_lock(${LAUNCH_LOCK}) AS ok`)).rows[0].ok) await sleepMs(200);
     for (const sql of HEARTBEAT_DDL) await c.query(sql);
     return await fn();
   } finally {
@@ -134,17 +140,22 @@ const alreadyStarted = (id: string) => (e: unknown): never => {
 // Повторы — свои, внутри одного шага DBOS: в историю пишется уже FlowError с причиной, как у Temporal.
 // Цена: отмена процесса не прерывает повторы шага, а ждёт его конца.
 
+/** Предел одновременных шагов пула; ждущие выходят по приоритету (1 — первым), внутри — по очереди. */
 class Semaphore {
-  private queue: (() => void)[] = [];
+  private queue: { priority: number; go: () => void }[] = [];
   constructor(private free: number) {}
-  async run<T>(fn: () => Promise<T>): Promise<T> {
+  async run<T>(fn: () => Promise<T>, priority = DEFAULT_PRIORITY): Promise<T> {
     if (this.free > 0) this.free--;
-    else await new Promise<void>((r) => this.queue.push(r));
+    else
+      await new Promise<void>((go) => {
+        const i = this.queue.findIndex((w) => w.priority > priority);
+        this.queue.splice(i < 0 ? this.queue.length : i, 0, { priority, go });
+      });
     try {
       return await fn();
     } finally {
       const next = this.queue.shift();
-      if (next) next();
+      if (next) next.go();
       else this.free++;
     }
   }
@@ -154,6 +165,9 @@ class AttemptTimeout extends Error {}
 
 const sleepMs = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
+/** Номер идущей попытки шага — для stepAttempt(). */
+const attemptNo = new AsyncLocalStorage<number>();
+
 /** Попытка, урезанная по сроку: брошенная продолжает идти в фоне, её итог отбрасывается. */
 async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -174,14 +188,15 @@ async function attempts(
   opts: StepOptions,
   pool: Semaphore | undefined,
   alive: () => Promise<boolean>,
+  priority: number | undefined,
 ) {
   const max = opts.attempts ?? 3;
   const started = Date.now();
   let interval = opts.retryIntervalMs ?? 200;
   for (let n = 1; ; n++) {
     try {
-      const attempt = () => withTimeout(fn(...args), opts.timeoutMs ?? 60_000);
-      return await (pool ? pool.run(attempt) : attempt());
+      const attempt = () => attemptNo.run(n, () => withTimeout(fn(...args), opts.timeoutMs ?? 60_000));
+      return await (pool ? pool.run(attempt, priority) : attempt());
     } catch (e) {
       const stop = (e instanceof Failure && e.nonRetryable) || (opts.nonRetryableTypes ?? []).includes(typeOf(e));
       if (stop || n >= max) {
@@ -194,16 +209,24 @@ async function attempts(
           exhausted,
         });
       }
-      if (opts.totalTimeoutMs !== undefined && Date.now() - started + interval >= opts.totalTimeoutMs)
+      // Отказ сам назвал срок (FLOOD_WAIT) — ждём его, а не паузу из opts.
+      const wait = e instanceof Failure && e.retryAfterMs !== undefined ? e.retryAfterMs : interval;
+      if (opts.totalTimeoutMs !== undefined && Date.now() - started + wait >= opts.totalTimeoutMs)
         throw new FlowError(e instanceof Error ? e.message : String(e), {
           reason: "timeout",
           type: typeOf(e),
           details: e instanceof Failure ? e.details : undefined,
         });
-      await sleepMs(interval);
-      // После паузы: за неё процесс мог выйти по сроку или быть отменён.
+      // Пауза кусками: срок или отмена процесса видны не позже чем через 5 с, а не после всей паузы.
       // Сбой чтения статуса — не повод бросать шаг: повторяем дальше.
-      if (!(await alive().catch(() => true))) throw new FlowError("процесс прерван — повторы шага остановлены", { reason: "terminated" });
+      // do…while: и при нулевой паузе статус процесса проверяется перед каждой попыткой.
+      let left = wait;
+      do {
+        await sleepMs(Math.min(Math.max(left, 0), 5_000));
+        if (!(await alive().catch(() => true)))
+          throw new FlowError("процесс прерван — повторы шага остановлены", { reason: "terminated" });
+        left -= 5_000;
+      } while (left > 0);
       interval = Math.min(interval * (opts.backoff ?? 1), opts.maxRetryIntervalMs ?? Infinity);
     }
   }
@@ -222,132 +245,166 @@ const describeStatus = (st: WorkflowStatus): FlowStatus =>
 
 export function dbosRuntime(): EngineRuntime {
   let pool: Pool | undefined;
-  return {
-    async start(def: AppDefinition) {
-      pool = new Pool({ connectionString: sysDb(), max: 2 });
-      const db = pool;
-      const patches = patchBook(db, def.app, def.patches ?? []);
-      bindStepRuntime({
-        async heartbeat(details) {
-          await db.query(
-            `INSERT INTO iwf.heartbeat (workflow_id, step_id, details) VALUES ($1, $2, $3)
-             ON CONFLICT (workflow_id, step_id) DO UPDATE SET details = EXCLUDED.details, at = now()`,
-            [...stepKey(), JSON.stringify(details ?? null)],
-          );
-        },
-        async lastHeartbeat() {
-          const r = await db.query("SELECT details FROM iwf.heartbeat WHERE workflow_id = $1 AND step_id = $2", stepKey());
-          return r.rows[0]?.details ?? undefined;
+  // Воркеров у DBOS нет: done() — до stop или сбоя start; падения исполнителя DBOS не видно.
+  const exit = exitSignal();
+  async function launch(def: AppDefinition) {
+    pool = new Pool({ connectionString: sysDb(), max: 2 });
+    const db = pool;
+    const patches = patchBook(db, def.app, def.patches ?? []);
+    bindStepRuntime({
+      async heartbeat(details) {
+        await db.query(
+          `INSERT INTO iwf.heartbeat (workflow_id, step_id, details) VALUES ($1, $2, $3)
+           ON CONFLICT (workflow_id, step_id) DO UPDATE SET details = EXCLUDED.details, at = now()`,
+          [...stepKey(), JSON.stringify(details ?? null)],
+        );
+      },
+      async lastHeartbeat() {
+        const r = await db.query("SELECT details FROM iwf.heartbeat WHERE workflow_id = $1 AND step_id = $2", stepKey());
+        return r.rows[0]?.details ?? undefined;
+      },
+      attempt: () => {
+        const n = attemptNo.getStore();
+        if (n === undefined) throw new Error("stepAttempt вне шага");
+        return n;
+      },
+    });
+    const pools = Object.fromEntries(Object.entries(def.pools ?? {}).map(([p, n]) => [p, new Semaphore(n)]));
+    const enqueue = (
+      target: { app: string; flow: string },
+      args: unknown[],
+      opts: ChildOptions,
+      reject: boolean,
+      priority: number | undefined,
+    ) =>
+      DBOS.enqueueWorkflowWithOptions(
+        {
+          queueName: target.app,
+          workflowName: target.flow,
+          workflowID: opts.id,
+          applicationName: target.app,
+          ...(opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {}),
+          ...(reject ? { workflowIDReusePolicy: "reject" as const } : {}),
+          // Ребёнок наследует приоритет родителя, как у Temporal.
+          priority: priority ?? DEFAULT_PRIORITY,
         },
-      });
-      const pools = Object.fromEntries(Object.entries(def.pools ?? {}).map(([p, n]) => [p, new Semaphore(n)]));
-      const enqueue = (target: { app: string; flow: string }, args: unknown[], opts: ChildOptions, reject: boolean) =>
-        DBOS.enqueueWorkflowWithOptions(
-          {
-            queueName: target.app,
-            workflowName: target.flow,
-            workflowID: opts.id,
-            applicationName: target.app,
-            ...(opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {}),
-            ...(reject ? { workflowIDReusePolicy: "reject" as const } : {}),
-          },
-          ...args,
-        ).catch(alreadyStarted(opts.id));
-      const waitChild = async <T>(h: { getResult(o?: object): Promise<unknown> }, id: string): Promise<T> => {
-        try {
-          return (await h.getResult(resultPoll())) as T;
-        } catch (e) {
-          throw await flowFailure(e, () => DBOS.getWorkflowStatus(id).then((st) => st ?? undefined));
-        }
-      };
-      for (const [name, flow] of Object.entries(def.flows)) {
-        const run = async (...args: unknown[]) => {
-          const workflowId = DBOS.workflowID!;
-          await patches.born(workflowId);
-          // Строка статуса не меняется после создания: чтение вне шага детерминировано.
-          const row = (
-            await db.query("SELECT created_at, parent_workflow_id FROM dbos.workflow_status WHERE workflow_uuid = $1", [
-              workflowId,
-            ])
-          ).rows[0];
-          const ctx: FlowContext = {
+        ...args,
+      ).catch(alreadyStarted(opts.id));
+    const waitChild = async <T>(h: { getResult(o?: object): Promise<unknown> }, id: string): Promise<T> => {
+      try {
+        return (await h.getResult(resultPoll())) as T;
+      } catch (e) {
+        throw await flowFailure(e, () => DBOS.getWorkflowStatus(id).then((st) => st ?? undefined));
+      }
+    };
+    for (const [name, flow] of Object.entries(def.flows)) {
+      const run = async (...args: unknown[]) => {
+        const workflowId = DBOS.workflowID!;
+        await patches.born(workflowId);
+        // Строка статуса не меняется после создания: чтение вне шага детерминировано.
+        const row = (
+          await db.query("SELECT created_at, parent_workflow_id, priority FROM dbos.workflow_status WHERE workflow_uuid = $1", [
             workflowId,
-            parentId: row?.parent_workflow_id ?? undefined,
-            startedAt: new Date(Number(row?.created_at)),
-            step: (step, stepArgs, opts = {}) => {
-              const pool = opts.pool ? pools[opts.pool] : undefined;
-              if (opts.pool && !pool) throw new Error(`пул "${opts.pool}" не объявлен в AppDefinition.pools модуля ${def.app}`);
-              // heartbeatTimeoutMs у DBOS не действует: умерший процесс ловится рестартом, шаг повторяется.
-              // Срок вышел, а DBOS ещё не отменил процесс — ждём отмены: иначе процесс поймает отказ и завершится успехом.
-              const alive = async () => {
-                for (;;) {
-                  const st = (
-                    await db.query(
-                      "SELECT status, workflow_deadline_epoch_ms AS deadline FROM dbos.workflow_status WHERE workflow_uuid = $1",
-                      [workflowId],
-                    )
-                  ).rows[0];
-                  if (!st || !["PENDING", "ENQUEUED"].includes(st.status)) return false;
-                  if (st.deadline === null || Number(st.deadline) > Date.now()) return true;
-                  // Отмену ставит DBOS; не поставил за минуту — не ждать вечно.
-                  if (Date.now() - Number(st.deadline) > 60_000) return false;
-                  await sleepMs(100);
-                }
-              };
-              return DBOS.runStep(() => attempts(def.activities[step]!, stepArgs, opts, pool, alive), {
-                name: step,
-                retriesAllowed: false,
-              }).catch((e) => {
-                throw revive(e);
-              }) as Promise<never>;
-            },
-            child: async (target, childArgs, opts) =>
-              waitChild(await enqueue(target, childArgs, opts, opts.onExisting === "reject"), opts.id),
-            async startChild(target, childArgs, opts) {
-              // Процесс DBOS не привязан к родителю: живёт сам, как ABANDON у Temporal.
-              const h = await enqueue(target, childArgs, opts, true);
-              return { id: opts.id, result: () => waitChild(h, opts.id) };
-            },
-            sleep: (ms) => DBOS.sleep(ms),
-            recv: (topic, timeoutMs) => DBOS.recv(topic, { timeoutSeconds: timeoutMs / 1000, ...resultPoll() }),
-            async signal(target, topic, value) {
-              // Отправка завершённому процессу у DBOS проходит молча; Temporal отказывает — проверяем сами.
-              const status = await DBOS.runStep(
-                async () =>
-                  ((await db.query("SELECT status FROM dbos.workflow_status WHERE workflow_uuid = $1", [target])).rows[0]
-                    ?.status as string | undefined) ?? null,
-                { name: "iwf.signalTarget" },
-              );
-              if (status === null || FINISHED.has(status))
-                throw new FlowError(`процесса ${target} нет или он завершён`, { reason: "not-found" });
-              await DBOS.send(target, value, topic);
-            },
-            setState: (key, value) => DBOS.setEvent(key, value),
-            patched: (id) => patches.patched(workflowId, id),
-            // Старых процессов нет — ветка всегда новая; вызов можно удалять.
-            deprecatePatch: async () => {},
-          };
-          return flow(ctx, ...args);
+          ])
+        ).rows[0];
+        const ctx: FlowContext = {
+          workflowId,
+          parentId: row?.parent_workflow_id ?? undefined,
+          startedAt: new Date(Number(row?.created_at)),
+          priority: row?.priority || DEFAULT_PRIORITY,
+          now: () => DBOS.now(),
+          step: (step, stepArgs, opts = {}) => {
+            const pool = opts.pool ? pools[opts.pool] : undefined;
+            if (opts.pool && !pool) throw new Error(`пул "${opts.pool}" не объявлен в AppDefinition.pools модуля ${def.app}`);
+            // heartbeatTimeoutMs у DBOS не действует: умерший процесс ловится рестартом, шаг повторяется.
+            // Срок вышел, а DBOS ещё не отменил процесс — ждём отмены: иначе процесс поймает отказ и завершится успехом.
+            const alive = async () => {
+              for (;;) {
+                const st = (
+                  await db.query(
+                    "SELECT status, workflow_deadline_epoch_ms AS deadline FROM dbos.workflow_status WHERE workflow_uuid = $1",
+                    [workflowId],
+                  )
+                ).rows[0];
+                if (!st || !["PENDING", "ENQUEUED"].includes(st.status)) return false;
+                if (st.deadline === null || Number(st.deadline) > Date.now()) return true;
+                // Отмену ставит DBOS; не поставил за минуту — не ждать вечно.
+                if (Date.now() - Number(st.deadline) > 60_000) return false;
+                await sleepMs(100);
+              }
+            };
+            return DBOS.runStep(() => attempts(def.activities[step]!, stepArgs, opts, pool, alive, checkPriority(opts.priority) ?? ctx.priority), {
+              name: step,
+              retriesAllowed: false,
+            }).catch((e) => {
+              throw revive(e);
+            }) as Promise<never>;
+          },
+          child: async (target, childArgs, opts) =>
+            waitChild(await enqueue(target, childArgs, opts, opts.onExisting === "reject", ctx.priority), opts.id),
+          async startChild(target, childArgs, opts) {
+            // Процесс DBOS не привязан к родителю: живёт сам, как ABANDON у Temporal.
+            const h = await enqueue(target, childArgs, opts, true, ctx.priority);
+            return { id: opts.id, result: () => waitChild(h, opts.id) };
+          },
+          sleep: (ms) => DBOS.sleep(ms),
+          recv: (topic, timeoutMs) => DBOS.recv(topic, { timeoutSeconds: timeoutMs / 1000, ...resultPoll() }),
+          async signal(target, topic, value) {
+            // Отправка завершённому процессу у DBOS проходит молча; Temporal отказывает — проверяем сами.
+            const status = await DBOS.runStep(
+              async () =>
+                ((await db.query("SELECT status FROM dbos.workflow_status WHERE workflow_uuid = $1", [target])).rows[0]
+                  ?.status as string | undefined) ?? null,
+              { name: "iwf.signalTarget" },
+            );
+            if (status === null || FINISHED.has(status))
+              throw new FlowError(`процесса ${target} нет или он завершён`, { reason: "not-found" });
+            await DBOS.send(target, value, topic);
+          },
+          setState: (key, value) => DBOS.setEvent(key, value),
+          patched: (id) => patches.patched(workflowId, id),
+          // Старых процессов нет — ветка всегда новая; вызов можно удалять.
+          deprecatePatch: async () => {},
         };
-        DBOS.registerWorkflow(run, { name });
+        return flow(ctx, ...args);
+      };
+      DBOS.registerWorkflow(run, { name });
+    }
+    // Версия постоянна, ветки кода — patched. Без этого версия — хэш кода, и после выкатки новый
+    // процесс не подхватывает незавершённые процессы старого. Своя на модуль: в общей системной
+    // базе DBOS требует уникальных имён версий.
+    DBOS.setConfig({
+      name: def.app,
+      systemDatabaseUrl: sysDb(),
+      logLevel: "warn",
+      applicationVersion: process.env.DBOS_APPLICATION_VERSION ?? `${def.app}-patching`,
+    });
+    await underLaunchLock(db, () => DBOS.launch());
+    // Опрос очереди — главный вклад в задержку перехода между модулями (по умолчанию ~1 с).
+    const poll = Number(process.env.DBOS_QUEUE_POLL_MS) || undefined;
+    await DBOS.registerQueue(def.app, { minPollingIntervalMs: poll, onConflict: "always_update" });
+  }
+  return {
+    done: () => exit.promise(),
+    async start(def: AppDefinition) {
+      exit.arm();
+      // Не запустился — done() отклоняется: для наблюдателя это сбой, а не штатный выход.
+      try {
+        await launch(def);
+      } catch (e) {
+        await pool?.end().catch(() => {});
+        pool = undefined;
+        exit.reject(e);
+        throw e;
       }
-      // Версия постоянна, ветки кода — patched. Без этого версия — хэш кода, и после выкатки новый
-      // процесс не подхватывает незавершённые процессы старого. Своя на модуль: в общей системной
-      // базе DBOS требует уникальных имён версий.
-      DBOS.setConfig({
-        name: def.app,
-        systemDatabaseUrl: sysDb(),
-        logLevel: "warn",
-        applicationVersion: process.env.DBOS_APPLICATION_VERSION ?? `${def.app}-patching`,
-      });
-      await underLaunchLock(db, () => DBOS.launch());
-      // Опрос очереди — главный вклад в задержку перехода между модулями (по умолчанию ~1 с).
-      const poll = Number(process.env.DBOS_QUEUE_POLL_MS) || undefined;
-      await DBOS.registerQueue(def.app, { minPollingIntervalMs: poll, onConflict: "always_update" });
     },
     async stop() {
-      await DBOS.shutdown();
-      await pool?.end();
+      try {
+        await DBOS.shutdown();
+        await pool?.end();
+      } finally {
+        exit.resolve();
+      }
     },
   };
 }
@@ -378,7 +435,7 @@ export async function dbosClient(): Promise<EngineClient> {
       await client.cancelWorkflow(id);
     },
   });
-  return {
+  const self: EngineClient = {
     async start(target, args, opts) {
       const h = await client.enqueue(
         {
@@ -387,12 +444,24 @@ export async function dbosClient(): Promise<EngineClient> {
           workflowID: opts.id,
           applicationName: target.app,
           ...(opts.timeoutMs ? { workflowTimeoutMS: opts.timeoutMs } : {}),
+          // Без приоритета DBOS ставит 0 — впереди всех; порт по умолчанию 3, как Temporal.
+          priority: checkPriority(opts.priority) ?? DEFAULT_PRIORITY,
         },
         ...args,
       );
       return wrap(h.workflowID);
     },
+    async signalWithStart<T>(target: FlowRef, args: unknown[], opts: StartOptions, topic: string, value: unknown) {
+      // Не атомарно, но без потерь: сигнал ждёт в очереди темы, пока процесс до него дойдёт.
+      const h = await self.start<T>(target, args, opts);
+      // id завершённого DBOS не переиспользует: сигнал ушёл бы в никуда.
+      if (FINISHED.has((await status(h.id))?.status ?? ""))
+        throw new FlowError(`процесс ${h.id} уже завершён — id не переиспользуется`, { reason: "already-started" });
+      await client.send(h.id, value, topic);
+      return h;
+    },
     handle: (id) => wrap(id),
     close: () => client.destroy(),
   };
+  return self;
 }