@zio.dev/zio-blocks 0.0.1 → 0.0.22

package/scope.md

@@ -2,11 +2,14 @@
 
 `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`)
+- **Zero-cost opaque type** (`$[A]` is the scoped type, equal to `A` at runtime)
 - **Simple, synchronous lifecycle management** (finalizers run LIFO on scope close)
+- **Eager evaluation** (all operations execute immediately, no deferred thunks)
 
 ---
 
@@ -14,23 +17,24 @@ If you've used `try/finally`, `Using`, or ZIO `Scope`, this library lives in the
 
 - [Quick start](#quick-start)
 - [Core concepts](#core-concepts)
-  - [1) `Scope[ParentTag, Tag]`](#1-scopeparenttag-tag)
-  - [2) Scoped values: `A @@ S`](#2-scoped-values-a--s)
+  - [1) `Scope`](#1-scope)
+  - [2) Scoped values: `$[+A]`](#2-scoped-values-a)
   - [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)
+  - [4) `Unscoped`: marking pure data types](#4-unscoped-marking-pure-data-types)
+  - [5) `lower`: accessing parent-scoped values](#5-lower-accessing-parent-scoped-values)
   - [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)
 - [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)
   - [Nested scopes (child can use parent, not vice versa)](#nested-scopes-child-can-use-parent-not-vice-versa)
-  - [Building a `Scoped` program (map/flatMap)](#building-a-scoped-program-mapflatmap)
+  - [Chaining resource acquisition](#chaining-resource-acquisition)
   - [Registering cleanup manually with `defer`](#registering-cleanup-manually-with-defer)
+  - [Classes with `Finalizer` parameters](#classes-with-finalizer-parameters)
   - [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)
 
 ---
@@ -46,80 +50,113 @@ final class Database extends AutoCloseable {
 }
 
 Scope.global.scoped { scope =>
-  val db: Database @@ scope.Tag =
-    scope.allocate(Resource(new Database))
+  import scope._
 
-  val result: String =
-    scope.$(db)(_.query("SELECT 1"))
+  val db: $[Database] = allocate(Resource(new Database))
 
-  println(result)
+  // scope.use applies a function to the scoped value, returning a scoped result
+  val result: $[String] = scope.use(db)(_.query("SELECT 1"))
+  println(result)  // $[String] = String at runtime, prints directly
 }
 ```
 
 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
+- `allocate(...)` returns a **scoped** value of type `$[Database]` (the path-dependent type of the enclosing scope)
+- `$[A] = A` at runtime — zero-cost opaque type, no boxing
+- All operations are **eager** — values are computed immediately, no lazy thunks
+- Use `scope.use(value)(f)` to work with scoped values; returns `$[B]`
 - When the `scoped { ... }` block exits, finalizers run **LIFO** and errors are handled safely
+- The `scoped` method requires `Unscoped[A]` evidence on the return type
 
 ---
 
 ## Core concepts
 
-### 1) `Scope[ParentTag, Tag]`
+### 1) `Scope`
 
-A `Scope` manages finalizers and ties values to a *type-level identity* called a **Tag**.
+`Scope` is a `sealed abstract class` with **no** type parameters. It manages finalizers and ties values to a *type-level identity* via abstract type members.
 
-- `Scope[ParentTag, Tag]` has **two** type parameters:
-  - `ParentTag`: the parent scope's tag (capability boundary)
-  - `Tag <: ParentTag`: this scope's unique identity (used to tag values)
+- **`type $[+A]`** — a path-dependent opaque type that tags values to this scope. Covariant in `A`. Equal to `A` at runtime (zero-cost).
+- **`type Parent <: Scope`** — the parent scope's type.
+- **`val parent: Parent`** — reference to the parent scope.
 
-Every `Scope` also exposes a *path-dependent* member type:
+Each scope instance exposes its own `$[+A]`, so a parent's `$[Database]` is a different type than a child's `$[Database]`, even though both equal `Database` at runtime.
 
 ```scala
-type Tag = Tag0
+type $[+A]  // = A at runtime (zero-cost)
 ```
 
 So in code you'll typically write:
 
 ```scala
 Scope.global.scoped { scope =>
-  val x: Something @@ scope.Tag = ???
+  import scope._
+  val x: $[Something] = ???  // or scope.$[Something]
 }
 ```
 
+Child scopes are represented by `Scope.Child[P <: Scope]`, a `final class` nested in the `Scope` companion object.
+
 #### Global scope
 
-`Scope.global` is the root of the tag hierarchy:
+`Scope.global` is the root of the scope hierarchy:
 
 ```scala
 object Scope {
-  type GlobalTag
-  lazy val global: Scope[GlobalTag, GlobalTag]
+  object global extends Scope {
+    type $[+A]  = A
+    type Parent = global.type
+    val parent: Parent = this
+  }
 }
 ```
 
 - 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).
 
 ---
 
-### 2) Scoped values: `A @@ S`
+### 2) Scoped values: `$[+A]`
 
-`A @@ S` means: "a value of type `A` that is locked to scope tag `S`".
+`$[+A]` (or `scope.$[A]` in type annotations) is a path-dependent opaque type representing a value of type `A` that is locked to a specific scope. It is covariant in `A`.
 
-- **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] = A` — zero-cost opaque type, no boxing or wrapping
+- **Key effect:** methods on `A` are hidden at the type level; you can't call `a.method` directly
+- **All operations are eager:** `allocate(resource)` acquires the resource **immediately** and returns a scoped value
 - **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.use(a)(f)` to apply a function and get `$[B]`
+
+#### `ScopedOps`: `map` and `flatMap` on `$[A]`
+
+`Scope` provides an implicit class `ScopedOps[A]` that adds `map` and `flatMap` to `$[A]` values, enabling for-comprehension syntax:
+
+```scala
+Scope.global.scoped { scope =>
+  import scope._
+
+  val x: $[Int] = $(42)
+  val y: $[String] = x.map(_.toString)
+  val z: $[String] = x.flatMap(v => $(s"value: $v"))
+}
+```
+
+- `sa.map(f: A => B): $[B]` — applies `f` to the unwrapped value, re-wraps the result
+- `sa.flatMap(f: A => $[B]): $[B]` — applies `f` to the unwrapped value (where `f` returns a scoped value)
+- All operations are **eager** (zero-cost)
+
+#### Scala 2 note
+
+In Scala 2, the `scoped` method must be called with a lambda literal. Passing a variable or method reference is not supported due to macro limitations:
 
-#### Scala 3 vs Scala 2 note
+```scala
+// ✅ OK: lambda literal
+Scope.global.scoped { scope => ... }
 
-- 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).
+// ❌ ERROR in Scala 2 (works in Scala 3):
+val f: Scope.Child[_] => Any = scope => ...
+Scope.global.scoped(f)
+```
 
 ---
 
@@ -128,7 +165,7 @@ object Scope {
 `Resource[A]` describes how to **acquire** an `A` and how to **release** it when a scope closes. It is intentionally lazy: you *describe what to do*, and allocation happens only through:
 
 ```scala
-scope.allocate(resource)
+allocate(resource)
 ```
 
 Common constructors:
@@ -139,12 +176,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 +199,138 @@ Common constructors:
 
 ---
 
-### 4) `Scoped[Tag, A]`: deferred computations
+### 4) `Unscoped`: marking pure data types
 
-`Scoped[-Tag, +A]` represents a computation that produces `A`, but can only be executed by a scope whose tag is compatible with `Tag`.
+The `Unscoped[A]` typeclass marks types as pure data that don't hold resources. The `scoped` method requires `Unscoped[A]` evidence on the return type to ensure only safe values can exit a scope.
 
-Execution happens via:
+**Built-in Unscoped types:**
+- Primitives: `Int`, `Long`, `Boolean`, `Double`, etc.
+- `String`, `Unit`, `Nothing`
+- Collections of Unscoped types
 
+**Custom Unscoped types:**
 ```scala
-scope(scopedComputation)
+// Scala 3:
+case class Config(debug: Boolean)
+object Config {
+  given Unscoped[Config] = Unscoped.derived
+}
+
+// Scala 2:
+case class Config(debug: Boolean)
+object Config {
+  implicit val unscopedConfig: Unscoped[Config] = Unscoped.derived[Config]
+}
 ```
 
-How to build them:
+**Allowed return types from `scoped`:**
 
-- 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)
+- **`Unscoped` types**: Pure data that can safely exit
+- **`Nothing`**: For blocks that throw
 
-`Scoped` is contravariant in `Tag`, which is what allows a **child** scope (more specific tag) to run computations that only require a **parent** tag.
+**Rejected return types (no Unscoped instance):**
+
+- **Closures**: `() => A` could capture the child scope
+- **Scoped values**: `$[A]` would be use-after-close
+- **The scope itself**: Would allow operations after close
+
+```scala
+Scope.global.scoped { parent =>
+  import parent._
+
+  // ✅ OK: String is Unscoped
+  val result: String = scoped { child =>
+    "hello"
+  }
+
+  // ❌ COMPILE ERROR: $[Database] has no Unscoped instance
+  // val escaped = scoped { child =>
+  //   import child._
+  //   allocate(Resource(new Database))  // $[Database] can't escape
+  // }
+}
+```
 
 ---
 
-### 5) `ScopeEscape` and `Unscoped`: what may escape
+### 5) `lower`: accessing parent-scoped values
+
+When working in a child scope, you may need to access values allocated in a parent scope. Use `lower(parentValue)` to "lower" a parent-scoped value into the child scope:
 
-Whenever you access a scoped value via:
+```scala
+Scope.global.scoped { parent =>
+  import parent._
 
-- `scope.$(value)(f)`, or
-- `scope(scopedComputation)`,
+  val parentDb: $[Database] = allocate(Resource(new Database))
 
-…the return type is controlled by `ScopeEscape[A, S]`, which decides whether a result:
+  scoped { child =>
+    import child._
 
-- escapes as raw `A`, or
-- remains tracked as `A @@ S`.
+    // Use lower() to access parent-scoped value in child scope
+    val db: $[Database] = lower(parentDb)
+    child.use(db)(_.query("SELECT 1"))
 
-Rule of thumb:
+    "done"
+  }
+}
+```
 
-- 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`.
+The `lower` operation is necessary because each scope has its own `$[A]` opaque type. A parent's `$[A]` is a different type than a child's `$[A]`, even though both equal `A` at runtime.
 
 ---
 
 ### 6) `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
 
-### 7) `Wireable[Out]`: DI for traits/abstract classes
+#### How `Resource.from[T](wires*)` works
 
-`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*".
+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
 
-That's what `Wireable[T]` is: a typeclass that supplies a `Wire` for a service.
+Key insight: **Compose Resources, don't accumulate values.** Each wire becomes a `Resource`, and they are composed via `flatMap`. This correctly preserves:
 
-Typical use:
+- **Sharing**: Same `Resource.Shared` instance → same value (even in diamond patterns)
+- **Uniqueness**: `Resource.Unique` → fresh value per injection site
 
-- Define a `Wireable[MyTrait]` in `MyTrait`'s companion object.
-- `shared[MyTrait]` or `unique[MyTrait]` will pick it up automatically.
+#### Subtype resolution
 
-This is especially useful when you want to inject an interface but construct a concrete implementation (and still register finalizers correctly).
+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.
+
+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)
@@ -257,20 +339,24 @@ Child scopes are created with:
 
 ```scala
 Scope.global.scoped { scope =>
-  scope.scoped { child =>
+  import scope._
+  scoped { child =>
+    import child._
     // allocate in child
   }
 }
 ```
 
-The child scope has an existential tag (fresh per invocation). You can allocate in the child, but you can't return those values to the parent in a usable form because the parent cannot name (or satisfy) the child tag.
+The child scope has a fresh, unnameable `$[A]` type (created per invocation). You can allocate in the child, but you can't return those values to the parent in a usable form because the parent cannot name (or satisfy) the child's `$[A]` type.
 
 Compile-time safety is verified in tests, e.g.:
 `ScopeCompileTimeSafetyScala3Spec`.
 
-### B) Tag invariance + "opaque-like" `@@` blocks subtyping escape
+### B) Opaque types prevent escape
 
-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.
+Each scope defines its own `$[A]` opaque type. Even though `$[A] = A` at runtime, the compiler treats each scope's `$[A]` as distinct. A child's `$[Database]` is a different type than the parent's `$[Database]`.
+
+Additionally, the opaque type hides `A`'s methods at the type level — you can't call `db.query(...)` directly on a `$[Database]`. Access routes are `scope.use(value)(f)` and the `ScopedOps` methods (`map`, `flatMap`) for for-comprehensions.
 
 ---
 
@@ -287,12 +373,13 @@ final class FileHandle(path: String) extends AutoCloseable {
 }
 
 Scope.global.scoped { scope =>
-  val h = scope.allocate(Resource(new FileHandle("data.txt")))
+  import scope._
 
-  val contents: String =
-    scope.$(h)(_.readAll())
+  val h: $[FileHandle] = allocate(Resource(new FileHandle("data.txt")))
 
-  println(contents)
+  // scope.use applies function to scoped value, returns $[String]
+  val contents: $[String] = scope.use(h)(_.readAll())
+  println(contents)  // $[String] = String at runtime
 }
 ```
 
@@ -304,64 +391,84 @@ Scope.global.scoped { scope =>
 import zio.blocks.scope._
 
 Scope.global.scoped { parent =>
-  val parentDb = parent.allocate(Resource(new Database))
+  import parent._
+
+  val parentDb: $[Database] = allocate(Resource(new Database))
+
+  scoped { child =>
+    import child._
 
-  parent.scoped { child =>
-    // child can use parent-scoped values:
-    val ok: String = child.$(parentDb)(_.query("SELECT 1"))
-    println(ok)
+    // Use lower() to access parent-scoped values in child scope:
+    val db: $[Database] = lower(parentDb)
+    println(child.use(db)(_.query("SELECT 1")))
 
-    val childDb = child.allocate(Resource(new Database))
+    val childDb: $[Database] = allocate(Resource(new Database))
 
     // You can use childDb *inside* the child:
-    val ok2: String = child.$(childDb)(_.query("SELECT 2"))
-    println(ok2)
+    println(child.use(childDb)(_.query("SELECT 2")))
 
-    // But you cannot return childDb to the parent in a usable way:
-    // childDb : Database @@ child.Tag
-    // parent cannot prove parent.Tag <:< child.Tag
+    // But you cannot return childDb to the parent:
+    // $[Database] has no Unscoped instance — compile error
+
+    // Return an Unscoped value
+    "done"
   }
 
   // parentDb is still usable here:
-  val stillOk = parent.$(parentDb)(_.query("SELECT 3"))
-  println(stillOk)
+  println(parent.use(parentDb)(_.query("SELECT 3")))
 }
 ```
 
 ---
 
-### Building a `Scoped` program (map/flatMap)
+### Chaining resource acquisition
+
+Since `$[A]` supports `map` and `flatMap` via `ScopedOps`, you can chain resource acquisitions in for-comprehensions:
 
 ```scala
 import zio.blocks.scope._
 
+class Pool extends AutoCloseable {
+  def lease(): Connection = 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 db = scope.allocate(Resource(new Database))
+  import scope._
 
-  val program: Scoped[scope.Tag, String] =
-    for {
-      a <- db.map(_.query("SELECT 1"))
-      b <- db.map(_.query("SELECT 2"))
-    } yield s"$a | $b"
+  // Chain allocations in a for-comprehension:
+  // flatMap unwraps $[Pool] to Pool, so pool.lease() returns a raw Connection
+  val result: $[String] = for {
+    pool <- allocate(Resource.from[Pool])
+    conn <- allocate(Resource(pool.lease()))
+  } yield conn.query("SELECT 1")
 
-  val result: String = scope(program)
   println(result)
 }
+// Output: result: SELECT 1
+// Then: connection closed, pool closed (LIFO)
 ```
 
 ---
 
 ### Registering cleanup manually with `defer`
 
-Use `scope.defer` when you already have a value and just need to register cleanup.
+Use `defer` when you already have a value and just need to register cleanup.
 
 ```scala
 import zio.blocks.scope._
 
 Scope.global.scoped { scope =>
+  import scope._
+
   val handle = new java.io.ByteArrayInputStream(Array[Byte](1, 2, 3))
 
-  scope.defer { handle.close() }
+  defer { handle.close() }
 
   val firstByte = handle.read()
   println(firstByte)
@@ -374,7 +481,9 @@ There is also a package-level helper `defer` that only requires a `Finalizer`:
 import zio.blocks.scope._
 
 Scope.global.scoped { scope =>
+  import scope._
   given Finalizer = scope
+
   defer { println("cleanup") }
 }
 ```
@@ -390,7 +499,7 @@ import zio.blocks.scope._
 
 class ConnectionPool(config: Config)(implicit finalizer: Finalizer) {
   private val pool = createPool(config)
-  finalizer.defer { pool.shutdown() }
+  finalizer.defer { pool.shutdown() }  // or: defer { ... } with import zio.blocks.scope._
   
   def getConnection(): Connection = pool.acquire()
 }
@@ -399,37 +508,40 @@ class ConnectionPool(config: Config)(implicit finalizer: Finalizer) {
 val resource = Resource.from[ConnectionPool](Wire(Config("jdbc://localhost")))
 
 Scope.global.scoped { scope =>
-  val pool = scope.allocate(resource)
+  import scope._
+  val pool = allocate(resource)
   // pool.shutdown() will be called when scope closes
 }
 ```
 
 Why `Finalizer` instead of `Scope`?
 - `Finalizer` is the minimal interface—it only has `defer`
-- Classes that need cleanup should not have access to `allocate` or `$`
+- Classes that need cleanup should not have access to `allocate` or `use`
 - The macros pass a `Finalizer` at runtime, so declaring `Scope` would be misleading
 
 ---
 
 ### 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 =>
-  val cfg: Config @@ scope.Tag =
-    scope.allocate(w.toResource(deps))
+  import scope._
 
-  val debug: Boolean =
-    scope.$(cfg)(_.debug) // Boolean typically escapes
+  val cfg: $[Config] = allocate(w.toResource(deps))
 
-  println(debug)
+  val debug: $[Boolean] = scope.use(cfg)(_.debug)
+
+  println(debug)  // $[Boolean] = Boolean at runtime
 }
 ```
 
@@ -438,107 +550,120 @@ 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())
+  import scope._
+  val svc: $[Service] = allocate(serviceResource)
+  scope.use(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)
+  import scope._
+  val app: $[App] = allocate(appResource)
+  scope.use(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
+```
 
 ---
 
 ### Interop escape hatch: `leak`
 
-Sometimes you must hand a raw value to code that cannot work with `@@` types.
+Sometimes you must hand a raw value to code that cannot work with `$[A]` types.
 
 ```scala
 import zio.blocks.scope._
 
 Scope.global.scoped { scope =>
-  val db = scope.allocate(Resource(new Database))
+  import scope._
+  val db: $[Database] = allocate(Resource(new Database))
 
   val raw: Database = leak(db) // emits a compiler warning
   // thirdParty(raw)
@@ -549,6 +674,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 you do not need to leak it.
+
+────────────────────────────────────────────────────────────────────────────
+```
+
+---
+
 ## API reference (selected)
 
 ### `Scope`
@@ -556,24 +843,42 @@ Scope.global.scoped { scope =>
 Core methods (Scala 3 `using` vs Scala 2 `implicit` differs, but the shapes are the same):
 
 ```scala
-final class Scope[ParentTag, Tag0 <: ParentTag] {
-  type Tag = Tag0
+sealed abstract class Scope extends Finalizer {
+  type $[+A]         // = A at runtime (zero-cost)
+  type Parent <: Scope
+  val parent: Parent
 
-  def allocate[A](resource: Resource[A]): A @@ Tag
+  def allocate[A](resource: Resource[A]): $[A]
+  def allocate[A <: AutoCloseable](value: => A): $[A]
   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, returns scoped result
+  def use[A, B](scoped: $[A])(f: A => B): $[B]
+
+  // Construct a scoped value from a raw value
+  def $[A](a: A): $[A]
+
+  // Lower parent-scoped value into this scope
+  def lower[A](value: parent.$[A]): $[A]
+
+  // Escape hatch: unwrap scoped value (emits compiler warning)
+  // Scala 3:
+  inline def leak[A](inline sa: $[A]): A  // macro — emits warning
+  // Scala 2:
+  def leak[A](sa: $[A]): A               // macro — emits warning
+
+  // Creates a child scope - requires Unscoped evidence on return type
+  // Scala 3:
+  def scoped[A](f: (child: Scope.Child[self.type]) => child.$[A])(using Unscoped[A]): A
+  // Scala 2 (macro rewrites the types; declared signature is untyped):
+  def scoped(f: Scope.Child[self.type] => Any): Any  // macro
 
-  def apply[A, S](scoped: Scoped[S, A])(
-    using ev: this.Tag <:< S,
-          escape: ScopeEscape[A, S]
-  ): escape.Out
+  implicit class ScopedOps[A](sa: $[A]) {
+    def map[B](f: A => B): $[B]
+    def flatMap[B](f: A => $[B]): $[B]
+  }
 
-  // Creates a child scope with an existential tag (fresh per call)
-  def scoped[A](f: Scope[this.Tag, ? <: this.Tag] => A): A
+  implicit def wrapUnscoped[A: Unscoped](a: A): $[A]
 }
 ```
 
@@ -587,20 +892,17 @@ 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]
-  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]
+  // Macro - DI entry point:
+  def from[T]: Resource[T]                      // zero-dep classes
+  def from[T](wires: Wire[?, ?]*): Resource[T]  // with dependency wires
 
-  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 +912,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.Shared[?, T]  // derive from T's constructor
+  def unique[T]: Wire.Unique[?, T]  // derive from T's constructor
+  
+  // Wrap pre-existing value (auto-finalizes if AutoCloseable):
+  def apply[T](value: T): Wire.Shared[Any, T]
+  
+  final case class Shared[-In, +Out] extends Wire[In, Out]
+  final case class Unique[-In, +Out] extends Wire[In, Out]
 }
 ```
 
@@ -620,8 +929,17 @@ 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)`.
-- Nest with `scope.scoped { child => ... }` to create a tighter lifetime boundary.
+- Use `Scope.global.scoped { scope => import scope._; ... }` to create a safe region.
+- For simple resources: `allocate(Resource(value))` or `allocate(Resource.acquireRelease(...)(...))`
+- For dependency injection: `allocate(Resource.from[App](Wire(config), ...))` — auto-wires concrete classes, you provide leaves and overrides.
+- Use `scope.use(value)(f)` to work with scoped values — all operations are eager.
+- `$[A] = A` at runtime — zero-cost opaque type.
+- The `scoped` method requires `Unscoped[A]` evidence on the return type.
+- Use `lower(parentValue)` to access parent-scoped values in child scopes.
+- 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