@kexhq/kex 0.4.0-alpha.2-dev.20d979e → 0.4.0-alpha.2-dev.db076ab

package/dist/kex_repl_wasm.data

@@ -1041,6 +1041,7 @@ record Policy do
   multiplier : Float
   maximumDelay : Duration
   maximumElapsed : Duration? = None
+  jitterFraction : Float = 0.0
 end
 
 # Decides whether an application error is eligible for another attempt.
@@ -1055,14 +1056,15 @@ type Sleeper = Duration -> Void
 # @param maximumAttempts [Integer] total calls including the first
 # @param delay [Duration] delay before each subsequent call
 # @return [Policy] the retry schedule
-# @example +Retry.fixed(3, Duration.milliseconds(100))+.
+# @example +Retry.fixed(3, 100.milliseconds)+.
 fixed : Integer -> Duration -> Policy
 let fixed(maximumAttempts, delay) = Policy {
   maximumAttempts: maximumAttempts,
   initialDelay: delay,
   multiplier: 1.0,
   maximumDelay: delay,
-  maximumElapsed: None
+  maximumElapsed: None,
+  jitterFraction: 0.0
 }
 
 # Builds a doubling backoff capped at +maximumDelay+.
@@ -1077,7 +1079,8 @@ let exponential(maximumAttempts, initialDelay, maximumDelay) = Policy {
   initialDelay: initialDelay,
   multiplier: 2.0,
   maximumDelay: maximumDelay,
-  maximumElapsed: None
+  maximumElapsed: None,
+  jitterFraction: 0.0
 }
 
 make Policy do
@@ -1089,13 +1092,26 @@ make Policy do
   #
   # @param maximumElapsed [Duration] maximum cumulative scheduled delay
   # @return [Policy] a copied policy with the elapsed bound
-  # @example +Retry.fixed(5, Duration.seconds(1)).withMaximumElapsed(Duration.seconds(2))+.
+  # @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)
+    maximumElapsed: Just(maximumElapsed),
+    jitterFraction: @jitterFraction
+  }
+
+  # 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+.
+  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
 
@@ -1108,7 +1124,7 @@ end
 # @param operation [Block<Result<X,E>>] a fresh attempt
 # @return [Result<X,E>] the first success or final failure
 run : Policy -> Block<Result<X, E>> -> Result<X, E>
-foul run(policy, operation) = runWith(policy, { |error| true }, { |delay| Task.sleep(delay) }, operation)
+foul run(policy, operation) = runWithRandom(policy, { |error| true }, { |delay| Task.sleep(delay) }, { Kex.Intrinsic.Retry.randomUnit() }, operation)
 
 # Runs with an application-specific error predicate.
 #
@@ -1121,7 +1137,7 @@ foul run(policy, operation) = runWith(policy, { |error| true }, { |delay| Task.s
 # @return [Result<X,E>] the first success or final/non-retryable failure
 # @example +Retry.run(policy, { |error| error.retryable? }, do request() end)+
 run : Policy -> Predicate<E> -> Block<Result<X, E>> -> Result<X, E>
-foul run(policy, predicate, operation) = runWith(policy, predicate, { |delay| Task.sleep(delay) }, operation)
+foul run(policy, predicate, operation) = runWithRandom(policy, predicate, { |delay| Task.sleep(delay) }, { Kex.Intrinsic.Retry.randomUnit() }, operation)
 
 # Runs with injected error classification and sleeping.
 #
@@ -1134,9 +1150,16 @@ foul run(policy, predicate, operation) = runWith(policy, predicate, { |delay| Ta
 # @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) = attempt(policy, predicate, sleeper, operation, 1, policy.initialDelay, Duration.seconds(0))
+foul runWith(policy, predicate, sleeper, operation) = runWithRandom(policy, predicate, sleeper, { 0.5 }, operation)
 
-foul attempt(policy: Policy, predicate: Predicate<E>, sleeper: Sleeper, operation: Block<Result<X, E>>, number: Integer, delay: Duration, elapsed: Duration) -> Result<X, E> do
+# 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)
@@ -1144,7 +1167,10 @@ foul attempt(policy: Policy, predicate: Predicate<E>, sleeper: Sleeper, operatio
       if number >= policy.maximumAttempts || !predicate(error)
         return Error(error)
       end
-      let nextElapsed = Duration { seconds: elapsed.seconds + delay.seconds }
+      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
         None => true
         Just(maximum) => nextElapsed.seconds <= maximum.seconds
@@ -1152,10 +1178,10 @@ foul attempt(policy: Policy, predicate: Predicate<E>, sleeper: Sleeper, operatio
       if !withinElapsed
         return Error(error)
       end
-      sleeper(delay)
+      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, operation, number + 1, bounded, nextElapsed)
+      return attempt(policy, predicate, sleeper, random, operation, number + 1, bounded, nextElapsed)
     end
   end
 end
@@ -1181,6 +1207,10 @@ module Retry do
   # 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.
 #
@@ -7759,6 +7789,22 @@ record CacheOptions do
   negativeTtl : Duration = Duration.seconds(30)
 end
 
+# One DNS server used by a custom resolver.
+record Nameserver do
+  address : Net.IP.Address
+  port : Net.Port
+end
+
+# Isolated resolver configuration. An empty search list only queries the name
+# as written; search domains are tried in order for single-label names.
+record ResolverOptions do
+  cache : CacheOptions = CacheOptions {}
+  nameservers : [Nameserver]
+  search : [Name] = []
+  retries : Integer = 2
+  timeout : Duration = 2.seconds
+end
+
 # Lifetime cache counters. +clear+ empties entries but keeps these counters.
 record CacheStatistics do
   entries : Integer
@@ -7789,6 +7835,12 @@ module Resolver do
   # @param cache [CacheOptions] entry and TTL limits
   # @return [Result<Resolver, NetError>] a resolver, or +Parse+
   foul system(cache: CacheOptions) -> Result<Resolver, NetError> = Kex.Intrinsic.NetDNS.resolver(cache)
+  # Opens an isolated resolver with typed nameservers and query bounds.
+  # @param options [ResolverOptions] nameservers, search domains, retry count,
+  #   per-query timeout, and cache bounds
+  # @return [Result<Resolver, NetError>] a resolver, or +Parse+
+  # @example +Resolver.custom(ResolverOptions { nameservers: [Nameserver { address: Net.IP.Address.parse("127.0.0.1").try, port: Net.Port.from(53).try }], timeout: 100.milliseconds }).try+
+  foul custom(options: ResolverOptions) -> Result<Resolver, NetError> = Kex.Intrinsic.NetDNS.resolverWith(options)
 end
 
 make Resolver do
@@ -8029,7 +8081,8 @@ module Client do
   open : Result<Client, NetError>
   foul open() = Kex.Intrinsic.NetHTTPClient.open(ClientOptions {})
   # Opens an explicit client owning the supplied pool policy.
-  foul open(options: ClientOptions) -> Result<Client, NetError> = Kex.Intrinsic.NetHTTPClient.open(options)
+  open : ClientOptions -> Result<Client, NetError>
+  foul open(options) = Kex.Intrinsic.NetHTTPClient.open(options)
 end
 
 make Client do
@@ -8288,6 +8341,21 @@ module TCP do
     host : String
     port : Net.Port
   end
+  record ConnectOptions do
+    connectTimeout : Duration = 10.seconds
+    noDelay? : Bool = true
+    keepAlive? : Bool = true
+    sendBuffer : Integer = 0
+    receiveBuffer : Integer = 0
+  end
+  record ListenOptions do
+    backlog : Integer = 128
+    reuseAddress? : Bool = true
+    noDelay? : Bool = true
+    keepAlive? : Bool = true
+    sendBuffer : Integer = 0
+    receiveBuffer : Integer = 0
+  end
 
   module Endpoint do
     # @return [Endpoint] an endpoint using +name+ exactly as supplied
@@ -8309,18 +8377,24 @@ module TCP do
   # @example +TCP.connect(TCP.Endpoint.host("example.test", Port.from(80).try))+.
   connect : Endpoint -> Result<TCPConnection, NetError>
   foul connect(endpoint) = Kex.Intrinsic.NetTCP.connect(endpoint)
+  connect : Endpoint -> ConnectOptions -> Result<TCPConnection, NetError>
+  foul connect(endpoint, options) = Kex.Intrinsic.NetTCP.connectWith(endpoint, options)
   # Binds and starts listening. Port zero selects an ephemeral local port.
   # @return [Result<TCPListener, NetError>] a listener or +Connect+
   # @example +TCP.listen(TCP.Endpoint.loopback(Port.from(0).try))+.
   listen : Endpoint -> Result<TCPListener, NetError>
   foul listen(endpoint) = Kex.Intrinsic.NetTCP.listen(endpoint)
+  listen : Endpoint -> ListenOptions -> Result<TCPListener, NetError>
+  foul listen(endpoint, options) = Kex.Intrinsic.NetTCP.listenWith(endpoint, options)
 
   # Sends every byte or reports the failure and transfer progress.
   foul sendAll(connection: TCPConnection, data: Binary) -> Result<Integer, NetError> = Kex.Intrinsic.NetTCP.sendAll(connection, data)
   # Receives one bounded chunk; EOF is reported as +Closed+.
   foul receiveChunk(connection: TCPConnection, limit: Integer) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveChunk(connection, limit)
+  foul receiveChunk(connection: TCPConnection, limit: Integer, timeout: Duration) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveChunkWithin(connection, limit, timeout)
   # Receives exactly +count+ bytes or returns a typed EOF/timeout failure.
   foul receiveExactly(connection: TCPConnection, count: Integer) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveExactly(connection, count)
+  foul receiveExactly(connection: TCPConnection, count: Integer, timeout: Duration) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveExactlyWithin(connection, count, timeout)
   # Receives through the first +delimiter+ without exceeding +limit+ bytes.
   #
   # The delimiter is included in the returned bytes. An empty delimiter is a
@@ -8328,12 +8402,15 @@ module TCP do
   #
   # @example +connection.receiveUntil("\r\n\r\n".to(Binary).try, 65536).try+
   foul receiveUntil(connection: TCPConnection, delimiter: Binary, limit: Integer) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveUntil(connection, delimiter, limit)
+  foul receiveUntil(connection: TCPConnection, delimiter: Binary, limit: Integer, timeout: Duration) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveUntilWithin(connection, delimiter, limit, timeout)
   # Receives through a newline without exceeding +limit+ bytes.
   foul receiveLine(connection: TCPConnection, limit: Integer) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveLine(connection, limit)
+  foul receiveLine(connection: TCPConnection, limit: Integer, timeout: Duration) -> Result<Binary, NetError> = Kex.Intrinsic.NetTCP.receiveLineWithin(connection, limit, timeout)
   # Half-closes the write side while leaving reads available.
   foul shutdownWrite(connection: TCPConnection) -> Result<Void, NetError> = Kex.Intrinsic.NetTCP.shutdownWrite(connection)
   # Waits for and returns the next connection.
   foul accept(listener: TCPListener) -> Result<TCPConnection, NetError> = Kex.Intrinsic.NetTCP.accept(listener)
+  foul accept(listener: TCPListener, timeout: Duration) -> Result<TCPConnection, NetError> = Kex.Intrinsic.NetTCP.acceptWithin(listener, timeout)
   # Idempotently closes a connected stream.
   foul close(connection: TCPConnection) -> Void = Kex.Intrinsic.NetTCP.close(connection)
   # Idempotently closes a listener and releases its port.
@@ -8373,6 +8450,14 @@ module UDP do
     source : Endpoint
     data : Binary
   end
+  # Curated socket policy. Broadcast is opt-in. The receive timeout applies to
+  # each +receiveFrom+ call; multicast TTL is bounded to the IP hop-limit range.
+  record BindOptions do
+    broadcast? : Bool = false
+    multicastTtl : Integer = 1
+    multicastLoopback? : Bool = true
+    receiveTimeout : Duration = 30.seconds
+  end
   module Endpoint do
     # @return [Endpoint] an endpoint using +name+ exactly as supplied
     host : String -> Net.Port -> Endpoint
@@ -8387,6 +8472,9 @@ module UDP do
   # Binds a datagram socket. Port zero selects an ephemeral local port.
   bind : Endpoint -> Result<Socket, NetError>
   foul bind(endpoint) = Kex.Intrinsic.NetUDP.bind(endpoint)
+  # Binds with explicit broadcast, multicast, and receive-timeout policy.
+  bind : Endpoint -> BindOptions -> Result<Socket, NetError>
+  foul bind(endpoint, options) = Kex.Intrinsic.NetUDP.bindWith(endpoint, options)
 
   # Sends one complete datagram and returns its byte count.
   foul sendTo(socket: Socket, endpoint: Endpoint, data: Binary) -> Result<Integer, NetError> = Kex.Intrinsic.NetUDP.sendTo(socket, endpoint, data)
@@ -8398,6 +8486,11 @@ module UDP do
   foul closed?(socket: Socket) -> Bool = Kex.Intrinsic.NetUDP.closed?(socket)
   # Returns the bound endpoint, including an ephemeral assigned port.
   foul localAddress(socket: Socket) -> Result<Endpoint, NetError> = Kex.Intrinsic.NetUDP.localAddress(socket)
+  # Joins an IPv4 multicast group on the selected local interface. The group
+  # must be multicast and the interface must be an IPv4 address.
+  foul joinMulticast(socket: Socket, group: Net.IP.Address, interface: Net.IP.Address) -> Result<Void, NetError> = Kex.Intrinsic.NetUDP.joinMulticast(socket, group, interface)
+  # Leaves a membership previously joined with the same group and interface.
+  foul leaveMulticast(socket: Socket, group: Net.IP.Address, interface: Net.IP.Address) -> Result<Void, NetError> = Kex.Intrinsic.NetUDP.leaveMulticast(socket, group, interface)
 
 end
 
@@ -8418,6 +8511,16 @@ module Unix do
   record Address do
     path : String
   end
+  record ConnectOptions do
+    connectTimeout : Duration = 10.seconds
+    receiveTimeout : Duration = 30.seconds
+  end
+  record ListenOptions do
+    backlog : Integer = 128
+    removeStale? : Bool = false
+    acceptTimeout : Duration = 30.seconds
+    receiveTimeout : Duration = 30.seconds
+  end
   module Address do
     # Validates a nonempty absolute Unix-domain socket path.
     # @return [Result<Address, NetError>] the address, or +Parse+
@@ -8427,9 +8530,15 @@ module Unix do
   # Connects to a filesystem-domain listener.
   connect : Address -> Result<UnixConnection, NetError>
   foul connect(address) = Kex.Intrinsic.NetUnix.connect(address)
+  connect : Address -> ConnectOptions -> Result<UnixConnection, NetError>
+  foul connect(address, options) = Kex.Intrinsic.NetUnix.connectWith(address, options)
   # Binds a new path; an existing filesystem entry is never removed implicitly.
   listen : Address -> Result<UnixListener, NetError>
   foul listen(address) = Kex.Intrinsic.NetUnix.listen(address)
+  # With +removeStale?+, only an existing filesystem socket is removed;
+  # regular files, directories, and other path types are always preserved.
+  listen : Address -> ListenOptions -> Result<UnixListener, NetError>
+  foul listen(address, options) = Kex.Intrinsic.NetUnix.listenWith(address, options)
 
   # Sends every byte and returns the count.
   foul sendAll(connection: UnixConnection, data: Binary) -> Result<Integer, NetError> = Kex.Intrinsic.NetUnix.sendAll(connection, data)
@@ -11945,6 +12054,31 @@ make String, implement: Enumerable, Foldable do
   length :> Integer
   let length = Kex.Intrinsic.List.length(this)
 
+  # Returns the number of user-perceived characters — extended grapheme
+  # clusters (Unicode UAX #29) — which is not always +count+.
+  #
+  # +count+ answers the codepoint count, and most text is one codepoint per
+  # grapheme cluster, so the two usually agree. They part ways for a base
+  # character combined with a following mark, an emoji built from more than
+  # one codepoint, and `"\r\n"`, which is one grapheme cluster over two
+  # codepoints — reach for +graphemeCount+ over +count+ wherever "how many
+  # characters does a person see" is the question, such as sizing text for
+  # display or truncating it at a boundary a reader would recognize.
+  #
+  # @return [Integer] the grapheme cluster count
+  #
+  # @example
+  #   "hello".graphemeCount   # => 5, same as count
+  #   "\r\n".graphemeCount    # => 1 ("\r\n".count is 2 -- a CR codepoint and an LF codepoint)
+  #
+  # @example A base character plus a combining mark
+  #   let acute = String.fromCodepoint(0x301).or("")     # combining acute accent
+  #   let e = "e" + acute
+  #   e.count           # => 2 (two codepoints: 'e' and the combining mark)
+  #   e.graphemeCount   # => 1 (one character on screen)
+  graphemeCount :> Integer
+  let graphemeCount = Kex.Intrinsic.String.graphemeCount(this)
+
   # Returns +true+ when the string has no characters.
   #
   # Note that a string of spaces is not empty — use +blank?+ from the
@@ -12876,6 +13010,431 @@ warnBetween : Integer -> Integer -> String -> Issue
 let warnBetween(start, finish, message) do
   Warn(Between(start, finish), message)
 end
+# An ERB-shaped template scanner: template text in, a template AST out.
+#
+# Opt-in — nothing here is in scope until `using Template`.
+#
+# This is the scanning stage only (see the Template proposal for the fuller
+# design): it turns template source into a flat list of +Node+s — plain text,
+# and the four kinds of `<% %>` region — plus whatever frontmatter tags sit
+# ahead of the body. It does not evaluate anything and does not know Kex
+# syntax; the text inside a hole is kept as-is, for a later stage to parse
+# and lower into real Kex.
+#
+#   using Template
+#
+#   let source = "---\nlayout: page\nparams: [name, library: Bool]\n---\nHi <%= name %>!"
+#   let parsed = Template.scan(source).try
+#   parsed.frontmatter.get("layout")   # => Just(Scalar("page"))
+#   parsed.parameters                  # => [TemplateParam { name: "name", type: "" },
+#                                       #     TemplateParam { name: "library", type: "Bool" }]
+#   parsed.nodes                       # => [Text("Hi "), Interpolate("name"), Text("!")]
+#
+# ## Syntax
+#
+#   <%= expr %>     interpolate (escaping is a later stage's job)
+#   <%== expr %>    interpolate raw, no escaping
+#   <% ... %>       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
+#   <%%             a literal `<%`, for a template that generates ERB-shaped
+#                   output itself
+#
+# ## Frontmatter
+#
+# A template file may open with a `---` line, generic `key: value` tags up to
+# a closing `---` line, and then the body. This is metadata for whatever
+# reads the template — a title, a layout name, a list of tags — and there is
+# nothing template-specific about it: it is scanned the same generic way
+# whatever key is used.
+#
+#   ---
+#   title: Release notes
+#   tags: [changelog, public]
+#   ---
+#   # <%= title %>
+#
+# A template's parameters, when a later stage needs them declared rather than
+# inferred, are just another frontmatter key — conventionally `params`, a
+# list of names each with an optional `: Type`:
+#
+#   ---
+#   params: [name, library: Bool, dependencies: [Dependency]]
+#   ---
+#   # <%= name %>
+#
+# Nothing in the scanner treats `params` specially while scanning — it is
+# metadata like any other key, a `[a, b, c]` list same as `tags` above.
+# `Parsed#parameters` is a convenience reader for it: it splits each entry on
+# its first colon into a `TemplateParam { name, type }` (`type` is `""` for a bare
+# name), so a caller does not need to know the key name, match on `Tag`
+# itself, or split each entry by hand. `type` is raw text, same as
+# everywhere else in this module — turning `[Dependency]` into a real,
+# resolved Kex type is later work, not this module's.
+module Template
+using Parsing
+
+# One piece of a scanned template.
+#
+# Hole and control content is carried as raw text — the Kex source that was
+# between the delimiters, trimmed of surrounding whitespace. Turning that
+# text into real, type-checked Kex expressions is later work; a `Node` only
+# records what KIND of region it is and what text it held.
+type Node = Text(String)
+          | Interpolate(String)
+          | InterpolateRaw(String)
+          | Control(String)
+          | Comment(String)
+
+# A frontmatter value: a plain scalar, or a `[a, b, c]` list.
+type Tag = Scalar(String)
+         | Tags([String])
+
+# Why a template's text could not be scanned, and where.
+type TemplateError = UnterminatedTag(Integer)
+                    | UnterminatedFrontmatter
+                    | MalformedFrontmatterLine(String)
+
+# One entry from a `params: [...]` frontmatter list: a name, and its
+# optional `: Type` annotation. `type` is raw text — `""` for a bare name,
+# never a resolved Kex type — the same way a frontmatter `Tag` is text and
+# not a parsed value.
+record TemplateParam do
+  name : String
+  type : String
+end
+
+# One scanned `<% ... %>` region: its node, and the whitespace trims its
+# delimiters asked for. Not part of the public API — internal to scanning —
+# but declared at module scope rather than inside `private do`: nested
+# there, this record's fields lose their names under BEAM codegen and the
+# value round-trips as an untagged tuple (`Undefined method: leftTrim for
+# Tuple`), even though the same code is fine on the tree-walking interpreter.
+record TagScan do
+  node      : Node
+  leftTrim  : Bool
+  rightTrim : Bool
+end
+
+# A scanned template: its frontmatter tags, and its body as a node list.
+record Parsed do
+  frontmatter : {String: Tag}
+  nodes       : [Node]
+end
+
+make Parsed do
+  # The template's declared parameters, out of a `params: [...]` frontmatter
+  # key — `[]` when the template declares none, or when `params` holds a
+  # bare scalar rather than a list.
+  #
+  # @return [[TemplateParam]] the declared parameters, in the order written
+  #
+  # @example
+  #   parsed.parameters
+  #   # => [TemplateParam { name: "name", type: "" }, TemplateParam { name: "library", type: "Bool" }]
+  let parameters -> [TemplateParam] do
+    let none: [TemplateParam] = []
+    match @frontmatter.get("params") do
+      Just(Tags(names)) => parseTemplateParams(names)
+      _ => none
+    end
+  end
+end
+
+# Scans template source into a `Parsed` template, or says where it broke.
+#
+# @param source [String] the template file's full text
+# @return [Result<Parsed, TemplateError>] the scanned template, or why not
+#
+# @example
+#   Template.scan("Hi <%= name %>!").map(~nodes)
+#   # => Ok([Text("Hi "), Interpolate("name"), Text("!")])
+let scan(source: String) -> Result<Parsed, TemplateError> do
+  let cursor = Input { input: source }
+  let (frontmatter, afterFrontmatter) = scanFrontmatter(cursor).try
+  let (nodes, _) = scanBody(afterFrontmatter).try
+  Ok(Parsed { frontmatter: frontmatter, nodes: nodes })
+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.
+  # Hand-rolled peek chain rather than `Input#string("---")`: `string`'s name
+  # collides with `Char#string` (a zero-arg property) the same way
+  # `takeWhile`/`atEnd?`/`readLine` collide elsewhere in this file — the
+  # prelude-interface build picks the wrong candidate and reports an arity
+  # mismatch even though the receiver type here is unambiguous.
+  let atFrontmatterOpen?(cursor: Input) -> Bool do
+    (cursor.pos == 0 &&
+      cursor.peek == Just('-') && cursor.peekAt(1) == Just('-') && cursor.peekAt(2) == Just('-') &&
+      (cursor.peekAt(3) == Just('\n') || cursor.peekAt(3) == Just('\r') || cursor.peekAt(3) == None))
+  end
+
+  # A cursor advanced past the current character if it is `\r\n` or `\n`;
+  # otherwise unchanged. What a `-%>` closer's trailing-newline trim needs.
+  let skipOneNewline(cursor: Input) -> Input do
+    if cursor.peek == Just('\r') && cursor.peekAt(1) == Just('\n')
+      cursor.advanceBy(2)
+    elif cursor.peek == Just('\n')
+      cursor.advance
+    else
+      cursor
+    end
+  end
+
+  # 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.
+  let scanLine(cursor: Input) -> (String, Input) do
+    var cur = cursor
+    var chars: [Char] = []
+    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)
+  end
+
+  # A line's text with any trailing `\r` dropped, for a source that mixes
+  # `\r\n` and `\n` line endings.
+  let stripTrailingCR(text: String) -> String do
+    text.endsWith?("\r") then text.take(text.count - 1) else text
+  end
+
+  # Strips one layer of matching `"..."` or `'...'` quotes, if present.
+  let unquote(text: String) -> String do
+    let quoted = (text.count >= 2 &&
+      ((text.startsWith?("\"") && text.endsWith?("\"")) || (text.startsWith?("'") && text.endsWith?("'"))))
+    quoted then text.drop(1).take(text.count - 2) else text
+  end
+
+  # A frontmatter value's text, parsed as a `[a, b, c]` list or a scalar.
+  # Splits `text` on commas that are not nested inside `[]`, `()`, `<>`, or
+  # `{}` — so a `params` entry's type, `Map<String, Integer>` or
+  # `[Dependency, Other]`, stays one list item rather than splitting on its
+  # own internal comma.
+  let splitTopLevelCommas(text: String) -> [String] do
+    let empty: ([String], String, Integer) = ([], "", 0)
+    let (parts, last, _) = text.reduce(empty) do |acc, ch|
+      let (parts, current, depth) = acc
+      if ch == '[' || ch == '(' || ch == '<' || ch == '{'
+        (parts, "${current}${ch}", depth + 1)
+      elif ch == ']' || ch == ')' || ch == '>' || ch == '}'
+        (parts, "${current}${ch}", depth - 1)
+      elif ch == ',' && depth == 0
+        ([...parts, current], "", depth)
+      else
+        (parts, "${current}${ch}", depth)
+      end
+    end
+    last.empty? then parts else [...parts, last]
+  end
+
+  let parseFrontmatterValue(raw: String) -> Tag do
+    if raw.startsWith?("[") && raw.endsWith?("]")
+      let inner = raw.drop(1).take(raw.count - 2).trim
+      let items = inner.empty? then [] else splitTopLevelCommas(inner).map { |item| unquote(item.trim) }
+      Tags(items)
+    else
+      Scalar(unquote(raw))
+    end
+  end
+
+  # One `key: value` frontmatter line, split at its first colon.
+  let parseFrontmatterLine(line: String) -> Result<(String, Tag), TemplateError> do
+    let colon = line.findIndex { |ch| ch == ':' }
+    return Error(MalformedFrontmatterLine(line)) if colon == None
+    # `.or(0)` rather than `let Just(index) = colon`: the guard above already
+    # rules out `None`, but destructuring it and feeding the bound name
+    # straight into another generic call (`take`/`drop`) trips a real
+    # type-checker bug where the prelude-interface build cross-contaminates
+    # unrelated generic inference elsewhere in the stdlib. Unwrapping with a
+    # (dead) default avoids it.
+    let index = colon.or(0)
+    let key = line.take(index).trim
+    return Error(MalformedFrontmatterLine(line)) if key.empty?
+    let value = parseFrontmatterValue(line.drop(index + 1).trim)
+    Ok((key, value))
+  end
+
+  # One `params` list entry, split into a name and its optional `: Type`.
+  # `type` is `""` when `raw` is a bare name.
+  let parseTemplateParam(raw: String) -> TemplateParam do
+    let colon = raw.findIndex { |ch| ch == ':' }
+    if colon == None
+      TemplateParam { name: raw.trim, type: "" }
+    else
+      # `.or(0)` rather than destructuring — see `parseFrontmatterLine`'s
+      # comment on why.
+      let index = colon.or(0)
+      TemplateParam { name: raw.take(index).trim, type: raw.drop(index + 1).trim }
+    end
+  end
+
+  # `names.map(~parseTemplateParam)`, spelled as an indexed loop rather than a
+  # generic `map`/`reduce` call: `[String]`'s element type is itself a type
+  # that implements `Enumerable`, and going through the shared HOF name here
+  # sends the prelude-interface build's overload resolution to `String`'s own
+  # `reduce` (iterating characters) instead of `List`'s — the bound block
+  # parameter then type-checks as `Char`, not `String`. Same collision class
+  # as `Input#takeWhile`/`atEnd?`/`string` elsewhere in this file.
+  let parseTemplateParams(names: [String]) -> [TemplateParam] do
+    var params: [TemplateParam] = []
+    var i = 0
+    loop do
+      break if i >= names.count
+      params.push!(parseTemplateParam(names.at(i).or("")))
+      i = i + 1
+    end
+    params
+  end
+
+  # Reads a leading `---` ... `---` frontmatter block, if the input opens with
+  # one. Answers an empty map and the cursor unmoved when it does not.
+  let scanFrontmatter(cursor: Input) -> Result<({String: Tag}, Input), TemplateError> do
+    return Ok(({}, cursor)) if !atFrontmatterOpen?(cursor)
+
+    let (_, afterOpenLine) = scanLine(cursor)
+    var cur = skipOneNewline(afterOpenLine)
+    var tags: {String: Tag} = {}
+    loop do
+      return Error(UnterminatedFrontmatter) if cur.peek == None
+      let (rawLine, afterLine) = scanLine(cur)
+      let line = stripTrailingCR(rawLine).trim
+      cur = skipOneNewline(afterLine)
+      return Ok((tags, cur)) if line == "---"
+      if !line.empty?
+        let (key, value) = parseFrontmatterLine(line).try
+        tags = tags.put(key, value)
+      end
+    end
+  end
+
+  # True when `cursor` sits at a `<%` tag opener (and it is not the `<%%`
+  # escape for a literal `<%`).
+  let atTagOpen?(cursor: Input) -> Bool do
+    cursor.peek == Just('<') && cursor.peekAt(1) == Just('%') && cursor.peekAt(2) != Just('%')
+  end
+
+  # Reads plain text up to the next tag opener or end of input. `<%%` is
+  # consumed as a literal `<%` and folded into the text rather than ending it.
+  #
+  # Hand-rolled rather than built on `Input#takeWhile`: that method's name
+  # 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).
+  let scanText(cursor: Input) -> (String, Input) do
+    var cur = cursor
+    var chars: [Char] = []
+    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!('%')
+        cur.advanceBy!(3)
+      else
+        let Just(ch) = cur.peek
+        chars.push!(ch)
+        cur.advance!
+      end
+    end
+    (chars.join(""), cur)
+  end
+
+  # Strips trailing spaces and tabs (not newlines) — the indentation a `<%-`
+  # opener asks to have removed from the text before it.
+  let trimTrailingIndent(text: String) -> String do
+    var chars = text.chars
+    loop do
+      break if chars.empty?
+      let Just(last) = chars.last
+      break if last != ' ' && last != '\t'
+      chars = chars.take(chars.count - 1)
+    end
+    chars.join("")
+  end
+
+  # `<%=`, `<%==`, `<%#`, or plain `<%` — which kind of region this is, and
+  # the cursor past the marker.
+  let classifyTag(cursor: Input) -> (String, Input) do
+    if cursor.peek == Just('=') && cursor.peekAt(1) == Just('=')
+      ("raw", cursor.advanceBy(2))
+    elif cursor.peek == Just('=')
+      ("interpolate", cursor.advance)
+    elif cursor.peek == Just('#')
+      ("comment", cursor.advance)
+    else
+      ("control", cursor)
+    end
+  end
+
+  # 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.
+  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)
+      cur.advance!
+    end
+  end
+
+  # The node a tag's kind and trimmed body settle into.
+  let tagNode(kind: String, body: String) -> Node do
+    if kind == "raw"
+      InterpolateRaw(body)
+    elif kind == "interpolate"
+      Interpolate(body)
+    elif kind == "comment"
+      Comment(body)
+    else
+      Control(body)
+    end
+  end
+
+  # Scans one tag starting at `cursor`, which must sit at a `<%` opener.
+  let scanTag(cursor: Input) -> Result<(TagScan, Input), TemplateError> do
+    let opened = cursor.advanceBy(2)
+    let leftTrim = opened.peek == Just('-')
+    let afterTrim = leftTrim then opened.advance else opened
+    let (kind, afterKind) = classifyTag(afterTrim)
+    let (body, rightTrim, rest) = scanTagBody(afterKind).try
+    let scanned = TagScan { node: tagNode(kind, body.trim), leftTrim: leftTrim, rightTrim: rightTrim }
+    Ok((scanned, rest))
+  end
+
+  # Scans the template body — everything after any frontmatter — into nodes.
+  let scanBody(cursor: Input) -> Result<([Node], Input), TemplateError> do
+    var cur = cursor
+    var nodes: [Node] = []
+    loop do
+      let (text, afterText) = scanText(cur)
+      if afterText.peek == None
+        if !text.empty?
+          nodes.push!(Text(text))
+        end
+        return Ok((nodes, afterText))
+      end
+      let (tag, afterTag) = scanTag(afterText).try
+      let keptText = tag.leftTrim 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
+    end
+  end
+end
 # The built-in testing DSL: +describe+, +it+, +before+, +after+, and
 # assertion helpers.
 #