@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/config/errors.md

@@ -0,0 +1,278 @@
+---
+id: errors
+title: "Configuration Errors"
+sidebar_label: "Errors"
+---
+
+`ConfigError` is the failure type for every configuration operation. It is a sealed hierarchy divided into four category traits, so code can match on the kind of problem — a missing key, an unparseable value, a source-level failure, a derivation failure — without enumerating every constructor. `ConfigLoadException` wraps a set of errors when a load is allowed to throw. The hierarchy:
+
+```scala
+sealed trait ConfigError extends NoStackTrace {
+  def message: String
+  override def getMessage: String = message
+}
+
+sealed trait ConfigParseError      extends ConfigError
+sealed trait ConfigValidationError extends ConfigError
+sealed trait ConfigSourceError     extends ConfigError
+sealed trait ConfigDerivationError extends ConfigError
+```
+
+## Motivation
+
+Configuration failures need three properties that a plain exception does not provide.
+
+They need to be **plural**. A config file with four mistakes should report four mistakes, so the person fixing it makes one pass rather than four. That rules out throwing at the first problem, which is why every decoding operation returns `Either[::[ConfigError], A]` — a non-empty list, so a `Left` is guaranteed to say something.
+
+They need to be **cheap**. `ConfigError` extends `NoStackTrace`, so constructing one does not capture a stack trace. Config errors are diagnosed by reading the message, not by reading a trace through the deriver's internals, and a decode that fails on twenty fields should not pay for twenty stack captures.
+
+They need to be **classifiable**. Whether a value was missing, malformed, or rejected by the source changes what the operator should do about it. The four category traits exist so that distinction survives into your error handling.
+
+## Category Traits
+
+Every concrete error extends exactly one category, except `ConfigError.Composite`, which extends `ConfigError` directly because it aggregates errors that may span categories:
+
+| Category                 | Meaning                                        | Constructors                                            |
+| ------------------------ | ---------------------------------------------- | ------------------------------------------------------- |
+| `ConfigParseError`       | Value present but not convertible               | `InvalidValue`, `ParseError`                             |
+| `ConfigValidationError`  | Value parsed but semantically rejected          | *(none built in)*                                        |
+| `ConfigSourceError`      | Problem with the source itself                  | `MissingKey`, `DuplicateKey`, `Unauthorized`             |
+| `ConfigDerivationError`  | Schema-driven decoding could not proceed        | `UnknownDiscriminator`, `MissingDiscriminatorKey`         |
+| *(no category)*          | Aggregate of several errors                     | `Composite`                                              |
+
+:::note[`ConfigValidationError` has no constructors]
+The category is declared and documented, but no error in the module currently extends it, and because the trait is sealed it cannot be extended from outside. Matching on it compiles and never matches. Validation failures raised by wrapper types surface as `ConfigError.InvalidValue` instead.
+:::
+
+## Error Constructors
+
+Each constructor carries the fields needed to act on the failure without re-reading the config, and renders them into a single-line `message`.
+
+### ConfigError.MissingKey
+
+A required key was not found. Produced by primitive decoding when the key is absent and the field has neither a default nor an `Option` type:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+```
+
+The error names the dotted path and the source that was searched, which for a composed source is the pipe-joined id of every source in the chain:
+
+```scala
+Config.load[Db](ConfigSource.fromMap(Map("port" -> "5432"), "defaults"))
+// res0: Either[::[ConfigError], Db] = Left(
+//   List(MissingKey(path = "host", source = "defaults"))
+// )
+```
+
+`MissingKey` is the error that optional fields and defaults absorb. A field of type `Option[A]` becomes `None`, and a field with a declared default takes that default, but only when *every* error from that field is a `MissingKey` — a mix of missing and invalid still fails.
+
+### ConfigError.InvalidValue
+
+A key was present but its value could not be converted to the expected type. Carries the path, the offending string, a human-readable expected type, the source id, and an optional underlying exception:
+
+```scala
+Config.load[Db](ConfigSource.fromMap(Map("host" -> "localhost", "port" -> "eight"), "defaults"))
+// res1: Either[::[ConfigError], Db] = Left(
+//   List(
+//     InvalidValue(
+//       path = "port",
+//       value = "eight",
+//       expectedType = "Int",
+//       source = "defaults",
+//       cause = Some(java.lang.NumberFormatException: For input string: "eight")
+//     )
+//   )
+// )
+```
+
+The `expectedType` string is derived from the schema's primitive type name. When a `cause` is present, its message is appended to the rendered message, which is where the underlying `NumberFormatException` text comes from.
+
+`InvalidValue` is also what a failing wrapper type produces: if a newtype's constructor throws while wrapping a successfully-decoded inner value, the thrown exception becomes the `cause`.
+
+### ConfigError.ParseError
+
+The raw value could not be decoded at the format level, as distinct from a type mismatch on a well-formed value. Carries the path, source, expected format, and optional cause. The HOCON adapter produces it when the document itself is malformed, and the JVM file loader produces it for a missing file or a rejected include path.
+
+The difference from `InvalidValue` is which layer failed. `InvalidValue` means "this string is not an `Int`"; `ParseError` means "this document is not HOCON", so there is no string to quote.
+
+### ConfigError.DuplicateKey
+
+The same key appears in multiple conflicting sources. Carries the path and the ids of every source that defined it. Nothing in the module produces it — `ConfigSource#orElse` resolves conflicts by precedence rather than reporting them — so it exists for custom sources that want to treat ambiguity as an error rather than resolving it silently.
+
+### ConfigError.Unauthorized
+
+Access to a key was denied by the source. Carries the path and source id. Like `DuplicateKey`, no built-in source produces it; it is the error a custom source backed by a secrets manager should return when a lookup is rejected rather than merely absent, so that "you may not read this" is distinguishable from "this does not exist".
+
+### ConfigError.MissingDiscriminatorKey
+
+A sealed trait was decoded but the key naming which case to use was absent. Carries the record's path and the discriminator key that was expected:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+sealed trait Backend
+
+object Backend {
+  case class Postgres(host: String, port: Int) extends Backend
+  case class Sqlite(path: String)              extends Backend
+
+  implicit val schema: Schema[Backend] = Schema.derived[Backend]
+}
+```
+
+The message states both, so the fix is unambiguous:
+
+```scala
+Config.load[Backend](ConfigSource.fromMap(Map("host" -> "localhost"), "conf"))
+// res3: Either[::[ConfigError], Backend] = Left(
+//   List(MissingDiscriminatorKey(path = "", key = "type"))
+// )
+```
+
+### ConfigError.UnknownDiscriminator
+
+The discriminator key was present but named a case that does not exist. Carries the full key path, the value found, and every accepted value in sorted order:
+
+```scala
+Config.load[Backend](ConfigSource.fromMap(Map("type" -> "MySql"), "conf"))
+// res4: Either[::[ConfigError], Backend] = Left(
+//   List(
+//     UnknownDiscriminator(
+//       path = "type",
+//       found = "MySql",
+//       expected = List("Postgres", "Sqlite")
+//     )
+//   )
+// )
+```
+
+Listing the expected values in the message is deliberate: a typo in a discriminator is one of the few config mistakes where the error can name the correct answer.
+
+### ConfigError.Composite
+
+Two or more errors accumulated while decoding one record. Carries them as a `::[ConfigError]`, and renders as the child messages joined with newlines:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+
+val failed = Config.load[Db](ConfigSource.fromMap(Map.empty[String, String], "empty"))
+```
+
+A record with a single failing field returns that error directly, so `Composite` appears only when there is genuinely more than one:
+
+```scala
+failed.left.map(_.head.getClass.getSimpleName)
+// res6: Either[String, Db] = Left("Composite")
+```
+
+Composites nest. Wrapping happens once per record, so a nested config whose inner and outer records both have multiple failures produces a `Composite` containing a `Composite`. Flatten before reporting if you want one list:
+
+```scala
+import zio.blocks.config._
+
+def flatten(error: ConfigError): List[ConfigError] = error match {
+  case ConfigError.Composite(errors) => errors.toList.flatMap(flatten)
+  case other                         => List(other)
+}
+```
+
+## Handling Errors
+
+How you consume a `Left` depends on whether the response varies by kind of failure. Matching on categories keeps the handler stable as new constructors are added; matching on constructors gets you the fields.
+
+### Matching by Category
+
+Categories answer "whose fault is this?", which is usually what determines the response — a missing key is an operator problem, a derivation error is a schema problem:
+
+```scala
+import zio.blocks.config._
+
+def describe(error: ConfigError): String = error match {
+  case _: ConfigSourceError     => "configuration is incomplete or unreadable"
+  case _: ConfigParseError      => "a configured value has the wrong format"
+  case _: ConfigDerivationError => "the config shape does not match the schema"
+  case _                        => "multiple problems"
+}
+```
+
+### Matching by Constructor
+
+Matching the concrete type gives access to the fields, which is what you need to build a targeted message or a machine-readable report:
+
+```scala
+import zio.blocks.config._
+
+def remedy(error: ConfigError): String = error match {
+  case ConfigError.MissingKey(path, source) =>
+    s"set $path in $source"
+  case ConfigError.InvalidValue(path, value, expected, _, _) =>
+    s"$path is '$value' but must be a $expected"
+  case ConfigError.UnknownDiscriminator(path, found, expected) =>
+    s"$path is '$found'; use one of ${expected.mkString(", ")}"
+  case other =>
+    other.message
+}
+```
+
+Because `ConfigError` extends `NoStackTrace`, and therefore `Throwable`, an individual error can also be thrown or wrapped directly when integrating with code that expects exceptions.
+
+## ConfigLoadException
+
+`Config.loadOrThrow` throws `ConfigLoadException` rather than returning a `Left`. The exception carries both a formatted report for humans and the original error list for programs:
+
+```scala
+final class ConfigLoadException(val report: String, val errors: ::[ConfigError])
+  extends RuntimeException(report)
+```
+
+`report` is a multi-line summary: a count line followed by one indented bullet per top-level error. Catching the exception and reading `errors` recovers the structured form, so throwing does not lose information:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+
+try Config.loadOrThrow[Db](ConfigSource.fromMap(Map.empty[String, String], "empty"))
+catch {
+  case e: ConfigLoadException =>
+    println(e.report)
+    e.errors.toList.foreach(err => println(err.message))
+}
+```
+
+Use `Config.loadOrThrow` at the top of `main`, where an unrecoverable config problem should stop startup with a readable message. Prefer `Config.load` anywhere the failure is recoverable — a reload, a per-request decode, or a validation pass that reports rather than aborts.
+
+:::warning[`Config.wire` throws]
+`Config.wire` decodes with `Config.loadOrThrow`, so a bad config surfaces as a `ConfigLoadException` while the dependency graph is being allocated rather than as a typed failure. Validate with `Config.load` first if you need to report config problems before touching the graph.
+:::
+
+## Flag Exceptions
+
+Flag resolution has a separate hierarchy, `FlagException`, because flags fail at class-load time and cannot return an `Either` from an object initializer. `ConfigError` still appears inside those exceptions as the underlying cause — a flag whose value will not parse carries the same `ConfigError.InvalidValue` a config field would. See [Flags](./flags.md).
+
+## Integration Points
+
+`ConfigError` is produced by `ConfigDecoder`, by every `ConfigSource` constructor that can fail, and by `Rollout` when an expression will not parse. It is consumed by `Config`, which either returns it or formats it into a `ConfigLoadException`, and by `Flag.ReloadResult.Failed`, which carries it out of a failed dynamic-flag reload.
+
+See [Config Decoder](./config-decoder.md) for which rule produces which error, and [Rollout](./rollout.md) for expression-level failures.

package/reference/config/flags.md

@@ -0,0 +1,369 @@
+---
+id: flags
+title: "Flags"
+sidebar_label: "Flags"
+---
+
+A flag is a named scalar whose value comes from outside the program. `StaticFlag[A]` resolves once at class-load time and never changes; `DynamicFlag[A]` holds a rollout expression that can be updated while the process runs. Both read through `FlagSource`, parse through `Flag.Reader`, and register themselves in a global registry that `Flag.dump` can print. Supporting types: `Flag.Source`, `FlagException`. The three declarations you write against:
+
+```scala
+trait FlagSource {
+  def sourceId: String
+  def get(name: String): Maybe[SourceValue[String]]
+  final def orElse(fallback: FlagSource): FlagSource
+}
+
+abstract class StaticFlag[A](default: A)(implicit reader: Flag.Reader[A], displayable: Displayable[A])
+
+abstract class DynamicFlag[A](default: A, defaultExpression: String)(implicit reader: Flag.Reader[A])
+```
+
+## Motivation
+
+Configuration and flags answer different questions. Configuration describes a deployment: which database, which port, which region. Flags describe a decision: is this feature on, for whom, and at what percentage. The two have different shapes — configuration is a typed record loaded once, a flag is a single value read at the point of use — and different failure modes.
+
+Flags in this module are Scala objects. That choice buys three things. The name is derived from the object's fully-qualified name, so it cannot drift from the code that reads it. The value is a `val`, so reading it is a field access with no lookup cost. And references are compile-checked: a deleted flag is a compile error at every use site, not a silently-missing key.
+
+The cost is that resolution happens during class initialization, which makes ordering matter. A `StaticFlag` touched before its `FlagSource` is registered resolves from the environment or its default and stays that way.
+
+## FlagSource
+
+`FlagSource` is the scalar half of `ConfigSource`: a name-to-string lookup with provenance, without prefix enumeration. Because `ConfigSource extends FlagSource`, any config source is also a flag source.
+
+### Creating a Source
+
+`FlagSource.fromMap` builds an in-memory source, which is what tests and local overrides use:
+
+```scala
+import zio.blocks.config._
+
+val source = FlagSource.fromMap(Map("myapp.poolSize" -> "32"), "local")
+```
+
+Lookups return the value with a `Provenance.Resolved` naming the source and the name it answered under:
+
+```scala
+source.get("myapp.poolSize")
+// res0: Maybe[SourceValue[String]] = SourceValue(
+//   value = "32",
+//   provenance = Resolved(
+//     sourceId = "local",
+//     key = "myapp.poolSize",
+//     rawValue = "32"
+//   )
+// )
+```
+
+`FlagSource#orElse` layers sources with the receiver taking priority, exactly as on `ConfigSource`.
+
+### The Registry
+
+Flags do not take a source as a constructor argument. They consult `FlagSource.Registry`, a thread-safe global that flags read during initialization:
+
+| Method                          | Effect                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------- |
+| `Registry.register(source)`     | Adds a source, keyed by `sourceId`; re-registering an id replaces it in place. |
+| `Registry.unregister(sourceId)` | Removes a source by id.                                                 |
+| `Registry.get(sourceId)`        | Looks up a registered source.                                           |
+| `Registry.all`                  | Every source in registration order.                                     |
+| `Registry.resolve(name)`        | First source that answers the name wins.                                |
+| `Registry.clear()`              | Removes everything; intended for tests.                                 |
+
+Registration order is resolution order, so the first source registered has the highest priority:
+
+```scala
+import zio.blocks.config._
+
+FlagSource.Registry.register(FlagSource.fromMap(Map("myapp.poolSize" -> "64"), "remote"))
+FlagSource.Registry.register(FlagSource.fromMap(Map("myapp.poolSize" -> "32"), "fallback"))
+
+FlagSource.Registry.resolve("myapp.poolSize")
+```
+
+Re-registering an existing `sourceId` swaps the source without changing its position, so refreshing a source's contents does not reshuffle priorities.
+
+:::warning[Register before first touch]
+A `StaticFlag` resolves during its object's initialization, which happens the first time anything references it. Sources registered after that point are never consulted for that flag. Register every source at the very top of `main`, before touching any flag.
+:::
+
+## StaticFlag
+
+`StaticFlag[A]` is for values that are fixed for the lifetime of the process: pool sizes, buffer limits, endpoints that cannot change without a restart.
+
+### Defining a Flag
+
+Extend `StaticFlag[A]` from a Scala `object`, passing the default:
+
+```scala
+import zio.blocks.config._
+
+object poolSize extends StaticFlag[Int](10)
+
+val size: Int = poolSize()
+```
+
+The flag's `name` is the object's fully-qualified name with `$` separators rewritten to dots, so an object `Limits.poolSize` in package `com.example` is named `com.example.Limits.poolSize`. Nothing declares that name — it follows from where the object lives, which means moving the object renames the flag.
+
+### Resolution Order
+
+Resolution runs once, in a fixed order, and stops at the first source that produces a value:
+
+```
+1. FlagSource.Registry.resolve(name)     ← registration order across all sources
+2. System property with the flag's name  ← -Dcom.example.Limits.poolSize=32
+3. Environment variable                  ← COM_EXAMPLE_LIMITS_POOLSIZE=32
+4. The constructor default
+```
+
+The environment variable name is the flag name with dots replaced by underscores, uppercased. That translation is fixed and not configurable.
+
+### Members
+
+Each resolved flag exposes what it resolved to and where from:
+
+| Member         | Type          | Meaning                                                   |
+| -------------- | ------------- | --------------------------------------------------------- |
+| `name`         | `String`      | Derived fully-qualified flag name.                         |
+| `value`        | `A`           | The resolved value.                                        |
+| `apply()`      | `A`           | Same as `value`; reads as a call at use sites.              |
+| `source`       | `Flag.Source` | Which of the four resolution steps answered.                |
+| `provenance`   | `Provenance`  | Source id, key, and raw string.                             |
+| `displayValue` | `String`      | Rendered through `Displayable[A]`, used by `Flag.dump`.      |
+
+### Failure at Initialization
+
+An object initializer cannot return an `Either`, so a flag that cannot resolve throws. A value that fails to parse throws `ExceptionInInitializerError` wrapping `FlagException.FlagValueParseException`, and a flag whose defining class is not a Scala object throws `FlagException.FlagNameException`.
+
+Failing at class load is the point: a malformed flag stops the process at startup rather than producing a plausible-looking wrong value that surfaces later.
+
+:::note[Secrets in flags]
+`Flag.Reader[Secret]` accepts any string, and the module provides `Displayable[Secret]` in the `zio.blocks.config` package object, so a `StaticFlag[Secret]` renders as `<secret>` in dumps without extra configuration. See [ConfigSource](./config-source.md) for `Secret` itself.
+:::
+
+## DynamicFlag
+
+`DynamicFlag[A]` is for decisions that change without a restart: enabling a feature for a subset of users, shifting traffic to a new code path, turning off an expensive query under load.
+
+### Defining a Flag
+
+Extend `DynamicFlag[A]` with both a default value and a default rollout expression:
+
+```scala
+import zio.blocks.config._
+
+object newCheckout extends DynamicFlag[Boolean](false, "true@*/50%; false")
+
+val enabled: Boolean = newCheckout("user-1234")
+```
+
+The initial expression resolves through the same chain as a static flag's value — registry, then system property, then environment variable, then the constructor default — but what it resolves is the *expression*, not the value. A malformed expression throws `ExceptionInInitializerError` wrapping `FlagException.FlagExpressionParseException`.
+
+### Evaluation
+
+`DynamicFlag#apply` takes a bucketing key and any number of path attributes, evaluates the expression, and tracks a counter for the key. `DynamicFlag#evaluate` does the same without touching counters:
+
+```scala
+import zio.blocks.config._
+
+object newCheckout extends DynamicFlag[Boolean](false, "true@*/prod/*/50%; false")
+
+newCheckout("user-1234", "prod", "eu")           // counted
+newCheckout.evaluate("user-1234", "prod", "eu") // not counted
+```
+
+The key determines the percentage bucket, and it is also the *first* segment of the path a selector matches against: the attributes are appended to it with slashes, so the call above matches against `user-1234/prod/eu`. A selector must have exactly as many segments as that path, which is why the expression starts with a wildcard. Evaluation details are in [Rollout](./rollout.md).
+
+When a matched value cannot be parsed into `A`, evaluation falls back to the flag's default and increments `DynamicFlag#parseErrorCount`. A non-zero count means the expression contains values the reader rejects — a misconfiguration that would otherwise be invisible, since every call still returns something usable.
+
+### Updating and Reloading
+
+`DynamicFlag#update` replaces the expression from code, returning `Left` if the new expression will not parse and leaving the old one in place:
+
+```scala
+import zio.blocks.config._
+
+object newCheckout extends DynamicFlag[Boolean](false, "false")
+
+newCheckout.update("true@prod/25%; false")
+newCheckout.expression
+```
+
+An empty or whitespace-only expression is accepted as a no-op and returns `Right(())` without changing anything.
+
+`DynamicFlag#reload` re-reads the expression from `FlagSource.Registry` and reports what happened as a `Flag.ReloadResult`. See [Rollout](./rollout.md) for the result variants and the update history.
+
+## Flag.Reader
+
+`Flag.Reader[A]` parses a raw string into `A` and supplies a type name for error messages. Instances are resolved implicitly by both flag types:
+
+```scala
+trait Reader[A] {
+  def parse(flagName: String, raw: String): Either[ConfigError, A]
+  def typeName: String
+}
+```
+
+### Built-in Instances
+
+| Type                | Accepted form                                              | Example  |
+| ------------------- | ---------------------------------------------------------- | -------- |
+| `Int`, `Long`       | Decimal integer literal                                     | `32`     |
+| `Double`            | Decimal or scientific literal                               | `0.5`    |
+| `Boolean`           | `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off` (any case)   | `on`     |
+| `String`            | Any string, taken as-is                                      | `eu-west` |
+| `Secret`            | Any string, wrapped so it cannot be printed                  | `hunter2` |
+| `FiniteDuration`    | Digits followed by a unit suffix                              | `30s`    |
+| `Seq[A]`            | Comma-separated values of a scalar `A`, each trimmed          | `a, b, c` |
+
+Boolean parsing accepts the same set of spellings as config decoding:
+
+```scala
+Flag.Reader.booleanReader.parse("example", "ON")
+// res6: Either[ConfigError, Boolean] = Right(true)
+Flag.Reader.booleanReader.parse("example", "maybe")
+// res7: Either[ConfigError, Boolean] = Left(
+//   InvalidValue(
+//     path = "example",
+//     value = "maybe",
+//     expectedType = "Boolean (true/false/1/0/yes/no/on/off)",
+//     source = "flag",
+//     cause = None
+//   )
+// )
+```
+
+Duration suffixes are `ms`/`millis`/`milliseconds`, `s`/`sec`/`secs`/`seconds`, `m`/`min`/`mins`/`minutes`, `h`/`hour`/`hours`, and `d`/`day`/`days`:
+
+```scala
+Flag.Reader.durationReader.parse("example", "500ms")
+// res8: Either[ConfigError, FiniteDuration] = Right(500 milliseconds)
+Flag.Reader.durationReader.parse("example", "2hours")
+// res9: Either[ConfigError, FiniteDuration] = Right(2 hours)
+```
+
+The grammar is digits immediately followed by letters, so a space between the number and the unit is rejected:
+
+```scala
+Flag.Reader.durationReader.parse("example", "2 hours")
+// res10: Either[ConfigError, FiniteDuration] = Left(
+//   InvalidValue(
+//     path = "example",
+//     value = "2 hours",
+//     expectedType = "Duration (e.g., 10s, 5m, 1h, 100ms, 2d)",
+//     source = "flag",
+//     cause = None
+//   )
+// )
+```
+
+:::warning[Flag durations are not config durations]
+`Flag.Reader[FiniteDuration]` parses `30s`. Config decoding parses `java.time.Duration` with `Duration.parse`, which requires ISO-8601 (`PT30S`). Neither accepts the other's format — see [Config Decoder](./config-decoder.md).
+:::
+
+### Scalar and Sequence Readers
+
+`Flag.Reader.Scalar[A]` marks a reader whose values contain no commas. `Flag.Reader.seqReader` requires that marker, because it splits on commas — a non-scalar element type would make the split ambiguous:
+
+```scala
+Flag.Reader.seqReader[Int].parse("example", "1, 2, 3")
+// res11: Either[ConfigError, Seq[Int]] = Right(ArraySeq(1, 2, 3))
+```
+
+An empty string parses to an empty sequence rather than failing. If any element fails, its error stands for the whole list.
+
+### Custom Readers
+
+`Flag.Reader.apply` builds a reader from a parse function and a type name, and `Flag.Reader.scalar` does the same for comma-free types so that `Seq` of them works:
+
+```scala
+import zio.blocks.config._
+
+final case class Region(code: String)
+
+implicit val regionReader: Flag.Reader.Scalar[Region] =
+  Flag.Reader.scalar(
+    (flagName, raw) =>
+      if (raw.matches("[a-z]{2}-[a-z]+-\\d")) Right(Region(raw))
+      else Left(ConfigError.InvalidValue(flagName, raw, "Region (e.g. eu-west-1)", "flag")),
+    "Region"
+  )
+```
+
+Return `ConfigError.InvalidValue` from a failing parse so the resulting message matches every other config failure.
+
+## Flag.Source
+
+`Flag.Source` records which resolution step answers a static flag:
+
+| Variant                            | Meaning                                        |
+| ---------------------------------- | ---------------------------------------------- |
+| `Flag.Source.FlagSourceValue(id)`  | A registered `FlagSource` answered; `id` names it. |
+| `Flag.Source.SystemProperty`       | A JVM system property answered.                 |
+| `Flag.Source.EnvironmentVariable`  | An environment variable answered.               |
+| `Flag.Source.Default`              | Nothing answered; the constructor default applies. |
+
+Checking for `Flag.Source.Default` at startup is how you detect a flag you meant to configure and did not.
+
+## Diagnostics
+
+Two helpers on `Flag` exist for the two questions that come up when a flag has the wrong value: what did everything resolve to, and did I misspell something?
+
+### Flag.dump
+
+`Flag.dump()` renders every registered flag — static and dynamic — as a table of name, type, value, and source. Static flags show their `displayValue` and provenance source id; dynamic flags show their current expression:
+
+```scala
+import zio.blocks.config._
+
+println(Flag.dump())
+```
+
+The registry is populated by construction, so a flag appears only after something has touched it. Print the dump after startup has forced every flag, not before.
+
+### Flag.nearMissWarnings
+
+`Flag.nearMissWarnings` looks for names that resemble a flag but do not match it, which catches the common failures: a case mismatch in a system property, a case mismatch in an environment variable, or a registered source holding a nearly-right key:
+
+```scala
+import zio.blocks.config._
+
+Flag.nearMissWarnings("com.example.Limits.poolSize").foreach(println)
+```
+
+Candidates checked include the name lowercased and uppercased, dots swapped for underscores, and underscores swapped for dots. A warning means a source contains something similar — it does not mean the flag is wrong, only that a typo is plausible.
+
+## FlagException
+
+Flag failures are exceptions rather than values because they occur inside object initializers. `FlagException` extends `NoStackTrace`, so constructing one is cheap:
+
+| Exception                                | Thrown when                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `FlagValueParseException`                | A static flag's raw value fails its `Flag.Reader`.                           |
+| `FlagExpressionParseException`            | A dynamic flag's initial rollout expression will not parse.                  |
+| `FlagNameException`                       | The defining class is not a Scala object, or is a lambda or anonymous class.  |
+| `FlagDuplicateNameException`              | A second flag registers under an existing name.                              |
+
+`FlagValueParseException` and `FlagExpressionParseException` are wrapped in `ExceptionInInitializerError` by the JVM when thrown from an initializer, so catch that and inspect its cause:
+
+```scala
+import zio.blocks.config._
+
+try {
+  // Touching a flag object forces its initialization.
+  Class.forName("com.example.Limits$poolSize$")
+} catch {
+  case e: ExceptionInInitializerError =>
+    e.getCause match {
+      case f: FlagException => println(f.getMessage)
+      case other           => throw other
+    }
+}
+```
+
+`FlagDuplicateNameException` means two objects derived the same name, which happens when two flags share a fully-qualified name after `$`-to-dot rewriting. Renaming either object resolves it.
+
+## Integration Points
+
+Flags depend on `FlagSource` — and therefore accept any `ConfigSource` — on `Flag.Reader` for parsing, on `Displayable` for rendering, and on `ConfigError` for parse failures. `DynamicFlag` additionally depends on `Rollout` for expression evaluation.
+
+See [Rollout](./rollout.md) for the expression language and reload lifecycle, [ConfigSource](./config-source.md) for sources and `Secret`, and [Errors](./errors.md) for the shared error model.