feat(client)!: split TypedClient/ContractClient and overhaul the client surface

Wave 3 of the v8 review remediation (items 11-18):

- 11: TypedClient is now connection-scoped (no type parameter):
  static create({ client, interceptors }) holds the schedule-presence
  check + eager ensureConnected; for(contract) hands out memoized,
  identity-stable ContractClient<TContract> bindings (the renamed old
  class, constructor @internal). createOrThrow and the create options'
  contract field are removed; ContractClient is exported.
- 12: handle.result() output-validation errors now carry the real
  workflow NAME (the workflowId was passed as workflowName);
  WorkflowValidationError gains a workflowId field, populated on
  start/execute/signalWithStart/result paths.
- 13: schedule parity — tagged ScheduleAlreadyExistsError /
  ScheduleNotFoundError classified from Temporal's ScheduleAlreadyRunning /
  ScheduleNotFoundError; create returns Err(ScheduleAlreadyExistsError);
  handle methods return AsyncResult<void, ScheduleNotFoundError>;
  new update + backfill on the typed handle and list on the typed
  schedule client; TypedScheduleClient constructor is @internal.
- 14: readonly raw escape hatch on the TypedClient root; typed workflow
  handles carry runId + firstExecutionRunId (signaledRunId stays on
  signalWithStart's); getHandle is now SYNCHRONOUS returning
  Result<handle, WorkflowNotInContractError> and accepts runId +
  GetWorkflowHandleOptions (firstExecutionRunId interlock); typed
  startUpdate beside executeUpdate with a parsed-on-receive result().
- 15: WorkflowNotFoundError renamed WorkflowNotInContractError (it
  squatted on the SDK's execution-not-found name);
  WorkflowExecutionNotFoundError unchanged.
- 16: deleted the six unused ClientInfer* type exports; fixed the
  inverted direction comment in types.ts; {} fallbacks are now
  Record<never, never>.
- 17: executeWorkflow composes classifyStartError + the new shared
  classifyExecutionResultError (rehydrate-then-classify) helper, also
  used by handle.result().
- 18: TSDoc/doc polish (orphaned TypedSearchAttributeMap doc, "Thrown
  when" -> "Surfaced on the Err channel when", module docs above
  imports, readonly handle/error fields, typeof-per-kind runtime checks
  for search-attribute VALUES, fixed interceptors.ts combinator names,
  README rewritten to the TypedClient.create({ client }).for(contract)
  two-step with .get()); payload arguments are omittable when the
  schema accepts undefined (input-less signals/queries/updates send
  empty args); expanded type-level and unit/integration suites incl.
  second-contract fixtures proving one root drives two task queues.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: btravers

packages/client/README.md

@@ -16,15 +16,21 @@ pnpm add @temporal-contract/client @temporal-contract/contract @temporalio/clien
 import { TypedClient } from "@temporal-contract/client";
 import { Connection, Client } from "@temporalio/client";
 
+import { myContract } from "./contract.js";
+
 const connection = await Connection.connect({ address: "localhost:7233" });
 const temporalClient = new Client({ connection });
-const client = await TypedClient.create({
-  contract: myContract,
-  client: temporalClient,
-}).getOrThrow();
+
+// One connection-scoped root per process. `create` returns
+// `AsyncResult<TypedClient, never>` — setup faults are defects, so `.get()`
+// unwraps directly.
+const client = await TypedClient.create({ client: temporalClient }).get();
+
+// Bind a contract — synchronous, infallible, memoized.
+const orders = client.for(myContract);
 
 // Execute workflow (fully typed!)
-const result = await client.executeWorkflow("processOrder", {
+const result = await orders.executeWorkflow("processOrder", {
   workflowId: "order-123",
   args: { orderId: "ORD-123" },
 });

packages/client/src/__tests__/client.spec.ts

@@ -7,18 +7,23 @@ import { Worker } from "@temporalio/worker";
 import { P } from "unthrown";
 import { describe, expect, vi, beforeEach } from "vitest";
 
-import { TypedClient } from "../client.js";
+import { type ContractClient, TypedClient } from "../client.js";
 import { WorkflowValidationError } from "../errors.js";
+import { secondContract } from "./second.contract.js";
 import { testContract } from "./test.contract.js";
 
 // ============================================================================
 // Test Setup
 // ============================================================================
 
-const it = baseIt.extend<{
+type WorkerFixtures = {
   worker: Worker;
-  client: TypedClient<typeof testContract>;
-}>({
+  secondWorker: Worker;
+  root: TypedClient;
+  client: ContractClient<typeof testContract>;
+};
+
+const it = baseIt.extend<WorkerFixtures>({
   worker: [
     async ({ workerConnection }, use) => {
       // Create and start worker
@@ -57,19 +62,44 @@ const it = baseIt.extend<{
     },
     { auto: true },
   ],
-  client: async ({ clientConnection }, use) => {
-    // Create typed client
+  // Second worker on the second contract's task queue — proves one
+  // connection-scoped root drives multiple contracts (see the
+  // "multiple contracts, one root" suite).
+  secondWorker: [
+    async ({ workerConnection }, use) => {
+      const worker = await Worker.create({
+        connection: workerConnection,
+        namespace: "default",
+        taskQueue: secondContract.taskQueue,
+        workflowsPath: workflowPath("second.workflows"),
+      });
+
+      worker.run().catch((err) => {
+        console.error("Second worker failed:", err);
+      });
+
+      await vi.waitFor(() => worker.getState() === "RUNNING", { interval: 100 });
+
+      await use(worker);
+
+      await worker.shutdown();
+
+      await vi.waitFor(() => worker.getState() === "STOPPED", { interval: 100 });
+    },
+    { auto: true },
+  ],
+  root: async ({ clientConnection }, use) => {
+    // One connection-scoped root per process; contracts bind via `for()`.
     const rawClient = new Client({
       connection: clientConnection,
       namespace: "default",
     });
-    const clientResult = await TypedClient.create({ contract: testContract, client: rawClient });
-    if (!clientResult.isOk()) {
-      throw clientResult.isErr() ? clientResult.error : clientResult.cause;
-    }
-    const client = clientResult.value;
+    const root = (await TypedClient.create({ client: rawClient })).get();
 
-    await use(client);
+    await use(root);
+  },
+  client: async ({ root }, use) => {
+    await use(root.for(testContract));
   },
 });
 
@@ -142,8 +172,9 @@ describe("Client Package - Integration Tests", () => {
         args: input,
       });
 
-      // WHEN
-      const handleResult = await client.getHandle("simpleWorkflow", workflowId);
+      // WHEN — getHandle is synchronous: the only failure mode is a
+      // workflow name missing from the contract.
+      const handleResult = client.getHandle("simpleWorkflow", workflowId);
 
       // THEN
       expect(handleResult).toBeOk();
@@ -158,6 +189,56 @@ describe("Client Package - Integration Tests", () => {
     });
   });
 
+  describe("Multiple contracts, one root", () => {
+    it("routes each contract's workflows to its own task queue through one root", async ({
+      root,
+      client,
+    }) => {
+      // GIVEN — the shared root, testContract already bound as `client`.
+      const second = root.for(secondContract);
+
+      // WHEN — drive both contracts through the same connection.
+      const first = await client.executeWorkflow("simpleWorkflow", {
+        workflowId: `multi-first-${Date.now()}`,
+        args: { value: "from-first" },
+      });
+      const echoed = await second.executeWorkflow("echoWorkflow", {
+        workflowId: `multi-second-${Date.now()}`,
+        args: { text: "from-second" },
+      });
+
+      // THEN — each contract's worker (polling its own queue) answered.
+      expect(first).toBeOk();
+      if (first.isOk()) {
+        expect(first.value).toEqual({ result: "Processed: from-first" });
+      }
+      expect(echoed).toBeOk();
+      if (echoed.isOk()) {
+        expect(echoed.value).toEqual({ echoed: "second-queue: from-second" });
+      }
+
+      // Binding is memoized — the same instance serves repeated `for()`.
+      expect(root.for(secondContract)).toBe(second);
+    });
+  });
+
+  describe("Handle identifiers", () => {
+    it("startWorkflow handles carry firstExecutionRunId and runId", async ({ client }) => {
+      const handleResult = await client.startWorkflow("simpleWorkflow", {
+        workflowId: `run-ids-${Date.now()}`,
+        args: { value: "ids" },
+      });
+
+      expect(handleResult).toBeOk();
+      if (!handleResult.isOk()) throw new Error("Expected Ok result");
+      const handle = handleResult.value;
+      expect(typeof handle.firstExecutionRunId).toBe("string");
+      expect(handle.runId).toBe(handle.firstExecutionRunId);
+
+      await handle.result();
+    });
+  });
+
   describe("Wire format (D1) — transforms apply exactly once per boundary", () => {
     it("sends the original input, receiver parses once; output parsed once by the client", async ({
       client,
@@ -317,6 +398,42 @@ describe("Client Package - Integration Tests", () => {
         expect(result.value).toEqual({ finalValue: 15 });
       }
     });
+
+    it("should start an update via startUpdate and await its result on the update handle", async ({
+      client,
+    }) => {
+      // GIVEN
+      const workflowId = `start-update-test-${Date.now()}`;
+      const handleResult = await client.startWorkflow("interactiveWorkflow", {
+        workflowId,
+        args: { initialValue: 4 },
+      });
+
+      expect(handleResult).toBeOk();
+      if (!handleResult.isOk()) throw new Error("Expected Ok result");
+      const handle = handleResult.value;
+
+      // WHEN — start the update without waiting for completion, then await
+      // its result through the typed update handle.
+      const updateHandleResult = await handle.startUpdate("multiply", {
+        args: { factor: 5 },
+      });
+
+      // THEN
+      expect(updateHandleResult).toBeOk();
+      if (!updateHandleResult.isOk()) throw new Error("Expected Ok result");
+      const updateHandle = updateHandleResult.value;
+      expect(updateHandle.workflowId).toBe(workflowId);
+      expect(typeof updateHandle.updateId).toBe("string");
+
+      const updateResult = await updateHandle.result();
+      expect(updateResult).toBeOk();
+      if (updateResult.isOk()) {
+        expect(updateResult.value).toEqual({ newValue: 20 }); // 4 * 5
+      }
+
+      await handle.result();
+    });
   });
 
   describe("Workflow Handle Operations", () => {
@@ -431,7 +548,7 @@ describe("Client Package - Integration Tests", () => {
         },
         errCases: (matcher) =>
           matcher.with(
-            P.tag("@temporal-contract/WorkflowNotFoundError"),
+            P.tag("@temporal-contract/WorkflowNotInContractError"),
             P.tag("@temporal-contract/WorkflowValidationError"),
             P.tag("@temporal-contract/WorkflowAlreadyStartedError"),
             P.tag("@temporal-contract/WorkflowFailedError"),

packages/client/src/__tests__/second.contract.ts

@@ -0,0 +1,22 @@
+import { defineContract, defineWorkflow } from "@temporal-contract/contract";
+import { z } from "zod";
+
+/**
+ * Second test contract on its own task queue — exercised by the
+ * "multiple contracts, one root" integration case: one `TypedClient`
+ * root drives both this contract and `testContract`, each routed to
+ * its own queue via `root.for(contract)`.
+ */
+export const secondContract = defineContract({
+  taskQueue: "second-client-queue",
+  workflows: {
+    echoWorkflow: defineWorkflow({
+      input: z.object({
+        text: z.string(),
+      }),
+      output: z.object({
+        echoed: z.string(),
+      }),
+    }),
+  },
+});

packages/client/src/__tests__/second.workflows.ts

@@ -0,0 +1,9 @@
+/**
+ * Workflow implementations for `second.contract.ts` — registered on the
+ * second worker (own task queue) in the integration suite.
+ */
+export async function echoWorkflow(args: { text: string }): Promise<{ echoed: string }> {
+  return {
+    echoed: `second-queue: ${args.text}`,
+  };
+}