fusion-lang 0.0.1.alpha2 → 0.0.2

data/docs/lang/implementation.md

@@ -0,0 +1,279 @@
+# Implementation notes — Fusion
+
+Companion to `design.md`. That file records *decisions*; this one explains *how* a
+few non-obvious mechanisms in the interpreter actually work.
+
+## Thunks: laziness, memoization, and bare `@`
+
+A top-level **unit** — a file, an inline (`-e`) program, or a REPL entry — is a
+single expression whose value is computed lazily and at most once. That is a `Thunk`
+(`lib/fusion/interpreter/thunk.rb`): a small state machine over a compute closure.
+
+- `:unforced` → on the first `force`, it runs the closure, stores the result, and
+  becomes `:done`. The closure takes **no arguments**, so the stored result is the
+  same for every reference.
+- `:done` → returns the stored value. **This is the memoization.** It lives on the
+  thunk object itself, not in any lookup table.
+- `:forcing` → re-entered while still computing ⇒ a non-productive data cycle,
+  reported as a `reference_error` at the point the cycle closes.
+
+The subtlety: a unit's *value* is independent of the reference that forced it, but a
+**read failure** is not — a missing file reached as `@a` from one place and `@../a`
+from another must report each reference's own `operation`/`input`/`site`. So the
+closure can't bake those in (it would memoize the *first* reference's error and hand
+it to every later one). Instead, when the unit's own source can't be read the closure
+*raises* `Thunk::ReadFailure` (carrying only the message, no reference). `force`
+catches it and stores the `ReadFailure` itself as the memoized `@value`; then — since
+it alone knows the reference — it builds a fresh `reference_error` from that stored
+failure per call. So the thunk still memoizes once (the read happens once) and caches
+nothing reference-specific. (A parse or evaluation error *is* part of the file's value
+and is memoized and returned as-is.)
+
+Raising — rather than returning a half-built error value — does two things. A read
+failure can never *be* a value, so an uncompleted one can never leak into the value
+space. And it couples `evaluate_file` to the Thunk: run outside one, the `ReadFailure`
+bubbles up and becomes an `internal_error`, instead of silently yielding a placeholder.
+
+A bare `@` means "the value of the current unit", resolved by forcing that unit's
+own thunk.
+
+### Two separate jobs — only one was ever keyed by filename
+
+It is tempting to think memoization is keyed by filename. It is not. There are two
+distinct mechanisms:
+
+1. **Sharing a file's thunk across references.** `@a` reached from many places must
+   load `a.fsn` once. The interpreter keeps `@file_cache` (`abspath → Thunk`); a
+   given file always resolves to the same thunk object. *This* is keyed by the
+   absolute path.
+2. **Memoizing a unit's value, and detecting cycles.** This is the thunk's own
+   `@state`/`@value`. It never consults a filename; it just remembers what it
+   computed.
+
+So the filename is the key for *finding and sharing* a file's thunk — never for the
+memoization itself.
+
+### How a bare `@` reaches its thunk
+
+Each unit puts its own thunk into the **interpreter context** of its environment
+(see below) under `:self`, and `@` forces `env.context(:self)`:
+
+- **Files**: the `:self` thunk is the very same object held in `@file_cache` for
+  that path (`set_context(:self, load_file(abspath))`). So `@` and a sibling `@a`
+  naming the same file share one memoized thunk, and a file that references itself
+  mid-load is caught as a cycle.
+- **Inline / REPL**: there is no path, so the thunk is *only* reachable through the
+  environment binding. A closure captures the env where it was defined, so a bare
+  `@` inside a function resolves to that unit's thunk even when the function is
+  applied much later — which is what makes recursion work. The older filename-only
+  scheme could not express this, which is why inline/REPL had no `@`.
+
+The REPL builds a fresh interpreter per entry, but the thunk object lives in the
+captured environment and outlives any single interpreter: once `:done`, forcing it
+from a later entry simply returns the stored value. So `f = (… @ …)` defined in one
+entry and applied by `5 | f` in the next resolves `@` to `f`.
+
+### When `@` produces something useful
+
+`@` only forces when it is actually evaluated, so the outcome depends on the program,
+not on whether stdin is present:
+
+- In a **function** unit, `@` sits in the unevaluated body, so the unit's value is
+  just the function. Applying it externally — stdin for `-e`, a later entry in the
+  REPL — forces `@` and recurses. With nothing to apply it, the value is the function
+  itself (a `serialization_error` on stdout, or a lenient `"<function>"` in the
+  REPL). Both are valid; neither is a special case.
+- In a **data** position (`[1, @]`), `@` is forced as the unit loads, while its own
+  thunk is still `:forcing` — a non-productive data cycle.
+
+## Environment: bindings vs. interpreter context
+
+`Env` (`lib/fusion/interpreter/env.rb`) holds two separate maps, both walking the
+parent chain:
+
+- **Bindings** (`@vars`) — user-visible identifiers. Pattern binders insert here via
+  `bind`; the REPL keeps a name across entries via `bind(…, checked: false)`. A bare
+  identifier in an expression is resolved here (`lookup`); unbound ⇒ `binding_error`.
+- **Interpreter context** (`@context`) — ambient state the evaluator needs, written
+  with `set_context` and read with `context`, keyed by symbol:
+
+  | key     | contents                                                     | set for                                 |
+  | ------- | ------------------------------------------------------------ | --------------------------------------- |
+  | `:dir`  | the directory `@name` / `@../a` resolve against (a `String`) | every unit (file's dir, else `Dir.pwd`) |
+  | `:file` | the absolute path, for error origins (a `String`)            | files only (absent ⇒ file `"<inline>"`) |
+  | `:self` | the unit's own `Thunk`, forced by a bare `@`                 | every unit                              |
+  | `:jail` | the run's jail root (a `String`, or nil for unconfined)      | once, on the run's root env             |
+  | `:call_site` | the innermost user-code `file`, stamped onto built-in/stdlib errors (a `String`) | a stdlib function's clause env, in `apply` |
+
+The two channels are deliberately separate, and a program reads only the first one.
+So the context names are **not** identifiers: `__dir__`, `__file__`, and `__self__`
+are unbound like any other unknown name (a `binding_error`), not readable values.
+
+In particular `__self__` is **not** a synonym for `@`. `@` *forces* the `:self`
+thunk down to the unit's value; the thunk object itself is not a Fusion value, and
+exposing it would put a non-value into the value space (where it would crash
+serialization). Keeping interpreter context out of the binding namespace is what
+prevents that.
+
+## The jail: confining `@`-resolution
+
+The jail root lives in the environment's `:jail` context (set once on the run's root
+env). Every file reached through an `@`-reference is checked with `within_jail?`, which
+reads the jail from the interpreter's `@env` (`@env.context(:jail)`): the target's
+expanded absolute path must be inside the jail root, or inside the stdlib directory
+(always reachable, since it lives outside any project). A target outside both is a
+`reference_error` (`outside the jail`).
+
+The time of check differs by reference form, because `@name`/`@dir/a` carry a
+built-in/stdlib fallback and `@../a`/`@load` do not:
+
+- `@../a` and `@load` check the jail *before* the file is touched, so an out-of-jail
+  target errors whether or not it exists (it is never probed for existence).
+- `@name`/`@dir/a` resolves *sibling-first*, so the sibling is `File.exist?`-ed to
+  choose between it and the built-in/stdlib fallback. An existing sibling outside the
+  jail then errors (`outside the jail`); a missing one falls through to the fallback.
+
+The jail does **not** cover two things:
+
+- The top-level program file (given explicitly on the CLI) is loaded directly, not
+  through `@`-resolution, so it is never jail-checked — the jail is about what the
+  program may *reach*, not whether it may run.
+- stdin — it is decoded as JSON, never evaluated as Fusion source, so it holds no
+  `@`-references at all.
+
+The check is lexical: `File.expand_path` normalises `..` and existing symlinks are
+followed. The jail confines references to a directory tree; it is not a security
+sandbox. Fusion cannot write files, so no symlink can be planted to escape, but
+existing ones are part of the legitimate project layout. A nil/unset jail means
+unconfined. `CLI.root_environment` defaults it to `Dir.pwd`, and a real CLI run
+instead supplies the program's directory.
+
+The jail rides the environment: the CLI builds the root env once (`root_environment`)
+and passes it to both program loading and `apply`, so every interpreter the run builds
+reads the same `:jail` from its `@env`.
+
+## The error `file`: the innermost user-code call site
+
+A standardized error's `file` is the **innermost user-code file** on the call chain
+when the operation failed — a stdlib frame like `@map` is transparent, so a built-in
+failing inside it reports *your* file, not the stdlib's. It is `Dir.pwd`-relative, or
+`"<inline>"` for an `-e`/REPL entry, or `"<fusion>"` above all user code (a bare
+operation applied straight to a value). Present for `code`/`builtin`/`stdlib` errors;
+absent for the channel/runtime ones (`input`/`output`/`interpreter`), which have no
+call site.
+
+It is filled by two complementary mechanisms, split by *where the error is born*.
+
+### Born in user code → set at birth, from `code_site`
+
+An error raised while evaluating user code (`.name`, `[]`, an unresolved `@`-ref, an
+unbound identifier) is created in `eval_expr` with the env in hand, so it takes its
+`file` straight from `code_site(env)`. This *must* happen at birth: for such an error
+the innermost user file is its own birth location — the deepest user frame, strictly
+below any caller — so no later step could recover it. These errors also routinely
+surface where no `apply` runs (`[1, @undefined]` as a whole program, emitted directly
+with no input applied), so they couldn't be stamped even if we wanted to. (`code_site`
+labels any file under the stdlib directory as `origin: "stdlib"`, so an `origin:
+"code"` error only ever arises in user code — where `code_site`'s file already *is*
+the innermost user file.)
+
+### Born outside user code → stamped at `apply`
+
+A built-in error is built in Ruby; a stdlib error is a `!{…}` raised deep in a stdlib
+body. Neither has the user's env in hand. But both are always produced *inside* an
+`apply` (a built-in runs as `f.fn.call`; a stdlib body runs in `apply`'s `Func`
+branch), and `apply` knows the call site — so `apply` wraps `dispatch_apply` and
+stamps the result with `ErrorVal#with_call_site(call_site)`. The call site is the
+`:call_site` context (`call_site(env)`); a stdlib function's clause env inherits its
+*caller's* `:call_site`, so a built-in failing several stdlib frames deep still reports
+the user's file. Stamping is idempotent (a no-op once a `file` is present), so an error
+is stamped once — at the innermost `apply` that produced it — and outer applies leave
+it alone. No "already-stamped" flag is needed: in the innermost-user-file model the
+call site is constant all the way up a stdlib chain.
+
+### Why the stamp keys on `runtime?`, never `origin`
+
+The stamp must fire for interpreter/stdlib errors but never for an arbitrary user
+`!{…}`. Keying on the payload's `origin` is **unsound** — `origin` is just data, so a
+user writing `!{"origin": "builtin"}` would get a spurious `file`. Provenance isn't
+payload; it is interpreter state, recorded by `ErrorVal#runtime?` (the `@runtime`
+flag). So the gate is two parts:
+
+```ruby
+return self unless @runtime && @payload.is_a?(Hash) && !@payload.key?("file")
+origin = @payload["origin"]
+return self unless origin == "builtin" || origin == "stdlib"
+```
+
+`@runtime` is the **soundness gate** — a user error is never runtime, so a forged
+`origin` can never trigger a stamp. The `origin` check runs only *past* that gate,
+where `origin` is interpreter-set and therefore safe to read; its narrower job is to
+skip runtime errors that have no call site (a JSON-`input` parse `syntax_error` is
+`runtime?` but `origin: "input"`, and rightly gets no `file`).
+
+### Why marking stdlib errors `@runtime` is watertight
+
+`@runtime` is set true in exactly two places, both keyed on interpreter state, never
+on payload content:
+
+1. `ErrorVal.from_runtime` — every interpreter-built error.
+2. An `ErrLit` evaluated **where `code_site(env).origin == "stdlib"`**.
+
+For (2), `env`'s `:file` must lie under `@stdlib_dir` (`file_site` checks
+`start_with?`), and `:file` is set there only by `evaluate_file` loading a file
+resolved via `resolve_builtin_or_stdlib`'s `File.join(@stdlib_dir, …)`. Every user
+route (`@name` siblings, `@../a`, `@load`) resolves into the user's own tree;
+inline/REPL has no `:file` at all. So user code always runs under `origin: "code"`;
+the only way to reach `origin: "stdlib"` is for the code to physically live in the
+interpreter's stdlib directory — which a Fusion program cannot arrange (it can't write
+files, and a project isn't installed there), and which *would be* stdlib if it did.
+Because the flag is set from *where the code runs*, a user writing `!{"origin":
+"stdlib", "runtime": true}` changes only payload fields; the `@runtime` ivar is
+untouched, so the error is never stamped.
+
+Marking the flag at construction (a constructor argument, not a later mutation) keeps
+`@runtime` write-once. A consequence of stdlib errors being runtime errors is that
+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/lang/roadmap.md

@@ -5,18 +5,12 @@ live in [design.md](./design.md); this file is only for things still ahead.
 
 ---
 
-## 1. Ergonomics: the most-wanted improvements
+## 1. Ergonomics
 
-**Operator sugar (planned).** Reintroduce infix `+ - * / % == != < <= > >= && || !`
-and string `++`, desugaring to the existing built-ins over pairs. Pure ergonomics,
-no semantic change. This is the single biggest readability win available and was
-always intended. Open question: exact precedence table and how it interleaves with
-`|` and `=>`.
-
-**`@`-namespace resolution polish.** Decide on project-root confinement
-(sandboxing) for `@../` escapes; consider a configurable standard-library search
-path; consider tooling to surface *which* target a given `@name` resolves to in
-a directory, since shadowing is invisible at the call site.
+**Exposing the current call site** *(use case found; needs a sigil)*. The
+interpreter tracks the current `:file`/`:dir`/`:call_site` as internal context,
+unreadable from a program. User code should be able to mimick our *standardized*
+error payloads. It needs access to `:file` for that.
 
 ---
 
@@ -29,32 +23,26 @@ help in deep pipelines.
 
 ---
 
-## 3. Standard library completion
-
-Populate Tier 1 (written in Fusion): `filter`, `reduce`/`fold`, `reverse`,
-`head`, `tail`, `last`, `init`, `take`, `drop`, `zip`, `flatten`, `member`,
-`find`, `all`, `any`, `count`; comparison derivatives `lessEq`, `greaterThan`,
-`greaterEq`, `notEquals`; object helpers `entries`, `merge`; an
-`if` helper. This is also the best stress test of whether the language is
-pleasant to *write* in, not just to implement.
-
----
-
-## 4. Runtime and tooling
+## 3. Runtime and tooling
 
 - **A faster implementation** once semantics are frozen.
-
-## 5. Open semantic questions to settle
-
-- Numeric tower: keep int/float split, or move to a single number type /
-  arbitrary precision? Affects `divide`, `floor`, `equals`, and the
-  `Integer`/`Float` predicates.
-- Function equality: `equals` on two functions — always `false`, or an error?
-  (Function equality is undecidable beyond trivial identity.)
+- **`fusion --stdlib-path`** *(planned)*. Print the absolute path of the bundled
+  standard library so a user can find, read, copy, or symlink its `.fsn` files —
+  e.g. to make a derived helper like `@range` follow a local `@OP` override:
+  `cp "$(fusion --stdlib-path)/range.fsn" .`. This is the one ergonomics gap in the
+  "reskin the operators" workflow (see how-to-guides). Needs a stable path: on a
+  versioned install the returned directory changes across upgrades, which dangles
+  any symlink made against it — copies are unaffected.
+- **`fusion vendor <name>…`** *(planned)*. Scaffold command: copy the named stdlib
+  files into the current directory as real, editable files. Ergonomic front-end
+  over `--stdlib-path` + `cp` for when a directory reskins `@OP` and wants several
+  helpers that derive from `@OP` (`range`, …) to follow the local override
+  at once. Copies (portable, frozen) rather than symlinks, so it survives upgrades;
+  the copied one-liners can then be hand-edited.
 
 ---
 
-## 6. Bigger experiments
+## 4. Bigger experiments
 
 **Destructuring functions (homoiconicity).** Treat a function as a list of
 `(pattern, output)` clause-pairs and pattern-match on it, enabling macros and
@@ -70,7 +58,3 @@ invertible functions; hopeless for many-to-one. Would change Fusion from
 functional to relational and needs backtracking search. The most exciting and
 most disruptive possible direction; best pursued as a separate mode or sibling
 project rather than folded into the core.
-
-**A static checker.** Because "types" are predicates, an optional static layer
-could attempt to verify predicate-guarded clauses and exhaustiveness without
-changing the dynamic semantics. Speculative.

data/docs/user/explanation.md

@@ -47,12 +47,12 @@ everything else line up. With exactly one input and one output:
 - **Application has one shape:** `value | function`. There is no argument list, no
   call syntax, no arity to track. A pipeline `a | f | g | h` reads like a sentence.
 - **Multi-argument needs are met by data:** pass an array `[a, b]` or an object
-  `{"f": ..., "xs": ...}`. The "arguments" become a value you can also store, inspect,
+  `{"f": ..., "c": ...}`. The "arguments" become a value you can also store, inspect,
   and destructure — there's no separate notion of "argument tuple."
 - **Pattern matching has one job:** match the single input. A function's clauses are
   just alternative shapes that one input might have.
 
-The cost is verbosity in arithmetic (`[a, b] | @add` instead of `a + b`) and a little
+The cost is verbosity in arithmetic (`[a, b] | @OP.sum` instead of `a + b`) and a little
 ceremony for multi-argument library functions. The first is a candidate for later
 syntactic sugar; the second is mild. In exchange, the evaluation model is almost
 trivially simple, which is exactly what you want in a language meant to be small.
@@ -110,7 +110,7 @@ This also resolved the module system for free. If a file is a value, then refere
 a file *is* importing a value — no separate `import` construct, no namespace syntax.
 The directory tree becomes the namespace. The standard library is just a folder of
 files. One mechanism (`@`-references) now does top-level structure, modules, and
-library delivery — and, in the current design, built-in access too: `@add` and
+library delivery — and, in the current design, built-in access too: `@OP` and
 `@Integer` are looked up through the very same `@name` machinery as files. A bare
 `@name` checks for a sibling file, then a built-in, then a standard-library file, so
 your own files can locally shadow a built-in or a stdlib function without affecting
@@ -137,14 +137,9 @@ productive structure surrounds it.
 
 ---
 
-## The roads not taken (and one we're still tempted by)
+## The roads not taken
 
-Two ideas were explored and deliberately set aside, both documented in the design doc.
-
-**Operator sugar.** We could write `a + b` and desugar it to `[a, b] | @add`. We rolled
-this back early to keep the core honest, with the explicit intent to reintroduce it
-once the semantics were settled. It is a pure ergonomics layer; it changes nothing
-underneath.
+Some ideas were explored and set aside for future experiments or a different language.
 
 **Destructuring functions.** The tantalizing one. Since a function literal is visibly
 a list of `pattern => output` clauses, could we pattern-match *on a function*, taking

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

@@ -9,11 +9,12 @@ basics. Scan for the problem you have and copy the solution.*
 
 When you run a program and see an error payload on stderr, the payload itself
 tells you what went wrong. Interpreter errors carry a standardized object whose
-fields (`kind`, `location`, `operation`, `input`, `message`) are documented in
+fields (`kind`, `origin`, `file`, `operation`, `status`, `input`, `expected`,
+`message`) are documented in
 [reference §6.5](./reference.md#65-the-standardized-error-payload).
 
-For a missing file or a parse error in an `@`-referenced file, the `location` and
-`input` fields name the exact path that failed.
+For a missing file or a parse error in an `@`-referenced file, the `file` and
+`input` fields name the path that failed.
 
 ---
 
@@ -25,7 +26,7 @@ Compute a boolean, then pipe it into a two-clause function:
 
 ```fusion
 (n =>
-  [n, 0] | @lessThan | (
+  (n < 0) | (
     true  => "negative",
     false => "non-negative"
   )
@@ -39,8 +40,8 @@ Here's an elegant way of writing FizzBuzz:
 (
   n =>
     [
-      [n, 3] | @mod,
-      [n, 5] | @mod,
+      [n, 3] | @OP.modulo,
+      [n, 5] | @OP.modulo,
     ]
       |
     (
@@ -60,7 +61,7 @@ You could write `sum` like this:
 ```fusion
 (
   [] => 0,
-  [x, ...rest] => [x, rest | @] | @add
+  [x, ...rest] => [x, rest | @] | @OP.sum
 )
 ```
 
@@ -77,7 +78,7 @@ A Fusion function takes exactly one input. Functions that require multiple input
 them into an array (or object) and destructure that in the pattern:
 
 ```fusion
-([a, b] => [a, b] | @add)
+([a, b] => [a, b] | @OP.sum)
 ```
 
 Call it as `[3, 4] | @thatFunction`
@@ -88,7 +89,7 @@ needs the remaining arguments (`y` in the example below). Each `=>` consumes one
 and hands back a function waiting for the next:
 
 ```fusion
-(x => (y => [x, y] | @add))
+(x => (y => [x, y] | @OP.sum))
 ```
 
 Call it as `4 | (3 | @thatFunction)`. `3 | f` yields a one-argument function that adds 3,
@@ -113,24 +114,153 @@ so guard the whole array instead:
 (
   []  => "palindrome",
   [_] => "palindrome",
-  [_, ...rest, _] ? ([first, ..., last] => [first, last] | @equals) => rest | @,
+  [_, ...rest, _] ? ([first, ..., last] => [first, last] | @OP.equal) => rest | @,
   _   => "not a palindrome"
 )
 ```
 
 The outer pattern `[_, ...rest, _]` is what you destructure for retrieving the middle
 of the array which you need to continue your recursion. The inline predicate
-`([first, ..., last] => [first, last] | @equals)` independently destructures the same
+`([first, ..., last] => [first, last] | @OP.equal)` independently destructures the same
 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
 either — but only for files in the same directory, so you can't break things
-globally. Put an `add.fsn` next to your program and every `@add` *in that directory*
-uses yours; files elsewhere still get the built-in.
+globally. Put a `map.fsn` next to your program and every `@map` *in that directory*
+uses yours; files elsewhere still get the standard one.
+
+---
+
+## Reskin the operators (`@OP`) for a directory
+
+The arithmetic, comparison, and boolean operators live in one built-in object,
+`@OP` (`@OP.sum`, `@OP.compare`, `@OP.and`, …), and — like any `@`-name — it is
+resolved per directory. To change what the operators mean for the files in one
+directory (complex numbers, matrices, …), drop an `OP.fsn` there that overrides the
+members you want, reaching the originals with `@@`:
+
+```fusion
+# OP.fsn — this directory's arithmetic
+{ ...@@, "sum": (p => "my sum"), "product": (p => "my product") }
+```
+
+Only files in *that* directory are affected; everything else keeps the defaults. To
+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,
+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),
+so it keeps the default even where you overrode `@OP`. To make it follow your override,
+copy the stdlib file to the directory containing your other overrides. It then
+resolves `@OP` locally:
+
+```sh
+# CAUTION: `fusion --stdlib-path` not implemented yet, determine manually
+
+# copy — portable, a frozen snapshot
+cp "$(fusion --stdlib-path)/range.fsn" .
+```
+
+Your copy of `range.fsn` now resolves `@OP` in its own directory first and will find
+your overrides before the original builtin implementations.
 
 ---
 
@@ -179,7 +309,7 @@ to be called) instead:
 
 ```fusion
 # factorial
-(0 => 1, n ? @Integer => [n, [n, 1] | @subtract | @] | @multiply)
+(0 => 1, n ? @Integer => [n, [n, -1] | @OP.sum | @] | @OP.product)
 ```
 
 If the file evaluates to an **object** and a recursive *helper* lives inside it as a
@@ -190,7 +320,7 @@ by a `.member` access — rather than `@filename.helper`:
 {
   "sumTo": (
     0 => 0,
-    n ? @Integer => [n, [n, 1] | @subtract | @.sumTo] | @add
+    n ? @Integer => [n, [n, -1] | @OP.sum | @.sumTo] | @OP.sum
   )
 }
 ```