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

package/dist/kex_repl_wasm.data

@@ -1,14 +1,8 @@
-# Algebraic structures, ordering, and combining values associatively.
+# Algebraic structures: combining values associatively.
 #
 # Kex traits do not inherit from one another, so concrete types explicitly
 # implement every structure whose laws they satisfy.
 #
-# The two most important things that you will meet in everyday code. +Ordering+ is what
-# a comparison answers, and it composes. This is how a multi-key sort is
-# written without nested +if+s:
-#
-#   a.age.compare(b.age).thenBy { a.score.compare(b.score) }
-#
 # +Monoid+ is "these two values combine, and there is a neutral one". Numbers,
 # strings and lists all satisfy it, which is what lets +repeat+ be written
 # once:
@@ -16,70 +10,15 @@
 #   "ab".repeat(3)   # => "ababab"
 #   [1].repeat(2)    # => [1, 1]
 #   5.repeat(3)      # => 15
-
-# The result of a comparison: +Less+, +Equal+ or +Greater+.
-#
-# Declared here rather than only inside the interpreter so that `Ordering`,
-# `Less`, `Equal` and `Greater` reach the semantic layer the same way every
-# other stdlib type does (through the collected interfaces) instead of
-# existing solely as native environment bindings the type checker and name
-# resolver cannot see.
-type Ordering = Less | Equal | Greater
-
-# Types that have a total order.
 #
-# Implemented by +Number+, which covers both +Integer+ and +Float+.
-trait Comparable do
-  # Compares this value with +other+ and answers +Less+, +Equal+ or
-  # +Greater+.
-  #
-  # +==+ stays independent of this: a type may be equatable without being
-  # ordered.
-  #
-  # @param other [This] the value to compare against
-  # @return [Ordering] how this value orders against +other+
-  #
-  # @example
-  #   1.compare(2)     # => Less
-  #   2.compare(2)     # => Equal
-  #   3.compare(2)     # => Greater
-  #
-  # @example Sorting with an explicit comparison
-  #   people.sort { |a, b| a.age.compare(b.age) == Less }
-  # A total order: `compare` answers Less, Equal or Greater. `==` stays
-  # independent: a type may be Equatable without being ordered.
-  compare :> This -> Ordering
-end
-
-# Number carries the implementation, so Integer and Float both inherit it
-# rather than repeating the same three comparisons. Mixed receivers work
-# because `<` and `>` promote across the two (`1.compare(1.0)` is Equal).
-make Number, implement: Comparable do
-  # Compares two numbers, across the +Integer+/+Float+ boundary.
-  #
-  # Mixed receivers work because +<+ and +>+ promote across the two, so
-  # +1.compare(1.0)+ is +Equal+.
-  #
-  # @param other [Number] the number to compare against
-  # @return [Ordering] how this number orders against +other+
-  #
-  # @example
-  #   1.compare(2)      # => Less
-  #   1.compare(1.0)    # => Equal
-  #   2.5.compare(2)    # => Greater
-  let compare(other: Number) -> Ordering do
-    return Less if this < other
-    return Greater if this > other
-
-    return Equal
-  end
-end
+# Ordering and comparison (+Ordering+, +Comparable+) live in
+# `comparable.kex`.
 
 # Types whose values combine associatively and have a neutral element.
 #
 # Implemented by +Integer+ (addition), +String+ and +List+ (concatenation),
 # +Map+ and both +Set+ flavours (union), and +Ordering+ ("first decision
-# wins").
+# wins" — declared beside +Ordering+ in `comparable.kex`).
 trait Monoid do
   # The neutral element: combining it with any value gives that value back.
   #
@@ -145,7 +84,6 @@ trait Group do
 
   # Combines this value with +other+.
   #
-  # @param other [This] the value to combine with
   # @return [This] the combined value
   combine :> This -> This
 
@@ -233,82 +171,6 @@ make [A], implement: Monoid do
   #   groups.reduce([]) { |acc, g| acc.combine(g) }
   let combine(other: This) -> This = this + other
 end
-
-# `Ordering` is a Monoid under "first decision wins", with Equal as identity.
-# That is what makes multi-key comparison compose instead of nesting ifs:
-#
-#   a.name.compare(b.name).combine(a.age.compare(b.age))
-#
-# `combine` evaluates its argument eagerly, so the later comparison runs even
-# when the earlier one already decided. Use `thenBy` when that matters.
-make Ordering, implement: Monoid do
-  # +Equal+ is the neutral element, since an undecided comparison lets the next
-  # one decide.
-  #
-  # @return [Ordering] +Equal+
-  let identity = Equal
-
-  # Returns the first decisive ordering: this one if it is not +Equal+,
-  # otherwise +other+.
-  #
-  # This is what makes multi-key comparison compose. Note that +other+ is
-  # evaluated eagerly, so the later comparison runs even when the earlier one
-  # has already decided: use +thenBy+ when that matters.
-  #
-  # @param other [Ordering] the tie-breaking ordering
-  # @return [Ordering] the first decisive ordering
-  #
-  # @example
-  #   Equal.combine(Less)     # => Less
-  #   Less.combine(Greater)   # => Less
-  #
-  # @example Sorting by surname, then by first name
-  #   a.last.compare(b.last).combine(a.first.compare(b.first))
-  let combine(@Equal, other: Ordering) -> Ordering = other
-  let combine(@Less, _) -> Ordering = Less
-  let combine(@Greater, _) -> Ordering = Greater
-
-  # Returns the opposite ordering: +Less+ becomes +Greater+, +Greater+ becomes
-  # +Less+, and +Equal+ stays +Equal+.
-  #
-  # The one-word way to turn an ascending comparison into a descending one.
-  #
-  # @return [Ordering] the reversed ordering
-  #
-  # @example
-  #   Less.reverse      # => Greater
-  #   Greater.reverse   # => Less
-  #   Equal.reverse     # => Equal
-  #
-  # @example Sorting newest first
-  #   a.created.compare(b.created).reverse
-  reverse :> Ordering
-  let reverse(@Less) -> Ordering = Greater
-  let reverse(@Greater) -> Ordering = Less
-  let reverse(@Equal) -> Ordering = Equal
-
-  # Returns this ordering if it is decisive, otherwise the result of calling
-  # +tieBreaker+.
-  #
-  # The short-circuiting form of +combine+: the block runs only when this
-  # comparison is +Equal+, so a tie-breaker costs nothing once the order is
-  # already decided. Prefer it whenever the tie-breaker is more than a field
-  # read.
-  #
-  # @param tieBreaker [Block<Ordering>] evaluated only on a tie
-  # @return [Ordering] the first decisive ordering
-  #
-  # @example
-  #   Equal.thenBy { 2.compare(1) }   # => Greater
-  #   Less.thenBy { 2.compare(1) }    # => Less
-  #
-  # @example Sorting by age, then by an expensive score
-  #   a.age.compare(b.age).thenBy { score(a).compare(score(b)) }
-  thenBy :> Block<Ordering> -> Ordering
-  let thenBy(@Equal, tieBreaker) -> Ordering = tieBreaker()
-  let thenBy(@Less, _) -> Ordering = Less
-  let thenBy(@Greater, _) -> Ordering = Greater
-end
 # An opaque, immutable sequence of bytes. A +Binary+ never implicitly becomes
 # text.
 #
@@ -843,6 +705,178 @@ make [X], implement: Blankable do
   let blank?(@[]) = true
   let blank?(@[_|_]) = false
 end
+# Ordering and comparison: what a comparison answers, and the types that
+# have a total order.
+#
+# Kex traits do not inherit from one another, so concrete types explicitly
+# implement every structure whose laws they satisfy.
+#
+# The two things you meet in everyday code here. +Ordering+ is what a
+# comparison answers, and it composes. This is how a multi-key sort is
+# written without nested +if+s:
+#
+#   a.age.compare(b.age).thenBy { a.score.compare(b.score) }
+#
+# +Ordering+ is also a +Monoid+ under "first decision wins", which is what
+# makes comparisons chain with +combine+; that conformance is declared here,
+# beside the type it belongs to, rather than in `algebra.kex` with the
+# +Monoid+ trait.
+
+# The result of a comparison: +Less+, +Equal+ or +Greater+.
+#
+# Declared here rather than only inside the interpreter so that `Ordering`,
+# `Less`, `Equal` and `Greater` reach the semantic layer the same way every
+# other stdlib type does (through the collected interfaces) instead of
+# existing solely as native environment bindings the type checker and name
+# resolver cannot see.
+type Ordering = Less | Equal | Greater
+
+# Types that have a total order.
+#
+# Implemented by +Number+, which covers both +Integer+ and +Float+, and by
+# +String+.
+trait Comparable do
+  # Compares this value with +other+ and answers +Less+, +Equal+ or
+  # +Greater+.
+  #
+  # +==+ stays independent of this: a type may be equatable without being
+  # ordered.
+  #
+  # @param other [This] the value to compare against
+  # @return [Ordering] how this value orders against +other+
+  #
+  # @example
+  #   1.compare(2)     # => Less
+  #   2.compare(2)     # => Equal
+  #   3.compare(2)     # => Greater
+  #
+  # @example Sorting with an explicit comparison
+  #   people.sort { |a, b| a.age.compare(b.age) == Less }
+  # A total order: `compare` answers Less, Equal or Greater. `==` stays
+  # independent: a type may be Equatable without being ordered.
+  compare :> This -> Ordering
+end
+
+# Number carries the implementation, so Integer and Float both inherit it
+# rather than repeating the same three comparisons. Mixed receivers work
+# because `<` and `>` promote across the two (`1.compare(1.0)` is Equal).
+make Number, implement: Comparable do
+  # Compares two numbers, across the +Integer+/+Float+ boundary.
+  #
+  # Mixed receivers work because +<+ and +>+ promote across the two, so
+  # +1.compare(1.0)+ is +Equal+.
+  #
+  # @param other [Number] the number to compare against
+  # @return [Ordering] how this number orders against +other+
+  #
+  # @example
+  #   1.compare(2)      # => Less
+  #   1.compare(1.0)    # => Equal
+  #   2.5.compare(2)    # => Greater
+  let compare(other: Number) -> Ordering do
+    return Less if this < other
+    return Greater if this > other
+
+    return Equal
+  end
+end
+
+# Strings order lexicographically, character by character, by code point —
+# the same order `<` and `>` already give them.
+make String, implement: Comparable do
+  # Compares this string with +other+ lexicographically, the same order
+  # +<+ and +>+ give strings.
+  #
+  # @param other [String] the string to compare against
+  # @return [Ordering] how this string orders against +other+
+  #
+  # @example
+  #   "apple".compare("banana")   # => Less
+  #   "kex".compare("kex")        # => Equal
+  #   "cherry".compare("apple")   # => Greater
+  let compare(other: String) -> Ordering do
+    return Less if this < other
+    return Greater if this > other
+
+    return Equal
+  end
+end
+
+# `Ordering` is a Monoid under "first decision wins", with Equal as identity.
+# That is what makes multi-key comparison compose instead of nesting ifs:
+#
+#   a.name.compare(b.name).combine(a.age.compare(b.age))
+#
+# `combine` evaluates its argument eagerly, so the later comparison runs even
+# when the earlier one already decided. Use `thenBy` when that matters.
+make Ordering, implement: Monoid do
+  # +Equal+ is the neutral element, since an undecided comparison lets the next
+  # one decide.
+  #
+  # @return [Ordering] +Equal+
+  let identity = Equal
+
+  # Returns the first decisive ordering: this one if it is not +Equal+,
+  # otherwise +other+.
+  #
+  # This is what makes multi-key comparison compose. Note that +other+ is
+  # evaluated eagerly, so the later comparison runs even when the earlier one
+  # has already decided: use +thenBy+ when that matters.
+  #
+  # @param other [Ordering] the tie-breaking ordering
+  # @return [Ordering] the first decisive ordering
+  #
+  # @example
+  #   Equal.combine(Less)     # => Less
+  #   Less.combine(Greater)   # => Less
+  #
+  # @example Sorting by surname, then by first name
+  #   a.last.compare(b.last).combine(a.first.compare(b.first))
+  let combine(@Equal, other: Ordering) -> Ordering = other
+  let combine(@Less, _) -> Ordering = Less
+  let combine(@Greater, _) -> Ordering = Greater
+
+  # Returns the opposite ordering: +Less+ becomes +Greater+, +Greater+ becomes
+  # +Less+, and +Equal+ stays +Equal+.
+  #
+  # The one-word way to turn an ascending comparison into a descending one.
+  #
+  # @return [Ordering] the reversed ordering
+  #
+  # @example
+  #   Less.reverse      # => Greater
+  #   Greater.reverse   # => Less
+  #   Equal.reverse     # => Equal
+  #
+  # @example Sorting newest first
+  #   a.created.compare(b.created).reverse
+  reverse :> Ordering
+  let reverse(@Less) -> Ordering = Greater
+  let reverse(@Greater) -> Ordering = Less
+  let reverse(@Equal) -> Ordering = Equal
+
+  # Returns this ordering if it is decisive, otherwise the result of calling
+  # +tieBreaker+.
+  #
+  # The short-circuiting form of +combine+: the block runs only when this
+  # comparison is +Equal+, so a tie-breaker costs nothing once the order is
+  # already decided. Prefer it whenever the tie-breaker is more than a field
+  # read.
+  #
+  # @param tieBreaker [Block<Ordering>] evaluated only on a tie
+  # @return [Ordering] the first decisive ordering
+  #
+  # @example
+  #   Equal.thenBy { 2.compare(1) }   # => Greater
+  #   Less.thenBy { 2.compare(1) }    # => Less
+  #
+  # @example Sorting by age, then by an expensive score
+  #   a.age.compare(b.age).thenBy { score(a).compare(score(b)) }
+  thenBy :> Block<Ordering> -> Ordering
+  let thenBy(@Equal, tieBreaker) -> Ordering = tieBreaker()
+  let thenBy(@Less, _) -> Ordering = Less
+  let thenBy(@Greater, _) -> Ordering = Greater
+end
 # ANSI terminal styling: colors, text attributes, and cursor control.
 #
 # Every constant here becomes an empty string when Kex is started with
@@ -3565,6 +3599,36 @@ make FileHandle<R, W> do
   #   end
   close :> Void
   foul close = Kex.Intrinsic.FileHandle.close(this)
+
+  # Moves the handle's cursor to an absolute byte offset from the start of
+  # the file. Read and write share one cursor, so this repositions both —
+  # a `readLine` right after `seek(0)` starts over from the top, and a
+  # `write` right after does too, overwriting from that point.
+  #
+  # @param offset [Integer] the byte offset to seek to, from the start of
+  #   the file
+  # @return [Result<Void, ReadError>] +Ok+ on success, or why the seek
+  #   failed
+  #
+  # @example Reading a length-prefixed record, then rewinding past it
+  #   let length = handle.readLine.or("0").to(Integer).or(0)
+  #   let record = handle.readBytes.try
+  #   handle.seek(0)
+  seek : Integer -> Result<Void, ReadError>
+  foul seek(offset) = Kex.Intrinsic.FileHandle.seek(this, offset)
+
+  # Moves the handle's cursor back to the start of the file — the same as
+  # +seek(0)+, for the common case of re-reading a handle from the top.
+  #
+  # @return [Result<Void, ReadError>] +Ok+ on success, or why the reset
+  #   failed
+  #
+  # @example Reading a file twice
+  #   let firstPass = handle.read.or("")
+  #   handle.reset
+  #   let secondPass = handle.read.or("")
+  reset :> Result<Void, ReadError>
+  foul reset = Kex.Intrinsic.FileHandle.reset(this)
 end
 # The filesystem: reading and writing files, walking directories, and
 # manipulating paths.
@@ -8243,6 +8307,18 @@ module Net.HTTP
 
 # An insertion-ordered HTTP field collection. Names compare case-insensitively
 # and duplicate fields are preserved.
+#
+# A list of pairs rather than a +{String: String}+ map, and deliberately so.
+# A map cannot hold the same name twice, and +Set-Cookie+ needs exactly that:
+# RFC 6265 does not define it as a comma-separated list, so two cookies must
+# travel as two fields and cannot be joined into one. A map interface would
+# read as the obvious one right up to the first response that sets two
+# cookies, then silently keep one — the same class of quiet data loss this
+# module's +Result+-returning builders exist to avoid.
+#
+# Order is kept for the same reason. RFC 9110 makes order insignificant
+# BETWEEN different names but significant between fields sharing a name, and
+# a map has no order to keep.
 record Headers do
   entries : [(String, String)]
 end
@@ -8345,8 +8421,8 @@ module Headers do
   #
   # @example Building request headers immutably
   #   Headers.empty
-  #     .add("Accept", "application/json")
-  #     .add("User-Agent", "inventory-sync/1.0")
+  #     .add("Accept", "application/json").try
+  #     .add("User-Agent", "inventory-sync/1.0").try
   empty : Headers
   let empty = Headers { entries: [] }
 
@@ -8398,7 +8474,7 @@ module Response do
   # Builds a buffered binary response with validated headers.
   #
   # @example Returning a downloaded file without decoding it as text
-  #   Response.binary(200, archive, Headers.empty.set("Content-Type", "application/zip"))
+  #   Response.binary(200, archive, Headers.empty.add("Content-Type", "application/zip").try)
   foul binary(status: Integer, body: Binary, headers: Headers) -> Response<Binary> = Kex.Intrinsic.NetHTTP.responseBinary(status, body, headers)
   # Builds a UTF-8 text response with an explicit text/plain content type.
   #
@@ -8524,8 +8600,8 @@ make Client do
   #
   # @example Sending JSON with an idempotency key
   #   let headers = Headers.empty
-  #     .set("Content-Type", "application/json")
-  #     .set("Idempotency-Key", requestId)
+  #     .add("Content-Type", "application/json").try
+  #     .add("Idempotency-Key", requestId).try
   #   client.request("POST", url, headers, JSON.stringify(order).to(Binary).try)
   foul request(method: String, url: String, headers: Headers, body: Binary) -> Result<Response<Binary>, NetError> = Kex.Intrinsic.NetHTTPClient.request(this, method, url, headers, body)
   # Sends a buffered GET request.
@@ -8557,12 +8633,27 @@ make Client do
 end
 
 make Headers, implement: Showable, Inspectable do
-  # Appends a field without replacing existing fields of the same name.
-  # @example +Headers.empty.add("Accept", "text/plain")+
-  let add(name: String, value: String) -> Headers = Kex.Intrinsic.NetHTTP.addHeader(this, name, value)
-  # Replaces all fields of +name+ with one value.
-  # @example +headers.set("Content-Type", "application/json")+
-  let set(name: String, value: String) -> Headers = Kex.Intrinsic.NetHTTP.setHeader(this, name, value)
+  # Appends a field, keeping existing fields of the same name.
+  #
+  # Repeats are how +Set-Cookie+ works: it is not a comma-separated list, so
+  # two cookies must be two fields. For replace-semantics, +remove+ first.
+  #
+  # An invalid name or value is an +Error+, not a silent drop. Rejecting
+  # +"a\r\nX: y"+ is what stops response splitting, but dropping it quietly
+  # left the caller holding a valid +Headers+ that simply lacked the field it
+  # asked for, and a response with no +Content-Type+ invites MIME sniffing.
+  # +from+ and +parse+ already answer with a +Result+ for this same input.
+  #
+  # @return [Result<Headers, NetError>] the extended fields, or +Parse+
+  #
+  # @example Two cookies on one response
+  #   Headers.empty
+  #     .add("Set-Cookie", "session=abc; HttpOnly").try
+  #     .add("Set-Cookie", "theme=dark").try
+  #
+  # @example Replacing a field
+  #   headers.remove("Content-Type").add("Content-Type", "application/json").try
+  let add(name: String, value: String) -> Result<Headers, NetError> = Kex.Intrinsic.NetHTTP.addHeader(this, name, value)
   # Removes every field matching +name+ case-insensitively.
   #
   # @example Stripping hop-by-hop state before forwarding
@@ -8619,7 +8710,7 @@ module HTTP do
   # occasional requests; use +Client+ for a service making repeated calls.
   #
   # @example A one-off authenticated request in a command-line tool
-  #   let headers = Headers.empty.set("Authorization", "Bearer ${token}")
+  #   let headers = Headers.empty.add("Authorization", "Bearer ${token}").try
   #   HTTP.request("GET", url, headers).try
   request : String -> String -> Headers -> Binary -> Result<Response<Binary>, NetError>
   let request(method, url, headers = Headers.empty, body = Binary.empty) = Kex.Intrinsic.NetHTTP.request(method, url, headers, body)
@@ -9748,6 +9839,7 @@ end
 # empty. Most of the time that is a single +.or(default)+ at the end of a
 # chain.
 #
+# @example
 #   let names = ["ada", "grace"]
 #   names.first.or("nobody")        # => "ada"
 #   names.at(9).or("nobody")        # => "nobody"
@@ -9755,6 +9847,7 @@ end
 #
 # Pattern matching handles the cases that need more than a default:
 #
+# @example
 #   match config.get("port") do
 #     Just(port) => IO.printLine("listening on ${port}")
 #     None       => IO.printLine("no port configured")
@@ -9767,7 +9860,7 @@ type Optional<X> = Just(X) | None
 # Use +Result+ over +Optional+ when the *reason* for failure matters to the
 # caller. Parsing is the standard example: +"12x".to(Integer)+ answers +None+,
 # while +Integer.parse("12x")+ answers an +Error+ that says where it stopped.
-#
+# @example
 #   Integer.parse("42").or(0)     # => 42
 #   Integer.parse("4x").or(0)     # => 0
 #
@@ -9782,6 +9875,7 @@ type Result<X, E> = Ok(X) | Error(E)
 # Unlike +Result+, neither side means failure: +Either+ is for a value that is
 # legitimately one of two shapes.
 #
+# @example
 #   type Id = Either<Integer, String>
 #
 #   let describe(id: Id) -> String do
@@ -9792,19 +9886,85 @@ type Result<X, E> = Ok(X) | Error(E)
 #   end
 type Either<L, R> = Left(L) | Right(R)
 
-# Marker trait for +Optional+. Constrain a generic parameter with it when a
+# A value that may be absent. Constrain a generic parameter with it when a
 # function accepts any optional value.
+#
+# The two operations below are what make the constraint worth having: an
+# empty trait would accept a value and then let you do nothing with it, since
+# there would be no method to call. +map+ is deliberately NOT required — its
+# result type differs per implementer (+Y?+ here, +Result<Y, E>+ for
+# +Resultable+), which needs a higher-kinded parameter Kex does not have.
 trait Optionable do
+  # Answers +true+ when a value is present.
+  #
+  # The one operation an +Optionable+ type must define; +none?+ is its
+  # negation.
+  #
+  # @return [Bool] +true+ for a present value
+  #
+  # @example
+  #   Just(1).set?   # => true
+  #   None.set?      # => false
+  set? :> Bool
+
+  # Returns the wrapped value, or +default+ when there is none.
+  #
+  # The way out of the optional world, and the reason a constrained parameter
+  # is usable at all.
+  #
+  # @param default [X] the value to use when absent
+  # @return [X] the wrapped value, or +default+
+  #
+  # @example
+  #   Just(42).or(0)   # => 42
+  #   None.or(0)       # => 0
+  or :> X -> X
 end
 
-# Marker trait for +Result+. Constrain a generic parameter with it when a
-# function accepts any result value.
+# A value that either succeeded or failed with a reason. Constrain a generic
+# parameter with it when a function accepts any result value.
 trait Resultable do
+  # Answers +true+ for a success.
+  #
+  # The one operation a +Resultable+ type must define; +error?+ is its
+  # negation.
+  #
+  # @return [Bool] +true+ for +Ok+
+  #
+  # @example
+  #   Ok(1).ok?         # => true
+  #   Error("!").ok?    # => false
+  ok? :> Bool
+
+  # Returns the success value, or +default+ on failure.
+  #
+  # @param default [X] the value to use on failure
+  # @return [X] the +Ok+ value, or +default+
+  #
+  # @example
+  #   Ok(42).or(0)       # => 42
+  #   Error("!").or(0)   # => 0
+  or :> X -> X
 end
 
-# Marker trait for +Either+. Constrain a generic parameter with it when a
-# function accepts any either value.
+# One of two values, neither meaning failure. Constrain a generic parameter
+# with it when a function accepts any either value.
 trait Eitherable do
+  # Case analysis: applies +onLeft+ to a +Left+ and +onRight+ to a +Right+.
+  #
+  # The one operation an +Eitherable+ type must define — +left?+ and +right?+
+  # are both written in terms of it. A discriminator alone would let you ask
+  # which side a value is on without being able to reach it, which is why this
+  # is the requirement rather than those.
+  #
+  # @param onLeft [L -> A] applied to a +Left+
+  # @param onRight [R -> A] applied to a +Right+
+  # @return [A] whichever branch ran
+  #
+  # @example
+  #   Left(2).either(~toString, ~upperCase)      # => "2"
+  #   Right("ok").either(~toString, ~upperCase)  # => "OK"
+  either :> (L -> A) -> (R -> A) -> A
 end
 
 make Optional<X>, implement: Optionable do
@@ -10003,21 +10163,6 @@ make Result<X, E>, implement: Resultable do
   let optional(@Error(_)) = None
 end
 
-# Returns the value unchanged.
-#
-# The catch-all clause of +or+: a value that is neither an +Optional+ nor a
-# +Result+ has already succeeded, so there is nothing to fall back to. This is
-# what lets +.or(default)+ be written after a call whose return type may later
-# stop being optional, without the call site changing.
-#
-# @param value [A] any plain value
-# @return [A] the same value
-#
-# @example
-#   42.or(0)        # => 42
-#   "text".or("")   # => "text"
-let or(value, _) = value
-
 # Converts +value+ to the type +t+, or +None+ if it cannot be represented.
 #
 # +t+ is a runtime type value: write the type name itself: +String+,
@@ -10066,6 +10211,49 @@ let to(value, t) = Kex.Intrinsic.Fun.convertTo(value, t)
 let to(value, t, radix: Integer) = Kex.Intrinsic.Fun.convertTo(value, t, radix)
 
 make Either<L, R>, implement: Eitherable do
+  # Case analysis: applies +onLeft+ to a +Left+ and +onRight+ to a +Right+.
+  #
+  # The way an +Either+ is consumed without a +match+, and the operation
+  # +Eitherable+ requires. Both branches answer the same type, so the result
+  # is a plain value rather than another +Either+.
+  #
+  # @param onLeft [L -> A] applied to a +Left+
+  # @param onRight [R -> A] applied to a +Right+
+  # @return [A] whichever branch ran
+  #
+  # @example
+  #   Left(2).either(~toString, ~upperCase)       # => "2"
+  #   Right("ok").either(~toString, ~upperCase)   # => "OK"
+  #
+  # @example Collapsing an id to text
+  #   let render(id: Either<Integer, String>) -> String do
+  #     id.either({ |n| "#${n}" }, { |slug| slug })
+  #   end
+  either :> (L -> A) -> (R -> A) -> A
+  let either(@Left(l), onLeft, _) = onLeft(l)
+  let either(@Right(r), _, onRight) = onRight(r)
+
+  # Returns +true+ for a +Left+.
+  #
+  # @return [Bool]
+  #
+  # @example
+  #   Left(1).left?    # => true
+  #   Right(1).left?   # => false
+  left? :> Bool
+  let left?(@Left(_)) = true
+  let left?(@Right(_)) = false
+
+  # Returns +true+ for a +Right+. The opposite of +left?+.
+  #
+  # @return [Bool]
+  #
+  # @example
+  #   Right(1).right?   # => true
+  #   Left(1).right?    # => false
+  right? :> Bool
+  let right?(@Left(_)) = false
+  let right?(@Right(_)) = true
 end
 # Declarative command-line parsing, shared by Kex tools and applications.
 #
@@ -10144,6 +10332,15 @@ record CommandSpec do
   # What to run when this command is named.
   handler : CommandHandler
 
+  # Whether the command parses its own options. A passthrough command owns
+  # every token after its name: the outer parser stops matching options
+  # against its OWN declarations and forwards them verbatim in `arguments`,
+  # the way everything after `--` is forwarded. Without this a subcommand
+  # that runs its own OptionParser can only receive the option names the
+  # outer tool does not itself declare, and a collision is silent — the
+  # outer tool consumes the value and the subcommand sees nothing.
+  passthrough : Bool = false
+
   # The help heading this command is listed under. "" is the tool's own
   # `Commands:` block; anything else gets its own heading, in the order the
   # sections were first declared. Commands a tool discovers at runtime: a
@@ -10393,6 +10590,31 @@ make OptionConfig do
     New { commands: [...@commands, spec] }
   end
 
+  # Declares a command that parses its own options.
+  #
+  # Everything after the command's name is handed to the handler in
+  # +arguments+ untouched, including options this tool also declares. Use it
+  # for a subcommand backed by its own +OptionConfig+: without it, an option
+  # the outer tool happens to declare too is consumed here and never reaches
+  # the subcommand, with no error to say so.
+  #
+  # @param name [String] the command's name, one or more words
+  # @param usage [String] the argument shape shown in the help text
+  # @param description [String] the help-text description
+  # @param handler [CommandHandler] what to run
+  # @return [OptionConfig] the config, with the command added
+  #
+  # @example
+  #   config.passthroughCommand("docs", "<build|serve>",
+  #                             "generate documentation", ~docs)
+  let passthroughCommand(name: String, usage: String, description: String,
+                         handler: CommandHandler) -> OptionConfig do
+    let spec = CommandSpec { name: name, description: description,
+                             usage: usage, handler: handler,
+                             passthrough: true }
+    New { commands: [...@commands, spec] }
+  end
+
   # Parses +args+ into option values and leftover words, without dispatching
   # to a command.
   #
@@ -10588,6 +10810,28 @@ module OptionParser do
     end
   end
 
+  # Whether the command +arguments+ names parses its own options.
+  #
+  # +false+ when no command matches yet, so options before any command word
+  # are still this parser's to claim.
+  #
+  # @param commands [[CommandSpec]] the declared commands
+  # @param arguments [[String]] the positional words seen so far
+  # @return [Bool] +true+ when a matched command is passthrough
+  #
+  # @example
+  #   OptionParser.passthrough?(commands, ["docs", "build"])   # => true
+  #   OptionParser.passthrough?(commands, [])                  # => false
+  let passthrough?(commands: [CommandSpec], arguments: [String]) -> Bool do
+    match OptionParser.commandFor(commands, arguments) do
+      None => false
+      Just(pair) => do
+        let (command, _) = pair
+        return command.passthrough
+      end
+    end
+  end
+
   # Returns +true+ when +arguments+ begins with the words of +name+.
   #
   # The word-wise prefix test +commandFor+ matches with: +"docs build"+ opens
@@ -10682,6 +10926,15 @@ module OptionParser do
         return OptionParser.walk(options, commands, rest, values, [...arguments, argument], false)
       end
 
+      # A passthrough command owns the rest of the line. Once its words are
+      # in `arguments`, every option belongs to ITS vocabulary, so none is
+      # matched against this tool's declarations — otherwise a name both
+      # parsers declare (`tey --package` and `tey docs --package`) is eaten
+      # here and the subcommand silently never sees it.
+      if OptionParser.passthrough?(commands, arguments)
+        return OptionParser.walk(options, commands, rest, values, [...arguments, argument], false)
+      end
+
       let equals = argument.startsWith?("--") then argument.split("=") else [argument]
       let spelling = equals.first.or(argument)
       match OptionParser.findOption(options, spelling) do
@@ -11082,6 +11335,7 @@ end
 using Algebra
 using Binary
 using Blankable
+using Comparable
 using Console
 using Enumerable
 using Env
@@ -11269,6 +11523,32 @@ module Process do
   run : String -> [String] -> Result<ProcessResult, String>
   foul run(command, args) = Kex.Intrinsic.Process.run(command, args)
 
+  # Runs an executable with a time budget, and kills it if it overruns.
+  #
+  # Everything +run+ does, plus a deadline: when +timeoutMs+ milliseconds
+  # pass with the child still running, the child's process group is sent
+  # SIGTERM (then SIGKILL after a short grace) and reaped, and the call
+  # answers a timeout Error rather than the child's output. Signalling the
+  # group means forked grandchildren die with it. The budget bounds the
+  # whole call, so a hung child cannot hang the caller.
+  #
+  # A child that finishes in time answers exactly as +run+ would; a missing
+  # program still reports +executable not found+ without waiting.
+  #
+  # @param command [String] the executable to run
+  # @param args [[String]] its arguments, one per element
+  # @param timeoutMs [Integer] milliseconds before the child is killed
+  # @return [Result<ProcessResult, String>] the captured result, or why it
+  #   could not start — or that the budget ran out
+  #
+  # @example
+  #   match Process.run("sleep", ["30"], 300) do
+  #     Error(error) => IO.printLine(error)   # prints: timed out after 300ms
+  #     Ok(result) => IO.printLine(result.exitCode)
+  #   end
+  run : String -> [String] -> Integer -> Result<ProcessResult, String>
+  foul run(command, args, timeoutMs) = Kex.Intrinsic.Process.run(command, args, timeoutMs)
+
   # Runs an executable with the CALLER's stdout and stderr, so its output
   # appears as it is produced rather than in one block when it exits.
   #
@@ -12986,6 +13266,52 @@ make String, implement: Enumerable, Foldable do
   bytes :> [Byte]
   let bytes = Kex.Intrinsic.String.bytes(this)
 
+  # The storage size in bytes, without building the byte list.
+  #
+  # +bytes.count+ answers the same number by materialising every byte first,
+  # which on a megabyte payload means a million values to count them. This
+  # reads the encoded length directly.
+  #
+  # @return [Integer] the length of the UTF-8 encoding
+  #
+  # @example Text length and storage length differ
+  #   "héllo".count      # => 5
+  #   "héllo".byteSize   # => 6
+  byteSize :> Integer
+  let byteSize = Kex.Intrinsic.String.byteSize(this)
+
+  # One byte of the storage view, or +None+ when the index is out of range.
+  #
+  # This indexes the ENCODING, not the text: +byteAt+ on a multi-byte
+  # character returns one of its bytes, never the character. Use +at+ or
+  # +chars+ for the text view.
+  #
+  # @param index [Integer] a zero-based byte offset
+  # @return [Byte?] the byte, or +None+ past the end
+  #
+  # @example The two views of the same string
+  #   "héllo".byteAt(1)   # => Just(195)
+  #   "héllo".at(1)       # => Just("é")
+  #   "héllo".byteAt(99)  # => None
+  byteAt :> Integer -> Byte?
+  let byteAt(index: Integer) = Kex.Intrinsic.String.byteAt(this, index)
+
+  # A slice of the storage view, by byte offset and byte count.
+  #
+  # The range is clamped rather than refused, the way +take+ and +drop+
+  # already behave. Slicing mid-character yields a string holding partial
+  # UTF-8 — legal storage, but not text: decode it only at a boundary you
+  # know is a character boundary.
+  #
+  # @param offset [Integer] a zero-based byte offset, clamped to the string
+  # @param count [Integer] how many bytes, clamped to what remains
+  # @return [String] the bytes in that range
+  #
+  # @example Reading a length-prefixed field out of a payload
+  #   payload.bytePart(4, payload.byteSize - 4)
+  bytePart :> Integer -> Integer -> String
+  let bytePart(offset: Integer, count: Integer) = Kex.Intrinsic.String.bytePart(this, offset, count)
+
   # Splits the string into its individual characters, as one-character
   # strings.
   #
@@ -13816,6 +14142,24 @@ end
 #                                       #     TemplateParam { name: "library", type: "Bool" }]
 #   parsed.nodes                       # => [Text("Hi "), Interpolate("name"), Text("!")]
 #
+# A template file carries its host's extension ahead of `.ket`, so an editor
+# can highlight it as what it is — `README.md.ket`, `profile.html.ket`:
+#
+#   ---
+#   params: [name, library: Bool, dependencies: [Dependency]]
+#   ---
+#   # <%= name %>
+#
+#   <% if library %>
+#   A Kex library.
+#   <% else %>
+#   A Kex application.
+#   <% end %>
+#
+#   <% dependencies.map do |dep| %>
+#   - `<%= dep.name %>` ~> <%= dep.version %>
+#   <% end %>
+#
 # ## Syntax
 #
 #   <%= expr %>     interpolate (escaping is a later stage's job)
@@ -13823,10 +14167,40 @@ end
 #   <% ... %>       a Kex control region: `if`/`match` arms, block bodies, `let`
 #   <%# ... %>      comment, emits nothing
 #   <%- ... -%>     whitespace control: trims the line's leading indent before
-#                   the tag, and the newline right after it
+#                   the tag, and the newline right after it. A `<% %>` or
+#                   `<%# %>` tag standing alone on its line does this on its
+#                   own, so the markers are for a tag sharing its line with
+#                   real content
 #   <%%             a literal `<%`, for a template that generates ERB-shaped
 #                   output itself
 #
+# ## Whitespace
+#
+# A tag that emits nothing — `<% %>` and `<%# %>` — and stands alone on its
+# line takes that line with it. Only whitespace may share the line with it:
+# the indent before it and the newline after it are scaffolding, never
+# content, so a template reads the way its output does:
+#
+#   <% if dependencies.count > 0 %>
+#   ## Dependencies
+#   <% end %>
+#
+#   # => "## Dependencies\n"   — no blank line where the tags were
+#
+# The `<%- -%>` markers are for the case this does not cover: a tag sharing
+# its line with real content, where what to trim is a judgement call rather
+# than obvious.
+#
+#   Total: <%= total %> <%- if pending > 0 %>(<%= pending %> pending)<% end %>
+#
+# An interpolation is never trimmed, on its own line or not. It stands in for
+# content, so the whitespace around it is content too:
+#
+#   <%= greeting %>
+#   <%= name %>
+#
+#   # => "Hi\nAda\n"          — both newlines survive
+#
 # ## Frontmatter
 #
 # A template file may open with a `---` line, generic `key: value` tags up to
@@ -13936,6 +14310,14 @@ end
 # @example
 #   Template.scan("Hi <%= name %>!").map(~nodes)
 #   # => Ok([Text("Hi "), Interpolate("name"), Text("!")])
+#
+# @example A control tag on a line of its own leaves no blank line behind
+#   Template.scan("<% if admin %>\nWelcome back.\n<% end %>\n").try.nodes
+#   # => [Control("if admin"), Text("Welcome back.\n"), Control("end")]
+#
+# @example Where the template broke, as a position in the source
+#   Template.scan("Hi <%= name")
+#   # => Error(UnterminatedTag(6))
 let scan(source: String) -> Result<Parsed, TemplateError> do
   let cursor = Input { input: source }
   let (frontmatter, afterFrontmatter) = scanFrontmatter(cursor).try
@@ -13943,6 +14325,27 @@ let scan(source: String) -> Result<Parsed, TemplateError> do
   Ok(Parsed { frontmatter: frontmatter, nodes: nodes })
 end
 
+# Escapes the five characters HTML gives special meaning: what `Template.html`
+# (kexhq/kex#171 M3) wraps every `<%= %>` hole in, so an interpolated value
+# can never inject markup or break out of an attribute. `<%== %>` opts out.
+#
+# `&` first, deliberately: escaping it after `<`/`>` would re-escape the
+# `&` those just introduced (`&lt;` -> `&amp;lt;`).
+#
+# @param text [String] the text to escape
+# @return [String] the same text, HTML-safe
+#
+# @example
+#   Template.escapeHtml("<b>Tom & Jerry</b>")
+#   # => "&lt;b&gt;Tom &amp; Jerry&lt;/b&gt;"
+let escapeHtml(text: String) -> String do
+  text.replace("&", "&amp;")
+      .replace("<", "&lt;")
+      .replace(">", "&gt;")
+      .replace("\"", "&quot;")
+      .replace("'", "&#39;")
+end
+
 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.
@@ -14145,6 +14548,58 @@ private do
     chars.join("")
   end
 
+  # A tag that emits nothing of its own. Only these can have their whole
+  # line disappear: a tag that produces output stands in real content, so
+  # the whitespace around it is content too.
+  let silent?(node: Node) -> Bool do
+    match node do
+      Control(_) => true
+      Comment(_) => true
+      _          => false
+    end
+  end
+
+  # Whether the text scanned before a tag leaves the cursor at the start of
+  # a line — nothing but spaces and tabs since the last newline. `prior`
+  # answers it for text that holds no newline at all, carrying forward what
+  # was true before that text: two tags separated by spaces alone are both
+  # still at the start of their line.
+  let atLineStart?(text: String, prior: Bool) -> Bool do
+    let after = text.split("\n").last
+    match after do
+      Just(tail) => text.contains?("\n") then blank?(tail) else prior && blank?(text)
+      None       => prior
+    end
+  end
+
+  # True for text of spaces and tabs alone, the empty string included.
+  let blank?(text: String) -> Bool do
+    text.chars.all? { |ch| ch == ' ' || ch == '\t' }
+  end
+
+  # True when nothing but spaces and tabs stands between `cursor` and the end
+  # of its line. The right half of what makes a tag stand alone; end of input
+  # counts, since there is no trailing content there either.
+  let blankToLineEnd?(cursor: Input) -> Bool do
+    var cur = cursor
+    loop do
+      break if cur.peek != Just(' ') && cur.peek != Just('\t')
+      cur.advance!
+    end
+    cur.peek == None || cur.peek == Just('\n') || cur.peek == Just('\r')
+  end
+
+  # A cursor advanced past the rest of a blank line, its newline included.
+  # What a standalone tag's own line needs once the tag itself is scanned.
+  let skipBlankLineRest(cursor: Input) -> Input do
+    var cur = cursor
+    loop do
+      break if cur.peek != Just(' ') && cur.peek != Just('\t')
+      cur.advance!
+    end
+    skipOneNewline(cur)
+  end
+
   # `<%=`, `<%==`, `<%#`, or plain `<%`, which kind of region this is, and
   # the cursor past the marker.
   let classifyTag(cursor: Input) -> (String, Input) do
@@ -14200,9 +14655,16 @@ private do
   end
 
   # Scans the template body (everything after any frontmatter) into nodes.
+  #
+  # A tag that emits nothing and stands alone on its line takes that line
+  # with it, without being asked: `<% end %>` on a line of its own leaves no
+  # blank line behind, the same as `<%- end -%>`. That is what a template
+  # author means every time, so the trim markers are for the other case — a
+  # tag with real content beside it on the line.
   let scanBody(cursor: Input) -> Result<([Node], Input), TemplateError> do
     var cur = cursor
     var nodes: [Node] = []
+    var lineStart = true
     loop do
       let (text, afterText) = scanText(cur)
       if afterText.peek == None
@@ -14212,12 +14674,20 @@ private do
         return Ok((nodes, afterText))
       end
       let (tag, afterTag) = scanTag(afterText).try
-      let keptText = tag.leftTrim then trimTrailingIndent(text) else text
+      let alone = silent?(tag.node) && atLineStart?(text, lineStart) && blankToLineEnd?(afterTag)
+      let keptText = (tag.leftTrim || alone) then trimTrailingIndent(text) else text
       if !keptText.empty?
         nodes.push!(Text(keptText))
       end
       nodes.push!(tag.node)
-      cur = tag.rightTrim then skipOneNewline(afterTag) else afterTag
+      cur = if alone
+        skipBlankLineRest(afterTag)
+      elif tag.rightTrim
+        skipOneNewline(afterTag)
+      else
+        afterTag
+      end
+      lineStart = alone || tag.rightTrim
     end
   end
 end
@@ -16842,6 +17312,24 @@ make Bool, implement: Truthyable do
   truthy? :> Bool
   let truthy? = this
 
+  # Returns the negation of this boolean.
+  #
+  # +!flag+ says the same thing, and is the spelling to reach for when the
+  # value is already to hand. This one exists for the position +!+ cannot
+  # take: the end of a chain, where what is being negated is whatever the
+  # chain just produced. +falsy?+ answers the same question for any
+  # +Truthyable+ value; +not+ is the one that both takes and answers a +Bool+.
+  #
+  # @return [Bool] +false+ for +true+, and +true+ for +false+
+  #
+  # @example
+  #   true.not    # => false
+  #   false.not   # => true
+  #
+  # @example At the end of a chain
+  #   book.borrowed?.not
+  not :> Bool
+  let not = !this
 end
 
 make Integer, implement: Truthyable do