@dojocho/effect-ts 0.0.1

package/katas/013-testing-effects/SENSEI.md

@@ -0,0 +1,88 @@
+# SENSEI — 013 Testing Effects
+
+## Briefing
+
+### Goal
+
+Learn how to write testable Effect programs using service doubles.
+
+### Tasks
+
+1. Implement `getUser(id)` — use `UserRepo` service to find a user by id and return `"User: {name}"`
+2. Implement `getUserSafe(id)` — use `UserRepo` to find a user, recovering from errors with `"Unknown"`
+
+### Hints
+
+```ts
+import { Context, Effect } from "effect";
+
+// Access a service inside Effect.gen
+const program = Effect.gen(function* () {
+  const repo = yield* MyRepo;
+  const value = yield* repo.findById(1);
+  return value;
+});
+
+// Recover from errors
+const safe = Effect.gen(function* () {
+  const repo = yield* MyRepo;
+  const value = yield* repo.findById(1).pipe(
+    Effect.catchAll(() => Effect.succeed("fallback")),
+  );
+  return value;
+});
+
+// Provide a test double
+const result = Effect.runSync(
+  Effect.provideService(program, MyRepo, {
+    findById: (id) => Effect.succeed("test"),
+  }),
+);
+```
+
+## Prerequisites
+
+- **011 Services and Context** — `Context.Tag`, `yield*` on a tag, `yield*` on a service method
+- **012 Layers** — `Layer.succeed`, composing services
+
+## Skills
+
+Invoke `effect-patterns-testing` before teaching this kata. This is the first kata in the Testing area.
+
+> **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 |
+|------|---------|----------|
+| `getUser(1) returns 'User: Alice'` | `yield* UserRepo` + `yield* repo.findById` | Service access and method call — success path |
+| `getUser(99) fails with 'not found'` | Error propagation | Service method failure passes through exactly |
+| `getUserSafe(1) returns 'User: Alice'` | `Effect.gen` + service access | Success path with error recovery in scope |
+| `getUserSafe(99) returns 'User: Unknown'` | `Effect.catchAll` | Recovering from service errors with a fallback |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "Look at the test file — `TestUserRepo` returns `Effect.succeed('Alice')` for id 1 and `Effect.fail('not found')` for anything else. Your code never sees this implementation. What does that tell you about how services work?"
+- "What's the difference between `getUser` and `getUserSafe`? Both access the same service — but one lets errors through and the other catches them."
+- "`catchAll` receives the error value. Do you need to inspect it here, or just replace it with a fallback?"
+- "If `findById` fails, what should `getUserSafe` return instead?"
+
+### Common pitfalls
+
+1. **Forgetting to format the result** — `findById` returns a name like `"Alice"`, but the test expects `"User: Alice"`. Ask: "What does the test check for? Is it just the name?"
+2. **Using try/catch instead of catchAll** — inside `Effect.gen`, errors short-circuit the generator. You can't catch them with JavaScript `try/catch`. Use `Effect.catchAll` on the whole effect or use `yield*` with a caught effect. Ask: "How does error handling work in Effect vs regular JavaScript?"
+3. **Applying catchAll too narrowly** — `catchAll` should wrap the entire pipeline for `getUserSafe`, not just the `findById` call. The simplest approach: write `getUser(id)` first, then pipe it through `catchAll` for the safe version.
+4. **Returning the wrong fallback** — `getUserSafe(99)` should return `"User: Unknown"`, not just `"Unknown"`. The `"User: "` prefix must be in the fallback too.
+5. **Reuse `getUser` in `getUserSafe`** — call `getUser(id)` (already written) then pipe it through `catchAll` to handle the error case with `Effect.succeed("User: Unknown")`.
+
+## On Completion
+
+### Insight
+
+Because services are accessed through the R channel, tests can swap implementations without changing the program. No mocking frameworks needed — just provide a different implementation. The test file created a `TestUserRepo` with predictable behavior, and your code worked against it without modification. This is the payoff of dependency injection via Effect: the program describes WHAT it needs, tests control HOW those needs are met.
+
+### Bridge
+
+Services, Layers, and testing give you the architecture for real programs. But real programs also need to validate data. Kata 014 introduces **Schema** — Effect's approach to parsing and validation that gives you runtime checks AND TypeScript types from a single definition.

package/katas/013-testing-effects/solution.test.ts

@@ -0,0 +1,41 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { UserRepo, getUser, getUserSafe } from "@/katas/013-testing-effects/solution.js";
+
+// Test double
+const TestUserRepo = {
+  findById: (id: number) =>
+    id === 1
+      ? Effect.succeed("Alice")
+      : Effect.fail("not found"),
+};
+
+describe("013 — Testing Effects", () => {
+  it("getUser(1) returns 'User: Alice'", () => {
+    const result = Effect.runSync(
+      Effect.provideService(getUser(1), UserRepo, TestUserRepo),
+    );
+    expect(result).toBe("User: Alice");
+  });
+
+  it("getUser(99) fails with 'not found'", () => {
+    const exit = Effect.runSyncExit(
+      Effect.provideService(getUser(99), UserRepo, TestUserRepo),
+    );
+    expect(exit).toEqual(Exit.fail("not found"));
+  });
+
+  it("getUserSafe(1) returns 'User: Alice'", () => {
+    const result = Effect.runSync(
+      Effect.provideService(getUserSafe(1), UserRepo, TestUserRepo),
+    );
+    expect(result).toBe("User: Alice");
+  });
+
+  it("getUserSafe(99) returns 'User: Unknown'", () => {
+    const result = Effect.runSync(
+      Effect.provideService(getUserSafe(99), UserRepo, TestUserRepo),
+    );
+    expect(result).toBe("User: Unknown");
+  });
+});

package/katas/013-testing-effects/solution.ts

@@ -0,0 +1,20 @@
+import { Context, Effect } from "effect";
+
+export class UserRepo extends Context.Tag("UserRepo")<
+  UserRepo,
+  {
+    readonly findById: (id: number) => Effect.Effect<string, string>;
+  }
+>() {}
+
+/** Use UserRepo service to find user by id and return "User: {name}" */
+export const getUser = (id: number) =>
+  Effect.gen(function* () {
+    throw new Error("Not implemented");
+  });
+
+/** Use UserRepo to find user, recovering from errors with "Unknown" */
+export const getUserSafe = (id: number) =>
+  Effect.gen(function* () {
+    throw new Error("Not implemented");
+  });

package/katas/014-schema-basics/SENSEI.md

@@ -0,0 +1,81 @@
+# SENSEI — 014 Schema Basics
+
+## Briefing
+
+### Goal
+
+Learn how to validate and parse data using Effect Schema.
+
+### Tasks
+
+1. Implement `parseUser` — parse unknown input into a `User` (name: string, age: number)
+2. Implement `parseStrictUser` — parse with stricter validation: name must be non-empty, age must be >= 0
+
+### Hints
+
+```ts
+import { Effect, Schema } from "effect";
+
+// Define a schema
+const PersonSchema = Schema.Struct({
+  name: Schema.String,
+  age: Schema.Number,
+});
+
+// Parse unknown data (returns Effect)
+const parse = Schema.decodeUnknown(PersonSchema);
+const result = Effect.runSync(parse({ name: "Alice", age: 30 }));
+
+// Refined schemas
+const NonEmpty = Schema.NonEmptyString;
+const Positive = Schema.Number.pipe(Schema.positive());
+```
+
+## Prerequisites
+
+- **007 Tagged Errors** — `Data.TaggedError`, domain errors
+- **009 Option Type** — `Option`, `some`, `none`, `match`
+
+## Skills
+
+Invoke `effect-patterns-domain-modeling` before teaching this kata. This is the first kata in the Domain Modeling area.
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Exit.isFailure` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `parseUser succeeds with valid input` | `Schema.decodeUnknown` | Parsing a valid object against UserSchema |
+| `parseUser fails with missing field` | `Schema.decodeUnknown` | Schema rejects incomplete input |
+| `parseUser fails with wrong type` | `Schema.decodeUnknown` | Schema rejects mistyped fields |
+| `parseStrictUser succeeds with valid input` | Refined schema + `Schema.decodeUnknown` | Stricter schema still accepts valid data |
+| `parseStrictUser fails with empty name` | `Schema.NonEmptyString` | Refinement rejects empty strings |
+| `parseStrictUser fails with negative age` | `Schema.positive()` or `Schema.filter` | Refinement rejects negative numbers |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You have a `UserSchema` already defined with `Schema.Struct`. How do you use it to parse an `unknown` value into a `User`?"
+- "`Schema.decodeUnknown` returns an Effect, not a plain value. Why would parsing be an Effect?"
+- "For `StrictUserSchema`, the basic `Schema.String` accepts empty strings. How can you make it stricter?"
+- "What's the difference between `Schema.Number` and `Schema.Number.pipe(Schema.positive())`? What does the refinement add?"
+
+### Common pitfalls
+
+1. **Calling Schema.decodeUnknown wrong** — the signature is `Schema.decodeUnknown(MySchema)(input)`. It's curried: first pass the schema, then the value. Ask: "What does `Schema.decodeUnknown(UserSchema)` return — a parser function or a result?"
+2. **Modifying UserSchema instead of creating StrictUserSchema** — `UserSchema` should stay as-is (the first three tests use it). `StrictUserSchema` is a separate, stricter schema. Nudge: "Keep `UserSchema` untouched — build `StrictUserSchema` with refined field types."
+3. **Wrong refinement for age** — the test rejects negative age (`-1`). Students might use `Schema.positive()` which also rejects zero, but the test for `parseStrictUser` with `{ name: "Alice", age: 30 }` only needs `>= 0`. Check whether `Schema.nonNegative()` or `Schema.filter` with `(n) => n >= 0` is needed. Look at what the tests actually check.
+4. **Forgetting the pipe for refinements** — `Schema.NonEmptyString` is a standalone schema, but for number refinements you typically use `Schema.Number.pipe(Schema.positive())`. Students may try `Schema.positive(Schema.Number)` which isn't the API.
+5. **`parseUser` is a one-liner** — `Schema.decodeUnknown(UserSchema)(input)` is all you need. The curried form takes the schema first, then the input.
+
+## On Completion
+
+### Insight
+
+`Schema.decodeUnknown` returns an Effect — parsing IS an effect because it can fail. The schema defines the shape AND the validation rules in one place. This is different from validation libraries that only check at runtime — Schema also gives you the TypeScript type via `typeof UserSchema.Type`. One definition, two purposes: runtime validation and compile-time type safety.
+
+### Bridge
+
+You've seen Schema for data validation. Kata 015 brings together everything from the Domain Modeling area: `Data.TaggedError` for typed validation errors, `Option` for optional fields, and `Effect.gen` for composing validators. It's the capstone of domain modeling in Effect.

package/katas/014-schema-basics/solution.test.ts

@@ -0,0 +1,35 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { parseUser, parseStrictUser } from "@/katas/014-schema-basics/solution.js";
+
+describe("014 — Schema Basics", () => {
+  it("parseUser succeeds with valid input", () => {
+    const result = Effect.runSync(parseUser({ name: "Alice", age: 30 }));
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
+
+  it("parseUser fails with missing field", () => {
+    const exit = Effect.runSyncExit(parseUser({ name: "Alice" }));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("parseUser fails with wrong type", () => {
+    const exit = Effect.runSyncExit(parseUser({ name: 123, age: "thirty" }));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("parseStrictUser succeeds with valid input", () => {
+    const result = Effect.runSync(parseStrictUser({ name: "Alice", age: 30 }));
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
+
+  it("parseStrictUser fails with empty name", () => {
+    const exit = Effect.runSyncExit(parseStrictUser({ name: "", age: 30 }));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("parseStrictUser fails with negative age", () => {
+    const exit = Effect.runSyncExit(parseStrictUser({ name: "Alice", age: -1 }));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+});

package/katas/014-schema-basics/solution.ts

@@ -0,0 +1,25 @@
+import { Effect, ParseResult, Schema } from "effect";
+
+/** Define a Schema for User with fields: name (string), age (number) */
+export const UserSchema = Schema.Struct({
+  name: Schema.String,
+  age: Schema.Number,
+});
+
+export type User = typeof UserSchema.Type;
+
+/** Parse unknown input into a User, returning Effect<User, ParseError> */
+export const parseUser = (input: unknown): Effect.Effect<User, ParseResult.ParseError> => {
+  throw new Error("Not implemented");
+};
+
+/** Parse and validate: name must be non-empty, age must be >= 0
+ * Use Schema.NonEmptyString and Schema.filter or Schema.positive */
+export const StrictUserSchema = Schema.Struct({
+  name: Schema.String,
+  age: Schema.Number,
+});
+
+export const parseStrictUser = (input: unknown): Effect.Effect<typeof StrictUserSchema.Type, ParseResult.ParseError> => {
+  throw new Error("Not implemented");
+};

package/katas/015-domain-modeling/SENSEI.md

@@ -0,0 +1,85 @@
+# SENSEI — 015 Domain Modeling
+
+## Briefing
+
+### Goal
+
+Combine TaggedError, Option, Schema, and Effect.gen to build a complete domain model.
+
+### Tasks
+
+1. Implement `validateEmail` — check that email contains "@", fail with `InvalidEmail` otherwise
+2. Implement `validateAge` — check that age is 0-150, fail with `InvalidAge` otherwise
+3. Implement `createUser` — validate email and age, then construct a `User` with `nickname` as `Option.none()`
+4. Implement `formatUser` — format as `"{name} <{email}>"` with optional `" aka {nickname}"` if present
+
+### Hints
+
+```ts
+import { Data, Effect, Option } from "effect";
+
+// TaggedError for domain errors
+class MyError extends Data.TaggedError("MyError")<{
+  readonly reason: string;
+}> {}
+
+// Conditional failure
+const validate = (x: number) =>
+  x > 0 ? Effect.succeed(x) : Effect.fail(new MyError({ reason: "too small" }));
+
+// Option matching
+const greet = (nickname: Option.Option<string>) =>
+  Option.match(nickname, {
+    onNone: () => "",
+    onSome: (n) => ` aka ${n}`,
+  });
+```
+
+## Prerequisites
+
+- **007 Tagged Errors** — `Data.TaggedError`, domain errors
+- **009 Option Type** — `Option`, `some`, `none`, `match`
+- **014 Schema Basics** — `Schema`, `decodeUnknown`
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Exit.isFailure` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `validateEmail succeeds with valid email` | `Effect.succeed` | Email containing `@` passes validation |
+| `validateEmail fails without @` | `Effect.fail` + `InvalidEmail` | Missing `@` produces a tagged error |
+| `validateAge succeeds with valid age` | `Effect.succeed` | Age in 0-150 range passes validation |
+| `validateAge fails with negative` | `Effect.fail` + `InvalidAge` | Negative age produces a tagged error |
+| `createUser succeeds with valid input` | `Effect.gen` + `yield*` | Composing validators with generator |
+| `createUser fails with invalid email` | Error propagation | Validator failure short-circuits the generator |
+| `formatUser without nickname` | `Option.match` onNone | Formatting when nickname is `Option.none()` |
+| `formatUser with nickname` | `Option.match` onSome | Formatting when nickname is `Option.some("Al")` |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You've used `Data.TaggedError` in kata 007. Here you have TWO error classes. What does the union type `InvalidEmail | InvalidAge` tell the caller?"
+- "For `validateEmail`, what's the simplest way to check if a string contains `@`? What should you return in each case?"
+- "In `createUser`, you call `validateEmail` and `validateAge` — both return Effects that might fail. What happens in `Effect.gen` if the first one fails?"
+- "`formatUser` is a pure function, not an Effect. How does `Option.match` let you handle the nickname being present or absent?"
+
+### Common pitfalls
+
+1. **Constructing TaggedErrors wrong** — use `new InvalidEmail({ email })`, not `InvalidEmail({ email })`. The `Data.TaggedError` classes need `new`. Ask: "How do you create an instance of a class in JavaScript?"
+2. **Forgetting Option.none() in createUser** — the `User` interface requires `nickname: Option.Option<string>`. When creating a user, set it to `Option.none()`. Students may use `undefined` or `null`. Ask: "What type does the `nickname` field expect?"
+3. **Using if/else in createUser instead of Effect.gen** — students might try to validate everything in a single conditional. Nudge: "You already have `validateEmail` and `validateAge` as separate Effects. How does `yield*` let you compose them?"
+4. **Option.match syntax** — the API is `Option.match(option, { onNone: () => ..., onSome: (value) => ... })`. Students may forget the object shape or try to pattern match differently. Check the Effect docs for the exact signature.
+5. **formatUser output format** — the tests expect `"Alice <a@b.com>"` without nickname and `"Alice <a@b.com> aka Al"` with nickname. Watch the exact spacing and format.
+6. **Compose validators with `Effect.gen`** — use `yield* validateEmail(email)`, then `yield* validateAge(age)`, then return the User object with `Option.none()` for nickname. If the first validator fails, the generator short-circuits.
+
+## On Completion
+
+### Insight
+
+This kata shows how Effect's building blocks compose into a real domain model: `Data.TaggedError` for typed validation errors, `Option` for optional fields, `Effect.gen` for sequencing validators, and union error types that accumulate automatically. The compiler tracks every possible error — `createUser` returns `Effect<User, InvalidEmail | InvalidAge>`, telling every caller exactly what can go wrong. No more `unknown` errors, no more forgotten error cases.
+
+### Bridge
+
+Domain Modeling is complete. You now have the tools to model data, validate it, and handle errors with full type safety. Next up: **scheduling and resilience**. Kata 016 introduces `Schedule`, retry policies, and `Effect.retry` — teaching your programs to recover from transient failures automatically.

package/katas/015-domain-modeling/solution.test.ts

@@ -0,0 +1,46 @@
+import { Effect, Exit, Option } from "effect";
+import { describe, expect, it } from "vitest";
+import { validateEmail, validateAge, createUser, formatUser } from "@/katas/015-domain-modeling/solution.js";
+
+describe("015 — Domain Modeling", () => {
+  it("validateEmail succeeds with valid email", () => {
+    expect(Effect.runSync(validateEmail("a@b.com"))).toBe("a@b.com");
+  });
+
+  it("validateEmail fails without @", () => {
+    const exit = Effect.runSyncExit(validateEmail("invalid"));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("validateAge succeeds with valid age", () => {
+    expect(Effect.runSync(validateAge(25))).toBe(25);
+  });
+
+  it("validateAge fails with negative", () => {
+    const exit = Effect.runSyncExit(validateAge(-1));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("createUser succeeds with valid input", () => {
+    const user = Effect.runSync(createUser("Alice", "a@b.com", 30));
+    expect(user.name).toBe("Alice");
+    expect(user.email).toBe("a@b.com");
+    expect(user.age).toBe(30);
+    expect(user.nickname).toEqual(Option.none());
+  });
+
+  it("createUser fails with invalid email", () => {
+    const exit = Effect.runSyncExit(createUser("Alice", "bad", 30));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("formatUser without nickname", () => {
+    const user = { name: "Alice", email: "a@b.com", age: 30, nickname: Option.none() as Option.Option<string> };
+    expect(formatUser(user)).toBe("Alice <a@b.com>");
+  });
+
+  it("formatUser with nickname", () => {
+    const user = { name: "Alice", email: "a@b.com", age: 30, nickname: Option.some("Al") };
+    expect(formatUser(user)).toBe("Alice <a@b.com> aka Al");
+  });
+});

package/katas/015-domain-modeling/solution.ts

@@ -0,0 +1,42 @@
+import { Data, Effect, Option, Schema } from "effect";
+
+// Domain types
+export class InvalidEmail extends Data.TaggedError("InvalidEmail")<{
+  readonly email: string;
+}> {}
+
+export class InvalidAge extends Data.TaggedError("InvalidAge")<{
+  readonly age: number;
+}> {}
+
+export interface User {
+  readonly name: string;
+  readonly email: string;
+  readonly age: number;
+  readonly nickname: Option.Option<string>;
+}
+
+/** Validate email contains "@", fail with InvalidEmail otherwise */
+export const validateEmail = (email: string): Effect.Effect<string, InvalidEmail> => {
+  throw new Error("Not implemented");
+};
+
+/** Validate age is 0-150, fail with InvalidAge otherwise */
+export const validateAge = (age: number): Effect.Effect<number, InvalidAge> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.gen to validate email and age, then construct a User
+ * nickname should be Option.none() */
+export const createUser = (
+  name: string,
+  email: string,
+  age: number,
+): Effect.Effect<User, InvalidEmail | InvalidAge> => {
+  throw new Error("Not implemented");
+};
+
+/** Format user as "{name} <{email}>" with optional " aka {nickname}" if present */
+export const formatUser = (user: User): string => {
+  throw new Error("Not implemented");
+};

package/katas/016-retry-and-schedule/SENSEI.md

@@ -0,0 +1,72 @@
+# SENSEI — 016 Retry and Schedule
+
+## Briefing
+
+### Goal
+
+Learn to retry failing effects and repeat successful ones using Schedules.
+
+### Tasks
+
+1. Implement `retryThreeTimes(effect)` — retry the given effect up to 3 times using `Schedule.recurs(3)`
+2. Implement `flakyEffect(failCount)` — create an effect that fails `failCount` times then succeeds with `"done"` (use a `Ref` to track attempts)
+3. Implement `repeatCollect(effect)` — repeat the effect 3 times using `Schedule.recurs(3)` and collect results
+
+### Hints
+
+```ts
+import { Effect, Schedule } from "effect";
+
+// Retry up to 3 times
+const retried = Effect.retry(myEffect, Schedule.recurs(3));
+
+// Repeat and collect results
+const repeated = Effect.repeat(myEffect, Schedule.recurs(3));
+```
+
+## Prerequisites
+
+- **006 Handle Errors** — `Effect.fail`, `catchAll`
+- **008 Error Patterns** — `catchTag`, error recovery patterns
+
+## Skills
+
+Invoke `effect-patterns-scheduling` before teaching this kata.
+
+> **Note**: `Effect.runSync`, `Effect.runSyncExit`, and `Effect.runPromise` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `retryThreeTimes succeeds on first try` | `Effect.retry` | Pass-through when the effect already succeeds |
+| `flakyEffect that fails 2 times then succeeds` | `Ref` + `Effect.retry` | Ref counting attempts across retries |
+| `flakyEffect that fails 5 times still fails after 3 retries` | `Effect.retry` + `Schedule.recurs` | Retry exhaustion — schedule allows only 3 retries |
+| `repeatCollect collects repeated values` | `Effect.repeat` | Repeating a successful effect and collecting results |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What's the difference between retrying and repeating? When does each apply?"
+- "`Schedule.recurs(3)` is a value, not a function call that does something. What does that mean for how you use it?"
+- "For `flakyEffect`, each retry re-runs the effect from scratch. How can you track how many times it's been called across retries?"
+- "What does `Effect.repeat` return — the last value, or all of them? How would you collect all results?"
+
+### Common pitfalls
+
+1. **`flakyEffect` needs a Ref to track state across retries** — since each retry re-runs the effect, you can't use a local variable. The Ref persists across calls. Ask: "If the effect is re-run on each retry, where does the attempt count live?"
+2. **`repeatCollect` needs to collect results** — `Effect.repeat` with `Schedule.recurs(3)` runs the effect 1 + 3 = 4 times. Look at the schedule's return type or use a Ref to accumulate. Ask: "How many times does the effect run with `recurs(3)`? The initial run plus 3 repeats."
+3. **Confusing retry and repeat** — retry applies to failing effects (retries on failure), repeat applies to succeeding effects (repeats on success). Ask: "Does `retryThreeTimes` retry successes or failures?"
+4. **Off-by-one with `Schedule.recurs`** — `recurs(3)` means 3 retries (not 3 total attempts). So the effect runs up to 4 times total. Check the test expectations carefully.
+5. **`flakyEffect` state tracking** — use `Effect.gen` to create a Ref, then on each call increment it and decide whether to fail or succeed based on the count vs `failCount`.
+
+## On Completion
+
+### Insight
+
+Schedules are composable descriptions of retry/repeat policies. `Schedule.recurs(3)` is a value, not imperative code. You can combine schedules with `Schedule.union` (either), `Schedule.intersect` (both), and pipe through transforms. This declarative approach makes complex retry logic readable — you describe *what* the policy is, not *how* to implement the loop.
+
+### Bridge
+
+Now that you can retry and repeat individual effects, the next step is running multiple effects **at the same time**. Kata 017 introduces `Effect.all` and `Effect.forEach` with concurrency options — parallelism as a configuration, not a rewrite.

package/katas/016-retry-and-schedule/solution.test.ts

@@ -0,0 +1,26 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { retryThreeTimes, flakyEffect, repeatCollect } from "@/katas/016-retry-and-schedule/solution.js";
+
+describe("016 — Retry and Schedule", () => {
+  it("retryThreeTimes succeeds on first try", () => {
+    expect(Effect.runSync(retryThreeTimes(Effect.succeed("ok")))).toBe("ok");
+  });
+
+  it("flakyEffect that fails 2 times then succeeds", () => {
+    const result = Effect.runSync(retryThreeTimes(flakyEffect(2)));
+    expect(result).toBe("done");
+  });
+
+  it("flakyEffect that fails 5 times still fails after 3 retries", () => {
+    const exit = Effect.runSyncExit(retryThreeTimes(flakyEffect(5)));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("repeatCollect collects repeated values", async () => {
+    let count = 0;
+    const effect = Effect.sync(() => ++count);
+    const result = await Effect.runPromise(repeatCollect(effect));
+    expect(result.length).toBeGreaterThanOrEqual(4); // initial + 3 repeats
+  });
+});

package/katas/016-retry-and-schedule/solution.ts

@@ -0,0 +1,23 @@
+import { Effect, Schedule, Ref } from "effect";
+
+/** Retry the given effect up to 3 times using Schedule.recurs(3) */
+export const retryThreeTimes = <A, E>(
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, E> => {
+  throw new Error("Not implemented");
+};
+
+/** Create an effect that fails n times then succeeds with "done".
+ * Use a Ref to track attempt count. On each call, increment ref;
+ * if count <= failCount, fail with "attempt {count}"; else succeed with "done". */
+export const flakyEffect = (failCount: number): Effect.Effect<string, string> =>
+  Effect.gen(function* () {
+    throw new Error("Not implemented");
+  });
+
+/** Repeat the effect 3 times using Schedule.recurs(3) and collect the results */
+export const repeatCollect = (
+  effect: Effect.Effect<number>,
+): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};

package/katas/017-parallel-effects/SENSEI.md

@@ -0,0 +1,70 @@
+# SENSEI — 017 Parallel Effects
+
+## Briefing
+
+### Goal
+
+Run multiple effects concurrently and control parallelism.
+
+### Tasks
+
+1. Implement `fetchAll(effects)` — run all effects in parallel and collect results
+2. Implement `processWithLimit(items, fn)` — apply `fn` to each item with at most 3 concurrent operations
+
+### Hints
+
+```ts
+import { Effect } from "effect";
+
+// Run all in parallel
+const results = Effect.all(effects, { concurrency: "unbounded" });
+
+// Bounded concurrency
+const processed = Effect.forEach(items, fn, { concurrency: 3 });
+```
+
+## Prerequisites
+
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`
+- **005 Pipe Composition** — `pipe`, composing effects
+
+## Skills
+
+Invoke `effect-patterns-concurrency` before teaching this kata.
+
+> **Note**: `Effect.runSync` and `Effect.runSyncExit` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `fetchAll runs effects and collects results` | `Effect.all` | Running effects in parallel and collecting results |
+| `fetchAll fails if any effect fails` | `Effect.all` | Error propagation — one failure fails the whole batch |
+| `processWithLimit applies function to each item` | `Effect.forEach` | Applying a function to each item with bounded concurrency |
+| `processWithLimit fails if any processing fails` | `Effect.forEach` | Error propagation through forEach |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You already know `Effect.all` from sequential use. What single option turns it parallel?"
+- "What's the difference between `concurrency: 'unbounded'` and `concurrency: 3`? When would you choose each?"
+- "`Effect.forEach` looks like `Array.map` but effectful. What extra capability does the concurrency option give you?"
+- "If one effect in `fetchAll` fails, what happens to the others?"
+
+### Common pitfalls
+
+1. **Forgetting the concurrency option** — without `{ concurrency: "unbounded" }`, `Effect.all` runs sequentially. The tests pass either way for correctness, but the kata is about parallelism. Ask: "Is your code actually running in parallel, or just sequentially?"
+2. **Using `Effect.all` instead of `Effect.forEach` for `processWithLimit`** — `Effect.forEach` takes a collection and a function, while `Effect.all` takes pre-built effects. Ask: "You have items and a function. Which combinator takes both?"
+3. **Wrong concurrency value for `processWithLimit`** — the function should limit to 3 concurrent operations. Check: "What does `{ concurrency: 3 }` mean exactly?"
+4. **`processWithLimit` is effectful map** — think of it as `Array.map` but each mapping produces an Effect. `Effect.forEach` takes items and a function, unlike `Effect.all` which takes pre-built effects.
+
+## On Completion
+
+### Insight
+
+`Effect.all` and `Effect.forEach` are the same functions you'd use sequentially — the `{ concurrency }` option is the only difference. Effect makes parallelism a configuration change, not a rewrite. You don't need `Promise.all` or manual thread management. Sequential, bounded parallel, or unbounded parallel — it's one option away.
+
+### Bridge
+
+Running effects in parallel is powerful, but sometimes you want **competition** rather than **cooperation** — the first to finish wins. Kata 018 introduces `Effect.race` and timeout patterns for when speed matters more than completeness.