fix: make all example programs work correctly

- Add string concatenation support to + operator in typechecker
- Register ADT constructors in both type environment and interpreter
- Bind handlers as values so they can be referenced in run...with
- Fix effect checking to use subset instead of exact match
- Add built-in effects (Console, Fail, State) to run block contexts
- Suppress dead code warnings in diagnostics, modules, parser

Update all example programs with:
- Expected output documented in comments
- Proper run...with statements to execute code

Add new example programs:
- behavioral.lux: pure, idempotent, deterministic, commutative functions
- pipelines.lux: pipe operator demonstrations
- statemachine.lux: ADT-based state machines
- tailcall.lux: tail call optimization examples
- traits.lux: type classes and pattern matching

Add documentation:
- docs/IMPLEMENTATION_PLAN.md: feature roadmap and status
- docs/PERFORMANCE_AND_TRADEOFFS.md: performance analysis

Add benchmarks for performance testing.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

examples/behavioral.lux

@@ -0,0 +1,43 @@
+// Demonstrating behavioral properties in Lux
+// Behavioral properties are compile-time guarantees about function behavior
+//
+// Expected output:
+// add(5, 3) = 8
+// clamp(150, 0, 100) = 100
+// factorial(5) = 120
+// multiply(7, 6) = 42
+
+// A pure function - no side effects, same input always gives same output
+fn add(a: Int, b: Int): Int is pure =
+    a + b
+
+// An idempotent function - applying twice gives same result as once
+fn clamp(value: Int, min: Int, max: Int): Int is idempotent =
+    if value < min then min
+    else if value > max then max
+    else value
+
+// A deterministic function - same input always gives same output
+fn factorial(n: Int): Int is deterministic =
+    if n <= 1 then 1
+    else n * factorial(n - 1)
+
+// A commutative function - order of arguments doesn't matter
+fn multiply(a: Int, b: Int): Int is commutative =
+    a * b
+
+// Test the functions
+let sumResult = add(5, 3)
+let clampedResult = clamp(150, 0, 100)
+let factResult = factorial(5)
+let productResult = multiply(7, 6)
+
+// Print results
+fn printResults(): Unit with {Console} = {
+    Console.print("add(5, 3) = " + toString(sumResult))
+    Console.print("clamp(150, 0, 100) = " + toString(clampedResult))
+    Console.print("factorial(5) = " + toString(factResult))
+    Console.print("multiply(7, 6) = " + toString(productResult))
+}
+
+let output = run printResults() with {}

examples/datatypes.lux

@@ -1,4 +1,10 @@
 // Demonstrating algebraic data types and pattern matching
+//
+// Expected output:
+// Tree sum: 8
+// Tree depth: 3
+// Safe divide 10/2: Result: 5
+// Safe divide 10/0: Division by zero!
 
 // Define a binary tree
 type Tree =
@@ -31,7 +37,7 @@ fn depth(tree: Tree): Int =
 // Leaf(1) Leaf(2)
 
 let myTree = Node(Node(Leaf(1), Leaf(2)), Leaf(5))
-let total = sumTree(myTree)
+let treeSum = sumTree(myTree)
 let treeDepth = depth(myTree)
 
 // Option type example
@@ -42,5 +48,15 @@ fn safeDivide(a: Int, b: Int): Option<Int> =
 fn showResult(result: Option<Int>): String =
     match result {
         None => "Division by zero!",
-        Some(n) => "Result: " + n
+        Some(n) => "Result: " + toString(n)
     }
+
+// Print results
+fn printResults(): Unit with {Console} = {
+    Console.print("Tree sum: " + toString(treeSum))
+    Console.print("Tree depth: " + toString(treeDepth))
+    Console.print("Safe divide 10/2: " + showResult(safeDivide(10, 2)))
+    Console.print("Safe divide 10/0: " + showResult(safeDivide(10, 0)))
+}
+
+let output = run printResults() with {}

examples/effects.lux

@@ -1,4 +1,9 @@
 // Demonstrating algebraic effects in Lux
+//
+// Expected output:
+// [info] Processing data...
+// [debug] Result computed
+// Final result: 42
 
 // Define a custom logging effect
 effect Logger {
@@ -20,16 +25,12 @@ handler consoleLogger: Logger {
     fn getLevel() = "debug"
 }
 
-// A handler that ignores logs (for testing)
-handler nullLogger: Logger {
-    fn log(level, msg) = ()
-    fn getLevel() = "none"
-}
-
-// Main function showing handler usage
+// Run and print
 fn main(): Unit with {Console} = {
     let result = run processData(21) with {
         Logger = consoleLogger
     }
-    Console.print("Final result: " + result)
+    Console.print("Final result: " + toString(result))
 }
+
+let output = run main() with {}

examples/factorial.lux

@@ -1,4 +1,6 @@
 // Factorial function demonstrating recursion
+//
+// Expected output: 10! = 3628800
 
 fn factorial(n: Int): Int =
     if n <= 1 then 1
@@ -7,6 +9,8 @@ fn factorial(n: Int): Int =
 // Calculate factorial of 10
 let result = factorial(10)
 
-// Print result
-fn main(): Unit with {Console} =
-    Console.print("10! = " + result)
+// Print result using Console effect
+fn showResult(): Unit with {Console} =
+    Console.print("10! = " + toString(result))
+
+let output = run showResult() with {}

examples/functional.lux

@@ -1,4 +1,12 @@
 // Demonstrating functional programming features
+//
+// Expected output:
+// apply(double, 21) = 42
+// compose(addOne, double)(5) = 11
+// pipe: 5 |> double |> addOne |> square = 121
+// curried add5(10) = 15
+// partial times3(7) = 21
+// record transform = 30
 
 // Higher-order functions
 fn apply(f: fn(Int): Int, x: Int): Int = f(x)
@@ -12,31 +20,43 @@ fn addOne(x: Int): Int = x + 1
 fn square(x: Int): Int = x * x
 
 // Using apply
-let result1 = apply(double, 21)  // 42
+let result1 = apply(double, 21)
 
 // Using compose
 let doubleAndAddOne = compose(addOne, double)
-let result2 = doubleAndAddOne(5)  // 11
+let result2 = doubleAndAddOne(5)
 
 // Using the pipe operator
-let result3 = 5 |> double |> addOne |> square  // ((5 * 2) + 1)^2 = 121
+let result3 = 5 |> double |> addOne |> square
 
 // Currying example
 fn add(a: Int): fn(Int): Int =
     fn(b: Int): Int => a + b
 
 let add5 = add(5)
-let result4 = add5(10)  // 15
+let result4 = add5(10)
 
 // Partial application simulation
 fn multiply(a: Int, b: Int): Int = a * b
 
 let times3 = fn(x: Int): Int => multiply(3, x)
-let result5 = times3(7)  // 21
+let result5 = times3(7)
 
 // Working with records
 let transform = fn(record: { x: Int, y: Int }): Int =>
     record.x + record.y
 
 let point = { x: 10, y: 20 }
-let sum = transform(point)  // 30
+let recordSum = transform(point)
+
+// Print all results
+fn printResults(): Unit with {Console} = {
+    Console.print("apply(double, 21) = " + toString(result1))
+    Console.print("compose(addOne, double)(5) = " + toString(result2))
+    Console.print("pipe: 5 |> double |> addOne |> square = " + toString(result3))
+    Console.print("curried add5(10) = " + toString(result4))
+    Console.print("partial times3(7) = " + toString(result5))
+    Console.print("record transform = " + toString(recordSum))
+}
+
+let output = run printResults() with {}

examples/hello.lux

@@ -1,5 +1,10 @@
 // Hello World in Lux
 // Demonstrates basic effect usage
+//
+// Expected output: Hello, World!
 
-fn main(): Unit with {Console} =
+fn greet(): Unit with {Console} =
     Console.print("Hello, World!")
+
+// Run the greeting with the Console effect
+let output = run greet() with {}

examples/pipelines.lux

@@ -0,0 +1,55 @@
+// Demonstrating the pipe operator and functional data processing
+//
+// Expected output:
+// 5 |> double |> addTen |> square = 400
+// Pipeline result2 = 42
+// process(1) = 144
+// process(2) = 196
+// process(3) = 256
+// clamped = 0
+// composed = 121
+
+// Basic transformations
+fn double(x: Int): Int = x * 2
+fn addTen(x: Int): Int = x + 10
+fn square(x: Int): Int = x * x
+fn negate(x: Int): Int = -x
+
+// Using the pipe operator for data transformation
+let result1 = 5 |> double |> addTen |> square
+
+// Chaining multiple operations
+let result2 = 3 |> double |> addTen |> double |> addTen
+
+// More complex pipelines
+fn process(n: Int): Int =
+    n |> double |> addTen |> square
+
+// Multiple values through same pipeline
+let a = process(1)
+let b = process(2)
+let c = process(3)
+
+// Conditional in pipeline
+fn clampPositive(x: Int): Int =
+    if x < 0 then 0 else x
+
+let clamped = -5 |> double |> clampPositive
+
+// Function composition using pipe
+fn increment(x: Int): Int = x + 1
+
+let composed = 5 |> double |> increment |> square
+
+// Print results
+fn printResults(): Unit with {Console} = {
+    Console.print("5 |> double |> addTen |> square = " + toString(result1))
+    Console.print("Pipeline result2 = " + toString(result2))
+    Console.print("process(1) = " + toString(a))
+    Console.print("process(2) = " + toString(b))
+    Console.print("process(3) = " + toString(c))
+    Console.print("clamped = " + toString(clamped))
+    Console.print("composed = " + toString(composed))
+}
+
+let output = run printResults() with {}

examples/statemachine.lux

@@ -0,0 +1,83 @@
+// State machine example using algebraic data types
+// Demonstrates pattern matching for state transitions
+//
+// Expected output:
+// Initial light: red
+// After transition: green
+// After two transitions: yellow
+// Door: Closed -> Open -> Closed -> Locked
+
+// Traffic light state machine
+type TrafficLight =
+    | Red
+    | Yellow
+    | Green
+
+fn nextLight(light: TrafficLight): TrafficLight =
+    match light {
+        Red => Green,
+        Green => Yellow,
+        Yellow => Red
+    }
+
+fn canGo(light: TrafficLight): Bool =
+    match light {
+        Green => true,
+        Yellow => false,
+        Red => false
+    }
+
+fn lightColor(light: TrafficLight): String =
+    match light {
+        Red => "red",
+        Yellow => "yellow",
+        Green => "green"
+    }
+
+// Door state machine
+type DoorState =
+    | Open
+    | Closed
+    | Locked
+
+type DoorAction =
+    | OpenDoor
+    | CloseDoor
+    | LockDoor
+    | UnlockDoor
+
+fn applyAction(state: DoorState, action: DoorAction): DoorState =
+    match (state, action) {
+        (Closed, OpenDoor) => Open,
+        (Open, CloseDoor) => Closed,
+        (Closed, LockDoor) => Locked,
+        (Locked, UnlockDoor) => Closed,
+        _ => state
+    }
+
+fn doorStateName(state: DoorState): String =
+    match state {
+        Open => "Open",
+        Closed => "Closed",
+        Locked => "Locked"
+    }
+
+// Test the state machines
+let light1 = Red
+let light2 = nextLight(light1)
+let light3 = nextLight(light2)
+
+let door1 = Closed
+let door2 = applyAction(door1, OpenDoor)
+let door3 = applyAction(door2, CloseDoor)
+let door4 = applyAction(door3, LockDoor)
+
+// Print results
+fn printResults(): Unit with {Console} = {
+    Console.print("Initial light: " + lightColor(light1))
+    Console.print("After transition: " + lightColor(light2))
+    Console.print("After two transitions: " + lightColor(light3))
+    Console.print("Door: " + doorStateName(door1) + " -> " + doorStateName(door2) + " -> " + doorStateName(door3) + " -> " + doorStateName(door4))
+}
+
+let output = run printResults() with {}

examples/tailcall.lux

@@ -0,0 +1,50 @@
+// Demonstrating tail call optimization (TCO) in Lux
+// TCO allows recursive functions to run in constant stack space
+//
+// Expected output:
+// factorial(20) = 2432902008176640000
+// fib(30) = 832040
+// sumTo(1000) = 500500
+// countdown(10000) completed
+
+// Factorial with accumulator - tail recursive
+fn factorialTCO(n: Int, acc: Int): Int =
+    if n <= 1 then acc
+    else factorialTCO(n - 1, n * acc)
+
+fn factorial(n: Int): Int = factorialTCO(n, 1)
+
+// Fibonacci with accumulator - tail recursive
+fn fibTCO(n: Int, a: Int, b: Int): Int =
+    if n <= 0 then a
+    else fibTCO(n - 1, b, a + b)
+
+fn fib(n: Int): Int = fibTCO(n, 0, 1)
+
+// Count down - simple tail recursion
+fn countdown(n: Int): Int =
+    if n <= 0 then 0
+    else countdown(n - 1)
+
+// Sum with accumulator - tail recursive
+fn sumToTCO(n: Int, acc: Int): Int =
+    if n <= 0 then acc
+    else sumToTCO(n - 1, acc + n)
+
+fn sumTo(n: Int): Int = sumToTCO(n, 0)
+
+// Test the functions
+let fact20 = factorial(20)
+let fib30 = fib(30)
+let sum1000 = sumTo(1000)
+let countResult = countdown(10000)
+
+// Print results
+fn printResults(): Unit with {Console} = {
+    Console.print("factorial(20) = " + toString(fact20))
+    Console.print("fib(30) = " + toString(fib30))
+    Console.print("sumTo(1000) = " + toString(sum1000))
+    Console.print("countdown(10000) completed")
+}
+
+let output = run printResults() with {}

examples/traits.lux

@@ -0,0 +1,45 @@
+// Demonstrating type classes (traits) in Lux
+//
+// Expected output:
+// RGB color: rgb(255,128,0)
+// Red color: red
+// Green color: green
+
+// Define a simple Printable trait
+trait Printable {
+    fn format(value: Int): String
+}
+
+// Implement Printable
+impl Printable for Int {
+    fn format(value: Int): String = "Number: " + toString(value)
+}
+
+// A Color type with pattern matching
+type Color =
+    | Red
+    | Green
+    | Blue
+    | RGB(Int, Int, Int)
+
+fn colorName(c: Color): String =
+    match c {
+        Red => "red",
+        Green => "green",
+        Blue => "blue",
+        RGB(r, g, b) => "rgb(" + toString(r) + "," + toString(g) + "," + toString(b) + ")"
+    }
+
+// Test
+let myColor = RGB(255, 128, 0)
+let redColor = Red
+let greenColor = Green
+
+// Print results
+fn printResults(): Unit with {Console} = {
+    Console.print("RGB color: " + colorName(myColor))
+    Console.print("Red color: " + colorName(redColor))
+    Console.print("Green color: " + colorName(greenColor))
+}
+
+let output = run printResults() with {}