fusion-lang 0.0.1.alpha1 → 0.0.1.alpha2

data/docs/user/reference.md

@@ -93,79 +93,89 @@ by the same rule.
 ### 2.5 Grammar (EBNF)
 
 ```ebnf
-file        = expr ;
-
-expr        = pipe ;
-pipe        = prefix { "|" prefix } ;
-prefix      = "!" [ prefix ] | postfix ;            (* bare "!" -> !null *)
-postfix     = primary { "." identifier | "[" expr "]" } ;
-primary     = atom | array | object | function | identifier | fileref | "(" expr ")" ;
-
-fileref     = "@" [ refpath ] ;                     (* bare "@" = current file *)
-refpath     = { "../" } segment { "/" segment } ;   (* ".fsn" implied *)
-segment     = identifier ;
-
-atom        = "null" | "true" | "false" | number | string ;
-                                                    (* errors are `!`+payload (see prefix) *)
-array       = "[" [ elem { "," elem } [ "," ] ] "]" ;
-elem        = expr | spread ;
-spread      = "..." expr ;
-object      = "{" [ member { "," member } [ "," ] ] "}" ;
-member      = string ":" expr | spread ;
-
-function    = "(" clause { "," clause } [ "," ] ")" ;
-clause      = pattern "=>" expr ;
-
-pattern     = errpat | guardedpat ;
-errpat      = "!" | "!" guardedpat ;                (* bare "!" matches any error, binds nothing *)
-guardedpat  = corepat [ "?" predicate ] ;
-predicate   = prefix ;                              (* any expression yielding a function *)
-corepat     = literalpat | bindpat | wildcard | arraypat | objectpat ;
-literalpat  = atom ;
-wildcard    = "_" ;
-bindpat     = identifier ;
-arraypat    = "[" [ pelem { "," pelem } [ "," ] ] "]" ;
-pelem       = guardedpat | "..." [ identifier ] ;
-objectpat   = "{" [ pmember { "," pmember } [ "," ] ] "}" ;
-pmember     = string ":" guardedpat | "..." [ identifier ] ;
-
-identifier  = letter { letter | digit | "_" } ;
-number      = int_lit | float_lit ;
-int_lit     = [ "-" ] digit { digit } ;
-float_lit   = int_lit "." digit { digit } [ exp ] | int_lit exp ;
-exp         = ("e" | "E") [ "+" | "-" ] digit { digit } ;
-string      = '"' { char | escape } '"' ;       (* char excludes raw newline; use \n *)
+file           = expr ;
+
+expr           = pipe ;
+pipe           = prefix { "|" prefix } ;
+prefix         = "!" [ prefix ] | postfix ;            (* bare "!" -> !null *)
+postfix        = primary { "." identifier | "[" expr "]" } ;
+primary        = atom | array | object | function | identifier | fileref | "(" expr ")" ;
+
+identifier     = letter { letter | digit | "_" } ;
+
+atom           = "null" | "true" | "false" | number | string ;
+number         = int_lit | float_lit ;
+int_lit        = [ "-" ] digit { digit } ;
+float_lit      = int_lit "." digit { digit } [ exp ] | int_lit exp ;
+exp            = ("e" | "E") [ "+" | "-" ] digit { digit } ;
+string         = '"' { char | escape } '"' ;           (* char excludes raw newline; use \n *)
+
+array          = "[" [ item { "," item } [ "," ] ] "]" ;
+item           = expr | spread ;
+object         = "{" [ pair { "," pair } [ "," ] ] "}" ;
+pair           = string ":" expr | spread ;
+spread         = "..." expr ;
+
+function       = "(" [ clause { "," clause } [ "," ] ] ")" ;   (* "()" is the empty function *)
+clause         = pattern "=>" expr ;
+
+fileref        = "@" [ refpath ] ;                     (* bare "@" = current file *)
+refpath        = { "../" } segment { "/" segment } ;   (* ".fsn" implied *)
+segment        = identifier ;
+
+pattern        = p_error | p_guarded ;
+p_error        = "!" | "!" p_guarded ;                 (* bare "!" matches any error, binds nothing *)
+p_guarded      = p_core [ "?" predicate ] ;
+predicate      = pipe ;                                (* a `|` chain of functions; the matched value flows in *)
+p_core         = p_literal | p_bind | p_wildcard | p_array | p_object ;
+p_literal      = atom ;
+p_wildcard     = "_" ;
+p_bind         = identifier ;
+
+p_array        = "[" ( p_fixed_items | p_rest_items ) "]" ;
+p_fixed_items  = [ p_items [ "," ] ] ;
+p_rest_items   = [ p_items "," ] p_rest [ "," p_items ] [ "," ] ;
+p_items        = p_item { "," p_item } ;
+p_item         = p_guarded ;
+
+p_object       = "{" ( p_fixed_pairs | p_rest_pairs ) "}" ;
+p_fixed_pairs  = [ p_pairs [ "," ] ] ;
+p_rest_pairs   = [ p_pairs "," ] p_rest [ "," ] ;
+p_pairs        = p_pair { "," p_pair } ;
+p_pair         = string ":" p_guarded ;
+
+p_rest         = "..." [ identifier ] ;
+
 ```
 
+### 2.6 Context-sensitive rules the grammar cannot express
+
+Object literals and object patterns may not repeat a fixed key. `{"a": …, "a": …}`
+is a `syntax_error`. Keys arriving through `...spread` / `...rest` are dynamic and
+not checked.
+
 ---
 
 ## 3. Functions and application
 
-A function is an ordered list of clauses. Applying a function to a value `v`:
-
-1. If the function value itself is an error (e.g. piping into an unresolved name),
-   that error is the result.
-2. Otherwise clauses are tried in order. The first clause whose pattern matches
-   `v` produces the result, evaluated with that clause's bindings in scope.
-3. If a `?` predicate evaluates to an error during matching, that error becomes
-   the function's result; no further clauses are tried (see §6.4).
-4. **If no clause matches:** the result is `v` itself when `v` is an error
-   (propagation — an unmatched error is never silently swallowed), and `null`
-   otherwise (the lenient default).
-
-A consequence of rule 4: a function with error clauses that only match *some*
-shapes of error (e.g. `(!42 => "got 42", _ => "ok")`) still propagates any
-other-shaped error it receives — `!"oops"` is not caught by `!42`, the `_`
-clause rejects errors, no clause matches, so `!"oops"` propagates. To handle
-"any unrecognized error" you must add a catch-all error clause: `!` (or
-equivalently `!_`) for "catch any error, ignore the payload"; `!msg` to bind
-the payload.
+A function is an ordered list of clauses `pattern => expression`. The literal `()`
+is the empty function, with no clauses.
 
 Functions take exactly one argument. Multiple arguments are passed as an array or
-object. Currying is done by returning a function: `(x => (y => [x, y] | @add))`.
+object.
+
+Applying a function to a value (`value | function`):
+1. Clauses are tried in order. The first clause whose pattern matches `value`
+   produces the result, evaluated with that clause's bindings in scope.
+2. If a `?` predicate evaluates to an error during matching, that error becomes
+   the function's result; no further clauses are tried (see §6.4).
+3. If no clause matches:
+   - Unmatched errors propagate.
+   - For unmatched regular values the function returns `null`.
 
 Functions are values: they may be elements of arrays, values of object keys, results
-of clauses, and arguments to other functions.
+of clauses, and arguments to other functions. However, they may not cross the CLI
+boundary (see §9.3).
 
 ---
 
@@ -173,17 +183,17 @@ of clauses, and arguments to other functions.
 
 A pattern both tests structure and extracts parts. Pattern forms:
 
-| Form                                       | Matches                                   | Binds                              |
-| ------------------------------------------ | ----------------------------------------- | ---------------------------------- |
-| literal (`42`, `"x"`, `true`, `null`)      | exactly that value                        | nothing                            |
-| `_` (wildcard)                             | anything **except** an error              | nothing                            |
-| identifier (`a`)                           | anything **except** an error              | the value, under that name         |
-| Fixed size arrays, e.g. `[x_1, x_2]`       | array of matching length, elementwise     | each `x_i` binds                   |
-| Variably arrays, e.g. `[p, ...rest]`       | array with ≥ fixed elements               | `rest` = remaining elements        |
-| Fixed member objects, e.g. `{"a": p}`      | object having key `a` (and others)        | as `p` binds                       |
-| Variable objects, e.g. `{"a": p, ...rest}` | object                                    | `rest` = unmatched key/value pairs |
-| `corepat ? pred`                           | `corepat` matches **and** pred is `true`  | as `corepat` binds                 |
-| `!`, `!_`, `!pat`                          | an error; `!pat` destructures the payload | as `pat` binds                     |
+| Form                                       | Matches                                    | Binds                              |
+| ------------------------------------------ | ------------------------------------------ | ---------------------------------- |
+| literal (`42`, `"x"`, `true`, `null`)      | exactly that value                         | nothing                            |
+| `_` (wildcard)                             | anything **except** an error               | nothing                            |
+| identifier (`a`)                           | anything **except** an error               | the value, under that name         |
+| Fixed size arrays, e.g. `[x_1, x_2]`       | array of matching length, elementwise      | each `x_i` binds                   |
+| Variable arrays, e.g. `[p, ...rest]`       | array with ≥ fixed elements                | `rest` = remaining elements        |
+| Fixed member objects, e.g. `{"a": p}`      | object whose keys are **exactly** `a`      | as `p` binds                       |
+| Variable objects, e.g. `{"a": p, ...rest}` | object having key `a` (extra keys allowed) | `rest` = unmatched key/value pairs |
+| `p_core ? pred`                            | `p_core` matches **and** pred is `true`    | as `p_core` binds                  |
+| `!`, `!_`, `!pat`                          | an error; `!pat` destructures the payload  | as `pat` binds                     |
 
 Rules:
 
@@ -208,19 +218,27 @@ Rules:
 - May appear at most once.
 - In an array pattern it may appear in any position and captures the start / middle / end
   of the array.
-- In an object pattern it may appear at the end and captures all keys not explicitly matched.
+- In an object pattern it must be the last member and captures all keys not explicitly matched.
 - A bare `...` with no name matches without binding.
-- An object pattern matches if all its named keys are present; extra keys are allowed
-  (and captured by `...rest` if present).
+- An object pattern is **open** if it carries a `...rest` (named or bare `...`). Otherwise
+  it is **closed**. A **closed** object pattern matches only objects whose keys are *exactly*
+  the named keys. An **open** object pattern also matches objects with additional keys.
 
 ---
 
 ## 5. The `?` predicate (refinement / types)
 
-`corepat ? predicate` matches when `corepat` matches structurally **and** piping the
-matched value into `predicate` yields exactly `true`. The predicate is any
+`p_core ? predicate` matches when `p_core` matches structurally **and** piping the
+matched value through `predicate` yields a **truthy** result. Truthiness is
+Ruby-style: every value is truthy except `false` and `null` (so `0` and `""` are
+truthy). The built-ins `@and` / `@or` / `@not` apply the same test.
+
+The predicate is a `|` chain of functions, and the matched value flows in from the
+left: `a ? b | c` matches when `a` matches and `a | b | c` is truthy. A single-stage
+predicate (`n ? @Integer`) is just the one-function case. Each stage is any
 expression evaluating to a function (a name, a member access, or an inline function
-literal).
+literal). If applying the predicate produces an error, that error bubbles up as the
+function's result (see §6.4).
 
 "Types" are not a separate construct: the built-in predicates `@Integer`, `@String`,
 etc. are ordinary functions returning booleans, reached with `@` and used with `?`
@@ -230,21 +248,29 @@ etc. are ordinary functions returning booleans, reached with `@` and used with `
 
 ## 6. Errors
 
-An **error value** is `!` followed by a payload: `!42`, `!"divide by zero"`,
-`!{"kind":"missing_key","key":"id"}`, `!null`. The payload may be any regular Fusion
-value (including `null`). Not allowed are functions and nested errors.
+An **error value** is `!` followed by a payload:
+- `!null`
+- `!42`
+- `!"oops"`
+- `!{"kind":"missing_key","key":"id"}`
+
+The payload may be any regular Fusion value. Errors can't nest (§6.3). Instead the inner
+error will propagate.
 
 Error values are distinct from ordinary data:
 - `null` means legitimate absence.
 - An error means something went wrong.
 
+Errors produced by the interpreter itself all share one standardized payload shape,
+documented in §6.5.
+
 ### 6.1 Constructing errors
 
 In expression position, `!` is a prefix operator that constructs an error from its
 operand:
 
 - `!42` is an error with payload `42`.
-- `!"oops"` is an error with payload the string `"oops"`.
+- `!"oops"` is an error with the string `"oops"` as payload.
 - `!` alone (with nothing following it) is shorthand for `!null`.
 - `!expr` where `expr` itself evaluates to an error **propagates** that inner error
   rather than wrapping it (so you cannot accidentally bury an error inside another
@@ -263,7 +289,7 @@ In pattern position, `!` introduces an **error pattern**:
 | `!_`                | any error; payload is not bound. Can carry a predicate (`!_ ? @pred`).   |
 | `!pattern`          | any error with a **payload** that matches `pattern`                      |
 
-The payload pattern (the `pattern` in `!pattern`) is a full `guardedpat`:
+The payload pattern (the `pattern` in `!pattern`) is a full `p_guarded`:
 - It uses the same destructuring semantics you know from regular values.
 - It fully supports `?` predicates. Predicates only refer to the payload, not the `!`.
   Caution: `! ? @Integer` is a syntax error. The bare `!` has no payload pattern
@@ -297,8 +323,8 @@ particular built-ins:
   evaluating an element/member. `[1, !"bad", 2]` evaluates to `!"bad"`, not to
   an array of three things.
 - **Constructing an error from an erroring expression** propagates the inner
-  error rather than wrapping it. `!([5,0] | @divide)` evaluates to
-  `!"divide: division by zero"`, never to an error wrapping an error. (This
+  error rather than wrapping it. `!([5,0] | @divide)` evaluates to the division
+  error itself (a `math_error`, §6.5), never to an error wrapping an error. (This
   preserves the rule that there is never more than one error simultaneously.)
 - **When the function value itself is an error** (e.g. `value | @undefined_name`
   where `@undefined_name` resolves to an error), that error is the result.
@@ -312,22 +338,64 @@ treated as program failures, not as "no match." This is the key reason to make
 your predicates *total* (end with `_ => false`): a predicate that can crash will
 short-circuit your whole function.
 
-### 6.5 Sources of errors
+### 6.5 The standardized error payload
 
-Built-in errors are produced by:
+There are two origins of error values, and they differ in payload:
 
-- A strict function (`_ => !`) on no match — payload `null`.
-- Built-in operations on bad input — payload is a descriptive string,
-  e.g. `"divide: division by zero"`, `"add: expected a pair of numbers"`.
-- Member access on a missing key or non-object, index out of range, or bad index
-  type — payload is a structured object like
-  `{"kind":"missing_key","key":"foo"}` or `{"kind":"index_out_of_range",...}`.
-- Spread of a non-array or non-object — `{"kind":"spread_non_array",...}`.
-- Unresolved `@`-reference — `{"kind":"unresolved_ref","name":"..."}`.
-- Non-productive data cycle — `{"kind":"data_cycle","path":"..."}`.
-- Applying a non-function — `{"kind":"apply_non_function","got":"..."}`.
+- **Interpreter errors** — produced by the language itself (a bad built-in call,
+  an unresolved `@`-reference, a parse failure, …). Every interpreter error
+  carries one **standardized payload**: a JSON object with a fixed set of fields,
+  documented here. The uniform shape lets one catch clause dispatch on a single
+  field, e.g. `(!{"kind": "math_error"} => …)`. Standard library functions
+  adhere to this same structure.
+- **User errors** — built with `!payload` (§6.1). The payload is whatever you
+  give it: any Fusion value, with no required shape.
 
-User code constructs errors with `!payload` as described above.
+#### Payload shape
+
+```json
+{"kind": "type_error", "location": "builtin add", "operation": "add", "input": [1, "x"], "message": "expected numbers"}
+```
+
+| Field       | Required | Meaning                                                                                                                    |
+| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `kind`      | yes      | The error category, from the closed set below.                                                                             |
+| `location`  | yes      | Where the failing operation lives, from the closed set below.                                                              |
+| `operation` | yes      | A short description of the operation that failed, e.g. `"\|"`, `".name"`, `"[2]"`, `"add"`, `"reading file"`, `"parsing"`. |
+| `input`     | yes      | The operand(s) the operation received — often the offending value; for member/index access it is `[object, key]`.          |
+| `message`   | no       | Extra human-readable detail, e.g. `"expected an object"`.                                                                  |
+
+#### `kind` — the closed set
+
+| `kind`                | Raised when                                                                                                    |
+| --------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `syntax_error`        | source code, or the JSON input, fails to parse.                                                                |
+| `reference_error`     | an `@`-reference cannot be resolved: unknown name, file not found, a file-system failure, a non-productive data cycle, or a `@`-self-reference with no current file. |
+| `type_error`          | a value has the wrong type for an operation (expected X / a type mismatch); also applying a non-function, spreading a non-array/object, member access on a non-object, or a wrong-typed index. |
+| `argument_error`      | a built-in receives the wrong number/shape of arguments (e.g. not a pair), or an `array`/`object`-mode input envelope has the wrong shape (§9.4). Its `message` states the expected shape as a Fusion pattern where possible (the pair-built-ins report `expected [_, _]`). |
+| `binding_error`       | reading an unbound identifier, or binding the same name twice in one clause.                                   |
+| `access_error`        | a missing object key or an out-of-range array index — and nothing else (a non-object member access or a wrong-typed index is a `type_error`). |
+| `math_error`          | division or modulo by zero, or a non-finite number.                                                            |
+| `conversion_error`    | a value cannot be converted (`@toString` of an unconvertible type, `@parseNumber` of a non-numeric string).    |
+| `stack_error`         | recursion too deep (a stack overflow).                                                                         |
+| `serialization_error` | a result, or a user error's payload, has no JSON form — see §9.3.                                              |
+
+#### `location` — the closed set
+
+| `location`      | Meaning                                                           |
+| --------------- | ----------------------------------------------------------------- |
+| `builtin X`     | the built-in named X, e.g. `builtin divide`.                      |
+| `stdlib X`      | the standard-library file X.                                      |
+| `code X`        | the user source file X (basename).                                |
+| `code <inline>` | an inline `-e` program or a REPL statement.                       |
+| `input`         | the input channel (stdin or the CLI-argument).                    |
+| `output`        | the output channel (the serialized result).                       |
+| `interpreter`   | the interpreter itself, e.g. a stack overflow.                    |
+
+`input` and `output` name the data channels; they **never** refer to the program
+source, which always reports as `code X`.
+
+User errors don't have to adhere to this standard.
 
 ---
 
@@ -341,21 +409,21 @@ input that is not of the queried type (they never return `!`).
 
 ### 7.1 Arithmetic (operations)
 
-| Name       | Input             | Result                                             |
-| ---------- | ----------------- | -------------------------------------------------- |
-| `add`      | `[number, number]`| sum                                                |
-| `subtract` | `[number, number]`| difference                                         |
-| `multiply` | `[number, number]`| product                                            |
+| Name       | Input             | Result                                                                 |
+| ---------- | ----------------- | ---------------------------------------------------------------------- |
+| `add`      | `[number, number]`| sum                                                                    |
+| `subtract` | `[number, number]`| difference                                                             |
+| `multiply` | `[number, number]`| product                                                                |
 | `divide`   | `[number, number]`| quotient; integer if evenly divisible, else float; `!` if divisor is 0 |
-| `mod`      | `[number, number]`| remainder; `!` if divisor is 0                     |
-| `negate`   | `number`          | negation                                           |
-| `floor`    | `number`          | floor (integer)                                    |
+| `mod`      | `[number, number]`| remainder; `!` if divisor is 0                                         |
+| `negate`   | `number`          | negation                                                               |
+| `floor`    | `number`          | floor (integer)                                                        |
 
 ### 7.2 Comparison (operations)
 
-| Name        | Input                                   | Result          |
-| ----------- | --------------------------------------- | --------------- |
-| `equals`    | `[any, any]`                            | deep structural equality (boolean) |
+| Name        | Input                                   | Result                                   |
+| ----------- | --------------------------------------- | ---------------------------------------- |
+| `equals`    | `[any, any]`                            | deep structural equality (boolean)       |
 | `lessThan`  | `[number, number]` or `[string, string]`| boolean; `!` on mismatched/invalid types |
 
 Other comparisons (`lessEq`, `greaterThan`, `greaterEq`, `notEquals`) are specified
@@ -363,11 +431,14 @@ for the standard library, derivable from `equals` and `lessThan`.
 
 ### 7.3 Boolean (operations)
 
-| Name  | Input                | Result        |
-| ----- | -------------------- | ------------- |
-| `and` | `[boolean, boolean]` | logical and   |
-| `or`  | `[boolean, boolean]` | logical or    |
-| `not` | `boolean`            | logical not   |
+These judge **truthiness** (the same Ruby-style test as `?` predicates: every value
+is truthy except `false` and `null`), not strict booleans, and always return a boolean.
+
+| Name  | Input    | Result                                              |
+| ----- | -------- | --------------------------------------------------- |
+| `and` | `[_, _]` | `true` if both operands are truthy                  |
+| `or`  | `[_, _]` | `true` if either operand is truthy                  |
+| `not` | `_`      | `true` if the operand is falsey (`false` or `null`) |
 
 ### 7.4 Strings and structure bridges (operations)
 
@@ -381,11 +452,31 @@ for the standard library, derivable from `equals` and `lessThan`.
 | `parseNumber` | string                      | integer or float; `!` if not numeric    |
 | `keys`        | object                      | array of key strings                    |
 | `values`      | object                      | array of values                         |
+| `get`         | `[array, int]` or `[object, string-key]` | element at that index/key (like `[]`, §8); `!` if out of range / missing |
+| `set`         | `[array, int, value]` or `[object, string-key, value]` | a **new** array/object with that entry set; an array index must already exist, an object key may be new |
+| `toObject`    | `[[string-key, value], …]`  | object built from entries; later duplicate keys win |
 
 ### 7.5 Type predicates (predicates)
 
-`Integer`, `Float`, `Number`, `String`, `Boolean`, `Array`, `Object`, `Null`. Each
-takes any value and returns a boolean. `Number` is true for integers and floats.
+Each of these functions takes any input value and returns a boolean. This set of
+functions provides a runtime type system.
+
+| Name        | `true` for                           | Equivalent pattern |
+| ----------- | ------------------------------------ | ------------------ |
+| `Null`      | `null`                               | `null`             |
+| `Boolean`   | `true`, `false`                      |                    |
+| `Integer`   | integers                             |                    |
+| `Float`     | floats                               |                    |
+| `Number`    | integers and floats                  |                    |
+| `String`    | strings                              |                    |
+| `Array`     | arrays                               | `[_]`              |
+| `Object`    | objects                              | `{_}`              |
+| `Function`  | any function (builtin, stdlib, user) |                    |
+| `NonFinite` | "Infinity", "-Infinity", "NaN"       |                    |
+
+Notes:
+- Booleans are separate from numbers. There's no automatic type conversion (`false` <-> `0`, `true` <-> `1`).
+- The set of values without JSON representation (§9.3) is exactly `Function` + `NonFinite`
 
 ### 7.6 Special built-ins: `ENV` and `load`
 
@@ -481,11 +572,12 @@ above. Recursion through functions is not a data cycle.
 
 ### 9.3 Runtime contract
 
-The interpreter reads standard input as JSON, converts it to a Fusion value `v`,
-computes `v | programFunction`, and prints the result on standard output as JSON.
+The default use case (**pipe**) reads standard input as JSON, converts it to a
+Fusion value `v`, computes `v | programFunction`, and prints the result on
+standard output as JSON.
 
-- Empty input is treated as `null`.
-- Non-JSON input yields an error (payload `{"kind":"stdin_not_json"}`).
+- Empty input is treated as `null` (in every input mode).
+- Non-JSON input yields a `syntax_error` at `location: "input"` (§6.5).
 - **If the final result is an error**, the interpreter prints **nothing** to
   standard output, prints the error's **payload** (as JSON) to standard error, and
   exits with status `1`. Otherwise the result is printed to standard output and the
@@ -493,13 +585,135 @@ computes `v | programFunction`, and prints the result on standard output as JSON
   stdout stream carries the value-or-nothing, the stderr stream carries the failure
   detail, and the exit code is `0`/`1` accordingly.
 
-### 9.4 Command-line interface
+This stdout/stderr/exit-code split is the **unix** output mode — the default for
+the pipe use case. §9.4 describes the other ways an error can cross the boundary,
+§9.5 the streaming use case, and §9.6 the REPL.
+
+**Serialization.** A function and a non-finite float number have no JSON form.
+How one is rendered depends on where it sits:
+
+- In a **result** or inside a **user error's** payload, they can't be serialized.
+  The whole output becomes a `serialization_error`.
+- Inside an **interpreter error's** payload, it is serialized leniently as a
+  string:
+  - a function renders as `"<function>"`
+  - a non-finite number as `"<Infinity>"` / `"<-Infinity>"` / `"<NaN>"`
+
+Note:
+- If a regular value or user error fails to serialize strictly, the resulting
+  `serializaton_error` will be an interpreter error and will subsequently
+  serialize leniently to preserve as much information about the root error as
+  possible.
+
+### 9.4 Input and output modes
+
+An error value cannot cross the CLI boundary as plain JSON — something must mark
+it as an error. The **input mode** and the **output mode** define that marking.
+They are independent of each other and selected with the `--input` and `--output`
+flags:
+
+- **`unix`** — the input is plain JSON and always a value; the `-!` flag marks
+  the whole input as an error value instead (its JSON becomes the payload).
+  Output: a value goes to stdout with exit code `0`; an error's payload goes to
+  stderr with exit code `1` (§9.3).
+- **`bang`** — a leading `!` marks an error value; the payload is the JSON after
+  the `!`. A lone `!` is `!null`, like the language's bare `!`. Output is always
+  on stdout and the exit code is always `0`. A `!`-marked line is not valid JSON;
+  that is the price of the most lightweight marking.
+- **`array`** — everything is wrapped in an envelope: `[0, value]` for a value,
+  `[1, payload]` for an error. Output is always on stdout, exit code always `0`.
+- **`object`** — the envelope is `{"value": value}` for a value, `{"error": payload}`
+  for an error. Output is always on stdout, exit code always `0`.
+
+A malformed `array`/`object` input envelope (any other shape; the array tag must
+be exactly the integer `0` or `1`) is an `argument_error` at `location: "input"`.
+Like any input failure it flows into the program as an error and is catchable.
+
+Mode support per use case (defaults in bold):
+
+| Use case   | `unix`   | `bang`   | `array` | `object` |
+| ---------- | -------- | -------- | ------- | -------- |
+| pipe       | **yes**  | yes      | yes     | yes      |
+| `--stream` | no       | **yes**  | yes     | yes      |
+| `--repl`   | —        | —        | —       | —        |
+
+The unix mode spends the process's only exit code and both standard streams on a
+single result, so it cannot mark errors per record in a stream; the stream use
+case therefore excludes it. The REPL is interactive and has no modes at all.
+
+### 9.5 Streaming (`--stream`)
+
+`fusion --stream` loads the program once, then treats standard input and output
+as NDJSON streams: each input line is decoded per the input mode, piped through
+the program, and printed as one output line encoded per the output mode.
+
+- Blank lines are skipped; every other input line produces exactly one output line.
+- Errors stay in-band, so a failing record — including a stack overflow — becomes
+  that record's output line and the stream continues. The exit code is always `0`.
+- A program that fails to load answers every record with that same load error.
+
+### 9.6 The REPL (`--repl`)
+
+`fusion --repl` starts an interactive session. It loads no program, takes no
+pipeline input, has no input/output mode, and always exits `0`. Each entry is
+read, evaluated, and its result printed. An entry is one of:
+
+- an **expression** — evaluated and printed; or
+- a **statement** — an assignment that also binds a name:
 
+```ebnf
+statement = identifier "=" expr ;
 ```
-fusion <file.fsn> [json-input]
-fusion -e '<source>' [json-input]
+
+A statement evaluates `expr`, prints the result, and binds it to `identifier`
+for later entries. Bare identifiers read earlier bindings; `@`-references resolve
+relative to the working directory.
+
+- Results print leniently (§9.3): a function prints as `"<function>"` instead of
+  becoming a `serialization_error`.
+- An error prints as `!payload`. A statement binds an error result like any other
+  result; reading that identifier later propagates the error, exactly as reading an
+  `@`-reference that resolved to one. (Pattern binders never capture an error, but a
+  statement is an assignment, not a pattern match.)
+- Rebinding a name is allowed; later entries see the new value.
+- A bound function can call itself through its own name
+  (`fact = (0 => 1, n => [n, [n,1] | @subtract | fact] | @multiply)`), because
+  the name is looked up at application time.
+- Entries report errors at `location: "code <inline>"`, like `-e` programs.
+
+**Input editing.** An entry is submitted only once it parses as a complete
+statement or expression; until then — whether still unfinished or not yet valid —
+the session opens a new line so the entry can be finished or corrected. An entry
+may therefore span multiple lines (continuation lines show `...> `); on an empty
+continuation line, backspace returns to the previous line. The prompt and the
+echoed input render on **stderr** (like a shell prompt), so stdout carries only
+the stream of results. End the session with Ctrl-D; Ctrl-C discards the entry
+being typed.
+
+### 9.7 Command-line interface
+
 ```
+usage: fusion [options] <file.fsn> [json-input]
+       fusion [options] -e '<source>' [json-input]
+       fusion --repl
+
+use cases:
+  (default)       pipe: apply the program to one input
+  --stream        apply the program to each line of an NDJSON stream
+  --repl          interactive expressions and `identifier = expression`
+
+options:
+  -e '<source>'   inline program instead of a file
+  --input MODE    how the input marks an error value (§9.4)
+  --output MODE   how the output marks an error value (§9.4)
+  -!              treat the input as an error value (unix input mode only)
+```
+
+In the pipe use case, input comes from the `[json-input]` argument if present,
+otherwise from standard input. The stream use case always reads standard input
+and accepts no input argument.
 
-Input comes from the `[json-input]` argument if present, otherwise from standard
-input. Setting the environment variable `FUSION_DEBUG` causes file-not-found and
-parse errors during reference resolution to be reported on standard error.
+A command-line misuse (an unknown flag, an unsupported mode combination, a
+missing program) is reported as plain usage text on stderr with exit code `1`.
+It happens before the input/output contract begins, so it is not a payloaded
+error.

data/docs/user/tutorial.md

@@ -5,8 +5,8 @@ every example. By the end you will have written a recursive program and understo
 Fusion's pieces fit together.*
 
 > **What you need:** Ruby installed and the `fusion` interpreter available on your
-> `PATH` (along with its bundled `stdlib/` folder). All commands below can be run
-> from any directory containing your `.fsn` files.
+> `PATH`. All commands below can be run from any directory containing your `.fsn`
+> files.
 
 ---
 
@@ -271,15 +271,16 @@ wrong? Try dividing by zero. Save as `boom.fsn`:
 echo '5' | fusion boom.fsn
 ```
 
-You will see no output on stdout, a message like `"divide: division by zero"` on
-stderr, and the process will exit with status `1`. The result *was* an error, and
-the interpreter knows the difference: it routes the error's **payload** to
-stderr, leaves stdout empty, and signals failure. That makes Fusion programs
-well-behaved Unix filters.
+You will see no output on stdout, an error payload like
+`{"kind":"math_error",…,"message":"division by zero"}` on stderr, and the process
+will exit with status `1`. The result *was* an error, and the interpreter knows
+the difference: it routes the error's **payload** to stderr, leaves stdout empty,
+and signals failure. That makes Fusion programs well-behaved Unix filters.
 
-An error is always written as `!` followed by a **payload** — any regular JSON value.
-The built-ins above produced `!"divide: division by zero"` (an error whose payload
-is a string). You can construct your own:
+An error is always written as `!` followed by a **payload**. Errors the
+interpreter produces (like the one above) use a standardized payload shape —
+see [reference §6.5](./reference.md#65-the-standardized-error-payload). You can
+also construct your own, with any payload you like:
 
 | Example                             | Meaning                  |
 | ----------------------------------- | ------------------------ |