@zio.dev/zio-blocks 0.0.21 → 0.0.24

package/scope.md

@@ -1,396 +1,466 @@
-# ZIO Blocks — Scope (compile-time safe resource management)
+# ZIO Blocks — Scope (`zio.blocks.scope`)
 
-`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.
+`zio.blocks.scope` is a **compile-time safe, zero-cost** resource management library for **Scala 3** (and Scala 2.13). It prevents a large class of lifetime bugs by tagging allocated values with an *unnameable*, scope-specific type and restricting how those values may be used.
 
-**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.
+At runtime the model stays simple:
 
-If you've used `try/finally`, `Using`, or ZIO `Scope`, this library lives in the same problem space, but it focuses on:
+- **Allocate eagerly** (no lazy thunks)
+- **Register finalizers**
+- **Run finalizers deterministically** when a scope closes (**LIFO** order)
+- Collect finalizer failures into a `Finalization` (and throw/suppress appropriately)
 
-- **Compile-time prevention of scope leaks**
-- **Unified scoped type** (`A @@ S` is a type alias for `Scoped[A, S]`)
-- **Simple, synchronous lifecycle management** (finalizers run LIFO on scope close)
+## Why Scope?
 
----
+Most resource bugs in Scala are "escape" bugs:
+
+- storing a connection/stream in a field and using it after it was closed
+- capturing a resource in a closure that outlives a scope
+- passing a resource to code that might retain it
+- mixing values from different lifetimes ("which scope owns this?")
+
+Scope addresses these with a *tight* design:
 
-## Table of contents
-
-- [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)
-  - [3) `Resource[A]`: acquisition + finalization](#3-resourcea-acquisition--finalization)
-  - [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)
-  - [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)
-  - [Registering cleanup manually with `defer`](#registering-cleanup-manually-with-defer)
-  - [Dependency injection with `Wire` + `Context`](#dependency-injection-with-wire--context)
-  - [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)
+| Feature | `zio.blocks.scope` |
+|---|---|
+| Compile-time leak prevention | ✓ (`scope.$[A]` + `$` macro + `Unscoped` boundary) |
+| Runtime overhead | ~0 (scoped values erase to `A`) |
+| Allocation model | Eager (allocation happens at `allocate`) |
+| Finalization | Deterministic, LIFO, errors collected |
+| Structured lifetime | Parent/child scopes, `lower` for explicit lifetime widening |
+| Escape hatch | `leak` (warns) |
+
+If you've used `try/finally`, `Using`, or ZIO's `Scope`, this is the same problem space—but optimized for **synchronous code** with **compile-time boundaries**.
 
 ---
 
-## Quick start
+## Quick start (Scala 3)
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-final class Database extends AutoCloseable {
+final class Database extends AutoCloseable:
   def query(sql: String): String = s"result: $sql"
   def close(): Unit = println("db closed")
-}
 
-Scope.global.scoped { scope =>
-  val db: Database @@ scope.Tag =
-    scope.allocate(Resource(new Database))
+@main def quickStart(): Unit =
+  val out: String =
+    Scope.global.scoped { scope =>
+      import scope.*
 
-  // $ 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)
-  }
-}
-```
+      val db: $[Database] =
+        Resource.fromAutoCloseable(new Database).allocate
 
-Key things to notice:
+      // Safe access: the lambda parameter can only be used as a receiver
+      $(db)(_.query("SELECT 1"))
+    }
 
-- `scope.allocate(...)` returns a **scoped** value: `Database @@ scope.Tag`
-- You **cannot** call `db.query(...)` directly (methods are intentionally hidden)
-- 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
+  println(out)
+```
 
----
+Key points:
 
-## Core concepts
+- `allocate(...)` returns a **scoped value**: `scope.$[Database]` (or `$[Database]` after `import scope.*`).
+- You **cannot** call `db.query(...)` directly on `$[Database]`.
+- You use the `$` access operator: `$(db)(...)` (or `(scope $ db)(...)` without the import).
+- The `scoped` block returns a plain `String` because `String: Unscoped`.
+- Finalizers run when the block exits, in **LIFO** order.
 
-### 1) `Scope[ParentTag, Tag]`
+---
 
-A `Scope` manages finalizers and ties values to a *type-level identity* called a **Tag**.
+## Core mental model
 
-- `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)
+### 1) `Scope`: finalizers + type identity
 
-Every `Scope` also exposes a *path-dependent* member type:
+`Scope` is a finalizer registry plus a unique type identity:
 
-```scala
-type Tag = Tag0
-```
+- `type $[+A]` — a scope-tagged, path-dependent type (erases to `A` at runtime)
+- `type Parent <: Scope` / `val parent: Parent` — the scope hierarchy
 
-So in code you'll typically write:
+Every scope instance defines a **different** `$` type, so values from different scopes don't accidentally mix.
 
 ```scala
 Scope.global.scoped { scope =>
-  val x: Something @@ scope.Tag = ???
+  import scope.*
+  val x: $[Int] = 1 // ok (in global, $[A] = A)
 }
 ```
 
 #### Global scope
 
-`Scope.global` is the root of the tag hierarchy:
+`Scope.global` is the root:
+
+- In the global scope: `type $[+A] = A` (identity)
+- On the JVM: global finalizers run on shutdown via a shutdown hook
+- On Scala.js: there is no shutdown hook, so global finalizers are **not** run automatically
+
+---
+
+### 2) Scoped values: `scope.$[A]` / `$[A]`
+
+A value of type `scope.$[A]` means:
+
+> "This is an `A`, but it is only valid while `scope` is alive."
+
+Properties:
+
+- **Zero-cost**: `$[A]` is just `A` at runtime (casts/identity)
+- **Incompatible across scopes**: `outer.$[A]` is not `inner.$[A]`
+- **Methods are hidden** at the type level; you must use `$` to access
+
+#### Access operator: `(scope $ value)(f)`
+
+The intended way to use a scoped value is:
 
 ```scala
-object Scope {
-  type GlobalTag
-  lazy val global: Scope[GlobalTag, GlobalTag]
-}
+(scope $ scopedValue)(a => a.method(...))
 ```
 
-- The global scope is intended to live for the lifetime of the process.
-- Its finalizers run on JVM shutdown.
-- Values allocated in `Scope.global` can escape as raw values via `ScopeLift.globalScope` (see below).
+This is enforced by a macro that checks the lambda uses its parameter only in **receiver position**.
 
----
+Allowed:
+
+```scala
+(scope $ db)(_.query("SELECT 1"))
+(scope $ db)(d => d.query("a") + d.query("b"))
+(scope $ db)(_.query("x").toUpperCase)
+(scope $ db)(_.field) // field access is allowed
+```
 
-### 2) Scoped values: `A @@ S`
+Rejected at compile time:
 
-`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`.
+```scala
+(scope $ db)(d => store(d))            // parameter used as an argument
+(scope $ db)(d => () => d.query("x"))  // captured in a nested lambda
+(scope $ db)(d => d)                   // returning the parameter
+(scope $ db)(d => { val x = d; 1 })    // binding/storing the parameter itself
+```
 
-- **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 execute and apply a function immediately
-  - `a.map / a.flatMap` to build composite scoped computations
-  - `scope.execute(scoped)` to run a composed computation
+##### "Auto-unwrap" rule (`Unscoped`)
 
-#### Scala 2 note
+`$` *auto-unwraps* when the result type is known to be safe data:
 
-In Scala 2, explicit type annotations are required when assigning scoped values to avoid existential type inference issues:
+- if `B: Unscoped` → `(scope $ sa)(f)` returns **`B`**
+- otherwise → it returns **`scope.$[B]`**
 
 ```scala
-// Scala 2 requires explicit type annotation
-val db: Database @@ scope.Tag = scope.allocate(Resource[Database])
+Scope.global.scoped { scope =>
+  import scope.*
+
+  val db: $[Database] = Resource.from[Database].allocate
 
-// Scala 3 can infer the type
-val db = scope.allocate(Resource[Database])
+  val s: String = $(db)(_.query("SELECT 1"))      // String is Unscoped => unwrapped
+  val n: Int    = $(db)(_.query("x").length)      // Int is Unscoped => unwrapped
+}
 ```
 
 ---
 
 ### 3) `Resource[A]`: acquisition + finalization
 
-`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:
+A `Resource[A]` is a **lazy description** of how to acquire a value and register cleanup in a scope. Nothing happens until you call `scope.allocate(resource)` (or `.allocate` syntax).
 
-```scala
-scope.allocate(resource)
-```
+#### Constructors
+
+From the source:
+
+- `Resource(value: => A)`
+  Wraps a by-name value; if it's `AutoCloseable`, `close()` is registered automatically (runtime check).
+- `Resource.fromAutoCloseable(thunk: => A <: AutoCloseable)`
+  Type-safe helper that registers `close()`.
+- `Resource.acquireRelease(acquire: => A)(release: A => Unit)`
+- `Resource.shared(f: Scope => A)`
+  **Memoized + reference-counted**, thread-safe.
+- `Resource.unique(f: Scope => A)`
+  Fresh instance per allocation.
+- `Resource.from[T]` and `Resource.from[T](wires*)` (macros)
+  Constructor-based dependency injection (covered below).
 
-Common constructors:
+#### Composition
 
-- `Resource(a)`
-  - Wraps a by-name value; if it's `AutoCloseable`, `close()` is registered automatically.
-- `Resource.acquireRelease(acquire)(release)`
-  - Explicit lifecycle.
-- `Resource.fromAutoCloseable(thunk)`
-  - A type-safe helper for `AutoCloseable`.
-- `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` composes with:
 
-#### Resource "sharing" vs "uniqueness"
+- `map`
+- `flatMap`
+- `zip`
 
-`Resource` has two important internal flavors:
+Finalizers remain tied to the allocation scope; in composed resources, finalizers still run LIFO.
 
-- `Resource.Unique[A]`
-  - Produces a **fresh** instance every time you allocate it (typical for `Resource(...)`, `acquireRelease`, etc.).
-- `Resource.Shared[A]`
-  - Produces a **shared** instance per `Resource.Shared` value, with **reference counting**:
-    - the first allocation initializes the value and collects finalizers
-    - each allocating scope registers a decrement finalizer
-    - when the reference count reaches zero, the collected finalizers run
+#### Sharing vs uniqueness (important)
 
-**Important clarification:** sharing is **not** "memoized within a Wire graph" or "within a scope" by magic. Sharing happens **within the specific `Resource.Shared` instance** you reuse.
+There are two distinct ideas:
+
+1. **Uniqueness**: "each allocation yields a fresh instance"
+   - Use `Resource.unique(...)`, or most ordinary `Resource(...)` / `acquireRelease(...)` resources.
+   - Each `allocate` runs the acquisition again and registers an independent finalizer.
+
+2. **Sharing**: "reusing the same instance across multiple allocations"
+   - Use `Resource.shared(...)` (or wires/resources that convert to shared).
+   - Sharing is tied to **reusing the same `Resource.Shared` value**, not "magic caching inside a scope".
+   - The first allocation initializes via an `OpenScope` parented to `Scope.global`; subsequent allocations increment a reference count. When the last referencing scope closes, the shared scope is closed.
 
 ---
 
-### 4) `A @@ S`: unified scoped type
+### 4) `Unscoped[A]`: types that may escape a scope
+
+`Unscoped[A]` is a marker typeclass for *pure data*. It's used in two places:
+
+1. `Scope.scoped` requires `Unscoped[A]` for the block's result type
+   ⇒ prevents returning resources, closures, or scoped values.
+2. `$` auto-unwraps results of type `B` when `B: Unscoped`.
+
+Built-in instances include primitives, `String`, many collections/containers, time values, `java.util.UUID`, and `zio.blocks.chunk.Chunk` (when element types are unscoped).
 
-`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.
+#### Deriving / defining your own instances
 
-Execution happens via:
+Scala 3 (derivation via `Unscoped.derived`):
 
 ```scala
-scope.execute(scopedComputation)
+import zio.blocks.scope.*
+
+final case class Config(debug: Boolean)
+object Config:
+  given Unscoped[Config] = Unscoped.derived
 ```
 
-How to build them:
+Scala 2.13:
 
-- 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)
+```scala
+import zio.blocks.scope.*
 
-**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.
+final case class Config(debug: Boolean)
+object Config {
+  implicit val unscopedConfig: Unscoped[Config] = Unscoped.derived[Config]
+}
+```
 
-**For-comprehension example:**
+#### Scope boundary 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)
+import zio.blocks.scope.*
+
+Scope.global.scoped { parent =>
+  import parent.*
+
+  val ok: String =
+    parent.scoped { child =>
+      "hello" // String is Unscoped
+    }
 
-  scope.execute(program)
+  // Does not compile: returning a resourceful value from a scoped block
+  // val leaked: Database =
+  //   parent.scoped { child =>
+  //     import child.*
+  //     Resource.fromAutoCloseable(new Database).allocate
+  //   }
+
+  ok
 }
 ```
 
 ---
 
-### 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.
+### 5) `lower`: using a parent-scoped value in a child scope
 
-**Built-in Unscoped types:**
-- Primitives: `Int`, `Long`, `Boolean`, `Double`, etc.
-- `String`, `Unit`, `Nothing`
-- Collections of Unscoped types
+Because each scope has its own `$[A]` type, a child cannot directly use a parent's `$[A]`. Use `lower` to retag a parent-scoped value into the child:
 
-**Custom Unscoped types:**
 ```scala
-case class Config(debug: Boolean)
-object Config {
-  given Unscoped[Config] = Unscoped.derived
+import zio.blocks.scope.*
+
+Scope.global.scoped { outer =>
+  import outer.*
+
+  val db: $[Database] = Resource.fromAutoCloseable(new Database).allocate
+
+  outer.scoped { inner =>
+    import inner.*
+    val innerDb: $[Database] = lower(db)
+    $(innerDb)(_.query("child"))
+  }
 }
 ```
 
-**Important:** `$` and `execute` always return `B @@ scope.Tag`. They never escape values directly. Escape only happens at the `.scoped` boundary via `ScopeLift`.
+This is safe because **parents always outlive children** (child finalizers run before the parent closes).
 
 ---
 
-### 6) `ScopeLift[A, S]`: what may return from child scopes
+### 6) `defer`: manual finalizers (+ cancellation)
 
-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.
+Use `defer` to register cleanup. It returns a `DeferHandle` you can cancel.
 
-**ScopeLift instances and their behavior:**
+```scala
+import zio.blocks.scope.*
 
-| 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) |
+Scope.global.scoped { scope =>
+  import scope.*
 
-**Allowed return types:**
+  val in = new java.io.ByteArrayInputStream(Array[Byte](1, 2, 3))
 
-- **`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
+  val h: DeferHandle =
+    defer(in.close())
 
-**Rejected return types (no ScopeLift instance):**
+  val first = in.read()
+  println(first)
 
-- **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
+  // If you already cleaned up manually:
+  // h.cancel() // thread-safe, idempotent
+}
+```
 
-```scala
-Scope.global.scoped { parent =>
-  // ✅ OK: String is Unscoped - lifts to raw String
-  val result: String = parent.scoped { child =>
-    "hello"  // Return raw Unscoped value
-  }
+There is also a **package-level** helper that only requires a `Finalizer`:
 
-  // ✅ 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
-  }
+```scala
+import zio.blocks.scope.*
 
-  // ❌ COMPILE ERROR: closure has no ScopeLift instance
-  // val leak = parent.scoped { child =>
-  //   val db = child.allocate(Resource[Database])
-  //   () => println("captured!")  // Function types rejected
-  // }
+Scope.global.scoped { scope =>
+  import scope.*
+  given Finalizer = scope
 
-  // ❌ COMPILE ERROR: child-scoped value has no ScopeLift instance
-  // val escaped = parent.scoped { child =>
-  //   child.allocate(Resource[Database])  // Database @@ child.Tag can't escape
-  // }
+  defer(println("cleanup")) // uses the package-level helper
 }
 ```
 
 ---
 
-### 7) `Wire[-In, +Out]`: dependency recipes
+### 7) `open()`: non-lexical, explicitly-managed child scopes
+
+`scoped` ties lifetime to a block. `open()` creates a child scope you close explicitly.
+
+- The child scope is **unowned** (can be used from any thread)
+- Still **linked to the parent**: parent closing will also close the child
+- You must call `close()` on the handle to detach + finalize now
 
-`Wire` is a recipe for constructing services. It describes **how** to build a service given its dependencies, but does not resolve those dependencies itself.
+From `Scope.global` the returned type is `Scope.OpenScope` directly (because global `$[A] = A`):
 
-- `In` is the required dependencies (provided as a `Context[In]`)
-- `Out` is the produced service
+```scala
+import zio.blocks.scope.*
+
+val os: Scope.OpenScope = Scope.global.open()
+
+val db = os.scope.allocate(Resource.fromAutoCloseable(new Database))
 
-There are two wire flavors:
+// ... use db ...
+
+os.close().orThrow()
+```
 
-- `Wire.Shared`: produces a shared (memoized) instance
-- `Wire.Unique`: produces a fresh instance each time
+Inside a child scope, `open()` returns `$[Scope.OpenScope]`. Prefer using it safely via `$`:
 
-**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
+import zio.blocks.scope.*
 
-#### Creating wires
+Scope.global.scoped { parent =>
+  import parent.*
 
-There are exactly **3 macro entry points**:
+  val os: $[Scope.OpenScope] = open()
 
-| 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` |
+  $(os) { h =>
+    val child = h.scope
+    val db    = child.allocate(Resource.fromAutoCloseable(new Database))
 
-For wrapping pre-existing values:
+    // ...
+    h.close().orThrow()
+  }
+}
+```
 
-- `Wire(value)` — wraps a value; if `AutoCloseable`, registers `close()` automatically
+---
 
-#### How `Resource.from[T](wires*)` works
+### 8) Escape hatch: `leak`
 
-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
+Sometimes you must hand a raw value to code that cannot work with `$[A]`. Use `leak`:
 
-Key insight: **Compose Resources, don't accumulate values.** Each wire becomes a `Resource`, and they are composed via `flatMap`. This correctly preserves:
+```scala
+import zio.blocks.scope.*
 
-- **Sharing**: Same `Resource.Shared` instance → same value (even in diamond patterns)
-- **Uniqueness**: `Resource.Unique` → fresh value per injection site
+Scope.global.scoped { scope =>
+  import scope.*
 
-#### Subtype resolution
+  val db: $[Database] = Resource.fromAutoCloseable(new Database).allocate
 
-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.
+  val raw: Database = leak(db) // emits a compiler warning
+  // thirdParty(raw)
+}
+```
 
-If the same concrete wire satisfies multiple types (e.g., `Service` and `LiveService`), only **one instance** is created and reused for both.
+`leak` bypasses compile-time guarantees—use only for unavoidable interop. If the type is genuinely pure data, prefer adding `Unscoped` so you don't need to leak.
 
 ---
 
 ## 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.
+Scope's safety comes from *three reinforcing layers*.
+
+### 1) Type barrier: scope-specific `$[A]`
+
+Every scope has a distinct `$[A]` type. You cannot accidentally use values across scopes without an explicit conversion (`lower` for parent → child).
+
+### 2) Controlled access: `$` macro restricts lambda usage
 
-The library prevents scope leaks via two reinforcing mechanisms:
+The `$` operator only allows using the unwrapped value as a **method/field receiver**. This prevents:
 
-### A) Existential child tags (fresh, unnameable types)
+- returning the resource
+- storing it in a local val/var
+- passing it as an argument
+- capturing it in a closure
 
-Child scopes are created with:
+Also note: `$` requires a **lambda literal**. Method references / variables are rejected:
 
 ```scala
-Scope.global.scoped { scope =>
-  scope.scoped { child =>
-    // allocate in child
-  }
-}
+// does not compile:
+val f: Database => String = _.query("x")
+(scope $ db)(f) // "$ requires a lambda literal ..."
 ```
 
-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.
+### 3) Scope boundary rule: `scoped` requires `Unscoped[A]`
+
+A `scoped { ... }` block can only return pure data (or `Nothing`). Resources and closures cannot escape.
+
+**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`).
 
-Compile-time safety is verified in tests, e.g.:
-`ScopeCompileTimeSafetyScala3Spec`.
+### Closed-scope defense (runtime)
 
-### B) Contravariance prevents child-to-parent widening
+If a scope escapes and is used after closing, operations become **no-ops returning default values**:
 
-`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.
+- `$`, `allocate`, `open`, `lower` return defaults (`null`, `0`, `false`, …)
+- `$` does not run the lambda when closed
+- `defer` on a closed scope is ignored
+- `scoped` creates a born-closed child if the parent is already closed
 
-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.
+This prevents post-close interaction with released resources, but can produce surprising default values if scopes are misused across threads.
+
+### Thread ownership rule (JVM)
+
+- Scopes created by `scoped` are **owned** by the entering thread.
+- Calling `scoped` on a scope you don't own throws `IllegalStateException`.
+- `open()` creates an **unowned** child scope (`isOwner == true` from any thread).
+
+(Scala.js uses a trivial ownership model; `isOwner` is effectively always true.)
 
 ---
 
-## Usage examples
+## Usage examples (patterns)
 
 ### Allocating and using a resource
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-final class FileHandle(path: String) extends AutoCloseable {
+final class FileHandle(path: String) extends AutoCloseable:
   def readAll(): String = s"contents of $path"
   def close(): Unit = println(s"closed $path")
-}
 
-Scope.global.scoped { scope =>
-  val h = scope.allocate(Resource(new FileHandle("data.txt")))
+@main def fileExample(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
+
+    val h: $[FileHandle] =
+      Resource(new FileHandle("data.txt")).allocate
+
+    val contents: String =
+      $(h)(_.readAll())
 
-  // $ executes immediately - work with the value inside the function
-  (scope $ h) { handle =>
-    val contents = handle.readAll()
     println(contents)
   }
-}
 ```
 
 ---
@@ -398,333 +468,393 @@ Scope.global.scoped { scope =>
 ### Nested scopes (child can use parent, not vice versa)
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-Scope.global.scoped { parent =>
-  val parentDb = parent.allocate(Resource(new Database))
+final class Database extends AutoCloseable:
+  def query(sql: String): String = s"result: $sql"
+  def close(): Unit = println("db closed")
 
-  parent.scoped { child =>
-    // child can use parent-scoped values:
-    child.$(parentDb) { db =>
-      println(db.query("SELECT 1"))
-    }
+@main def nested(): Unit =
+  Scope.global.scoped { parent =>
+    import parent.*
 
-    val childDb = child.allocate(Resource(new Database))
+    val parentDb: $[Database] = Resource.fromAutoCloseable(new Database).allocate
 
-    // You can use childDb *inside* the child:
-    child.$(childDb) { db =>
-      println(db.query("SELECT 2"))
-    }
+    val done: String =
+      parent.scoped { child =>
+        import child.*
 
-    // Return an Unscoped value - ScopeLift extracts it
-    "done"
-    
-    // But you cannot return childDb to the parent:
-    // childDb : Database @@ child.Tag has no ScopeLift instance
-  }
+        val db: $[Database] = lower(parentDb)
+        println($(db)(_.query("SELECT 1")))
 
-  // parentDb is still usable here:
-  parent.$(parentDb) { db =>
-    println(db.query("SELECT 3"))
-  }
-}
-```
-
----
-
-### Building a `Scoped` program (map/flatMap)
+        val childDb: $[Database] = Resource.fromAutoCloseable(new Database).allocate
+        println($(childDb)(_.query("SELECT 2")))
 
-You can use for-comprehensions to compose scoped computations. Each `<-` uses `flatMap`, accumulating requirements:
+        // childDb cannot be returned to the parent (not Unscoped)
+        "done"
+      }
 
-```scala
-import zio.blocks.scope._
+    println($(parentDb)(_.query("SELECT 3")))
+    done
+  }
+```
 
-Scope.global.scoped { scope =>
-  val db: Database @@ scope.Tag = scope.allocate(Resource(new Database))
+Finalizers run **child first, then parent**.
 
-  // 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)
-}
-```
+### Chaining resource acquisition (`$[Resource[A]]` + `.allocate`)
 
-This pattern shines when chaining resource acquisition:
+If a method returns `Resource[A]`, `$` returns a **scoped** `Resource[A]` (because `Resource[A]` is not `Unscoped`). Allocate it without leaking:
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-// A pool that leases connections
-class Pool(implicit finalizer: Finalizer) extends AutoCloseable {
-  def lease: Resource[Connection] = Resource(new Connection)
+final class Pool extends AutoCloseable:
+  def lease(): Resource[Conn] = Resource.fromAutoCloseable(new Conn)
   def close(): Unit = println("pool closed")
-}
 
-class Connection extends AutoCloseable {
+final class Conn 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])
+@main def chaining(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
 
-  val program: String @@ scope.Tag =
-    for {
-      p          <- pool                      // extract Pool from scoped
-      connection <- scope.allocate(p.lease)   // allocate returns Connection @@ Tag
-    } yield connection.query("SELECT 1")
+    val pool: $[Pool] = Resource.fromAutoCloseable(new Pool).allocate
 
-  // execute runs the computation - connection is used inside the yield
-  scope.execute(program)
-}
-// Output: connection closed, then pool closed (LIFO)
+    // $(pool)(_.lease()) : $[Resource[Conn]]
+    val conn: $[Conn] =
+      $(pool)(_.lease()).allocate
+
+    val result: String =
+      $(conn)(_.query("SELECT 1"))
+
+    println(result)
+  }
 ```
 
+This `.allocate` comes from `Scope.ScopedResourceOps` (an extension on `$[Resource[A]]`).
+
 ---
 
-### Registering cleanup manually with `defer`
+### Allocating a bare `Resource[A]` with `.allocate`
 
-Use `scope.defer` when you already have a value and just need to register cleanup.
+A plain `Resource[A]` also has `.allocate` as syntax sugar for `scope.allocate(resource)`:
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
 Scope.global.scoped { scope =>
-  val handle = new java.io.ByteArrayInputStream(Array[Byte](1, 2, 3))
+  import scope.*
 
-  scope.defer { handle.close() }
+  val db: $[Database] =
+    Resource.fromAutoCloseable(new Database).allocate
 
-  val firstByte = handle.read()
-  println(firstByte)
+  $(db)(_.query("SELECT 1"))
 }
 ```
 
-There is also a package-level helper `defer` that only requires a `Finalizer`:
+---
+
+### Classes with `Finalizer` parameters (cleanup-only capability)
+
+If a class only needs cleanup registration, accept a `Finalizer`. DI macros inject it automatically.
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-Scope.global.scoped { scope =>
-  given Finalizer = scope
+final case class Config(url: String)
+object Config:
+  given Unscoped[Config] = Unscoped.derived
 
-  defer { println("cleanup") }
-}
+final class ConnectionPool(config: Config)(using Finalizer):
+  private val pool = s"pool(${config.url})"
+  defer(println(s"shutdown $pool"))
+
+val poolResource: Resource[ConnectionPool] =
+  Resource.from[ConnectionPool](
+    Wire(Config("jdbc://localhost"))
+  )
+
+@main def finalizerInjection(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
+    val pool: $[ConnectionPool] = poolResource.allocate
+    ()
+  }
 ```
 
+When to prefer `Finalizer` over `Scope`:
+
+- you only need `defer`
+- you want to expose minimal power to the class
+
 ---
 
-### Classes with `Finalizer` parameters
+### Classes with `Scope` parameters (scope injection)
 
-If your class needs to register cleanup logic, accept a `Finalizer` parameter (not `Scope`). The wire and resource macros automatically inject the `Finalizer` when constructing such classes.
+If a class needs to allocate resources or create child scopes, accept a `Scope`:
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-class ConnectionPool(config: Config)(implicit finalizer: Finalizer) {
-  private val pool = createPool(config)
-  defer { pool.shutdown() }
-  
-  def getConnection(): Connection = pool.acquire()
-}
+final case class Config(url: String)
+object Config:
+  given Unscoped[Config] = Unscoped.derived
 
-// The macro sees the implicit Finalizer and injects it automatically:
-val resource = Resource.from[ConnectionPool](Wire(Config("jdbc://localhost")))
+final class Connection(config: Config) extends AutoCloseable:
+  def query(sql: String): String = s"[${config.url}] $sql"
+  def close(): Unit = println("connection closed")
 
-Scope.global.scoped { scope =>
-  val pool = scope.allocate(resource)
-  // pool.shutdown() will be called when scope closes
-}
+final class RequestHandler(config: Config)(using scope: Scope):
+  def handle(sql: String): String =
+    scope.scoped { child =>
+      import child.*
+      val conn: $[Connection] = Resource.fromAutoCloseable(new Connection(config)).allocate
+      $(conn)(_.query(sql))
+    }
+
+val handlerResource: Resource[RequestHandler] =
+  Resource.from[RequestHandler](
+    Wire(Config("jdbc://localhost"))
+  )
+
+@main def scopeInjection(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
+    val handler: $[RequestHandler] = handlerResource.allocate
+    val out: String = $(handler)(_.handle("SELECT 1"))
+    println(out)
+  }
 ```
 
-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 `$`
-- The macros pass a `Finalizer` at runtime, so declaring `Scope` would be misleading
+The `Scope`/`Finalizer` parameter can appear in any parameter list position; it's recognized specially by the derivation macros.
 
 ---
 
-### Dependency injection with `Wire` + `Context`
+## Dependency injection (DI) with `Wire` + `Resource.from`
+
+Scope includes a small constructor-based DI layer built on top of `zio.blocks.context.Context`.
+
+### `Wire[-In, +Out]`: a dependency recipe
 
-For manual wiring (when you already have dependencies assembled), use `wire.toResource(ctx)`:
+A `Wire` is a recipe for constructing `Out` from a `Context[In]` (and a `Scope` for finalization):
+
+- `Wire.Shared` → converts to `Resource.shared` (ref-counted sharing)
+- `Wire.Unique` → converts to `Resource.unique` (fresh instance)
+
+#### Manual wire + Context
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 import zio.blocks.context.Context
 
 final case class Config(debug: Boolean)
+object Config:
+  given Unscoped[Config] = Unscoped.derived
 
-val w: Wire.Shared[Boolean, Config] = Wire.shared[Config]
-val deps: Context[Boolean] = Context[Boolean](true)
+val w: Wire.Shared[Boolean, Config] =
+  Wire.shared[Config] // Boolean => Config
 
-Scope.global.scoped { scope =>
-  val cfg: Config @@ scope.Tag =
-    scope.allocate(w.toResource(deps))
+val deps: Context[Boolean] =
+  Context(true)
 
-  val debug: Boolean =
-    (scope $ cfg)(_.debug) // Boolean typically escapes
+@main def wireAndContext(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
 
-  println(debug)
-}
+    val cfg: $[Config] =
+      allocate(w.toResource(deps))
+
+    val debug: Boolean =
+      $(cfg)(_.debug)
+
+    println(debug)
+  }
 ```
 
-Sharing vs uniqueness at the wire level:
+#### Sharing vs uniqueness at the wire level
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-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
+val ws = Wire.shared[Config] // shared recipe
+val wu = Wire.unique[Config] // unique recipe
 ```
 
+The difference is realized when converting to resources (`toResource`) and allocating.
+
 ---
 
-### Dependency injection with `Resource.from[T](wires*)`
+### `Resource.from[T](wires*)`: derive a whole object graph
+
+`Resource.from[T](wires*)` is the primary entry point for DI. It:
 
-`Resource.from[T](wires*)` is the **primary entry point** for dependency injection. It resolves `T` and all its dependencies into a single `Resource[T]`.
+- uses provided wires as overrides
+- auto-creates missing wires for **concrete classes** (defaulting to shared)
+- rejects unmakeable/abstract types unless you provide a wire
+- detects cycles, duplicate providers, and subtype conflicts
+- generates a composed `Resource[T]` via `flatMap` chains (preserving sharing/uniqueness)
+
+Example:
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
 final case class Config(url: String)
+object Config:
+  given Unscoped[Config] = Unscoped.derived
 
-final class Logger {
+final class Logger:
   def info(msg: String): Unit = println(msg)
-}
 
-final class Database(cfg: Config) extends AutoCloseable {
+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(db: Database, logger: Logger) extends AutoCloseable {
+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")
-}
 
-// 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(Config("jdbc:postgresql://localhost/db")) // leaf value
   )
 
-Scope.global.scoped { scope =>
-  val svc = scope.allocate(serviceResource)
-  (scope $ svc)(_.run())
-}
-// Output: running with [jdbc:postgresql://localhost/db] SELECT 1
-// Then: service closed, database closed (LIFO order)
+@main def di(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
+    val svc: $[Service] = serviceResource.allocate
+    $(svc)(_.run())
+  }
 ```
 
-**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`)
-
----
-
-### Injecting traits via subtype wires
+#### Injecting traits via subtype wires
 
-When a dependency is a trait or abstract class, provide a wire for a concrete implementation:
+When a dependency is abstract, provide a wire for a concrete implementation:
 
 ```scala
-import zio.blocks.scope._
+import zio.blocks.scope.*
 
-trait Logger {
+trait Logger:
   def info(msg: String): Unit
-}
 
-final class ConsoleLogger extends Logger {
+final class ConsoleLogger extends Logger:
   def info(msg: String): Unit = println(msg)
-}
 
-final class App(logger: Logger) {
+final class App(logger: Logger):
   def run(): Unit = logger.info("Hello!")
-}
 
-// Wire.shared[ConsoleLogger] satisfies the Logger dependency via subtyping:
 val appResource: Resource[App] =
   Resource.from[App](
-    Wire.shared[ConsoleLogger]
+    Wire.shared[ConsoleLogger] // satisfies Logger via subtyping
   )
 
-Scope.global.scoped { scope =>
-  val app = scope.allocate(appResource)
-  (scope $ app)(_.run())
-}
+@main def traitInjection(): Unit =
+  Scope.global.scoped { scope =>
+    import scope.*
+    val app: $[App] = appResource.allocate
+    $(app)(_.run())
+  }
 ```
 
-**Single instance for diamond patterns:**
+#### Diamond patterns share a single instance (when appropriate)
 
 ```scala
+import zio.blocks.scope.*
+
 trait Service
-class LiveService extends Service
-class NeedsService(s: Service)
-class NeedsLive(l: LiveService)
-class App(a: NeedsService, b: NeedsLive)
+final class LiveService extends Service
+final class NeedsService(s: Service)
+final class NeedsLive(l: LiveService)
+final 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
+val appResource: Resource[App] =
+  Resource.from[App](
+    Wire.shared[LiveService]
+  )
+// LiveService instantiations: 1
 ```
 
 ---
 
-### Interop escape hatch: `leak`
+## Common compile errors (and what they mean)
 
-Sometimes you must hand a raw value to code that cannot work with `@@` types.
+This module produces two kinds of compile-time feedback:
 
-```scala
-import zio.blocks.scope._
-
-Scope.global.scoped { scope =>
-  val db = scope.allocate(Resource(new Database))
+- **Plain macro aborts** for unsafe `$` usage
+- **ASCII-rendered** errors/warnings for DI derivation + leak warnings (via `internal.ErrorMessages`)
 
-  val raw: Database = leak(db) // emits a compiler warning
-  // thirdParty(raw)
-}
-```
+### Unsafe use inside `$`
 
-**Warning:** leaking bypasses compile-time guarantees. The value may be used after its scope closes. Use only when unavoidable.
+Typical messages include:
 
----
+```
+Unsafe use of scoped value: the lambda parameter cannot be passed as an argument to a function or method.
+```
 
-## Common compile errors
+Other variants:
 
-The scope macros produce beautiful, actionable compile-time error messages with ASCII diagrams and helpful hints:
+- `Unsafe use of scoped value: the lambda parameter cannot be captured in a nested lambda or closure.`
+- `Unsafe use of scoped value: the lambda parameter must only be used as a method receiver ...`
+- `$ requires a lambda literal: (scope $ x)(a => a.method()). Method references and variables are not supported.`
 
-### Not a class (Wire.shared/unique on trait or abstract class)
+### Not a class (`Wire.shared/unique` on a trait / abstract)
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ─────────────────────────────────────────────────────────────────
 
   Cannot derive Wire for MyTrait: not a class.
 
   Hint: Use Wire.Shared / Wire.Unique directly.
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
+```
+
+### No primary constructor
+
+```
+── Scope Error ─────────────────────────────────────────────────────────────────
+
+  MyType has no primary constructor.
+
+  Hint: Use Wire.Shared / Wire.Unique directly
+        with a custom construction strategy.
+
+───────────────────────────────────────────────────────────────────────────────
+```
+
+### `Resource.from[T]` used when `T` has dependencies
+
+```
+── Scope Error ─────────────────────────────────────────────────────────────────
+
+  Resource.from[MyService] cannot be derived.
+
+  MyService has dependencies that must be provided:
+    • Config
+    • Logger
+
+  Hint: Use Resource.from[MyService](wire1, wire2, ...)
+        to provide wires for all dependencies.
+
+───────────────────────────────────────────────────────────────────────────────
 ```
 
 ### Unmakeable type (primitives, functions, collections)
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ─────────────────────────────────────────────────────────────────
 
   Cannot auto-create String
 
   This type (primitive, collection, or function) cannot be auto-created.
 
   Required by:
-    └── Config
-        └── App
+  ├── Config
+    └── App
 
   Fix: Provide Wire(value) with the desired value:
 
@@ -733,20 +863,20 @@ The scope macros produce beautiful, actionable compile-time error messages with
       ...
     )
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
-### Abstract type (trait or abstract class)
+### Abstract type (trait / abstract class dependency)
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ─────────────────────────────────────────────────────────────────
 
   Cannot auto-create Logger
 
   This type is abstract (trait or abstract class).
 
   Required by:
-    └── App
+  └── App
 
   Fix: Provide a wire for a concrete implementation:
 
@@ -755,13 +885,13 @@ The scope macros produce beautiful, actionable compile-time error messages with
       ...
     )
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
 ### Duplicate providers (ambiguous wires)
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ────────────────────────────────────────────────────────────────
 
   Multiple providers for Service
 
@@ -771,13 +901,13 @@ The scope macros produce beautiful, actionable compile-time error messages with
 
   Hint: Remove duplicate wires or use distinct wrapper types.
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
 ### Dependency cycle
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ────────────────────────────────────────────────────────────────
 
   Dependency cycle detected
 
@@ -793,13 +923,13 @@ The scope macros produce beautiful, actionable compile-time error messages with
     • Using lazy initialization
     • Restructuring dependencies
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
 ### Subtype conflict (related dependency types)
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ────────────────────────────────────────────────────────────────
 
   Dependency type conflict in MyService
 
@@ -812,16 +942,16 @@ The scope macros produce beautiful, actionable compile-time error messages with
   To fix this, wrap one or both types in a distinct wrapper:
 
     case class WrappedInputStream(value: InputStream)
-    or
+  or
     opaque type WrappedInputStream = InputStream
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
-### Duplicate parameter types in constructor
+### Duplicate parameter types in a constructor
 
 ```
-── Scope Error ──────────────────────────────────────────────────────────────
+── Scope Error ────────────────────────────────────────────────────────────────
 
   Constructor of App has multiple parameters of type String
 
@@ -830,118 +960,240 @@ The scope macros produce beautiful, actionable compile-time error messages with
   Fix: Wrap one parameter in an opaque type to distinguish them:
 
     opaque type FirstString = String
-    or
+  or
     case class FirstString(value: String)
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
 ### Leak warning
 
-When using `leak(value)` to escape the scoped type system:
-
 ```
-── Scope Warning ────────────────────────────────────────────────────────────
+── Scope Warning ───────────────────────────────────────────────────────────────
 
   leak(db)
        ^
        |
 
-  Warning: db is being leaked from scope MyScope.
+  Warning: db is being leaked from scope zio.blocks.scope.Scope.Child[...].
   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.
+     instance for it so you do not need to leak it.
 
-────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────
 ```
 
 ---
 
-## API reference (selected)
+## API reference (from source)
+
+Examples below use Scala 3 syntax. Scala 2.13 has equivalent APIs, but macro signatures differ slightly (notably `$`'s return type encoding).
 
 ### `Scope`
 
-Core methods (Scala 3 `using` vs Scala 2 `implicit` differs, but the shapes are the same):
+```scala
+sealed abstract class Scope extends Finalizer with ScopeVersionSpecific
+```
+
+Associated types and hierarchy:
+
+- `type $[+A]`
+- `type Parent <: Scope`
+- `val parent: Parent`
+- `def isClosed: Boolean`
+- `def isOwner: Boolean`
+
+Core operations:
 
 ```scala
-final class Scope[ParentTag, Tag0 <: ParentTag] {
-  type Tag = Tag0
+def scoped[A](f: (child: Scope.Child[this.type]) => A)(using Unscoped[A]): A
 
-  def allocate[A](resource: Resource[A]): A @@ Tag
-  def defer(f: => Unit): Unit
+def allocate[A](resource: Resource[A]): $[A]
+def allocate[A <: AutoCloseable](value: => A): $[A]
 
-  // Apply function to scoped value - executes immediately, always returns scoped
-  def $[A, B](scoped: A @@ this.Tag)(f: A => B): B @@ Tag
+infix transparent inline def $[A, B](sa: $[A])(inline f: A => B): B | $[B]
 
-  // Execute scoped computation - runs immediately, always returns scoped
-  def execute[A](scoped: A @@ this.Tag): A @@ Tag
+def lower[A](value: parent.$[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
-}
+override def defer(f: => Unit): DeferHandle
+
+def open(): $[Scope.OpenScope]
+
+inline def leak[A](inline sa: $[A]): A
 ```
 
-### `Resource`
+Notes:
+
+- `$` requires a **lambda literal** and enforces safe receiver-only usage.
+- `$` returns `B` if `Unscoped[B]` exists; otherwise returns `$[B]`.
+- If the scope is closed, `$` / `allocate` / `open` / `lower` return default values and perform no work.
+
+Syntax enrichments available after `import scope.*` inside a scope:
+
+```scala
+implicit class ScopedResourceOps[A](sr: $[Resource[A]]):
+  def allocate: $[A]
+
+implicit class ResourceOps[A](r: Resource[A]):
+  def allocate: $[A]
+```
+
+---
+
+### `Scope.global`
+
+```scala
+object Scope:
+  object global extends Scope
+```
+
+Properties:
+
+- `type $[+A] = A` (identity)
+- `isOwner` always returns `true`
+- JVM: finalizers run at shutdown via a shutdown hook
+- Scala.js: shutdown hook is not available
+
+---
+
+### `Scope.OpenScope`
+
+```scala
+case class OpenScope(scope: Scope, close: () => Finalization)
+```
+
+- `scope`: the child scope
+- `close()`: detaches from parent, runs child finalizers (LIFO), returns `Finalization`
+
+---
+
+### `Finalizer`
+
+```scala
+trait Finalizer:
+  def defer(f: => Unit): DeferHandle
+```
+
+A minimal capability interface for registering cleanup.
+
+Also available as a package-level helper:
+
+```scala
+def defer(finalizer: => Unit)(using fin: Finalizer): DeferHandle
+```
+
+---
+
+### `DeferHandle`
+
+```scala
+abstract class DeferHandle:
+  def cancel(): Unit
+```
+
+- `cancel()` is thread-safe and idempotent
+- cancellation is O(1) (true removal from a concurrent map)
+
+---
+
+### `Finalization`
+
+```scala
+final class Finalization(val errors: zio.blocks.chunk.Chunk[Throwable]):
+  def isEmpty: Boolean
+  def nonEmpty: Boolean
+  def orThrow(): Unit
+  def suppress(initial: Throwable): Throwable
+
+object Finalization:
+  val empty: Finalization
+  def apply(errors: Chunk[Throwable]): Finalization
+```
+
+---
+
+### `Resource[+A]`
 
 ```scala
-sealed trait Resource[+A]
+sealed trait Resource[+A]:
+  def map[B](f: A => B): Resource[B]
+  def flatMap[B](f: A => Resource[B]): Resource[B]
+  def zip[B](that: Resource[B]): Resource[(A, B)]
+```
 
-object Resource {
+Companion constructors:
+
+```scala
+object Resource:
   def apply[A](value: => A): Resource[A]
-  def acquireRelease[A](acquire: => A)(release: A => Unit): Resource[A]
   def fromAutoCloseable[A <: AutoCloseable](thunk: => A): Resource[A]
+  def acquireRelease[A](acquire: => A)(release: A => Unit): Resource[A]
+  def shared[A](f: Scope => A): Resource[A]
+  def unique[A](f: Scope => A): Resource[A]
 
-  // Macro - DI entry point (can also be called with no args for zero-dep classes):
-  def from[T](wires: Wire[?, ?]*): Resource[T]
-
-  // Internal (used by generated code):
-  def shared[A](f: Finalizer => A): Resource[A]
-  def unique[A](f: Finalizer => A): Resource[A]
-}
+  inline def from[T]: Resource[T]
+  inline def from[T](inline wires: Wire[?, ?]*): Resource[T]
 ```
 
-### `Wire`
+Notes:
+
+- `Resource.from[T]` (no args) only works when `T` has **no non-scope dependencies** (constructor params may include `Scope`/`Finalizer`).
+- Use `Resource.from[T](wires*)` to provide/override dependencies and derive the full graph.
+
+---
+
+### `Wire[-In, +Out]`
 
 ```scala
-sealed trait Wire[-In, +Out] {
+sealed trait Wire[-In, +Out]:
   def isShared: Boolean
+  def isUnique: Boolean = !isShared
+
   def shared: Wire.Shared[In, Out]
   def unique: Wire.Unique[In, Out]
+
   def toResource(deps: zio.blocks.context.Context[In]): Resource[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]
-}
+Wires:
+
+```scala
+object Wire:
+  final case class Shared[-In, +Out](makeFn: (Scope, Context[In]) => Out) extends Wire[In, Out]
+  final case class Unique[-In, +Out](makeFn: (Scope, Context[In]) => Out) extends Wire[In, Out]
+
+  def apply[T](t: T): Wire.Shared[Any, T]
+
+  transparent inline def shared[T]: Wire.Shared[?, T]
+  transparent inline def unique[T]: Wire.Unique[?, T]
 ```
 
+Notes:
+
+- `Wire(t)` wraps a pre-existing value; if it's `AutoCloseable`, `close()` is registered automatically when used.
+
 ---
 
-## Mental model recap
-
-- Use `Scope.global.scoped { scope => ... }` to create a safe region.
-- 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
+### `Unscoped[A]`
+
+```scala
+trait Unscoped[A]
+
+object Unscoped:
+  inline given derived[A](using scala.deriving.Mirror.Of[A]): Unscoped[A]
+  // plus many built-in givens (primitives, collections, time, UUID, Chunk, ...)
+```
+
+---
+
+## Practical guidance (summary)
+
+- Allocate in a scope: `resource.allocate` (inside `Scope.global.scoped { scope => import scope.* ... }`)
+- Use scoped values only through: `(scope $ value)(...)`
+- Return only `Unscoped` data from `scoped` blocks
+- Use `lower` to use parent values inside a child
+- If `$` returns `$[Resource[A]]`, call `.allocate` on it (scoped resource chaining)
+- Use `open()` for explicitly-managed, cross-thread capable scopes
+- Use `leak` only when interop forces it; prefer `Unscoped` for pure data