@kexhq/kex 0.4.0-beta → 0.4.0-beta.3

package/dist/kex_repl_wasm.data

@@ -1,14 +1,8 @@
-# Algebraic structures, ordering, and combining values associatively.
+# Algebraic structures: combining values associatively.
 #
 # Kex traits do not inherit from one another, so concrete types explicitly
 # implement every structure whose laws they satisfy.
 #
-# The two most important things that you will meet in everyday code. +Ordering+ is what
-# a comparison answers, and it composes. This is how a multi-key sort is
-# written without nested +if+s:
-#
-#   a.age.compare(b.age).thenBy { a.score.compare(b.score) }
-#
 # +Monoid+ is "these two values combine, and there is a neutral one". Numbers,
 # strings and lists all satisfy it, which is what lets +repeat+ be written
 # once:
@@ -16,70 +10,15 @@
 #   "ab".repeat(3)   # => "ababab"
 #   [1].repeat(2)    # => [1, 1]
 #   5.repeat(3)      # => 15
-
-# The result of a comparison: +Less+, +Equal+ or +Greater+.
-#
-# Declared here rather than only inside the interpreter so that `Ordering`,
-# `Less`, `Equal` and `Greater` reach the semantic layer the same way every
-# other stdlib type does (through the collected interfaces) instead of
-# existing solely as native environment bindings the type checker and name
-# resolver cannot see.
-type Ordering = Less | Equal | Greater
-
-# Types that have a total order.
 #
-# Implemented by +Number+, which covers both +Integer+ and +Float+.
-trait Comparable do
-  # Compares this value with +other+ and answers +Less+, +Equal+ or
-  # +Greater+.
-  #
-  # +==+ stays independent of this: a type may be equatable without being
-  # ordered.
-  #
-  # @param other [This] the value to compare against
-  # @return [Ordering] how this value orders against +other+
-  #
-  # @example
-  #   1.compare(2)     # => Less
-  #   2.compare(2)     # => Equal
-  #   3.compare(2)     # => Greater
-  #
-  # @example Sorting with an explicit comparison
-  #   people.sort { |a, b| a.age.compare(b.age) == Less }
-  # A total order: `compare` answers Less, Equal or Greater. `==` stays
-  # independent: a type may be Equatable without being ordered.
-  compare :> This -> Ordering
-end
-
-# Number carries the implementation, so Integer and Float both inherit it
-# rather than repeating the same three comparisons. Mixed receivers work
-# because `<` and `>` promote across the two (`1.compare(1.0)` is Equal).
-make Number, implement: Comparable do
-  # Compares two numbers, across the +Integer+/+Float+ boundary.
-  #
-  # Mixed receivers work because +<+ and +>+ promote across the two, so
-  # +1.compare(1.0)+ is +Equal+.
-  #
-  # @param other [Number] the number to compare against
-  # @return [Ordering] how this number orders against +other+
-  #
-  # @example
-  #   1.compare(2)      # => Less
-  #   1.compare(1.0)    # => Equal
-  #   2.5.compare(2)    # => Greater
-  let compare(other: Number) -> Ordering do
-    return Less if this < other
-    return Greater if this > other
-
-    return Equal
-  end
-end
+# Ordering and comparison (+Ordering+, +Comparable+) live in
+# `comparable.kex`.
 
 # Types whose values combine associatively and have a neutral element.
 #
 # Implemented by +Integer+ (addition), +String+ and +List+ (concatenation),
 # +Map+ and both +Set+ flavours (union), and +Ordering+ ("first decision
-# wins").
+# wins" — declared beside +Ordering+ in `comparable.kex`).
 trait Monoid do
   # The neutral element: combining it with any value gives that value back.
   #
@@ -145,7 +84,6 @@ trait Group do
 
   # Combines this value with +other+.
   #
-  # @param other [This] the value to combine with
   # @return [This] the combined value
   combine :> This -> This
 
@@ -233,82 +171,6 @@ make [A], implement: Monoid do
   #   groups.reduce([]) { |acc, g| acc.combine(g) }
   let combine(other: This) -> This = this + other
 end
-
-# `Ordering` is a Monoid under "first decision wins", with Equal as identity.
-# That is what makes multi-key comparison compose instead of nesting ifs:
-#
-#   a.name.compare(b.name).combine(a.age.compare(b.age))
-#
-# `combine` evaluates its argument eagerly, so the later comparison runs even
-# when the earlier one already decided. Use `thenBy` when that matters.
-make Ordering, implement: Monoid do
-  # +Equal+ is the neutral element, since an undecided comparison lets the next
-  # one decide.
-  #
-  # @return [Ordering] +Equal+
-  let identity = Equal
-
-  # Returns the first decisive ordering: this one if it is not +Equal+,
-  # otherwise +other+.
-  #
-  # This is what makes multi-key comparison compose. Note that +other+ is
-  # evaluated eagerly, so the later comparison runs even when the earlier one
-  # has already decided: use +thenBy+ when that matters.
-  #
-  # @param other [Ordering] the tie-breaking ordering
-  # @return [Ordering] the first decisive ordering
-  #
-  # @example
-  #   Equal.combine(Less)     # => Less
-  #   Less.combine(Greater)   # => Less
-  #
-  # @example Sorting by surname, then by first name
-  #   a.last.compare(b.last).combine(a.first.compare(b.first))
-  let combine(@Equal, other: Ordering) -> Ordering = other
-  let combine(@Less, _) -> Ordering = Less
-  let combine(@Greater, _) -> Ordering = Greater
-
-  # Returns the opposite ordering: +Less+ becomes +Greater+, +Greater+ becomes
-  # +Less+, and +Equal+ stays +Equal+.
-  #
-  # The one-word way to turn an ascending comparison into a descending one.
-  #
-  # @return [Ordering] the reversed ordering
-  #
-  # @example
-  #   Less.reverse      # => Greater
-  #   Greater.reverse   # => Less
-  #   Equal.reverse     # => Equal
-  #
-  # @example Sorting newest first
-  #   a.created.compare(b.created).reverse
-  reverse :> Ordering
-  let reverse(@Less) -> Ordering = Greater
-  let reverse(@Greater) -> Ordering = Less
-  let reverse(@Equal) -> Ordering = Equal
-
-  # Returns this ordering if it is decisive, otherwise the result of calling
-  # +tieBreaker+.
-  #
-  # The short-circuiting form of +combine+: the block runs only when this
-  # comparison is +Equal+, so a tie-breaker costs nothing once the order is
-  # already decided. Prefer it whenever the tie-breaker is more than a field
-  # read.
-  #
-  # @param tieBreaker [Block<Ordering>] evaluated only on a tie
-  # @return [Ordering] the first decisive ordering
-  #
-  # @example
-  #   Equal.thenBy { 2.compare(1) }   # => Greater
-  #   Less.thenBy { 2.compare(1) }    # => Less
-  #
-  # @example Sorting by age, then by an expensive score
-  #   a.age.compare(b.age).thenBy { score(a).compare(score(b)) }
-  thenBy :> Block<Ordering> -> Ordering
-  let thenBy(@Equal, tieBreaker) -> Ordering = tieBreaker()
-  let thenBy(@Less, _) -> Ordering = Less
-  let thenBy(@Greater, _) -> Ordering = Greater
-end
 # An opaque, immutable sequence of bytes. A +Binary+ never implicitly becomes
 # text.
 #
@@ -829,19 +691,191 @@ end
 make [X], implement: Blankable do
   # Returns +true+ when the list has no elements.
   #
-  # @return [Bool] +true+ for the empty list
+  # @return [Bool] +true+ for the empty list
+  #
+  # @example
+  #   [].blank?         # => true
+  #   [1, 2].blank?     # => false
+  #
+  # @example Reporting an empty result set
+  #   if matches.blank?
+  #     IO.printLine("no matches")
+  #   end
+  blank? :> Bool
+  let blank?(@[]) = true
+  let blank?(@[_|_]) = false
+end
+# Ordering and comparison: what a comparison answers, and the types that
+# have a total order.
+#
+# Kex traits do not inherit from one another, so concrete types explicitly
+# implement every structure whose laws they satisfy.
+#
+# The two things you meet in everyday code here. +Ordering+ is what a
+# comparison answers, and it composes. This is how a multi-key sort is
+# written without nested +if+s:
+#
+#   a.age.compare(b.age).thenBy { a.score.compare(b.score) }
+#
+# +Ordering+ is also a +Monoid+ under "first decision wins", which is what
+# makes comparisons chain with +combine+; that conformance is declared here,
+# beside the type it belongs to, rather than in `algebra.kex` with the
+# +Monoid+ trait.
+
+# The result of a comparison: +Less+, +Equal+ or +Greater+.
+#
+# Declared here rather than only inside the interpreter so that `Ordering`,
+# `Less`, `Equal` and `Greater` reach the semantic layer the same way every
+# other stdlib type does (through the collected interfaces) instead of
+# existing solely as native environment bindings the type checker and name
+# resolver cannot see.
+type Ordering = Less | Equal | Greater
+
+# Types that have a total order.
+#
+# Implemented by +Number+, which covers both +Integer+ and +Float+, and by
+# +String+.
+trait Comparable do
+  # Compares this value with +other+ and answers +Less+, +Equal+ or
+  # +Greater+.
+  #
+  # +==+ stays independent of this: a type may be equatable without being
+  # ordered.
+  #
+  # @param other [This] the value to compare against
+  # @return [Ordering] how this value orders against +other+
+  #
+  # @example
+  #   1.compare(2)     # => Less
+  #   2.compare(2)     # => Equal
+  #   3.compare(2)     # => Greater
+  #
+  # @example Sorting with an explicit comparison
+  #   people.sort { |a, b| a.age.compare(b.age) == Less }
+  # A total order: `compare` answers Less, Equal or Greater. `==` stays
+  # independent: a type may be Equatable without being ordered.
+  compare :> This -> Ordering
+end
+
+# Number carries the implementation, so Integer and Float both inherit it
+# rather than repeating the same three comparisons. Mixed receivers work
+# because `<` and `>` promote across the two (`1.compare(1.0)` is Equal).
+make Number, implement: Comparable do
+  # Compares two numbers, across the +Integer+/+Float+ boundary.
+  #
+  # Mixed receivers work because +<+ and +>+ promote across the two, so
+  # +1.compare(1.0)+ is +Equal+.
+  #
+  # @param other [Number] the number to compare against
+  # @return [Ordering] how this number orders against +other+
+  #
+  # @example
+  #   1.compare(2)      # => Less
+  #   1.compare(1.0)    # => Equal
+  #   2.5.compare(2)    # => Greater
+  let compare(other: Number) -> Ordering do
+    return Less if this < other
+    return Greater if this > other
+
+    return Equal
+  end
+end
+
+# Strings order lexicographically, character by character, by code point —
+# the same order `<` and `>` already give them.
+make String, implement: Comparable do
+  # Compares this string with +other+ lexicographically, the same order
+  # +<+ and +>+ give strings.
+  #
+  # @param other [String] the string to compare against
+  # @return [Ordering] how this string orders against +other+
+  #
+  # @example
+  #   "apple".compare("banana")   # => Less
+  #   "kex".compare("kex")        # => Equal
+  #   "cherry".compare("apple")   # => Greater
+  let compare(other: String) -> Ordering do
+    return Less if this < other
+    return Greater if this > other
+
+    return Equal
+  end
+end
+
+# `Ordering` is a Monoid under "first decision wins", with Equal as identity.
+# That is what makes multi-key comparison compose instead of nesting ifs:
+#
+#   a.name.compare(b.name).combine(a.age.compare(b.age))
+#
+# `combine` evaluates its argument eagerly, so the later comparison runs even
+# when the earlier one already decided. Use `thenBy` when that matters.
+make Ordering, implement: Monoid do
+  # +Equal+ is the neutral element, since an undecided comparison lets the next
+  # one decide.
+  #
+  # @return [Ordering] +Equal+
+  let identity = Equal
+
+  # Returns the first decisive ordering: this one if it is not +Equal+,
+  # otherwise +other+.
+  #
+  # This is what makes multi-key comparison compose. Note that +other+ is
+  # evaluated eagerly, so the later comparison runs even when the earlier one
+  # has already decided: use +thenBy+ when that matters.
+  #
+  # @param other [Ordering] the tie-breaking ordering
+  # @return [Ordering] the first decisive ordering
+  #
+  # @example
+  #   Equal.combine(Less)     # => Less
+  #   Less.combine(Greater)   # => Less
+  #
+  # @example Sorting by surname, then by first name
+  #   a.last.compare(b.last).combine(a.first.compare(b.first))
+  let combine(@Equal, other: Ordering) -> Ordering = other
+  let combine(@Less, _) -> Ordering = Less
+  let combine(@Greater, _) -> Ordering = Greater
+
+  # Returns the opposite ordering: +Less+ becomes +Greater+, +Greater+ becomes
+  # +Less+, and +Equal+ stays +Equal+.
+  #
+  # The one-word way to turn an ascending comparison into a descending one.
+  #
+  # @return [Ordering] the reversed ordering
+  #
+  # @example
+  #   Less.reverse      # => Greater
+  #   Greater.reverse   # => Less
+  #   Equal.reverse     # => Equal
+  #
+  # @example Sorting newest first
+  #   a.created.compare(b.created).reverse
+  reverse :> Ordering
+  let reverse(@Less) -> Ordering = Greater
+  let reverse(@Greater) -> Ordering = Less
+  let reverse(@Equal) -> Ordering = Equal
+
+  # Returns this ordering if it is decisive, otherwise the result of calling
+  # +tieBreaker+.
+  #
+  # The short-circuiting form of +combine+: the block runs only when this
+  # comparison is +Equal+, so a tie-breaker costs nothing once the order is
+  # already decided. Prefer it whenever the tie-breaker is more than a field
+  # read.
+  #
+  # @param tieBreaker [Block<Ordering>] evaluated only on a tie
+  # @return [Ordering] the first decisive ordering
   #
   # @example
-  #   [].blank?         # => true
-  #   [1, 2].blank?     # => false
+  #   Equal.thenBy { 2.compare(1) }   # => Greater
+  #   Less.thenBy { 2.compare(1) }    # => Less
   #
-  # @example Reporting an empty result set
-  #   if matches.blank?
-  #     IO.printLine("no matches")
-  #   end
-  blank? :> Bool
-  let blank?(@[]) = true
-  let blank?(@[_|_]) = false
+  # @example Sorting by age, then by an expensive score
+  #   a.age.compare(b.age).thenBy { score(a).compare(score(b)) }
+  thenBy :> Block<Ordering> -> Ordering
+  let thenBy(@Equal, tieBreaker) -> Ordering = tieBreaker()
+  let thenBy(@Less, _) -> Ordering = Less
+  let thenBy(@Greater, _) -> Ordering = Greater
 end
 # ANSI terminal styling: colors, text attributes, and cursor control.
 #
@@ -1074,232 +1108,346 @@ module Console do
   enabled? : Bool
   let enabled? = Kex.Intrinsic.Console.enabled?
 end
-# Bounded retries for operations whose failures can be classified by the
-# application.
+# Runs bounded retries with a reusable schedule.
 #
-# A retry is never automatically safe just because an error was temporary.
-# The caller owns the operation and, where necessary, a predicate that excludes
-# permanent failures and non-idempotent work. Policies bound attempts, delay,
-# and optionally total sleep so a dependency cannot stall the program forever.
+# +Retry.run+ executes the block immediately. An +Ok+ stops the run; an
+# +Error+ schedules another attempt. When attempts or total sleep run out,
+# the last error is returned unchanged. Runtime faults are not caught.
 #
+# @example Retry a request and handle the final result
 #   using Control.Retry
+#   using Net.HTTP
 #
-#   let policy = Retry.exponential(4, 100.milliseconds, 2.seconds)
-#     .withJitter(0.2)
-#   Retry.run(policy, ~retryable?) do
-#     client.get("https://api.example.com/inventory")
+#   let result = Retry.run(attempts: 5) do
+#     HTTP.get("https://api.example.com/inventory")
+#   end
+#   match result do
+#     Ok(response) => IO.printLine(response.status.code)
+#     Error(error) => IO.printLine(error.message)
 #   end
+#
+# HTTP responses, including 429 and 503, are +Ok(response)+. Automatic
+# retries handle request failures, not response statuses. Use +again+ and
+# +done+ to classify responses or stop on permanent errors. Repeat writes
+# only when the application makes them safe, for example with idempotency
+# keys. A schedule bounds retry sleep, not the operation's execution time;
+# configure request timeouts separately.
 module Control.Retry
 
-# A bounded retry schedule. Attempts includes the initial call.
-# Delays are immutable +Duration+ values and never exceed +maximumDelay+.
-record Policy do
-  maximumAttempts : Integer
-  initialDelay : Duration
-  multiplier : Float
-  maximumDelay : Duration
-  maximumElapsed : Duration? = None
-  jitterFraction : Float = 0.0
-end
-
-# Decides whether an application error is eligible for another attempt.
-type Predicate<E> = E -> Bool
-
-# Performs one scheduled delay. Supplying this callback makes retry tests
-# deterministic without sleeping.
-type Sleeper = Duration -> Void
-
-# Builds a constant-delay retry policy.
-#
-# Fixed delays are predictable and useful for a local resource expected to
-# become ready shortly. For many clients sharing a remote dependency, prefer
-# exponential backoff with jitter to avoid synchronized retry bursts.
-#
-# @param maximumAttempts [Integer] total calls including the first
-# @param delay [Duration] delay before each subsequent call
-# @return [Policy] the retry schedule
-#
-# @example Waiting briefly for a local test server to start
-#   let policy = Retry.fixed(5, 50.milliseconds)
-fixed : Integer -> Duration -> Policy
-let fixed(maximumAttempts, delay) = Policy {
-  maximumAttempts: maximumAttempts,
-  initialDelay: delay,
-  multiplier: 1.0,
-  maximumDelay: delay,
-  maximumElapsed: None,
-  jitterFraction: 0.0
-}
+# Provides automatic error retries and explicit retry decisions.
+module Retry do
+  # Describes the timing and limits of one execution of +run+.
+  #
+  # All fields are optional. Defaults allow three attempts with exponential
+  # backoff from 100 milliseconds, capped at 5 seconds, with 20% jitter.
+  # Creating a schedule performs no work. It is immutable configuration:
+  # each run starts a fresh attempt count and delay sequence.
+  #
+  # * +attempts+: maximum executions, including the first; default 3.
+  # * +delay+: initial base wait; default 100 milliseconds.
+  # * +backoff+: base-delay multiplier; default 2.0, or 1.0 for fixed waits.
+  # * +maximumDelay+: cap on each actual wait, including jitter; default 5 seconds.
+  # * +jitter+: symmetric proportional variation; default 0.2, or 0.0 to disable.
+  # * +maximumTotalDelay+: cumulative sleep allowance; default +None+.
+  #   Operation execution time is excluded. A wait that exceeds the remaining
+  #   allowance ends the run without sleeping or calling the operation again.
+  #
+  # @example Fixed delays: three waits of 250 milliseconds
+  #   let schedule = Retry.Schedule {
+  #     attempts: 4, delay: 250.milliseconds, backoff: 1.0,
+  #     maximumDelay: 250.milliseconds, jitter: 0.0
+  #   }
+  #   Retry.run(schedule: schedule) do
+  #     Error("not ready")
+  #   end
+  #   # => Error("not ready"), after four calls and 750 ms of sleep
+  #
+  # @example Exponential delays: 200, 400, 800, 1600 milliseconds
+  #   let schedule = Retry.Schedule {
+  #     attempts: 5, delay: 200.milliseconds, backoff: 2.0,
+  #     maximumDelay: 5.seconds, jitter: 0.0
+  #   }
+  #   Retry.run(schedule: schedule) do
+  #     Ok("ready")
+  #   end
+  #   # => Ok("ready"), immediately, without sleeping
+  #
+  # @example Capped delays: 500 ms, 1 s, 2 s, 2 s, 2 s
+  #   Retry.Schedule {
+  #     attempts: 6, delay: 500.milliseconds, backoff: 2.0,
+  #     maximumDelay: 2.seconds, jitter: 0.0
+  #   }
+  #
+  # @example Share settings, not an attempt budget
+  #   using Net.HTTP
+  #   let schedule = Retry.Schedule { attempts: 5 }
+  #   let inventory = Retry.run(schedule: schedule) do
+  #     HTTP.get("https://api.example.com/inventory")
+  #   end
+  #   let orders = Retry.run(schedule: schedule) do
+  #     HTTP.get("https://api.example.com/orders")
+  #   end
+  #   # Each request gets up to five attempts, independently.
+  record Schedule do
+    # Maximum executions including the initial call. Default: 3.
+    # Values below 1 are treated as 1: the initial call always happens.
+    attempts : Integer = 3
+    # Base wait before the second attempt. Default: 100 milliseconds.
+    # Negative durations are treated as zero; the delay cap applies here too.
+    delay : Duration = Duration.milliseconds(100)
+    # Base-delay multiplier. Default: 2.0. Values below 1 become 1.
+    # Set to 1.0 for fixed delays. Jitter never changes the next base delay.
+    backoff : Float = 2.0
+    # Maximum actual wait, including jitter. Default: 5 seconds.
+    # Negative durations become zero. Hitting this cap does not stop retries.
+    maximumDelay : Duration = Duration.seconds(5)
+    # Symmetric proportional variation. Default: 0.2; clamped to 0..1.
+    # For a 200 ms base, 0.2 samples 160..240 ms, then applies the cap.
+    # Set to 0.0 for exact waits. Samples are independent between runs.
+    jitter : Float = 0.2
+    # Optional bound on cumulative actual sleep. Default: None.
+    # A wait exceeding the remaining allowance stops retries before sleeping.
+    # Negative bounds become zero. Operation execution time is not counted.
+    maximumTotalDelay : Duration? = None
+  end
 
-# Builds a doubling backoff capped at +maximumDelay+.
-#
-# The first retry waits +initialDelay+; later delays double until they reach
-# the cap. Add jitter for production network traffic.
-#
-# @param maximumAttempts [Integer] total calls including the first
-# @param initialDelay [Duration] delay after the first failure
-# @param maximumDelay [Duration] upper bound for each delay
-# @return [Policy] the retry schedule
-#
-# @example Backing off calls to a busy upstream service
-#   Retry.exponential(5, 200.milliseconds, 5.seconds).withJitter(0.25)
-exponential : Integer -> Duration -> Duration -> Policy
-let exponential(maximumAttempts, initialDelay, maximumDelay) = Policy {
-  maximumAttempts: maximumAttempts,
-  initialDelay: initialDelay,
-  multiplier: 2.0,
-  maximumDelay: maximumDelay,
-  maximumElapsed: None,
-  jitterFraction: 0.0
-}
+  # Carries an explicit decision and the last application value.
+  # +Done(value)+ means the block stopped deliberately. +Again(value)+
+  # returned by +run+ means the schedule was exhausted before completion.
+  # Neither form wraps the application value in an additional +Result+.
+  type Decision<X> = Again(X) | Done(X)
+
+  # Requests another attempt if the schedule allows it.
+  #
+  # @param value [X] the last outcome, retained if the schedule is exhausted
+  # @return [Decision<X>] +Again(value)+
+  # @example Polling an application job
+  #   Retry.again("pending")
+  again : X -> Decision<X>
+  let again(value) = Again(value)
+
+  # Stops immediately, even when the application value represents failure.
+  #
+  # @param value [X] the final application outcome
+  # @return [Decision<X>] +Done(value)+
+  # @example Stop on invalid credentials without retrying
+  #   Retry.done(Error("invalid credentials"))
+  done : X -> Decision<X>
+  let done(value) = Done(value)
+
+  # Describes a retry that is about to wait and then execute another attempt.
+  #
+  # Passed to +onRetry+ only after the last outcome requests a retry and
+  # the schedule permits it. There is no notification for the initial call,
+  # success, explicit completion, or exhaustion. Reporting does not consume
+  # attempts. Durations describe scheduled sleep, not wall-clock elapsed time.
+  #
+  # * +attempt+: the just-completed attempt, starting at 1.
+  # * +nextAttempt+: the attempt that follows the upcoming wait.
+  # * +maximumAttempts+: total permitted executions, including the first.
+  # * +remainingAttempts+: executions remaining, including the upcoming one.
+  # * +delay+: actual upcoming wait, after jitter and the delay cap.
+  # * +totalDelay+: sleep already performed, excluding the upcoming wait.
+  # * +result+: the last +Error+ or +Again+, including its application payload.
+  record Info<X> do
+    # The attempt that just finished, starting at 1.
+    attempt : Integer
+    # The attempt that will run after the upcoming delay.
+    nextAttempt : Integer
+    # Total allowed executions, normalized to at least 1.
+    maximumAttempts : Integer
+    # Executions still allowed, including the upcoming attempt.
+    remainingAttempts : Integer
+    # The actual upcoming wait, after jitter and the delay cap.
+    delay : Duration
+    # Sleep already performed in this run, excluding the upcoming wait.
+    totalDelay : Duration
+    # The last Error or Again value, including the application's payload.
+    result : X
+  end
 
-make Policy do
-  # Returns the same schedule with a bound on total scheduled sleep time.
-  #
-  # The operation's own execution time is not counted; use operation-specific
-  # deadlines for that. A retry whose next delay would exceed this bound is
-  # not started.
-  #
-  # @param maximumElapsed [Duration] maximum cumulative scheduled delay
-  # @return [Policy] a copied policy with the elapsed bound
-  # @example +Retry.fixed(5, 1.seconds).withMaximumElapsed(2.seconds)+.
-  let withMaximumElapsed(maximumElapsed: Duration) -> Policy = Policy {
-    maximumAttempts: @maximumAttempts,
-    initialDelay: @initialDelay,
-    multiplier: @multiplier,
-    maximumDelay: @maximumDelay,
-    maximumElapsed: Just(maximumElapsed),
-    jitterFraction: @jitterFraction
-  }
+  # Runs a fresh operation until it succeeds, stops, or exhausts its schedule.
+  #
+  # The first attempt is immediate. Every later attempt follows one sleep.
+  # There is no sleep after success or the final error. Named timing options
+  # override the corresponding schedule field for this execution only.
+  #
+  # An ordinary block returns +Result<X, E>+: +Ok+ stops, +Error+ retries,
+  # and exhaustion returns the last +Error+ unchanged. An explicit block
+  # returns +Decision<X>+: +Done+ stops, +Again+ retries, and exhaustion
+  # returns the last +Again+. Match the returned decision to distinguish
+  # completion from exhaustion. Use one form consistently within a block.
+  #
+  # Finite settings are normalized: attempts below one become one, negative
+  # durations become zero, backoff below one becomes one, jitter and random
+  # samples are clamped to 0..1. Non-finite Float settings are unsupported.
+  #
+  # @param operation [Block<X>] fresh Result or Decision on each attempt
+  # @param schedule [Schedule] reusable settings; defaults to +Schedule {}+
+  # @param attempts [Integer] total attempts; defaults to the schedule field
+  # @param delay [Duration] initial wait; defaults to the schedule field
+  # @param backoff [Float] delay multiplier; defaults to the schedule field
+  # @param maximumDelay [Duration] sleep cap; defaults to the schedule field
+  # @param jitter [Float] variation fraction; defaults to the schedule field
+  # @param maximumTotalDelay [Duration?] sleep budget; defaults to the field
+  # @param sleeper [Duration -> Void] defaults to real +Task.sleep+
+  # @param random [Block<Float>] defaults to secure backend sampling in 0..1
+  # @param onRetry [Info<X> -> Void] reports an allowed retry; defaults to no action
+  # @return [X] first Ok/Done or last Error/Again, without extra wrapping
+  #
+  # @example Named options without constructing a schedule
+  #   Retry.run(attempts: 5, delay: 200.milliseconds, jitter: 0.0) do
+  #     Ok("ready")
+  #   end
+  #   # => Ok("ready")
+  #
+  # @example Stop before a wait exceeds the total sleep budget
+  #   Retry.run(
+  #     attempts: 5, delay: 1.seconds, backoff: 2.0,
+  #     jitter: 0.0, maximumTotalDelay: Just(2.seconds)
+  #   ) do
+  #     Error("busy")
+  #   end
+  #   # => Error("busy"), two calls and one second of sleep
+  #
+  # @example Test jitter without waiting
+  #   Retry.run(
+  #     attempts: 2, delay: 4.seconds, jitter: 0.25,
+  #     sleeper: { |wait| Assert.equal(wait, 3.seconds) },
+  #     random: { 0.0 }
+  #   ) do
+  #     Error("temporary")
+  #   end
+  #   # => Error("temporary"), two calls and one fake sleep
+  #
+  # @example Report progress to a user or log
+  #   using Net.HTTP
+  #   Retry.run(attempts: 5, onRetry: { |info|
+  #     let progress = "retrying ${info.nextAttempt}/${info.maximumAttempts}"
+  #     IO.printLine("${progress} in ${info.delay.seconds} seconds")
+  #   }) do
+  #     HTTP.get("https://api.example.com/inventory")
+  #   end
+  #
+  # @example Retry temporary HTTP failures and selected statuses
+  #   using Net
+  #   using Net.HTTP
+  #   let schedule = Retry.Schedule { attempts: 5 }
+  #   let outcome = Retry.run(schedule: schedule) do
+  #     let result = HTTP.get("https://api.example.com/inventory")
+  #     match result do
+  #       Error(error) => if error.kind == Timeout || error.kind == Connect
+  #         Retry.again(result)
+  #       else
+  #         Retry.done(result)
+  #       end
+  #       Ok(response) => if [429, 502, 503, 504].contains?(response.status.code)
+  #         Retry.again(result)
+  #       else
+  #         Retry.done(result)
+  #       end
+  #     end
+  #   end
+  #   match outcome do
+  #     Done(result) => IO.printLine(result)
+  #     Again(last) => IO.printLine("retry budget exhausted: ${last}")
+  #   end
+  #
+  # +Done(Error(...))+ means the application stopped on a permanent error.
+  # +Again(Ok(response))+ means an unacceptable HTTP status persisted until
+  # exhaustion. HTTP status classification and Retry-After handling are the
+  # application's responsibility; +run+ has no HTTP-specific behavior.
+  #
+  # The testing hooks are independent: replacing sleep keeps normal random
+  # sampling, and replacing randomness keeps real sleep. A random sample of
+  # 0 selects the lower jitter bound, 0.5 the base, and 1 the upper bound.
+  # With zero jitter no random sample is needed.
+  # lint:allow parameter-count — named options make each setting independent
+  run : Block<X> -> Schedule -> Integer -> Duration -> Float -> Duration -> Float -> Duration? -> (Duration -> Void) -> Block<Float> -> (Info<X> -> Void) -> X
+  foul run(
+    operation,
+    schedule = Schedule {},
+    attempts = schedule.attempts,
+    delay = schedule.delay,
+    backoff = schedule.backoff,
+    maximumDelay = schedule.maximumDelay,
+    jitter = schedule.jitter,
+    maximumTotalDelay = schedule.maximumTotalDelay,
+    sleeper = { |wait| Task.sleep(wait) },
+    random = { Kex.Intrinsic.Retry.randomUnit() },
+    onRetry = { |_info| () }
+  ) do
+    let settings = Schedule {
+      attempts: attempts,
+      delay: delay,
+      backoff: backoff,
+      maximumDelay: maximumDelay,
+      jitter: jitter,
+      maximumTotalDelay: maximumTotalDelay
+    }
+    attempt(settings, sleeper, random, onRetry, operation, 1, boundedDelay(settings, delay.seconds), 0.0)
+  end
 
-  # Returns the same schedule with symmetric bounded jitter. A fraction of
-  # +0.25+ selects each actual delay from 75% through 125% of its scheduled
-  # value. Fractions are clamped to +0.0..1.0+.
-  #
-  # Jitter prevents many workers that failed together from retrying together.
-  # It changes delay timing, never the number of attempts or the backoff cap.
-  #
-  # @param fraction [Float] maximum proportional variation on either side
-  # @return [Policy] a copied policy with bounded jitter
-  #
-  # @example Spreading retries by up to 20 percent
-  #   Retry.exponential(4, 1.seconds, 10.seconds).withJitter(0.2)
-  let withJitter(fraction: Float) -> Policy = Policy {
-    maximumAttempts: @maximumAttempts,
-    initialDelay: @initialDelay,
-    multiplier: @multiplier,
-    maximumDelay: @maximumDelay,
-    maximumElapsed: @maximumElapsed,
-    jitterFraction: if fraction < 0.0 then 0.0 else if fraction > 1.0 then 1.0 else fraction end end
-  }
-end
+  private do
+    retry? : Result<X, E> -> Bool
+    let retry?(Ok(_)) = false
+    let retry?(Error(_)) = true
+    retry? : Decision<X> -> Bool
+    let retry?(Done(_)) = false
+    let retry?(Again(_)) = true
+
+    let clamp(value: Float, low: Float, high: Float) -> Float do
+      if value < low
+        low
+      elif value > high
+        high
+      else
+        value
+      end
+    end
 
-# Runs +operation+ until it succeeds or exhausts the policy.
-#
-# The last application error is returned unchanged. This helper performs no
-# network-specific classification: callers decide what operation to wrap.
-#
-# @param policy [Policy] the bounded schedule
-# @param operation [Block<Result<X,E>>] a fresh attempt
-# @return [Result<X,E>] the first success or final failure
-#
-# @example Retrying an idempotent health check
-#   Retry.run(Retry.fixed(3, 250.milliseconds)) do
-#     HTTP.get("https://service.example.com/health")
-#   end
-run : Policy -> Block<Result<X, E>> -> Result<X, E>
-foul run(policy, operation) = runWithRandom(policy, { |error| true }, { |delay| Task.sleep(delay) }, { Kex.Intrinsic.Retry.randomUnit() }, operation)
+    let boundedDelay(schedule: Schedule, waitSeconds: Float) -> Float do
+      let cap = if schedule.maximumDelay.seconds < 0.0
+        0.0
+      else
+        schedule.maximumDelay.seconds
+      end
+      clamp(waitSeconds, 0.0, cap)
+    end
 
-# Runs with an application-specific error predicate.
-#
-# A false predicate returns that error immediately. The predicate is evaluated
-# only when another attempt would otherwise be possible.
-#
-# @param policy [Policy] the bounded schedule
-# @param predicate [Predicate<E>] whether an error may be retried
-# @param operation [Block<Result<X,E>>] a fresh attempt
-# @return [Result<X,E>] the first success or final/non-retryable failure
-#
-# @example Retrying timeouts but returning parse failures immediately
-#   Retry.run(policy, { |error| error.kind == Timeout }) do
-#     client.get(url)
-#   end
-run : Policy -> Predicate<E> -> Block<Result<X, E>> -> Result<X, E>
-foul run(policy, predicate, operation) = runWithRandom(policy, predicate, { |delay| Task.sleep(delay) }, { Kex.Intrinsic.Retry.randomUnit() }, operation)
-
-# Runs with injected error classification and sleeping.
-#
-# This is the deterministic testing seam: a fake sleeper can record durations
-# or advance a virtual clock. Production callers normally use +Retry.run+.
-#
-# @param policy [Policy] the bounded schedule
-# @param predicate [Predicate<E>] whether an error may be retried
-# @param sleeper [Sleeper] performs or records each scheduled delay
-# @param operation [Block<Result<X,E>>] a fresh attempt
-# @return [Result<X,E>] the first success or final failure
-runWith : Policy -> Predicate<E> -> Sleeper -> Block<Result<X, E>> -> Result<X, E>
-foul runWith(policy, predicate, sleeper, operation) = runWithRandom(policy, predicate, sleeper, { 0.5 }, operation)
-
-# Runs with injected sleeping and a random source returning a value in
-# +0.0..1.0+. Out-of-range test values are clamped. Production +run+ uses a
-# cryptographically secure backend source; this overload makes jitter specs
-# deterministic.
-runWithRandom : Policy -> Predicate<E> -> Sleeper -> Block<Float> -> Block<Result<X, E>> -> Result<X, E>
-foul runWithRandom(policy, predicate, sleeper, random, operation) = attempt(policy, predicate, sleeper, random, operation, 1, policy.initialDelay, Duration.seconds(0))
-
-foul attempt(policy: Policy, predicate: Predicate<E>, sleeper: Sleeper, random: Block<Float>, operation: Block<Result<X, E>>, number: Integer, delay: Duration, elapsed: Duration) -> Result<X, E> do
-  let result = operation()
-  return match result do
-    Ok(value) => Ok(value)
-    Error(error) => do
-      if number >= policy.maximumAttempts || !predicate(error)
-        return Error(error)
+    attempt : Schedule -> (Duration -> Void) -> Block<Float> -> (Info<X> -> Void) -> Block<X> -> Integer -> Float -> Float -> X
+    foul attempt(schedule, sleeper, random, onRetry, operation, number, base, elapsed) do
+      let result = operation()
+      if number >= schedule.attempts || !retry?(result)
+        return result
       end
-      let sample = random()
-      let boundedSample = if sample < 0.0 then 0.0 else if sample > 1.0 then 1.0 else sample end end
-      let jittered = Duration { seconds: delay.seconds * (1.0 + ((boundedSample * 2.0 - 1.0) * policy.jitterFraction)) }
-      let nextElapsed = Duration { seconds: elapsed.seconds + jittered.seconds }
-      let withinElapsed = match policy.maximumElapsed do
+      let fraction = clamp(schedule.jitter, 0.0, 1.0)
+      let sample = if fraction == 0.0 then 0.5 else clamp(random(), 0.0, 1.0) end
+      let sleepSeconds = boundedDelay(schedule, base * (1.0 + (sample * 2.0 - 1.0) * fraction))
+      let nextElapsed = elapsed + sleepSeconds
+      let allowed = match schedule.maximumTotalDelay do
         None => true
-        Just(maximum) => nextElapsed.seconds <= maximum.seconds
+        Just(limit) => nextElapsed <= (if limit.seconds < 0.0 then 0.0 else limit.seconds end)
       end
-      if !withinElapsed
-        return Error(error)
+      if !allowed
+        return result
       end
-      sleeper(jittered)
-      let nextSeconds = delay.seconds * policy.multiplier
-      let bounded = if nextSeconds > policy.maximumDelay.seconds then policy.maximumDelay else Duration { seconds: nextSeconds } end
-      return attempt(policy, predicate, sleeper, random, operation, number + 1, bounded, nextElapsed)
+      onRetry(Info {
+        attempt: number,
+        nextAttempt: number + 1,
+        maximumAttempts: schedule.attempts,
+        remainingAttempts: schedule.attempts - number,
+        delay: Duration { seconds: sleepSeconds },
+        totalDelay: Duration { seconds: elapsed },
+        result: result
+      })
+      sleeper(Duration { seconds: sleepSeconds })
+      let factor = if schedule.backoff < 1.0 then 1.0 else schedule.backoff end
+      let nextBase = boundedDelay(schedule, base * factor)
+      attempt(schedule, sleeper, random, onRetry, operation, number + 1, nextBase, nextElapsed)
     end
   end
 end
-
-# The imported public namespace: `using Control.Retry` then `Retry.run(...)`.
-module Retry do
-  # Public imported alias of +Control.Retry.fixed+.
-  fixed : Integer -> Duration -> Policy
-  let fixed(maximumAttempts, delay) = Control.Retry.fixed(maximumAttempts, delay)
-
-  # Public imported alias of +Control.Retry.exponential+.
-  exponential : Integer -> Duration -> Duration -> Policy
-  let exponential(maximumAttempts, initialDelay, maximumDelay) = Control.Retry.exponential(maximumAttempts, initialDelay, maximumDelay)
-
-  # Public imported alias of +Control.Retry.run+.
-  run : Policy -> Block<Result<X, E>> -> Result<X, E>
-  foul run(policy, operation) = Control.Retry.run(policy, operation)
-
-  # Retries only errors accepted by +predicate+.
-  run : Policy -> Predicate<E> -> Block<Result<X, E>> -> Result<X, E>
-  foul run(policy, predicate, operation) = Control.Retry.run(policy, predicate, operation)
-
-  # Deterministic seam with an injected sleeper, primarily for specifications.
-  runWith : Policy -> Predicate<E> -> Sleeper -> Block<Result<X, E>> -> Result<X, E>
-  foul runWith(policy, predicate, sleeper, operation) = Control.Retry.runWith(policy, predicate, sleeper, operation)
-
-  # Deterministic seam with injected sleeping and random sampling.
-  runWithRandom : Policy -> Predicate<E> -> Sleeper -> Block<Float> -> Block<Result<X, E>> -> Result<X, E>
-  foul runWithRandom(policy, predicate, sleeper, random, operation) = Control.Retry.runWithRandom(policy, predicate, sleeper, random, operation)
-end
 # A first-in-first-out queue.
 #
 # Opt-in: nothing here is in scope until `using Data.Queue`.
@@ -2447,6 +2595,89 @@ module Digest do
   fileSha256 : String -> String?
   let fileSha256(path) = Kex.Intrinsic.Digest.fileSha256(path)
 end
+# Dimension algebra, implemented with ordinary Kex maps and integers.
+#
+# A base dimension is identified by the type of a marker value. Reuse that
+# marker type to share a dimension across modules. Its display name and the
+# marker's field values do not participate in dimensional arithmetic.
+#
+# Multiplication adds exponents, division subtracts them, and integer powers
+# multiply them. Zero exponents are removed so cancellation is structural.
+module Dimensions
+
+# A normalized map from base identities to integer exponents.
+#
+# Construct dimensions with +Dimensions.base+ and compose them with arithmetic.
+# If importing a map, use +Dimensions.fromPowers+ to remove zero exponents.
+# This runtime representation does not itself provide static measure typing.
+record Dimension do
+  powers : {Type: Integer}
+end
+
+# The dimension with no remaining base factors.
+#
+# @return [Dimension] the multiplicative identity
+let one -> Dimension = Dimension { powers: {} }
+
+# Defines a base dimension using the nominal type of a marker value.
+#
+# @param marker [A] a value of a dedicated marker type
+# @return [Dimension] that base dimension, raised to the first power
+let base(marker: A) -> Dimension = Dimension {
+  powers: {}.put(Type.of(marker), 1)
+}
+
+# Normalizes a map of base identities and powers.
+#
+# @param powers [Map<Type, Integer>] the dimension's exponents
+# @return [Dimension] the same dimension with zero exponents removed
+let fromPowers(powers: {Type: Integer}) -> Dimension = Dimension {
+  powers: powers.filter { |_, exponent| exponent != 0 }
+}
+
+make Dimension do
+  # Whether every base factor has cancelled.
+  #
+  # @return [Bool] true for a dimensionless quantity
+  dimensionless? :> Bool
+  let dimensionless? = @powers.values.all? { |exponent| exponent == 0 }
+
+  # The exponent of the supplied marker's dimension, or zero if absent.
+  #
+  # @param marker [A] a value of the base marker type
+  # @return [Integer] the base's exponent
+  exponentOf :> A -> Integer
+  let exponentOf(marker) = @powers.get(Type.of(marker), 0)
+
+  # Composes dimensions by adding their base exponents.
+  #
+  # @param other [Dimension] the other factor
+  # @return [Dimension] the normalized product
+  * :> Dimension -> Dimension
+  let *(other) do
+    let powers = other.powers.entries.reduce(@powers) do |result, entry|
+      let (base, exponent) = entry
+      result.put(base, result.get(base, 0) + exponent)
+    end
+    Dimensions.fromPowers(powers)
+  end
+
+  # Composes dimensions by subtracting the denominator's exponents.
+  #
+  # @param other [Dimension] the denominator's dimension
+  # @return [Dimension] the normalized quotient
+  / :> Dimension -> Dimension
+  let /(other) = this * (other ^ -1)
+
+  # Raises a dimension to an integer power, including zero and negatives.
+  #
+  # @param exponent [Integer] the power
+  # @return [Dimension] the normalized powered dimension
+  ^ :> Integer -> Dimension
+  let ^(exponent) = Dimensions.fromPowers(
+    @powers.mapValues { |power| power * exponent }
+  )
+end
 # Traversal operations that every foldable collection gets for free.
 #
 # A type becomes +Foldable+ by implementing one method, +reduce+; the rest:
@@ -3565,6 +3796,36 @@ make FileHandle<R, W> do
   #   end
   close :> Void
   foul close = Kex.Intrinsic.FileHandle.close(this)
+
+  # Moves the handle's cursor to an absolute byte offset from the start of
+  # the file. Read and write share one cursor, so this repositions both —
+  # a `readLine` right after `seek(0)` starts over from the top, and a
+  # `write` right after does too, overwriting from that point.
+  #
+  # @param offset [Integer] the byte offset to seek to, from the start of
+  #   the file
+  # @return [Result<Void, ReadError>] +Ok+ on success, or why the seek
+  #   failed
+  #
+  # @example Reading a length-prefixed record, then rewinding past it
+  #   let length = handle.readLine.or("0").to(Integer).or(0)
+  #   let record = handle.readBytes.try
+  #   handle.seek(0)
+  seek : Integer -> Result<Void, ReadError>
+  foul seek(offset) = Kex.Intrinsic.FileHandle.seek(this, offset)
+
+  # Moves the handle's cursor back to the start of the file — the same as
+  # +seek(0)+, for the common case of re-reading a handle from the top.
+  #
+  # @return [Result<Void, ReadError>] +Ok+ on success, or why the reset
+  #   failed
+  #
+  # @example Reading a file twice
+  #   let firstPass = handle.read.or("")
+  #   handle.reset
+  #   let secondPass = handle.read.or("")
+  reset :> Result<Void, ReadError>
+  foul reset = Kex.Intrinsic.FileHandle.reset(this)
 end
 # The filesystem: reading and writing files, walking directories, and
 # manipulating paths.
@@ -4009,6 +4270,33 @@ module FS do
     # because it is not lexical: it asks the process where it is.
     absolute : FilePath -> String?
     foul absolute(path) = Kex.Intrinsic.File.absolute(path)
+
+    # The canonical form of +path+: absolute, with every +.+, +..+ and
+    # symlink resolved, like +realpath(3)+.
+    #
+    # Unlike +absolute+ this reads the filesystem, so a path that does not
+    # exist (or a symlink loop) is an error. Use it to keep reads and writes
+    # inside a directory: compare the real path's prefix, and neither +../+
+    # nor a symlink can escape.
+    #
+    # @param path [FilePath] the path to resolve
+    # @return [Result<String, FileError>] the canonical path, or +ReadFailed+
+    #
+    # @example
+    #   FS.File.canonical("/tmp/../etc")   # => Ok("/private/etc") on macOS
+    canonical : FilePath -> Result<String, FileError>
+    foul canonical(path) = Kex.Intrinsic.File.canonical(path)
+
+    # Whether +path+ is itself a symlink, without following it. A dangling
+    # link is still a symlink.
+    #
+    # @param path [FilePath] the path to inspect
+    # @return [Bool] +true+ for a symlink
+    #
+    # @example
+    #   FS.File.symlink?("current")   # => true
+    symlink? : FilePath -> Bool
+    foul symlink?(path) = Kex.Intrinsic.File.symlink?(path)
   end
 
   # Path arithmetic: joining, splitting, normalising and comparing paths.
@@ -4855,6 +5143,14 @@ private do
     end
 
     let allowComments = Kex.Intrinsic.Map.getWithDefault(options, allowCommentsKey(), false)
+    # On BEAM, OTP's own decoder builds the same value in a fraction of the
+    # time (kexhq/kex#333). It answers None for anything it will not vouch
+    # for — invalid input, JSONC, the tree-walker — and this parser runs.
+    if !allowComments
+      if let Just(value) = Kex.Intrinsic.Json.decode(text)
+        return Ok(value)
+      end
+    end
     let cursor = skipIgnored(Input { input: text }, allowComments).try
     let (value, afterValue) = parseValue(cursor, allowComments).try
     let rest = skipIgnored(afterValue, allowComments).try
@@ -4889,25 +5185,40 @@ end
 #   JSON.parse(JSON.stringify({ a: 1 }))   # => Ok({ a: 1 })
 stringify : Any -> String
 let stringify(value: Any) -> String do
-  match Kex.Intrinsic.Kex.kind(value) do
-    :none => return "null"
-    :bool => return value then "true" else "false"
-    :integer => return "${value}"
-    :float => return "${value}"
-    :string => return encodeString(value)
-    :list => return "[${value.map(~stringify).join(",")}]"
-    :map => do
-      let fields = Kex.Intrinsic.Map.entries(value).map do |entry|
-        let (key, item) = entry
-        "${encodeString(objectKey(key))}:${stringify(item)}"
-      end
-      return "{${fields.join(",")}}"
-    end
-    _ => return "null"
+  # The BEAM encoder follows `stringifyValue` rule for rule (kexhq/kex#333);
+  # the tree-walker has none and answers None.
+  if let Just(text) = Kex.Intrinsic.Json.encode(value)
+    return text
   end
+  return stringifyValue(value)
 end
 
 private do
+  let stringifyValue(value: Any) -> String do
+    # An optional is JSON's nullable: `Just(x)` is `x`, as `None` is `null`.
+    # Without this a caller had to unwrap first, and the only spelling that
+    # type-checked was the meaningless `.or(None)`.
+    if let Just(inner) = value
+      return stringifyValue(inner)
+    end
+    match Kex.Intrinsic.Kex.kind(value) do
+      :none => return "null"
+      :bool => return value then "true" else "false"
+      :integer => return "${value}"
+      :float => return "${value}"
+      :string => return encodeString(value)
+      :list => return "[${value.map(~stringifyValue).join(",")}]"
+      :map => do
+        let fields = Kex.Intrinsic.Map.entries(value).map do |entry|
+          let (key, item) = entry
+          "${encodeString(objectKey(key))}:${stringifyValue(item)}"
+        end
+        return "{${fields.join(",")}}"
+      end
+      _ => return "null"
+    end
+  end
+
   # A JSON object key is a string, but a Kex map literal is written with ATOM
   # keys (`{ n: 1 }`): the shape most values being stringified actually have.
   # Rendering one gives `:n`, so drop the leading colon; anything else goes
@@ -5686,6 +5997,144 @@ module Kex.AST do
   parseExpression : String -> Result<Expression, ParseError>
   let parseExpression(source) = Kex.Intrinsic.AST.parseExpression(source)
 
+  # One token of a lossless syntax tree, exactly as written.
+  #
+  # Where +parse+ gives a program's meaning, +parseSyntax+ gives its text:
+  # nothing is normalised or dropped, so +toSource+ reprints the file byte for
+  # byte. It is the tree a formatter or a linter works on (kexhq/kex#136).
+  record SyntaxToken do
+    # The lexer's name for the token: +LowerIdent+, +Newline+, +Eof+, ...
+    kind : String
+
+    # The token exactly as written, quotes, escapes and underscores included.
+    text : String
+
+    # Everything between the previous token and this one: spaces, tabs and
+    # comments. A comment on a line of its own sits in front of the +Newline+
+    # that ends that line; whatever follows the last token belongs to +Eof+.
+    trivia : String
+  end
+
+  # One child of a +SyntaxNode+: a token, or a nested node.
+  type SyntaxElement = TokenElement(SyntaxToken) | NodeElement(SyntaxNode)
+
+  # A declaration, expression, pattern or type, holding its own tokens and
+  # nested nodes in source order.
+  #
+  #   let tree = Kex.AST.parseSyntax("# the answer\nlet x = 42\n").try
+  #   tree.kind                  # => "Program"
+  #   Kex.AST.toSource(tree)     # => "# the answer\nlet x = 42\n"
+  record SyntaxNode do
+    # What the parser built there: +FunctionDef+, +MethodCall+, +ListPattern+,
+    # ... The root is +Program+.
+    kind : String
+
+    # The node's tokens and nested nodes, in source order.
+    children : [SyntaxElement]
+  end
+
+  # Parses Kex source into its lossless syntax tree.
+  #
+  # @param source [String] the Kex source text
+  # @return [Result<SyntaxNode, ParseError>] the tree rooted at +Program+, or why it failed
+  #
+  # @example
+  #   Kex.AST.parseSyntax("let x = 1\n").map { |tree| tree.kind }   # => Ok("Program")
+  #   Kex.AST.parseSyntax("let x =").error?                         # => true
+  parseSyntax : String -> Result<SyntaxNode, ParseError>
+  let parseSyntax(source) = Kex.Intrinsic.AST.parseSyntax(source)
+
+  # Reprints a syntax tree as the source it was parsed from, byte for byte.
+  #
+  # Every node prints its own tokens and its nested nodes in order, never a
+  # slice of the original text, so a rearranged tree prints the rearranged
+  # program, its comments moving with it.
+  #
+  # @param node [SyntaxNode] a tree, or any node in one
+  # @return [String] the source the node covers, trivia included
+  #
+  # @example
+  #   let source = "let x = 1   # one\n"
+  #   Kex.AST.parseSyntax(source).map { |tree| Kex.AST.toSource(tree) }   # => Ok(source)
+  toSource : SyntaxNode -> String
+  let toSource(node) = node.children.map { |child| Kex.AST.elementSource(child) }.join("")
+
+  # The source of one child of a node: a token's trivia and text, or a nested
+  # node reprinted.
+  #
+  # @param element [SyntaxElement] the child
+  # @return [String] its source text
+  elementSource : SyntaxElement -> String
+  let elementSource(element) = match element do
+    TokenElement(token) => token.trivia + token.text
+    NodeElement(child) => Kex.AST.toSource(child)
+  end
+
+  # The comments written on their own lines directly above the child at
+  # +index+: the ones that belong to it, move with it when a formatter moves
+  # it, and hold a `# kex:disable-next-line` meant for it.
+  #
+  # A comment at the end of the previous line trails that line instead, and is
+  # not included.
+  #
+  # @param parent [SyntaxNode] the node holding the child
+  # @param index [Integer] the child's position in +parent.children+
+  # @return [[String]] the comment lines, top to bottom, each starting with +#+
+  #
+  # @example
+  #   let tree = Kex.AST.parseSyntax("let x = 1  # x\n# about y\nlet y = 2\n").try
+  #   Kex.AST.commentsBefore(tree, 3)   # => ["# about y"]
+  commentsBefore : SyntaxNode -> Integer -> [String]
+  let commentsBefore(parent, index) do
+    var comments: [String] = []
+    Kex.AST.linesBefore(parent, index).each do |line|
+      let text = line.trim
+      comments = comments + [text] if text.startsWith?("#")
+    end
+    return comments
+  end
+
+  # How many blank lines separate the child at +index+ from what precedes it.
+  #
+  # Kept as a count, not a flag: a formatter preserves one blank line between
+  # declarations and collapses longer runs, which needs to know how many there
+  # were.
+  #
+  # @param parent [SyntaxNode] the node holding the child
+  # @param index [Integer] the child's position in +parent.children+
+  # @return [Integer] the number of blank lines directly above the child
+  #
+  # @example
+  #   let tree = Kex.AST.parseSyntax("let x = 1\n\n\nlet y = 2\n").try
+  #   Kex.AST.blankLinesBefore(tree, 4)   # => 2
+  blankLinesBefore : SyntaxNode -> Integer -> Integer
+  let blankLinesBefore(parent, index) = Kex.AST.linesBefore(parent, index).filter { |line| line.trim.empty? }.count
+
+  # The whole lines between the child at +index+ and the code before it, as
+  # the trivia of the +Newline+ tokens that end them. The newline that ends the
+  # previous line of code is not one of them: what sits in front of it trails
+  # that code.
+  #
+  # @param parent [SyntaxNode] the node holding the child
+  # @param index [Integer] the child's position in +parent.children+
+  # @return [[String]] the lines, top to bottom, without their newlines
+  linesBefore : SyntaxNode -> Integer -> [String]
+  let linesBefore(parent, index) do
+    var position = index - 1
+    var lines: [String] = []
+    var scanning = true
+    while scanning && position >= 0 do
+      match parent.children.at(position) do
+        Just(TokenElement(token)) when token.kind == "Newline" => do
+          lines = [token.trivia] + lines
+          position = position - 1
+        end
+        _ => scanning = false
+      end
+    end
+    return position >= 0 then lines.drop(1) else lines
+  end
+
   # A type as it was written in source.
   #
   # +typeRefText+ renders one back to the source spelling.
@@ -6246,6 +6695,17 @@ make [Number] do
   let max = Kex.Intrinsic.List.max(this)
 end
 
+make [[Y]] do
+  # Flattens exactly one level of nesting.
+  #
+  # @return [[Y]]
+  #
+  # @example
+  #   [[1, 2], [3, 4]].flatten   # => [1, 2, 3, 4]
+  flatten :> [Y]
+  let flatten = Kex.Intrinsic.List.flatten(this)
+end
+
 make [X], implement: Enumerable, Foldable do
   # Returns the first element wrapped in +Just+, or +None+ if the list is empty.
   #
@@ -6638,15 +7098,6 @@ make [X], implement: Enumerable, Foldable do
   zip :> [Y] -> [(X, Y)]
   let zip(other) = Kex.Intrinsic.List.zip(this, other)
 
-  # Flattens exactly one level of nesting. Only valid on lists of lists.
-  #
-  # @return [[Y]]
-  #
-  # @example
-  #   [[1, 2], [3, 4]].flatten   # => [1, 2, 3, 4]
-  flatten :> [X]
-  let flatten = Kex.Intrinsic.List.flatten(this)
-
   # Returns the elements sorted in ascending natural order.
   #
   # @return [[X]]
@@ -7830,6 +8281,11 @@ module Mock do
     foul file?(path) = this.cannedRead(path) != None
     foul directory?(path) = false
     foul absolute(path) = Just(path)
+    foul canonical(path) = match this.cannedRead(path) do
+      Just(_) => Ok(path)
+      None => Error(ReadFailed(path))
+    end
+    foul symlink?(path) = false
 
     # A fake is a value, so there is nowhere for a write to go. Refusing is
     # the honest answer and the useful one: a test that did not expect a
@@ -8243,6 +8699,18 @@ module Net.HTTP
 
 # An insertion-ordered HTTP field collection. Names compare case-insensitively
 # and duplicate fields are preserved.
+#
+# A list of pairs rather than a +{String: String}+ map, and deliberately so.
+# A map cannot hold the same name twice, and +Set-Cookie+ needs exactly that:
+# RFC 6265 does not define it as a comma-separated list, so two cookies must
+# travel as two fields and cannot be joined into one. A map interface would
+# read as the obvious one right up to the first response that sets two
+# cookies, then silently keep one — the same class of quiet data loss this
+# module's +Result+-returning builders exist to avoid.
+#
+# Order is kept for the same reason. RFC 9110 makes order insignificant
+# BETWEEN different names but significant between fields sharing a name, and
+# a map has no order to keep.
 record Headers do
   entries : [(String, String)]
 end
@@ -8345,8 +8813,8 @@ module Headers do
   #
   # @example Building request headers immutably
   #   Headers.empty
-  #     .add("Accept", "application/json")
-  #     .add("User-Agent", "inventory-sync/1.0")
+  #     .add("Accept", "application/json").try
+  #     .add("User-Agent", "inventory-sync/1.0").try
   empty : Headers
   let empty = Headers { entries: [] }
 
@@ -8366,6 +8834,22 @@ module Headers do
   from : [(String, String)] -> Result<Headers, NetError>
   let from(entries) = Kex.Intrinsic.NetHTTP.headers(entries)
 
+  # Validates header names and values from unordered pairs, for the common
+  # case where every name is used once. Do not use this for `Set-Cookie` or
+  # any other field that legitimately repeats — a `Map` cannot hold a name
+  # twice, so unlike the list form above, a second value for the same name
+  # here does not add a second field; it silently replaces the first (see
+  # this module's own +Headers+ record doc for why that specific field
+  # cannot be folded into one entry). Reach for the ordered list form for
+  # anything that might repeat a name.
+  #
+  # @return [Result<Headers, NetError>] validated fields, or +Parse+
+  #
+  # @example Forwarding a set of request headers that are each sent once
+  #   Headers.from({ "Accept": "application/json", "X-Request-ID": requestId }).try
+  from : Map<String, String> -> Result<Headers, NetError>
+  let from(entries: Map<String, String>) = Kex.Intrinsic.NetHTTP.headers(entries.entries)
+
   # Parses CRLF- or LF-separated header fields.
   #
   # Use this at a protocol boundary when headers arrive as text. Application
@@ -8398,7 +8882,7 @@ module Response do
   # Builds a buffered binary response with validated headers.
   #
   # @example Returning a downloaded file without decoding it as text
-  #   Response.binary(200, archive, Headers.empty.set("Content-Type", "application/zip"))
+  #   Response.binary(200, archive, Headers.empty.add("Content-Type", "application/zip").try)
   foul binary(status: Integer, body: Binary, headers: Headers) -> Response<Binary> = Kex.Intrinsic.NetHTTP.responseBinary(status, body, headers)
   # Builds a UTF-8 text response with an explicit text/plain content type.
   #
@@ -8524,8 +9008,8 @@ make Client do
   #
   # @example Sending JSON with an idempotency key
   #   let headers = Headers.empty
-  #     .set("Content-Type", "application/json")
-  #     .set("Idempotency-Key", requestId)
+  #     .add("Content-Type", "application/json").try
+  #     .add("Idempotency-Key", requestId).try
   #   client.request("POST", url, headers, JSON.stringify(order).to(Binary).try)
   foul request(method: String, url: String, headers: Headers, body: Binary) -> Result<Response<Binary>, NetError> = Kex.Intrinsic.NetHTTPClient.request(this, method, url, headers, body)
   # Sends a buffered GET request.
@@ -8557,12 +9041,27 @@ make Client do
 end
 
 make Headers, implement: Showable, Inspectable do
-  # Appends a field without replacing existing fields of the same name.
-  # @example +Headers.empty.add("Accept", "text/plain")+
-  let add(name: String, value: String) -> Headers = Kex.Intrinsic.NetHTTP.addHeader(this, name, value)
-  # Replaces all fields of +name+ with one value.
-  # @example +headers.set("Content-Type", "application/json")+
-  let set(name: String, value: String) -> Headers = Kex.Intrinsic.NetHTTP.setHeader(this, name, value)
+  # Appends a field, keeping existing fields of the same name.
+  #
+  # Repeats are how +Set-Cookie+ works: it is not a comma-separated list, so
+  # two cookies must be two fields. For replace-semantics, +remove+ first.
+  #
+  # An invalid name or value is an +Error+, not a silent drop. Rejecting
+  # +"a\r\nX: y"+ is what stops response splitting, but dropping it quietly
+  # left the caller holding a valid +Headers+ that simply lacked the field it
+  # asked for, and a response with no +Content-Type+ invites MIME sniffing.
+  # +from+ and +parse+ already answer with a +Result+ for this same input.
+  #
+  # @return [Result<Headers, NetError>] the extended fields, or +Parse+
+  #
+  # @example Two cookies on one response
+  #   Headers.empty
+  #     .add("Set-Cookie", "session=abc; HttpOnly").try
+  #     .add("Set-Cookie", "theme=dark").try
+  #
+  # @example Replacing a field
+  #   headers.remove("Content-Type").add("Content-Type", "application/json").try
+  let add(name: String, value: String) -> Result<Headers, NetError> = Kex.Intrinsic.NetHTTP.addHeader(this, name, value)
   # Removes every field matching +name+ case-insensitively.
   #
   # @example Stripping hop-by-hop state before forwarding
@@ -8619,7 +9118,7 @@ module HTTP do
   # occasional requests; use +Client+ for a service making repeated calls.
   #
   # @example A one-off authenticated request in a command-line tool
-  #   let headers = Headers.empty.set("Authorization", "Bearer ${token}")
+  #   let headers = Headers.empty.add("Authorization", "Bearer ${token}").try
   #   HTTP.request("GET", url, headers).try
   request : String -> String -> Headers -> Binary -> Result<Response<Binary>, NetError>
   let request(method, url, headers = Headers.empty, body = Binary.empty) = Kex.Intrinsic.NetHTTP.request(method, url, headers, body)
@@ -8669,6 +9168,8 @@ end
 #   socket.close
 module Net.HTTP.WebSocket
 
+using Net.HTTP
+
 # A complete high-level WebSocket message. Fragmentation and ping/pong control
 # frames are handled by the connection runtime.
 #
@@ -8692,10 +9193,31 @@ record Session do
   subprotocol : String?
 end
 
-# An opaque RFC 6455 client connection. It does not reconnect automatically.
+# An opaque RFC 6455 connection, client- or server-side. It does not
+# reconnect automatically.
 type Connection
 
-# Constructors for high-level WebSocket client connections.
+# Subprotocols offered by an incoming upgrade request, in the order the peer
+# listed them.
+record Handshake do
+  subprotocols : [String] = []
+end
+
+# A server's decision after inspecting a +Handshake+.
+#
+# +Accept+ takes over the connection once the 101 response is sent: +handler+
+# runs with the negotiated server +Connection+, and its return value is
+# discarded. +headers+ are added to the 101 response; a name that manages the
+# handshake itself (+Upgrade+, +Connection+, +Sec-WebSocket-Accept+,
+# +Sec-WebSocket-Protocol+) is dropped rather than overridden. +subprotocol+
+# must be one +handshake.subprotocols+ actually offered, or +None+.
+#
+# +Reject+ answers with an ordinary buffered response instead, leaving the
+# connection as plain HTTP — a client requesting an unsupported subprotocol
+# might get +Response.text(426, "chat.v2 required")+, for instance.
+type Upgrade = Accept(Connection -> Void, Headers, String?) | Reject(Response<Binary>)
+
+# Constructors for high-level WebSocket connections, client- and server-side.
 module WebSocket do
   # Opens a +ws:+ or verified +wss:+ connection with default options.
   #
@@ -8720,6 +9242,32 @@ module WebSocket do
   #     maximumMessageBytes: 1024 * 1024
   #   }).try
   foul connect(url: String, options: ClientOptions) -> Result<Connection, NetError> = Kex.Intrinsic.NetWebSocket.connect(url, options)
+
+  # Decides whether to accept an incoming +Net.HTTP.Server+ upgrade request.
+  #
+  # Call from a route handler and return the result directly — it types as
+  # an ordinary +Response<Binary>+, and +Net.HTTP.Server+ recognizes what it
+  # actually is: a request that isn't a syntactically valid WebSocket
+  # handshake at all (wrong method, missing +Sec-WebSocket-Key+, unsupported
+  # +Sec-WebSocket-Version+) is answered automatically without calling
+  # +decide+; a valid one reaches +decide+ for an application decision.
+  #
+  # @param request [Request<Binary>] the route handler's own request
+  # @param decide [Handshake -> Upgrade] the accept/reject decision
+  # @return [Response<Binary>] the handler's response — an upgrade in
+  #   disguise on +Accept+, sent as given on +Reject+
+  #
+  # @example An authenticated, subprotocol-gated chat route
+  #   foul socketRoute(request: Request<Binary>, context: Context) -> Response<Binary> = WebSocket.upgrade(request) do |handshake|
+  #     if handshake.subprotocols.contains?("chat.v2")
+  #       let handler : Connection -> Void = { |socket| serveChat(socket) }
+  #       Accept(handler, Headers.empty, Just("chat.v2"))
+  #     else
+  #       Reject(Response.text(426, "chat.v2 required"))
+  #     end
+  #   end
+  #   let router = Router.build.get("/socket", ~socketRoute)
+  foul upgrade(request: Request<Binary>, decide: Handshake -> Upgrade) -> Response<Binary> = Kex.Intrinsic.NetWebSocket.upgrade(request, decide)
 end
 
 make Connection do
@@ -8748,6 +9296,32 @@ make Connection do
   #     end
   #   end
   foul receiveMessage() -> Result<Message, NetError> = Kex.Intrinsic.NetWebSocket.receiveMessage(this)
+  # `receiveMessage`, but the deadline is explicit rather than implicit in
+  # whether you passed an argument at all: +None+ waits exactly as long as
+  # a bare +receiveMessage+ does (as long as the peer stays connected —
+  # routinely indefinitely, for a WebSocket left open with nothing to say),
+  # and +Just(duration)+ gives up and answers +Timeout+ once +duration+
+  # elapses without a message.
+  #
+  # A real disconnect is still reported as +Closed+, not +Timeout+: the two
+  # are distinguishable, unlike a bare +receiveMessage+ that assumes a
+  # failed read always means the peer is gone (kexhq/kex#381).
+  #
+  # @param timeout [Duration?] how long to wait before giving up, or +None+
+  #   to wait as long as the peer stays connected
+  # @return [Result<Message, NetError>] the next data or close message, or
+  #   +Timeout+ if none arrived in time
+  #
+  # @example Prompting an otherwise-quiet client every 30 seconds
+  #   match connection.receiveMessage(timeout: Just(30.seconds)).try do
+  #     Text(text) => handleEvent(text)
+  #     _          => sendPing(connection)
+  #   end
+  #
+  # @example Being explicit that a wait has no deadline, rather than relying
+  #   on the zero-argument form's default
+  #   connection.receiveMessage(timeout: None)
+  foul receiveMessage(timeout: Duration?) -> Result<Message, NetError> = Kex.Intrinsic.NetWebSocket.receiveMessageWithin(this, timeout)
   # Returns handshake details negotiated with the server.
   #
   # @return [Session] the selected subprotocol, if any
@@ -9473,7 +10047,13 @@ make Integer do
   #
   # @example Repeating an action
   #   retries.times { |_| attemptConnection }
+  #
+  # @example Repeating an action that needs no index
+  #   3.times do
+  #     IO.printLine("hi")
+  #   end
   times :> (Integer -> Void) -> Void
+  times :> Block<Void> -> Void
   let times(block) = Kex.Intrinsic.Integer.times(this, block)
 
   # Returns the integer unchanged. Present so that code written against
@@ -9748,6 +10328,7 @@ end
 # empty. Most of the time that is a single +.or(default)+ at the end of a
 # chain.
 #
+# @example
 #   let names = ["ada", "grace"]
 #   names.first.or("nobody")        # => "ada"
 #   names.at(9).or("nobody")        # => "nobody"
@@ -9755,6 +10336,7 @@ end
 #
 # Pattern matching handles the cases that need more than a default:
 #
+# @example
 #   match config.get("port") do
 #     Just(port) => IO.printLine("listening on ${port}")
 #     None       => IO.printLine("no port configured")
@@ -9767,7 +10349,7 @@ type Optional<X> = Just(X) | None
 # Use +Result+ over +Optional+ when the *reason* for failure matters to the
 # caller. Parsing is the standard example: +"12x".to(Integer)+ answers +None+,
 # while +Integer.parse("12x")+ answers an +Error+ that says where it stopped.
-#
+# @example
 #   Integer.parse("42").or(0)     # => 42
 #   Integer.parse("4x").or(0)     # => 0
 #
@@ -9782,6 +10364,7 @@ type Result<X, E> = Ok(X) | Error(E)
 # Unlike +Result+, neither side means failure: +Either+ is for a value that is
 # legitimately one of two shapes.
 #
+# @example
 #   type Id = Either<Integer, String>
 #
 #   let describe(id: Id) -> String do
@@ -9792,19 +10375,85 @@ type Result<X, E> = Ok(X) | Error(E)
 #   end
 type Either<L, R> = Left(L) | Right(R)
 
-# Marker trait for +Optional+. Constrain a generic parameter with it when a
+# A value that may be absent. Constrain a generic parameter with it when a
 # function accepts any optional value.
+#
+# The two operations below are what make the constraint worth having: an
+# empty trait would accept a value and then let you do nothing with it, since
+# there would be no method to call. +map+ is deliberately NOT required — its
+# result type differs per implementer (+Y?+ here, +Result<Y, E>+ for
+# +Resultable+), which needs a higher-kinded parameter Kex does not have.
 trait Optionable do
+  # Answers +true+ when a value is present.
+  #
+  # The one operation an +Optionable+ type must define; +none?+ is its
+  # negation.
+  #
+  # @return [Bool] +true+ for a present value
+  #
+  # @example
+  #   Just(1).set?   # => true
+  #   None.set?      # => false
+  set? :> Bool
+
+  # Returns the wrapped value, or +default+ when there is none.
+  #
+  # The way out of the optional world, and the reason a constrained parameter
+  # is usable at all.
+  #
+  # @param default [X] the value to use when absent
+  # @return [X] the wrapped value, or +default+
+  #
+  # @example
+  #   Just(42).or(0)   # => 42
+  #   None.or(0)       # => 0
+  or :> X -> X
 end
 
-# Marker trait for +Result+. Constrain a generic parameter with it when a
-# function accepts any result value.
+# A value that either succeeded or failed with a reason. Constrain a generic
+# parameter with it when a function accepts any result value.
 trait Resultable do
+  # Answers +true+ for a success.
+  #
+  # The one operation a +Resultable+ type must define; +error?+ is its
+  # negation.
+  #
+  # @return [Bool] +true+ for +Ok+
+  #
+  # @example
+  #   Ok(1).ok?         # => true
+  #   Error("!").ok?    # => false
+  ok? :> Bool
+
+  # Returns the success value, or +default+ on failure.
+  #
+  # @param default [X] the value to use on failure
+  # @return [X] the +Ok+ value, or +default+
+  #
+  # @example
+  #   Ok(42).or(0)       # => 42
+  #   Error("!").or(0)   # => 0
+  or :> X -> X
 end
 
-# Marker trait for +Either+. Constrain a generic parameter with it when a
-# function accepts any either value.
+# One of two values, neither meaning failure. Constrain a generic parameter
+# with it when a function accepts any either value.
 trait Eitherable do
+  # Case analysis: applies +onLeft+ to a +Left+ and +onRight+ to a +Right+.
+  #
+  # The one operation an +Eitherable+ type must define — +left?+ and +right?+
+  # are both written in terms of it. A discriminator alone would let you ask
+  # which side a value is on without being able to reach it, which is why this
+  # is the requirement rather than those.
+  #
+  # @param onLeft [L -> A] applied to a +Left+
+  # @param onRight [R -> A] applied to a +Right+
+  # @return [A] whichever branch ran
+  #
+  # @example
+  #   Left(2).either(~toString, ~upperCase)      # => "2"
+  #   Right("ok").either(~toString, ~upperCase)  # => "OK"
+  either :> (L -> A) -> (R -> A) -> A
 end
 
 make Optional<X>, implement: Optionable do
@@ -10003,21 +10652,6 @@ make Result<X, E>, implement: Resultable do
   let optional(@Error(_)) = None
 end
 
-# Returns the value unchanged.
-#
-# The catch-all clause of +or+: a value that is neither an +Optional+ nor a
-# +Result+ has already succeeded, so there is nothing to fall back to. This is
-# what lets +.or(default)+ be written after a call whose return type may later
-# stop being optional, without the call site changing.
-#
-# @param value [A] any plain value
-# @return [A] the same value
-#
-# @example
-#   42.or(0)        # => 42
-#   "text".or("")   # => "text"
-let or(value, _) = value
-
 # Converts +value+ to the type +t+, or +None+ if it cannot be represented.
 #
 # +t+ is a runtime type value: write the type name itself: +String+,
@@ -10065,7 +10699,50 @@ let to(value, t) = Kex.Intrinsic.Fun.convertTo(value, t)
 #   "ff".to(Integer, radix: 10)    # => None
 let to(value, t, radix: Integer) = Kex.Intrinsic.Fun.convertTo(value, t, radix)
 
-make Either<L, R>, implement: Eitherable do
+make Either<L, R>, implement: Eitherable do
+  # Case analysis: applies +onLeft+ to a +Left+ and +onRight+ to a +Right+.
+  #
+  # The way an +Either+ is consumed without a +match+, and the operation
+  # +Eitherable+ requires. Both branches answer the same type, so the result
+  # is a plain value rather than another +Either+.
+  #
+  # @param onLeft [L -> A] applied to a +Left+
+  # @param onRight [R -> A] applied to a +Right+
+  # @return [A] whichever branch ran
+  #
+  # @example
+  #   Left(2).either(~toString, ~upperCase)       # => "2"
+  #   Right("ok").either(~toString, ~upperCase)   # => "OK"
+  #
+  # @example Collapsing an id to text
+  #   let render(id: Either<Integer, String>) -> String do
+  #     id.either({ |n| "#${n}" }, { |slug| slug })
+  #   end
+  either :> (L -> A) -> (R -> A) -> A
+  let either(@Left(l), onLeft, _) = onLeft(l)
+  let either(@Right(r), _, onRight) = onRight(r)
+
+  # Returns +true+ for a +Left+.
+  #
+  # @return [Bool]
+  #
+  # @example
+  #   Left(1).left?    # => true
+  #   Right(1).left?   # => false
+  left? :> Bool
+  let left?(@Left(_)) = true
+  let left?(@Right(_)) = false
+
+  # Returns +true+ for a +Right+. The opposite of +left?+.
+  #
+  # @return [Bool]
+  #
+  # @example
+  #   Right(1).right?   # => true
+  #   Left(1).right?    # => false
+  right? :> Bool
+  let right?(@Left(_)) = false
+  let right?(@Right(_)) = true
 end
 # Declarative command-line parsing, shared by Kex tools and applications.
 #
@@ -10144,6 +10821,15 @@ record CommandSpec do
   # What to run when this command is named.
   handler : CommandHandler
 
+  # Whether the command parses its own options. A passthrough command owns
+  # every token after its name: the outer parser stops matching options
+  # against its OWN declarations and forwards them verbatim in `arguments`,
+  # the way everything after `--` is forwarded. Without this a subcommand
+  # that runs its own OptionParser can only receive the option names the
+  # outer tool does not itself declare, and a collision is silent — the
+  # outer tool consumes the value and the subcommand sees nothing.
+  passthrough : Bool = false
+
   # The help heading this command is listed under. "" is the tool's own
   # `Commands:` block; anything else gets its own heading, in the order the
   # sections were first declared. Commands a tool discovers at runtime: a
@@ -10393,6 +11079,31 @@ make OptionConfig do
     New { commands: [...@commands, spec] }
   end
 
+  # Declares a command that parses its own options.
+  #
+  # Everything after the command's name is handed to the handler in
+  # +arguments+ untouched, including options this tool also declares. Use it
+  # for a subcommand backed by its own +OptionConfig+: without it, an option
+  # the outer tool happens to declare too is consumed here and never reaches
+  # the subcommand, with no error to say so.
+  #
+  # @param name [String] the command's name, one or more words
+  # @param usage [String] the argument shape shown in the help text
+  # @param description [String] the help-text description
+  # @param handler [CommandHandler] what to run
+  # @return [OptionConfig] the config, with the command added
+  #
+  # @example
+  #   config.passthroughCommand("docs", "<build|serve>",
+  #                             "generate documentation", ~docs)
+  let passthroughCommand(name: String, usage: String, description: String,
+                         handler: CommandHandler) -> OptionConfig do
+    let spec = CommandSpec { name: name, description: description,
+                             usage: usage, handler: handler,
+                             passthrough: true }
+    New { commands: [...@commands, spec] }
+  end
+
   # Parses +args+ into option values and leftover words, without dispatching
   # to a command.
   #
@@ -10588,6 +11299,28 @@ module OptionParser do
     end
   end
 
+  # Whether the command +arguments+ names parses its own options.
+  #
+  # +false+ when no command matches yet, so options before any command word
+  # are still this parser's to claim.
+  #
+  # @param commands [[CommandSpec]] the declared commands
+  # @param arguments [[String]] the positional words seen so far
+  # @return [Bool] +true+ when a matched command is passthrough
+  #
+  # @example
+  #   OptionParser.passthrough?(commands, ["docs", "build"])   # => true
+  #   OptionParser.passthrough?(commands, [])                  # => false
+  let passthrough?(commands: [CommandSpec], arguments: [String]) -> Bool do
+    match OptionParser.commandFor(commands, arguments) do
+      None => false
+      Just(pair) => do
+        let (command, _) = pair
+        return command.passthrough
+      end
+    end
+  end
+
   # Returns +true+ when +arguments+ begins with the words of +name+.
   #
   # The word-wise prefix test +commandFor+ matches with: +"docs build"+ opens
@@ -10682,6 +11415,15 @@ module OptionParser do
         return OptionParser.walk(options, commands, rest, values, [...arguments, argument], false)
       end
 
+      # A passthrough command owns the rest of the line. Once its words are
+      # in `arguments`, every option belongs to ITS vocabulary, so none is
+      # matched against this tool's declarations — otherwise a name both
+      # parsers declare (`tey --package` and `tey docs --package`) is eaten
+      # here and the subcommand silently never sees it.
+      if OptionParser.passthrough?(commands, arguments)
+        return OptionParser.walk(options, commands, rest, values, [...arguments, argument], false)
+      end
+
       let equals = argument.startsWith?("--") then argument.split("=") else [argument]
       let spelling = equals.first.or(argument)
       match OptionParser.findOption(options, spelling) do
@@ -11082,6 +11824,7 @@ end
 using Algebra
 using Binary
 using Blankable
+using Comparable
 using Console
 using Enumerable
 using Env
@@ -11269,6 +12012,32 @@ module Process do
   run : String -> [String] -> Result<ProcessResult, String>
   foul run(command, args) = Kex.Intrinsic.Process.run(command, args)
 
+  # Runs an executable with a time budget, and kills it if it overruns.
+  #
+  # Everything +run+ does, plus a deadline: when +timeoutMs+ milliseconds
+  # pass with the child still running, the child's process group is sent
+  # SIGTERM (then SIGKILL after a short grace) and reaped, and the call
+  # answers a timeout Error rather than the child's output. Signalling the
+  # group means forked grandchildren die with it. The budget bounds the
+  # whole call, so a hung child cannot hang the caller.
+  #
+  # A child that finishes in time answers exactly as +run+ would; a missing
+  # program still reports +executable not found+ without waiting.
+  #
+  # @param command [String] the executable to run
+  # @param args [[String]] its arguments, one per element
+  # @param timeoutMs [Integer] milliseconds before the child is killed
+  # @return [Result<ProcessResult, String>] the captured result, or why it
+  #   could not start — or that the budget ran out
+  #
+  # @example
+  #   match Process.run("sleep", ["30"], 300) do
+  #     Error(error) => IO.printLine(error)   # prints: timed out after 300ms
+  #     Ok(result) => IO.printLine(result.exitCode)
+  #   end
+  run : String -> [String] -> Integer -> Result<ProcessResult, String>
+  foul run(command, args, timeoutMs) = Kex.Intrinsic.Process.run(command, args, timeoutMs)
+
   # Runs an executable with the CALLER's stdout and stderr, so its output
   # appears as it is produced rather than in one block when it exits.
   #
@@ -11655,6 +12424,409 @@ make Reference do
   demonitor :> Void
   let demonitor = Kex.Intrinsic.Process.demonitor(this)
 end
+# Pseudorandom values: integers, floats, choices, and shuffles.
+#
+# Opt-in: nothing here is in scope until `using Random`, which brings both
+# the seeded generator and the ambient conveniences into scope at once.
+#
+#   using Random
+#
+#   main do
+#     IO.printLine(Random.between(1, 6))
+#     IO.printLine(Random.shuffle(["a", "b", "c"]))
+#   end
+#
+# Two layers, for two needs. `Rng` is a small deterministic generator with
+# explicit state: the same seed answers the same sequence on every run and
+# on both backends, which is what makes randomized code testable. `Random`
+# is the ambient convenience layer over it: each call draws fresh entropy
+# from the host, so answers differ between runs.
+#
+#   let rng = Rng.seeded(42)
+#   let (roll, next) = rng.nextBounded(6)   # 0..5, then keep going with next
+#   Random.integer(6)                       # 0..5, fresh entropy, foul
+#
+# The generator is SplitMix64: tiny, fast, and good enough for modelling,
+# games, sampling, shuffling, and randomized tests. It is NOT cryptographic:
+# its state follows directly from its output, so never use it for secrets,
+# tokens, or anything an adversary gets to see. The ambient layer draws its
+# seeds from the host's secure source, but one secure seed does not make
+# the stream that follows secure.
+
+# The state of a deterministic generator: one 64-bit word.
+#
+# A value, not a handle: every step answers a new `Rng` alongside its
+# output, and the old one keeps answering what it always did. Thread the
+# answer forward and the sequence is reproducible from its seed.
+#
+#   let rng = Rng.seeded(42)
+#   let (a, rng) = rng.nextUint64
+#   let (b, rng) = rng.nextUint64   # same `a` and `b` on every run
+#
+# Build one with +Rng.seeded+ rather than by hand: the record literal does
+# no range reduction, and every step here assumes a state inside
+# 0..2^64 - 1.
+record Rng do
+  state : Integer = 0
+end
+
+# Constructors and constants for the deterministic +Rng+. The draws
+# themselves are methods in the +make+ block below, so every one answers
+# to Uniform Function Call Syntax: +rng.nextBounded(6)+.
+module Rng do
+  # One past the largest representable state: all arithmetic here is
+  # modulo 2^64, keeping the word closed under the mixing below. Also the
+  # largest exclusive bound one 64-bit draw can cover directly.
+  #
+  # Public because the +make+ block below lives outside this module and
+  # reaches it by qualification.
+  let maxBound = 18446744073709551616
+
+  # The SplitMix64 odd increment: every addition steps the state by a
+  # different odd multiple, so even a seed of 0 walks the whole space.
+  let gamma = 0x9e3779b97f4a7c15
+
+  # The two xor-shift/multiply mixing constants.
+  let mixA = 0xbf58476d1ce4e5b9
+  let mixB = 0x94d049bb133111eb
+
+  # Builds a generator from any integer seed.
+  #
+  # The seed is reduced modulo 2^64, so negative seeds and huge ones are
+  # fine: every integer names a generator, and equal integers name the
+  # same one.
+  #
+  # @param seed [Integer] any integer; equal seeds answer equal sequences
+  # @return [Rng] the generator
+  #
+  # @example
+  #   let (word, _) = Rng.seeded(42).nextUint64
+  #   word   # => 13679457532755275413, always
+  #
+  # @example Reproducible sampling in a test
+  #   let (pick, _) = Rng.seeded(7).choice(["a", "b", "c"])
+  seeded : Integer -> Rng
+  let seeded(seed: Integer) -> Rng do
+    return Rng { state: seed.modulo(Rng.maxBound) }
+  end
+
+end
+
+# The draws on an +Rng+. Each answers its draw alongside the generator
+# that follows it, so state threads through a chain of calls. All are
+# methods, so Uniform Function Call Syntax reaches every one.
+make Rng do
+  # Draws one 64-bit unsigned word and the generator that follows it.
+  #
+  # This is the primitive everything else here is built on: the raw
+  # SplitMix64 output, uniformly spread over 0..2^64 - 1. Pure arithmetic
+  # over unbounded integers with an explicit mask, so both backends agree
+  # bit for bit with the reference C.
+  #
+  # @return [(Integer, Rng)] the word and the next generator
+  #
+  # @example
+  #   let (word, next) = Rng.seeded(0).nextUint64
+  #   word   # => 16294208416658607535
+  nextUint64 :> (Integer, Rng)
+  let nextUint64 do
+    let mask = Rng.maxBound - 1
+    let advanced = Kex.Intrinsic.Bits.and(@state + Rng.gamma, mask)
+    let spread1 = Kex.Intrinsic.Bits.xor(advanced, Kex.Intrinsic.Bits.shiftRight(advanced, 30))
+    let mixed1 = Kex.Intrinsic.Bits.and(spread1 * Rng.mixA, mask)
+    let spread2 = Kex.Intrinsic.Bits.xor(mixed1, Kex.Intrinsic.Bits.shiftRight(mixed1, 27))
+    let mixed2 = Kex.Intrinsic.Bits.and(spread2 * Rng.mixB, mask)
+    let output = Kex.Intrinsic.Bits.xor(mixed2, Kex.Intrinsic.Bits.shiftRight(mixed2, 31))
+    return (output, Rng { state: advanced })
+  end
+
+  # Draws a uniform integer in 0..bound-1 and the generator that follows.
+  #
+  # Uses rejection sampling rather than a bare remainder, so small bounds
+  # are not biased toward small answers: draws that would tilt the range
+  # are discarded and redrawn. Dies when +bound+ is not positive or does
+  # not fit in one 64-bit word.
+  #
+  # @param bound [Integer] the exclusive upper bound, 1..2^64
+  # @return [(Integer, Rng)] the draw and the next generator
+  #
+  # @example
+  #   let (roll, _) = Rng.seeded(42).nextBounded(6)   # => 0..5
+  #
+  # @example Rolling again with the threaded state
+  #   var rng = Rng.seeded(42)
+  #   let (first, advanced) = rng.nextBounded(6)
+  #   rng = advanced
+  nextBounded :> Integer -> (Integer, Rng)
+  let nextBounded(bound: Integer) -> (Integer, Rng) do
+    if bound <= 0
+      die("Rng.nextBounded: bound must be positive, got ${bound}")
+    end
+    if bound > Rng.maxBound
+      die("Rng.nextBounded: bound does not fit in 64 bits")
+    end
+    let (draw, advanced) = this.nextUint64
+    # Draws at or above this limit would make some residues likelier than
+    # others; there is always less than one bound's worth of them, so the
+    # expected number of redraws stays below two.
+    let limit = Rng.maxBound - Rng.maxBound.modulo(bound)
+    return (draw.modulo(bound), advanced) if draw < limit
+    return advanced.nextBounded(bound)
+  end
+
+  # Draws a uniform float in 0.0..1.0 and the generator that follows.
+  #
+  # Takes the top 53 bits of one word: exactly what a double's mantissa
+  # holds, so every representable value in range is reachable and 1.0
+  # itself never comes out.
+  #
+  # @return [(Float, Rng)] the draw and the next generator
+  #
+  # @example
+  #   let (unit, _) = Rng.seeded(42).nextFloat   # => 0.0..1.0
+  nextFloat :> (Float, Rng)
+  let nextFloat do
+    let (draw, advanced) = this.nextUint64
+    # Into a float by multiplication, not conversion: `* 1.0` is the
+    # typed idiom (`Duration.seconds` is built the same way).
+    let mantissa = Kex.Intrinsic.Bits.shiftRight(draw, 11) * 1.0
+    return (mantissa / 9007199254740992.0, advanced)
+  end
+
+  # Draws a fair coin flip and the generator that follows.
+  #
+  # Reads the top bit of one word rather than the bottom one, which is
+  # the bit a multiply-mixed generator decorrelates fastest.
+  #
+  # @return [(Bool, Rng)] the flip and the next generator
+  #
+  # @example
+  #   let (heads, _) = Rng.seeded(42).nextBoolean
+  nextBoolean :> (Bool, Rng)
+  let nextBoolean do
+    let (draw, advanced) = this.nextUint64
+    return (Kex.Intrinsic.Bits.shiftRight(draw, 63) == 1, advanced)
+  end
+
+  # Shuffles a list into a new order, answering the generator that follows.
+  #
+  # A selection shuffle: each position draws uniformly among the elements
+  # not yet placed, so every permutation is equally likely. The input is
+  # untouched; shuffling an empty list answers an empty list.
+  #
+  # @param items [[A]] the elements to order
+  # @return [([A], Rng)] the shuffled elements and the next generator
+  #
+  # @example
+  #   let (order, _) = Rng.seeded(42).shuffle([1, 2, 3])
+  shuffle :> [A] -> ([A], Rng)
+  let shuffle(items: [A]) -> ([A], Rng) do
+    var pool = items
+    var out: [A] = []
+    var state = this
+    while !pool.empty? do
+      let (index, advanced) = state.nextBounded(pool.count)
+      state = advanced
+      # `index` is below `pool.count` by construction, so `None` is
+      # unreachable; `die` says what the typechecker cannot.
+      let picked = match pool.at(index) do
+        Just(x) => x
+        None => die("Rng.shuffle: unreachable empty draw")
+      end
+      out.push!(picked)
+      pool = pool.take(index) + pool.drop(index + 1)
+    end
+    return (out, state)
+  end
+
+  # Draws +n+ distinct elements in random order, with the next generator.
+  #
+  # Shuffles and takes the front: uniform over every ordered +n+-subset.
+  # Asking for more than the list holds answers the whole list shuffled;
+  # asking for none answers an empty list. Dies for a negative +n+.
+  #
+  # @param items [[A]] the elements to draw from
+  # @param n [Integer] how many to draw, 0 or more
+  # @return [([A], Rng)] the drawn elements and the next generator
+  #
+  # @example
+  #   let (hand, _) = Rng.seeded(42).sample([1, 2, 3, 4, 5], 2)
+  #   hand.count   # => 2
+  sample :> [A] -> Integer -> ([A], Rng)
+  let sample(items: [A], n: Integer) -> ([A], Rng) do
+    if n < 0
+      die("Rng.sample: count must not be negative, got ${n}")
+    end
+    let (order, advanced) = this.shuffle(items)
+    return (order.take(n), advanced)
+  end
+
+  # Draws one element uniformly, or +None+ from an empty list.
+  #
+  # The only fallible draw here, and the failure carries no information
+  # worth an error type: an empty list has no element to give, whatever
+  # the seed, so +None+ is the whole story.
+  #
+  # @param items [[A]] the elements to draw from
+  # @return [(A?, Rng)] the drawn element, if any, and the next generator
+  #
+  # @example
+  #   let (pick, _) = Rng.seeded(42).choice(["a", "b", "c"])
+  #   ["a", "b", "c"].contains?(pick.or(""))   # => true
+  choice :> [A] -> (A?, Rng)
+  let choice(items: [A]) -> (A?, Rng) do
+    return (None, this) if items.empty?
+    let (index, advanced) = this.nextBounded(items.count)
+    return (items.at(index), advanced)
+  end
+end
+
+# Ambient randomness: fresh host entropy on every call.
+#
+# Each function here draws its own seed from the host's secure source and
+# runs the deterministic core above on it, so answers differ between runs
+# the way the clock differs between reads. That is why every one is
+# +foul+: the same call with the same arguments may answer differently.
+#
+# Reach for +Rng+ instead when the answers must repeat: seeded simulation,
+# property tests, anything asserting on a particular draw.
+module Random do
+  # Builds a generator from fresh host entropy.
+  #
+  # The entry point for hand-threaded flows that still vary between runs:
+  # seed once here, then draw purely from the answer.
+  #
+  # @return [Rng] a generator seeded from the host's secure source
+  #
+  # @example
+  #   var rng = Random.fresh()
+  #   let (roll, advanced) = rng.nextBounded(6)
+  #   rng = advanced
+  foul fresh() -> Rng do
+    let high = Math.floor(Kex.Intrinsic.Retry.randomUnit() * 4294967296.0)
+    let low = Math.floor(Kex.Intrinsic.Retry.randomUnit() * 4294967296.0)
+    return Rng.seeded(high * 4294967296 + low)
+  end
+
+  # Builds a generator from any integer seed. The deterministic entry:
+  # the same seed replays the same sequence, which is what tests want.
+  #
+  # @param seed [Integer] any integer; equal seeds answer equal sequences
+  # @return [Rng] the generator
+  #
+  # @example
+  #   let (roll, _) = Random.seeded(42).nextBounded(6)
+  seeded : Integer -> Rng
+  let seeded(seed: Integer) -> Rng = Rng.seeded(seed)
+
+  # Returns a uniform float in 0.0..1.0. Never answers 1.0 itself.
+  #
+  # @return [Float] the draw
+  #
+  # @example Scaling into a range
+  #   let jitter = Random.float() * maxJitter
+  foul float() -> Float do
+    let (value, _) = Random.fresh().nextFloat
+    return value
+  end
+
+  # Returns a uniform integer in 0..bound-1. Dies unless +bound+ is
+  # positive and fits in 64 bits.
+  #
+  # @param bound [Integer] the exclusive upper bound, 1..2^64
+  # @return [Integer] the draw
+  #
+  # @example
+  #   Random.integer(6)    # => 0..5, like a die minus one
+  foul integer(bound: Integer) -> Integer do
+    let (value, _) = Random.fresh().nextBounded(bound)
+    return value
+  end
+
+  # Returns a uniform integer in +low+..+high+, endpoints included. Dies
+  # unless +low+ is below +high+ and the span fits in 64 bits.
+  #
+  # @param low [Integer] the smallest answer
+  # @param high [Integer] the largest answer
+  # @return [Integer] the draw
+  #
+  # @example
+  #   Random.between(1, 6)   # => a die roll
+  foul between(low: Integer, high: Integer) -> Integer do
+    if low > high
+      die("Random.between: low must not exceed high, got ${low}..${high}")
+    end
+    return low + Random.integer(high - low + 1)
+  end
+
+  # Returns a fair coin flip.
+  #
+  # @return [Bool] the flip
+  #
+  # @example
+  #   if Random.boolean() then IO.printLine("heads") else IO.printLine("tails") end
+  foul boolean() -> Bool do
+    let (value, _) = Random.fresh().nextBoolean
+    return value
+  end
+
+  # Returns +true+ with probability +p+: a coin weighted by its argument.
+  # Dies unless +p+ is inside 0.0..1.0.
+  #
+  # @param p [Float] the chance of +true+, 0.0..1.0
+  # @return [Bool] +true+ with probability +p+
+  #
+  # @example
+  #   Random.chance?(0.25)   # => true about one call in four
+  #
+  # @example Simulating a failure rate
+  #   if Random.chance?(0.01) then Error("flaky") else Ok(send(request)) end
+  foul chance?(p: Float) -> Bool do
+    if p < 0.0 || p > 1.0
+      die("Random.chance?: chance must be inside 0.0..1.0, got ${p}")
+    end
+    return Random.float() < p
+  end
+
+  # Returns a uniformly drawn element, or +None+ from an empty list.
+  #
+  # @param items [[A]] the elements to draw from
+  # @return [A?] the drawn element, if any
+  #
+  # @example
+  #   Random.choice(["heads", "tails"])   # => Just("heads") or Just("tails")
+  foul choice(items: [A]) -> A? do
+    let (value, _) = Random.fresh().choice(items)
+    return value
+  end
+
+  # Returns +n+ distinct elements in random order. Asking for more than
+  # the list holds answers the whole list shuffled. Dies for a
+  # negative +n+.
+  #
+  # @param items [[A]] the elements to draw from
+  # @param n [Integer] how many to draw, 0 or more
+  # @return [[A]] the drawn elements
+  #
+  # @example
+  #   Random.sample(["a", "b", "c", "d"], 2)   # => two of the four
+  foul sample(items: [A], n: Integer) -> [A] do
+    let (value, _) = Random.fresh().sample(items, n)
+    return value
+  end
+
+  # Returns the elements in a uniformly random order.
+  #
+  # @param items [[A]] the elements to order
+  # @return [[A]] the shuffled elements
+  #
+  # @example
+  #   Random.shuffle([1, 2, 3, 4])   # => the four, in a random order
+  foul shuffle(items: [A]) -> [A] do
+    let (value, _) = Random.fresh().shuffle(items)
+    return value
+  end
+end
 # A span between two bounds, written +(1..10)+ or +('a'..'z')+.
 #
 # A range stores only its two endpoints and computes everything else from
@@ -12986,6 +14158,52 @@ make String, implement: Enumerable, Foldable do
   bytes :> [Byte]
   let bytes = Kex.Intrinsic.String.bytes(this)
 
+  # The storage size in bytes, without building the byte list.
+  #
+  # +bytes.count+ answers the same number by materialising every byte first,
+  # which on a megabyte payload means a million values to count them. This
+  # reads the encoded length directly.
+  #
+  # @return [Integer] the length of the UTF-8 encoding
+  #
+  # @example Text length and storage length differ
+  #   "héllo".count      # => 5
+  #   "héllo".byteSize   # => 6
+  byteSize :> Integer
+  let byteSize = Kex.Intrinsic.String.byteSize(this)
+
+  # One byte of the storage view, or +None+ when the index is out of range.
+  #
+  # This indexes the ENCODING, not the text: +byteAt+ on a multi-byte
+  # character returns one of its bytes, never the character. Use +at+ or
+  # +chars+ for the text view.
+  #
+  # @param index [Integer] a zero-based byte offset
+  # @return [Byte?] the byte, or +None+ past the end
+  #
+  # @example The two views of the same string
+  #   "héllo".byteAt(1)   # => Just(195)
+  #   "héllo".at(1)       # => Just("é")
+  #   "héllo".byteAt(99)  # => None
+  byteAt :> Integer -> Byte?
+  let byteAt(index: Integer) = Kex.Intrinsic.String.byteAt(this, index)
+
+  # A slice of the storage view, by byte offset and byte count.
+  #
+  # The range is clamped rather than refused, the way +take+ and +drop+
+  # already behave. Slicing mid-character yields a string holding partial
+  # UTF-8 — legal storage, but not text: decode it only at a boundary you
+  # know is a character boundary.
+  #
+  # @param offset [Integer] a zero-based byte offset, clamped to the string
+  # @param count [Integer] how many bytes, clamped to what remains
+  # @return [String] the bytes in that range
+  #
+  # @example Reading a length-prefixed field out of a payload
+  #   payload.bytePart(4, payload.byteSize - 4)
+  bytePart :> Integer -> Integer -> String
+  let bytePart(offset: Integer, count: Integer) = Kex.Intrinsic.String.bytePart(this, offset, count)
+
   # Splits the string into its individual characters, as one-character
   # strings.
   #
@@ -13816,6 +15034,24 @@ end
 #                                       #     TemplateParam { name: "library", type: "Bool" }]
 #   parsed.nodes                       # => [Text("Hi "), Interpolate("name"), Text("!")]
 #
+# A template file carries its host's extension ahead of `.ket`, so an editor
+# can highlight it as what it is — `README.md.ket`, `profile.html.ket`:
+#
+#   ---
+#   params: [name, library: Bool, dependencies: [Dependency]]
+#   ---
+#   # <%= name %>
+#
+#   <% if library %>
+#   A Kex library.
+#   <% else %>
+#   A Kex application.
+#   <% end %>
+#
+#   <% dependencies.map do |dep| %>
+#   - `<%= dep.name %>` ~> <%= dep.version %>
+#   <% end %>
+#
 # ## Syntax
 #
 #   <%= expr %>     interpolate (escaping is a later stage's job)
@@ -13823,10 +15059,40 @@ end
 #   <% ... %>       a Kex control region: `if`/`match` arms, block bodies, `let`
 #   <%# ... %>      comment, emits nothing
 #   <%- ... -%>     whitespace control: trims the line's leading indent before
-#                   the tag, and the newline right after it
+#                   the tag, and the newline right after it. A `<% %>` or
+#                   `<%# %>` tag standing alone on its line does this on its
+#                   own, so the markers are for a tag sharing its line with
+#                   real content
 #   <%%             a literal `<%`, for a template that generates ERB-shaped
 #                   output itself
 #
+# ## Whitespace
+#
+# A tag that emits nothing — `<% %>` and `<%# %>` — and stands alone on its
+# line takes that line with it. Only whitespace may share the line with it:
+# the indent before it and the newline after it are scaffolding, never
+# content, so a template reads the way its output does:
+#
+#   <% if dependencies.count > 0 %>
+#   ## Dependencies
+#   <% end %>
+#
+#   # => "## Dependencies\n"   — no blank line where the tags were
+#
+# The `<%- -%>` markers are for the case this does not cover: a tag sharing
+# its line with real content, where what to trim is a judgement call rather
+# than obvious.
+#
+#   Total: <%= total %> <%- if pending > 0 %>(<%= pending %> pending)<% end %>
+#
+# An interpolation is never trimmed, on its own line or not. It stands in for
+# content, so the whitespace around it is content too:
+#
+#   <%= greeting %>
+#   <%= name %>
+#
+#   # => "Hi\nAda\n"          — both newlines survive
+#
 # ## Frontmatter
 #
 # A template file may open with a `---` line, generic `key: value` tags up to
@@ -13877,10 +15143,13 @@ type Node = Text(String)
 type Tag = Scalar(String)
          | Tags([String])
 
-# Why a template's text could not be scanned, and where.
+# Why a template's text could not be scanned or rendered, and where (or,
+# for `render`/`renderParsed`, what stopped it).
 type TemplateError = UnterminatedTag(Integer)
                     | UnterminatedFrontmatter
                     | MalformedFrontmatterLine(String)
+                    | UndefinedVariable(String)
+                    | UnsupportedControl(String)
 
 # One entry from a `params: [...]` frontmatter list: a name, and its
 # optional `: Type` annotation. `type` is raw text: `""` for a bare name,
@@ -13936,6 +15205,14 @@ end
 # @example
 #   Template.scan("Hi <%= name %>!").map(~nodes)
 #   # => Ok([Text("Hi "), Interpolate("name"), Text("!")])
+#
+# @example A control tag on a line of its own leaves no blank line behind
+#   Template.scan("<% if admin %>\nWelcome back.\n<% end %>\n").try.nodes
+#   # => [Control("if admin"), Text("Welcome back.\n"), Control("end")]
+#
+# @example Where the template broke, as a position in the source
+#   Template.scan("Hi <%= name")
+#   # => Error(UnterminatedTag(6))
 let scan(source: String) -> Result<Parsed, TemplateError> do
   let cursor = Input { input: source }
   let (frontmatter, afterFrontmatter) = scanFrontmatter(cursor).try
@@ -13943,6 +15220,107 @@ let scan(source: String) -> Result<Parsed, TemplateError> do
   Ok(Parsed { frontmatter: frontmatter, nodes: nodes })
 end
 
+# Escapes the five characters HTML gives special meaning: what `Template.html`
+# (kexhq/kex#171 M3) wraps every `<%= %>` hole in, so an interpolated value
+# can never inject markup or break out of an attribute. `<%== %>` opts out.
+#
+# `&` first, deliberately: escaping it after `<`/`>` would re-escape the
+# `&` those just introduced (`&lt;` -> `&amp;lt;`).
+#
+# @param text [String] the text to escape
+# @return [String] the same text, HTML-safe
+#
+# @example
+#   Template.escapeHtml("<b>Tom & Jerry</b>")
+#   # => "&lt;b&gt;Tom &amp; Jerry&lt;/b&gt;"
+let escapeHtml(text: String) -> String do
+  text.replace("&", "&amp;")
+      .replace("<", "&lt;")
+      .replace(">", "&gt;")
+      .replace("\"", "&quot;")
+      .replace("'", "&#39;")
+end
+
+# Renders an already-scanned template's holes from a runtime `context`,
+# `<%= %>` HTML-escaped and `<%== %>` raw, same as `Template.html`/
+# `Template.text` do at compile time — but there is no runtime evaluator for
+# `<% ... %>` CONTROL regions here. Evaluating a `<% if … %>`/`<% match … %>`/
+# a block loop chosen at run time means evaluating arbitrary Kex source
+# picked at run time, which is its own design decision (kexhq/kex#335) and
+# not what this covers: a template using one reports `UnsupportedControl`
+# with the region's text rather than silently doing nothing with it, so the
+# gap is loud, not a template that quietly renders wrong.
+#
+# This is for what `Template.html(Kex.embed(path))` cannot do at all — a
+# template file chosen while the program is running, not baked in at compile
+# time — for the shape of template that does not need control flow: a
+# subject line, a notification body, a plain-text substitution. A template
+# with real control flow still needs compiling in (`Kex.embed`), or a hole
+# it does not have: turning `Parsed#nodes` into a fuller runtime evaluator is
+# further work this only lays the groundwork for.
+#
+# `<%= %>`/`<%== %>` names are looked up VERBATIM (trimmed of surrounding
+# whitespace) in `context` — `dep.name` in a template needs a `"dep.name"`
+# key, not field access into a `dep` key's value. Splitting a dotted hole
+# into a real field path is, again, further work.
+#
+# @param parsed [Parsed] a template already scanned by `Template.scan`
+# @param context [{String: String}] a value for every `<%= %>`/`<%== %>`
+#   hole the template uses, keyed by the hole's exact (trimmed) text
+# @return [Result<String, TemplateError>] the rendered text, or why not
+#
+# @example
+#   let parsed = Template.scan("Hi <%= name %>!").try
+#   Template.renderParsed(parsed, { "name": "<Ada>" })
+#   # => Ok("Hi &lt;Ada&gt;!")
+#
+# @example A hole `context` does not cover
+#   Template.renderParsed(Template.scan("<%= missing %>").try, {})
+#   # => Error(UndefinedVariable("missing"))
+#
+# @example Control flow is refused, not silently skipped
+#   Template.renderParsed(Template.scan("<% if x %>y<% end %>").try, {})
+#   # => Error(UnsupportedControl("if x"))
+let renderParsed(parsed: Parsed, context: {String: String}) -> Result<String, TemplateError> do
+  var out = ""
+  var i = 0
+  loop do
+    break if i >= parsed.nodes.count
+    match parsed.nodes.at(i).or(Text("")) do
+      Text(text) => out = "${out}${text}"
+      Interpolate(name) => do
+        let value = context.get(name.trim)
+        return Error(UndefinedVariable(name.trim)) if value == None
+        out = "${out}${escapeHtml(value.or(""))}"
+      end
+      InterpolateRaw(name) => do
+        let value = context.get(name.trim)
+        return Error(UndefinedVariable(name.trim)) if value == None
+        out = "${out}${value.or("")}"
+      end
+      Comment(_) => ()
+      Control(body) => return Error(UnsupportedControl(body))
+    end
+    i = i + 1
+  end
+  Ok(out)
+end
+
+# `Template.scan(source).try` then `renderParsed` — see its doc comment for
+# what this does and, as importantly, what it refuses to do.
+#
+# @param source [String] the template's full text, scanned fresh
+# @param context [{String: String}] see `renderParsed`
+# @return [Result<String, TemplateError>] the rendered text, or why not
+#
+# @example
+#   Template.render("Hi <%= name %>!", { "name": "Ada" })
+#   # => Ok("Hi Ada!")
+let render(source: String, context: {String: String}) -> Result<String, TemplateError> do
+  let parsed = scan(source).try
+  renderParsed(parsed, context)
+end
+
 private do
   # True when `cursor` sits at the very start of the input and that line is
   # exactly `---`: the only place a frontmatter block may open.
@@ -13972,17 +15350,21 @@ private do
   # A cursor advanced to the next `\n` (not past it), and the text skipped.
   #
   # Hand-rolled rather than `Input#takeWhile`: see `scanText`'s comment on why.
+  #
+  # Tracks the run's start position and slices once at the end, rather than
+  # building it one `Char` at a time with `push!`: pushing to a `var` list
+  # rebinds it to a freshly copied list every call (kexhq/kex#379), so a
+  # character-at-a-time accumulation of an N-character line cost O(N^2), not
+  # O(N). One slice is O(N) total regardless of how many lines are scanned.
   let scanLine(cursor: Input) -> (String, Input) do
     var cur = cursor
-    var chars: [Char] = []
+    let start = cur.pos
     loop do
       break if cur.peek == None
       break if cur.peek == Just('\n')
-      let Just(ch) = cur.peek
-      chars.push!(ch)
       cur.advance!
     end
-    (chars.join(""), cur)
+    (cur.input.chars.drop(start).take(cur.pos - start).join(""), cur)
   end
 
   # A line's text with any trailing `\r` dropped, for a source that mixes
@@ -14113,23 +15495,31 @@ private do
   # collides with `List#takeWhile`, and calling it through an `Input` receiver
   # sends overload resolution down the wrong path (`json.kex`'s own scanners
   # hit the same thing and avoid it the same way).
+  #
+  # Tracks each run's start position and slices it out whole, rather than
+  # pushing one `Char` at a time: see `scanLine`'s comment on why that was
+  # quadratic (kexhq/kex#379). `<%%` still needs a per-occurrence split (it
+  # folds three input characters into two output ones), but that split is as
+  # rare as `<%%` itself, not once per character of ordinary text.
   let scanText(cursor: Input) -> (String, Input) do
     var cur = cursor
-    var chars: [Char] = []
+    var pieces: [String] = []
+    var runStart = cur.pos
     loop do
       break if cur.peek == None
       break if atTagOpen?(cur)
       if cur.peek == Just('<') && cur.peekAt(1) == Just('%') && cur.peekAt(2) == Just('%')
-        chars.push!('<')
-        chars.push!('%')
+        pieces.push!(cur.input.chars.drop(runStart).take(cur.pos - runStart).join(""))
+        pieces.push!("<%")
         cur.advanceBy!(3)
+        runStart = cur.pos
       else
-        let Just(ch) = cur.peek
-        chars.push!(ch)
         cur.advance!
+        ()
       end
     end
-    (chars.join(""), cur)
+    pieces.push!(cur.input.chars.drop(runStart).take(cur.pos - runStart).join(""))
+    (pieces.join(""), cur)
   end
 
   # Strips trailing spaces and tabs (not newlines): the indentation a `<%-`
@@ -14145,6 +15535,58 @@ private do
     chars.join("")
   end
 
+  # A tag that emits nothing of its own. Only these can have their whole
+  # line disappear: a tag that produces output stands in real content, so
+  # the whitespace around it is content too.
+  let silent?(node: Node) -> Bool do
+    match node do
+      Control(_) => true
+      Comment(_) => true
+      _          => false
+    end
+  end
+
+  # Whether the text scanned before a tag leaves the cursor at the start of
+  # a line — nothing but spaces and tabs since the last newline. `prior`
+  # answers it for text that holds no newline at all, carrying forward what
+  # was true before that text: two tags separated by spaces alone are both
+  # still at the start of their line.
+  let atLineStart?(text: String, prior: Bool) -> Bool do
+    let after = text.split("\n").last
+    match after do
+      Just(tail) => text.contains?("\n") then blank?(tail) else prior && blank?(text)
+      None       => prior
+    end
+  end
+
+  # True for text of spaces and tabs alone, the empty string included.
+  let blank?(text: String) -> Bool do
+    text.chars.all? { |ch| ch == ' ' || ch == '\t' }
+  end
+
+  # True when nothing but spaces and tabs stands between `cursor` and the end
+  # of its line. The right half of what makes a tag stand alone; end of input
+  # counts, since there is no trailing content there either.
+  let blankToLineEnd?(cursor: Input) -> Bool do
+    var cur = cursor
+    loop do
+      break if cur.peek != Just(' ') && cur.peek != Just('\t')
+      cur.advance!
+    end
+    cur.peek == None || cur.peek == Just('\n') || cur.peek == Just('\r')
+  end
+
+  # A cursor advanced past the rest of a blank line, its newline included.
+  # What a standalone tag's own line needs once the tag itself is scanned.
+  let skipBlankLineRest(cursor: Input) -> Input do
+    var cur = cursor
+    loop do
+      break if cur.peek != Just(' ') && cur.peek != Just('\t')
+      cur.advance!
+    end
+    skipOneNewline(cur)
+  end
+
   # `<%=`, `<%==`, `<%#`, or plain `<%`, which kind of region this is, and
   # the cursor past the marker.
   let classifyTag(cursor: Input) -> (String, Input) do
@@ -14161,16 +15603,17 @@ private do
 
   # Reads a tag's body up to its closer, `%>` or `-%>`. Answers the raw text,
   # whether the closer trims the following newline, and the cursor past it.
+  #
+  # Slices the body out once at the closer, rather than pushing one `Char` at
+  # a time — see `scanLine`'s comment on why that was quadratic
+  # (kexhq/kex#379).
   let scanTagBody(cursor: Input) -> Result<(String, Bool, Input), TemplateError> do
     let start = cursor.pos
     var cur = cursor
-    var chars: [Char] = []
     loop do
       return Error(UnterminatedTag(start)) if cur.peek == None
-      return Ok((chars.join(""), true, cur.advanceBy(3))) if cur.peek == Just('-') && cur.peekAt(1) == Just('%') && cur.peekAt(2) == Just('>')
-      return Ok((chars.join(""), false, cur.advanceBy(2))) if cur.peek == Just('%') && cur.peekAt(1) == Just('>')
-      let Just(ch) = cur.peek
-      chars.push!(ch)
+      return Ok((cur.input.chars.drop(start).take(cur.pos - start).join(""), true, cur.advanceBy(3))) if cur.peek == Just('-') && cur.peekAt(1) == Just('%') && cur.peekAt(2) == Just('>')
+      return Ok((cur.input.chars.drop(start).take(cur.pos - start).join(""), false, cur.advanceBy(2))) if cur.peek == Just('%') && cur.peekAt(1) == Just('>')
       cur.advance!
     end
   end
@@ -14200,9 +15643,16 @@ private do
   end
 
   # Scans the template body (everything after any frontmatter) into nodes.
+  #
+  # A tag that emits nothing and stands alone on its line takes that line
+  # with it, without being asked: `<% end %>` on a line of its own leaves no
+  # blank line behind, the same as `<%- end -%>`. That is what a template
+  # author means every time, so the trim markers are for the other case — a
+  # tag with real content beside it on the line.
   let scanBody(cursor: Input) -> Result<([Node], Input), TemplateError> do
     var cur = cursor
     var nodes: [Node] = []
+    var lineStart = true
     loop do
       let (text, afterText) = scanText(cur)
       if afterText.peek == None
@@ -14212,12 +15662,20 @@ private do
         return Ok((nodes, afterText))
       end
       let (tag, afterTag) = scanTag(afterText).try
-      let keptText = tag.leftTrim then trimTrailingIndent(text) else text
+      let alone = silent?(tag.node) && atLineStart?(text, lineStart) && blankToLineEnd?(afterTag)
+      let keptText = (tag.leftTrim || alone) then trimTrailingIndent(text) else text
       if !keptText.empty?
         nodes.push!(Text(keptText))
       end
       nodes.push!(tag.node)
-      cur = tag.rightTrim then skipOneNewline(afterTag) else afterTag
+      cur = if alone
+        skipBlankLineRest(afterTag)
+      elif tag.rightTrim
+        skipOneNewline(afterTag)
+      else
+        afterTag
+      end
+      lineStart = alone || tag.rightTrim
     end
   end
 end
@@ -16842,6 +18300,24 @@ make Bool, implement: Truthyable do
   truthy? :> Bool
   let truthy? = this
 
+  # Returns the negation of this boolean.
+  #
+  # +!flag+ says the same thing, and is the spelling to reach for when the
+  # value is already to hand. This one exists for the position +!+ cannot
+  # take: the end of a chain, where what is being negated is whatever the
+  # chain just produced. +falsy?+ answers the same question for any
+  # +Truthyable+ value; +not+ is the one that both takes and answers a +Bool+.
+  #
+  # @return [Bool] +false+ for +true+, and +true+ for +false+
+  #
+  # @example
+  #   true.not    # => false
+  #   false.not   # => true
+  #
+  # @example At the end of a chain
+  #   book.borrowed?.not
+  not :> Bool
+  let not = !this
 end
 
 make Integer, implement: Truthyable do
@@ -18502,6 +19978,21 @@ module Query do
   from : [(String, String?)] -> Query
   let from(entries) = Query { entries: entries }
 
+  # Builds a query from unordered key/value pairs, for the common case where
+  # every key is used once. A `Map` cannot hold "tag" twice, so — unlike the
+  # list form above — repeating a key here does not add a second field; it
+  # silently keeps only one value for it. Reach for the ordered list form
+  # instead of this one for anything that legitimately repeats a key, such
+  # as `?tag=kex&tag=beam`.
+  #
+  # @param entries [Map<String, String?>] decoded key/value pairs, one per key
+  # @return [Query] the query
+  #
+  # @example Building filters that each use a distinct key
+  #   Query.from({ "sort": Just("name"), "debug": None })
+  from : Map<String, String?> -> Query
+  let from(entries: Map<String, String?>) = Query { entries: entries.entries }
+
   # Parses generic URI query encoding; ++ remains a literal plus.
   #
   # @param text [String] encoded query text without the leading question mark
@@ -18524,6 +20015,21 @@ module Form do
   from : [(String, String)] -> Form
   let from(entries) = Kex.Intrinsic.URI.formFrom(entries)
 
+  # Builds a form from unordered key/value pairs, for the common case where
+  # every field name is used once. A `Map` cannot hold a name twice, so —
+  # unlike the list form above — a repeated field name here does not add a
+  # second entry; it silently keeps only one value for it. Reach for the
+  # ordered list form instead of this one for anything that legitimately
+  # repeats a field name, such as several same-named checkboxes.
+  #
+  # @param entries [Map<String, String>] decoded form fields, one per name
+  # @return [Form] the form
+  #
+  # @example Preparing a login request body
+  #   Form.from({ "email": email, "password": password }).encode
+  from : Map<String, String> -> Form
+  let from(entries: Map<String, String>) = Kex.Intrinsic.URI.formFrom(entries.entries)
+
   # Parses form encoding where ++ represents a space.
   #
   # @param text [String] an +application/x-www-form-urlencoded+ body