docs: drop redudant sections

Author: f15u

apps/web/src/content/docs/v4/guides/modeling-errors.mdx

@@ -830,176 +830,6 @@ never entered the `Error` type parameter: it became a defect.
 with the error. Unknown defects stay fatal, so the handler re-raises them with
 `Effect.die`.
 
-### Typed recovery never catches a defect
-
-`Effect.catchTags` from the previous section handles every modeled failure.
-Does it also handle defects? Give the job both steps, authorize then capture,
-and handle every tag:
-
-```ts twoslash import.meta.vitest
-import { Effect, Data } from "effect"
-
-interface Authorization {
-  readonly authorizationId: string
-  readonly status: "authorized" | "declined"
-}
-
-class NetworkError extends Data.TaggedError("NetworkError")<{
-  readonly cause?: unknown
-}> {}
-class PaymentDeclinedError extends Data.TaggedError("PaymentDeclinedError") {}
-class ParseError extends Data.TaggedError("ParseError")<{
-  readonly cause?: unknown
-}> {}
-class DoubleCaptureError extends Data.TaggedError("DoubleCaptureError")<{
-  readonly authorizationId: string
-}> {}
-
-function isAuthorization(body: unknown): body is Authorization {
-  const r = body as Authorization
-  return (
-    (r?.status === "authorized" || r?.status === "declined") &&
-    typeof r?.authorizationId === "string"
-  )
-}
-
-type PaymentToken = "tok_visa" | "tok_declined" | "tok_timeout"
-
-const authorizePayment = async (token: PaymentToken): Promise<unknown> => {
-  if (token === "tok_timeout") {
-    throw new Error("Provider unreachable")
-  }
-  if (token === "tok_declined") {
-    return { authorizationId: "pauth_123", status: "declined" }
-  }
-  return { authorizationId: "pauth_123", status: "authorized" }
-}
-
-const processPayment = (token: PaymentToken) =>
-  Effect.gen(function* () {
-    const response = yield* Effect.tryPromise({
-      try: () => authorizePayment(token),
-      catch: (cause) => new NetworkError({ cause }),
-    })
-
-    if (!isAuthorization(response)) {
-      return yield* new ParseError({})
-    }
-
-    if (response.status === "declined") {
-      return yield* new PaymentDeclinedError()
-    }
-
-    return response
-  })
-
-const captured = new Set(["pauth_123"])
-
-const capturePayment = (
-  authorization: Authorization,
-): Effect.Effect<Authorization> =>
-  Effect.gen(function* () {
-    if (captured.has(authorization.authorizationId)) {
-      return yield* Effect.die(
-        new DoubleCaptureError({
-          authorizationId: authorization.authorizationId,
-        }),
-      )
-    }
-    captured.add(authorization.authorizationId)
-    return authorization
-  })
-
-const captureFlow = (token: PaymentToken) =>
-  Effect.gen(function* () {
-    const authorization = yield* processPayment(token)
-    return yield* capturePayment(authorization)
-  })
-
-// ---cut---
-//    ┌─ Effect.Effect<string | Authorization, never>
-//    |
-//    ▼
-const outcome = captureFlow("tok_visa").pipe(
-  Effect.catchTags({
-    NetworkError: () => Effect.succeed("handled NetworkError"),
-    ParseError: () => Effect.succeed("handled ParseError"),
-    PaymentDeclinedError: () => Effect.succeed("handled PaymentDeclinedError"),
-  }),
-  Effect.catchDefect(() => Effect.succeed("the defect passed through")),
-)
-
-await Effect.runPromise(outcome) // => "the defect passed through"
-```
-
-The table handles every tag, and the `Error` type parameter is `never`. The
-defect still terminated the program: typed recovery never catches defects, so
-only `Effect.catchDefect` saw it.
-
-### Guard impossible data
-
-Whether a bug throws an error or you write it with `Effect.die`, it lands in
-the same place: the `Cause`. `Effect.die` is the deliberate form, for the
-invariants you check on purpose.
-
-The third invariant is a status the type says cannot exist. The problem:
-
-1. `authorization.status` has two members: `"authorized"` and `"declined"`.
-1. Data from an untyped source, a parsed JSON body or a third-party response,
-   can carry anything at runtime.
-1. A `default` arm in the switch guards the difference. The type says the arm
-   is unreachable, the runtime says otherwise.
-
-The arm casts before reading the status, because TypeScript considers it dead
-code. `Effect.die` is what it returns: an exception you raise on purpose. It
-never enters the `Error` type parameter.
-
-```ts twoslash import.meta.vitest
-import { Effect } from "effect"
-
-interface Authorization {
-  readonly authorizationId: string
-  readonly status: "authorized" | "declined"
-}
-
-//    ┌─ Effect.Effect<string>: no `Error` type parameter
-//    ▼
-const label = (authorization: Authorization) => {
-  switch (authorization.status) {
-    case "authorized":
-      return Effect.succeed(`charged ${authorization.authorizationId}`)
-    case "declined":
-      return Effect.succeed("no charge")
-    default: {
-      // Unreachable per the type. Here for the runtime anyway.
-      const status = (authorization as { status: string }).status
-      return Effect.die(new Error(`Impossible status: ${status}`))
-    }
-  }
-}
-
-// The data lies: a status the type says cannot exist.
-const forged = {
-  authorizationId: "pauth_123",
-  status: "refunded",
-} as unknown as Authorization
-
-const outcome = label(forged).pipe(
-  Effect.catchDefect((defect) =>
-    defect instanceof Error
-      ? Effect.succeed(`terminated with a defect: ${defect.message}`)
-      : Effect.die(defect),
-  ),
-)
-
-await Effect.runPromise(outcome) // => "terminated with a defect: Impossible status: refunded"
-```
-
-The forged value stands in for the untyped source. The status is `"refunded"`:
-the type says it cannot exist, and the runtime says otherwise. The impossible
-arm fired, and `Effect.die` terminated with a descriptive `Error`. Pass an
-`Error` with a useful message: it is the report `catchDefect` receives.
-
 ### Stop tracking failures no caller can respond to
 
 `Effect.orDie` is a modeling decision: no caller can do anything with these
@@ -1058,56 +888,6 @@ alerts whoever owns it. Nothing here is recoverable in place, so nothing is
 left to track. The failure crossed the boundary as a defect:
 `Effect.runPromise` rejected with the `PaymentDeclinedError` itself.
 
-### Promote one failure to a defect
-
-`Effect.orDie` promotes every failure. Promote one failure when it is
-a bug, not an expected outcome. Suppose the provider is your own service, and
-its contract guarantees the response shape. `ParseError` stops being a failure
-a caller can respond to: it is a broken promise. To promote one while keeping
-the rest tracked, catch the tag and die with it:
-
-```ts twoslash showLineNumbers=false
-import { Effect, Data } from "effect"
-
-interface Authorization {
-  readonly authorizationId: string
-  readonly status: "authorized" | "declined"
-}
-
-class NetworkError extends Data.TaggedError("NetworkError")<{
-  readonly cause?: unknown
-}> {}
-class PaymentDeclinedError extends Data.TaggedError("PaymentDeclinedError") {}
-class ParseError extends Data.TaggedError("ParseError")<{
-  readonly cause?: unknown
-}> {}
-
-// Tutorial fixture: sandbox tokens make provider results reproducible.
-type PaymentToken = "tok_visa" | "tok_declined" | "tok_timeout"
-
-declare const processPayment: (
-  token: PaymentToken,
-) => Effect.Effect<
-  Authorization,
-  PaymentDeclinedError | NetworkError | ParseError
->
-
-//    ┌─ Effect.Effect<Authorization, PaymentDeclinedError | NetworkError>
-//    |  `ParseError` is now a defect; `PaymentDeclinedError` and `NetworkError` stay tracked
-//    ▼
-const strictProcessPayment = (token: PaymentToken) =>
-  processPayment(token).pipe(
-    Effect.catchTag("ParseError", (error) => Effect.die(error)),
-  )
-```
-
-Keep `PaymentDeclinedError` and `NetworkError` as failures:
-
-- A decline has a message for the customer.
-- A timeout has a retry.
-
-Promoting those would make them invisible to every caller.
-
 ### Recover at the boundary
 
 A defect is a bug. A handler cannot fix it. But the boundary decides what