@zio.dev/zio-blocks 0.0.1 → 0.0.21

package/scope.md

@@ -2,10 +2,12 @@
 
 `zio.blocks.scope` provides **compile-time verified resource safety** for synchronous code by tagging values with an unnameable, type-level **scope identity**. Values allocated in a scope can only be used when you hold a compatible `Scope`, and values allocated in a *child* scope cannot be returned to the parent in a usable form.
 
+**Structured scopes.** Scopes follow the structured-concurrency philosophy: child scopes are nested within parent scopes, resources are tied to the lifetime of the scope that allocated them, and cleanup happens deterministically when the scope exits (finalizers run LIFO). This "nesting = lifetime" structure provides clear ownership boundaries in addition to compile-time leak prevention.
+
 If you've used `try/finally`, `Using`, or ZIO `Scope`, this library lives in the same problem space, but it focuses on:
 
 - **Compile-time prevention of scope leaks**
-- **Zero runtime overhead for the scoped tag** (`A @@ S` is represented as `A`)
+- **Unified scoped type** (`A @@ S` is a type alias for `Scoped[A, S]`)
 - **Simple, synchronous lifecycle management** (finalizers run LIFO on scope close)
 
 ---
@@ -17,10 +19,10 @@ If you've used `try/finally`, `Using`, or ZIO `Scope`, this library lives in the
   - [1) `Scope[ParentTag, Tag]`](#1-scopeparenttag-tag)
   - [2) Scoped values: `A @@ S`](#2-scoped-values-a--s)
   - [3) `Resource[A]`: acquisition + finalization](#3-resourcea-acquisition--finalization)
-  - [4) `Scoped[Tag, A]`: deferred computations](#4-scopedtag-a-deferred-computations)
-  - [5) `ScopeEscape` and `Unscoped`: what may escape](#5-scopeescape-and-unscoped-what-may-escape)
-  - [6) `Wire[-In, +Out]`: dependency recipes](#6-wire-in-out-dependency-recipes)
-  - [7) `Wireable[Out]`: DI for traits/abstract classes](#7-wireableout-di-for-traitsabstract-classes)
+  - [4) `A @@ S`: unified scoped type](#4-a--s-unified-scoped-type)
+  - [5) `Unscoped`: marking pure data types](#5-unscoped-marking-pure-data-types)
+  - [6) `ScopeLift[A, S]`: what may return from child scopes](#6-scopelifta-s-what-may-return-from-child-scopes)
+  - [7) `Wire[-In, +Out]`: dependency recipes](#7-wire-in-out-dependency-recipes)
 - [Safety model (why leaking is prevented)](#safety-model-why-leaking-is-prevented)
 - [Usage examples](#usage-examples)
   - [Allocating and using a resource](#allocating-and-using-a-resource)
@@ -28,9 +30,10 @@ If you've used `try/finally`, `Using`, or ZIO `Scope`, this library lives in the
   - [Building a `Scoped` program (map/flatMap)](#building-a-scoped-program-mapflatmap)
   - [Registering cleanup manually with `defer`](#registering-cleanup-manually-with-defer)
   - [Dependency injection with `Wire` + `Context`](#dependency-injection-with-wire--context)
-  - [Supplying dependencies with `Resource.from[T](wire1, wire2, ...)`](#supplying-dependencies-with-resourcefromtwire1-wire2-)
-  - [DI for traits via `Wireable`](#di-for-traits-via-wireable)
+  - [Dependency injection with `Resource.from[T](wires*)`](#dependency-injection-with-resourcefromtwires)
+  - [Injecting traits via subtype wires](#injecting-traits-via-subtype-wires)
   - [Interop escape hatch: `leak`](#interop-escape-hatch-leak)
+- [Common compile errors](#common-compile-errors)
 - [API reference (selected)](#api-reference-selected)
 
 ---
@@ -49,10 +52,12 @@ Scope.global.scoped { scope =>
   val db: Database @@ scope.Tag =
     scope.allocate(Resource(new Database))
 
-  val result: String =
-    scope.$(db)(_.query("SELECT 1"))
-
-  println(result)
+  // $ executes immediately and returns String @@ scope.Tag
+  // Use the function to work with the value
+  (scope $ db) { database =>
+    val result = database.query("SELECT 1")
+    println(result)
+  }
 }
 ```
 
@@ -60,7 +65,8 @@ Key things to notice:
 
 - `scope.allocate(...)` returns a **scoped** value: `Database @@ scope.Tag`
 - You **cannot** call `db.query(...)` directly (methods are intentionally hidden)
-- You must use `scope.$(db)(...)` or build a `Scoped` computation
+- You must use `(scope $ db) { ... }` to access the value - the function executes immediately
+- `$` and `execute` always return scoped values (`B @@ scope.Tag`), never raw values
 - When the `scoped { ... }` block exits, finalizers run **LIFO** and errors are handled safely
 
 ---
@@ -102,24 +108,33 @@ object Scope {
 
 - The global scope is intended to live for the lifetime of the process.
 - Its finalizers run on JVM shutdown.
-- Values allocated in `Scope.global` typically **escape** as raw values via `ScopeEscape` (see below).
+- Values allocated in `Scope.global` can escape as raw values via `ScopeLift.globalScope` (see below).
 
 ---
 
 ### 2) Scoped values: `A @@ S`
 
-`A @@ S` means: "a value of type `A` that is locked to scope tag `S`".
+`A @@ S` is a type alias for `Scoped[A, S]` — a handle to a value of type `A` that is locked to scope tag `S`.
 
-- **Runtime representation:** just `A` (no wrapper allocation)
-- **Key effect:** methods on `A` are hidden, so you can't call `a.method` without proving scope access
+- **Runtime representation:** a boxed thunk (lightweight wrapper)
+- **Key effect:** methods on `A` are hidden; you can't call `a.method` directly
+- **Acquisition timing:** `scope.allocate(resource)` acquires the resource **immediately** (eagerly) and returns a scoped handle for accessing the already-acquired value. The thunk defers *access*, not *acquisition*.
 - **Access paths:**
-  - `scope.$(a)(f)` to use a scoped value immediately
-  - `a.map / a.flatMap` to build a `Scoped` computation, then run it via `scope(scoped)`
+  - `(scope $ a)(f)` to execute and apply a function immediately
+  - `a.map / a.flatMap` to build composite scoped computations
+  - `scope.execute(scoped)` to run a composed computation
 
-#### Scala 3 vs Scala 2 note
+#### Scala 2 note
 
-- In **Scala 3**, `@@` is implemented as an `opaque` type.
-- In **Scala 2**, the library emulates the same "opaque-like" behavior using the *module pattern* (still zero-overhead at runtime).
+In Scala 2, explicit type annotations are required when assigning scoped values to avoid existential type inference issues:
+
+```scala
+// Scala 2 requires explicit type annotation
+val db: Database @@ scope.Tag = scope.allocate(Resource[Database])
+
+// Scala 3 can infer the type
+val db = scope.allocate(Resource[Database])
+```
 
 ---
 
@@ -139,12 +154,12 @@ Common constructors:
   - Explicit lifecycle.
 - `Resource.fromAutoCloseable(thunk)`
   - A type-safe helper for `AutoCloseable`.
-- `Resource.from[T]` (macro)
-  - Derives a resource from `T`'s constructor.
-  - If `T` is `AutoCloseable`, registers `close()` automatically.
-  - If `T` has dependencies, either:
-    - use `Wire` + `toResource(deps)`, or
-    - use `Resource.from[T](wire1, wire2, ...)` (see below).
+- `Resource.from[T](wires*)` (macro)
+  - The primary entry point for dependency injection.
+  - Resolves `T` and all its dependencies into a single `Resource[T]`.
+  - Auto-creates missing wires using `Wire.shared` for concrete classes.
+  - Requires explicit wires for: primitives, functions, collections, and abstract types.
+  - If `T` or any dependency is `AutoCloseable`, registers `close()` automatically.
 
 #### Resource "sharing" vs "uniqueness"
 
@@ -162,93 +177,172 @@ Common constructors:
 
 ---
 
-### 4) `Scoped[Tag, A]`: deferred computations
+### 4) `A @@ S`: unified scoped type
 
-`Scoped[-Tag, +A]` represents a computation that produces `A`, but can only be executed by a scope whose tag is compatible with `Tag`.
+`A @@ S` (type alias for `Scoped[A, S]`) is the core type representing a deferred computation that produces `A` and requires scope tag `S` to execute.
 
 Execution happens via:
 
 ```scala
-scope(scopedComputation)
+scope.execute(scopedComputation)
 ```
 
 How to build them:
 
-- From scoped values:
-  - `val s: Scoped[S, B] = (a: A @@ S).map(f)`
-  - `flatMap` composes scoped values while tracking combined requirements
-- Or directly:
-  - `Scoped.create(() => ...)` (advanced/internal style)
+- From `scope.allocate`:
+  - `scope.allocate(resource)` returns `A @@ scope.Tag`
+- Using combinators:
+  - `(a: A @@ S).map(f: A => B)` returns `B @@ S`
+  - `(a: A @@ S).flatMap(f: A => B @@ T)` returns `B @@ (S & T)` (Scala 3) / `B @@ (S with T)` (Scala 2)
+  - Use for-comprehensions to chain scoped computations
+- From ordinary values:
+  - `Scoped(value)` lifts a value into an `A @@ Any` (which can be used anywhere due to contravariance)
+
+**Contravariance:** `A @@ S` is contravariant in `S`. This means `A @@ ParentTag` is a subtype of `A @@ ChildTag` when `ChildTag <: ParentTag`. Child scopes can execute parent-scoped computations automatically.
+
+**For-comprehension example:**
+
+```scala
+Scope.global.scoped { scope =>
+  val program: Result @@ scope.Tag = for {
+    pool <- scope.allocate(Resource[Pool])
+    conn <- scope.allocate(Resource(pool.lease()))
+    data <- conn.map(_.query("SELECT *"))
+  } yield process(data)
+
+  scope.execute(program)
+}
+```
+
+---
+
+### 5) `Unscoped`: marking pure data types
+
+The `Unscoped[A]` typeclass marks types as pure data that don't hold resources. This is used by `ScopeLift` to determine what can escape from child scopes.
+
+**Built-in Unscoped types:**
+- Primitives: `Int`, `Long`, `Boolean`, `Double`, etc.
+- `String`, `Unit`, `Nothing`
+- Collections of Unscoped types
+
+**Custom Unscoped types:**
+```scala
+case class Config(debug: Boolean)
+object Config {
+  given Unscoped[Config] = Unscoped.derived
+}
+```
 
-`Scoped` is contravariant in `Tag`, which is what allows a **child** scope (more specific tag) to run computations that only require a **parent** tag.
+**Important:** `$` and `execute` always return `B @@ scope.Tag`. They never escape values directly. Escape only happens at the `.scoped` boundary via `ScopeLift`.
 
 ---
 
-### 5) `ScopeEscape` and `Unscoped`: what may escape
+### 6) `ScopeLift[A, S]`: what may return from child scopes
+
+When you call `scope.scoped { child => ... }`, the return type `A` must have a `ScopeLift[A, S]` instance where `S` is the parent scope's tag. This typeclass both **gates** what can exit child scopes and **transforms** the return type.
+
+**ScopeLift instances and their behavior:**
+
+| Instance | Matches | Output Type |
+|----------|---------|-------------|
+| `globalScope[A]` | Any `A` when `S = GlobalTag` | `A` (unchanged) |
+| `nothing[S]` | `Nothing` | `Nothing` |
+| `unscoped[A, S]` | `A` with `Unscoped[A]` | `A` (raw value) |
+| `scoped[B, T, S]` | `B @@ T` when `S <:< T` | `B @@ T` (unchanged) |
 
-Whenever you access a scoped value via:
+**Allowed return types:**
 
-- `scope.$(value)(f)`, or
-- `scope(scopedComputation)`,
+- **`Unscoped` types**: Pure data lifts to raw `A`
+- **Parent-scoped values**: `B @@ T` where `S <:< T` lifts as-is
+- **`Nothing`**: For blocks that throw
+- **Anything from global scope**: Global scope never closes
 
-…the return type is controlled by `ScopeEscape[A, S]`, which decides whether a result:
+**Rejected return types (no ScopeLift instance):**
 
-- escapes as raw `A`, or
-- remains tracked as `A @@ S`.
+- **Closures**: `() => A` could capture the child scope
+- **Child-scoped values**: `B @@ child.Tag` would be use-after-close
+- **The scope itself**: Would allow operations after close
 
-Rule of thumb:
+```scala
+Scope.global.scoped { parent =>
+  // ✅ OK: String is Unscoped - lifts to raw String
+  val result: String = parent.scoped { child =>
+    "hello"  // Return raw Unscoped value
+  }
+
+  // ✅ OK: parent-tagged value outlives child - lifts as-is
+  val parentDb: Database @@ parent.Tag = parent.allocate(Resource[Database])
+  val same: Database @@ parent.Tag = parent.scoped { _ =>
+    parentDb
+  }
 
-- Pure data (e.g. `Int`, `String`, small case classes you mark `Unscoped`) should escape as raw values.
-- Resource-like values should remain scoped unless you explicitly `leak`.
+  // ❌ COMPILE ERROR: closure has no ScopeLift instance
+  // val leak = parent.scoped { child =>
+  //   val db = child.allocate(Resource[Database])
+  //   () => println("captured!")  // Function types rejected
+  // }
+
+  // ❌ COMPILE ERROR: child-scoped value has no ScopeLift instance
+  // val escaped = parent.scoped { child =>
+  //   child.allocate(Resource[Database])  // Database @@ child.Tag can't escape
+  // }
+}
+```
 
 ---
 
-### 6) `Wire[-In, +Out]`: dependency recipes
+### 7) `Wire[-In, +Out]`: dependency recipes
 
-`Wire` is a recipe for constructing services, commonly used for dependency injection.
+`Wire` is a recipe for constructing services. It describes **how** to build a service given its dependencies, but does not resolve those dependencies itself.
 
 - `In` is the required dependencies (provided as a `Context[In]`)
 - `Out` is the produced service
 
 There are two wire flavors:
 
-- `Wire.Shared`: a shared recipe
-- `Wire.Unique`: a unique recipe
+- `Wire.Shared`: produces a shared (memoized) instance
+- `Wire.Unique`: produces a fresh instance each time
 
-**Important clarification:** `Wire` itself is just a recipe. The actual memoization/sharing behavior happens when you convert the wire into a `Resource`:
+**Important clarification:** `Wire` itself is just a recipe. The sharing/uniqueness behavior is realized when the wire is used inside `Resource.from`, which composes `Resource.Shared` or `Resource.Unique` instances accordingly.
 
-```scala
-val r: Resource[Out] = wire.toResource(deps)
-val out: Out @@ scope.Tag = scope.allocate(r)
-```
+#### Creating wires
 
-- `Wire.Shared#toResource` produces a `Resource.Shared`, which is where the reference-counted sharing is implemented.
-- `Wire.Unique#toResource` produces a `Resource.Unique`.
+There are exactly **3 macro entry points**:
 
-Macros available at package level:
+| Macro | Purpose |
+|-------|---------|
+| `Wire.shared[T]` | Create a shared wire from `T`'s constructor |
+| `Wire.unique[T]` | Create a unique wire from `T`'s constructor |
+| `Resource.from[T](wires*)` | Wire up `T` and all dependencies into a `Resource` |
 
-- `shared[T]`: derive a shared wire from `T`'s constructor (or from a `Wireable[T]` if present)
-- `unique[T]`: derive a unique wire
+For wrapping pre-existing values:
 
----
+- `Wire(value)` — wraps a value; if `AutoCloseable`, registers `close()` automatically
+
+#### How `Resource.from[T](wires*)` works
 
-### 7) `Wireable[Out]`: DI for traits/abstract classes
+1. **Collect wires**: Uses explicit wires when provided, otherwise auto-creates with `Wire.shared`
+2. **Validate**: Checks for cycles, unmakeable types, duplicate providers
+3. **Topological sort**: Orders dependencies so leaves are allocated first
+4. **Generate composition**: Produces a `Resource[T]` via flatMap chains
 
-`shared[T]` / `unique[T]` can derive wires from **concrete classes** with constructors. But traits and abstract classes are not instantiable, so you need a way to tell the macros "when someone asks for `T`, build it like *this*".
+Key insight: **Compose Resources, don't accumulate values.** Each wire becomes a `Resource`, and they are composed via `flatMap`. This correctly preserves:
 
-That's what `Wireable[T]` is: a typeclass that supplies a `Wire` for a service.
+- **Sharing**: Same `Resource.Shared` instance → same value (even in diamond patterns)
+- **Uniqueness**: `Resource.Unique` → fresh value per injection site
 
-Typical use:
+#### Subtype resolution
 
-- Define a `Wireable[MyTrait]` in `MyTrait`'s companion object.
-- `shared[MyTrait]` or `unique[MyTrait]` will pick it up automatically.
+When `Resource.from` needs a dependency of type `Service`, it will accept a wire whose output is a subtype (e.g., `Wire.shared[LiveService]` where `LiveService extends Service`). This enables trait injection without extra boilerplate.
 
-This is especially useful when you want to inject an interface but construct a concrete implementation (and still register finalizers correctly).
+If the same concrete wire satisfies multiple types (e.g., `Service` and `LiveService`), only **one instance** is created and reused for both.
 
 ---
 
 ## Safety model (why leaking is prevented)
 
+**Pragmatic safety.** The type-level tagging prevents *accidental* scope misuse in normal code, but it is not a security boundary. A determined developer can bypass it via `leak` (which emits a compiler warning), unsafe casts (`asInstanceOf`), or storing scoped references in mutable state (`var`). The guarantees are "good enough" to catch mistakes in regular usage, not protection against intentional circumvention.
+
 The library prevents scope leaks via two reinforcing mechanisms:
 
 ### A) Existential child tags (fresh, unnameable types)
@@ -268,9 +362,11 @@ The child scope has an existential tag (fresh per invocation). You can allocate
 Compile-time safety is verified in tests, e.g.:
 `ScopeCompileTimeSafetyScala3Spec`.
 
-### B) Tag invariance + "opaque-like" `@@` blocks subtyping escape
+### B) Contravariance prevents child-to-parent widening
 
-Even if you try to "widen" a child-tagged value to a parent-tagged value, invariance and hidden members prevent it from typechecking. The only sanctioned access route is through `scope.$` / `scope.apply`, which require tag evidence.
+`A @@ S` is contravariant in `S`. This means `Db @@ child.Tag` is **not** a subtype of `Db @@ parent.Tag` — the subtyping goes the *other* direction. A child scope can use parent-tagged values (because `child.Tag <: parent.Tag` makes `A @@ parent.Tag <: A @@ child.Tag`), but you cannot widen a child-tagged value to a parent tag.
+
+Additionally, the thunk-based representation hides `A`'s methods — you can't call `db.query(...)` directly on a `Database @@ scope.Tag`. The only sanctioned access routes are `scope.$` and `scope.execute`, which require a scope with a compatible tag.
 
 ---
 
@@ -289,10 +385,11 @@ final class FileHandle(path: String) extends AutoCloseable {
 Scope.global.scoped { scope =>
   val h = scope.allocate(Resource(new FileHandle("data.txt")))
 
-  val contents: String =
-    scope.$(h)(_.readAll())
-
-  println(contents)
+  // $ executes immediately - work with the value inside the function
+  (scope $ h) { handle =>
+    val contents = handle.readAll()
+    println(contents)
+  }
 }
 ```
 
@@ -308,23 +405,28 @@ Scope.global.scoped { parent =>
 
   parent.scoped { child =>
     // child can use parent-scoped values:
-    val ok: String = child.$(parentDb)(_.query("SELECT 1"))
-    println(ok)
+    child.$(parentDb) { db =>
+      println(db.query("SELECT 1"))
+    }
 
     val childDb = child.allocate(Resource(new Database))
 
     // You can use childDb *inside* the child:
-    val ok2: String = child.$(childDb)(_.query("SELECT 2"))
-    println(ok2)
-
-    // But you cannot return childDb to the parent in a usable way:
-    // childDb : Database @@ child.Tag
-    // parent cannot prove parent.Tag <:< child.Tag
+    child.$(childDb) { db =>
+      println(db.query("SELECT 2"))
+    }
+
+    // Return an Unscoped value - ScopeLift extracts it
+    "done"
+    
+    // But you cannot return childDb to the parent:
+    // childDb : Database @@ child.Tag has no ScopeLift instance
   }
 
   // parentDb is still usable here:
-  val stillOk = parent.$(parentDb)(_.query("SELECT 3"))
-  println(stillOk)
+  parent.$(parentDb) { db =>
+    println(db.query("SELECT 3"))
+  }
 }
 ```
 
@@ -332,21 +434,54 @@ Scope.global.scoped { parent =>
 
 ### Building a `Scoped` program (map/flatMap)
 
+You can use for-comprehensions to compose scoped computations. Each `<-` uses `flatMap`, accumulating requirements:
+
 ```scala
 import zio.blocks.scope._
 
 Scope.global.scoped { scope =>
-  val db = scope.allocate(Resource(new Database))
+  val db: Database @@ scope.Tag = scope.allocate(Resource(new Database))
+
+  // Build a scoped computation with map
+  val program: String @@ scope.Tag = db.map { d =>
+    d.query("SELECT 1")
+  }
+
+  // execute runs the computation immediately, returns String @@ scope.Tag
+  // Use side effects inside the computation to observe results
+  scope.execute(program)
+}
+```
+
+This pattern shines when chaining resource acquisition:
+
+```scala
+import zio.blocks.scope._
+
+// A pool that leases connections
+class Pool(implicit finalizer: Finalizer) extends AutoCloseable {
+  def lease: Resource[Connection] = Resource(new Connection)
+  def close(): Unit = println("pool closed")
+}
+
+class Connection extends AutoCloseable {
+  def query(sql: String): String = s"result: $sql"
+  def close(): Unit = println("connection closed")
+}
+
+Scope.global.scoped { scope =>
+  val pool: Pool @@ scope.Tag = scope.allocate(Resource.from[Pool])
 
-  val program: Scoped[scope.Tag, String] =
+  val program: String @@ scope.Tag =
     for {
-      a <- db.map(_.query("SELECT 1"))
-      b <- db.map(_.query("SELECT 2"))
-    } yield s"$a | $b"
+      p          <- pool                      // extract Pool from scoped
+      connection <- scope.allocate(p.lease)   // allocate returns Connection @@ Tag
+    } yield connection.query("SELECT 1")
 
-  val result: String = scope(program)
-  println(result)
+  // execute runs the computation - connection is used inside the yield
+  scope.execute(program)
 }
+// Output: connection closed, then pool closed (LIFO)
 ```
 
 ---
@@ -375,6 +510,7 @@ import zio.blocks.scope._
 
 Scope.global.scoped { scope =>
   given Finalizer = scope
+
   defer { println("cleanup") }
 }
 ```
@@ -390,7 +526,7 @@ import zio.blocks.scope._
 
 class ConnectionPool(config: Config)(implicit finalizer: Finalizer) {
   private val pool = createPool(config)
-  finalizer.defer { pool.shutdown() }
+  defer { pool.shutdown() }
   
   def getConnection(): Connection = pool.acquire()
 }
@@ -413,13 +549,15 @@ Why `Finalizer` instead of `Scope`?
 
 ### Dependency injection with `Wire` + `Context`
 
+For manual wiring (when you already have dependencies assembled), use `wire.toResource(ctx)`:
+
 ```scala
 import zio.blocks.scope._
 import zio.blocks.context.Context
 
 final case class Config(debug: Boolean)
 
-val w: Wire.Shared[Boolean, Config] = shared[Config]
+val w: Wire.Shared[Boolean, Config] = Wire.shared[Config]
 val deps: Context[Boolean] = Context[Boolean](true)
 
 Scope.global.scoped { scope =>
@@ -427,7 +565,7 @@ Scope.global.scoped { scope =>
     scope.allocate(w.toResource(deps))
 
   val debug: Boolean =
-    scope.$(cfg)(_.debug) // Boolean typically escapes
+    (scope $ cfg)(_.debug) // Boolean typically escapes
 
   println(debug)
 }
@@ -438,95 +576,105 @@ Sharing vs uniqueness at the wire level:
 ```scala
 import zio.blocks.scope._
 
-val ws = shared[Config] // shared recipe; sharing happens via Resource.Shared when allocated
-val wu = unique[Config] // unique recipe; each allocation is fresh
+val ws = Wire.shared[Config] // shared recipe; sharing happens via Resource.Shared when allocated
+val wu = Wire.unique[Config] // unique recipe; each allocation is fresh
 ```
 
 ---
 
-### Supplying dependencies with `Resource.from[T](wire1, wire2, ...)`
+### Dependency injection with `Resource.from[T](wires*)`
 
-`Resource.from[T]` can also be used as a "standalone mini graph" by providing wires for constructor dependencies.
+`Resource.from[T](wires*)` is the **primary entry point** for dependency injection. It resolves `T` and all its dependencies into a single `Resource[T]`.
 
 ```scala
 import zio.blocks.scope._
-import zio.blocks.context.Context
 
 final case class Config(url: String)
 
-trait Logger {
-  def info(msg: String): Unit
+final class Logger {
+  def info(msg: String): Unit = println(msg)
 }
 
-final class ConsoleLogger extends Logger {
-  def info(msg: String): Unit = println(msg)
+final class Database(cfg: Config) extends AutoCloseable {
+  def query(sql: String): String = s"[${cfg.url}] $sql"
+  def close(): Unit = println("database closed")
 }
 
-final class Service(cfg: Config, logger: Logger) extends AutoCloseable {
-  def run(): Unit = logger.info(s"running with ${cfg.url}")
+final class Service(db: Database, logger: Logger) extends AutoCloseable {
+  def run(): Unit = logger.info(s"running with ${db.query("SELECT 1")}")
   def close(): Unit = println("service closed")
 }
 
-// Provide wires for *all* dependencies of Service:
+// Only provide leaf values (primitives, configs) - the rest is auto-wired:
 val serviceResource: Resource[Service] =
   Resource.from[Service](
-    Wire(Config("jdbc:postgresql://localhost/db")),
-    Wire(new ConsoleLogger: Logger)
+    Wire(Config("jdbc:postgresql://localhost/db"))
   )
 
 Scope.global.scoped { scope =>
   val svc = scope.allocate(serviceResource)
-  scope.$(svc)(_.run())
+  (scope $ svc)(_.run())
 }
+// Output: running with [jdbc:postgresql://localhost/db] SELECT 1
+// Then: service closed, database closed (LIFO order)
 ```
 
-Notes:
-- All dependencies of `T` must be covered by the provided wires, otherwise you get a compile-time error.
-- If `T` is `AutoCloseable`, `close()` is registered automatically.
+**What you must provide:**
+- Leaf values: primitives, configs, pre-existing instances via `Wire(value)`
+- Abstract types: traits/abstract classes via `Wire.shared[ConcreteImpl]`
+- Overrides: when you want `unique` instead of the default `shared`
+
+**What is auto-created:**
+- Concrete classes with accessible primary constructors (default: `Wire.shared`)
 
 ---
 
-### DI for traits via `Wireable`
+### Injecting traits via subtype wires
 
-When you want to inject a trait (or abstract class), define a `Wireable` in the companion so `shared[T]` / `unique[T]` can resolve it.
+When a dependency is a trait or abstract class, provide a wire for a concrete implementation:
 
 ```scala
 import zio.blocks.scope._
-import zio.blocks.context.Context
 
-trait DatabaseApi {
-  def query(sql: String): String
+trait Logger {
+  def info(msg: String): Unit
 }
 
-final class LiveDatabaseApi(cfg: Config) extends DatabaseApi with AutoCloseable {
-  def query(sql: String): String = s"[${cfg.url}] $sql"
-  def close(): Unit = println("LiveDatabaseApi closed")
+final class ConsoleLogger extends Logger {
+  def info(msg: String): Unit = println(msg)
 }
 
-object DatabaseApi {
-  // Tell Scope how to build the trait by wiring a concrete implementation.
-  given Wireable.Typed[Config, DatabaseApi] =
-    Wireable.fromWire(shared[LiveDatabaseApi].shared.asInstanceOf[Wire[Config, DatabaseApi]])
+final class App(logger: Logger) {
+  def run(): Unit = logger.info("Hello!")
 }
 
-final case class Config(url: String)
+// Wire.shared[ConsoleLogger] satisfies the Logger dependency via subtyping:
+val appResource: Resource[App] =
+  Resource.from[App](
+    Wire.shared[ConsoleLogger]
+  )
 
 Scope.global.scoped { scope =>
-  val deps = Context(Config("jdbc:postgresql://localhost/db"))
-
-  val db: DatabaseApi @@ scope.Tag =
-    scope.allocate(shared[DatabaseApi].toResource(deps))
-
-  val out: String =
-    scope.$(db)(_.query("SELECT 1"))
-
-  println(out)
+  val app = scope.allocate(appResource)
+  (scope $ app)(_.run())
 }
 ```
 
-Practical guidance:
-- Prefer `Wireable.fromWire(...)` when you already have a `Wire` you trust.
-- Put `given Wireable[...]` / `implicit val wireable: Wireable[...]` in the companion of the trait being injected.
+**Single instance for diamond patterns:**
+
+```scala
+trait Service
+class LiveService extends Service
+class NeedsService(s: Service)
+class NeedsLive(l: LiveService)
+class App(a: NeedsService, b: NeedsLive)
+
+// One LiveService instance satisfies both Service and LiveService dependencies:
+val appResource = Resource.from[App](
+  Wire.shared[LiveService]
+)
+// count of LiveService instantiations: 1
+```
 
 ---
 
@@ -549,6 +697,168 @@ Scope.global.scoped { scope =>
 
 ---
 
+## Common compile errors
+
+The scope macros produce beautiful, actionable compile-time error messages with ASCII diagrams and helpful hints:
+
+### Not a class (Wire.shared/unique on trait or abstract class)
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Cannot derive Wire for MyTrait: not a class.
+
+  Hint: Use Wire.Shared / Wire.Unique directly.
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Unmakeable type (primitives, functions, collections)
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Cannot auto-create String
+
+  This type (primitive, collection, or function) cannot be auto-created.
+
+  Required by:
+    └── Config
+        └── App
+
+  Fix: Provide Wire(value) with the desired value:
+
+    Resource.from[...](
+      Wire(...),  // provide a value for String
+      ...
+    )
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Abstract type (trait or abstract class)
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Cannot auto-create Logger
+
+  This type is abstract (trait or abstract class).
+
+  Required by:
+    └── App
+
+  Fix: Provide a wire for a concrete implementation:
+
+    Resource.from[...](
+      Wire.shared[ConcreteImpl],  // provides Logger
+      ...
+    )
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Duplicate providers (ambiguous wires)
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Multiple providers for Service
+
+  Conflicting wires:
+    1. LiveService
+    2. TestService
+
+  Hint: Remove duplicate wires or use distinct wrapper types.
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Dependency cycle
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Dependency cycle detected
+
+  Cycle:
+    ┌───────────┐
+    │           ▼
+    A ──► B ──► C
+    ▲           │
+    └───────────┘
+
+  Break the cycle by:
+    • Introducing an interface/trait
+    • Using lazy initialization
+    • Restructuring dependencies
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Subtype conflict (related dependency types)
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Dependency type conflict in MyService
+
+  FileInputStream is a subtype of InputStream.
+
+  When both types are dependencies, Context cannot reliably distinguish
+  them. The more specific type may be retrieved when the more general
+  type is requested.
+
+  To fix this, wrap one or both types in a distinct wrapper:
+
+    case class WrappedInputStream(value: InputStream)
+    or
+    opaque type WrappedInputStream = InputStream
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Duplicate parameter types in constructor
+
+```
+── Scope Error ──────────────────────────────────────────────────────────────
+
+  Constructor of App has multiple parameters of type String
+
+  Context is type-indexed and cannot supply distinct values for the same type.
+
+  Fix: Wrap one parameter in an opaque type to distinguish them:
+
+    opaque type FirstString = String
+    or
+    case class FirstString(value: String)
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Leak warning
+
+When using `leak(value)` to escape the scoped type system:
+
+```
+── Scope Warning ────────────────────────────────────────────────────────────
+
+  leak(db)
+       ^
+       |
+
+  Warning: db is being leaked from scope MyScope.
+  This may result in undefined behavior.
+
+  Hint:
+     If you know this data type is not resourceful, then add an Unscoped
+     instance for it so ScopeLift can lift it automatically.
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+---
+
 ## API reference (selected)
 
 ### `Scope`
@@ -562,18 +872,16 @@ final class Scope[ParentTag, Tag0 <: ParentTag] {
   def allocate[A](resource: Resource[A]): A @@ Tag
   def defer(f: => Unit): Unit
 
-  def $[A, B, S](scoped: A @@ S)(f: A => B)(
-    using ev: this.Tag <:< S,
-          escape: ScopeEscape[B, S]
-  ): escape.Out
+  // Apply function to scoped value - executes immediately, always returns scoped
+  def $[A, B](scoped: A @@ this.Tag)(f: A => B): B @@ Tag
 
-  def apply[A, S](scoped: Scoped[S, A])(
-    using ev: this.Tag <:< S,
-          escape: ScopeEscape[A, S]
-  ): escape.Out
+  // Execute scoped computation - runs immediately, always returns scoped
+  def execute[A](scoped: A @@ this.Tag): A @@ Tag
 
-  // Creates a child scope with an existential tag (fresh per call)
-  def scoped[A](f: Scope[this.Tag, ? <: this.Tag] => A): A
+  // Creates a child scope - ScopeLift controls what may exit
+  def scoped[A](f: Scope[this.Tag, ? <: this.Tag] => A)(
+    using lift: ScopeLift[A, this.Tag]
+  ): lift.Out
 }
 ```
 
@@ -587,20 +895,16 @@ object Resource {
   def acquireRelease[A](acquire: => A)(release: A => Unit): Resource[A]
   def fromAutoCloseable[A <: AutoCloseable](thunk: => A): Resource[A]
 
-  // Macro-derived constructors:
-  def from[T]: Resource[T]
+  // Macro - DI entry point (can also be called with no args for zero-dep classes):
   def from[T](wires: Wire[?, ?]*): Resource[T]
 
-  // Internal / produced by wires:
-  def shared[A](f: Finalizer => A): Resource.Shared[A]
-  def unique[A](f: Finalizer => A): Resource.Unique[A]
-
-  final class Shared[+A] extends Resource[A]
-  final class Unique[+A] extends Resource[A]
+  // Internal (used by generated code):
+  def shared[A](f: Finalizer => A): Resource[A]
+  def unique[A](f: Finalizer => A): Resource[A]
 }
 ```
 
-### `Wire` and `Wireable`
+### `Wire`
 
 ```scala
 sealed trait Wire[-In, +Out] {
@@ -610,9 +914,16 @@ sealed trait Wire[-In, +Out] {
   def toResource(deps: zio.blocks.context.Context[In]): Resource[Out]
 }
 
-trait Wireable[+Out] {
-  type In
-  def wire: Wire[In, Out]
+object Wire {
+  // Macro entry points:
+  def shared[T]: Wire[?, T]  // derive from T's constructor
+  def unique[T]: Wire[?, T]  // derive from T's constructor
+  
+  // Wrap pre-existing value (auto-finalizes if AutoCloseable):
+  def apply[T](value: T): Wire.Shared[Any, T]
+  
+  final class Shared[-In, +Out] extends Wire[In, Out]
+  final class Unique[-In, +Out] extends Wire[In, Out]
 }
 ```
 
@@ -621,7 +932,16 @@ trait Wireable[+Out] {
 ## Mental model recap
 
 - Use `Scope.global.scoped { scope => ... }` to create a safe region.
-- Allocate managed things with `scope.allocate(Resource(...))` (or `Resource.from[...]`).
-- Use scoped values only via `scope.$(value)(...)` or via `Scoped` computations executed by `scope(scoped)`.
+- For simple resources: `scope.allocate(Resource(value))` or `scope.allocate(Resource.acquireRelease(...)(...))`
+- For dependency injection: `scope.allocate(Resource.from[App](Wire(config), ...))` — auto-wires concrete classes, you provide leaves and overrides.
+- Use scoped values via `(scope $ value) { v => ... }` — the function executes immediately.
+- `$` and `execute` always return scoped values (`B @@ scope.Tag`), never raw values.
+- Escape only happens at `.scoped` boundaries via `ScopeLift`.
 - Nest with `scope.scoped { child => ... }` to create a tighter lifetime boundary.
+- Return `Unscoped` types from child scopes to extract raw values.
 - If it doesn't typecheck, it would have been unsafe at runtime.
+
+**The 3 macro entry points:**
+- `Wire.shared[T]` — shared wire from constructor
+- `Wire.unique[T]` — unique wire from constructor
+- `Resource.from[T](wires*)` — wire up T and all dependencies