@dojocho/effect-ts 0.0.1

package/katas/017-parallel-effects/solution.test.ts

@@ -0,0 +1,33 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { fetchAll, processWithLimit } from "@/katas/017-parallel-effects/solution.js";
+
+describe("017 — Parallel Effects", () => {
+  it("fetchAll runs effects and collects results", () => {
+    const effects = [Effect.succeed(1), Effect.succeed(2), Effect.succeed(3)];
+    const result = Effect.runSync(fetchAll(effects));
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  it("fetchAll fails if any effect fails", () => {
+    const effects = [Effect.succeed(1), Effect.fail("oops"), Effect.succeed(3)];
+    const exit = Effect.runSyncExit(fetchAll(effects));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+
+  it("processWithLimit applies function to each item", () => {
+    const result = Effect.runSync(
+      processWithLimit([1, 2, 3], (n) => Effect.succeed(n * 2)),
+    );
+    expect(result).toEqual([2, 4, 6]);
+  });
+
+  it("processWithLimit fails if any processing fails", () => {
+    const exit = Effect.runSyncExit(
+      processWithLimit([1, 2, 3], (n) =>
+        n === 2 ? Effect.fail("bad") : Effect.succeed(n),
+      ),
+    );
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+});

package/katas/017-parallel-effects/solution.ts

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+
+/** Run all effects in parallel using Effect.all with { concurrency: "unbounded" } */
+export const fetchAll = <A, E>(
+  effects: Effect.Effect<A, E>[],
+): Effect.Effect<A[], E> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.forEach with { concurrency: 3 } to process items
+ * Apply the given function to each item with at most 3 concurrent operations */
+export const processWithLimit = <A, B, E>(
+  items: A[],
+  fn: (a: A) => Effect.Effect<B, E>,
+): Effect.Effect<B[], E> => {
+  throw new Error("Not implemented");
+};

package/katas/018-race-and-timeout/SENSEI.md

@@ -0,0 +1,75 @@
+# SENSEI — 018 Race and Timeout
+
+## Briefing
+
+### Goal
+
+Race effects against each other and apply timeouts with fallbacks.
+
+### Tasks
+
+1. Implement `raceTwo(a, b)` — race two effects, returning whichever succeeds first
+2. Implement `withTimeout(effect, duration)` — add a timeout that fails with `"timeout"` if exceeded
+3. Implement `withTimeoutFallback(effect, duration, fallback)` — return a fallback value if the effect times out
+
+### Hints
+
+```ts
+import { Effect, Duration } from "effect";
+
+// Race two effects
+const winner = Effect.race(effectA, effectB);
+
+// Timeout with failure
+const timed = Effect.timeoutFail(myEffect, {
+  duration: "5 seconds",
+  onTimeout: () => "timeout",
+});
+
+// Timeout with fallback
+const safe = myEffect.pipe(
+  Effect.timeout("5 seconds"),
+  Effect.map(Option.getOrElse(() => fallback)),
+);
+```
+
+## Prerequisites
+
+- **017 Parallel Effects** — `Effect.all`, `Effect.forEach`, concurrency options
+
+> **Note**: `Effect.runSync`, `Effect.runPromise`, and `Effect.delay` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `raceTwo returns the faster result` | `Effect.race` | First-to-finish semantics |
+| `withTimeout succeeds within time` | `Effect.timeoutFail` | Timeout with custom error — success path |
+| `withTimeout fails when effect exceeds duration` | `Effect.timeoutFail` | Timeout with custom error — failure path |
+| `withTimeoutFallback returns fallback on slow effect` | `Effect.timeout` + fallback | Timeout producing a fallback value |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What happens to the loser in a race? Does it keep running?"
+- "For `withTimeout`, you need to fail with a specific string on timeout. Which timeout variant lets you specify a custom error?"
+- "For `withTimeoutFallback`, `Effect.timeout` doesn't fail — it wraps the result in `Option`. How do you handle the `None` case?"
+- "How is racing different from running two effects in parallel with `Effect.all`?"
+
+### Common pitfalls
+
+1. **`withTimeout` — using `Effect.timeout` instead of `Effect.timeoutFail`** — `Effect.timeout` wraps the result in Option and never fails on timeout. `Effect.timeoutFail` lets you specify a custom error. Ask: "Does this function need to fail on timeout, or return a fallback?"
+2. **`withTimeoutFallback` — not handling the Option** — `Effect.timeout` changes the success type from `A` to `Option<A>`. You need to unwrap it with `Option.getOrElse` (via `Effect.map`) or another approach. Ask: "What's the type of the effect after applying `Effect.timeout`?"
+3. **Duration import** — the functions take `Duration.DurationInput`, which accepts strings like `"1 second"`. Students don't need to construct Duration objects manually.
+4. **`withTimeout` uses `Effect.timeoutFail`** — it takes the effect, a duration, and a function that creates the error. Don't confuse with `Effect.timeout` which wraps in Option instead of failing.
+
+## On Completion
+
+### Insight
+
+Racing and timeout are composition patterns — you wrap existing effects with timing constraints. The original effect doesn't change; you add behavior around it. This is the power of Effect's compositional model: `race`, `timeout`, `timeoutFail` are all decorators that modify when and how an effect completes, without touching its internal logic.
+
+### Bridge
+
+You've seen concurrency through parallel execution (017) and racing (018). But concurrent code often needs **shared state**. Kata 019 introduces `Ref` — Effect's atomic mutable reference that makes shared state safe without locks or race conditions.

package/katas/018-race-and-timeout/solution.test.ts

@@ -0,0 +1,30 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { raceTwo, withTimeout, withTimeoutFallback } from "@/katas/018-race-and-timeout/solution.js";
+
+describe("018 — Race and Timeout", () => {
+  it("raceTwo returns the faster result", () => {
+    const fast = Effect.succeed("fast");
+    const slow = Effect.succeed("slow").pipe(Effect.delay("1 second"));
+    const result = Effect.runSync(raceTwo(fast, slow));
+    expect(result).toBe("fast");
+  });
+
+  it("withTimeout succeeds within time", () => {
+    const fast = Effect.succeed("ok");
+    const result = Effect.runSync(withTimeout(fast, "1 second"));
+    expect(result).toBe("ok");
+  });
+
+  it("withTimeoutFallback returns fallback on slow effect", async () => {
+    const slow = Effect.succeed("slow").pipe(Effect.delay("1 second"));
+    const result = await Effect.runPromise(withTimeoutFallback(slow, "10 millis", "default"));
+    expect(result).toBe("default");
+  });
+
+  it("withTimeout fails when effect exceeds duration", async () => {
+    const slow = Effect.succeed("slow").pipe(Effect.delay("1 second"));
+    const exit = await Effect.runPromiseExit(withTimeout(slow, "10 millis"));
+    expect(Exit.isFailure(exit)).toBe(true);
+  });
+});

package/katas/018-race-and-timeout/solution.ts

@@ -0,0 +1,27 @@
+import { Effect, Duration } from "effect";
+
+/** Race two effects, returning whichever succeeds first */
+export const raceTwo = <A, E>(
+  a: Effect.Effect<A, E>,
+  b: Effect.Effect<A, E>,
+): Effect.Effect<A, E> => {
+  throw new Error("Not implemented");
+};
+
+/** Add a timeout to the effect. If it doesn't complete within the duration,
+ * fail with "timeout" */
+export const withTimeout = <A>(
+  effect: Effect.Effect<A, string>,
+  duration: Duration.DurationInput,
+): Effect.Effect<A, string> => {
+  throw new Error("Not implemented");
+};
+
+/** Try the effect with a timeout; if it times out, return the fallback value */
+export const withTimeoutFallback = <A>(
+  effect: Effect.Effect<A>,
+  duration: Duration.DurationInput,
+  fallback: A,
+): Effect.Effect<A> => {
+  throw new Error("Not implemented");
+};

package/katas/019-ref-and-state/SENSEI.md

@@ -0,0 +1,72 @@
+# SENSEI — 019 Ref and State
+
+## Briefing
+
+### Goal
+
+Manage mutable state safely within effects using Ref.
+
+### Tasks
+
+1. Implement `counter(n)` — create a Ref with initial value 0, increment it `n` times, return the final value
+2. Implement `accumulate(items)` — create a Ref of `string[]`, push each item, return the accumulated array
+3. Implement `getAndIncrement(ref)` — use `Ref.modify` to atomically return the current value and increment by 1
+
+### Hints
+
+```ts
+import { Effect, Ref } from "effect";
+
+// Create and use a Ref
+const program = Effect.gen(function* () {
+  const ref = yield* Ref.make(0);
+  yield* Ref.update(ref, (n) => n + 1);
+  return yield* Ref.get(ref);
+});
+
+// Atomic read-and-update
+const old = yield* Ref.modify(ref, (n) => [n, n + 1]);
+```
+
+## Prerequisites
+
+- **017 Parallel Effects** — `Effect.all`, concurrency
+- **018 Race and Timeout** — `Effect.race`, `Effect.timeout`
+
+> **Note**: `Effect.runSync` appears only in tests. Never attribute it to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `counter(5) returns 5` | `Ref.make` + `Ref.update` + `Ref.get` | Incrementing a Ref n times in a loop |
+| `counter(0) returns 0` | `Ref.make` + `Ref.get` | Edge case — no increments |
+| `accumulate collects all items` | `Ref.make([])` + `Ref.update` | Pushing items into a Ref array |
+| `getAndIncrement returns current then increments` | `Ref.modify` | Atomic read-then-update in one operation |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "Why use a Ref instead of a regular `let` variable? What could go wrong with `let` in concurrent code?"
+- "For `counter`, you need to increment n times. How do you loop in the Effect world?"
+- "`Ref.modify` does a read AND an update atomically. What does 'atomically' mean here? Why does it matter?"
+- "What's the difference between `Ref.update` (which returns void) and `Ref.modify` (which returns a value)?"
+
+### Common pitfalls
+
+1. **`counter` needs a loop** — you can't just set the Ref to n. Use `Effect.forEach` over a range (like `Array.from({ length: n }, (_, i) => i)`) or `Effect.repeatN`. Ask: "How do you express 'do this n times' in Effect?"
+2. **`Ref.modify` tuple order** — `Ref.modify` takes a function that returns `[returnValue, newState]`. The return value comes first, the new state second. Getting this backwards means `getAndIncrement` returns the wrong value. Ask: "What does the tuple `[current, current + 1]` mean — which part is returned, which is stored?"
+3. **Using `Ref.get` + `Ref.update` instead of `Ref.modify`** — for `getAndIncrement`, a separate get-then-update is not atomic. Between the read and the write, another fiber could modify the Ref. Ask: "What if two fibers call `getAndIncrement` at the same time with separate get and update?"
+4. **Forgetting `yield*` on Ref operations** — `Ref.make`, `Ref.get`, `Ref.update`, and `Ref.modify` all return Effects. They must be yielded inside a generator. Ask: "What type does `Ref.make(0)` return?"
+5. **`Ref.modify` returns `[returnValue, newState]`** — you need to return the current value AND set the new one in a single step. The function signature is `(current) => [valueToReturn, newState]`.
+
+## On Completion
+
+### Insight
+
+Ref provides atomic state updates — no locks, no race conditions. `Ref.modify` is the fundamental operation: it atomically reads the current value AND computes the new value in one step. This is safe even with concurrent access. Unlike mutable variables, Ref operations are Effects — they compose, they're explicit about mutation, and the runtime guarantees atomicity.
+
+### Bridge
+
+You now have shared state with Ref and parallelism with `Effect.all`. But sometimes you need finer control over concurrent work — starting it, waiting for it, or cancelling it. Kata 020 introduces **Fibers**, Effect's lightweight unit of concurrency: `fork`, `join`, and `interrupt`.

package/katas/019-ref-and-state/solution.test.ts

@@ -0,0 +1,29 @@
+import { Effect, Ref } from "effect";
+import { describe, expect, it } from "vitest";
+import { counter, accumulate, getAndIncrement } from "@/katas/019-ref-and-state/solution.js";
+
+describe("019 — Ref and State", () => {
+  it("counter(5) returns 5", () => {
+    expect(Effect.runSync(counter(5))).toBe(5);
+  });
+
+  it("counter(0) returns 0", () => {
+    expect(Effect.runSync(counter(0))).toBe(0);
+  });
+
+  it("accumulate collects all items", () => {
+    const result = Effect.runSync(accumulate(["a", "b", "c"]));
+    expect(result).toEqual(["a", "b", "c"]);
+  });
+
+  it("getAndIncrement returns current then increments", () => {
+    const program = Effect.gen(function* () {
+      const ref = yield* Ref.make(0);
+      const a = yield* getAndIncrement(ref);
+      const b = yield* getAndIncrement(ref);
+      const c = yield* getAndIncrement(ref);
+      return [a, b, c];
+    });
+    expect(Effect.runSync(program)).toEqual([0, 1, 2]);
+  });
+});

package/katas/019-ref-and-state/solution.ts

@@ -0,0 +1,16 @@
+import { Effect, Ref } from "effect";
+
+/** Create a Ref with initial value 0, increment it n times, return final value */
+export const counter = (n: number): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};
+
+/** Create a Ref<string[]>, push each item from the list, return the accumulated array */
+export const accumulate = (items: string[]): Effect.Effect<string[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Ref.modify to atomically read and update: return current value and increment by 1 */
+export const getAndIncrement = (ref: Ref.Ref<number>): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};

package/katas/020-fibers/SENSEI.md

@@ -0,0 +1,80 @@
+# SENSEI — 020 Fibers
+
+## Briefing
+
+### Goal
+
+Work with fibers for lightweight concurrency, forking, joining, and interruption.
+
+### Tasks
+
+1. Implement `forkAndJoin(effect)` — fork the effect into a fiber, then join it to get the result
+2. Implement `forkBoth(a, b)` — fork two effects, join both, return results as a tuple
+3. Implement `forkAndInterrupt(effect)` — fork the effect, interrupt the fiber, return `"interrupted"`
+
+### Hints
+
+```ts
+import { Effect, Fiber } from "effect";
+
+// Fork and join
+const program = Effect.gen(function* () {
+  const fiber = yield* Effect.fork(myEffect);
+  const result = yield* Fiber.join(fiber);
+  return result;
+});
+
+// Interrupt a fiber
+const interrupted = Effect.gen(function* () {
+  const fiber = yield* Effect.fork(longRunning);
+  yield* Fiber.interrupt(fiber);
+  return "interrupted";
+});
+```
+
+## Prerequisites
+
+- **017 Parallel Effects** — `Effect.all`, concurrency
+- **018 Race and Timeout** — `Effect.race`, `Effect.timeout`
+- **019 Ref and State** — `Ref`, shared state
+
+## Skills
+
+Invoke `effect-patterns-concurrency-getting-started` before teaching this kata.
+
+> **Note**: `Effect.runPromise` and `Effect.delay` appear only in tests. Never attribute them to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `forkAndJoin returns the effect result` | `Effect.fork` + `Fiber.join` | Fork then join to get the result |
+| `forkBoth returns both results` | `Effect.fork` + `Fiber.join` | Forking two fibers and joining both |
+| `forkAndInterrupt returns 'interrupted'` | `Effect.fork` + `Fiber.interrupt` | Forking then cancelling a fiber |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What's the difference between `Effect.fork` and just running an effect? What does fork give you back?"
+- "If `fork` returns a `Fiber`, how do you eventually get the result out of it?"
+- "What happens when you interrupt a fiber — does it throw? Does it return a value? What does the calling code do next?"
+- "How are fibers different from JavaScript Promises? Can you cancel a Promise?"
+
+### Common pitfalls
+
+1. **`forkAndInterrupt` — trying to get a result from an interrupted fiber** — after `Fiber.interrupt`, the fiber is done. Don't try to `Fiber.join` it expecting a value. Just return the string `"interrupted"` directly. Ask: "After interrupting the fiber, what do you need to return? Where does that value come from?"
+2. **Forgetting `yield*` on fork/join** — `Effect.fork` and `Fiber.join` both return Effects. They must be yielded. Ask: "What type does `Effect.fork(myEffect)` return?"
+3. **`forkBoth` — joining sequentially vs concurrently** — you can join two fibers one after another since they're already running concurrently (they were forked). The join just waits for completion. Ask: "If both fibers are already running, does the order you join them matter for correctness?"
+4. **Confusing fork with Effect.all** — `Effect.all` handles parallelism for you. `fork` gives you the fiber handle for manual control. Ask: "When would you choose `fork` over `Effect.all`?"
+5. **`forkBoth` is the pattern twice** — fork both effects to get two fibers, then join both fibers. Combine the two results into a tuple `[resultA, resultB]`.
+
+## On Completion
+
+### Insight
+
+Fibers are Effect's unit of concurrency — lighter than threads, managed by the runtime. `fork` starts concurrent work, `join` waits for it, `interrupt` cancels it. Unlike raw Promises, fibers support structured concurrency: when a parent fiber is interrupted, all its children are too. This means no orphaned background work, no resource leaks from forgotten tasks. The runtime manages the lifecycle for you.
+
+### Bridge
+
+Concurrency is about managing running computations. But what about managing **resources** — things that need to be acquired and then reliably released? Kata 021 starts the Resource Management area with `acquireRelease` and `Scope` — ensuring cleanup happens even when things go wrong.

package/katas/020-fibers/solution.test.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { forkAndJoin, forkBoth, forkAndInterrupt } from "@/katas/020-fibers/solution.js";
+
+describe("020 — Fibers", () => {
+  it("forkAndJoin returns the effect result", async () => {
+    const result = await Effect.runPromise(forkAndJoin(Effect.succeed(42)));
+    expect(result).toBe(42);
+  });
+
+  it("forkBoth returns both results", async () => {
+    const result = await Effect.runPromise(
+      forkBoth(Effect.succeed("a"), Effect.succeed("b")),
+    );
+    expect(result).toEqual(["a", "b"]);
+  });
+
+  it("forkAndInterrupt returns 'interrupted'", async () => {
+    const slow = Effect.succeed("done").pipe(Effect.delay("10 seconds"));
+    const result = await Effect.runPromise(forkAndInterrupt(slow));
+    expect(result).toBe("interrupted");
+  });
+});

package/katas/020-fibers/solution.ts

@@ -0,0 +1,23 @@
+import { Effect, Fiber } from "effect";
+
+/** Fork the effect into a background fiber, then join it to get the result */
+export const forkAndJoin = <A, E>(
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, E> => {
+  throw new Error("Not implemented");
+};
+
+/** Fork two effects, join both, return their results as a tuple */
+export const forkBoth = <A, B, E>(
+  a: Effect.Effect<A, E>,
+  b: Effect.Effect<B, E>,
+): Effect.Effect<[A, B], E> => {
+  throw new Error("Not implemented");
+};
+
+/** Fork the effect, then immediately interrupt the fiber, return "interrupted" */
+export const forkAndInterrupt = (
+  effect: Effect.Effect<string>,
+): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};

package/katas/021-acquire-release/SENSEI.md

@@ -0,0 +1,57 @@
+# SENSEI — 021 Acquire Release
+
+## Briefing
+
+### Goal
+
+Learn to use `Effect.acquireRelease` to safely acquire and release resources, `Effect.scoped` to run scoped effects that manage resource lifetimes, and guaranteed cleanup so resources are always released even on failure.
+
+### Tasks
+
+1. Implement `useResource` -- use `Effect.acquireRelease` to acquire a resource (push `"{id}:open"` to the log, return `{ id, isOpen: true }`), release it (push `"{id}:closed"`), and use it (push `"{id}:used"`, return the resource id). Wrap with `Effect.scoped`.
+2. Implement `useTwoResources` -- use `Effect.acquireRelease` with two resources sequentially in `Effect.gen`. Both should be acquired, used, and released in reverse order.
+
+## Prerequisites
+
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`
+- **011 Services and Context** — `Context.Tag`, service access
+- **012 Layers** — `Layer`, composition
+
+## Skills
+
+Invoke `effect-patterns-resource-management` before teaching this kata.
+
+> **Note**: `Effect.runSync` appears only in tests. The student does NOT write it. Never attribute it to their learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `useResource acquires, uses, and releases` | `Effect.acquireRelease` + `Effect.scoped` | Log contains `["db:open", "db:used", "db:closed"]` in order; returns `"db"` |
+| `useTwoResources releases in reverse order` | `Effect.acquireRelease` + `Effect.gen` | Acquires a then b, releases b then a (LIFO order) |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What happens to your database connection if the code that uses it throws? How does `try/finally` handle this — and what's the Effect equivalent?"
+- "If you acquire resource A, then acquire resource B, and B's use phase fails — in what order should they be released?"
+- "What does `Effect.scoped` actually do? What happens if you forget it?"
+
+### Common pitfalls
+
+1. **Forgetting `Effect.scoped`** — without it, the scope is never closed and the release function never runs. `acquireRelease` registers a finalizer on a scope, but someone needs to provide that scope. Ask: "You've set up acquire and release — but what tells Effect *when* to release?"
+2. **Release function signature** — the release function receives the acquired resource as its argument. Students may try to close over the resource variable instead. Nudge: "Look at the type of the release callback — what parameter does it get?"
+3. **`useTwoResources` structure** — both resources should be acquired inside a single `Effect.gen` wrapped with `Effect.scoped`. Each `yield*` of an `acquireRelease` registers its finalizer on the same scope. Ask: "If you yield two acquireRelease calls inside one gen, how many finalizers are registered?"
+4. **Using `Effect.sync` for log mutations** — pushing to the log array is a side effect. It needs to be wrapped in `Effect.sync(() => { ... })`. Students may try bare mutations inside the generator.
+5. **Separate "use" phase** — the "use" phase is separate from acquire/release. After acquiring, you still need code to actually use the resource before the scope closes.
+
+## On Completion
+
+### Insight
+
+`acquireRelease` guarantees cleanup — even if the "use" phase throws, fails, or is interrupted. Resources are released in reverse acquisition order (LIFO, like a stack). This is Effect's answer to `try/finally`, but compositional: you can acquire multiple resources and Effect manages all their lifetimes automatically.
+
+### Bridge
+
+Now that you can manage resource lifetimes, the next step is **scoped layers**. Kata 022 introduces `Layer.scoped` — combining service provisioning with resource management so that services like database connections are acquired when the layer is built and released when the scope closes.

package/katas/021-acquire-release/solution.test.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { useResource, useTwoResources } from "@/katas/021-acquire-release/solution.js";
+
+describe("021 — Acquire Release", () => {
+  it("useResource acquires, uses, and releases", () => {
+    const log: string[] = [];
+    const result = Effect.runSync(useResource("db", log));
+    expect(result).toBe("db");
+    expect(log).toEqual(["db:open", "db:used", "db:closed"]);
+  });
+
+  it("useTwoResources releases in reverse order", () => {
+    const log: string[] = [];
+    Effect.runSync(useTwoResources(log));
+    expect(log[0]).toBe("a:open");
+    expect(log[1]).toBe("b:open");
+    // Resources used
+    // Release in reverse: b first, then a
+    expect(log[log.length - 2]).toBe("b:closed");
+    expect(log[log.length - 1]).toBe("a:closed");
+  });
+});

package/katas/021-acquire-release/solution.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+
+// Simulates a resource that tracks open/close state
+export interface Resource {
+  readonly id: string;
+  readonly isOpen: boolean;
+}
+
+/** Use Effect.acquireRelease to:
+ * - Acquire: push "{id}:open" to the log array, return { id, isOpen: true }
+ * - Release: push "{id}:closed" to the log array
+ * - Use: push "{id}:used" to the log array, return the resource id
+ * Wrap with Effect.scoped */
+export const useResource = (id: string, log: string[]): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.acquireRelease with two resources sequentially in Effect.gen
+ * Both should be acquired, used, and released (in reverse order) */
+export const useTwoResources = (log: string[]): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};

package/katas/022-scoped-layers/SENSEI.md

@@ -0,0 +1,52 @@
+# SENSEI — 022 Scoped Layers
+
+## Briefing
+
+### Goal
+
+Learn to use `Layer.scoped` to create layers that manage resource lifetimes, and to provide managed resources as services that acquire on layer build and release on scope close.
+
+### Tasks
+
+1. Implement `DatabaseLive` -- create a `Layer.scoped` that acquires a "connection" (log `"db:connected"`), provides a `Database` service whose `query` method returns `"result:{sql}"`, and releases by logging `"db:disconnected"`.
+2. Implement `runQuery` -- use the `Database` service to run a query via `Effect.gen`.
+
+## Prerequisites
+
+- **012 Layers** — `Layer`, composition
+- **021 Acquire Release** — `Effect.acquireRelease`, `Effect.scoped`
+
+> **Note**: `Effect.runSync`, `Effect.scoped`, and `Effect.provide` appear only in tests. The student does NOT write them. Never attribute them to their learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `DatabaseLive connects and disconnects` | `Layer.scoped` + `Effect.acquireRelease` | Log contains `"db:connected"` and `"db:disconnected"`; query returns `"result:SELECT 1"` |
+| `DatabaseLive disconnects even when query fails` | `acquireRelease` cleanup guarantee | Cleanup runs even when the use phase fails — `"db:disconnected"` still in log |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "In kata 012 you built layers with `Layer.succeed`. What if building the service requires acquiring a resource — like opening a database connection?"
+- "When should the database connection be closed? Who decides that?"
+- "What's the difference between `Layer.effect` and `Layer.scoped`? Why does this kata need `scoped`?"
+
+### Common pitfalls
+
+1. **Understanding `Layer.scoped`'s argument** — `Layer.scoped` takes an Effect that returns the service value. Inside that effect, you use `acquireRelease` to set up the resource, then return the service implementation that uses it. Students may try to pass a Layer or a service object directly. Ask: "What type does `Layer.scoped` expect as its argument?"
+2. **Returning the service, not the connection** — the acquireRelease creates and manages the connection, but the layer needs to provide a `Database` service (with a `query` method). Students may return the raw connection instead. Nudge: "What does the Database tag expect? A connection or a service with a `query` method?"
+3. **`runQuery` needs to access the service** — use `yield*` with the Database tag to get the service, then call `query`. Students may try to access the database directly. Ask: "How do you get a service from the context inside `Effect.gen`?"
+4. **Logging in the right places** — `"db:connected"` should be logged during acquire, `"db:disconnected"` during release. Students may log in the wrong phase.
+5. **Shape of `Layer.scoped`** — inside `Layer.scoped`, write an Effect that does `acquireRelease`, then return an object with a `query` method. That object is your Database service.
+
+## On Completion
+
+### Insight
+
+`Layer.scoped` combines service provisioning with resource management. The service is available as long as the scope is open; when the scope closes, the resource is released. This means database connections, file handles, and network connections can be managed declaratively — you describe *what* to acquire and release, and Effect handles *when*.
+
+### Bridge
+
+You've seen `acquireRelease` for resources and `Layer.scoped` for services. Kata 023 introduces additional **resource patterns** like `Effect.ensuring` for extra cleanup and handling failures during the use phase — rounding out the Resource Management area.

package/katas/022-scoped-layers/solution.test.ts

@@ -0,0 +1,35 @@
+import { Effect, Exit } from "effect";
+import { describe, expect, it } from "vitest";
+import { Database, DatabaseLive, runQuery } from "@/katas/022-scoped-layers/solution.js";
+
+describe("022 — Scoped Layers", () => {
+  it("DatabaseLive connects and disconnects", () => {
+    const log: string[] = [];
+    const program = Effect.scoped(
+      Effect.provide(runQuery("SELECT 1"), DatabaseLive(log)),
+    );
+    const result = Effect.runSync(program);
+    expect(result).toBe("result:SELECT 1");
+    expect(log).toContain("db:connected");
+    expect(log).toContain("db:disconnected");
+  });
+
+  it("DatabaseLive disconnects even when query fails", () => {
+    const log: string[] = [];
+    const program = Effect.scoped(
+      Effect.provide(
+        Effect.gen(function* () {
+          const db = yield* Database;
+          return yield* db.query("FAIL").pipe(
+            Effect.flatMap(() => Effect.fail("query error")),
+          );
+        }),
+        DatabaseLive(log),
+      ),
+    );
+    const exit = Effect.runSyncExit(program);
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(log).toContain("db:connected");
+    expect(log).toContain("db:disconnected");
+  });
+});

package/katas/022-scoped-layers/solution.ts

@@ -0,0 +1,19 @@
+import { Context, Effect, Layer } from "effect";
+
+export class Database extends Context.Tag("Database")<
+  Database,
+  { readonly query: (sql: string) => Effect.Effect<string> }
+>() {}
+
+/** Create a Layer.scoped that:
+ * - acquires a "connection" (log "db:connected" to the log array)
+ * - provides a Database service whose query returns "result:{sql}"
+ * - releases by logging "db:disconnected" */
+export const DatabaseLive = (log: string[]): Layer.Layer<Database> =>
+  Layer.fail("Not implemented" as any);
+
+/** Use the Database service to run a query */
+export const runQuery = (sql: string) =>
+  Effect.gen(function* () {
+    throw new Error("Not implemented");
+  });