@stigmer/server 3.14.0-dev.20260910084630

package/src/temporal/workflow-source.ts

@@ -0,0 +1,72 @@
+/**
+ * Resolves where a worker's Temporal WORKFLOW code comes from — the
+ * runner's resolveWorkflowSource seam (runner src/workflow-source.ts),
+ * generalized for a server that hosts one workflow entry per domain
+ * worker.
+ *
+ * Workflow code runs inside Temporal's deterministic sandbox and must be
+ * bundled separately from host code. Two production modes:
+ *
+ * 1. **Runtime** (this sub-project's operative mode, ratified brief #7 of
+ *    sub-project 20260824.03): the worker bundles the compiled dist entry
+ *    on boot via the SDK's built-in webpack. This is how conformance and
+ *    the CLI-launched dev server boot — node_modules present, no native
+ *    packaging needed.
+ * 2. **Prebuilt** (the hook #24 cli-cutover fills): the slim artifact
+ *    cannot bundle at runtime (no webpack/@swc shipped), so the build
+ *    emits the bundle next to main.js and this resolver finds it as a
+ *    sibling — exactly the runner's discovery rule.
+ *
+ * Callers pass URLs relative to their own module (import.meta.url): in the
+ * tsc dist the sibling bundle never exists so dev builds always take the
+ * runtime path; in a slim artifact every module collapses into main.js and
+ * the sibling resolves next to it, where #24's build will emit it.
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export type WorkflowSource =
+  | {
+      /** Pre-built bundle on disk (slim artifacts; #24). */
+      readonly kind: "prebuilt";
+      readonly codePath: string;
+    }
+  | {
+      /** Bundle on boot from the compiled workflows entry module. */
+      readonly kind: "runtime";
+      readonly workflowsPath: string;
+    };
+
+export interface ResolveWorkflowSourceOptions {
+  /**
+   * Candidate workflows entries in preference order — typically the
+   * compiled `.js` first, then the `.ts` source (the tsx dev loop runs
+   * from src/, where only the .ts exists; the SDK's bundler compiles
+   * TypeScript natively, so either candidate works).
+   */
+  readonly workflowsEntryCandidates: readonly URL[];
+  /** Where a prebuilt bundle would sit (e.g. new URL("./workflow-bundle-agent-execution.js", import.meta.url)). */
+  readonly prebuiltSibling: URL;
+}
+
+export function resolveWorkflowSource(
+  options: ResolveWorkflowSourceOptions,
+): WorkflowSource {
+  const prebuiltPath = fileURLToPath(options.prebuiltSibling);
+  if (existsSync(prebuiltPath)) {
+    return { kind: "prebuilt", codePath: prebuiltPath };
+  }
+  for (const candidate of options.workflowsEntryCandidates) {
+    const candidatePath = fileURLToPath(candidate);
+    if (existsSync(candidatePath)) {
+      return { kind: "runtime", workflowsPath: candidatePath };
+    }
+  }
+  throw new Error(
+    "no Temporal workflows entry found (checked: " +
+      options.workflowsEntryCandidates
+        .map((url) => fileURLToPath(url))
+        .join(", ") +
+      ") — the build did not emit the workflows module",
+  );
+}

package/src/temporal/workflowexecution/__tests__/activities.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Pins the worker's UpdateWorkflowExecutionStatus activity against Go's
+ * update_status_impl.go — the ACTIVITY merge, deliberately distinct from
+ * the RPC's applyUpdateStatusMerge (sub-project DD-001 brief):
+ *
+ *   - the statusAudit bump is UNCONDITIONAL (the RPC bumps only on phase
+ *     transitions) — the pin that would catch a "consolidate the merges"
+ *     refactor changing wire-visible audit timestamps;
+ *   - no events are written (getEventLog must not grow from orchestrator
+ *     persists);
+ *   - a missing execution is a wrapped ordinary error with Go's
+ *     "workflow execution not found:" text, not a NotFound RPC error;
+ *   - the persist rides the atomic updateResource and broadcasts through
+ *     the domain broker after commit.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { create, toJson } from "@bufbuild/protobuf";
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { timestampMs } from "@bufbuild/protobuf/wkt";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import {
+  WorkflowExecutionSchema,
+  WorkflowExecutionStatusSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { WorkflowExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { StreamBroker } from "../../../domain/workflowexecution/stream-broker.js";
+import { SqliteStore } from "../../../store/sqlite/store.js";
+import type { Store } from "../../../store/interface.js";
+import {
+  applyActivityStatusMerge,
+  createWorkflowExecutionActivities,
+} from "../activities.js";
+import { UPDATE_WORKFLOW_EXECUTION_STATUS_ACTIVITY_NAME } from "../names.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+describe("applyActivityStatusMerge (the activity's own merge, not the RPC's)", () => {
+  function merged(
+    existingStatus: MessageInitShape<typeof WorkflowExecutionStatusSchema>,
+    updates: WorkflowExecutionStatus,
+  ): WorkflowExecution {
+    const execution = create(WorkflowExecutionSchema, {
+      metadata: { id: "wfe-1" },
+      status: existingStatus,
+    });
+    applyActivityStatusMerge(execution, updates);
+    return execution;
+  }
+
+  it("applies a phase-only update and preserves tasks, error, and totals", () => {
+    const result = merged(
+      {
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+        tasks: [{ taskName: "t1" }],
+        error: "prior",
+        totalCostMicros: 5n,
+      },
+      create(WorkflowExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_PAUSED,
+      }),
+    );
+    expect(result.status?.phase).toBe(ExecutionPhase.EXECUTION_PAUSED);
+    expect(result.status?.tasks.map((task) => task.taskName)).toEqual(["t1"]);
+    expect(result.status?.error).toBe("prior");
+    expect(result.status?.totalCostMicros).toBe(5n);
+  });
+
+  it("bumps statusAudit.updatedAt UNCONDITIONALLY — even without a phase transition", () => {
+    // The RPC merge would NOT bump here (same phase re-asserted); the
+    // activity always does (update_status_impl.go's unconditional bump).
+    const before = Date.now() - 1;
+    const result = merged(
+      { phase: ExecutionPhase.EXECUTION_PAUSED },
+      create(WorkflowExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_PAUSED,
+      }),
+    );
+    const updatedAt = result.status?.audit?.statusAudit?.updatedAt;
+    expect(updatedAt).toBeDefined();
+    expect(timestampMs(updatedAt!)).toBeGreaterThanOrEqual(before);
+    expect(result.status?.audit?.statusAudit?.event).toBe("updated");
+  });
+
+  it("replaces tasks only when the update carries a non-empty set", () => {
+    const withEmpty = merged(
+      { tasks: [{ taskName: "keep" }] },
+      create(WorkflowExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_FAILED,
+      }),
+    );
+    expect(withEmpty.status?.tasks.map((task) => task.taskName)).toEqual([
+      "keep",
+    ]);
+
+    const withTasks = merged(
+      { tasks: [{ taskName: "old" }] },
+      create(WorkflowExecutionStatusSchema, {
+        tasks: [{ taskName: "new-1" }, { taskName: "new-2" }],
+      }),
+    );
+    expect(withTasks.status?.tasks.map((task) => task.taskName)).toEqual([
+      "new-1",
+      "new-2",
+    ]);
+  });
+
+  it("treats zero totals as no-update, never reset", () => {
+    const result = merged(
+      { totalCostMicros: 7n, totalInputTokens: 3n, totalOutputTokens: 2n },
+      create(WorkflowExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_FAILED,
+        error: "boom",
+      }),
+    );
+    expect(result.status?.totalCostMicros).toBe(7n);
+    expect(result.status?.totalInputTokens).toBe(3n);
+    expect(result.status?.totalOutputTokens).toBe(2n);
+    expect(result.status?.error).toBe("boom");
+  });
+
+  it("sets timestamps only when provided", () => {
+    const result = merged(
+      { startedAt: "2026-01-01T00:00:00Z" },
+      create(WorkflowExecutionStatusSchema, {
+        completedAt: "2026-01-02T00:00:00Z",
+      }),
+    );
+    expect(result.status?.startedAt).toBe("2026-01-01T00:00:00Z");
+    expect(result.status?.completedAt).toBe("2026-01-02T00:00:00Z");
+  });
+});
+
+describe("UpdateWorkflowExecutionStatus activity (real store)", () => {
+  let dir: string;
+  let store: Store;
+  let broker: StreamBroker;
+
+  beforeAll(() => {
+    dir = mkdtempSync(path.join(tmpdir(), "wfexec-activity-"));
+    store = SqliteStore.open(path.join(dir, "test.db"));
+    broker = new StreamBroker(silentLogger);
+  });
+
+  afterAll(async () => {
+    await store.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function activity() {
+    const activities = createWorkflowExecutionActivities({
+      store,
+      logger: silentLogger,
+      broker,
+      sandboxTerminalObserver: () => {},
+    });
+    return activities[UPDATE_WORKFLOW_EXECUTION_STATUS_ACTIVITY_NAME] as (
+      executionId: string,
+      statusJson: unknown,
+    ) => Promise<void>;
+  }
+
+  it("persists the merge atomically and broadcasts the updated execution", async () => {
+    const id = "wfe-activity-1";
+    await store.saveResource(
+      ApiResourceKind.workflow_execution,
+      id,
+      WorkflowExecutionSchema,
+      create(WorkflowExecutionSchema, {
+        metadata: { id, name: id },
+        status: { phase: ExecutionPhase.EXECUTION_IN_PROGRESS },
+      }),
+    );
+
+    const subscription = broker.subscribe(id);
+    try {
+      await activity()(
+        id,
+        toJson(
+          WorkflowExecutionStatusSchema,
+          create(WorkflowExecutionStatusSchema, {
+            phase: ExecutionPhase.EXECUTION_CANCELLED,
+          }),
+        ),
+      );
+
+      const stored = await store.getResource(
+        ApiResourceKind.workflow_execution,
+        id,
+        WorkflowExecutionSchema,
+      );
+      expect(stored.status?.phase).toBe(ExecutionPhase.EXECUTION_CANCELLED);
+      // CANCELLED carries NO error (stigmer#282's quiet-terminal contract).
+      expect(stored.status?.error).toBe("");
+      // The unconditional audit bump reached the stored state.
+      expect(stored.status?.audit?.statusAudit?.updatedAt).toBeDefined();
+
+      // The broadcast landed on the registered subscriber AFTER the
+      // persist committed (ADR 011 write path).
+      const frames: WorkflowExecution[] = subscription.queue;
+      expect(frames).toHaveLength(1);
+      expect(frames[0]!.status?.phase).toBe(
+        ExecutionPhase.EXECUTION_CANCELLED,
+      );
+    } finally {
+      broker.unsubscribe(id, subscription);
+    }
+  });
+
+  it("writes NO workflow_execution_events (the activity never touches the event log)", async () => {
+    const id = "wfe-activity-2";
+    await store.saveResource(
+      ApiResourceKind.workflow_execution,
+      id,
+      WorkflowExecutionSchema,
+      create(WorkflowExecutionSchema, {
+        metadata: { id, name: id },
+        status: { phase: ExecutionPhase.EXECUTION_IN_PROGRESS },
+      }),
+    );
+
+    await activity()(
+      id,
+      toJson(
+        WorkflowExecutionStatusSchema,
+        create(WorkflowExecutionStatusSchema, {
+          phase: ExecutionPhase.EXECUTION_FAILED,
+          error: "Workflow execution failed: child boom",
+        }),
+      ),
+    );
+
+    const events = await store.getWorkflowExecutionEvents(id, 0, "", "", 10);
+    expect(events).toHaveLength(0);
+  });
+
+  it("wraps a missing execution with Go's 'workflow execution not found:' text", async () => {
+    await expect(
+      activity()(
+        "wfe-missing",
+        toJson(
+          WorkflowExecutionStatusSchema,
+          create(WorkflowExecutionStatusSchema, {
+            phase: ExecutionPhase.EXECUTION_FAILED,
+          }),
+        ),
+      ),
+    ).rejects.toThrowError(/^workflow execution not found: /);
+  });
+});

package/src/temporal/workflowexecution/__tests__/dispatch.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Pins resolveWorkflowTaskQueue against Go's dispatch_test.go: the two
+ * routing modes, the wfexec:{id} format, and the UNSPECIFIED-target
+ * resolution through the config's single rule.
+ */
+import { describe, expect, it } from "vitest";
+
+import { ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import {
+  WORKFLOW_DEFAULT_EXECUTION_TARGET_CLOUD,
+  WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL,
+  WORKFLOW_ROUTING_EXECUTION,
+  WORKFLOW_ROUTING_GLOBAL,
+  WorkflowExecutionTemporalConfig,
+} from "../../../domain/workflowexecution/temporal/config.js";
+import { resolveWorkflowTaskQueue } from "../dispatch.js";
+import { formatWfExecTaskQueue } from "../names.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+function config(
+  routing: string,
+  defaultTarget = WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL,
+): WorkflowExecutionTemporalConfig {
+  return new WorkflowExecutionTemporalConfig(
+    "workflow_execution_stigmer",
+    "stigmer_runner",
+    routing,
+    defaultTarget,
+  );
+}
+
+describe("resolveWorkflowTaskQueue", () => {
+  it("routes to the global runner queue in global mode", () => {
+    const result = resolveWorkflowTaskQueue(
+      "wfe-1",
+      ExecutionTarget.LOCAL,
+      config(WORKFLOW_ROUTING_GLOBAL),
+      silentLogger,
+    );
+    expect(result.taskQueue).toBe("stigmer_runner");
+    expect(result.executionTarget).toBe(ExecutionTarget.LOCAL);
+  });
+
+  it("derives wfexec:{id} in execution mode regardless of target", () => {
+    for (const target of [
+      ExecutionTarget.LOCAL,
+      ExecutionTarget.CLOUD,
+      ExecutionTarget.UNSPECIFIED,
+    ]) {
+      const result = resolveWorkflowTaskQueue(
+        "wfe-42",
+        target,
+        config(WORKFLOW_ROUTING_EXECUTION),
+        silentLogger,
+      );
+      expect(result.taskQueue).toBe("wfexec:wfe-42");
+    }
+  });
+
+  it("resolves UNSPECIFIED to the configured default target", () => {
+    const local = resolveWorkflowTaskQueue(
+      "wfe-1",
+      ExecutionTarget.UNSPECIFIED,
+      config(WORKFLOW_ROUTING_GLOBAL, WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL),
+      silentLogger,
+    );
+    expect(local.executionTarget).toBe(ExecutionTarget.LOCAL);
+
+    const cloud = resolveWorkflowTaskQueue(
+      "wfe-1",
+      ExecutionTarget.UNSPECIFIED,
+      config(WORKFLOW_ROUTING_GLOBAL, WORKFLOW_DEFAULT_EXECUTION_TARGET_CLOUD),
+      silentLogger,
+    );
+    expect(cloud.executionTarget).toBe(ExecutionTarget.CLOUD);
+  });
+
+  it("passes explicit targets through unchanged", () => {
+    const result = resolveWorkflowTaskQueue(
+      "wfe-1",
+      ExecutionTarget.CLOUD,
+      config(WORKFLOW_ROUTING_GLOBAL, WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL),
+      silentLogger,
+    );
+    expect(result.executionTarget).toBe(ExecutionTarget.CLOUD);
+  });
+
+  it("formatWfExecTaskQueue matches Go's format", () => {
+    expect(formatWfExecTaskQueue("abc")).toBe("wfexec:abc");
+  });
+});

package/src/temporal/workflowexecution/__tests__/engine-client.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Pins the ConnectedWorkflowExecutionEngine implementation against
+ * workflow_creator.go and the lifecycle steps' temporalClient contract:
+ * the workflow name/ID, the runnerTaskQueue memo, the slim input's
+ * omitempty JSON shape, the SignalWithStart lane, the one-null-argument
+ * raw-signal convention, the WorkflowNotFoundError → seam-sentinel
+ * mapping, and the provider's memoization/disconnected semantics.
+ *
+ * The Temporal Client is a recording double — the real dial path is
+ * proven by local-execution.
+ */
+import { describe, expect, it } from "vitest";
+
+import type { Client } from "@temporalio/client";
+import { WorkflowNotFoundError } from "@temporalio/common";
+
+import { ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import {
+  ENGINE_DISCONNECTED,
+  EngineWorkflowNotFoundError,
+  type StartWorkflowExecutionInput,
+} from "../../../domain/workflowexecution/engine.js";
+import {
+  WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL,
+  WORKFLOW_ROUTING_GLOBAL,
+  WorkflowExecutionTemporalConfig,
+} from "../../../domain/workflowexecution/temporal/config.js";
+import type { TemporalManager } from "../../manager.js";
+import {
+  newWorkflowExecutionEngineStateProvider,
+  TemporalWorkflowExecutionEngine,
+} from "../engine-client.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const config = new WorkflowExecutionTemporalConfig(
+  "workflow_execution_stigmer",
+  "stigmer_runner",
+  WORKFLOW_ROUTING_GLOBAL,
+  WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL,
+);
+
+interface RecordedStart {
+  readonly workflowType: string;
+  readonly options: Record<string, unknown>;
+}
+
+interface RecordedHandleCall {
+  readonly workflowId: string;
+  readonly method: string;
+  readonly args: unknown[];
+}
+
+function newClientDouble(handleError?: Error) {
+  const starts: RecordedStart[] = [];
+  const signalWithStarts: RecordedStart[] = [];
+  const handleCalls: RecordedHandleCall[] = [];
+
+  const client = {
+    workflow: {
+      start: async (workflowType: string, options: Record<string, unknown>) => {
+        starts.push({ workflowType, options });
+      },
+      signalWithStart: async (
+        workflowType: string,
+        options: Record<string, unknown>,
+      ) => {
+        signalWithStarts.push({ workflowType, options });
+      },
+      getHandle: (workflowId: string) => ({
+        signal: async (...args: unknown[]) => {
+          if (handleError) throw handleError;
+          handleCalls.push({ workflowId, method: "signal", args });
+        },
+        cancel: async () => {
+          if (handleError) throw handleError;
+          handleCalls.push({ workflowId, method: "cancel", args: [] });
+        },
+        terminate: async (reason: string) => {
+          if (handleError) throw handleError;
+          handleCalls.push({ workflowId, method: "terminate", args: [reason] });
+        },
+      }),
+    },
+  } as unknown as Client;
+
+  return { client, starts, signalWithStarts, handleCalls };
+}
+
+function startInput(
+  overrides: Partial<StartWorkflowExecutionInput> = {},
+): StartWorkflowExecutionInput {
+  return {
+    executionId: "wfe-1",
+    workflowInstanceId: "wfi-1",
+    workflowId: "wf-1",
+    orgId: "org-1",
+    recoveryMode: false,
+    executionTarget: ExecutionTarget.LOCAL,
+    ...overrides,
+  };
+}
+
+describe("TemporalWorkflowExecutionEngine", () => {
+  it("starts the orchestrator with the pinned ID, queue, memo, and omitempty input", async () => {
+    const double = newClientDouble();
+    const engine = new TemporalWorkflowExecutionEngine({
+      client: double.client,
+      config,
+      logger: silentLogger,
+    });
+
+    await engine.startInvokeWorkflow(startInput());
+
+    expect(double.starts).toHaveLength(1);
+    const start = double.starts[0]!;
+    expect(start.workflowType).toBe("stigmer/workflow-execution/invoke");
+    expect(start.options["workflowId"]).toBe(
+      "stigmer/workflow-execution/invoke/wfe-1",
+    );
+    expect(start.options["taskQueue"]).toBe("workflow_execution_stigmer");
+    expect(start.options["memo"]).toEqual({ runnerTaskQueue: "stigmer_runner" });
+    // Go's omitempty shape: recovery_mode false is OMITTED, not false.
+    expect(start.options["args"]).toEqual([
+      {
+        execution_id: "wfe-1",
+        workflow_instance_id: "wfi-1",
+        workflow_id: "wf-1",
+        org_id: "org-1",
+      },
+    ]);
+    // No workflowRunTimeout — durable execution (module header).
+    expect(start.options["workflowRunTimeout"]).toBeUndefined();
+  });
+
+  it("omits every zero-valued optional field and carries recovery_mode when set", async () => {
+    const double = newClientDouble();
+    const engine = new TemporalWorkflowExecutionEngine({
+      client: double.client,
+      config,
+      logger: silentLogger,
+    });
+
+    await engine.startInvokeWorkflow(
+      startInput({
+        workflowInstanceId: "",
+        workflowId: "",
+        orgId: "",
+        recoveryMode: true,
+      }),
+    );
+
+    expect(double.starts[0]!.options["args"]).toEqual([
+      { execution_id: "wfe-1", recovery_mode: true },
+    ]);
+  });
+
+  it("signalWithStart carries the signal, its payload, and the same start options", async () => {
+    const double = newClientDouble();
+    const engine = new TemporalWorkflowExecutionEngine({
+      client: double.client,
+      config,
+      logger: silentLogger,
+    });
+
+    await engine.signalWithStart(startInput(), "relaySignal", {
+      signalName: "human_input_step1",
+      payload: { answer: 42 },
+    });
+
+    expect(double.signalWithStarts).toHaveLength(1);
+    const call = double.signalWithStarts[0]!;
+    expect(call.workflowType).toBe("stigmer/workflow-execution/invoke");
+    expect(call.options["workflowId"]).toBe(
+      "stigmer/workflow-execution/invoke/wfe-1",
+    );
+    expect(call.options["signal"]).toBe("relaySignal");
+    expect(call.options["signalArgs"]).toEqual([
+      { signalName: "human_input_step1", payload: { answer: 42 } },
+    ]);
+    expect(call.options["memo"]).toEqual({ runnerTaskQueue: "stigmer_runner" });
+  });
+
+  it("raw signal sends exactly one argument, null when the payload is absent", async () => {
+    const double = newClientDouble();
+    const engine = new TemporalWorkflowExecutionEngine({
+      client: double.client,
+      config,
+      logger: silentLogger,
+    });
+
+    await engine.signalWorkflow("wf-id-1", "pause", "user requested");
+    await engine.signalWorkflow("wf-id-1", "resume", undefined);
+
+    expect(double.handleCalls).toEqual([
+      { workflowId: "wf-id-1", method: "signal", args: ["pause", "user requested"] },
+      // Go SignalWorkflow(nil) — one nil argument, not zero arguments.
+      { workflowId: "wf-id-1", method: "signal", args: ["resume", null] },
+    ]);
+  });
+
+  it("maps WorkflowNotFoundError onto the seam's sentinel for signal/cancel/terminate", async () => {
+    const notFound = new WorkflowNotFoundError("gone", "wf-id-x", undefined);
+    const double = newClientDouble(notFound);
+    const engine = new TemporalWorkflowExecutionEngine({
+      client: double.client,
+      config,
+      logger: silentLogger,
+    });
+
+    await expect(
+      engine.signalWorkflow("wf-id-x", "pause", "r"),
+    ).rejects.toBeInstanceOf(EngineWorkflowNotFoundError);
+    await expect(engine.cancelWorkflow("wf-id-x")).rejects.toBeInstanceOf(
+      EngineWorkflowNotFoundError,
+    );
+    await expect(
+      engine.terminateWorkflow("wf-id-x", "reason"),
+    ).rejects.toBeInstanceOf(EngineWorkflowNotFoundError);
+  });
+
+  it("passes non-not-found errors through unchanged", async () => {
+    const boom = new Error("connection refused");
+    const double = newClientDouble(boom);
+    const engine = new TemporalWorkflowExecutionEngine({
+      client: double.client,
+      config,
+      logger: silentLogger,
+    });
+
+    await expect(engine.cancelWorkflow("wf-id-x")).rejects.toBe(boom);
+  });
+});
+
+describe("newWorkflowExecutionEngineStateProvider", () => {
+  it("is disconnected until the first client and memoizes per client instance", () => {
+    let client: Client | undefined;
+    const manager = {
+      getClient: () => client,
+    } as unknown as TemporalManager;
+
+    const provider = newWorkflowExecutionEngineStateProvider({
+      manager,
+      config,
+      logger: silentLogger,
+    });
+
+    expect(provider()).toBe(ENGINE_DISCONNECTED);
+
+    client = newClientDouble().client;
+    const first = provider();
+    expect(first.connected).toBe(true);
+    // Same client → the SAME memoized state object.
+    expect(provider()).toBe(first);
+
+    // A reconnect swaps the client → a fresh engine wrapping it.
+    client = newClientDouble().client;
+    const second = provider();
+    expect(second.connected).toBe(true);
+    expect(second).not.toBe(first);
+  });
+});