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

package/dist/kex_repl_wasm.data

@@ -1108,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`.
@@ -2481,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:
@@ -4073,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.
@@ -4919,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
@@ -4953,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
@@ -5750,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.
@@ -6310,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.
   #
@@ -6702,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]]
@@ -7894,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
@@ -8442,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
@@ -8760,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.
 #
@@ -8783,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.
   #
@@ -8811,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
@@ -8839,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
@@ -9564,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
@@ -11935,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
@@ -14251,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,
@@ -14346,6 +15241,86 @@ let escapeHtml(text: String) -> String do
       .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.
@@ -14375,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
@@ -14516,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 `<%-`
@@ -14616,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
@@ -18990,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
@@ -19012,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