fusion-lang 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6571414d6f0a1f977f517652742c7b2766d7a17577f0276163856ff992bc7bc0
-  data.tar.gz: 1f4f3a71cbfe0a18e18e91276b0ade75ea5c49a5b9a531097b739e8f04929b24
+  metadata.gz: be9bb991ddd9049b4dfbf56cd1b71395941e6836acb71272be3a72588cf80aea
+  data.tar.gz: e47c996224e5ffa767095f8be75c9c0728df566ba7463d351e065925e36cd5d7
 SHA512:
-  metadata.gz: e4f9a32c372aea8633c1e66ab883015674d052ca83cccfab10c693f65ac805d90b4d768e1f78a4fb1a77745c158e6a39d56fa25ff9cae16cc29c765c22480ca7
-  data.tar.gz: 7feb41d65c7be52ee4a92c820edd714b8ef28b6e0c5e9a6726d1a7c41963e9f3ff4d36b7cb89afacba1256cdc675c8a4a0c5c34d6ca5865e8106f4efe70fc4c7
+  metadata.gz: fa9b652f9f19d74561245a6948726ecef900ff4e40ba2fd3d8fda66f36cf68a0fc54fc7369ee78094794a083a6519c78751c4e0c8b5b3cd7cf1a99cfca55ff00
+  data.tar.gz: 66cc3557d141785c1075f3483c894140bb7d94c9fa8634a069713b84b00c72ae3852e395637d750e4da0486079fad96edd378677e8070b811f2500e39220763a

data/.mutant.yml

@@ -0,0 +1,24 @@
+---
+requires:
+  - ./lib/fusion
+
+integration:
+  name: rspec
+  # Optional per integration arguments. Proxies through to the integrations native CLI processor.
+  # Currently for minitest integration arguments are ignored.
+  # Note that when set this *OVERWRITES* the hardcoded defaults mutant provides. So should you
+  # provide your own arguments, for rspec you *need* to specify the `spec` directory at a minimum.
+  # Mutant is not compatible with many rspec options, take care you do not violate mutants invariants.
+  # During CLI executions you can manually add new integration arguments via `--integration-argument`,
+  # you have to specify it once per argument, so: `--integration-argument seed --integration-argument 0`
+  # would execute rspec with the `--seed 0` flag.
+  # Below shows an example configuring rspec to use a static seed from the config file.
+  arguments:
+  - --fail-fast # rspec integration default, keep this when specifying manual options!
+  - --options
+  - .rspec-ci
+  - spec # spec directory
+
+matcher:
+  subjects:
+  - Fusion*

data/.simplecov

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Central SimpleCov configuration, shared by
+# - the in-process suite (spec/spec_helper.rb)
+# - the subprocesses spawned to drive the real binary (spec/simplecov_spawn.rb)
+SimpleCov.configure do
+  enable_coverage :branch
+
+  add_group "Fusion", "lib/"
+  add_group "Tests", "spec/"
+end

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+This project adheres to [Break Versioning](https://www.taoensso.com/break-versioning).
+
+## [Unreleased]
+
+### Breaking
+
+- The stdlib functions `@lt`, `@lte`, `@gt`, `@gte` have been turned into builtins
+  and moved into the `@OP` object. Migration:
+  - `@lt` -> `@OP.lt`
+  - `@lte` -> `@OP.lte`
+  - `@gt` -> `@OP.gt`
+  - `@gte` -> `@OP.gte`
+  Their errors now report `"origin": "builtin"`.
+- The builtin `@toObject` has been moved to the stdlib. Its regular behavior stayed
+  the same, but its errors now report `"origin": "stdlib"`.
+- The `expected` strings of many error payloads have been improved. Consumers that
+  matched the exact `expected` text need to update.
+- The stdlib function `@concat` has been extended to be n-ary. Consumers that relied
+  on an error if the number of given strings wasn't equal to 2 need to update.
+
+### Non-breaking
+
+- New syntax sugar has been introduced:
+  - `a < b` is `[a, b] | @OP.compare | @OP.lt`
+  - `a <= b` is `[a, b] | @OP.compare | @OP.lte`
+  - `a > b` is `[a, b] | @OP.compare | @OP.gt`
+  - `a >= b` is `[a, b] | @OP.compare | @OP.gte`
+- New builtin predicates:
+  - `@Collection`: true for arrays and objects.
+- New stdlib functions:
+  - `@entries`: an object's `[key, value]` pairs, the inverse of `@toObject`.
+  - `@zip`: turns a pair of equal-length arrays into an array of `[left, right]` pairs.
+  - `@safe`: the error catcher `(! => false, v => v)`
+- New stdlib modules:
+  - `matrix/` (including the matrix operator set `@matrix/OP`)
+  - `vector/`
+
+## [0.0.1] - 2026-07-04
+
+Release the first non-alpha version of Fusion.

data/README.md

@@ -77,7 +77,8 @@ Refer to the [Documentation](docs/index.md) for further information.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Run `bin/console` for an interactive prompt that will allow you to experiment.
+- Run `bundle install` to install dependencies.
+- Run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ### Tests
 

data/Rakefile

@@ -12,6 +12,14 @@ namespace :spec do
   RSpec::Core::RakeTask.new(:all) do |task|
     task.rspec_opts = "--options .rspec-ci"
   end
+
+  desc "Run mutation testing"
+  task :mutant do
+    command = "bundle exec mutant run --usage opensource"
+    # On CI, let mutant use all available cores.
+    command += " --jobs 8" unless ENV["CI"]
+    sh command
+  end
 end
 
 task default: :spec

data/docs/lang/design.md

@@ -475,7 +475,7 @@ Refines §2.9: same general shape, more orthogonal fields, field values easier t
 - 🧑 ✅ Split `location` into `origin` (where the operation is *defined*) and an optional `file` (the **innermost user-code file** on the call chain).
 - 🧑 ✅ `file` is `Dir.pwd`-relative, so it reads as the route from the location where `fusion` was called to the offending source code.
 - 🧑 ✅ Split `status` out from `input`. `status` is `0` (a value) or `1` (an error). On `1`, `input` carries the error's bare payload, so `input` is always valid JSON.
-- 🧑 ✅ `operation` now contains the failing operation's own **`@`-reference** (`@`, `@@`, `@lt`, `@math.round`, `@../mod`, `@load`) or for Built-in *syntax* its own form (`|`, `.key`, `[]`, `parsing code`). Loading the top-level program file is `loading code` (not an `@`-reference).
+- 🧑 ✅ `operation` now contains the failing operation's own **`@`-reference** (`@`, `@@`, `@range`, `@math.round`, `@../mod`, `@load`) or for Built-in *syntax* its own form (`|`, `.key`, `[]`, `parsing code`). Loading the top-level program file is `loading code` (not an `@`-reference).
 - 🧑 ✅ An `@`-reference takes no argument, so its `input` is `null` and its `status` is always `0`. `@load` is the exception: it's a function taking a filename.
 - 🧑 ✅ For *access errors* the "key" appears only once:
   - `.name` carries the static key in `operation` and the object alone in `input`
@@ -851,8 +851,6 @@ error value can cross the boundary.
 
 **I/O modes** — how an error is marked crossing the boundary; `--input` and `--output` are independent:
 
-TODO: Under `-!` the input is the error payload, so empty stdin is a usage error (nothing to mark).
-
 - 🧑 ✅ Four modes: **unix** (asymmetric, Unix filter) and **bang** / **array** (`[0, value]` / `[1, payload]`), **object** (`{"value": _}` / `{"error": _}`).
 - 🧑 ✅ **unix**: input is `stdin` + `-!` flag, output is `value → stdout` + `exit 0` OR `error → stderr` + `exit 1`. stdin/stdout/stderr are always pure JSON.
 - 🧑 ✅ **bang**: shortest encoding, errors are simply a `!` prefix and thus not valid JSON.
@@ -1008,7 +1006,7 @@ TODO: Under `-!` the input is the error payload, so empty stdin is a usage error
 ### Decisions
 
 - 🧑 ✅ Bundle the most important arithmetic and logic operations together into a single `@OP` reference.
-- 🧑 ✅ Make the `stdlib` as orthogonal as possible to `@OP`.
+- 🧑 ✅ Make the `stdlib` as orthogonal as possible to `@OP`. Addendum: this only applies to top-level stdlib functions. *Modules* like `matrix` are exempt.
 - 🧑 ✅ Higher-order helpers (`map`, `filter`, `reduce`, `compact`, `flatten`, `any`, `all`) are implemented via recursion in Fusion, not hidden in Ruby. They work for both arrays and objects where possible.
 - 🧑 ✅ Provide access to more advanced mathematical operations in `@math`.
 - 🧑 ✅ Where possible, builtins and stdlib functions are n-ary instead of binary.
@@ -1026,7 +1024,7 @@ TODO: Under `-!` the input is the error payload, so empty stdin is a usage error
 ### Cons
 
 - Not all operators with syntax sugar have been grouped into `@OP`. Exceptions are the structural operators `@map`, `@filter`, `@reduce`.
-- The few helpers that still reference `@OP` (currently only `@range`) will ignore `@OP` overrides. To make them aware of `@OP` overrides, create a copy of their `stdlib` source code next to your `OP.fsn`.
+- The few top-level stdlib functions that still reference `@OP` (currently only `@range`) will ignore `@OP` overrides. To make them aware of `@OP` overrides, create a copy of their `stdlib` source code next to your `OP.fsn`.
 - The native way of writing division `[a, b | @OP.negate] | @OP.product` is numerically incorrect and might produce a double rounding error. For the numerically correct division you have to use `@math.divide`.
 
 ---
@@ -1058,7 +1056,58 @@ runtime node is the `[=]` setter.
 - 🤖 ⏪ Lex negative-number literals (JSON-style). Rewound: `a-3` would be ambiguous between the literal `-3` and subtraction.
 - 🤖 ❌ Desugar every `-x` to `x | @OP.negate`, dropping literal negatives. Rejected: `-5` should stay a plain literal, not an `@OP`-routed computation.
 - 🤖 ❌ Assemble the path in the parser so `@a / b` is also the path `a/b` (divide via `(@a) / b`). Rejected: a spaced `@a / b` should read as division like every other operator.
+- 🤖 ❌ Make `&&` / `||` short-circuiting by desugaring to clause dispatch. Rejected: the boolean operators would no longer be reskinnable.
 
 ### Pros
 
 - Giving `pipe` the tightest precedence keeps the "useful reading" paren-free: a pipe's RHS has to always be a function and arithmetic never yields one, so `x|@f + 1` can only sensibly mean `(x|@f) + 1`.
+
+### Cons
+
+- By desugaring `==`/`&&`/`||` into an n-ary `@OP.equal`/`@OP.and`/`@OP.or`, the logic operators can never be short-circuiting. All inputs will be evaluated up front before getting passed to the `@OP` operator as an array. The first erroring input will propagate. The only way to create real short-circuiting is by using **clause bodies**: `a | (true => b, _ => false)`.
+
+---
+
+## 5.7 Comparison operators `<` `<=` `>=` `>`
+
+Extends the §5.6 syntax sugar with comparisons.
+
+### Decisions
+
+- 🧑 ✅ The builtins `@OP.lt` / `@OP.gt` / `@OP.lte` / `@OP.gte` map an `@OP.compare` result (`-1`/`0`/`1`) to a boolean. They pass `null` through to make partial orders possible.
+- 🧑 ✅ The inequality operator `a < b` is syntax sugar for the function chain `[a, b] | @OP.compare | @OP.lt`. Likewise `<=` / `>` / `>=` via `@OP.lte` / `@OP.gt` / `@OP.gte`.
+- 🤖 ✅ The comparisons sit at the ordering level with `??`: binary, left-associative, no folding.
+
+### Alternatives
+
+- 🧑 ⏪ The comparisons previously were stdlib functions (`@lt`, `@gt`, `@lte`, `@gte`), because they can be built in Fusion natively. Superseded: as they are now target of syntax sugar, they have been moved into `@OP`.
+- 🧑 ❌ Four direct pair-comparing members (`[a, b] | @OP.lt`). Rejected: they are semantically coupled to `@OP.compare`. Keeping them consistent would have required to always override all of them together with `@OP.compare`.
+
+### Pros
+
+- `@OP.compare` stays the single ordering primitive. The four operators are thin readers of its result. Shadowing `@OP.compare` keeps the semantics of all 5 syntax sugar operators `??`, `<`, `<=`, `>` and `>=` in sync.
+
+### Cons
+
+- Comparisons don't chain: `a < b < c` is not `a < b && b < c`.
+
+---
+
+## 5.8 Stdlib modules
+
+### Decisions
+
+- 🧑 ✅ Stdlib modules are directories (`@matrix/...`, `@vector/...`).
+- 🧑 ✅ Stdlib modules may ship shadowed default operators (`@matrix/OP`).
+
+### Alternatives
+
+- 🧑 💭 Don't ship a preconstructed `@matrix/OP` and require users to manually assemble it themselves.
+
+### Pros
+
+- Pointing a directory's `OP.fsn` at `@matrix/OP` switches the arithmetic operators `+`, `-`, `*`, `/` to matrix operations. A linear-system solver can be expressed by `([a, b] => /a * b)`.
+
+### Cons
+
+- `@matrix/...` methods make frequent use of `@@`. This makes the `@matrix/...` module unable to compose with other definitions of the basic arithmetic operations (like complex numbers).

data/docs/lang/implementation.md

@@ -236,3 +236,44 @@ Marking the flag at construction (a constructor argument, not a later mutation)
 they serialize **leniently** (functions → `"<function>"`, non-finite → `"<Infinity>"`),
 which made the old `| @sanitize` in stdlib error payloads redundant; it was dropped,
 and `sanitize.fsn` remains as a standalone utility.
+
+## `Unreachable` is relative to the `exe/fusion` entry point
+
+`raise Unreachable` asserts "no input can steer execution here **from `exe/fusion`**":
+the lexer/parser only emit the known token/node classes and `Options.parse` only
+produces the known use cases and modes, so from the binary the guarded arms are dead
+— reaching one is by definition an interpreter bug, the one deliberate exception to
+"no raw Ruby errors on stderr" (design §2.9). The claim says nothing about the more
+granular Ruby seams: calling `Fusion::CLI` or `Fusion::Interpreter` directly *can*
+reach the guards by handing over a bogus node or use case, which is exactly how the
+specs prove they exist (`cli_spec.rb`, `error_kinds_spec.rb` "internal invariant
+guards"). For the same reason the guards carry no `:nocov:` markers: the four with
+such specs count as covered, the rest as honest misses.
+
+## Mutant test selection: the `mutant_expression` tags
+
+Mutation testing (`.mutant.yml`, subjects `Fusion*`) kills a mutation by re-running
+specs **inside the mutant worker's process** — the mutated method exists only in that
+process's memory, never on disk. Two consequences shape how the specs are wired up:
+
+- The subprocess-driven specs (`cli_subprocess_spec.rb`, `repl_pty_spec.rb`) can never
+  kill a mutation: they spawn `exe/fusion`, which loads the pristine code from disk.
+  Their prose describe titles keep them out of selection, deliberately.
+- Mutant does not select tests by coverage. mutant-rspec parses the first word of each
+  example's description into an expression (`RSpec.describe Fusion::CLI` →
+  `Fusion::CLI`); a prose title is unaddressable. The `mutant_expression` metadata is
+  the explicit override, which is why every `expect_pipe` spec file is tagged
+  `mutant_expression: "Fusion::CLI*"` — the entry point the spec harness drives.
+
+For each subject, mutant walks the subject's match expressions most-specific-first —
+`Fusion::Interpreter#load_file`, then `Fusion::Interpreter*`, then `Fusion*` — and
+**stops at the first level that matches any tests**. The tagged battery matches at the
+`Fusion::CLI*` level (CLI subjects, alongside `cli_spec.rb`) and at the `Fusion*`
+fallback (all other subjects).
+
+**Caveat — preemption.** The fallback reaches the tagged specs only because no spec
+file describes an inner scope directly. Adding a `RSpec.describe Fusion::Interpreter`
+file would match at the `Fusion::Interpreter*` level and silently preempt the whole
+tagged battery for every interpreter mutation — most kills would vanish. When adding
+such a file, extend the language specs' tags to cover that scope too
+(`mutant_expression` accepts an array).

data/docs/user/how-to-guides.md

@@ -26,7 +26,7 @@ Compute a boolean, then pipe it into a two-clause function:
 
 ```fusion
 (n =>
-  [n, 0] | @OP.compare | @lt | (
+  (n < 0) | (
     true  => "negative",
     false => "non-negative"
   )
@@ -126,6 +126,84 @@ array again to compare its two ends.
 
 ---
 
+## Short-circuit a chain of checks
+
+`&&` and `||` are **eager**. `a && b` desugars to `[a, b] | @OP.and` — an array
+piped into a function — so both operands are computed before the operator sees
+them. The same goes for a hand-written conditions array `[a, b, c] | @OP.and`:
+an array literal evaluates all of its elements, and if one of them is an error,
+the error propagates out of the literal immediately. No piped form can keep its
+input from being computed.
+
+The one place where Fusion is lazy is a **clause body**: it evaluates only when
+its clause's pattern matches. To run check B only if check A passed, put B in a
+body that A's success selects. For boolean conditions:
+
+```fusion
+a | (true => b, _ => false)   # short-circuiting a && b
+a | (true => true, _ => b)    # short-circuiting a || b
+```
+
+For example, `x | @Array | (true => x | @size > 0, _ => false)` safely tests
+"a non-empty array": fed `5`, it yields `false` without ever piping the number
+into `@size`.
+
+In a guard, the same sequencing falls out of the stages pattern → predicate →
+body, each of which runs only after the previous one succeeded. `@zip`
+validates "a pair of equal-length arrays" like this:
+
+```fusion
+[xs, ys] ? ([a ? @Array, b ? @Array] => a | @size == b | @size)
+```
+
+The size comparison lives in the predicate's body, so it is computed only after
+the pattern has established that both elements are arrays — `@size` can never
+see a non-array. Sequencing matters because a predicate that *errors* does not
+fall through to the next clause — the error propagates.
+
+For a longer chain of checks you have two options. You can keep sequencing by
+nesting another predicate between pattern and body — the checks stay lazy, and
+a broken predicate still fails loudly. Or you can accept that every condition
+is computed and route any error into "no match" by piping a conditions array
+through `@OP.and | @safe`, one condition per line. `@matrix/sum` checks "an
+array, non-empty, all matrices, all of equal dimensions" like this:
+
+```fusion
+matrices ? (ms => [
+    ms | @Array,
+    ms | @size > 0,
+    {"c": ms, "f": @Matrix} | @all,
+    ms |: @dimensions | @OP.equal,
+  ] | @OP.and | @safe)
+```
+
+Fed `[5]`, the last condition errors (`@dimensions` of the number `5`), the
+error collapses the conditions array — an array literal propagates an error
+element, and `@OP.and` passes an error through untouched — and `@safe` turns
+it into `false`: the clause simply doesn't match, and the input falls through
+to the function's own error clause. Two things to keep in mind:
+
+- `@safe` is just the two-clause function `(! => false, v => v)`, and it needs
+  both clauses: the error clause alone would turn every *successful* condition
+  into `null` — a value that matches no clause yields `null` — and the guard
+  would go falsey for valid inputs too.
+- Catching trades loudness for flatness. Errors-as-false means a genuinely
+  broken condition (a typo'd reference, a wrong shape) reads as "the guard is
+  false for every input" instead of crashing. Prefer sequenced clauses where
+  the checks order themselves structurally anyway.
+
+Eager conditions are fine when they are safe on the already-matched input.
+After `[x ? @Matrix, row ? @Integer, col ? @Integer]` has matched, bounds
+checks like `row >= 0 && row < x | @size` cannot error, and the flat `&&`
+chain reads best — the structural pattern is what bought that safety.
+
+(`@all` and `@any` do short-circuit, but at the level of applying their
+predicate to already-computed items: the first falsey/truthy item stops the
+testing. That protects against a predicate erroring on a later item, not
+against computing the items themselves.)
+
+---
+
 ## Shadow a built-in or stdlib function locally
 
 Because a sibling file wins over a built-in or the standard library, you can override
@@ -152,14 +230,21 @@ Only files in *that* directory are affected; everything else keeps the defaults.
 check whether a directory changed the operators, look for an `OP.fsn` — there is no
 other way to change them.
 
+The standard library ships one ready-made reskin: an `OP.fsn` containing just
+`@matrix/OP` gives the directory matrix arithmetic — `a + b` elementwise, `a * b`
+the matrix product, `a / b` multiplication by the inverse, `%`/`//` always an
+error — built on the helpers `@matrix/multiply`, `@matrix/determinant`,
+`@matrix/scale`, and `@matrix/rotate`.
+
 ### Making a named derived helper follow your override
 
 Most stdlib helpers are deliberately **immune** to your override, so a reskin can't
 break them by accident: `@truthy`/`@falsey` decide truthiness by pattern matching,
-`@compact` drops nulls by pattern matching too, and the comparison helpers
-`@lt`/`@gt`/`@lte`/`@gte` interpret an `@OP.compare` *result* (you write
-`[a, b] | @OP.compare | @lt`, so the compare step already follows your override while
-the interpretation stays fixed).
+and `@compact` drops nulls by pattern matching too. The comparison readers
+`@OP.lt`/`@OP.gt`/`@OP.lte`/`@OP.gte` interpret an `@OP.compare` *result*, and both
+steps of `a < b` (= `[a, b] | @OP.compare | @OP.lt`) resolve through `@OP` — so
+overriding `compare` alone already reskins the comparisons, and an `OP.fsn` that
+spreads `...@@` keeps the original readers.
 
 One helper still calls `@OP` internally — `@range` uses `@OP.sum` and `@OP.compare` —
 and, like `@`-names everywhere, it resolves `@OP` in *its own* directory (the stdlib),

data/docs/user/reference.md

@@ -48,7 +48,7 @@ Precedence, tightest to loosest:
    `|+` (reduce). Left-associative (`a | f | g` ≡ `(a | f) | g`).
 5. Multiplicative: `*`, `/`, `%`, `//`. Left-associative.
 6. Additive: `+`, `-`. Left-associative.
-7. Ordering: `??`. Left-associative.
+7. Ordering: `??` and the comparisons `<`, `<=`, `>`, `>=`. Binary, left-associative.
 8. Equality: `==`.
 9. Logical and: `&&`.
 10. Logical or: `||`.
@@ -105,7 +105,7 @@ expr           = logical_or ;
 logical_or     = logical_and { "||" logical_and } ;
 logical_and    = equality { "&&" equality } ;
 equality       = ordering { "==" ordering } ;
-ordering       = additive { "??" additive } ;
+ordering       = additive { ( "??" | "<" | "<=" | ">" | ">=" ) additive } ;
 additive       = multiplicative { ( "+" | "-" ) multiplicative } ;
 multiplicative = pipe { ( "*" | "/" | "%" | "//" ) pipe } ;
 pipe           = unary { ( "|" | "|:" | "|?" | "|+" ) unary } ;
@@ -194,6 +194,7 @@ member (§7.6), or, for the map-pipes, into a stdlib call.
   a % b        →  [a, b] | @OP.modulo
   a // b       →  [a, b] | @OP.quotient
   a ?? b       →  [a, b] | @OP.compare
+  a < b        →  [a, b] | @OP.compare | @OP.lt     (likewise <= / > / >= via @OP.lte / @OP.gt / @OP.gte)
   a == b == c  →  [a, b, c] | @OP.equal
   a && b && c  →  [a, b, c] | @OP.and
   a || b || c  →  [a, b, c] | @OP.or
@@ -209,15 +210,17 @@ Folding and associativity:
 - A maximal run of `*`/`/` folds into one `@OP.product`; each `/` term is inverted via
   `@OP.invert` (never a literal, so `1/x` stays a float and `/0` stays a runtime error).
 - Runs of `==`, `&&`, `||` fold n-ary into `@OP.equal` / `@OP.and` / `@OP.or`.
-- `%`, `//`, `??` are binary and left-associative; they sit at their level and break a
-  fold run: `a * b % c` is `(a * b) % c`; `a ?? b == 0` is `(a ?? b) == 0`.
+- `%`, `//`, `??`, `<`, `<=`, `>`, `>=` are binary and left-associative; they sit at
+  their level and break a fold run: `a * b % c` is `(a * b) % c`; `a ?? b == 0` is
+  `(a ?? b) == 0`. Comparisons do not chain: `a < b < c` is `(a < b) < c`, which
+  errors at runtime (a boolean is not comparable).
 
 Because pipe binds tighter than the value operators, `x|@f + 1` is `(x|@f) + 1`; to pipe a
-computed value onward, parenthesize it: `(a + b)|@f`, `(a ?? b)|@gt`.
+computed value onward, parenthesize it: `(a + b)|@f`, `(a < b)|@f`.
 
-Comparisons: `a == b` is equality. `a < b` needs to be expressed as `(a ?? b) | @lt`
-(likewise `@gt` / `@lte` / `@gte`), since `??` yields the `-1`/`0`/`1` ordering those
-stdlib helpers interpret.
+Comparisons: `a == b` is equality; `a < b` (and `<=` / `>` / `>=`) orders two numbers
+or two strings. `??` exposes the underlying `-1`/`0`/`1` ordering that the comparison
+desugaring reads through `@OP.lt` / `@OP.lte` / `@OP.gt` / `@OP.gte` (§7.2).
 
 ---
 
@@ -379,7 +382,10 @@ particular built-ins:
   that clause must match the specific error received. An error of a shape no
   clause catches propagates unchanged.
 - **Built-in and stdlib operations (`@math.divide`, `@OP.sum`, `@Integer`, …) all
-  propagate** their input error without examining it. To inspect or compare an
+  propagate** their input error without examining it. The one deliberate
+  exception is the stdlib catcher `@safe` — an ordinary two-clause function
+  `(! => false, v => v)` that catches any error into `false` and passes regular
+  values through. To inspect or compare an
   error's payload, you must catch it first and operate on the extracted payload:
   `!42 | (!a => a) | @Integer` returns `true` (the payload `42` *is* an integer);
   `!42 | @Integer` returns `!42` (the predicate doesn't handle the error,
@@ -476,8 +482,7 @@ below are the built-in names; write `@` before them to use them. **Operations**
 input that is not of the queried type (they never return `!`).
 
 The operators (`+ - * / == < …` and the boolean ops) live in the shadowable `@OP`
-object (§7.6); a directory reskins them by placing an `OP.fsn`. Their **named** forms
-below are stdlib functions built on `@OP.*`, so they follow a per-directory override.
+object (§7.6); a directory reskins them by placing an `OP.fsn`.
 
 ### 7.1 Arithmetic
 
@@ -492,22 +497,21 @@ division and the other numeric functions live in `@math` (§7.6a): `@math.divide
 
 Equality is `@OP.equal` (deep structural equality of a pair; §7.6) — used directly,
 there is no `@eq` helper. Ordering is `@OP.compare`, which returns `-1`/`0`/`1`. The
-named boolean forms **interpret that result** and are applied *after* it:
-
-| Name  | `-1`   | `0`    | `1`    | `null` |
-| ----- | ------ | ------ | ------ | ------ |
-| `lt`  | `true` | `false`| `false`| `null` |
-| `gt`  | `false`| `false`| `true` | `null` |
-| `lte` | `true` | `true` | `false`| `null` |
-| `gte` | `false`| `true` | `true` | `null` |
-
-So `a < b` is written `[a, b] | @OP.compare | @lt` (with sugar: `(a ?? b) | @lt`; equality
-is `a == b` — see §2.7). Because the caller invokes
-`@OP.compare`, the ordering follows a per-directory `@OP` override while the helper
-itself is fixed and shadow-independent. A partial order whose `compare` returns `null`
-for incomparable operands passes that `null` straight through; any other input is an
-`argument_error`. A type mismatch surfaces as `@OP.compare`'s own error, before the
-helper runs.
+comparison members **interpret that result** and are applied *after* it:
+
+| Member   | `-1`   | `0`    | `1`    | `null` |
+| -------- | ------ | ------ | ------ | ------ |
+| `OP.lt`  | `true` | `false`| `false`| `null` |
+| `OP.gt`  | `false`| `false`| `true` | `null` |
+| `OP.lte` | `true` | `true` | `false`| `null` |
+| `OP.gte` | `false`| `true` | `true` | `null` |
+
+`a < b` desugars to exactly this pipeline: `[a, b] | @OP.compare | @OP.lt` (likewise
+`<=` / `>` / `>=`; equality is `a == b` — see §2.7). Both steps resolve `@OP` per
+directory, so an override reskins the ordering and its reading together. A partial
+order whose `compare` returns `null` for incomparable operands passes that `null`
+straight through; any other input is an `argument_error`. A type mismatch surfaces
+as `@OP.compare`'s own error, before the reader runs.
 
 ### 7.3 Boolean
 
@@ -530,11 +534,13 @@ everything except `false`/`null`, and `@falsey` is its complement.
 | `parseNumber` | string                      | integer or float; `!` if not numeric    |
 | `keys`        | object                      | array of key strings                    |
 | `values`      | object                      | array of values                         |
-| `toObject`    | `[[string-key, value], …]`  | object built from entries; later duplicate keys win |
 
-`concat` (`[string, string]` → concatenation) and `chars` (string → array of its
-characters) are **standard-library** functions built on `join` / `split`, not
-built-ins.
+`concat` (array of strings, any length → concatenation) and `chars` (string →
+array of its characters) are **standard-library** functions built on `join` /
+`split`, not built-ins. So are `entries` (object → array of its `[key, value]` entries, in
+insertion order; built on `keys`) and `toObject` (`[[string-key, value], …]` →
+object, later duplicate keys win; built on the `[=]` setter). They are inverses:
+`obj | @entries | @toObject` is `obj`.
 
 Indexed read (`x[k]`) and write (`x[k = v]`) are **core syntax**, not built-ins — there
 is no `@get`/`@set`; see §8.
@@ -554,6 +560,7 @@ functions provides a runtime type system.
 | `String`    | strings                              |                    |
 | `Array`     | arrays                               | `[_]`              |
 | `Object`    | objects                              | `{_}`              |
+| `Collection`| arrays and objects                   |                    |
 | `Function`  | any function (builtin, stdlib, user) |                    |
 | `NonFinite` | "Infinity", "-Infinity", "NaN"       |                    |
 
@@ -570,9 +577,10 @@ elements); `compare` reports an ordering. The infix operators (§2.7) desugar to
 
 `@OP` is **shadowable per directory**: place an `OP.fsn` sibling that overrides members
 (spread the originals with `@@`) to reskin the operators — complex numbers, matrices,
-ternary logic — for that directory only. The comparison helpers in §7.2 (`@lt`, `@gt`, …)
-interpret an `@OP.compare` result, so ordering follows a local override the moment the
-caller pipes through `@OP.compare` (see the how-to guide).
+ternary logic — for that directory only. The comparison members (§7.2: `lt`, `gt`,
+`lte`, `gte`) interpret an `@OP.compare` *result* rather than comparing values
+themselves, so an override of `compare` alone already reskins `a < b` (see the
+how-to guide).
 
 | Member        | Input                                    | Result                                                   |
 | ------------- | ---------------------------------------- | -------------------------------------------------------- |
@@ -584,6 +592,10 @@ caller pipes through `@OP.compare` (see the how-to guide).
 | `OP.modulo`   | `[integer, integer]`                     | integer remainder; `!` on a non-integer or a `0` divisor |
 | `OP.equal`    | array (any element types)                | deep equality: `true` iff every element equals the first |
 | `OP.compare`  | `[number, number]` or `[string, string]` | `-1` / `0` / `1` (first smaller / equal / larger)        |
+| `OP.lt`       | a compare result (`-1`/`0`/`1`/`null`)   | `true` for `-1`, else `false`; `null` passes through     |
+| `OP.gt`       | a compare result                         | `true` for `1`                                           |
+| `OP.lte`      | a compare result                         | `true` for `-1` / `0`                                    |
+| `OP.gte`      | a compare result                         | `true` for `0` / `1`                                     |
 | `OP.and`      | array                                    | `true` if every element is truthy (`true` for `[]`)      |
 | `OP.or`       | array                                    | `true` if any element is truthy (`false` for `[]`)       |
 | `OP.not`      | `_`                                      | `true` if the operand is falsey                          |
@@ -717,9 +729,8 @@ Two built-ins are special in how they resolve:
 - **`@ENV`** resolves (at step 2) to a fresh object of environment variables.
 - **`@load`** resolves (at step 2) to a function that loads a file by a **verbatim**
   filename string — no `.fsn` is appended — relative to the referencing directory,
-  returning that file's value. If the argument is not a string, or the file does not
-  exist, the result is an error (`{"kind":"load_bad_arg",...}` or
-  `{"kind":"file_not_found","path":...}` respectively). This is the only way to load
+  returning that file's value. A non-string argument is an `argument_error`; a
+  missing file is a `reference_error` (`file not found`). This is the only way to load
   a file whose name is computed at runtime or is not a plain identifier (e.g.
   `"data.config.fsn"`).
 

data/docs/user/tutorial.md

@@ -127,7 +127,7 @@ number's absolute value:
 
 ```fusion
 (n =>
-  [n, 0] | @OP.compare | @lt | (
+  [n, 0] | @OP.compare | @OP.lt | (
     true  => n | @OP.negate,
     false => n
   )
@@ -142,9 +142,10 @@ echo '5'  | fusion lesson.fsn    # => 5
 ```
 
 Read the middle line carefully: `[n, 0] | @OP.compare` orders the pair as `-1`/`0`/`1`,
-and `@lt` turns that into `true`/`false`. That boolean is then piped into a *second,
-inline function* whose two clauses are the two branches. **An `if` is just a function
-with a `true` clause and a `false` clause.**
+and `@OP.lt` turns that into `true`/`false` (the infix `n < 0` is sugar for exactly
+this pipeline). That boolean is then piped into a *second, inline function* whose two
+clauses are the two branches. **An `if` is just a function with a `true` clause and a
+`false` clause.**
 
 Note: you don't need to restrict yourself to the two values `true` and `false` as
 an intermediate result. Don't use it purely as an `if / else`. Use it like a `case`
@@ -216,7 +217,7 @@ Create a function that sorts a pair of values:
 
 ```fusion
 (
-  [a, b] ? (p => p | @OP.compare | @lt) => [a, b],
+  [a, b] ? (p => p | @OP.compare | @OP.lt) => [a, b],
   [a, b] => [b, a]
 )
 ```

data/examples/double.fsn

@@ -1,4 +1,7 @@
+# Double every number in an array or object.
+# Equivalent to: (c ? @Collection => c |: (n => 2 * n))
 (
   [] => [],
-  [first, ...rest] => [2 * first, ...rest|@]
+  [first, ...rest] => [2 * first, ...rest|@],
+  obj ? @Object => obj | @entries |: ([key, value] => [key, 2 * value]) | @toObject
 )

data/examples/factorial.fsn

@@ -1,6 +1,9 @@
 # Factorial: n! for a non-negative integer.
 (
-  _ ? (i ? @Integer => (i ?? 0)|@lt, _ => true) => !"Only non-negative integers, please!",
-  0 => 1,
-  n => n * (n - 1)|@
+  n ? (i ? @Integer => i >= 0) =>
+    n | (
+      0 => 1,
+      n => n * (n - 1)|@
+    ),
+  _ => !"Only non-negative integers, please!"
 )

data/examples/gcd.fsn

@@ -0,0 +1,9 @@
+# Greatest common divisor of a pair of non-negative integers (Euclidean algorithm).
+(
+  pair ? ([a ? @Integer, b ? @Integer] => a >= 0 && b >= 0) =>
+    pair | (
+      [a, 0] => a,
+      [a, b] => [b, a % b] | @
+    ),
+  _ => !"Only pairs of non-negative integers, please!"
+)

data/examples/matrix/OP.fsn

@@ -0,0 +1,2 @@
+# This directory computes with matrices: the operators are the matrix reskin.
+@matrix/OP

data/examples/matrix/average.fsn

@@ -0,0 +1,2 @@
+# Average two matrices: elementwise sum, then halve each entry.
+([a, b] => [0.5, a + b] | @matrix/scale)

data/examples/matrix/solve.fsn

@@ -0,0 +1,2 @@
+# Solve the linear system a * x = b for x (b a column matrix): x = a⁻¹ * b.
+([a, b] => /a * b)