@dojocho/effect-ts 0.0.1

package/katas/023-resource-patterns/SENSEI.md

@@ -0,0 +1,52 @@
+# SENSEI — 023 Resource Patterns
+
+## Briefing
+
+### Goal
+
+Learn to use `Effect.ensuring` to add additional cleanup that always runs, verify that resources are released even when the use phase fails, and guarantee cleanup regardless of success or failure.
+
+### Tasks
+
+1. Implement `withEnsuring` -- use `Effect.acquireRelease` to create a resource and `Effect.ensuring` to add additional cleanup. Log `"acquire"`, `"ensure-cleanup"`, and `"release"` to the log array.
+2. Implement `releaseOnFailure` -- use `Effect.acquireRelease` where the "use" phase fails. Verify the resource is still released. Return `"released"` if cleanup happened.
+
+## Prerequisites
+
+- **021 Acquire Release** — `Effect.acquireRelease`, `Effect.scoped`
+- **022 Scoped Layers** — `Layer.scoped`, service lifetime
+
+> **Note**: `Effect.runSync` appears only in tests. The student does NOT write it. Never attribute it to their learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `withEnsuring runs all cleanup` | `Effect.ensuring` + `Effect.acquireRelease` | Log contains `"acquire"`, `"ensure-cleanup"`, and `"release"` |
+| `releaseOnFailure still releases on error` | `Effect.acquireRelease` + error recovery | Returns `"released"`; log contains `"release"` despite use-phase failure |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "You know `acquireRelease` guarantees cleanup. What if you need *additional* cleanup that isn't tied to a specific resource — like flushing a metrics buffer?"
+- "If the use phase fails, does the release still run? How would you verify that?"
+- "For `releaseOnFailure`, the test expects the return value `'released'`. But if the use phase fails, how do you get a success value out?"
+
+### Common pitfalls
+
+1. **`ensuring` execution order** — `ensuring` runs after the whole effect completes, including after `acquireRelease`'s release. Students may expect it to run before release. Ask: "If you wrap an `acquireRelease` with `ensuring`, which cleanup runs first — the release or the ensuring finalizer?"
+2. **`releaseOnFailure` — catching after scoped** — the use phase fails inside the scope, but `acquireRelease` still releases. To return `"released"`, you need to catch the error *after* `Effect.scoped`. Students may try to catch inside the scope. Ask: "Where should the `catchAll` go — inside or outside the `Effect.scoped` call?"
+3. **Forgetting `Effect.scoped`** — same pitfall as kata 021. The scope boundary triggers the release. Without it, nothing gets cleaned up.
+4. **`withEnsuring` structure** — students need to combine `acquireRelease` (with its own release) *and* `ensuring` on the outer effect. The ensuring callback is separate from the acquireRelease release function.
+5. **`releaseOnFailure` catch placement** — create an `acquireRelease` where the use phase calls `Effect.fail`, wrap with `Effect.scoped`, then catch the error *outside* the scope and return `'released'`.
+
+## On Completion
+
+### Insight
+
+`Effect.ensuring` adds a finalizer that runs regardless of outcome — it stacks with `acquireRelease`. For error recovery with resources, the key insight is that `acquireRelease` ALWAYS releases, even on failure. You can catch the use-phase failure after the scope closes and still verify cleanup happened. Together, these patterns give you complete control over resource lifecycles.
+
+### Bridge
+
+Resource Management is now complete. You can acquire and release resources, tie them to service layers, add extra finalizers, and recover from failures — all with guaranteed cleanup. Next up: **Streams**. Kata 024 introduces `Stream`, `runCollect`, and `runFold` for processing lazy sequences of data.

package/katas/023-resource-patterns/solution.test.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { withEnsuring, releaseOnFailure } from "@/katas/023-resource-patterns/solution.js";
+
+describe("023 — Resource Patterns", () => {
+  it("withEnsuring runs all cleanup", () => {
+    const log: string[] = [];
+    Effect.runSync(withEnsuring(log));
+    expect(log).toContain("acquire");
+    expect(log).toContain("ensure-cleanup");
+    expect(log).toContain("release");
+  });
+
+  it("releaseOnFailure still releases on error", () => {
+    const log: string[] = [];
+    const result = Effect.runSync(releaseOnFailure(log));
+    expect(result).toBe("released");
+    expect(log).toContain("release");
+  });
+});

package/katas/023-resource-patterns/solution.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+
+/** Use Effect.acquireRelease to create a resource, and Effect.ensuring
+ * to add additional cleanup. Log "acquire", "ensure-cleanup", "release" to the log array */
+export const withEnsuring = (log: string[]): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.acquireRelease where the "use" phase fails.
+ * Verify the resource is still released. Return "released" if cleanup happened. */
+export const releaseOnFailure = (log: string[]): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};

package/katas/024-streams-basics/SENSEI.md

@@ -0,0 +1,61 @@
+# SENSEI — 024 Streams Basics
+
+## Briefing
+
+### Goal
+
+Learn to use `Stream.fromIterable` to create streams, `Stream.map` and `Stream.filter` to transform them, `Stream.runCollect` to collect elements into a Chunk, and `Stream.runFold` to reduce a stream into a single value.
+
+### Tasks
+
+1. Implement `streamFromArray` -- create a Stream from an array and collect all elements back to an array.
+2. Implement `filterAndDouble` -- create a stream from `[1,2,3,4,5]`, filter even numbers, double them, and collect the results.
+3. Implement `sumStream` -- use `Stream.runFold` to sum all elements in a stream.
+
+## Prerequisites
+
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`
+- **005 Pipe Composition** — `pipe`, function composition
+
+## Skills
+
+Invoke `effect-patterns-streams-getting-started` 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 |
+|------|---------|----------|
+| `streamFromArray collects all elements` | `Stream.fromIterable` + `Stream.runCollect` | `[1, 2, 3]` round-trips through stream and back |
+| `streamFromArray handles empty array` | `Stream.fromIterable` + `Stream.runCollect` | Edge case — empty input produces empty output |
+| `filterAndDouble returns [4, 8]` | `Stream.filter` + `Stream.map` | Filters evens from `[1,2,3,4,5]`, doubles them |
+| `sumStream sums all elements` | `Stream.runFold` | Folds `[1,2,3,4,5]` with addition to get `15` |
+| `sumStream of empty is 0` | `Stream.runFold` | Edge case — empty stream with initial value `0` |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What happens to elements in a Stream that you never consume? How does laziness help when the data source is huge or infinite?"
+- "If `runCollect` forces the entire stream into memory, when is that acceptable and when would you prefer `runFold`?"
+- "After `runCollect`, you get a `Chunk`, not an array. Why do you think Effect uses its own collection type instead of plain arrays?"
+- "What's the relationship between `Stream.runFold` and `Array.reduce`? Could you express `runCollect` in terms of `runFold`?"
+
+### Common pitfalls
+
+1. **`runCollect` returns a Chunk, not an array** — students must call `Chunk.toArray` to convert. Without it, the test comparison with `toEqual([...])` will fail. Ask: "What type does `runCollect` give you? How do you get a plain array from it?"
+2. **`filterAndDouble` source data** — the stream is created from `[1, 2, 3, 4, 5]`. Evens are 2 and 4. Doubled: `[4, 8]`. Students may filter odds instead. Ask: "Which numbers from 1 to 5 are even?"
+3. **`runFold` signature** — it takes an initial value, a combining function, and returns an Effect (not a Stream). Students may try to chain more stream operations after it. Ask: "Is `runFold` a transformation or a terminal operation?"
+4. **Forgetting that stream operations return new streams** — `Stream.filter` and `Stream.map` don't consume the stream. You need a terminal operation like `runCollect` or `runFold` to get a result. Ask: "What turns a stream description into an actual value?"
+5. **`runFold` is like `Array.reduce`** — for `sumStream`, use `runFold` with initial value `0` and a function `(acc, n) => acc + n`. Ask: "What should the sum be if the stream is empty?"
+
+## On Completion
+
+### Insight
+
+Streams are lazy, pull-based sequences of values. Unlike arrays, they can represent infinite sequences and process elements one at a time without loading everything into memory. `runCollect` and `runFold` are terminal operations that "consume" the stream — until you call one, no elements are processed. This lazy evaluation model is what makes streams efficient for large or unbounded data.
+
+### Bridge
+
+Now that you can create, transform, and consume streams, the next step is more powerful **stream operations**. Kata 025 introduces `Stream.take` (limiting elements), `Stream.scan` (running accumulations), and `Stream.grouped` (batching) — tools for building real data processing pipelines.

package/katas/024-streams-basics/solution.test.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { streamFromArray, filterAndDouble, sumStream } from "@/katas/024-streams-basics/solution.js";
+
+describe("024 — Streams Basics", () => {
+  it("streamFromArray collects all elements", () => {
+    const result = Effect.runSync(streamFromArray([1, 2, 3]));
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  it("streamFromArray handles empty array", () => {
+    const result = Effect.runSync(streamFromArray([]));
+    expect(result).toEqual([]);
+  });
+
+  it("filterAndDouble returns [4, 8]", () => {
+    const result = Effect.runSync(filterAndDouble());
+    expect(result).toEqual([4, 8]);
+  });
+
+  it("sumStream sums all elements", () => {
+    const result = Effect.runSync(sumStream([1, 2, 3, 4, 5]));
+    expect(result).toBe(15);
+  });
+
+  it("sumStream of empty is 0", () => {
+    const result = Effect.runSync(sumStream([]));
+    expect(result).toBe(0);
+  });
+});

package/katas/024-streams-basics/solution.ts

@@ -0,0 +1,16 @@
+import { Effect, Stream, Chunk } from "effect";
+
+/** Create a Stream from an array and collect all elements back to an array */
+export const streamFromArray = (items: number[]): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Create a stream from [1,2,3,4,5], filter even numbers, double them, collect */
+export const filterAndDouble = (): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Stream.runFold to sum all elements */
+export const sumStream = (items: number[]): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};

package/katas/025-stream-operations/SENSEI.md

@@ -0,0 +1,59 @@
+# SENSEI — 025 Stream Operations
+
+## Briefing
+
+### Goal
+
+Learn to use `Stream.take` to take the first n elements from a stream, `Stream.scan` to compute running accumulations, and `Stream.grouped` to batch stream elements into fixed-size chunks.
+
+### Tasks
+
+1. Implement `takeFirst` -- take the first n elements from a stream of numbers 1, 2, 3, ...
+2. Implement `runningTotal` -- use `Stream.scan` to compute running totals of the input array (e.g., `[1,2,3]` becomes `[1,3,6]`).
+3. Implement `batchItems` -- use `Stream.grouped` to batch items into chunks of size n, returning an array of arrays.
+
+## Prerequisites
+
+- **024 Streams Basics** — `Stream.fromIterable`, `Stream.filter`, `Stream.map`, `Stream.runCollect`, `Stream.runFold`
+
+## Skills
+
+Invoke `effect-patterns-streams` 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 |
+|------|---------|----------|
+| `takeFirst(3) returns [1, 2, 3]` | `Stream.iterate` + `Stream.take` | Infinite stream limited to 3 elements |
+| `takeFirst(0) returns []` | `Stream.take` | Edge case — taking zero elements |
+| `runningTotal of [1,2,3] is [1,3,6]` | `Stream.scan` | Accumulating sums: 1, 1+2=3, 3+3=6 |
+| `runningTotal of [] is []` | `Stream.scan` | Edge case — empty input |
+| `batchItems groups into chunks` | `Stream.grouped` | `[1,2,3,4,5]` with size 2 produces `[[1,2],[3,4],[5]]` |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "How does `scan` differ from `reduce` / `runFold`? When would you want *all* the intermediate results instead of just the final one?"
+- "If you `take(3)` from an infinite stream, how does laziness prevent the stream from running forever?"
+- "For batching, the last group might be smaller than the batch size. How does `grouped` handle that — does it drop it, pad it, or emit it as-is?"
+
+### Common pitfalls
+
+1. **`takeFirst` needs an infinite stream** — students must create a stream starting at 1 that counts upward. Use `Stream.iterate(1, n => n + 1)` or similar. Students may try to create a finite array first, which defeats the purpose. Ask: "Can you take 3 elements from an infinite stream without running out of memory? How?"
+2. **`scan` emits every intermediate value** — unlike `runFold` which produces one final result, `scan` emits each accumulation step. For `[1, 2, 3]` with addition, scan emits `[1, 3, 6]`, not just `6`. Students may confuse scan with fold. Ask: "How many elements does the output stream have compared to the input?"
+3. **`grouped` returns Chunk<Chunk<A>>** — after `runCollect`, you get a `Chunk` of `Chunk`s. You need to convert both the outer and inner chunks to arrays. Students may forget the inner conversion. Ask: "After `runCollect`, what's the type? How do you get `number[][]` from it?"
+4. **`scan` initial value and empty streams** — `scan` with an initial value of 0 would emit `[0, 1, 3, 6]` for input `[1, 2, 3]`. The test expects `[1, 3, 6]` — no leading zero. Students need to think about whether to use an initial value or start from the first element. Ask: "The test expects 3 elements out for 3 elements in. Does your scan add an extra element?"
+5. **`takeFirst` uses `Stream.iterate`** — create an infinite stream with `Stream.iterate(1, n => n + 1)`, then pipe through `Stream.take(n)` and collect. Don't pre-allocate a finite array.
+
+## On Completion
+
+### Insight
+
+`Stream.take` on an infinite stream is safe — it only pulls n elements, then stops. `Stream.scan` is a stateful transformation that remembers the accumulator and emits each intermediate result. `Stream.grouped` batches elements without buffering the entire stream. These operations compose naturally — you build complex pipelines from simple parts, and laziness ensures only the necessary work is done.
+
+### Bridge
+
+You can now create, transform, limit, accumulate, and batch streams. Kata 026 introduces **combining streams** — `merge`, `zip`, and `concat` — for building pipelines that draw from multiple data sources simultaneously.

package/katas/025-stream-operations/solution.test.ts

@@ -0,0 +1,26 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { takeFirst, runningTotal, batchItems } from "@/katas/025-stream-operations/solution.js";
+
+describe("025 — Stream Operations", () => {
+  it("takeFirst(3) returns [1, 2, 3]", () => {
+    expect(Effect.runSync(takeFirst(3))).toEqual([1, 2, 3]);
+  });
+
+  it("takeFirst(0) returns []", () => {
+    expect(Effect.runSync(takeFirst(0))).toEqual([]);
+  });
+
+  it("runningTotal of [1,2,3] is [1,3,6]", () => {
+    expect(Effect.runSync(runningTotal([1, 2, 3]))).toEqual([1, 3, 6]);
+  });
+
+  it("runningTotal of [] is []", () => {
+    expect(Effect.runSync(runningTotal([]))).toEqual([]);
+  });
+
+  it("batchItems groups into chunks", () => {
+    const result = Effect.runSync(batchItems([1, 2, 3, 4, 5], 2));
+    expect(result).toEqual([[1, 2], [3, 4], [5]]);
+  });
+});

package/katas/025-stream-operations/solution.ts

@@ -0,0 +1,17 @@
+import { Effect, Stream } from "effect";
+
+/** Take the first n elements from a stream of numbers 1,2,3,... */
+export const takeFirst = (n: number): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Stream.scan to compute running totals of the input array
+ * e.g., [1,2,3] -> [1,3,6] */
+export const runningTotal = (items: number[]): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Stream.grouped to batch items into chunks of size n, return as array of arrays */
+export const batchItems = (items: number[], size: number): Effect.Effect<number[][]> => {
+  throw new Error("Not implemented");
+};

package/katas/026-combining-streams/SENSEI.md

@@ -0,0 +1,54 @@
+# SENSEI — 026 Combining Streams
+
+## Briefing
+
+### Goal
+
+Learn to use `Stream.concat` to concatenate two streams sequentially, `Stream.zip` to pair elements from two streams into tuples, and `Stream.merge` to interleave elements from two streams.
+
+### Tasks
+
+1. Implement `concatStreams` -- concatenate two streams sequentially.
+2. Implement `zipStreams` -- zip two streams into tuples.
+3. Implement `mergeStreams` -- merge two streams (interleaved, order may vary).
+
+## Prerequisites
+
+- **024 Streams Basics** — `Stream`, `Stream.fromIterable`, `Stream.runCollect`
+- **025 Stream Operations** — `Stream.map`, `Stream.filter`, `Stream.take`
+
+> **Note**: `Effect.runSync` appears only in tests. Never attribute it to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `concatStreams appends second after first` | `Stream.concat` | `[1,2] ++ [3,4] = [1,2,3,4]` — sequential ordering |
+| `zipStreams pairs elements` | `Stream.zip` | `[1,2] zip ["a","b"] = [[1,"a"],[2,"b"]]` — lock-step pairing |
+| `mergeStreams contains all elements` | `Stream.merge` | `merge [1,2] [3,4]` sorted = `[1,2,3,4]` — all elements present regardless of order |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "What ordering guarantees does `merge` give you vs `concat`? If you need results in a specific order, which do you pick?"
+- "If one stream has 3 elements and the other has 5, what should `zip` produce? What about `concat`? What about `merge`? Think about the semantics of each combinator."
+- "When would you choose `merge` (non-deterministic interleaving) over `concat` (sequential) in a real application?"
+
+### Common pitfalls
+
+1. **zip stops at the shorter stream** — `Stream.zip` produces pairs until one stream runs out. If the streams have different lengths, the extra elements from the longer one are dropped. Ask: "How many pairs do you get from zipping [1,2,3] with ['a','b']?"
+2. **merge order is non-deterministic** — `Stream.merge` interleaves elements as they become available. The test uses `.sort()` to verify contents regardless of order. Ask: "Can you guarantee which element comes first from a merge? Why does the test sort the result?"
+3. **Forgetting Chunk.toArray** — See kata 024 for `Chunk.toArray` -- same pattern applies here.
+4. **Confusing concat and merge** — `concat` is sequential (all of A, then all of B), while `merge` is concurrent (interleaved). Ask: "If stream A takes a long time, does `concat` start B before A finishes?"
+5. **All three end the same way** — every combinator function ends with `runCollect` then `Chunk.toArray`. Start with `concatStreams` (most intuitive), then apply the same pattern to `zip` and `merge`.
+
+## On Completion
+
+### Insight
+
+`concat` is sequential (all of A then all of B), `zip` is lock-step (pairs up elements, stops at the shorter), `merge` is concurrent (interleaves as available). Each combinator models a different relationship between two data sources. Choosing the right one depends on whether your sources are independent and unrelated (concat), correlated by position (zip), or independent but concurrent (merge).
+
+### Bridge
+
+Now that you can create, transform, and combine streams, kata 027 introduces **data pipelines** — using `Stream.mapEffect` to process each element through an effectful function, and `Stream.runFold` to reduce streams to a single value. This is the ETL (Extract, Transform, Load) pattern expressed as a stream pipeline.

package/katas/026-combining-streams/solution.test.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { concatStreams, zipStreams, mergeStreams } from "@/katas/026-combining-streams/solution.js";
+
+describe("026 — Combining Streams", () => {
+  it("concatStreams appends second after first", () => {
+    const result = Effect.runSync(concatStreams([1, 2], [3, 4]));
+    expect(result).toEqual([1, 2, 3, 4]);
+  });
+
+  it("zipStreams pairs elements", () => {
+    const result = Effect.runSync(zipStreams([1, 2], ["a", "b"]));
+    expect(result).toEqual([[1, "a"], [2, "b"]]);
+  });
+
+  it("mergeStreams contains all elements", () => {
+    const result = Effect.runSync(mergeStreams([1, 2], [3, 4]));
+    expect(result.sort()).toEqual([1, 2, 3, 4]);
+  });
+});

package/katas/026-combining-streams/solution.ts

@@ -0,0 +1,16 @@
+import { Effect, Stream } from "effect";
+
+/** Concatenate two streams sequentially */
+export const concatStreams = (a: number[], b: number[]): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Zip two streams into tuples */
+export const zipStreams = (a: number[], b: string[]): Effect.Effect<[number, string][]> => {
+  throw new Error("Not implemented");
+};
+
+/** Merge two streams (interleaved, order may vary) */
+export const mergeStreams = (a: number[], b: number[]): Effect.Effect<number[]> => {
+  throw new Error("Not implemented");
+};

package/katas/027-data-pipelines/SENSEI.md

@@ -0,0 +1,58 @@
+# SENSEI — 027 Data Pipelines
+
+## Briefing
+
+### Goal
+
+Learn to use `Stream.mapEffect` to apply an effectful function to each stream element, and to build multi-step pipelines that compose stream transformations into data processing workflows.
+
+### Tasks
+
+1. Implement `processItems` -- use `Stream.mapEffect` to asynchronously process each item by applying `fn` to each element in the stream, then collect results.
+2. Implement `sumPositiveNumbers` -- build a pipeline that takes an array of strings, parses them to numbers (skipping non-numeric values), filters positives, and sums them.
+
+## Prerequisites
+
+- **024 Streams Basics** — `Stream`, `Stream.fromIterable`, `Stream.runCollect`
+- **025 Stream Operations** — `Stream.map`, `Stream.filter`, `Stream.take`
+- **026 Combining Streams** — `Stream.concat`, `Stream.zip`, `Stream.merge`
+
+## Skills
+
+Invoke `effect-patterns-building-data-pipelines` before teaching this kata.
+
+> **Note**: `Effect.runSync` appears only in tests. Never attribute it to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `processItems applies function to each` | `Stream.mapEffect` + `Stream.runCollect` | `[1,2,3]` with `n => succeed(n*10)` = `[10,20,30]` |
+| `sumPositiveNumbers parses, filters, and sums` | `Stream.map` + `Stream.filter` + `Stream.runFold` | `["1","abc","-2","3","4"]` -> skip non-numeric, filter positive, sum = 8 |
+| `sumPositiveNumbers of empty is 0` | `Stream.runFold` | Empty stream fold returns initial value 0 |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "If one step in your pipeline fails (e.g., a bad parse or a failed API call), what happens to the partially processed data? Does the entire pipeline abort?"
+- "For `sumPositiveNumbers`, there are three stages: parse, filter, sum. What happens if you reorder them -- say, filter before parse? Does the pipeline still work?"
+- "What makes `mapEffect` different from `map`? When would each step in a pipeline *need* to be effectful vs pure?"
+
+### Common pitfalls
+
+1. **Non-numeric strings should be skipped, not fail the pipeline** — `parseInt("abc")` returns `NaN`. The pipeline should filter these out rather than failing the entire stream. Ask: "What happens when you parse 'abc'? Should that crash the whole pipeline or just skip that element?"
+2. **processItems uses mapEffect, not map** — since `fn` returns an `Effect`, you need `Stream.mapEffect` to unwrap each result into the stream. Using `Stream.map` would give you a stream of Effects. Ask: "What type do you get if you `map` with a function that returns an Effect?"
+3. **runFold needs an initial value and a combine function** — `Stream.runFold(0, (acc, n) => acc + n)` starts at 0 and adds each element. Ask: "What should the sum be if the stream is empty?"
+4. **Filter placement matters** — filter out `NaN` values BEFORE filtering for positive numbers. Both checks can be combined, but the parse step must come first.
+5. **Pipeline stage order** — break `sumPositiveNumbers` into stages: `fromIterable` -> `map(parseInt)` -> `filter(not NaN and positive)` -> `runFold` to sum.
+
+## On Completion
+
+### Insight
+
+`Stream.mapEffect` is the bridge between streams and effects — each element is processed through an effectful function, making streams capable of I/O, validation, and error handling at every step. The `sumPositiveNumbers` pipeline demonstrates the ETL pattern: **Extract** (parse strings), **Transform** (filter positives), **Load** (fold into sum). This same pattern scales to real-world data processing — reading from files, transforming records, writing to databases — all expressed as a composable stream pipeline.
+
+### Bridge
+
+With streams and data pipelines covered, kata 028 shifts to **observability** — using `Effect.log`, `Effect.annotateLogs`, and `Effect.withSpan` to add structured logging and tracing to your effects. These tools make production applications debuggable without changing their logic.

package/katas/027-data-pipelines/solution.test.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import { processItems, sumPositiveNumbers } from "@/katas/027-data-pipelines/solution.js";
+
+describe("027 — Data Pipelines", () => {
+  it("processItems applies function to each", () => {
+    const result = Effect.runSync(
+      processItems([1, 2, 3], (n) => Effect.succeed(n * 10)),
+    );
+    expect(result).toEqual([10, 20, 30]);
+  });
+
+  it("sumPositiveNumbers parses, filters, and sums", () => {
+    const result = Effect.runSync(sumPositiveNumbers(["1", "abc", "-2", "3", "4"]));
+    expect(result).toBe(8);
+  });
+
+  it("sumPositiveNumbers of empty is 0", () => {
+    const result = Effect.runSync(sumPositiveNumbers([]));
+    expect(result).toBe(0);
+  });
+});

package/katas/027-data-pipelines/solution.ts

@@ -0,0 +1,16 @@
+import { Effect, Stream } from "effect";
+
+/** Use Stream.mapEffect to asynchronously process each item
+ * Apply fn to each element in the stream, collect results */
+export const processItems = <A, B>(
+  items: A[],
+  fn: (a: A) => Effect.Effect<B>,
+): Effect.Effect<B[]> => {
+  throw new Error("Not implemented");
+};
+
+/** Build a pipeline: take array of strings, parse to numbers (skip non-numeric),
+ * filter positives, sum them */
+export const sumPositiveNumbers = (items: string[]): Effect.Effect<number> => {
+  throw new Error("Not implemented");
+};

package/katas/028-logging-and-spans/SENSEI.md

@@ -0,0 +1,58 @@
+# SENSEI — 028 Logging and Spans
+
+## Briefing
+
+### Goal
+
+Learn to use `Effect.log` for structured logging within effects, `Effect.annotateLogs` to add contextual metadata to log entries, and `Effect.withSpan` to wrap computations in named spans for tracing.
+
+### Tasks
+
+1. Implement `logAndReturn` -- use `Effect.log` to log a message, then return `"done"`.
+2. Implement `logWithContext` -- use `Effect.annotateLogs` to add a `{ requestId }` annotation, then log the message, then return `"done"`.
+3. Implement `withTracking` -- use `Effect.withSpan` to wrap a computation in a named span.
+
+## Prerequisites
+
+- **003 Generator Pipelines** — `Effect.gen`, `yield*`
+- **011 Services and Context** — `Context.Tag`, service access
+
+## Skills
+
+Invoke `effect-patterns-observability` before teaching this kata.
+
+> **Note**: `Effect.runSync` appears only in tests. Never attribute it to the user's learning.
+
+## Test Map
+
+| Test | Concept | Verifies |
+|------|---------|----------|
+| `logAndReturn logs the message and returns 'done'` | `Effect.log` + sequencing | Custom logger captures "hello"; returns `"done"` |
+| `logWithContext annotates logs with requestId` | `Effect.annotateLogs` + `Effect.log` | Custom logger captures `requestId: "req-1"` annotation |
+| `withTracking preserves the effect result` | `Effect.withSpan` | Wrapping `Effect.succeed(42)` in a span still yields 42 |
+
+## Teaching Approach
+
+### Socratic prompts
+
+- "If you removed all logging calls, would the tests still pass? What does that tell you about how the current tests verify observability?"
+- "If you have a request ID and want every log in that request's scope to include it, how would you avoid passing it to every function manually? How does `annotateLogs` solve this?"
+- "`withSpan` doesn't change the result of the effect. So what *does* it do, and why would you want it in production?"
+
+### Common pitfalls
+
+1. **Effect.log returns void** — `Effect.log("hello")` produces `Effect<void>`. You need to sequence it with the return value using `gen`, `flatMap`, or `andThen`. Writing `return Effect.log(message)` would return `Effect<void>`, not `Effect<string>`. Ask: "What type does `Effect.log` produce? How do you sequence it with returning 'done'?"
+2. **annotateLogs wraps an effect** — `Effect.annotateLogs(effect, { requestId })` adds annotations to ALL logs within that effect's scope. The annotation is the outer wrapper; the logging happens inside. Ask: "Does `annotateLogs` emit a log itself, or does it modify logs emitted by the effect you give it?"
+3. **withSpan is a simple wrapper** — `Effect.withSpan(effect, "name")` or `effect.pipe(Effect.withSpan("name"))` does not change the effect's result. Students may overthink it. Ask: "If you wrap `Effect.succeed(42)` in a span, what value comes out?"
+4. **Argument order** — `Effect.annotateLogs` and `Effect.withSpan` have specific argument orders. Check the types if unsure.
+5. **Sequencing with `Effect.gen`** — for `logAndReturn`, use `Effect.gen`: yield `Effect.log(message)`, then return `"done"`. The same pattern applies to `logWithContext` with `annotateLogs` wrapping the generator.
+
+## On Completion
+
+### Insight
+
+`Effect.log` is structured — it integrates with the runtime's logging system, not just `console.log`. `annotateLogs` adds contextual metadata (like request IDs) that propagates through the entire effect tree. `withSpan` creates tracing spans for performance monitoring. All three are composable and production-ready. The key insight is that observability is a cross-cutting concern that Effect handles declaratively — you add it to your effects without changing their logic or return values.
+
+### Bridge
+
+With observability in place, kata 029 introduces the **HTTP client** pattern — combining services (from kata 011), schema validation (from kata 014), and retry (from kata 016) into a realistic HTTP request pipeline. This is where multiple Effect patterns come together for real-world use.

package/katas/028-logging-and-spans/solution.test.ts

@@ -0,0 +1,50 @@
+import { Effect, Logger, Ref, LogLevel, HashMap } from "effect";
+import { describe, expect, it } from "vitest";
+import { logAndReturn, logWithContext, withTracking } from "@/katas/028-logging-and-spans/solution.js";
+
+// Helper: create a test logger that captures messages to a Ref
+const makeTestLogger = () =>
+  Effect.gen(function* () {
+    const logs = yield* Ref.make<string[]>([]);
+    const logger = Logger.make(({ message }) => {
+      Ref.update(logs, (arr) => [...arr, String(message)]).pipe(Effect.runSync);
+    });
+    return { logs, logger };
+  });
+
+describe("028 — Logging and Spans", () => {
+  it("logAndReturn logs the message and returns 'done'", () =>
+    Effect.gen(function* () {
+      const { logs, logger } = yield* makeTestLogger();
+      const result = yield* logAndReturn("hello").pipe(
+        Logger.withMinimumLogLevel(LogLevel.All),
+        Effect.provide(Logger.replace(Logger.defaultLogger, logger)),
+      );
+      expect(result).toBe("done");
+      const captured = yield* Ref.get(logs);
+      expect(captured).toContain("hello");
+    }).pipe(Effect.runSync));
+
+  it("logWithContext annotates logs with requestId", () =>
+    Effect.gen(function* () {
+      const annotations = yield* Ref.make<Record<string, unknown>>({});
+      const logger = Logger.make(({ annotations: ann }) => {
+        const obj: Record<string, unknown> = {};
+        HashMap.forEach(ann, (value, key) => {
+          obj[key] = value;
+        });
+        Ref.update(annotations, () => obj).pipe(Effect.runSync);
+      });
+      yield* logWithContext("req-1", "processing").pipe(
+        Logger.withMinimumLogLevel(LogLevel.All),
+        Effect.provide(Logger.replace(Logger.defaultLogger, logger)),
+      );
+      const captured = yield* Ref.get(annotations);
+      expect(captured).toHaveProperty("requestId", "req-1");
+    }).pipe(Effect.runSync));
+
+  it("withTracking preserves the effect result", () => {
+    const result = Effect.runSync(withTracking("my-span", Effect.succeed(42)));
+    expect(result).toBe(42);
+  });
+});

package/katas/028-logging-and-spans/solution.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+
+/** Use Effect.log to log a message, then return "done" */
+export const logAndReturn = (message: string): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.annotateLogs to add { requestId } annotation,
+ * then log the message, then return "done" */
+export const logWithContext = (requestId: string, message: string): Effect.Effect<string> => {
+  throw new Error("Not implemented");
+};
+
+/** Use Effect.withSpan to wrap a computation in a named span */
+export const withTracking = <A, E>(
+  name: string,
+  effect: Effect.Effect<A, E>,
+): Effect.Effect<A, E> => {
+  throw new Error("Not implemented");
+};