@stigmer/server 3.14.0-dev.20260910084630

package/src/temporal/README.md

@@ -0,0 +1,17 @@
+# temporal/ — the Temporal engine
+
+The shared worker infrastructure and the per-domain workers. Landed with D4 #18 (agent-execution); workflow-execution (#21) and the schedule clock (#22) append their workers to the same manager.
+
+## Layout
+
+- `manager.ts` — TemporalManager (ports pkg/server/temporal_manager.go): non-fatal initial connect, 15s health monitor, reconnect with worker recreation, reconnect hooks. Domain code observes the CURRENT client through providers — there is no Go-style creator re-injection.
+- `payload-codec.ts` — the decode-only payload codec (ports pkg/encryption/payloadcodec): encode is the identity, decode delegates to @stigmer/temporal-codecs.
+- `workflow-source.ts` — prebuilt-bundle vs bundle-on-boot resolution (runner precedent); prebuilt bundles arrive with #24.
+- `runner-failure.ts` — worker-shutdown classification shared by the execution workflows (ports pkg/runnerfailure, #776).
+- `agentexecution/` — the agent-execution worker: byte-pinned names, dispatch resolution, the ConnectedExecutionEngine implementation, server-side activities, and `workflows/` (the deterministic sandbox bundle).
+
+## Workflow-bundle import discipline
+
+Everything reachable from a `workflows/` entry runs in Temporal's deterministic sandbox: only @temporalio/workflow, @temporalio/common, @bufbuild/protobuf, generated protos, and verified-pure domain modules (imported by DIRECT path, never via barrels — e.g. `filereview/gate.js`, whose sibling `digest.ts` pulls node:crypto). The SDK bundler hard-fails on node built-ins; keep it that way.
+
+Queue names, workflow names, signal names, and memo keys are byte-pinned wire constants (D2 §4) — see `agentexecution/names.ts`.

package/src/temporal/__tests__/manager.test.ts

@@ -0,0 +1,325 @@
+/**
+ * TemporalManager lifecycle tests — pins the two panel findings, the
+ * availability posture, and the worker-construction capability:
+ *
+ *   - close() racing an in-flight reconnect must NOT resurrect the
+ *     manager (fresh dial discarded; no workers recreated; no hooks
+ *     fired after shutdown) — Go is immune via context cancellation,
+ *     this port re-checks `closed` across every await;
+ *   - a worker factory throwing mid-loop must leave the already-started
+ *     workers TRACKED so close() can stop them (an untracked poller
+ *     lives forever — latent until #21/#22 add factories);
+ *   - the Go availability parity: getClient() is undefined only until
+ *     the first successful connect;
+ *   - deps.createWorker builds through THIS package's Worker.create with
+ *     the manager's connection, namespace, and codec chain pre-wired
+ *     (the finding-16 seam — factories never see the NativeConnection);
+ *   - a worker's run() rejection logs at ERROR with its queue identity
+ *     (a permanent death re-dies on every recreate while the worker
+ *     reports RUNNING — the log line is the only signal).
+ *
+ * The manager's private dial and the SDK's NativeConnection/Worker.create
+ * are stubbed (module mock + private-seam override): the real connect
+ * path is proven end-to-end by local-execution; these tests pin the
+ * manager's OWN state machine and wiring, which only misbehave in windows
+ * no live harness can schedule deterministically.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createLogger } from "../../boot/logger.js";
+import { TemporalManager, type WorkerFactory } from "../manager.js";
+
+const sdkSpy = vi.hoisted(() => ({
+  /** Options of every Worker.create call, in order. */
+  createCalls: [] as Record<string, unknown>[],
+  /** The connection object the mocked NativeConnection.connect returned last. */
+  lastConnection: undefined as unknown,
+}));
+
+vi.mock("@temporalio/worker", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@temporalio/worker")>();
+  return {
+    ...original,
+    NativeConnection: {
+      connect: async () => {
+        const connection = { close: async () => {} };
+        sdkSpy.lastConnection = connection;
+        return connection;
+      },
+    },
+    Worker: {
+      create: async (options: Record<string, unknown>) => {
+        sdkSpy.createCalls.push(options);
+        let release: (() => void) | undefined;
+        const done = new Promise<void>((resolve) => {
+          release = resolve;
+        });
+        return {
+          options: { taskQueue: options["taskQueue"] },
+          run: () => done,
+          shutdown: () => release?.(),
+        };
+      },
+    },
+  };
+});
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const managers: TemporalManager[] = [];
+afterEach(async () => {
+  sdkSpy.createCalls.length = 0;
+  sdkSpy.lastConnection = undefined;
+  for (const manager of managers.splice(0)) {
+    await manager.close();
+  }
+});
+
+interface FakeWorkerRecord {
+  shutdowns: number;
+}
+
+/** A Worker double: run() resolves when shutdown() is called. */
+function fakeWorkerFactory(record: FakeWorkerRecord): WorkerFactory {
+  return async () => {
+    let release: (() => void) | undefined;
+    const done = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    return {
+      options: { taskQueue: "fake-queue" },
+      run: () => done,
+      shutdown: () => {
+        record.shutdowns++;
+        release?.();
+      },
+    } as unknown as Awaited<ReturnType<WorkerFactory>>;
+  };
+}
+
+function newManager(
+  factories: WorkerFactory[],
+  options?: {
+    logger?: typeof silentLogger;
+    payloadCodecs?: ConstructorParameters<
+      typeof TemporalManager
+    >[0]["payloadCodecs"];
+  },
+): TemporalManager {
+  const manager = new TemporalManager({
+    hostPort: "127.0.0.1:1",
+    namespace: "default",
+    logger: options?.logger ?? silentLogger,
+    payloadCodecs: options?.payloadCodecs ?? [],
+    workerFactories: factories,
+  });
+  managers.push(manager);
+  return manager;
+}
+
+/** Stubs the private dial seam with a controllable connection/client pair. */
+function stubDial(
+  manager: TemporalManager,
+  impl: () => Promise<{ connection: unknown; client: unknown }>,
+): void {
+  (manager as unknown as { dial: typeof impl }).dial = impl;
+}
+
+describe("TemporalManager close/reconnect race", () => {
+  it("discards a dial that completes after close() — no resurrection, no hooks", async () => {
+    const record: FakeWorkerRecord = { shutdowns: 0 };
+    const manager = newManager([fakeWorkerFactory(record)]);
+    let hookFired = false;
+    manager.addReconnectHook(() => {
+      hookFired = true;
+    });
+
+    let releaseDial: (() => void) | undefined;
+    const dialGate = new Promise<void>((resolve) => {
+      releaseDial = resolve;
+    });
+    const freshConnection = { closed: 0, close: async () => {} };
+    freshConnection.close = async () => {
+      freshConnection.closed++;
+    };
+    stubDial(manager, async () => {
+      await dialGate;
+      return { connection: freshConnection, client: {} };
+    });
+
+    // Drive attemptReconnection directly (the monitor path), then close()
+    // while the dial is parked, then release the dial.
+    const reconnectPromise = (
+      manager as unknown as { attemptReconnection: () => Promise<void> }
+    ).attemptReconnection();
+    await manager.close();
+    releaseDial!();
+    await reconnectPromise;
+
+    expect(manager.isConnected(), "a closed manager must stay down").toBe(
+      false,
+    );
+    expect(
+      manager.getClient(),
+      "the fresh client must be discarded",
+    ).toBeUndefined();
+    expect(hookFired, "reconnect hooks must never fire after shutdown").toBe(
+      false,
+    );
+    expect(
+      freshConnection.closed,
+      "the discarded dial's connection is closed",
+    ).toBe(1);
+    expect(record.shutdowns, "no workers may be created after close").toBe(0);
+  });
+});
+
+describe("TemporalManager worker tracking", () => {
+  it("keeps already-started workers stoppable when a later factory throws", async () => {
+    const record: FakeWorkerRecord = { shutdowns: 0 };
+    const manager = newManager([
+      fakeWorkerFactory(record),
+      async () => {
+        throw new Error("factory two exploded");
+      },
+    ]);
+    stubDial(manager, async () => ({
+      connection: { close: async () => {} },
+      client: {},
+    }));
+
+    await manager.initialConnect();
+    // startWorkers logs the factory failure as a warning (Go posture)…
+    await manager.startWorkers();
+    // …but the FIRST worker already started polling; close() must reach it.
+    await manager.close();
+
+    expect(
+      record.shutdowns,
+      "the started worker must be tracked and shut down despite the later factory failure",
+    ).toBe(1);
+  });
+});
+
+describe("TemporalManager availability posture", () => {
+  it("getClient() is undefined until the first successful connect (Go's nil-creator window)", async () => {
+    const manager = newManager([]);
+    expect(manager.getClient()).toBeUndefined();
+
+    const client = { marker: "client-1" };
+    stubDial(manager, async () => ({
+      connection: { close: async () => {} },
+      client,
+    }));
+    await manager.initialConnect();
+
+    expect(manager.getClient()).toBe(client);
+    expect(manager.isConnected()).toBe(true);
+  });
+});
+
+describe("TemporalManager createWorker capability (the finding-16 seam)", () => {
+  it("builds through this package's Worker.create with connection, namespace, and codecs pre-wired", async () => {
+    const fakeCodec = { encode: async () => [], decode: async () => [] };
+    const manager = newManager(
+      [
+        (deps) =>
+          deps.createWorker({
+            taskQueue: "capability-queue",
+            activities: { doThing: async () => {} },
+            workflows: { workflowsPath: "/tmp/workflows.js" },
+          }),
+      ],
+      { payloadCodecs: [fakeCodec] },
+    );
+    stubDial(manager, async () => ({
+      connection: { close: async () => {} },
+      client: {},
+    }));
+
+    await manager.initialConnect();
+    await manager.startWorkers();
+
+    expect(sdkSpy.createCalls).toHaveLength(1);
+    const created = sdkSpy.createCalls[0]!;
+    expect(
+      created["connection"],
+      "the worker must be bound to the manager's own NativeConnection",
+    ).toBe(sdkSpy.lastConnection);
+    expect(created["namespace"]).toBe("default");
+    expect(created["taskQueue"]).toBe("capability-queue");
+    expect(created["workflowsPath"]).toBe("/tmp/workflows.js");
+    expect(
+      created["dataConverter"],
+      "the decode-only codec chain must reach every worker (the choke point)",
+    ).toEqual({ payloadCodecs: [fakeCodec] });
+  });
+
+  it("omits dataConverter when no codecs are configured (the SQLite-local shape)", async () => {
+    const manager = newManager([
+      (deps) =>
+        deps.createWorker({
+          taskQueue: "codecless-queue",
+          activities: {},
+          workflows: { workflowBundle: { code: "bundled" } },
+        }),
+    ]);
+    stubDial(manager, async () => ({
+      connection: { close: async () => {} },
+      client: {},
+    }));
+
+    await manager.initialConnect();
+    await manager.startWorkers();
+
+    expect(sdkSpy.createCalls).toHaveLength(1);
+    const created = sdkSpy.createCalls[0]!;
+    expect("dataConverter" in created).toBe(false);
+    expect(created["workflowBundle"]).toEqual({ code: "bundled" });
+  });
+});
+
+describe("TemporalManager worker-death observability", () => {
+  it("logs a run() rejection at ERROR with the dead worker's queue identity", async () => {
+    const lines: string[] = [];
+    const capturingLogger = createLogger({
+      level: "error",
+      pretty: false,
+      write: (line) => {
+        lines.push(line);
+      },
+    });
+    const manager = newManager(
+      [
+        async () =>
+          ({
+            options: { taskQueue: "doomed-queue" },
+            run: () => Promise.reject(new Error("poller exploded")),
+            shutdown: () => {},
+          }) as unknown as Awaited<ReturnType<WorkerFactory>>,
+      ],
+      { logger: capturingLogger },
+    );
+    stubDial(manager, async () => ({
+      connection: { close: async () => {} },
+      client: {},
+    }));
+
+    await manager.initialConnect();
+    await manager.startWorkers();
+    // The rejection is handled asynchronously; drain the microtask queue.
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const death = lines.find((line) =>
+      line.includes("Temporal worker stopped with error"),
+    );
+    expect(death, "the death must be logged").toBeDefined();
+    expect(death).toContain('"level":"error"');
+    expect(death).toContain('"task_queue":"doomed-queue"');
+    expect(death).toContain("poller exploded");
+  });
+});

package/src/temporal/__tests__/payload-codec.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Pins the decode-only codec contract (Go DecryptionCodec parity;
+ * stigmer#398): encode is the IDENTITY even when encryption is configured
+ * (server histories stay plaintext), decode delegates to the shared codec
+ * (runner-encrypted payloads decrypt; unencrypted payloads pass through;
+ * tampering fails closed), and the loader is enabled-iff-configured with
+ * boot-fatal misconfiguration.
+ */
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { EncryptionPayloadCodec } from "@stigmer/temporal-codecs";
+import type { Payload } from "@temporalio/common";
+
+import {
+  loadServerPayloadCodecs,
+  ServerDecryptionPayloadCodec,
+} from "../payload-codec.js";
+
+const KEY = randomBytes(32);
+const KEY_ID = "test-key-1";
+
+function textPayload(text: string): Payload {
+  return {
+    metadata: { encoding: Buffer.from("json/plain") },
+    data: Buffer.from(JSON.stringify(text)),
+  };
+}
+
+function newCodecPair(): {
+  runnerSide: EncryptionPayloadCodec;
+  serverSide: ServerDecryptionPayloadCodec;
+} {
+  const config = { primary: { keyId: KEY_ID, key: KEY } };
+  return {
+    runnerSide: new EncryptionPayloadCodec(config),
+    serverSide: new ServerDecryptionPayloadCodec(
+      new EncryptionPayloadCodec(config),
+    ),
+  };
+}
+
+describe("ServerDecryptionPayloadCodec", () => {
+  it("passes payloads through encode untouched even with a key configured", async () => {
+    const { serverSide } = newCodecPair();
+    const payload = textPayload("server-authored payload");
+
+    const encoded = await serverSide.encode([payload]);
+
+    expect(encoded).toHaveLength(1);
+    // Same object, not an equal copy — identity is the contract.
+    expect(encoded[0]).toBe(payload);
+  });
+
+  it("decrypts payloads the runner-side codec encrypted", async () => {
+    const { runnerSide, serverSide } = newCodecPair();
+    const original = textPayload("runner activity result");
+    const [encrypted] = await runnerSide.encode([original]);
+    expect(Buffer.from(encrypted!.metadata!["encoding"]!).toString()).toBe(
+      "binary/encrypted",
+    );
+
+    const [decoded] = await serverSide.decode([encrypted!]);
+
+    expect(Buffer.from(decoded!.data!).toString()).toBe(
+      JSON.stringify("runner activity result"),
+    );
+  });
+
+  it("passes through payloads nobody encrypted", async () => {
+    const { serverSide } = newCodecPair();
+    const payload = textPayload("plaintext history entry");
+
+    const [decoded] = await serverSide.decode([payload]);
+
+    expect(decoded).toBe(payload);
+  });
+
+  it("fails closed on tampered ciphertext", async () => {
+    const { runnerSide, serverSide } = newCodecPair();
+    const [encrypted] = await runnerSide.encode([textPayload("secret")]);
+    const tampered: Payload = {
+      metadata: encrypted!.metadata,
+      data: Buffer.from(
+        encrypted!.data!.map((b, i) => (i === 20 ? b ^ 0xff : b)),
+      ),
+    };
+
+    await expect(serverSide.decode([tampered])).rejects.toThrow();
+  });
+});
+
+describe("loadServerPayloadCodecs", () => {
+  // The loader deliberately reads process.env (see the module header), so
+  // these tests set and restore the real environment.
+  const ENV_KEYS = [
+    "STIGMER_PAYLOAD_ENCRYPTION_KEY",
+    "STIGMER_PAYLOAD_ENCRYPTION_KEY_ID",
+  ] as const;
+
+  afterEach(() => {
+    for (const key of ENV_KEYS) {
+      delete process.env[key];
+    }
+  });
+
+  it("returns no codecs when encryption is not configured", () => {
+    expect(loadServerPayloadCodecs()).toEqual([]);
+  });
+
+  it("returns the decode-only codec when a key pair is configured", () => {
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY"] = KEY.toString("base64");
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY_ID"] = KEY_ID;
+
+    const codecs = loadServerPayloadCodecs();
+
+    expect(codecs).toHaveLength(1);
+    expect(codecs[0]).toBeInstanceOf(ServerDecryptionPayloadCodec);
+  });
+
+  it("boot-fails on a key without its id (never a silent plaintext downgrade)", () => {
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY"] = KEY.toString("base64");
+
+    expect(() => loadServerPayloadCodecs()).toThrow(/KEY_ID/);
+  });
+
+  it("boot-fails on a malformed key", () => {
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY"] =
+      Buffer.from("short").toString("base64");
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY_ID"] = KEY_ID;
+
+    expect(() => loadServerPayloadCodecs()).toThrow(/32 bytes/);
+  });
+
+  // The resolvePayloadKey threading (C4 Stage 2): the composed provider's
+  // capability rides the decode codec as its resolveKey fallback —
+  // consulted for key ids outside the env pair, never installed without
+  // the env-keyed codec (the named coupling in the module header).
+  it("threads the resolver into the decode codec for rpk_ key ids", async () => {
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY"] = KEY.toString("base64");
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY_ID"] = KEY_ID;
+
+    const runnerKey = { keyId: "rpk_identity1", key: randomBytes(32) };
+    const desktopRunner = new EncryptionPayloadCodec({ primary: runnerKey });
+    const [encrypted] = await desktopRunner.encode([
+      textPayload("desktop runner activity result"),
+    ]);
+
+    const [codec] = loadServerPayloadCodecs(async (keyId) =>
+      keyId === runnerKey.keyId ? runnerKey.key : undefined,
+    );
+    const [decoded] = await codec!.decode([encrypted!]);
+
+    expect(Buffer.from(decoded!.data!).toString()).toBe(
+      JSON.stringify("desktop runner activity result"),
+    );
+  });
+
+  it("keeps the fail-closed throw when the resolver does not know the id", async () => {
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY"] = KEY.toString("base64");
+    process.env["STIGMER_PAYLOAD_ENCRYPTION_KEY_ID"] = KEY_ID;
+
+    const desktopRunner = new EncryptionPayloadCodec({
+      primary: { keyId: "rpk_unknown", key: randomBytes(32) },
+    });
+    const [encrypted] = await desktopRunner.encode([textPayload("secret")]);
+
+    const [codec] = loadServerPayloadCodecs(async () => undefined);
+    await expect(codec!.decode([encrypted!])).rejects.toThrow(
+      /unknown key id 'rpk_unknown'/,
+    );
+  });
+
+  it("returns no codecs even with a resolver when encryption is not configured", () => {
+    expect(loadServerPayloadCodecs(async () => undefined)).toEqual([]);
+  });
+});

package/src/temporal/__tests__/runner-failure.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Pins the worker-shutdown classification (pkg/runnerfailure parity,
+ * issue #776): the two message shapes that mean "infrastructure
+ * interrupted the turn", matched exactly as the Go and Java control
+ * planes match them, and the honest status.error copy every edition
+ * shares. The invoke workflow's recovery loop and failure-path persist
+ * both key on this classifier.
+ */
+import { ApplicationFailure, CancelledFailure } from "@temporalio/common";
+import { describe, expect, it } from "vitest";
+
+import {
+  isWorkerShutdown,
+  WORKER_SHUTDOWN_STATUS_ERROR,
+} from "../runner-failure.js";
+
+describe("isWorkerShutdown", () => {
+  it("matches the runner's own shutdown classification in a cancelled failure", () => {
+    expect(
+      isWorkerShutdown(
+        new CancelledFailure("Activity cancelled (worker shutdown, not user pause)"),
+      ),
+    ).toBe(true);
+  });
+
+  it("matches loose markers only inside CANCELLED failures (runner-authored text)", () => {
+    expect(isWorkerShutdown(new CancelledFailure("shutting down"))).toBe(true);
+    // The same loose text in a NON-cancelled failure could be agent/tool
+    // output — it must NOT classify.
+    expect(isWorkerShutdown(new Error("shutting down"))).toBe(false);
+  });
+
+  it("matches the Temporal TS worker's drain text in application failures", () => {
+    expect(
+      isWorkerShutdown(
+        ApplicationFailure.create({
+          message:
+            "Worker is shutting down and this activity did not complete in time",
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("matches the drain text anywhere in the cause chain", () => {
+    const wrapped = new Error("activity 'ExecuteDeepAgent' failed", {
+      cause: ApplicationFailure.create({
+        message: "Worker is shutting down and this activity did not complete in time",
+      }),
+    });
+    expect(isWorkerShutdown(wrapped)).toBe(true);
+  });
+
+  it("does not classify ordinary failures", () => {
+    expect(isWorkerShutdown(new Error("agent blew up"))).toBe(false);
+    expect(
+      isWorkerShutdown(ApplicationFailure.create({ message: "boom" })),
+    ).toBe(false);
+    expect(isWorkerShutdown(undefined)).toBe(false);
+  });
+
+  it("pins the honest cross-edition status.error copy", () => {
+    expect(WORKER_SHUTDOWN_STATUS_ERROR).toBe(
+      "Execution interrupted: runner worker was shut down. Retry or resume.",
+    );
+  });
+});