docs: unwrap discarded AsyncResults and fix non-exhaustive matchers

Addresses PR review. `AsyncResult` is a success-only thenable — its
internal promise never rejects (core.ts:616) — so `await` collapses it
to a Result and a bare `await handle.signals.x(...)` or
`await schedule.pause(...)` discards the failure entirely.

Copilot flagged four sites; the same bug was present at ~15. All are
now unwrapped with `.get()` / `.getOrThrow()` or an explicit branch, and
the trap is documented in the-result-model.md ("`await` is not an
extractor") plus inline warnings on the schedule, signals, and upgrade
pages.

Also fixes the interceptor short-circuit, which returned
`Err(new RuntimeClientError(...))`. That is both a type error —
`ClientCallError` excludes it since 8.0 — and the wrong channel. It now
defects via `fromSafePromise`, and the note points at the `defect`
helper passed as the second argument to every `*ErrCases` callback.

Auditing that turned up a further class of broken example: all the
`*ErrCases` combinators require an `ExhaustiveMatch`, so the single-arm
`.with(tag(...))` calls in the interceptor and middleware pages would
not compile against their wide unions. Those now close with `P._`, and
the abbreviated before/after snippets in the migration guides are
labelled as such.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/explanation/the-result-model.md

@@ -193,6 +193,34 @@ Extractors, and how each treats a defect:
 
 Every one rethrows a defect. There is no extractor that quietly swallows a bug.
 
+### `await` is not an extractor
+
+The one trap worth internalizing. `AsyncResult` is a **success-only thenable**:
+awaiting it collapses it to a `Result`, and the underlying promise never
+rejects. So `await` never throws, whatever the outcome:
+
+```typescript
+// ❌ The Result is discarded. A failed signal — or an outright bug — vanishes.
+await handle.signals.approve({ approvedBy: "ops" });
+
+// ✅ Unwrap it.
+(await handle.signals.approve({ approvedBy: "ops" })).getOrThrow();
+
+// ✅ Or chain the extractor before awaiting.
+await handle.signals.approve({ approvedBy: "ops" }).getOrThrow();
+
+// ✅ Or branch.
+const sent = await handle.signals.approve({ approvedBy: "ops" });
+if (sent.isErr()) {
+  /* ... */
+}
+```
+
+This bites hardest on operations returning `AsyncResult<void, never>` — the
+schedule handle's `pause` / `unpause` / `trigger` / `delete`. An empty error
+channel reads like "cannot fail", but every failure there is a _defect_, and a
+bare `await` drops it silently. Chain `.get()`.
+
 ## Next
 
 - [Errors reference](/reference/errors) — every class and its channel

docs/explanation/workflow-determinism.md

@@ -104,7 +104,7 @@ Temporal's `CancellationScope` and surface cancellation as
 const result = await context.cancellableScope(() => context.activities.processStep(args));
 
 if (result.isErr()) {
-  await context.nonCancellableScope(() => context.activities.releaseResources(args));
+  await context.nonCancellableScope(() => context.activities.releaseResources(args)).getOrThrow();
   return { status: "cancelled" };
 }
 ```

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

@@ -174,11 +174,17 @@ Because `next` can be called more than once, a retry is just a branch on the
 error channel:
 
 ```typescript
+import { Err, P } from "unthrown";
+
 const retryOnce: ActivityMiddleware = (invocation, next) =>
   next().flatMapErrCases((matcher) =>
-    matcher.with(P.instanceOf(ApplicationFailure), (error) =>
-      error.type === "GATEWAY_TIMEOUT" ? next() : Err(error).toAsync(),
-    ),
+    matcher
+      .with(P.instanceOf(ApplicationFailure), (error) =>
+        error.type === "GATEWAY_TIMEOUT" ? next() : Err(error).toAsync(),
+      )
+      // The middleware error union is `ApplicationFailure | AnyContractError`,
+      // and the matcher must cover all of it — pass declared errors through.
+      .with(P._, (error) => Err(error).toAsync()),
   );
 ```
 

docs/how-to/handle-cancellation.md

@@ -13,10 +13,12 @@ if (bound.isErr()) {
 }
 
 // Cooperative: the workflow observes the request and exits on its own terms.
-await bound.value.cancel();
+// `.getOrThrow()` surfaces a WorkflowExecutionNotFoundError — a bare `await`
+// would collapse the AsyncResult to an ignored Result instead.
+await bound.value.cancel().getOrThrow();
 
 // Forceful: Temporal stops the execution immediately. No cleanup runs.
-await bound.value.terminate("fraud detected");
+await bound.value.terminate("fraud detected").getOrThrow();
 ```
 
 Prefer `cancel`. Reach for `terminate` only when the workflow is stuck or
@@ -76,7 +78,11 @@ implementation: async (context, order) => {
     // Cancelled after the charge but before shipping — refund.
     // Without the non-cancellable scope this refund would itself be cancelled.
     if (transactionId !== undefined) {
-      await context.nonCancellableScope(() => context.activities.refundPayment({ transactionId }));
+      // Unwrap: a refund that silently failed is worse than a loud failure,
+      // and a bare `await` would discard both the Err and any defect.
+      await context
+        .nonCancellableScope(() => context.activities.refundPayment({ transactionId }))
+        .getOrThrow();
     }
     return { status: "cancelled" as const };
   }

docs/how-to/index-workflows-with-search-attributes.md

@@ -152,15 +152,17 @@ Attributes set on a schedule apply to each run it spawns, so scheduled and
 directly started executions are indexed identically:
 
 ```typescript
-await client.schedule.create("processOrder", {
-  scheduleId: "nightly-reconcile",
-  spec: { cronExpressions: ["0 2 * * *"] },
-  args: { mode: "reconcile" },
-  searchAttributes: {
-    priority: 5,
-    tags: ["scheduled"],
-  },
-});
+await client.schedule
+  .create("processOrder", {
+    scheduleId: "nightly-reconcile",
+    spec: { cronExpressions: ["0 2 * * *"] },
+    args: { mode: "reconcile" },
+    searchAttributes: {
+      priority: 5,
+      tags: ["scheduled"],
+    },
+  })
+  .getOrThrow();
 ```
 
 ## Keep the cardinality sane

docs/how-to/intercept-client-calls.md

@@ -95,32 +95,71 @@ Modeled domain errors (`WorkflowNotFoundError`, a `ContractError`, a validation
 failure) stay on the `err` channel. Branch on those with `flatMapErrCases`:
 
 ```typescript
+import { Err, Ok, P, tag } from "unthrown";
+
 const fallback: ClientInterceptor = (args, next) =>
   next().flatMapErrCases((matcher) =>
-    matcher.with(tag("@temporal-contract/WorkflowAlreadyStartedError"), () =>
+    matcher
       // Idempotent start: treat "already running" as success.
-      Ok(undefined).toAsync(),
-    ),
+      .with(tag("@temporal-contract/WorkflowAlreadyStartedError"), () => Ok(undefined).toAsync())
+      // The matcher must cover the whole union — `P._` passes the rest through.
+      .with(P._, (error) => Err(error).toAsync()),
   );
 ```
 
+::: warning The matcher is exhaustive
+`flatMapErrCases`, `mapErrCases`, `tapErrCases`, and `recoverErrCases` all
+require a match that covers every member of the error union — here the nine
+members of `ClientCallError`. A single `.with(tag(...))` arm will not compile.
+Handle the cases you care about, then close with `P._`.
+:::
+
 Calling `next()` twice re-runs the rest of the chain, so retries compose.
 
 ## Short-circuit
 
 Return your own result without calling `next`:
 
 ```typescript
+import { fromSafePromise } from "unthrown";
+
 const readOnlyGuard: ClientInterceptor = (args, next) => {
   if (maintenanceMode && args.operation !== "query") {
-    return Err(
-      new RuntimeClientError(args.operation, new Error("maintenance mode: writes disabled")),
-    ).toAsync();
+    // Maintenance mode is a technical fault, not a domain outcome, so it
+    // belongs on the defect channel. `fromSafePromise` turns any throw from
+    // the thunk into a defect, giving an AsyncResult<never, never>.
+    return fromSafePromise(async () => {
+      throw new RuntimeClientError(args.operation, new Error("maintenance mode: writes disabled"));
+    });
   }
   return next();
 };
 ```
 
+::: warning Do not put `RuntimeClientError` on the `err` channel
+`ClientCallError` does not include it — since 8.0 it rides the defect channel.
+`Err(new RuntimeClientError(...))` is both a type error and the wrong channel.
+
+There is no exported bare `Defect` constructor. Produce one by throwing inside
+`fromSafePromise` / `fromSafeThrowable`, or via the `defect` helper passed as
+the **second argument** to every `*ErrCases` callback and to a `fromPromise`
+qualifier:
+
+```typescript
+next().mapErrCases(
+  (matcher, defect) => matcher.with(P._, (error) => defect(error)), // demote every modeled error
+);
+```
+
+:::
+
+To short-circuit with a _modeled_ outcome instead, return `Ok`:
+
+```typescript
+const skipInReadOnly: ClientInterceptor = (args, next) =>
+  maintenanceMode && args.operation === "signal" ? Ok(undefined).toAsync() : next();
+```
+
 ## Measure latency
 
 ```typescript

docs/how-to/migrate-from-neverthrow.md

@@ -103,7 +103,7 @@ exhaustive matcher instead of the bare error:
 // before
 result.mapErr((error) => new WrappedError(error));
 
-// after
+// after — one arm per tag in the union (abbreviated here; see the note below)
 import { tag } from "unthrown";
 
 result.mapErrCases((matcher) =>

docs/how-to/schedule-workflows.md

@@ -61,19 +61,21 @@ DST shifts will surprise you otherwise.
 ## Control overlap and catch-up
 
 ```typescript
-await client.schedule.create("reconcileLedger", {
-  scheduleId: "nightly-reconcile",
-  spec: { cronExpressions: ["0 2 * * *"] },
-  args: { mode: "full" },
-  policies: {
-    // What to do if the previous run is still going.
-    overlap: "SKIP", // BUFFER_ONE | BUFFER_ALL | CANCEL_OTHER | TERMINATE_OTHER | ALLOW_ALL
-    // How far back to catch up after an outage.
-    catchupWindow: "1 hour",
-    // Pause the whole schedule if a run fails.
-    pauseOnFailure: true,
-  },
-});
+await client.schedule
+  .create("reconcileLedger", {
+    scheduleId: "nightly-reconcile",
+    spec: { cronExpressions: ["0 2 * * *"] },
+    args: { mode: "full" },
+    policies: {
+      // What to do if the previous run is still going.
+      overlap: "SKIP", // BUFFER_ONE | BUFFER_ALL | CANCEL_OTHER | TERMINATE_OTHER | ALLOW_ALL
+      // How far back to catch up after an outage.
+      catchupWindow: "1 hour",
+      // Pause the whole schedule if a run fails.
+      pauseOnFailure: true,
+    },
+  })
+  .getOrThrow();
 ```
 
 `overlap: "SKIP"` is the safe default for anything non-idempotent. `ALLOW_ALL`
@@ -82,35 +84,39 @@ will happily run twenty copies at once after an outage.
 ## Start paused
 
 ```typescript
-await client.schedule.create("reconcileLedger", {
-  scheduleId: "nightly-reconcile",
-  spec: { cronExpressions: ["0 2 * * *"] },
-  args: { mode: "full" },
-  state: {
-    paused: true,
-    note: "awaiting sign-off",
-    // Fire a fixed number of times then stop.
-    remainingActions: 10,
-  },
-});
+await client.schedule
+  .create("reconcileLedger", {
+    scheduleId: "nightly-reconcile",
+    spec: { cronExpressions: ["0 2 * * *"] },
+    args: { mode: "full" },
+    state: {
+      paused: true,
+      note: "awaiting sign-off",
+      // Fire a fixed number of times then stop.
+      remainingActions: 10,
+    },
+  })
+  .getOrThrow();
 ```
 
 ## Override the spawned workflow
 
 `action` carries workflow-level overrides for each run:
 
 ```typescript
-await client.schedule.create("reconcileLedger", {
-  scheduleId: "nightly-reconcile",
-  spec: { cronExpressions: ["0 2 * * *"] },
-  args: { mode: "full" },
-  memo: { owner: "platform" }, // metadata on the schedule itself
-  action: {
-    workflowExecutionTimeout: "2 hours",
-    retry: { maximumAttempts: 2 },
-    memo: { kind: "scheduled-run" }, // metadata on each spawned workflow
-  },
-});
+await client.schedule
+  .create("reconcileLedger", {
+    scheduleId: "nightly-reconcile",
+    spec: { cronExpressions: ["0 2 * * *"] },
+    args: { mode: "full" },
+    memo: { owner: "platform" }, // metadata on the schedule itself
+    action: {
+      workflowExecutionTimeout: "2 hours",
+      retry: { maximumAttempts: 2 },
+      memo: { kind: "scheduled-run" }, // metadata on each spawned workflow
+    },
+  })
+  .getOrThrow();
 ```
 
 ::: tip Two different memos
@@ -124,15 +130,17 @@ are nested separately.
 ## Index the spawned runs
 
 ```typescript
-await client.schedule.create("reconcileLedger", {
-  scheduleId: "nightly-reconcile",
-  spec: { cronExpressions: ["0 2 * * *"] },
-  args: { mode: "full" },
-  searchAttributes: {
-    priority: 5,
-    tags: ["scheduled"],
-  },
-});
+await client.schedule
+  .create("reconcileLedger", {
+    scheduleId: "nightly-reconcile",
+    spec: { cronExpressions: ["0 2 * * *"] },
+    args: { mode: "full" },
+    searchAttributes: {
+      priority: 5,
+      tags: ["scheduled"],
+    },
+  })
+  .getOrThrow();
 ```
 
 Keys and value types are constrained to what the workflow declares. See
@@ -149,24 +157,35 @@ if (created.isErr()) throw created.error;
 
 const schedule = created.value;
 
-await schedule.pause("incident #4821");
-await schedule.unpause("incident resolved");
+// `.get()` rethrows a defect's original cause. Without it, `await` merely
+// collapses the AsyncResult to a Result and the failure is discarded.
+await schedule.pause("incident #4821").get();
+await schedule.unpause("incident resolved").get();
 
 // Run it right now, without waiting for the next tick.
-await schedule.trigger();
+await schedule.trigger().get();
 
 // Inspect current state.
 const described = await schedule.describe();
-if (described.isOk()) {
+if (described.isDefect()) {
+  console.error("describe failed:", described.cause);
+} else {
   console.log(described.value.state.paused, described.value.info.nextActionTimes);
 }
 
-await schedule.delete();
+await schedule.delete().get();
 ```
 
 Every method returns `AsyncResult<T, never>` — there is no modeled error. An
 unknown schedule id or a transport failure is a technical fault on the defect
-channel, so `.get()` is the extractor and a genuine problem surfaces loudly.
+channel.
+
+::: warning `await` alone does not surface the failure
+`AsyncResult` is a success-only thenable: awaiting it yields a `Result`, and the
+underlying promise never rejects. `await schedule.pause(...)` therefore discards
+a defect silently. Chain `.get()` (which rethrows the original cause) or branch
+on `isDefect()` — the same applies to every `AsyncResult` in this library.
+:::
 
 ## Reach an existing schedule