docs!: v8 migration guide and full docs sweep for the review remediation

Documents the v8 review-remediation changes (D1-D3 plus the client split)
across the hand-written docs, root README, and agent rules:

- upgrade-to-v8: new migration sections for the TypedClient/ContractClient
  split (create({client}).for(contract), ContractClient annotations, no
  createOrThrow), the WorkflowNotInContractError rename, sync getHandle,
  deleted ClientInfer* aliases, the validate-on-send/parse-on-receive wire
  format (D1) and its behavioral notes, signal drop-and-log semantics (D2),
  qualify -> qualifyFailure, ContractMisuseError (D3), workflow-only
  workers, fail-fast declareActivitiesHandler, contract-package changes
  (strict root validation without zod, collision recalibration, input-less
  builders, InferContractWorkflows removal, ESM-only), and the typed
  schedule surface (ScheduleAlreadyExistsError/ScheduleNotFoundError,
  update/backfill/list) with an expanded checklist
- validation-boundaries: rewritten around validate-on-send/parse-on-receive
  with the exactly-once transform rationale, signal-drop row, and the
  hand-rolled strict contract validation
- reference: client-surface rewritten for the two-class surface (for(),
  raw, startUpdate, runId fields, sync getHandle, schedule additions);
  contract-surface (UndefinedInputSchema, input-less builders, strict root
  keys); worker-surface (ContractMisuseError, qualifyFailure, optional
  activities, child-handle signals, signal-drop policy); errors (renames,
  schedule errors, workflowId, channel tables)
- how-to/tutorials: construction sweep to the two-step client form,
  input-less signal/query/update forms and omittable payloads, child
  signals map, workflow-only workers, schedule typed errors and
  create-if-absent idiom, sync getHandle call sites
- agent rules: qualifyFailure rename, client-split guidance, hand-rolled
  contract validation wording

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

Author: btravers

.agents/rules/contract-patterns.md

@@ -50,8 +50,9 @@ const processOrder = defineWorkflow({
     cancel: defineSignal({ input: z.object({ reason: z.string() }) }),
   },
   queries: {
+    // `input` is optional on signals/queries/updates — omit it for an
+    // argument-less definition (handler gets `undefined`).
     getStatus: defineQuery({
-      input: z.object({}),
       output: z.object({ status: z.string() }),
     }),
   },
@@ -101,4 +102,4 @@ Any Standard Schema compatible library works:
   - `errors` — same shape as workflow errors; produced via the `errors` constructors in the implementation's helpers argument, and rehydrated as a typed `AsyncResult` error union on the workflow side
   - `defaultOptions` — contract-level `ActivityOptions` defaults (timeouts, retry). Merge precedence at the worker: `declareWorkflow` `activityOptions` < `defaultOptions` < `activityOptionsByName`
 
-`defineContract` rejects collisions between workflow-local and global activity names at runtime — `defineContract` runs a Zod validation pass and throws a descriptive error. Activities share a single flat namespace at the worker level, so two activities can't share a name even across workflows. See `packages/contract/src/builder.ts:441` for the validation schema.
+`defineContract` validates the contract's structure at runtime with a hand-rolled structural validator (no zod runtime dependency) and throws a descriptive error: strict root keys (only `taskQueue`/`workflows`/`activities`), identifier-safe names, Standard Schema slots, and collision checks. Activities share a single flat namespace at the worker level, so two _different_ definitions can't share a name even across workflows — but reusing the **same definition object** across workflows is allowed (it's one activity), and the collision message recommends hoisting shared activities to the global `activities` block. A workflow name colliding with a global activity name is also rejected (they share the root of the worker implementations map). See `packages/contract/src/builder.ts` (`validateContractDefinition`).

.agents/rules/handlers.md

@@ -23,10 +23,10 @@ export const activities = declareActivitiesHandler({
 });
 ```
 
-`fromPromise(promise, qualify)` forces every rejection through `qualify`, which
+`fromPromise(promise, qualifyFailure)` forces every rejection through `qualifyFailure`, which
 returns the modeled error `E` (here an `ApplicationFailure`). For the common
-case, the worker package exports a `qualify(type, options?)` helper that builds
-that function — `fromPromise(inventoryService.check(orderId), qualify("INVENTORY_CHECK_FAILED"))`
+case, the worker package exports a `qualifyFailure(type, options?)` helper that builds
+that function — `fromPromise(inventoryService.check(orderId), qualifyFailure("INVENTORY_CHECK_FAILED"))`
 preserves an `Error` rejection's message and `cause`, with `options.nonRetryable`
 / `options.details` / `options.message` (non-`Error` fallback) available. For a
 value you already have, use `OkAsync(value)` / `ErrAsync(failure)`, or lift an
@@ -103,10 +103,13 @@ Typed-error semantics inside the workflow context:
 `createWorker` returns `AsyncResult<Worker, never>` — bundling / connection
 failures are _technical_ infrastructure faults, so they ride the **defect**
 channel (a `TechnicalError` instance as the cause), not the modeled Err
-channel. Same shape on the client: `TypedClient.create({ contract, client })`
+channel. `activities` is optional — omit it for a workflow-only worker. Same
+shape on the client: the connection-scoped `TypedClient.create({ client })`
 returns `AsyncResult<TypedClient, never>` (a `TechnicalError`-caused defect on
-setup failure). Deprecated throwing aliases (`createWorkerOrThrow`,
-`TypedClient.createOrThrow`) exist for migration.
+setup failure); bind a contract with the synchronous, infallible
+`typedClient.for(contract)`, which returns a `ContractClient<TContract>` (the
+type to use in annotations). There is no `TypedClient.createOrThrow`; the
+deprecated `createWorkerOrThrow` still exists for migration.
 
 ```typescript
 import { createWorker, workflowsPathFromURL } from "@temporal-contract/worker/worker";
@@ -181,7 +184,7 @@ ApplicationFailure.create({
 
 ## Anti-patterns
 
-- **Never throw** from activities — Temporal sees thrown errors as `ApplicationFailure(type: "Error", retryable: true)` by default, which masks the real failure type and triggers unwanted retries. Use `Err(ApplicationFailure.create({ type, message, nonRetryable })).toAsync()` (or a `fromPromise(promise, qualify)` chain whose `qualify` returns the `ApplicationFailure`) instead.
+- **Never throw** from activities — Temporal sees thrown errors as `ApplicationFailure(type: "Error", retryable: true)` by default, which masks the real failure type and triggers unwanted retries. Use `Err(ApplicationFailure.create({ type, message, nonRetryable })).toAsync()` (or a `fromPromise(promise, qualifyFailure)` chain whose `qualifyFailure` returns the `ApplicationFailure`) instead.
 - **Never use `any`** — use `unknown` and validate with schemas. Enforced by oxlint.
 - **Always use `.js` extensions** in imports (even for TypeScript files) — required by ESM module resolution.
 - **Don't `try/catch` `CancelledFailure` in workflows** — use `cancellableScope` so cancellation flows through the same `AsyncResult` discipline as everything else.

.agents/rules/project-overview.md

@@ -31,6 +31,6 @@
 
 - **Contract** — defines task queue, workflows, activities, signals, queries, updates, search attributes with schemas. See [contract-patterns.md](./contract-patterns.md).
 - **Worker** — `declareWorkflow` + `declareActivitiesHandler` with automatic validation. See [handlers.md](./handlers.md).
-- **Client** — `TypedClient.create()` returns `AsyncResult<T, E>` for all operations.
+- **Client** — `TypedClient.create({ client })` is connection-scoped; `client.for(contract)` hands out a contract-bound `ContractClient` whose operations return `AsyncResult<T, E>`.
 - **Result** — `Result<T, E>` and `AsyncResult<T, E>` from unthrown for explicit error handling, plus a third `defect` channel for unanticipated failures.
 - **Determinism** — workflow code runs in Temporal's replay sandbox. See [workflow-determinism.md](./workflow-determinism.md).

README.md

@@ -65,17 +65,19 @@ Implement the activities — note that workflow-scoped activities nest under the
 workflow, mirroring the contract:
 
 ```typescript
-import { declareActivitiesHandler, qualify } from "@temporal-contract/worker/activity";
+import { declareActivitiesHandler, qualifyFailure } from "@temporal-contract/worker/activity";
 import { fromPromise } from "unthrown";
 
 export const activities = declareActivitiesHandler({
   contract: orderContract,
   activities: {
     processOrder: {
       chargeCard: ({ customerId, amount }) =>
-        fromPromise(gateway.charge(customerId, amount), qualify("CHARGE_FAILED")).map((charge) => ({
-          transactionId: charge.id,
-        })),
+        fromPromise(gateway.charge(customerId, amount), qualifyFailure("CHARGE_FAILED")).map(
+          (charge) => ({
+            transactionId: charge.id,
+          }),
+        ),
     },
   },
 });
@@ -112,7 +114,8 @@ partial state, nothing to unwind.
 - **End-to-end type safety** — workflows, activities, signals, queries, updates,
   errors, and search attributes all derive from one contract
 - **Validation at every boundary** — Standard Schema (Zod, Valibot, ArkType) runs
-  on both sides of every network hop
+  on both sides of every network hop: validated on send, parsed on receive, so
+  transforms apply exactly once
 - **Typed domain errors** — declare failures on the contract; consume them as
   schema-validated values with an exhaustive matcher
 - **Explicit error handling** — `Result` / `AsyncResult` from

docs/examples/index.md

@@ -68,7 +68,7 @@ pnpm --filter @temporal-contract/sample-order-processing-worker test
 | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
 | [`contract.ts`](https://github.com/btravstack/temporal-contract/blob/main/examples/order-processing-contract/src/contract.ts)               | The global vs workflow-scoped activity split                    |
 | [`workflows.ts`](https://github.com/btravstack/temporal-contract/blob/main/examples/order-processing-worker/src/application/workflows.ts)   | Compensation logic, cancellation handling, per-activity options |
-| [`activities.ts`](https://github.com/btravstack/temporal-contract/blob/main/examples/order-processing-worker/src/application/activities.ts) | The nested implementation map, `fromPromise` + `qualify`        |
+| [`activities.ts`](https://github.com/btravstack/temporal-contract/blob/main/examples/order-processing-worker/src/application/activities.ts) | The nested implementation map, `fromPromise` + `qualifyFailure` |
 
 ## Smaller, focused examples
 

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 }),
-      qualify("NEXUS_CHARGE_FAILED")),
+      qualifyFailure("NEXUS_CHARGE_FAILED")),
 }
 ```
 

docs/explanation/the-result-model.md

@@ -17,7 +17,7 @@ three.
 | `defect` | A failure you did **not** model | `result.cause` |
 
 An `err` is a value you produced on purpose — `Err(...)`, or a rejection mapped
-through `fromPromise(promise, qualify(...))`. It is part of your type signature,
+through `fromPromise(promise, qualifyFailure(...))`. It is part of your type signature,
 and callers are expected to branch on it.
 
 A `defect` is what happens when something throws that you never modeled: a
@@ -57,7 +57,7 @@ anticipated failure modes_. Everything that can go wrong is a defect.
 
 ```typescript
 // `.get()` rethrows a defect's original cause — the right behaviour at startup
-const client = await TypedClient.create({ contract, client: temporalClient }).get();
+const client = await TypedClient.create({ client: temporalClient }).get();
 ```
 
 ## The shapes at each boundary

docs/explanation/validation-boundaries.md

@@ -1,59 +1,75 @@
 # Validation boundaries
 
-Where schemas run, why some data is validated twice, and what that buys.
+Where schemas run, why both sides of a hop run one, and what that buys.
 
 ## The map
 
+Every boundary follows one rule: **validate on send, parse on receive.** The
+sender runs the schema to fail early but transmits the caller's _original_
+value; the receiver parses, and the parsed value is what the handler sees.
+
 ```
 ┌─ Client process ───────────────────────────────────────┐
 │  executeWorkflow(args)                                  │
 │      │                                                  │
-│      ├─▶ ① workflow input schema                        │
+│      ├─▶ ① validate workflow input   (send original)    │
 │      ▼                                                  │
 └──────┼──────────────────────────────────────────────────┘
        │  network
 ┌──────▼─── Worker process ──────────────────────────────┐
 │  workflow function                                      │
-│      ├─▶ ② workflow input schema (again)               │
+│      ├─▶ ② parse workflow input     (handler gets it)   │
 │      │                                                  │
 │      │   context.activities.chargeCard(input)           │
-│      │       ├─▶ ③ activity input schema                │
+│      │       ├─▶ ③ validate activity input (send orig.) │
 │      │       ▼   network                                │
 │      │   activity implementation                        │
-│      │       ├─▶ ④ activity input schema (again)        │
+│      │       ├─▶ ④ parse activity input                 │
 │      │       │   ... your code ...                      │
-│      │       ├─▶ ⑤ activity output schema               │
+│      │       ├─▶ ⑤ validate activity output (send orig.)│
 │      │       ▼   network                                │
-│      │       └─▶ ⑥ activity output schema (again)       │
+│      │       └─▶ ⑥ parse activity output                │
 │      │                                                  │
-│      └─▶ ⑦ workflow output schema                       │
+│      └─▶ ⑦ validate workflow output  (send original)    │
 └──────┼──────────────────────────────────────────────────┘
        │  network
 ┌──────▼─── Client process ──────────────────────────────┐
-│      └─▶ ⑧ workflow output schema (again)               │
+│      └─▶ ⑧ parse workflow output                        │
 └─────────────────────────────────────────────────────────┘
 ```
 
-Signals, queries, and updates follow the same pattern: validated on the client
-before dispatch and on the worker before the handler runs.
+Signals, queries, updates, and child workflows follow the same pattern:
+validated on the sending side before dispatch, parsed on the receiving side
+before the handler (or caller) sees the value.
 
-## Why validate twice
+## Why both sides run the schema
 
-Points ①/② and ③/④ look redundant. They are not.
+Points ①/② and ③/④ look redundant. They are not — they do different jobs.
 
-**The caller-side check is for diagnostics.** It catches bad data _before_ it
+**The send-side check is for diagnostics.** It catches bad data _before_ it
 crosses the network, so you get a descriptive schema error naming the offending
 field, at the call site, with a stack trace pointing at your code. Without it,
 the same mistake surfaces as a deserialization failure inside a worker you may
-not even own.
-
-**The callee-side check is authoritative.** The worker cannot assume its caller
-used this library. A workflow may be started by the Temporal CLI, the Web UI,
-another SDK, or an older version of your own client. The contract is only a
-real guarantee if the side that enforces it is the side that runs the code.
-
-The cost is a schema parse against data that already passed one — negligible
-next to a network round-trip.
+not even own. Its parsed result is deliberately **discarded** — the wire
+carries the original value.
+
+**The receive-side parse is authoritative.** The worker cannot assume its
+caller used this library. A workflow may be started by the Temporal CLI, the
+Web UI, another SDK, or an older version of your own client. The contract is
+only a real guarantee if the side that enforces it is the side that runs the
+code.
+
+**Parsing once is what keeps transforms correct.** Schemas can transform —
+`z.coerce.date()`, `.transform(...)`, `.default(...)`. If both sides applied
+the parse and the wire carried the parsed value, every transform would run
+twice, silently corrupting data (a date coerced twice, a default applied to an
+already-defaulted object). Because the sender transmits the original and only
+the receiver's parse "counts", **each transform applies exactly once per
+boundary**. It also means what travels the wire — and what you see in the
+Temporal Web UI or a raw history export — is the sender's original value.
+
+The cost is one extra schema run per hop — negligible next to a network round
+trip.
 
 ## Fail fast, fail nowhere
 
@@ -100,13 +116,22 @@ disagreeing.
 | Worker, entering a workflow          | `WorkflowInputValidationError`                                                                      | Thrown; terminal              |
 | Worker, leaving a workflow           | `WorkflowOutputValidationError`                                                                     | Thrown; terminal              |
 | Worker, entering/leaving an activity | `ActivityInputValidationError`, `ActivityOutputValidationError`                                     | Thrown; terminal              |
+| Worker, receiving a signal           | —                                                                                                   | Signal dropped; `log.warn`    |
 | Contract error payload               | `ContractErrorDataValidationError`                                                                  | Thrown; terminal              |
 
 Worker-side validation errors extend Temporal's `ApplicationFailure` and are
 marked **non-retryable**. This is the right default: a schema mismatch is
 deterministic. Retrying the same payload against the same schema will fail
 identically, so retrying would only burn attempts and delay the real signal.
 
+The signal row is the deliberate exception. A signal is a fire-and-forget
+message any stale client can send; failing the whole execution over one
+malformed payload would let any sender kill any workflow. The worker drops the
+signal and logs a warning (via `@temporalio/workflow`'s replay-aware
+`log.warn`, with the signal name and the schema issues) — the execution
+continues untouched. Client-side, a malformed signal still fails early with
+`SignalValidationError` before dispatch.
+
 All of them carry `issues` — the raw Standard Schema issue array — for
 programmatic inspection, and a human-readable summary in `message`:
 
@@ -121,18 +146,33 @@ if (result.isErr() && result.error instanceof WorkflowValidationError) {
 ## Structure is validated too
 
 `defineContract` validates the contract itself, at call time — not the data, the
-_shape_:
+_shape_ (a hand-rolled structural check; the contract package has no runtime
+schema-library dependency):
 
 - `taskQueue` present and non-empty
 - at least one workflow
+- no unknown keys at the contract root (strict — only `taskQueue`,
+  `workflows`, `activities`)
 - every name a valid JavaScript identifier
 - every schema slot Standard Schema compatible
-- no activity-name collisions in the flat runtime namespace
+- 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`
 
 Because this runs at import time, a malformed contract fails when the process
 starts rather than when a workflow first executes.
 
+Inside the workflow sandbox, contract misuse — binding a handler for an
+undeclared signal/query/update, an async-validating query schema, an activity
+no options cover — throws `ContractMisuseError`, a non-retryable
+`ApplicationFailure`. It fails the execution terminally instead of hanging it
+in an infinite Workflow Task retry loop, which is what a plain `Error` thrown
+from sandbox code would cause.
+
 ## Where middleware and interceptors sit
 
 The two extension points sit on opposite sides of the boundary, and the