feat(worker)!: signal drop policy, contract-misuse failures, and worker surface fixes

- D2: invalid signal payloads are dropped and logged via @temporalio/workflow's
  log.warn instead of throwing; SignalInputValidationError is deleted
- D3: new ContractMisuseError (non-retryable ApplicationFailure) replaces every
  plain Error thrown from workflow-sandbox code (handler binding guards,
  sync-schema guards, buildRawActivitiesProxy options-coverage errors)
- item 20: declareActivitiesHandler iterates contract definitions (fail fast on
  declared-but-missing implementations), rejects workflow-name/global-activity
  collisions (defense-in-depth, message aligned with defineContract), and
  errors on stray root-level keys whether or not contract.activities exists
- item 21: TypedChildWorkflowHandle gains a typed signals map (validate on
  send, transmit original per D1) and firstExecutionRunId
- item 22: declareWorkflow throws ContractMisuseError for unknown workflow
  names, listing the available ones
- item 23: activities is optional on createWorker (workflow-only workers, key
  omitted from Worker.create when absent); key remapping drops empty
  "workflowName: {}" placeholder entries from the implementations map (NoInfer
  keeps lambda contextual typing intact); extractHandlerInput maps zero args
  to undefined, pairing with input-less signal/query/update definitions
- item 24: rename exported qualify -> qualifyFailure (no alias; unshipped beta)
- item 25: ValidationError name property non-enumerable; new SignalDefOf /
  QueryDefOf / UpdateDefOf type helpers replace the triple-repeated
  conditionals; deduped the update sync-validation message
- item 26: README quick start rewritten around createWorker +
  workflowsPathFromURL (ESM, .js imports, named contract export, conditional
  cause spread); TSDoc fixes (child-workflow contract-required bullets,
  .getOrThrow -> .get, declareActivitiesHandler example uses createWorker,
  cause idiom); worker integration tests migrated to the new
  TypedClient.create({ client }).for(contract) client surface

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

Author: btravers

packages/worker/README.md

@@ -17,6 +17,8 @@ pnpm add @temporal-contract/worker @temporal-contract/contract @temporalio/workf
 import { declareActivitiesHandler, ApplicationFailure } from "@temporal-contract/worker/activity";
 import { fromPromise } from "unthrown";
 
+import { myContract } from "./contract.js";
+
 export const activities = declareActivitiesHandler({
   contract: myContract,
   activities: {
@@ -25,15 +27,20 @@ export const activities = declareActivitiesHandler({
         ApplicationFailure.create({
           type: "EMAIL_FAILED",
           message: error instanceof Error ? error.message : "Failed to send email",
-          cause: error,
+          // Omit `cause` entirely for non-Error rejections — don't pass undefined.
+          ...(error instanceof Error ? { cause: error } : {}),
         }),
       ).map(() => ({ sent: true })),
   },
 });
+```
 
+```typescript
 // workflows.ts
 import { declareWorkflow } from "@temporal-contract/worker/workflow";
 
+import { myContract } from "./contract.js";
+
 export const processOrder = declareWorkflow({
   workflowName: "processOrder",
   contract: myContract,
@@ -44,23 +51,48 @@ export const processOrder = declareWorkflow({
     return { success: true };
   },
 });
+```
 
+```typescript
 // worker.ts
-import { Worker } from "@temporalio/worker";
-import { activities } from "./activities";
-import myContract from "./contract";
-
-async function run() {
-  const worker = await Worker.create({
-    workflowsPath: require.resolve("./workflows"),
-    activities,
-    taskQueue: myContract.taskQueue,
-  });
-
-  await worker.run();
+import { NativeConnection } from "@temporalio/worker";
+import { createWorker, workflowsPathFromURL } from "@temporal-contract/worker/worker";
+
+import { activities } from "./activities.js";
+import { myContract } from "./contract.js";
+
+const connection = await NativeConnection.connect({ address: "localhost:7233" });
+
+// The task queue comes from the contract; the workflows path is resolved
+// from this module's URL (ESM — include the extension explicitly).
+const workerResult = await createWorker({
+  contract: myContract,
+  connection,
+  workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
+  activities,
+});
+if (workerResult.isDefect()) {
+  // Bundling / connection failure — a TechnicalError-caused defect, not thrown.
+  console.error("worker setup failed", workerResult.cause);
+  process.exit(1);
 }
 
-run().catch(console.error);
+await workerResult.value.run();
+```
+
+### Workflow-only workers
+
+`activities` is optional on `createWorker`. Omit it to run a worker that only
+executes workflows — useful when workflow code and activity code are deployed
+and scaled as separate processes on the same task queue:
+
+```typescript
+const workerResult = await createWorker({
+  contract: myContract,
+  connection,
+  workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
+  // no `activities` — this process polls for Workflow Tasks only
+});
 ```
 
 ### Child Workflows

packages/worker/src/__tests__/time-skipping.inprocess.spec.ts

@@ -80,13 +80,12 @@ describe("time-skipping TestWorkflowEnvironment", () => {
     const worker = workerResult.value;
 
     const clientResult = await TypedClient.create({
-      contract: inprocessContract,
       client: testEnv.client,
       interceptors: [recording],
     });
     expect(clientResult.isOk()).toBe(true);
     if (!clientResult.isOk()) return;
-    const client = clientResult.value;
+    const client = clientResult.value.for(inprocessContract);
 
     await worker.runUntil(async () => {
       // Happy path — the hour-long sleep is skipped, the accumulated

packages/worker/src/__tests__/worker.spec.ts

@@ -1,7 +1,11 @@
 import { extname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { TypedClient, WorkflowValidationError } from "@temporal-contract/client";
+import {
+  TypedClient,
+  WorkflowValidationError,
+  type ContractClient,
+} from "@temporal-contract/client";
 import { it as baseIt } from "@temporal-contract/testing/extension";
 import { Client, WorkflowFailedError } from "@temporalio/client";
 import { type Worker } from "@temporalio/worker";
@@ -22,7 +26,7 @@ const errAsync = <E>(error: E): AsyncResult<never, E> => Err(error).toAsync();
 
 const it = baseIt.extend<{
   worker: Worker;
-  client: TypedClient<typeof testContract>;
+  client: ContractClient<typeof testContract>;
 }>({
   worker: [
     async ({ workerConnection }, use) => {
@@ -55,17 +59,14 @@ const it = baseIt.extend<{
     { auto: true },
   ],
   client: async ({ clientConnection }, use) => {
-    // Create typed client
+    // Create the connection-scoped root, then bind the contract.
     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 root = (await TypedClient.create({ client: rawClient })).get();
 
-    await use(clientResult.value);
+    await use(root.for(testContract));
   },
 });
 
@@ -78,8 +79,8 @@ const logMessages: string[] = [];
 const activities = declareActivitiesHandler({
   contract: testContract,
   activities: {
-    simpleWorkflow: {},
-
+    // Workflows without declared activities (simpleWorkflow,
+    // interactiveWorkflow, parentWorkflow, ...) no longer need `{}` entries.
     workflowWithActivities: {
       processPayment: ({ amount }) => {
         return okAsync({
@@ -95,14 +96,6 @@ const activities = declareActivitiesHandler({
       },
     },
 
-    interactiveWorkflow: {},
-
-    parentWorkflow: {},
-
-    childWorkflow: {},
-
-    workflowWithFailableActivity: {},
-
     logMessage: ({ message }) => {
       logMessages.push(message);
       return okAsync({});
@@ -190,8 +183,8 @@ describe("Worker Package - Integration Tests", () => {
         args: input,
       });
 
-      // WHEN
-      const handleResult = await client.getHandle("simpleWorkflow", workflowId);
+      // WHEN — getHandle is synchronous in the new client surface
+      const handleResult = client.getHandle("simpleWorkflow", workflowId);
 
       // THEN
       expect(handleResult).toBeOk();

packages/worker/src/activity-contract-errors.spec.ts

@@ -116,7 +116,6 @@ describe("declareActivitiesHandler — contract errors", () => {
     const activities = declareActivitiesHandler({
       contract: transformingContract,
       activities: {
-        noop: {},
         flaky: (_args, { errors }) => errAsync(errors.Nope({ reason: "declined" })),
       },
     });