@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/endpoint/index.md

@@ -1,6 +1,6 @@
 ---
 id: index
-title: "Endpoint (Module)"
+title: "Endpoint"
 ---
 
 `zio-blocks-endpoint` is a **pure, type-safe HTTP endpoint descriptor** for building clients, servers, and API documentation from a single source of truth. It provides composable types that describe every part of an HTTP surface — routes, query parameters, headers, request bodies, response bodies, error shapes, and authentication — without committing to any particular server or client implementation.
@@ -41,18 +41,18 @@ The endpoint module is a cross-platform library (JVM + Scala.js). Add the depend
 
 **JVM (Scala 3.x):**
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-endpoint" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-endpoint" % "0.0.55"
 ```
 
 **Scala.js (Scala 3.x):**
 ```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-endpoint" % "0.0.51"
+libraryDependencies += "dev.zio" %%% "zio-blocks-endpoint" % "0.0.55"
 ```
 
 **For Scala 3.7+**, the module name is rewritten to `zio-blocks-next-endpoint`:
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-next-endpoint" % "0.0.51"  // JVM
-libraryDependencies += "dev.zio" %%% "zio-blocks-next-endpoint" % "0.0.51" // Scala.js
+libraryDependencies += "dev.zio" %% "zio-blocks-next-endpoint" % "0.0.55"  // JVM
+libraryDependencies += "dev.zio" %%% "zio-blocks-next-endpoint" % "0.0.55" // Scala.js
 ```
 
 Supported Scala versions: 3.x (Scala 3 only — the endpoint module uses Scala 3-only DSL and macro code).
@@ -227,22 +227,6 @@ cd zio-blocks
 Constructs `Endpoint` values from `RoutePattern` and chains request body, query parameters, headers, success outputs, response headers, and typed error variants using the builder DSL.
 
 ```scala title="endpoint-examples/src/main/scala/endpointexamples/BasicEndpointDefinition.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package endpointexamples
 
 import scala.language.implicitConversions
@@ -316,22 +300,6 @@ sbt "endpoint-examples/runMain endpointexamples.BasicEndpointDefinition"
 Builds `HttpCodec` atoms for query parameters, request headers, response headers, request bodies, response bodies, and status codes. Shows sequential composition with `++` and alternative composition with `|`.
 
 ```scala title="endpoint-examples/src/main/scala/endpointexamples/HttpCodecConstruction.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package endpointexamples
 
 import zio.blocks.chunk.Chunk
@@ -432,22 +400,6 @@ sbt "endpoint-examples/runMain endpointexamples.HttpCodecConstruction"
 Demonstrates all `SegmentCodec` kinds, intra-segment composition with `~` for patterns like `v42`, bidirectional `PathCodec` decode and format, `RoutePattern` matching, `nest` for version prefixes, and `transform`/`transformOrFail` for domain type mapping.
 
 ```scala title="endpoint-examples/src/main/scala/endpointexamples/PathAndSegmentCodecs.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package endpointexamples
 
 import scala.language.implicitConversions
@@ -535,7 +487,7 @@ import zio.http.{Method, Path}
   final case class UserId(value: Int)
 
   val userIdCodec: PathCodec[UserId] =
-    PathCodec.int("id").transform[UserId](UserId(_), _.value)
+    PathCodec.int("id").transform(UserId(_), _.value)
 
   val decodedUserId = userIdCodec.decode(Path("/99"))
   println(s"UserId decoded: $decodedUserId")
@@ -544,9 +496,9 @@ import zio.http.{Method, Path}
   val positiveInt: PathCodec[Int] =
     PathCodec
       .int("count")
-      .transformOrFail[Int](
+      .transformOrFail(
         n => if (n > 0) Right(n) else Left(s"Expected positive, got $n"),
-        n => Right(n)
+        (n: Int) => Right(n)
       )
 
   println(s"Positive decode 5:  ${positiveInt.decode(Path("/5"))}")
@@ -567,22 +519,6 @@ sbt "endpoint-examples/runMain endpointexamples.PathAndSegmentCodecs"
 Shows all built-in `AuthType` variants (None, Basic, Bearer, Digest), a custom API-key variant, OR composition with `|`, scoped bearer tokens for OAuth scope metadata, and overriding the default unauthorized status.
 
 ```scala title="endpoint-examples/src/main/scala/endpointexamples/AuthTypePatterns.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package endpointexamples
 
 import scala.language.implicitConversions
@@ -673,22 +609,6 @@ sbt "endpoint-examples/runMain endpointexamples.AuthTypePatterns"
 Assembles a full users CRUD API combining `Endpoint`, `RoutePattern`, `PathCodec`, `SegmentCodec`, `HttpCodec`, `AuthType`, and `RouteTree`. Demonstrates versioned routes via `nest`, Scala 3 union error types via `orOutError`, and `RouteTree` lookup priority for efficient O(depth) dispatch.
 
 ```scala title="endpoint-examples/src/main/scala/endpointexamples/CompleteApiDefinition.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package endpointexamples
 
 import scala.language.implicitConversions
@@ -715,7 +635,7 @@ import zio.http.{Method, Path, Status}
   final case class UserId(value: Int)
 
   val userIdPath: PathCodec[UserId] =
-    PathCodec.int("id").transform[UserId](UserId(_), _.value)
+    PathCodec.int("id").transform(UserId(_), _.value)
 
   // --- Endpoint definitions ---
 

package/reference/endpoint/path-codec.md

@@ -3,16 +3,12 @@ id: path-codec
 title: "PathCodec"
 ---
 
-`PathCodec[A]` is a composable descriptor for URL path structures. It holds a tree of segment codecs connected by concatenation and fallback nodes, and provides bidirectional path conversion: `PathCodec#decode` extracts a typed value from a `Path`, returning `Either[String, A]` (the typed value or error), and `PathCodec#format` formats a typed value back to a `Path`, returning `Either[String, Path]` (the path or error). In addition to its runtime value type `A`, each codec also carries a phantom `PathVars` track that records the ordered list of declared path-variable markers contributed by its dynamic segments. Its definition begins:
+`PathCodec[A]` is a composable descriptor for URL path structures. It holds a tree of segment codecs connected by concatenation and fallback nodes, and provides bidirectional path conversion: `PathCodec#decode` extracts a typed value from a `Path`, returning `Either[String, A]` (the typed value or error), and `PathCodec#format` formats a typed value back to a `Path`, returning `Either[String, Path]` (the path or error). Its definition begins:
 
 ```scala
-sealed trait PathCodec[A] {
-  type PathVars
-}
+sealed trait PathCodec[A]
 ```
 
-`PathVars` is purely type-level: it has zero runtime footprint and does not affect decoding or formatting. It exists so downstream tooling (for example, handler macros or static checks) can recover which named path variables a route declared, in order, and whether any of them were explicitly marked as ignored.
-
 ## Motivation
 
 URL paths need both matching and generation. A routing library that only matches paths requires a separate URL-builder for links and redirects, leading to duplication and drift. `PathCodec` is bidirectional: every codec that can decode `/users/42` into `42: Int` can also format `42` back into `/users/42`. This makes it safe to use the same path definition for routing, link generation, and OpenAPI path parameter documentation.
@@ -49,9 +45,7 @@ val boolFlag: PathCodec[Boolean]          = PathCodec.bool("enabled")
 val rest: PathCodec[zio.http.Path]        = PathCodec.trailing
 ```
 
-`PathCodec.literal` is a macro that validates the value at compile time — it rejects empty strings and strings containing `/` or characters requiring URL encoding.
-
-For literal names like `PathCodec.int("id")`, the name is preserved as a singleton type inside `PathVars`, so the phantom track remembers not just that the codec captures an `Int`, but that it came from the path variable named `"id"`.
+`PathCodec.literal` validates the value — it rejects empty strings and strings containing `/` or characters requiring URL encoding.
 
 ### From a string
 
@@ -79,27 +73,21 @@ val combined = PathCodec(SegmentCodec.literal("v") ~ SegmentCodec.int("version")
 
 There is also an implicit conversion from `SegmentCodec[A]` to `PathCodec[A]` and from `String` to `PathCodec[Unit]`, so both can appear directly in `/` expressions.
 
-## Phantom `PathVars` Track and `.unused`
-
-Every dynamic path segment contributes one phantom marker to `PathCodec#PathVars`:
+## Marking a capture as unused with `.unused`
 
-- `PathCodec.int("id")` contributes `PathVar["id", Int]`
-- `PathCodec.uuid("orderId")` contributes `PathVar["orderId", UUID]`
-- literal segments and `PathCodec.trailing` contribute no markers
-
-Sequential composition with `/` or `++` concatenates those markers in declaration order, matching the left-to-right route shape.
-
-Sometimes a route needs to capture a segment for matching or formatting, but a downstream handler intentionally does not consume that variable. For that case, single-variable codecs expose `.unused`, which keeps the runtime behavior identical while relabeling the phantom marker to `PathVar.Ignored[Name, Type]`:
+Sometimes a route needs to capture a segment for matching or formatting, but a downstream handler intentionally does not consume that variable. `PathCodec` instances expose `.unused`, which converts the value type to `Unit` while keeping the same path shape:
 
 ```scala
 import zio.blocks.endpoint._
 import zio.blocks.endpoint.RoutePattern._
 
 val userId: PathCodec[Int] = PathCodec.int("id")
-val ignoredUserId: PathCodec[Int] = PathCodec.int("id").unused
+val ignoredUserId: PathCodec[Unit] = PathCodec.int("id").unused
 ```
 
-`.unused` has zero runtime cost: decoding, formatting, rendering, and matching all behave exactly the same as the non-`.unused` codec. The only difference is the phantom `PathVars` marker, which tells tooling that this declared path variable was intentionally ignored.
+`.unused` converts the path codec's value type to `Unit`: the route still matches the same shape and renders `{name}` placeholders, but decoding yields `Unit` instead of the captured value, so no handler parameter is required. `format` on an unused path fails because there is no value to encode back into the ignored segment.
+
+`PathCodec.unused` composes normally with `/` and is unaffected by `transform` / `transformOrFail` lifting.
 
 ## Composition
 
@@ -204,7 +192,7 @@ import zio.blocks.endpoint.PathCodec._
 final case class UserId(value: Int)
 
 val userIdCodec: PathCodec[UserId] =
-  PathCodec.int("id").transform[UserId](UserId(_), _.value)
+  PathCodec.int("id").transform(UserId(_), _.value)
 ```
 
 ### `PathCodec#transformOrFail`
@@ -216,9 +204,9 @@ import zio.blocks.endpoint._
 import zio.blocks.endpoint.RoutePattern._
 
 val nonNegativeInt: PathCodec[Int] =
-  PathCodec.int("count").transformOrFail[Int](
+  PathCodec.int("count").transformOrFail(
     n => if (n >= 0) Right(n) else Left(s"Expected non-negative, got $n"),
-    n => Right(n)
+    (n: Int) => Right(n)
   )
 ```
 

package/reference/endpoint/route-pattern.md

@@ -3,7 +3,7 @@ id: route-pattern
 title: "RoutePattern"
 ---
 
-`RoutePattern[A]` pairs an HTTP method with a typed path pattern. It is the primary routing descriptor in `zio-blocks-endpoint`: every `Endpoint` carries a `RoutePattern` that determines which HTTP method and URL path it matches. Like `PathCodec`, it also carries a phantom `PathVars` track that mirrors the ordered path-variable declarations contributed by its path codec. Its shape is:
+`RoutePattern[A]` pairs an HTTP method with a typed path pattern. It is the primary routing descriptor in `zio-blocks-endpoint`: every `Endpoint` carries a `RoutePattern` that determines which HTTP method and URL path it matches. Its shape is:
 
 ```scala
 final case class RoutePattern[A](
@@ -13,13 +13,11 @@ final case class RoutePattern[A](
 )
 ```
 
-The `PathVars` track is not a constructor parameter because it is purely type-level: it has zero runtime footprint and is derived from `pathCodec`. A literal-only route contributes no path-variable markers; a route with dynamic segments preserves them in declaration order.
-
 ## Motivation
 
 HTTP routing requires matching both a method (GET, POST, …) and a path (`/users/42`). `RoutePattern` holds both in a single typed value. The type parameter `A` is the type of values extracted from the dynamic path segments — `Unit` for fully-literal paths, `Int` for a single integer segment, `(String, UUID)` for two dynamic segments, and so on.
 
-Using a typed route pattern means route construction and path extraction are verified at compile time: the type of the extracted path value is always consistent with the path codec definition. The phantom `PathVars` track keeps the declared path-variable names and ignored-variable markers available to tooling without changing runtime behavior.
+Using a typed route pattern means route construction and path extraction are verified at compile time: the type of the extracted path value is always consistent with the path codec definition.
 
 ## Construction
 
@@ -85,7 +83,7 @@ val catchAll: RoutePattern[Path]   = RoutePattern.any
 val getAny: RoutePattern[Path]     = RoutePattern.any(Method.GET)
 ```
 
-These helpers preserve `PathVars = SegmentCodec.NoPathVars`: a trailing catch-all captures a `zio.http.Path` runtime value, but it does not declare any named path variables.
+A trailing catch-all captures a `zio.http.Path` runtime value without declaring any named path variables.
 
 ## Path Composition with `/`
 
@@ -99,7 +97,7 @@ import zio.http.Method
 val route = Method.GET / "users" / PathCodec.int("id") / "posts"
 ```
 
-Each `/` call produces a new `RoutePattern` with a widened type. The type is automatically flattened, eliminating `Unit` components: `Unit / Int / Unit` becomes `Int`, not `((Unit, Int), Unit)`. At the same time, the phantom `PathVars` track is concatenated left-to-right, so a route like `Method.GET / PathCodec.int("id") / PathCodec.string("slug")` preserves the declaration order of `"id"` then `"slug"` for downstream tooling.
+Each `/` call produces a new `RoutePattern` with a widened type. The type is automatically flattened, eliminating `Unit` components: `Unit / Int / Unit` becomes `Int`, not `((Unit, Int), Unit)`.
 
 ## Decoding and Encoding
 

package/reference/endpoint/segment-codec.md

@@ -3,19 +3,13 @@ id: segment-codec
 title: "SegmentCodec"
 ---
 
-`SegmentCodec[A]` describes a single URL path segment. It supports basic typed segment kinds — `SegmentCodec.bool`, `SegmentCodec.int`, `SegmentCodec.long`, `SegmentCodec.string`, `SegmentCodec.uuid`, and `SegmentCodec.literal` — as well as intra-segment composition via `~`, which combines multiple typed parts within a single path segment (for example, `v42` as a literal prefix followed by an integer). Ambiguous combinations are rejected at compile time by a Scala 3 macro. Alongside the runtime decoded value type `A`, every segment codec also carries phantom metadata describing its boundary behavior and any declared path variable. The core type-level shape is:
+`SegmentCodec[A]` describes a single URL path segment. It supports basic typed segment kinds — `SegmentCodec.bool`, `SegmentCodec.int`, `SegmentCodec.long`, `SegmentCodec.string`, `SegmentCodec.uuid`, and `SegmentCodec.literal` — as well as intra-segment composition via `~`, which combines multiple typed parts within a single path segment (for example, `v42` as a literal prefix followed by an integer). Ambiguous adjacencies (`string ~ string`, numeric ~ numeric in any `Int`/`Long` order, anything involving `Trailing`) are rejected at runtime with `IllegalArgumentException`. Combine representation first, then transform: `transform` / `transformOrFail` lift a segment into a `PathCodec`, ending intra-segment composition. The core type-level shape is:
 
 ```scala
-sealed trait SegmentCodec[A] {
-  type Prefix <: SegmentCodec.BoundaryTag
-  type Suffix <: SegmentCodec.BoundaryTag
-  type PathVars
-}
+sealed trait SegmentCodec[A]
 ```
 
-`PathVars` is purely type-level: it has zero runtime footprint. Capturing segments contribute one marker (for example `PathVar["id", Int]`), while non-capturing segments like `literal` and `Trailing` contribute none.
-
-(The trait also includes additional members for documentation, examples, formatting, and rendering.)
+(The trait also includes methods for `~` composition, `transform` lifting, documentation, examples, formatting, and rendering.)
 
 ## Motivation
 
@@ -23,7 +17,7 @@ Standard routing libraries treat path segments as plain strings, deferring all p
 
 - **Type-safe path building**: `PathCodec.int("id")` produces a `PathCodec[Int]`, not `PathCodec[String]`.
 - **Bidirectional conversion**: every `SegmentCodec` can both decode a string into `A` and format an `A` back to a string.
-- **Compile-time combination validation**: the `~` operator is a macro that validates boundary constraints, rejecting combinations like `string ~ string` before the code compiles.
+- **Fail-fast combination validation**: the `~` operator rejects ambiguous adjacencies (`string ~ string`, numeric ~ numeric) at composition time, so bad splits surface immediately instead of misrouting.
 
 ## Segment Kinds
 
@@ -57,19 +51,16 @@ val stringSeg: SegmentCodec[String]       = SegmentCodec.string("slug")
 val uuidSeg: SegmentCodec[java.util.UUID] = SegmentCodec.uuid("id")
 ```
 
-When the name is written as a literal string, that literal is preserved in the phantom `PathVars` marker. For example, `SegmentCodec.int("id")` contributes `PathVar["id", Int]`.
-
-If a route should keep a captured segment for matching/formatting but explicitly mark it as intentionally unused for downstream tooling, the leaf dynamic segment codecs expose `.unused`:
+If a route should capture a segment for matching or formatting but the handler intentionally does not consume the variable, the leaf dynamic segment codecs expose `.unused`:
 
 ```scala
-import zio.blocks.endpoint._
-import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.endpoint.SegmentCodec
 
-val requiredId: SegmentCodec[Int] = SegmentCodec.int("id")
-val ignoredId: SegmentCodec[Int] = SegmentCodec.int("id").unused
+val requiredId = SegmentCodec.int("id")
+val ignoredId  = SegmentCodec.int("id").unused
 ```
 
-`.unused` keeps decoding, formatting, rendering, and composition identical, but changes the phantom marker from `PathVar[Name, Type]` to `PathVar.Ignored[Name, Type]`.
+`.unused` keeps decoding, formatting, rendering, and composition identical. The only difference is at the type level: downstream tooling (handler macros, static checks) sees the variable as intentionally unused and does not require the handler to bind it.
 
 The ordering of match priority in the routing trie follows the kind: `Literal` matches first, then `Int`, `Long`, `UUID`, `Bool`, `String`, `Combined`, and `Trailing` last.
 
@@ -99,14 +90,14 @@ val versionSeg: SegmentCodec[Int] =
 
 The type is automatically flattened (eliminating `Unit` from the literal), so the resulting codec decodes `"v42"` into `42` and formats `42` back to `"v42"`.
 
-### Compile-time boundary validation
+### Runtime adjacency validation
 
-The `~` operator is a macro that checks `BoundaryTag` phantom types at compile time. Two categories of combination are always rejected:
+The `~` operator checks the physical adjacency at composition time. Two categories of combination are always rejected with `IllegalArgumentException`:
 
 - **Two string segments**: `SegmentCodec.string("a") ~ SegmentCodec.string("b")` — both are unbounded greedy matchers; the parser cannot know where one ends and the other begins.
-- **Two numeric segments**: `SegmentCodec.int("a") ~ SegmentCodec.int("b")` — numeric segments are also ambiguously bounded.
+- **Two numeric segments**: `SegmentCodec.int("a") ~ SegmentCodec.int("b")` — numeric segments are also ambiguously bounded (any `Int`/`Long` order, including through a flattened combined tail).
 
-Combinations that are safe compile successfully:
+Anything involving `Trailing` is likewise rejected. Combinations that are safe compose normally:
 
 ```scala
 import zio.blocks.endpoint._
@@ -122,11 +113,11 @@ val prefixedUuid =
   SegmentCodec.string("prefix") ~ SegmentCodec.uuid("id") ~ SegmentCodec.string("suffix")
 ```
 
-Attempting an ambiguous combination like `string ~ string` produces a compiler error describing the constraint violation, not a runtime failure.
+Attempting an ambiguous combination like `string ~ string` throws `IllegalArgumentException` at composition time, not a silent misroute.
 
 ## Type Transformations
 
-Use these methods to remap the value a codec decodes or encodes without changing the underlying segment structure or its compile-time boundary tags.
+Combine representation first, then transform: `transform` / `transformOrFail` map the decoded segment value into a domain type and lift the segment into a `PathCodec`, ending intra-segment composition (a transformed codec no longer offers `~`; compose with `/` instead).
 
 ### `SegmentCodec#transform`
 
@@ -138,14 +129,10 @@ import zio.blocks.endpoint.RoutePattern._
 
 final case class UserId(value: java.util.UUID)
 
-val userIdSeg: SegmentCodec[UserId] =
-  SegmentCodec.uuid("id").transform[UserId](UserId(_), _.value)
+val userIdCodec: PathCodec[UserId] =
+  SegmentCodec.uuid("id").transform(UserId(_), _.value)
 ```
 
-`SegmentCodec#transform` preserves the `BoundaryTag` types of the original codec, so transformed codecs still participate in compile-time `~` boundary validation.
-
-It also preserves the original `PathVars` marker unchanged: transforming a captured `SegmentCodec.int("id")` into a domain type still records that the segment came from the declared `"id"` path variable.
-
 ### `SegmentCodec#transformOrFail`
 
 When decoding can fail, use `SegmentCodec#transformOrFail`. A `Left` result causes segment matching to fail for that candidate:
@@ -156,8 +143,8 @@ import zio.blocks.endpoint.RoutePattern._
 
 final case class PositiveInt(value: Int)
 
-val positiveIntSeg: SegmentCodec[PositiveInt] =
-  SegmentCodec.int("count").transformOrFail[PositiveInt](
+val positiveIntCodec: PathCodec[PositiveInt] =
+  SegmentCodec.int("count").transformOrFail(
     n => if (n > 0) Right(PositiveInt(n)) else Left(s"Expected positive, got $n"),
     p => Right(p.value)
   )