chore: enable all @unthrown/oxlint rules and fix the docs build

Docs build (root cause of the Package / ci Build / Bundle Size failures):
the TSDoc on TypedWorkflowHandle's queries/signals/updates properties held
inline code spans containing a raw `|` (e.g.
AsyncResult<T, QueryValidationError | WorkflowExecutionNotFoundError>).
typedoc renders member docs into markdown table cells without escaping
pipes inside code spans, so markdown-it split the row at the pipe, the
broken span left `Promise<T>` as a raw HTML-looking `<T>` element, and
VitePress's Vue compiler failed with "Element is missing end tag" at
api/client/index.md. Fixed at the source by rewording the three doc
comments so no code span carries a pipe; generated files untouched.

Lint: turn on unthrown/no-throw and unthrown/prefer-ensure, so all six
rules are now at "error". prefer-ensure surfaced 0 violations. no-throw
surfaced 148:

- 76 in test files, handled by a config override turning only no-throw
  off for **/*.spec.ts and **/__tests__/** (tests throw to simulate
  defects and assert rejections; the other five rules stay on).
- 72 in source, each carrying a targeted oxlint-disable naming its
  category — none could be restructured to Err(...) without changing
  semantics:
  - 33 sanctioned ValidationError / ContractMisuseError /
    ApplicationFailure sites (CLAUDE.md rule 2 exception — Temporal's
    terminal-failure semantics require the throw)
  - 12 client-side technical faults thrown inside makeAsyncResult work
    thunks (RuntimeClientError/TechnicalError — the throw IS the
    defect-channel routing)
  - 6 defect-cause / workflow-sandbox rethrows (unmodeled failures kept
    on the defect channel)
  - 1 cancellation rethrow (CancelledFailure must propagate)
  - 7 declaration-time fail-fast config errors (worker startup /
    contract definition / test setup)
  - 13 example-domain throws in plain Promise helpers wrapped once at
    the activity boundary via fromPromise(..., qualifyFailure(...))

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

Author: btravers

.oxlintrc.json

@@ -5,7 +5,17 @@
   "rules": {
     "unthrown/no-ambiguous-error-type": "error",
     "unthrown/no-catch-all-pattern": "error",
+    "unthrown/no-throw": "error",
     "unthrown/no-unhandled-result": "error",
-    "unthrown/prefer-async-result": "error"
-  }
+    "unthrown/prefer-async-result": "error",
+    "unthrown/prefer-ensure": "error"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.spec.ts", "**/__tests__/**"],
+      "rules": {
+        "unthrown/no-throw": "off"
+      }
+    }
+  ]
 }

examples/order-processing-worker/src/application/workflows.ts

@@ -150,6 +150,7 @@ export const processOrder = declareWorkflow({
       if (paymentResult.isDefect()) {
         // Unmodeled failure (a bug, not an anticipated outcome) — rethrow at
         // the edge so Temporal surfaces the Workflow Task failure.
+        // oxlint-disable-next-line unthrown/no-throw -- defect-cause rethrow at the edge: an unmodeled failure must surface as a Workflow Task failure
         throw paymentResult.cause;
       }
       const failure = paymentResult.error;
@@ -169,6 +170,7 @@ export const processOrder = declareWorkflow({
           // Rethrow as this workflow's own declared contract error: the
           // execution fails with `ApplicationFailure(type: "PaymentDeclined")`
           // and the typed client rehydrates it into a `ContractError`.
+          // oxlint-disable-next-line unthrown/no-throw -- sanctioned ApplicationFailure model: `throw context.errors.X(...)` is how a workflow fails terminally with a typed contract error (CLAUDE.md rule 2 exception)
           throw context.errors.PaymentDeclined({ reason: failure.data.reason }, { cause: failure });
         }
         case "@temporal-contract/ActivityError":
@@ -244,6 +246,7 @@ export const processOrder = declareWorkflow({
       // Cancellation must propagate — swallowing it here would leave the
       // workflow running after a cancel request.
       if (isCancellation(error)) {
+        // oxlint-disable-next-line unthrown/no-throw -- cancellation rethrow: swallowing a CancelledFailure would leave the workflow running after a cancel request
         throw error;
       }
       // Non-critical: log but continue

examples/order-processing-worker/src/domain/usecases/create-shipment.usecase.ts

@@ -12,10 +12,12 @@ export class CreateShipmentUseCase {
   async execute(orderId: string, customerId: string): Promise<ShippingResult> {
     // Business validation
     if (!orderId || orderId.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Order ID is required");
     }
 
     if (!customerId || customerId.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Customer ID is required");
     }
 

examples/order-processing-worker/src/domain/usecases/process-payment.usecase.ts

@@ -12,10 +12,12 @@ export class ProcessPaymentUseCase {
   async execute(customerId: string, amount: number): Promise<PaymentOutcome> {
     // Business validation
     if (amount <= 0) {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Payment amount must be positive");
     }
 
     if (!customerId || customerId.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Customer ID is required");
     }
 

examples/order-processing-worker/src/domain/usecases/purge-expired-orders.usecase.ts

@@ -11,6 +11,7 @@ export class PurgeExpiredOrdersUseCase {
   async execute(olderThanDays: number): Promise<number> {
     // Business validation
     if (!Number.isInteger(olderThanDays) || olderThanDays <= 0) {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("olderThanDays must be a positive integer");
     }
 

examples/order-processing-worker/src/domain/usecases/refund-payment.usecase.ts

@@ -11,6 +11,7 @@ export class RefundPaymentUseCase {
   async execute(transactionId: string): Promise<void> {
     // Business validation
     if (!transactionId || transactionId.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Transaction ID is required");
     }
 

examples/order-processing-worker/src/domain/usecases/release-inventory.usecase.ts

@@ -11,6 +11,7 @@ export class ReleaseInventoryUseCase {
   async execute(reservationId: string): Promise<void> {
     // Business validation
     if (!reservationId || reservationId.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Reservation ID is required");
     }
 

examples/order-processing-worker/src/domain/usecases/reserve-inventory.usecase.ts

@@ -12,11 +12,13 @@ export class ReserveInventoryUseCase {
   async execute(items: OrderItem[]): Promise<InventoryReservation> {
     // Business validation
     if (!items || items.length === 0) {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("At least one item is required");
     }
 
     for (const item of items) {
       if (item.quantity <= 0) {
+        // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
         throw new Error(`Invalid quantity for product ${item.productId}`);
       }
     }

examples/order-processing-worker/src/domain/usecases/send-notification.usecase.ts

@@ -11,14 +11,17 @@ export class SendNotificationUseCase {
   async execute(customerId: string, subject: string, message: string): Promise<void> {
     // Business validation
     if (!customerId || customerId.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Customer ID is required");
     }
 
     if (!subject || subject.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Subject is required");
     }
 
     if (!message || message.trim() === "") {
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Message is required");
     }
 

examples/order-processing-worker/src/infrastructure/adapters/payment.adapter.ts

@@ -56,6 +56,7 @@ export class MockPaymentAdapter implements PaymentPort {
       logger.info(`✅ Refund successful`);
     } else {
       logger.error(`❌ Refund failed`);
+      // oxlint-disable-next-line unthrown/no-throw -- known-technical precondition throw in a plain (non-Result) domain helper, wrapped once at the activity boundary via fromPromise(..., qualifyFailure(...))
       throw new Error("Payment processor rejected refund request");
     }
   }