chore: add changeset for the v8 audit remediation

Author: btravers

.changeset/v8-audit-remediation.md

@@ -0,0 +1,54 @@
+---
+"@temporal-contract/contract": major
+"@temporal-contract/client": major
+"@temporal-contract/worker": major
+"@temporal-contract/testing": major
+---
+
+v8 audit remediation — a second full-surface pass hardening robustness, the unthrown integration, developer experience, and btravstack-family consistency before 8.0 stabilises.
+
+**All packages.**
+
+- ESM-only everywhere: `@temporal-contract/client` and `@temporal-contract/worker` drop their CJS output and legacy `main`/`module`/`types` fields; all four packages verify with `attw --profile esm-only`.
+- `@temporalio/*` peer ranges tightened from `^1` to `^1.16.0` — the real floor for the Schedule API and the top-level `@temporalio/common` search-attribute imports.
+- Error tags are exported as literal-typed constants (`CONTRACT_ERROR_TAG`, `ACTIVITY_ERROR_TAG`, `WORKFLOW_FAILED_ERROR_TAG`, …) so consumers match with `P.tag(CONST)` instead of hand-written strings; the classes consume the constants so tag and constant cannot drift.
+
+**`@temporal-contract/contract`:**
+
+- Type-helper renames to the family-standard `Infer*` prefix: `SignalNamesOf`/`QueryNamesOf`/`UpdateNamesOf`/`DeclaredErrorsOf` → `InferSignalNames`/`InferQueryNames`/`InferUpdateNames`/`InferDeclaredErrors`.
+- `defineActivity`'s `defaultOptions` key is renamed `activityOptions` (merge precedence unchanged).
+- Duration strings are validated against the `ms` grammar at `defineContract` time — `"5 minutos"`, `""`, and negative durations now fail at definition, naming the offending path, instead of at the worker.
+- Temporal-reserved names are rejected at `defineContract`: the `__temporal_` prefix and the exact `__stack_trace` / `__enhanced_stack_trace` query names.
+- Activity-only contracts are allowed — `workflows` may be `{}` when at least one global activity is declared (dedicated activity-pool task queues).
+- The typed-error wire encoding carries a provenance marker (`details[1] = { $tc: 1 }`). Data-less declared errors now require the marker to rehydrate, closing a false positive where any `ApplicationFailure` sharing a declared error's `type` string was surfaced as the typed domain error. A degrade-to-generic rehydration miss fires the new `onRehydrationMiss` diagnostic hook instead of failing silently.
+- The `/result-async` subpath is removed; the `_internal_*` helpers move behind a dedicated `@temporal-contract/contract/internal` subpath (not a public API).
+
+**`@temporal-contract/worker`:**
+
+- A shared activity referenced from several contract scopes must be implemented once at the global level or with the same function reference; two different implementations for one flattened name now throw at declaration time (previously the last one silently clobbered the rest).
+- The in-workflow handler binders are renamed to the `handle*` convention: `context.defineSignal`/`defineQuery`/`defineUpdate` → `context.handleSignal`/`handleQuery`/`handleUpdate` (no collision with the contract-authoring `define*` helpers or Temporal's own functions).
+- Previously-internal types are now exported so implementations can be factored out of the `declareWorkflow`/`declareActivitiesHandler` calls: `WorkflowContext`, `DeclareWorkflowOptions`, `WorkflowImplementation`, the child-workflow handle types, the signal/query/update handler-implementation types, `WorkflowInferActivity`, `DeclareActivitiesHandlerOptions`, `TypedContinueAsNewOptions`, plus the new `ActivityImplementationFor` / `GlobalActivityImplementationFor` helpers.
+- `qualifyFailure(errorType, options)` requires an `expected` discriminator (an error class, an array of classes, a predicate, or the explicit literal `"any"`). Causes matching `expected` are wrapped into the modeled `ApplicationFailure`; everything else — a `TypeError` from a bug, say — rides the **defect** channel instead of being mislabelled a business error. A matched inner `ApplicationFailure` with `nonRetryable: true` is inherited by default.
+- New `rethrowCancellation(error)` helper. When an activity declares an `errors` map, cancellation surfaces as `Err(ActivityCancelledError)`; generic error handling that folds every `Err` to a fallback would complete the workflow instead of cancelling it. The cancellation error classes' JSDoc documents the hazard and the helper.
+- Async query/update schemas are rejected at bind time (`ContractMisuseError`) rather than on the first live request.
+- `context.continueAsNew` can no longer have its validated `workflowType`/`taskQueue` overridden through the options bag.
+- `ChildWorkflowError` carries a structured `workflowName`; the input/output `ValidationError` subclasses carry a `readonly direction: "input" | "output"`.
+- `TypedWorker.create` verifies workflow registration by default — a contract workflow missing from the `workflowsPath` bundle, or an export whose name differs from its `workflowName`, fails creation with a contract-aware message. Opt out with `verifyWorkflowRegistration: false`.
+
+**`@temporal-contract/client`:**
+
+- Workflow outcomes are first-class typed errors on `executeWorkflow`/`handle.result()`: `WorkflowCancelledError`, `WorkflowTerminatedError`, `WorkflowTimeoutError` (each retaining the original `TemporalFailure` as `cause`) — no more `err.cause instanceof CancelledFailure` digging the matcher can't see.
+- Update and query operational failures are modeled instead of leaking as defects: `UpdateFailedError`, `UpdateRejectedError`, `QueryFailedError` (the last covering Temporal's `QueryNotRegisteredError`).
+- `P`-composable tag bundles (`WORKFLOW_START_ERROR_TAGS`, `WORKFLOW_OUTCOME_ERROR_TAGS`, `WORKFLOW_RESULT_ERROR_TAGS`) and a `tagPatterns(tags)` helper collapse the recurring multi-tag `match` arms.
+- `handle.raw` exposes the underlying `@temporalio/client` `WorkflowHandle`.
+- `ContractClient` and `TypedScheduleClient` are no longer constructible directly (use `typedClient.for(...)` / the schedule accessor); `ContractClient` exposes readonly `contract` and `taskQueue` getters.
+- Client interceptors may patch only `input`/`signalInput`, never identity fields such as `workflowName`.
+- `TypedScheduleHandle.update()` validates the updated action's `args` against the contract when its `workflowType` is a declared workflow. Invalid `DATETIME` search-attribute values (`new Date(NaN)`) are rejected.
+- Internals: the imperative `assertNoDefect` thunks are replaced with `AsyncResult` combinator chains, so defects flow through channels without manual re-wrapping.
+
+**`@temporal-contract/testing`:**
+
+- The factories move to the family option-bag convention: `createContractTest({ contract, workflowsPath, ... })` and `runActivity(definition, { implementation, input, env? })`.
+- New `runActivityHandler(definition, { ... })` routes through the real `declareActivitiesHandler` wrapping — input parse, output validation, contract-error wire conversion, and rehydration — so a test exercises what production does, not just the raw implementation.
+- `@unthrown/vitest` is wired in; the package's assertions use `toBeOk`/`toBeErrTagged`/`toBeDefect`.
+- `testcontainers` is now an optional peer dependency, required only for `createContractTest`; the Docker-free `/time-skipping` and `/activity` entries no longer pull it in.

docs/.vitepress/config.ts

@@ -78,6 +78,7 @@ const DOCS_SIDEBAR = [
       { text: "Contract surface", link: "/reference/contract-surface" },
       { text: "Worker surface", link: "/reference/worker-surface" },
       { text: "Client surface", link: "/reference/client-surface" },
+      { text: "Testing surface", link: "/reference/testing-surface" },
       { text: "Errors", link: "/reference/errors" },
       { text: "Glossary", link: "/reference/glossary" },
       { text: "API reference", link: "/api/" },

docs/api/index.md

@@ -19,13 +19,21 @@ from the previous `neverthrow`-based version.
 
 - [@temporal-contract/testing](./testing/) - Testing utilities with testcontainers
 
+Each package is documented per **public entry point**: contract as `index`
+(the root) and `errors`; worker as `activity`, `worker`, and `workflow`; testing
+as `activity`, `contract`, `extension`, `global-setup`, and `time-skipping`. The
+internal `@temporal-contract/contract/internal` entry carries no semver
+guarantee and is intentionally excluded.
+
 ## Hand-written reference
 
-The generated pages above describe every exported symbol. For grouped,
-narrative reference — option tables, error channels, merge order — see:
+The generated pages above describe every symbol exported from those public
+entry points. For grouped, narrative reference — option tables, error channels,
+merge order — see:
 
 - [Contract surface](/reference/contract-surface)
 - [Worker surface](/reference/worker-surface)
 - [Client surface](/reference/client-surface)
+- [Testing surface](/reference/testing-surface)
 - [Errors](/reference/errors)
 - [Glossary](/reference/glossary)

docs/examples/index.md

@@ -59,7 +59,7 @@ Watch the execution at <http://localhost:8233>.
 
 ```bash
 # Integration tests — needs Docker
-pnpm --filter @temporal-contract/sample-order-processing-worker test
+pnpm --filter @temporal-contract/sample-order-processing-worker test:integration
 ```
 
 ## Worth reading in the source

docs/explanation/nexus.md

@@ -119,7 +119,7 @@ contract covers its input and output again, at the cost of an extra hop:
 processOrder: {
   chargeViaNexus: ({ customerId, amount }) =>
     fromPromise(nexusClient.executeOperation("charge", { customerId, amount }),
-      qualifyFailure("NEXUS_CHARGE_FAILED")),
+      qualifyFailure("NEXUS_CHARGE_FAILED", { expected: NexusOperationError })),
 }
 ```
 

docs/explanation/validation-boundaries.md

@@ -150,18 +150,22 @@ _shape_ (a hand-rolled structural check; the contract package has no runtime
 schema-library dependency):
 
 - `taskQueue` present and non-empty
-- at least one workflow
+- at least one workflow _or_ global activity (activity-only contracts are valid
+  — a dedicated activity-pool worker needs no workflows)
 - no unknown keys at the contract root (strict — only `taskQueue`,
   `workflows`, `activities`)
-- every name a valid JavaScript identifier
+- every name a valid JavaScript identifier, and not a Temporal-reserved name
+  (the `__temporal_` prefix, `__stack_trace`, `__enhanced_stack_trace`)
+- every duration option a valid `ms` string (`"5 minutes"`, `"30s"`) — a typo
+  like `"5 minutos"` fails here, not at the worker
 - every schema slot Standard Schema compatible
 - no activity-name collisions in the flat runtime namespace — reusing the
   _same_ definition object across workflows is fine (that is one activity, not
   a collision); two different definitions under one name is rejected, with a
   hint to hoist the shared activity to the global `activities` block
 - no workflow name colliding with a global activity name (they share the root
   of the worker's implementations map)
-- no unknown keys in `defaultOptions`
+- no unknown keys in `activityOptions`
 
 Because this runs at import time, a malformed contract fails when the process
 starts rather than when a workflow first executes.

docs/explanation/workflow-determinism.md

@@ -75,7 +75,7 @@ is the boundary worth guarding.
 
 ```typescript
 let approved = false;
-context.defineSignal("approve", () => {
+context.handleSignal("approve", () => {
   approved = true;
 });
 ```

docs/how-to/add-activity-middleware.md

@@ -67,7 +67,11 @@ The most useful thing middleware does is extend the typed context that flows to
 implementations. Use `declareActivityMiddleware` to pin the in and out types:
 
 ```typescript
-import { declareActivityMiddleware, type EmptyContext } from "@temporal-contract/worker/activity";
+import {
+  ApplicationFailure,
+  declareActivityMiddleware,
+  type EmptyContext,
+} from "@temporal-contract/worker/activity";
 import { ErrAsync } from "unthrown";
 
 const withTenant = declareActivityMiddleware<EmptyContext, { tenantId: string }>(
@@ -96,7 +100,9 @@ export const activities = declareActivitiesHandler({
         // context.tenantId: string
         fromPromise(
           gateway.charge(context.tenantId, customerId, amount),
-          qualifyFailure("CHARGE_FAILED"),
+          // `expected` is required: name the anticipated failure class (or a
+          // predicate). Everything else rides the defect channel.
+          qualifyFailure("CHARGE_FAILED", { expected: GatewayError }),
         ),
     },
   },
@@ -145,7 +151,10 @@ export const activities = declareActivitiesHandler({
   activities: {
     processOrder: {
       chargeCard: ({ customerId, amount }, { context }) =>
-        fromPromise(context.gateway.charge(customerId, amount), qualifyFailure("CHARGE_FAILED")),
+        fromPromise(
+          context.gateway.charge(customerId, amount),
+          qualifyFailure("CHARGE_FAILED", { expected: GatewayError }),
+        ),
     },
   },
 });

docs/how-to/configure-a-worker.md

@@ -19,13 +19,14 @@ const worker = await TypedWorker.create({
   connection,
   workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
   activities,
-}).get();
+}).getOrThrow();
 
-await worker.run().get();
+await worker.run().getOrThrow();
 ```
 
 `taskQueue` comes from the contract, so you never repeat it. Everything else on
 Temporal's `WorkerOptions` is accepted and passed through.
+`TypedWorker.create` replaces the old free `createWorker` function.
 
 ## Handle a failed start
 
@@ -46,19 +47,55 @@ if (result.isDefect()) {
   process.exit(1);
 }
 
-await result.value.run().get();
+// Past the guard the only remaining variant is `Ok` — the error channel is
+// `never` — so unwrap and run.
+await result.getOrThrow().run().getOrThrow();
 ```
 
-`.get()` is the terse form — on a defect it rethrows the original cause with its
-stack intact, which is usually what you want at process startup.
+`.getOrThrow()` is the terse form — on a defect it rethrows the original cause
+with its stack intact, which is usually what you want at process startup. (With
+a `never` error channel `.get()` would compile too, but `.getOrThrow()` is the
+one idiom that stays correct if a modeled error is ever added.)
 
 `run()` has the same shape: it returns `AsyncResult<void, never>`, so a worker
 that fails while running surfaces as a defect (a `TechnicalError` cause) rather
-than a rejected promise — `await worker.run().get()` rethrows it at the edge.
-The underlying Temporal `Worker` stays available as `worker.raw` for anything
-the typed surface doesn't cover (`worker.raw.getState()`,
+than a rejected promise — `await worker.run().getOrThrow()` rethrows it at the
+edge. The underlying Temporal `Worker` stays available as `worker.raw` for
+anything the typed surface doesn't cover (`worker.raw.getState()`,
 `worker.raw.runUntil(...)`).
 
+## Verify workflow registration
+
+`TypedWorker.create` verifies workflow registration by default: it imports the
+`workflowsPath` module and checks that every contract workflow is exported
+under its declared name. Creation fails (a `TechnicalError`-caused defect) when
+
+- a contract workflow is missing from the bundle — a forgotten
+  `declareWorkflow` export that would otherwise surface only when the first
+  task for it was dispatched; or
+- a workflow is exported under a name that differs from its `workflowName` —
+  Temporal registers workflows by export name, so the mismatch would register
+  it as the wrong workflow type.
+
+Opt out with `verifyWorkflowRegistration: false`, for example when the
+workflows module intentionally exports helpers whose names shadow contract
+workflows:
+
+```typescript
+const worker = await TypedWorker.create({
+  contract: orderContract,
+  connection,
+  workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
+  activities,
+  verifyWorkflowRegistration: false,
+}).getOrThrow();
+```
+
+The check is best-effort: it only runs when `workflowsPath` is provided
+(prebuilt `workflowBundle`s are skipped), and a module that cannot be imported
+in the main thread is skipped silently — `Worker.create`'s bundler is the
+authority on whether the module loads at all.
+
 ## Resolve the workflows path
 
 Temporal bundles workflow code into an isolated sandbox, so it needs a _path_,
@@ -109,9 +146,9 @@ const worker = await TypedWorker.create({
   connection,
   workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
   // no `activities`
-}).get();
+}).getOrThrow();
 
-await worker.run().get();
+await worker.run().getOrThrow();
 ```
 
 This is the split-deployment pattern: workflows are deterministic and
@@ -134,7 +171,7 @@ const worker = await TypedWorker.create({
 
   // Cap the rate at which this worker pulls new work.
   maxTaskQueueActivitiesPerSecond: 50,
-}).get();
+}).getOrThrow();
 ```
 
 Activity concurrency is the usual bottleneck. Raise it for I/O-bound work; keep
@@ -143,14 +180,14 @@ it low for CPU-bound or memory-hungry activities.
 ## Shut down gracefully
 
 ```typescript
-const worker = await TypedWorker.create({/* ... */}).get();
+const worker = await TypedWorker.create({/* ... */}).getOrThrow();
 
 process.on("SIGTERM", () => {
   console.log("draining...");
   worker.shutdown();
 });
 
-await worker.run().get(); // resolves once in-flight tasks finish
+await worker.run().getOrThrow(); // resolves once in-flight tasks finish
 await connection.close();
 ```
 
@@ -180,16 +217,16 @@ const [orderWorker, shipmentWorker] = await Promise.all([
     connection,
     workflowsPath: workflowsPathFromURL(import.meta.url, "./order.workflows.js"),
     activities: orderActivities,
-  }).get(),
+  }).getOrThrow(),
   TypedWorker.create({
     contract: shipmentContract,
     connection,
     workflowsPath: workflowsPathFromURL(import.meta.url, "./shipment.workflows.js"),
     activities: shipmentActivities,
-  }).get(),
+  }).getOrThrow(),
 ]);
 
-await Promise.all([orderWorker.run().get(), shipmentWorker.run().get()]);
+await Promise.all([orderWorker.run().getOrThrow(), shipmentWorker.run().getOrThrow()]);
 ```
 
 They share the connection. Split them into separate processes when their
@@ -216,7 +253,7 @@ const worker = await TypedWorker.create({
   namespace: "my-namespace.a1b2c",
   workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
   activities,
-}).get();
+}).getOrThrow();
 ```
 
 ## Add logging

docs/how-to/continue-as-new.md

@@ -48,19 +48,21 @@ Base the decision on something deterministic. `context.info` exposes Temporal's
 ```typescript
 implementation: async (context, args) => {
   let processed = args.processed;
+  let cursor = args.cursor;
 
   while (true) {
-    const batch = await context.activities.fetchBatch({ cursor: args.cursor });
+    const batch = await context.activities.fetchBatch({ cursor });
     if (batch.items.length === 0) {
       return { processed };
     }
 
     await context.activities.processBatch({ items: batch.items });
     processed += batch.items.length;
+    cursor = batch.nextCursor; // advance, so the next fetch makes progress
 
     // Temporal's own signal that history is getting long.
     if (context.info.continueAsNewSuggested) {
-      return context.continueAsNew({ cursor: batch.nextCursor, processed });
+      return context.continueAsNew({ cursor, processed });
     }
   }
 };
@@ -118,14 +120,16 @@ return context.continueAsNew(
   { subscriptionId: args.subscriptionId, cycle: args.cycle + 1 },
   {
     workflowRunTimeout: "7 days",
-    retry: { maximumAttempts: 3 },
+    workflowTaskTimeout: "10 seconds",
     memo: { tenant: args.tenantId },
   },
 );
 ```
 
-`workflowType` and `taskQueue` are derived from the contract and cannot be set
-here.
+`TypedContinueAsNewOptions` is Temporal's `ContinueAsNewOptions` minus
+`workflowType` and `taskQueue` (derived from the contract, and ignored if you
+try to set them). There is no `retry` option — a continued run inherits the
+chain's retry policy; use activity retry policies for step-level retries.
 
 ## Drain handlers first