New rules

Author: adamw

cursor-rules/100-ox-direct-style-overview.mdc

@@ -0,0 +1,48 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Ox Library Overview
+
+Ox is a Scala 3 library for **safe direct-style streaming, concurrency and resiliency** on the JVM. Requires JDK 21+ and Scala 3.
+
+## Key Concepts
+
+**Direct-Style Programming**: Write blocking-style code using virtual threads instead of async/await or reactive streams. This provides readable, debuggable code without callback hell.
+
+**Dual Error Handling**: 
+- Use **exceptions** for bugs and unexpected situations
+- Use **Either values** for application logic errors with `.ok()` unwrapping
+
+**Structured Concurrency**: All concurrent operations happen within high-level operations or low-level scopes that ensure proper cleanup and resource management.
+
+**Streaming with Flows**: Use `Flow[T]` for lazy, composable, reactive-streams compatible data transformation pipelines with built-in concurrency control.
+
+## Common Patterns
+
+```scala
+// High-level concurrency
+val result = par(computation1, computation2)
+val winner = raceSuccess(comp1, comp2)
+
+// Streaming transformations  
+Flow.fromValues(1, 2, 3)
+  .mapPar(4)(process)
+  .filter(_ > 0)
+  .runForeach(println)
+
+// Error handling with Either
+val result: Either[String, Int] = either:
+  val user = lookupUser(id).ok()
+  val org = lookupOrg(id).ok()
+  calculateResult(user, org)
+
+// Structured concurrency scopes
+supervised:
+  val f1 = fork { longRunningTask1() }
+  val f2 = fork { longRunningTask2() }
+  (f1.join(), f2.join())
+```
+
+Ox emphasizes safety, composability and readability while providing high performance through virtual threads.

cursor-rules/110-ox-high-level-concurrency-ops.mdc

@@ -0,0 +1,74 @@
+---
+description: Prefer high-level operations like `par()`, `race()`, and `timeout()` for concurrent programming instead of manual fork management. These operations handle error propagation, interruption, and resource cleanup automatically. Use `.mapPar`, `.filterPar` and `.collectPar` on large collections for added performance.
+globs: 
+alwaysApply: false
+---
+# High-Level Concurrency Operations
+
+**Prefer high-level concurrency operations** over manual fork management. These operations automatically handle error propagation, interruption, and resource cleanup.
+
+## Core Operations
+
+**Parallel execution** with `par()`:
+```scala
+import ox.{par, sleep}
+import scala.concurrent.duration.*
+
+val result: (Int, String) = par(
+  { sleep(2.seconds); 1 },
+  { sleep(1.second); "done" }
+)
+```
+
+**Racing computations** with `race()` and `raceSuccess()`:
+```scala
+import ox.{raceSuccess, timeout}
+
+val winner = raceSuccess(
+  computation1,
+  timeout(1.second)(computation2)
+)
+```
+
+**Timeouts** with automatic interruption:
+```scala
+import ox.{timeout, either}
+
+val result = either.catching:
+  timeout(5.seconds)(longRunningTask())
+```
+
+## Collection Operations
+
+**Use parallel collection operations** for improved performance:
+```scala
+// Instead of manual forking
+val results = items.mapPar(4)(process)        // parallel map
+val filtered = items.filterPar(8)(predicate)  // parallel filter  
+val collected = items.collectPar(2)(partial)  // parallel collect
+```
+
+## Error Handling
+
+High-level operations **automatically handle failures**:
+- Failed computations interrupt others
+- Resources are properly cleaned up
+- Original exceptions are preserved and re-thrown
+- `parEither` variant supports application errors
+
+**Good**: Using high-level operations
+```scala
+val result = parEither(
+  { sleep(100.millis); Right("ok") },
+  { sleep(200.millis); Left("error") }
+)
+```
+
+**Avoid**: Manual fork management for simple parallel operations
+```scala
+// Don't do this for simple cases
+supervised:
+  val f1 = fork(computation1)
+  val f2 = fork(computation2) 
+  (f1.join(), f2.join())
+```

cursor-rules/111-ox-dual-error-handling.mdc

@@ -0,0 +1,86 @@
+---
+description: Use exceptions for bugs/unexpected situations and use `Either` values for application logic errors. Use Rust-like `either` blocks with `.ok()` to unwrap `Either` values with automatic short-circuiting. Combine different error types using union types (`Either[Int | Long, String]`) and avoid nested `either` blocks in the same scope.
+globs: 
+alwaysApply: false
+---
+# Dual Error Handling
+
+Ox uses **two channels for error handling**:
+1. **Exceptions**: for bugs, unexpected situations, Java library integration
+2. **Either values**: for application logic errors (typed, explicit)
+
+## Either Blocks with `.ok()` Unwrapping
+
+**Use `either` blocks** for Rust-like error handling with automatic short-circuiting:
+
+```scala
+import ox.either
+import ox.either.ok
+
+case class User()
+case class Organization()
+
+def lookupUser(id: Int): Either[String, User] = ???
+def lookupOrganization(id: Int): Either[String, Organization] = ???
+
+// Automatic short-circuiting on first Left value
+val result: Either[String, Assignment] = either:
+  val user = lookupUser(1).ok()      // unwraps Right, or short-circuits on Left
+  val org = lookupOrganization(2).ok()
+  Assignment(user, org)
+```
+
+## Union Types for Multiple Error Types
+
+**Combine different error types** using union types:
+
+```scala
+val v1: Either[Int, String] = ???
+val v2: Either[Long, String] = ???
+
+val result: Either[Int | Long, String] = either:
+  v1.ok() ++ v2.ok()  // Error type becomes Int | Long
+```
+
+## Converting Exceptions to Either
+
+**Convert exception-throwing code** using `either.catching`:
+
+```scala
+val result: Either[Throwable, String] = either.catching:
+  riskyOperation()  // catches non-fatal exceptions
+```
+
+## Important: Avoid Nested `either` Blocks
+
+**Don't nest `either` blocks** in the same scope - this can cause surprising behavior after refactoring:
+
+```scala
+// BAD: Nested either blocks
+val outerResult: Either[Exception, Unit] = either:
+  val innerResult: Either[String, Int] = either:  // DON'T DO THIS
+    returnsEither.ok()  // Which either block does this target?
+    // ...
+  ()
+
+// GOOD: Extract to separate function
+def innerLogic(): Either[String, Int] = either:
+  returnsEither.ok()
+
+val outerResult: Either[Exception, Unit] = either:
+  val innerResult = innerLogic()
+  ()
+```
+
+## When to Use Each Approach
+
+**Use exceptions for**:
+- Programming bugs
+- Unexpected system failures  
+- Java library integration
+
+**Use Either for**:
+- Expected application errors
+- Validation failures
+- Business logic errors
+- When you want explicit error types in signatures

cursor-rules/120-ox-streaming-flows-over-channels.mdc

@@ -0,0 +1,106 @@
+---
+description: Use Flows for functional-style streaming transformations with methods like `map`, `mapPar`, `filter`, `groupBy` and many others. Flows are lazy, composable, and manage concurrency declaratively and efficiently. Flows only start processing data when run.
+globs: 
+alwaysApply: false
+---
+# Streaming: Prefer Flows Over Channels
+
+**Use `Flow[T]` for streaming data transformations** instead of low-level channel operations. Flows provide a functional, composable API with built-in concurrency management.
+
+## Flow Characteristics
+
+**Flows are lazy**: No processing happens until `.run*()` methods are called
+```scala
+import ox.flow.Flow
+
+// This just describes the pipeline - nothing executes yet
+val pipeline = Flow.fromValues(1, 2, 3)
+  .map(_ * 2)
+  .filter(_ > 2)
+
+// Processing happens here
+val result = pipeline.runToList()  // List(4, 6)
+```
+
+## Creating Flows
+
+**Multiple ways to create flows**:
+```scala
+import ox.flow.Flow
+import scala.concurrent.duration.*
+
+// From values
+Flow.fromValues(1, 2, 3)
+
+// Infinite flows  
+Flow.tick(1.second, "heartbeat")
+Flow.iterate(0)(_ + 1)  // natural numbers
+
+// From channels
+Flow.fromSource(channel)
+
+// Custom emission logic
+Flow.usingEmit: emit =>
+  emit(1)
+  for i <- 4 to 50 do emit(i)
+  if condition() then emit(42)
+```
+
+## Functional Transformations
+
+**Rich transformation API** similar to Scala collections:
+```scala
+Flow.fromValues(1, 2, 3, 4, 5)
+  .map(_ * 2)
+  .filter(_ % 4 == 0)
+  .take(3)
+  .zip(Flow.repeat("item"))
+  .interleave(Flow.fromValues((0, "other")))
+  .runForeach(println)
+```
+
+## Built-in Concurrency Management
+
+**Flows handle concurrency declaratively**:
+```scala
+// Parallel processing with controlled concurrency
+Flow.fromValues(urls)
+  .mapPar(4)(sendHttpRequest)  // max 4 concurrent requests
+  .filter(_.isSuccess)
+  .runDrain()
+
+// Asynchronous boundaries with buffering
+Flow.fromSource(inputChannel)
+  .buffer(capacity = 100)  // explicit async boundary
+  .mapPar(8)(process)
+  .runToChannel()
+```
+
+## When to Use Channels Directly
+
+**Use low-level channels only for**:
+- Go-like inter-thread communication patterns
+- Custom coordination with `select` operations  
+- Bridging callback-based APIs
+- Building custom flow operations
+
+**Good**: Flow-based streaming
+```scala
+Flow.fromInputStream(inputStream)
+  .linesUtf8
+  .mapPar(parallelism)(processLine)
+  .runForeach(println)
+```
+
+**Avoid**: Manual channel coordination for simple transformations
+```scala
+// Don't do this for simple transformations
+val ch1 = Channel.buffered[String](mdc:10)
+val ch2 = Channel.buffered[Int](mdc:10)
+fork:
+  ch1.drain(): line =>
+    ch2.send(line.length)
+  ch2.done()
+```
+
+Flows provide **safety, composability, and performance** with a familiar functional API.