@dojocho/effect-ts 0.0.1

package/katas/029-http-client/SENSEI.md

@@ -0,0 +1,59 @@
+# SENSEI — 029 HTTP Client
+
+## Briefing
+
+### Goal
+
+Learn to define an `HttpClient` service abstraction for testability, parse HTTP responses with `Schema`, and use `Effect.retry` with a `Schedule` for transient failures.
+
+### Tasks
+
+1. Implement `fetchUser` -- use `HttpClient.get` to fetch from a URL, then decode the response with `UserSchema`.
+2. Implement `fetchUserWithRetry` -- fetch a user with retry logic (up to 2 retries).
+
+## Prerequisites
+
+- **011 Services and Context** — `Context.Tag`, `provideService`
+- **014 Schema Basics** — `Schema`, encode/decode
+- **016 Retry and Schedule** — `Schedule`, retry policies
+
+## Skills
+
+Invoke `effect-patterns-making-http-requests` before teaching this kata.
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Effect.provideService` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `fetchUser succeeds with valid response` | `HttpClient.get` + `Schema.decodeUnknown` | Fetch from `/user/1`, decode to `{ id: 1, name: "Alice" }` |
+| `fetchUser fails with invalid url` | Error propagation | Fetch from `/user/999` fails — HttpClient returns `"not found"` |
+| `fetchUserWithRetry succeeds with valid response` | `fetchUser` + `Effect.retry` | Same success case, but wrapped with retry logic |
+| `fetchUserWithRetry retries on failure` | `Effect.retry` + `Schedule.recurs` | Flaky client fails twice, succeeds on third — verifies retry behavior |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "The `HttpClient` is defined as a `Context.Tag`. Why is this useful for testing — why not just use `fetch` directly?"
+- "After getting a response from the HTTP client, how do you know the data has the right shape? What if the response is missing a field?"
+- "For `fetchUserWithRetry`, should you re-implement the HTTP call, or can you build on top of `fetchUser`?"
+
+### Common pitfalls
+
+1. **Schema.decodeUnknown returns an Effect with ParseError** — the function signature expects errors as `string`, so you may need `Effect.mapError` to convert the ParseError to a string. Ask: "What error type does `Schema.decodeUnknown(UserSchema)` produce? What does your function's type signature expect?"
+2. **fetchUserWithRetry wraps fetchUser, not the raw HTTP call** — avoid duplicating the fetch+decode logic. Simply call `fetchUser(url)` and pipe it through `Effect.retry`. Ask: "You already have `fetchUser` working. How can you add retry to it without rewriting it?"
+3. **Accessing the HttpClient service** — inside `Effect.gen`, use `yield* HttpClient` to get the service implementation. Students sometimes try to call `HttpClient.get` directly as a static method. Ask: "How do you access a service inside a generator?"
+4. **Schedule.recurs argument** — `Schedule.recurs(2)` means 2 retries (3 total attempts). Students may confuse retries with total attempts.
+5. **Error mapping for Schema** — if `Schema.decodeUnknown` gives you a `ParseError` but you need a `string`, use `Effect.mapError` to convert it.
+
+## On Completion
+
+### Insight
+
+The HttpClient is a service — making it injectable means tests don't need a real HTTP server. Schema validates the response shape at the boundary. Retry handles transient failures. This pattern — **service abstraction + schema validation + retry** — is the standard approach for HTTP in Effect applications. Notice how each concern is separate and composable: you didn't write retry logic inside your HTTP call, and you didn't hardcode the HTTP implementation.
+
+### Bridge
+
+Kata 030 is the **capstone** — bringing together services, layers, tagged errors, Option, Schema, and everything else you've learned into a complete mini-application. It's the final kata in the dojo.

package/katas/029-http-client/solution.test.ts

@@ -0,0 +1,49 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { HttpClient, fetchUser, fetchUserWithRetry } from "@/katas/029-http-client/solution.js";
+
+const TestClient = {
+  get: (url: string) => {
+    if (url === "/user/1") return Effect.succeed({ id: 1, name: "Alice" });
+    return Effect.fail("not found");
+  },
+};
+
+describe("029 — HTTP Client", () => {
+  it("fetchUser succeeds with valid response", () => {
+    const result = Effect.runSync(
+      Effect.provideService(fetchUser("/user/1"), HttpClient, TestClient),
+    );
+    expect(result).toEqual({ id: 1, name: "Alice" });
+  });
+
+  it("fetchUser fails with invalid url", () => {
+    const exit = Effect.runSyncExit(
+      Effect.provideService(fetchUser("/user/999"), HttpClient, TestClient),
+    );
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("fetchUserWithRetry succeeds with valid response", () => {
+    const result = Effect.runSync(
+      Effect.provideService(fetchUserWithRetry("/user/1"), HttpClient, TestClient),
+    );
+    expect(result).toEqual({ id: 1, name: "Alice" });
+  });
+
+  it("fetchUserWithRetry retries on failure", () => {
+    let attempts = 0;
+    const FlakyClient = {
+      get: (_url: string) => {
+        attempts++;
+        if (attempts <= 2) return Effect.fail("network error");
+        return Effect.succeed({ id: 1, name: "Alice" });
+      },
+    };
+    const result = Effect.runSync(
+      Effect.provideService(fetchUserWithRetry("/user/1"), HttpClient, FlakyClient),
+    );
+    expect(result).toEqual({ id: 1, name: "Alice" });
+    expect(attempts).toBe(3);
+  });
+});

package/katas/029-http-client/solution.ts

@@ -0,0 +1,24 @@
+import { Context, Effect, Schema } from "effect";
+
+// Abstract HTTP client service for testability
+export class HttpClient extends Context.Tag("HttpClient")<
+  HttpClient,
+  { readonly get: (url: string) => Effect.Effect<unknown, string> }
+>() {}
+
+export const UserSchema = Schema.Struct({
+  id: Schema.Number,
+  name: Schema.String,
+});
+
+export type User = typeof UserSchema.Type;
+
+/** Use HttpClient.get to fetch from the url, then decode with UserSchema */
+export const fetchUser = (url: string): Effect.Effect<User, string, HttpClient> => {
+  throw new Error("Not implemented");
+};
+
+/** Fetch user with retry (up to 2 retries) */
+export const fetchUserWithRetry = (url: string): Effect.Effect<User, string, HttpClient> => {
+  throw new Error("Not implemented");
+};

package/katas/030-capstone/SENSEI.md

@@ -0,0 +1,63 @@
+# SENSEI — 030 Capstone
+
+## Briefing
+
+### Goal
+
+Bring it all together -- services, layers, tagged errors, Option, Schema, and testing in one mini-application.
+
+### Tasks
+
+1. Implement `findProduct` -- look up a product by id. If found, return it wrapped in `Option.some`. If not found, catch the error and return `Option.none`.
+2. Implement `getValidatedProduct` -- validate that price meets `minPrice`, then look up the product by id. Fail with `ValidationError` if price is invalid, or `NotFoundError` if the product is not found.
+3. Implement `formatExpensiveProducts` -- get all products, filter those with price above `minPrice`, and format each as `"{name}: ${price}"`.
+4. The `TestProductRepo` is provided in the test file — study it to understand the service interface.
+
+## Prerequisites
+
+- **All prior katas** — this capstone draws on every area: basics, error handling, services, layers, Option, Schema, and composition.
+
+## Skills
+
+Invoke `effect-patterns-building-apis` before teaching this kata.
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, `Effect.provide`, `Option.isSome`, `Option.isNone`, and `Exit.isFailure` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `findProduct(1) returns Some(Widget)` | Service access + `Option.some` | Repo lookup wraps found product in `Some` |
+| `findProduct(99) returns None` | `Effect.catchTag` + `Option.none` | Repo throws `NotFoundError`, caught and converted to `None` |
+| `getValidatedProduct(1, 5) succeeds` | Service + validation | Widget (price 9.99) passes `minPrice: 5` check |
+| `getValidatedProduct(1, 20) fails with ValidationError` | `Effect.fail` + `ValidationError` | Widget (price 9.99) fails `minPrice: 20` check |
+| `getValidatedProduct(99, 0) fails with NotFoundError` | Error propagation | Product not found, `NotFoundError` propagates |
+| `formatExpensiveProducts(5) returns Widget and Gadget` | Service + filter + format | `findAll` -> filter `price > 5` -> format as `"Name: $price"` |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You need to call `repo.findById(id)` which might fail with `NotFoundError`. But `findProduct` should return `Option<Product>`, not fail. How do you convert a failure into a `None`?"
+- "For `getValidatedProduct`, there are two things that can go wrong: invalid price and product not found. Which should you check first? Does the order matter?"
+- "How do you create a `Layer` that provides a `ProductRepo` implementation? What methods does the service interface require?"
+- "For `formatExpensiveProducts`, the return type has `never` in the error channel. What does that tell you about error handling?"
+
+### Common pitfalls
+
+1. **findProduct must catch NotFoundError and return None** — the return type is `Effect<Option<Product>, never, ProductRepo>` with `never` in the error position. This means the function must not fail. Use `Effect.catchTag("NotFoundError", () => Effect.succeed(Option.none()))` to convert the error. Ask: "What does `never` in the error type mean for your implementation?"
+2. **getValidatedProduct validation order** — find the product first, then check if its price meets `minPrice`. The test for id=1 minPrice=20 expects `ValidationError`, meaning the product was found (price 9.99) but failed validation. Ask: "Do you validate the price before or after looking up the product?"
+3. **TestProductRepo needs both findById and findAll** — `findById` should find a product by id or fail with `NotFoundError`. `findAll` should return all three products. Students may forget one method. Ask: "What does the `ProductRepo` interface require?"
+4. **Format string must match exactly** — the test expects `"Widget: $9.99"` format. Students may use different formatting. Ask: "Check the test assertion — what exact string format does it expect?"
+5. **Layer.succeed vs Layer.effect** — since the repo methods return Effects but don't need external state, `Layer.succeed(ProductRepo, { ... })` works. The service value is the object with `findById` and `findAll` methods.
+6. **Start with `TestProductRepo`** — define the three products first, implement `findById` (find in array or fail with NotFoundError) and `findAll` (return all). Everything else depends on having the repo.
+
+## On Completion
+
+### Insight
+
+This capstone proves you can build real applications with Effect: **services** for architecture, **layers** for composition and testing, **tagged errors** for type-safe failure handling, **Option** for optional results, **Schema** for domain modeling. Every pattern you learned works together naturally — services are injected, errors are caught and transformed, optional values are wrapped, and layers make it all testable. The `never` error type in `findProduct` and `formatExpensiveProducts` is a compile-time guarantee that these functions handle all their errors internally.
+
+### Bridge
+
+Congratulations — you've completed the core curriculum! You've gone from `Effect.succeed` to building a fully-typed, testable, service-oriented application. The patterns you practiced — composition, typed errors, dependency injection, streams, observability, and resource management — are the foundation of production Effect-TS code. Katas 031-040 cover advanced topics like configuration, causes and defects, pattern matching, coordination primitives, caching, metrics, managed runtimes, and request batching.

package/katas/030-capstone/solution.test.ts

@@ -0,0 +1,67 @@
+import { Effect, Exit, Layer, Option } from "effect";
+import { describe, expect, it } from "vitest";
+import {
+  findProduct,
+  getValidatedProduct,
+  formatExpensiveProducts,
+  ProductRepo,
+  NotFoundError,
+} from "@/katas/030-capstone/solution.js";
+
+const testProducts = [
+  { id: 1, name: "Widget", price: 9.99 },
+  { id: 2, name: "Gadget", price: 24.99 },
+  { id: 3, name: "Gizmo", price: 4.99 },
+];
+
+const TestProductRepo = Layer.succeed(ProductRepo, {
+  findById: (id: number) => {
+    const product = testProducts.find((p) => p.id === id);
+    if (product) return Effect.succeed(product);
+    return Effect.fail(new NotFoundError({ id }));
+  },
+  findAll: () => Effect.succeed(testProducts),
+});
+
+const run = <A, E>(effect: Effect.Effect<A, E, any>) =>
+  Effect.runSync(Effect.provide(effect, TestProductRepo));
+
+const runExit = <A, E>(effect: Effect.Effect<A, E, any>) =>
+  Effect.runSyncExit(Effect.provide(effect, TestProductRepo));
+
+describe("030 — Capstone", () => {
+  it("findProduct(1) returns Some(Widget)", () => {
+    const result = run(findProduct(1));
+    expect(Option.isSome(result)).toBe(true);
+    if (Option.isSome(result)) {
+      expect(result.value.name).toBe("Widget");
+    }
+  });
+
+  it("findProduct(99) returns None", () => {
+    const result = run(findProduct(99));
+    expect(Option.isNone(result)).toBe(true);
+  });
+
+  it("getValidatedProduct(1, 5) succeeds", () => {
+    const result = run(getValidatedProduct(1, 5));
+    expect(result.name).toBe("Widget");
+  });
+
+  it("getValidatedProduct(1, 20) fails with ValidationError", () => {
+    const exit = runExit(getValidatedProduct(1, 20));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("getValidatedProduct(99, 0) fails with NotFoundError", () => {
+    const exit = runExit(getValidatedProduct(99, 0));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("formatExpensiveProducts(5) returns Widget and Gadget", () => {
+    const result = run(formatExpensiveProducts(5));
+    expect(result).toContain("Widget: $9.99");
+    expect(result).toContain("Gadget: $24.99");
+    expect(result).not.toContain("Gizmo");
+  });
+});

package/katas/030-capstone/solution.ts

@@ -0,0 +1,55 @@
+import { Context, Data, Effect, Option, Schema } from "effect";
+
+// === Domain Types ===
+
+export class NotFoundError extends Data.TaggedError("NotFoundError")<{
+  readonly id: number;
+}> {}
+
+export class ValidationError extends Data.TaggedError("ValidationError")<{
+  readonly message: string;
+}> {}
+
+export const ProductSchema = Schema.Struct({
+  id: Schema.Number,
+  name: Schema.String,
+  price: Schema.Number,
+});
+export type Product = typeof ProductSchema.Type;
+
+// === Services ===
+
+export class ProductRepo extends Context.Tag("ProductRepo")<
+  ProductRepo,
+  {
+    readonly findById: (id: number) => Effect.Effect<Product, NotFoundError>;
+    readonly findAll: () => Effect.Effect<Product[]>;
+  }
+>() {}
+
+// === Tasks ===
+
+/** Look up a product by id. If found, return it. If not, return Option.none. */
+export const findProduct = (
+  id: number,
+): Effect.Effect<Option.Option<Product>, never, ProductRepo> => {
+  throw new Error("Not implemented");
+};
+
+/** Validate that price > 0, then look up product by id.
+ * If price invalid: fail with ValidationError
+ * If product not found: fail with NotFoundError */
+export const getValidatedProduct = (
+  id: number,
+  minPrice: number,
+): Effect.Effect<Product, NotFoundError | ValidationError, ProductRepo> => {
+  throw new Error("Not implemented");
+};
+
+/** Get all products, filter those with price > minPrice,
+ * format each as "{name}: ${price}", return as array */
+export const formatExpensiveProducts = (
+  minPrice: number,
+): Effect.Effect<string[], never, ProductRepo> => {
+  throw new Error("Not implemented");
+};

package/katas/031-config-and-environment/SENSEI.md

@@ -0,0 +1,77 @@
+# SENSEI — 031 Config and Environment
+
+## Briefing
+
+### Goal
+
+Read typed configuration values from a provider using Effect's `Config` module, with defaults and composition.
+
+### Tasks
+
+1. Implement `getAppName` — read a string config value for the key `"APP_NAME"`
+2. Implement `getPort` — read a numeric config value for `"PORT"`, falling back to `3000` if missing
+3. Implement `getAppConfig` — combine both reads and return `{ name, port }`
+
+### Hints
+
+```ts
+import { Config, ConfigProvider, Effect, Layer } from "effect";
+
+// Read a string config
+const name = Config.string("MY_KEY");
+
+// Read a number config with a default
+const port = Config.withDefault(Config.number("PORT"), 3000);
+
+// Config values are Effects — use them in generators
+const program = Effect.gen(function* () {
+  const n = yield* Config.string("NAME");
+  const p = yield* Config.withDefault(Config.number("PORT"), 8080);
+  return { n, p };
+});
+
+// Provide a config in tests
+const provider = ConfigProvider.fromMap(new Map([["KEY", "value"]]));
+const withProvider = Effect.provide(program, Layer.setConfigProvider(provider));
+```
+
+## Prerequisites
+
+- **011 Services and Context** — Dependency injection with `Context`
+- **012 Layers** — Building and providing layers
+- **005 Pipe Composition** — Composing effects with `pipe`
+
+## Test Map
+
+> **Note**: `ConfigProvider.fromMap`, `Layer.setConfigProvider`, and `Effect.runSync` appear only in tests. Never attribute them to the user's learning.
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `getAppName reads APP_NAME config` | `Config.string` | Reading a string config value by key |
+| `getPort reads PORT config as number` | `Config.number` | Reading a numeric config value |
+| `getPort falls back to 3000 when PORT is missing` | `Config.withDefault` | Default value when config key is absent |
+| `getAppConfig returns both name and port` | Composing configs | Combining multiple config reads into a single object |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "Config values in Effect are described declaratively, not read imperatively. What does `Config.string('APP_NAME')` return — a string, or something else?"
+- "Why does Effect treat configuration as a dependency rather than reading `process.env` directly? What does this make easier?"
+- "When you compose two config reads in a generator, what happens if one of them fails? How does this compare to manually checking `process.env.PORT || 3000`?"
+
+### Common pitfalls
+
+1. **Treating Config as a raw value instead of an Effect** — `Config.string("APP_NAME")` returns an `Effect`, not a string. You must `yield*` it in a generator or use it in a pipeline. Ask: "What type does `Config.string` return?"
+2. **Applying `withDefault` to the wrong thing** — `Config.withDefault` wraps a `Config`, not an `Effect`. It should be `Config.withDefault(Config.number("PORT"), 3000)`, not applied after yielding. Ask: "At what level does the default apply — to the config description or to the effect result?"
+3. **Forgetting that Config.number parses strings** — The config provider stores strings. `Config.number` handles the parsing for you. Don't try to manually parse with `parseInt`.
+
+## On Completion
+
+### Insight
+
+Effect's Config module separates _what_ configuration your program needs from _where_ it comes from. By declaring configs as typed descriptors (`Config.string`, `Config.number`), your program becomes testable and portable — you can swap `process.env` for a `Map` in tests without changing any application code. `Config.withDefault` is not just a convenience; it documents which values are optional and what the fallback behavior is, making configuration self-describing.
+
+### Bridge
+
+Now that you can read configuration, what happens when things go wrong in unexpected ways — not just typed errors, but crashes and defects? Kata 032 explores `Cause` and defects, the deeper error model beneath `Effect.fail`.

package/katas/031-config-and-environment/solution.test.ts

@@ -0,0 +1,38 @@
+import { Config, ConfigProvider, Effect, Layer } from "effect";
+import { describe, expect, it } from "vitest";
+import { getAppName, getPort, getAppConfig } from "@/katas/031-config-and-environment/solution.js";
+
+const TestConfig = ConfigProvider.fromMap(
+  new Map([
+    ["APP_NAME", "my-app"],
+    ["PORT", "8080"],
+  ]),
+);
+
+const withConfig = <A, E>(effect: Effect.Effect<A, E>) =>
+  Effect.provide(effect, Layer.setConfigProvider(TestConfig));
+
+describe("031 — Config and Environment", () => {
+  it("getAppName reads APP_NAME config", () => {
+    const result = Effect.runSync(withConfig(getAppName));
+    expect(result).toBe("my-app");
+  });
+
+  it("getPort reads PORT config as number", () => {
+    const result = Effect.runSync(withConfig(getPort));
+    expect(result).toBe(8080);
+  });
+
+  it("getPort falls back to 3000 when PORT is missing", () => {
+    const emptyConfig = ConfigProvider.fromMap(new Map([["APP_NAME", "app"]]));
+    const result = Effect.runSync(
+      Effect.provide(getPort, Layer.setConfigProvider(emptyConfig)),
+    );
+    expect(result).toBe(3000);
+  });
+
+  it("getAppConfig returns both name and port", () => {
+    const result = Effect.runSync(withConfig(getAppConfig));
+    expect(result).toEqual({ name: "my-app", port: 8080 });
+  });
+});

package/katas/031-config-and-environment/solution.ts

@@ -0,0 +1,11 @@
+import { Config, Effect } from "effect";
+
+/** Read the APP_NAME config as a string */
+export const getAppName: Effect.Effect<string> = Effect.fail("Not implemented") as any;
+
+/** Read the PORT config as a number, defaulting to 3000 */
+export const getPort: Effect.Effect<number> = Effect.fail("Not implemented") as any;
+
+/** Read both APP_NAME and PORT into an object { name, port } */
+export const getAppConfig: Effect.Effect<{ name: string; port: number }> =
+  Effect.fail("Not implemented") as any;

package/katas/032-cause-and-defects/SENSEI.md

@@ -0,0 +1,90 @@
+# SENSEI — 032 Cause and Defects
+
+## Briefing
+
+### Goal
+
+Understand Effect's two-tier error model: expected failures (`Effect.fail`) vs unexpected defects (`Effect.die`), and the tools to inspect and recover from each.
+
+### Tasks
+
+1. Implement `boom` — an effect that dies with the string `"boom"`
+2. Implement `catchDefect(effect)` — catch any defect; if it's an `Error`, return its `.message`; otherwise return `"unknown defect"`. Normal successes pass through unchanged.
+3. Implement `sandboxed(effect)` — use `Effect.sandbox` to expose the full `Cause`, then map the cause back to a string error
+4. Implement `safeDivide(n)` — die if `n < 0`, fail with `"zero"` if `n === 0`, succeed with `n` otherwise
+
+### Hints
+
+```ts
+import { Cause, Effect } from "effect";
+
+// Die with a defect (unrecoverable by default)
+const defect = Effect.die("something unexpected");
+
+// Catch defects
+const recovered = Effect.catchAllDefect(myEffect, (defect) => {
+  if (defect instanceof Error) return Effect.succeed(defect.message);
+  return Effect.succeed("unknown defect");
+});
+
+// Sandbox exposes the full Cause
+const exposed = Effect.sandbox(myEffect);
+// exposed has error type Cause<OriginalError>
+
+// Catch the sandboxed cause and extract failures
+const handled = exposed.pipe(
+  Effect.catchAll((cause) => {
+    const failures = Cause.failures(cause); // Chunk of original errors
+    return Effect.fail(Array.from(failures)[0] ?? "unknown");
+  }),
+);
+```
+
+## Prerequisites
+
+- **006 Handle Errors** — `Effect.catchAll`, `Effect.catchTag`
+- **007 Tagged Errors** — `Data.TaggedError` patterns
+- **008 Error Patterns** — `Effect.mapError`, `Effect.catchSome`
+
+## Skills
+
+Invoke `effect-patterns-error-handling` before teaching this kata.
+
+## Test Map
+
+> **Note**: `Effect.runSyncExit`, `Exit.isFailure`, and `Cause.isDie` appear only in tests. Never attribute them to the user's learning.
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `boom dies with 'boom'` | `Effect.die` | Creating a defect (not a typed failure) |
+| `catchDefect recovers from a die` | `Effect.catchAllDefect` | Recovering from a string defect |
+| `catchDefect recovers from an Error defect` | `Effect.catchAllDefect` | Extracting `.message` from Error defects |
+| `catchDefect passes through normal values` | `Effect.catchAllDefect` | Defect recovery does not interfere with success |
+| `sandboxed exposes cause on failure` | `Effect.sandbox` | Converting typed errors to `Cause` for full inspection |
+| `safeDivide succeeds with positive numbers` | `Effect.succeed` | Happy path branching |
+| `safeDivide fails with 'zero' for 0` | `Effect.fail` | Expected failure branch |
+| `safeDivide dies for negative numbers` | `Effect.die` | Defect branch for truly invalid input |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What is the difference between `Effect.fail('error')` and `Effect.die('error')`? If both stop execution, why have two mechanisms?"
+- "`Effect.catchAll` handles typed failures. What happens if you use `catchAll` on an effect that dies — does it catch the defect?"
+- "When would you intentionally use `Effect.die` in your own code? What kind of errors deserve to be defects rather than typed failures?"
+
+### Common pitfalls
+
+1. **Using `Effect.fail` instead of `Effect.die` for `boom`** — `fail` creates a typed, recoverable error. `die` creates an unrecoverable defect. The test checks for `Cause.isDie`. Ask: "What does the test expect to find in the Cause — a `Fail` or a `Die`?"
+2. **Forgetting that `catchAllDefect` receives the raw defect, not a Cause** — The callback gets whatever value was passed to `Effect.die`. It might be a string, an Error, or anything. You need to check its type. Ask: "If someone calls `Effect.die(42)`, what type does your defect handler receive?"
+3. **Confusing `sandbox` with `catchAllDefect`** — `sandbox` changes the error channel to `Cause<E>`, exposing the full error model. `catchAllDefect` specifically intercepts defects. For `sandboxed`, you need to work with the Cause type. Ask: "After `Effect.sandbox`, what is the new error type of the effect?"
+
+## On Completion
+
+### Insight
+
+Effect's error model has two layers by design. Typed failures (`Effect.fail`) represent expected, recoverable business errors — they appear in the type signature and must be handled. Defects (`Effect.die`) represent bugs, assertion violations, or truly unexpected crashes — they propagate silently through `catchAll` and only surface when you explicitly use `catchAllDefect` or `sandbox`. This separation keeps your typed error channel meaningful: if the types say the only error is `NotFoundError`, you can trust that. Defects are for things that "should never happen" — and when they do, `Cause` gives you the full forensic picture including stack traces, parallel failures, and interruption.
+
+### Bridge
+
+You now understand Effect's complete error hierarchy. Kata 033 shifts to a different kind of safety: exhaustive pattern matching with `Match`, ensuring every case is handled at compile time rather than runtime.

package/katas/032-cause-and-defects/solution.test.ts

@@ -0,0 +1,50 @@
+import { Cause, Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { boom, catchDefect, sandboxed, safeDivide } from "@/katas/032-cause-and-defects/solution.js";
+
+describe("032 — Cause and Defects", () => {
+  it("boom dies with 'boom'", () => {
+    const exit = Effect.runSyncExit(boom);
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      expect(Cause.isDie(exit.cause)).toBe(true);
+    }
+  });
+
+  it("catchDefect recovers from a die", () => {
+    const result = Effect.runSync(catchDefect(Effect.die("crash")));
+    expect(result).toBe("crash");
+  });
+
+  it("catchDefect recovers from an Error defect", () => {
+    const result = Effect.runSync(catchDefect(Effect.die(new Error("oops"))));
+    expect(result).toBe("oops");
+  });
+
+  it("catchDefect passes through normal values", () => {
+    const result = Effect.runSync(catchDefect(Effect.succeed(42)));
+    expect(result).toBe(42);
+  });
+
+  it("sandboxed exposes cause on failure", () => {
+    const exit = Effect.runSyncExit(sandboxed(Effect.fail("bad")));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("safeDivide succeeds with positive numbers", () => {
+    expect(Effect.runSync(safeDivide(5))).toBe(5);
+  });
+
+  it("safeDivide fails with 'zero' for 0", () => {
+    const exit = Effect.runSyncExit(safeDivide(0));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("safeDivide dies for negative numbers", () => {
+    const exit = Effect.runSyncExit(safeDivide(-1));
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      expect(Cause.isDie(exit.cause)).toBe(true);
+    }
+  });
+});

package/katas/032-cause-and-defects/solution.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+
+/** Create an effect that dies with "boom" */
+export const boom: Effect.Effect<never> = Effect.fail("Not implemented") as any;
+
+/** Catch defects from an effect, returning the defect message as a string */
+export const catchDefect = <A>(
+  effect: Effect.Effect<A>,
+): Effect.Effect<A | string> => {
+  throw new Error("Not implemented");
+};
+
+/** Sandbox an effect to expose its full Cause */
+export const sandboxed = <A, E>(
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, unknown> => {
+  throw new Error("Not implemented");
+};
+
+/** If n < 0, die with "negative". If n === 0, fail with "zero". Otherwise succeed. */
+export const safeDivide = (n: number): Effect.Effect<number, string> => {
+  throw new Error("Not implemented");
+};