@devosurf/tesser-server 0.1.0-alpha.0

package/src/engine/executor.ts

@@ -0,0 +1,536 @@
+// The durable engine (ADR-0002/0003): journal-of-results over plain Postgres. The
+// handler re-executes from the top on every (re)invocation; completed steps return
+// journaled results; everything else is ordinary TypeScript. Suspensions (sleep, signal
+// waits, durable retries) unwind via RunSuspended and a queue job re-invokes later —
+// hibernate-on-wait, zero idle cost.
+//
+// Exactly-once INTERNAL: a step's checkpoint (result + buffered events + fan-out jobs)
+// commits in ONE transaction. External connector calls stay at-least-once with the
+// auto-derived idempotency key (runId + step + occurrence).
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AutomationDef, Ctx, EventDefinition, Logger, Schema, StepOpts } from "@devosurf/tesser-sdk";
+import { isRetryableError, isTerminalError, TerminalError, RetryableError } from "@devosurf/tesser-sdk";
+import {
+  buildHarnesses,
+  buildOperators,
+  decodeJournal,
+  encodeJournal,
+  nextRetryDelayMs,
+  parseDuration,
+  resolveRetryPolicy,
+  validateSchema,
+  type JsonValue,
+} from "@devosurf/tesser-sdk/internal";
+import { enqueue } from "../queue/queue.js";
+import { RunSuspended } from "./signals.js";
+import type { EngineDeps, RunOutcome, RunRow } from "./types.js";
+
+interface StepRow {
+  name: string;
+  occurrence: number;
+  status: string;
+  attempts: number;
+  result: JsonValue | null;
+  error: { name?: string; message?: string } | null;
+}
+
+interface ActiveStep {
+  name: string;
+  occurrence: number;
+  idempotencyKey: string;
+  unsafeWrite: boolean;
+  events: Array<{ name: string; payload: JsonValue }>;
+}
+
+function serializeError(err: unknown): JsonValue {
+  const e = err instanceof Error ? err : new Error(String(err));
+  return {
+    name: e.name,
+    message: e.message,
+    retryable: isRetryableError(err),
+    terminal: isTerminalError(err),
+    ...(e.stack !== undefined ? { stack: e.stack.split("\n").slice(0, 12).join("\n") } : {}),
+  };
+}
+
+export async function executeRun(deps: EngineDeps, runId: string): Promise<RunOutcome> {
+  const { db } = deps;
+  const { rows: runRows } = await db.query<RunRow>(`SELECT * FROM runs WHERE id = $1`, [runId]);
+  const run = runRows[0];
+  if (!run) return "skipped";
+  if (["completed", "failed", "cancelled"].includes(run.status)) return "skipped";
+  if (!run.version_id) {
+    await db.query(`UPDATE runs SET status='failed', error=$2::jsonb, finished_at=now() WHERE id=$1`, [
+      runId,
+      JSON.stringify({ name: "TesserError", message: "run has no version" }),
+    ]);
+    return "failed";
+  }
+
+  const def = await deps.loadAutomation(run.version_id);
+  let input = run.input === null ? undefined : decodeJournal(run.input);
+
+  // Validate input against the declared schema (def.input, or the trigger's own).
+  const inputSchema =
+    def.input ??
+    (def.trigger as { input?: Schema<unknown> }).input ??
+    (def.trigger as { event?: { schema?: Schema<unknown> } }).event?.schema;
+  if (inputSchema !== undefined && input !== undefined) {
+    try {
+      input = await validateSchema(inputSchema, input, `automation "${def.id}" input`);
+    } catch (err) {
+      await db.query(`UPDATE runs SET status='failed', error=$2::jsonb, finished_at=now() WHERE id=$1`, [
+        runId,
+        JSON.stringify(serializeError(err)),
+      ]);
+      return "failed";
+    }
+  }
+
+  // ---- concurrency gate (first start only; ADR sketch: onConflict queue|drop) ----
+  if (run.status === "queued" && def.concurrency) {
+    const key =
+      run.concurrency_key ??
+      (typeof def.concurrency.key === "function" ? String(def.concurrency.key(input as never)) : "");
+    const decision = await db.tx(async (c) => {
+      await c.query(`UPDATE runs SET concurrency_key = $2 WHERE id = $1`, [runId, key]);
+      const { rows } = await c.query<{ n: string }>(
+        `SELECT count(*)::text AS n FROM runs
+         WHERE project_id = $1 AND automation_id = $2 AND env = $3
+           AND concurrency_key = $4 AND id <> $5
+           AND status IN ('running','suspended')`,
+        [run.project_id, run.automation_id, run.env, key, runId],
+      );
+      const active = Number(rows[0]?.n ?? 0);
+      if (active < def.concurrency!.limit) return "go";
+      if ((def.concurrency!.onConflict ?? "queue") === "drop") {
+        await c.query(
+          `UPDATE runs SET status='cancelled', error=$2::jsonb, finished_at=now() WHERE id=$1`,
+          [runId, JSON.stringify({ name: "ConcurrencyDrop", message: "dropped: concurrency limit reached" })],
+        );
+        return "drop";
+      }
+      await enqueue(c, {
+        kind: "run",
+        payload: { runId },
+        runAtMs: Date.now() + 2000,
+        dedupeKey: `run:${runId}`,
+      });
+      return "defer";
+    });
+    if (decision === "drop") return "skipped";
+    if (decision === "defer") return "deferred";
+  }
+
+  const attempt = run.attempt + 1;
+  await db.query(
+    `UPDATE runs SET status='running', attempt=$2, started_at=COALESCE(started_at, now()),
+       waiting_signal=NULL, wake_at=NULL WHERE id=$1`,
+    [runId, attempt],
+  );
+
+  // ---- journal ----
+  const { rows: stepRows } = await db.query<StepRow>(
+    `SELECT name, occurrence, status, attempts, result, error FROM run_steps WHERE run_id = $1`,
+    [runId],
+  );
+  const journal = new Map<string, StepRow>();
+  for (const r of stepRows) journal.set(`${r.name}#${r.occurrence}`, r);
+
+  const occurrences = new Map<string, number>();
+  const nextOcc = (name: string): number => {
+    const n = (occurrences.get(name) ?? 0) + 1;
+    occurrences.set(name, n);
+    return n;
+  };
+
+  const undoStack: Array<{ name: string; occurrence: number; undo: () => unknown | Promise<unknown> }> = [];
+  const active = new AsyncLocalStorage<ActiveStep>();
+  const defaultRetry = resolveRetryPolicy(def.retry);
+
+  const log = (level: "info" | "warn" | "error", msg: string, meta?: Record<string, unknown>, step?: string) => {
+    void db
+      .query(`INSERT INTO run_logs (run_id, step, level, msg, meta) VALUES ($1,$2,$3,$4,$5::jsonb)`, [
+        runId,
+        step ?? active.getStore()?.name ?? null,
+        level,
+        deps.mask(msg),
+        meta ? deps.mask(JSON.stringify(encodeJournal(meta))) : null,
+      ])
+      .catch(() => {});
+  };
+  const logger: Logger = {
+    info: (m, meta) => log("info", m, meta),
+    warn: (m, meta) => log("warn", m, meta),
+    error: (m, meta) => log("error", m, meta),
+  };
+
+  const hooks = {
+    current() {
+      const s = active.getStore();
+      if (!s) return undefined;
+      return {
+        name: s.name,
+        occurrence: s.occurrence,
+        idempotencyKey: s.idempotencyKey,
+        markUnsafeWrite: () => {
+          s.unsafeWrite = true;
+        },
+      };
+    },
+  };
+
+  const connections = await deps.buildConnections(run, def, hooks);
+  const secrets = await deps.resolveSecrets(run, def);
+
+  const suspendForRetry = async (delayMs: number, reason: string): Promise<never> => {
+    await db.tx(async (c) => {
+      await c.query(`UPDATE runs SET status='suspended', wake_at=$2 WHERE id=$1`, [
+        runId,
+        new Date(Date.now() + delayMs).toISOString(),
+      ]);
+      await enqueue(c, {
+        kind: "run",
+        payload: { runId },
+        runAtMs: Date.now() + delayMs,
+        dedupeKey: `run:${runId}`,
+      });
+    });
+    throw new RunSuspended(reason);
+  };
+
+  const ctx: Ctx<any, any, any, any> = {
+    async step<T>(name: string, fn: () => Promise<T> | T, opts?: StepOpts<T>): Promise<T> {
+      if (typeof name !== "string" || name.length === 0 || name.startsWith("$")) {
+        throw new TerminalError(`ctx.step: invalid step name ${JSON.stringify(name)} ("$" prefix is reserved)`);
+      }
+      if (active.getStore()) {
+        throw new TerminalError(`ctx.step("${name}") called inside step "${active.getStore()!.name}" — steps do not nest`);
+      }
+      const occurrence = nextOcc(name);
+      const key = `${name}#${occurrence}`;
+      const row = journal.get(key);
+
+      if (row?.status === "completed") {
+        const value = decodeJournal(row.result as JsonValue) as T;
+        if (opts?.undo) undoStack.push({ name, occurrence, undo: () => opts.undo!(value) });
+        return value;
+      }
+      if (row?.status === "failed") {
+        // The step already exhausted its attempts in a prior invocation; re-throwing the
+        // recorded error keeps author-level try/catch paths deterministic.
+        const msg = row.error?.message ?? "step failed";
+        throw row.error?.name === "RetryableError" ? new RetryableError(msg) : new TerminalError(msg);
+      }
+
+      const policy = resolveRetryPolicy(opts?.retry, defaultRetry);
+      const attempts = (row?.attempts ?? 0) + 1;
+      if (row) {
+        await db.query(`UPDATE run_steps SET attempts=$3, status='running' WHERE run_id=$1 AND name=$2 AND occurrence=$4`, [
+          runId,
+          name,
+          attempts,
+          occurrence,
+        ]);
+      } else {
+        await db.query(
+          `INSERT INTO run_steps (run_id, name, occurrence, status, attempts, has_undo)
+           VALUES ($1,$2,$3,'running',$4,$5)`,
+          [runId, name, occurrence, attempts, opts?.undo !== undefined],
+        );
+      }
+
+      const state: ActiveStep = {
+        name,
+        occurrence,
+        idempotencyKey: `${runId}:${name}:${occurrence}`,
+        unsafeWrite: false,
+        events: [],
+      };
+
+      try {
+        let p = Promise.resolve(active.run(state, () => fn()));
+        const timeoutMs = opts?.timeout !== undefined ? parseDuration(opts.timeout, "step timeout") : undefined;
+        if (timeoutMs !== undefined) {
+          let timer: NodeJS.Timeout;
+          p = Promise.race([
+            p,
+            new Promise<never>((_res, reject) => {
+              timer = setTimeout(
+                () => reject(new RetryableError(`step "${name}" timed out after ${opts?.timeout}`)),
+                timeoutMs,
+              );
+              timer.unref?.();
+            }),
+          ]).finally(() => clearTimeout(timer));
+        }
+        const result = await p;
+        const encoded = encodeJournal(result);
+
+        // THE exactly-once-internal checkpoint: result + outbox events + fan-out jobs.
+        await db.tx(async (c) => {
+          await c.query(
+            `UPDATE run_steps SET status='completed', result=$4::jsonb, finished_at=now()
+             WHERE run_id=$1 AND name=$2 AND occurrence=$3`,
+            [runId, name, occurrence, JSON.stringify(encoded)],
+          );
+          for (const evt of state.events) {
+            const { rows } = await c.query<{ id: string }>(
+              `INSERT INTO events (project_id, env, name, payload, emitted_by_run)
+               VALUES ($1,$2,$3,$4::jsonb,$5) RETURNING id`,
+              [run.project_id, run.env, evt.name, JSON.stringify(evt.payload), runId],
+            );
+            await enqueue(c, { kind: "event-fanout", payload: { eventId: rows[0]!.id } });
+          }
+        });
+        journal.set(key, { name, occurrence, status: "completed", attempts, result: encoded, error: null });
+        if (opts?.undo) undoStack.push({ name, occurrence, undo: () => opts.undo!(result) });
+        return result;
+      } catch (err) {
+        if (err instanceof RunSuspended) throw err;
+        const serialized = serializeError(err);
+        const finalize = async () => {
+          await db.query(
+            `UPDATE run_steps SET status='failed', error=$4::jsonb, finished_at=now()
+             WHERE run_id=$1 AND name=$2 AND occurrence=$3`,
+            [runId, name, occurrence, JSON.stringify(serialized)],
+          );
+          journal.set(key, { name, occurrence, status: "failed", attempts, result: null, error: serialized as never });
+        };
+
+        if (isTerminalError(err)) {
+          await finalize();
+          throw err;
+        }
+        if (state.unsafeWrite && opts?.retry === undefined) {
+          log(
+            "warn",
+            `step "${name}" performed a non-retry-safe write and will not auto-retry (ADR-0012) — pass StepOpts.retry to opt in`,
+            undefined,
+            name,
+          );
+          await finalize();
+          throw err;
+        }
+        const delay = nextRetryDelayMs(policy, attempts, isRetryableError(err) ? err.retryAfterMs : undefined);
+        if (delay === null) {
+          await finalize();
+          throw err;
+        }
+        await db.query(
+          `UPDATE run_steps SET error=$4::jsonb WHERE run_id=$1 AND name=$2 AND occurrence=$3`,
+          [runId, name, occurrence, JSON.stringify(serialized)],
+        );
+        log("warn", `step "${name}" attempt ${attempts} failed (${(err as Error).message}) — retrying in ${delay}ms`, undefined, name);
+        return suspendForRetry(delay, `retry step ${name}#${occurrence}`);
+      }
+    },
+
+    connections: connections as never,
+    secrets: secrets as never,
+    operators: {} as never,
+    harnesses: {} as never,
+
+    async sleep(duration: string): Promise<void> {
+      if (active.getStore()) {
+        throw new TerminalError(`ctx.sleep cannot be called inside step "${active.getStore()!.name}"`);
+      }
+      const ms = parseDuration(duration, "ctx.sleep");
+      const occurrence = nextOcc("$sleep");
+      const row = journal.get(`$sleep#${occurrence}`);
+      if (row?.status === "completed") return;
+
+      let wakeAtMs: number;
+      if (row) {
+        wakeAtMs = Date.parse((decodeJournal(row.result as JsonValue) as { wakeAt: string }).wakeAt);
+      } else {
+        wakeAtMs = Date.now() + ms;
+        await db.query(
+          `INSERT INTO run_steps (run_id, name, occurrence, status, attempts, result)
+           VALUES ($1,'$sleep',$2,'running',1,$3::jsonb)`,
+          [runId, occurrence, JSON.stringify(encodeJournal({ wakeAt: new Date(wakeAtMs).toISOString() }))],
+        );
+      }
+      if (wakeAtMs <= Date.now()) {
+        await db.query(
+          `UPDATE run_steps SET status='completed', finished_at=now() WHERE run_id=$1 AND name='$sleep' AND occurrence=$2`,
+          [runId, occurrence],
+        );
+        journal.set(`$sleep#${occurrence}`, { name: "$sleep", occurrence, status: "completed", attempts: 1, result: null, error: null });
+        return;
+      }
+      return suspendForRetry(wakeAtMs - Date.now(), `sleep ${duration}`) as Promise<never>;
+    },
+
+    async waitForSignal<T>(name: string, opts: { schema: Schema<T>; timeout?: string }): Promise<T | null> {
+      if (active.getStore()) {
+        throw new TerminalError(`ctx.waitForSignal cannot be called inside step "${active.getStore()!.name}"`);
+      }
+      const stepName = `$signal:${name}`;
+      const occurrence = nextOcc(stepName);
+      const row = journal.get(`${stepName}#${occurrence}`);
+      if (row?.status === "completed") {
+        const stored = decodeJournal(row.result as JsonValue) as { value?: unknown; timedOut?: boolean };
+        return stored.timedOut === true ? null : (stored.value as T);
+      }
+
+      let deadlineMs: number | undefined;
+      if (row) {
+        const stored = decodeJournal(row.result as JsonValue) as { deadline?: string };
+        deadlineMs = stored.deadline !== undefined ? Date.parse(stored.deadline) : undefined;
+      } else if (opts.timeout !== undefined) {
+        deadlineMs = Date.now() + parseDuration(opts.timeout, "waitForSignal timeout");
+      }
+
+      // Try to consume a delivered signal (exactly-once: consumption + checkpoint in one tx).
+      const consumed = await db.tx(async (c) => {
+        const { rows } = await c.query<{ id: string; payload: JsonValue }>(
+          `SELECT id, payload FROM signals
+           WHERE run_id=$1 AND name=$2 AND NOT consumed
+           ORDER BY created_at LIMIT 1 FOR UPDATE SKIP LOCKED`,
+          [runId, name],
+        );
+        const sig = rows[0];
+        if (!sig) return undefined;
+        await c.query(`UPDATE signals SET consumed=true WHERE id=$1`, [sig.id]);
+        const resultJson = JSON.stringify(encodeJournal({ value: decodeJournal(sig.payload ?? null) }));
+        if (row) {
+          await c.query(
+            `UPDATE run_steps SET status='completed', result=$4::jsonb, finished_at=now()
+             WHERE run_id=$1 AND name=$2 AND occurrence=$3`,
+            [runId, stepName, occurrence, resultJson],
+          );
+        } else {
+          await c.query(
+            `INSERT INTO run_steps (run_id, name, occurrence, status, attempts, result, finished_at)
+             VALUES ($1,$2,$3,'completed',1,$4::jsonb,now())`,
+            [runId, stepName, occurrence, resultJson],
+          );
+        }
+        return sig.payload ?? null;
+      });
+      if (consumed !== undefined) {
+        const value = decodeJournal(consumed);
+        journal.set(`${stepName}#${occurrence}`, {
+          name: stepName,
+          occurrence,
+          status: "completed",
+          attempts: 1,
+          result: encodeJournal({ value }),
+          error: null,
+        });
+        return validateSchema(opts.schema, value, `signal "${name}" payload`);
+      }
+
+      if (deadlineMs !== undefined && deadlineMs <= Date.now()) {
+        const resultJson = JSON.stringify(encodeJournal({ timedOut: true }));
+        await db.query(
+          row
+            ? `UPDATE run_steps SET status='completed', result=$4::jsonb, finished_at=now() WHERE run_id=$1 AND name=$2 AND occurrence=$3`
+            : `INSERT INTO run_steps (run_id, name, occurrence, status, attempts, result, finished_at) VALUES ($1,$2,$3,'completed',1,$4::jsonb,now())`,
+          [runId, stepName, occurrence, resultJson],
+        );
+        journal.set(`${stepName}#${occurrence}`, { name: stepName, occurrence, status: "completed", attempts: 1, result: { timedOut: true } as never, error: null });
+        return null;
+      }
+
+      if (!row) {
+        await db.query(
+          `INSERT INTO run_steps (run_id, name, occurrence, status, attempts, result)
+           VALUES ($1,$2,$3,'running',1,$4::jsonb)`,
+          [
+            runId,
+            stepName,
+            occurrence,
+            JSON.stringify(
+              encodeJournal(deadlineMs !== undefined ? { deadline: new Date(deadlineMs).toISOString() } : {}),
+            ),
+          ],
+        );
+      }
+      await db.tx(async (c) => {
+        await c.query(`UPDATE runs SET status='suspended', waiting_signal=$2, wake_at=$3 WHERE id=$1`, [
+          runId,
+          name,
+          deadlineMs !== undefined ? new Date(deadlineMs).toISOString() : null,
+        ]);
+        if (deadlineMs !== undefined) {
+          await enqueue(c, { kind: "run", payload: { runId }, runAtMs: deadlineMs, dedupeKey: `run:${runId}` });
+        }
+      });
+      throw new RunSuspended(`waitForSignal ${name}`);
+    },
+
+    async emit<T>(event: EventDefinition<T>, payload: T): Promise<void> {
+      const state = active.getStore();
+      if (!state) {
+        throw new TerminalError(
+          `ctx.emit("${event.name}") outside ctx.step — emitting is a side effect; wrap it (ADR-0002)`,
+        );
+      }
+      const validated = await validateSchema(event.schema, payload, `event "${event.name}" payload`);
+      state.events.push({ name: event.name, payload: encodeJournal(validated as unknown) });
+    },
+
+    ...(run.trigger["request"] !== undefined
+      ? {
+          request: (() => {
+            const r = run.trigger["request"] as { headers: Record<string, string>; query: Record<string, string>; rawBodyB64: string };
+            return {
+              headers: r.headers ?? {},
+              query: r.query ?? {},
+              rawBody: new Uint8Array(Buffer.from(r.rawBodyB64 ?? "", "base64")),
+            };
+          })(),
+        }
+      : {}),
+
+    logger,
+    run: { id: runId, attempt, automationId: run.automation_id },
+  };
+
+  (ctx as { operators: unknown }).operators = buildOperators(def, ctx, async (info) => {
+    if (!deps.callModel) throw new TerminalError(`operator.${info.operatorKey}: no model adapter configured`);
+    return deps.callModel(run, def, hooks, info);
+  });
+  (ctx as { harnesses: unknown }).harnesses = buildHarnesses(def, ctx, async (info) => {
+    if (!deps.callHarness) throw new TerminalError(`harness.${info.harnessKey}: no Harness adapter configured`);
+    return deps.callHarness(run, def, hooks, info);
+  });
+
+  try {
+    let output: unknown = await def.run(input as never, ctx as never);
+    if (def.output) {
+      output = await validateSchema(def.output, output, `automation "${def.id}" output`);
+    }
+    await db.query(`UPDATE runs SET status='completed', output=$2::jsonb, finished_at=now() WHERE id=$1`, [
+      runId,
+      JSON.stringify(encodeJournal(output)),
+    ]);
+    return "completed";
+  } catch (err) {
+    if (err instanceof RunSuspended) return "suspended";
+
+    // Terminal failure → undo completed steps in reverse, best-effort + durable bookkeeping.
+    for (const item of [...undoStack].reverse()) {
+      try {
+        await item.undo();
+        await db.query(`UPDATE run_steps SET undone=true WHERE run_id=$1 AND name=$2 AND occurrence=$3`, [
+          runId,
+          item.name,
+          item.occurrence,
+        ]);
+        log("info", `undo: reversed step "${item.name}"`, undefined, item.name);
+      } catch (undoErr) {
+        log("error", `undo for step "${item.name}" failed: ${(undoErr as Error).message}`, undefined, item.name);
+      }
+    }
+    await db.query(`UPDATE runs SET status='failed', error=$2::jsonb, finished_at=now() WHERE id=$1`, [
+      runId,
+      JSON.stringify(serializeError(err)),
+    ]);
+    log("error", `run failed: ${(err as Error).message}`);
+    return "failed";
+  }
+}

package/src/engine/runs.ts

@@ -0,0 +1,83 @@
+// Run lifecycle entry points: create-and-enqueue (one tx), signal delivery (wakes the
+// waiting run), cancel.
+
+import type { JsonValue } from "@devosurf/tesser-sdk/internal";
+import { encodeJournal } from "@devosurf/tesser-sdk/internal";
+import type { Db, DbClient } from "../db/db.js";
+import { enqueue } from "../queue/queue.js";
+
+export interface CreateRunOpts {
+  projectId: string;
+  automationId: string;
+  versionId: string;
+  env?: string;
+  trigger: { kind: string; [k: string]: unknown };
+  input?: unknown;
+  /** Cross-trigger dedup (e.g. webhook delivery id): same key → one run, ever. */
+  dedupeKey?: string;
+}
+
+export async function createRun(dbOrClient: Db | DbClient, opts: CreateRunOpts): Promise<string | null> {
+  const exec = async (c: DbClient): Promise<string | null> => {
+    const { rows } = await c.query<{ id: string }>(
+      `INSERT INTO runs (project_id, automation_id, version_id, env, status, trigger, input)
+       VALUES ($1,$2,$3,$4,'queued',$5::jsonb,$6::jsonb)
+       RETURNING id`,
+      [
+        opts.projectId,
+        opts.automationId,
+        opts.versionId,
+        opts.env ?? "production",
+        JSON.stringify(opts.trigger),
+        opts.input === undefined ? null : JSON.stringify(encodeJournal(opts.input)),
+      ],
+    );
+    const runId = rows[0]!.id;
+    await enqueue(c, {
+      kind: "run",
+      payload: { runId },
+      dedupeKey: `run:${runId}`,
+      ...(opts.dedupeKey !== undefined ? {} : {}),
+    });
+    return runId;
+  };
+  if ("tx" in dbOrClient) return dbOrClient.tx(exec);
+  return exec(dbOrClient);
+}
+
+export interface SignalDelivery {
+  runId: string;
+  name: string;
+  payload?: unknown;
+}
+
+/** Deliver a Signal: exactly-once input for ONE suspended run. Wakes it immediately
+ *  when it is waiting on this name. Returns false when the run doesn't exist. */
+export async function deliverSignal(db: Db, sig: SignalDelivery): Promise<boolean> {
+  return db.tx(async (c) => {
+    const { rows } = await c.query<{ id: string; status: string; waiting_signal: string | null }>(
+      `SELECT id, status, waiting_signal FROM runs WHERE id = $1 FOR UPDATE`,
+      [sig.runId],
+    );
+    const run = rows[0];
+    if (!run) return false;
+    await c.query(`INSERT INTO signals (run_id, name, payload) VALUES ($1,$2,$3::jsonb)`, [
+      sig.runId,
+      sig.name,
+      sig.payload === undefined ? null : JSON.stringify(encodeJournal(sig.payload)),
+    ]);
+    if (run.status === "suspended" && run.waiting_signal === sig.name) {
+      await enqueue(c, { kind: "run", payload: { runId: sig.runId }, dedupeKey: `run:${sig.runId}` });
+    }
+    return true;
+  });
+}
+
+export async function cancelRun(db: Db, runId: string, reason: string): Promise<boolean> {
+  const { rowCount } = await db.query(
+    `UPDATE runs SET status='cancelled', error=$2::jsonb, finished_at=now()
+     WHERE id=$1 AND status IN ('queued','suspended')`,
+    [runId, JSON.stringify({ name: "Cancelled", message: reason } satisfies Record<string, JsonValue>)],
+  );
+  return rowCount > 0;
+}

package/src/engine/signals.ts

@@ -0,0 +1,18 @@
+// Control-flow signal: thrown to unwind the handler when a run hibernates (sleep,
+// waitForSignal, durable retry). Zero idle cost (ADR-0002): nothing stays in memory —
+// a queue job (or an arriving Signal) re-invokes the handler, and completed steps
+// replay from the journal.
+//
+// Authors: never catch this. `catch (e)` blocks that swallow unknown errors instead of
+// rethrowing will break suspension — the same caveat every durable runtime carries.
+
+export class RunSuspended extends Error {
+  constructor(readonly reason: string) {
+    super(`tesser: run suspended (${reason}) — do not catch this`);
+    this.name = "TesserRunSuspended";
+  }
+}
+
+export function isRunSuspended(err: unknown): err is RunSuspended {
+  return err instanceof RunSuspended || (err as Error)?.name === "TesserRunSuspended";
+}

package/src/engine/types.ts

@@ -0,0 +1,53 @@
+import type { AutomationDef } from "@devosurf/tesser-sdk";
+import type { HarnessCallInfo, JsonValue, ModelCallInfo } from "@devosurf/tesser-sdk/internal";
+import type { Db } from "../db/db.js";
+
+export interface RunRow {
+  id: string;
+  project_id: string;
+  automation_id: string;
+  version_id: string | null;
+  env: string;
+  status: string;
+  trigger: { kind: string; [k: string]: unknown };
+  input: JsonValue | null;
+  attempt: number;
+  concurrency_key: string | null;
+  waiting_signal: string | null;
+}
+
+/** Hooks the broker layer uses to attribute connector calls to the active step. */
+export interface ActiveStepHooks {
+  current():
+    | { name: string; occurrence: number; idempotencyKey: string; markUnsafeWrite(): void }
+    | undefined;
+}
+
+/** Engine dependencies — the seams where the loader (git-sync artifacts) and the
+ *  credential broker plug in; tests inject in-memory versions. */
+export interface EngineDeps {
+  db: Db;
+  loadAutomation(versionId: string): Promise<AutomationDef<any, any, any, any, any, any, any>>;
+  buildConnections(
+    run: RunRow,
+    def: AutomationDef<any, any, any, any, any, any, any>,
+    hooks: ActiveStepHooks,
+  ): Promise<Record<string, unknown>>;
+  resolveSecrets(run: RunRow, def: AutomationDef<any, any, any, any, any, any, any>): Promise<Record<string, string>>;
+  callModel?(
+    run: RunRow,
+    def: AutomationDef<any, any, any, any, any, any, any>,
+    hooks: ActiveStepHooks,
+    info: ModelCallInfo,
+  ): Promise<import("@devosurf/tesser-sdk").NormalizedModelResponse>;
+  callHarness?(
+    run: RunRow,
+    def: AutomationDef<any, any, any, any, any, any, any>,
+    hooks: ActiveStepHooks,
+    info: HarnessCallInfo,
+  ): Promise<import("@devosurf/tesser-sdk").HarnessRunResult<unknown>>;
+  /** Mask credential material out of any string headed for logs (ADR-0005). */
+  mask(text: string): string;
+}
+
+export type RunOutcome = "completed" | "failed" | "suspended" | "skipped" | "deferred";