fusion-lang 0.0.1.alpha2 → 0.0.1

data/docs/user/reference.md

@@ -41,13 +41,19 @@ Precedence, tightest to loosest:
 
 1. Primary: literals, `[...]`, `{...}`, `(...)` grouping, function literals,
    identifiers, `@`-references.
-2. Postfix member/index access: `x.key`, `x[expr]`.
-3. Error prefix: `!expr` (construct an error). Bare `!` (with no operand) is the
-   same as `!null`.
-4. Pipe (application): `value | function`. Left-associative
-   (`a | f | g` ≡ `(a | f) | g`).
-5. Clause arrow: `=>` (loosest, so the entire right-hand side of a clause is one
-   expression).
+2. Postfix: member access `x.key`, index read `x[expr]`, index write `x[key = value]`.
+3. Unary prefix: `!x` (construct an error; bare `!` is `!null`), `-x` (negate),
+   `/x` (invert), `~x` (logical not).
+4. Pipe (application) and map-pipes: `value | function`, `|:` (map), `|?` (filter),
+   `|+` (reduce). Left-associative (`a | f | g` ≡ `(a | f) | g`).
+5. Multiplicative: `*`, `/`, `%`, `//`. Left-associative.
+6. Additive: `+`, `-`. Left-associative.
+7. Ordering: `??`. Left-associative.
+8. Equality: `==`.
+9. Logical and: `&&`.
+10. Logical or: `||`.
+11. Clause arrow: `=>` (loosest, so the entire right-hand side of a clause is one
+    expression).
 
 ### 2.2 Function literals
 
@@ -95,17 +101,25 @@ by the same rule.
 ```ebnf
 file           = expr ;
 
-expr           = pipe ;
-pipe           = prefix { "|" prefix } ;
-prefix         = "!" [ prefix ] | postfix ;            (* bare "!" -> !null *)
-postfix        = primary { "." identifier | "[" expr "]" } ;
+expr           = logical_or ;
+logical_or     = logical_and { "||" logical_and } ;
+logical_and    = equality { "&&" equality } ;
+equality       = ordering { "==" ordering } ;
+ordering       = additive { "??" additive } ;
+additive       = multiplicative { ( "+" | "-" ) multiplicative } ;
+multiplicative = pipe { ( "*" | "/" | "%" | "//" ) pipe } ;
+pipe           = unary { ( "|" | "|:" | "|?" | "|+" ) unary } ;
+unary          = "!" [ unary ]                          (* bare "!" -> !null; "!x" builds an error *)
+               | ( "-" | "/" | "~" ) unary              (* negate / invert / not; operand required *)
+               | postfix ;
+postfix        = primary { "." identifier | "[" expr [ "=" expr ] "]" } ;   (* "[e]" reads, "[e = e]" writes *)
 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 } ;
+number         = int_lit | float_lit ;                 (* unsigned; a negative is unary "-" *)
+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 *)
@@ -119,8 +133,8 @@ spread         = "..." expr ;
 function       = "(" [ clause { "," clause } [ "," ] ] ")" ;   (* "()" is the empty function *)
 clause         = pattern "=>" expr ;
 
-fileref        = "@" [ refpath ] ;                     (* bare "@" = current file *)
-refpath        = { "../" } segment { "/" segment } ;   (* ".fsn" implied *)
+fileref        = ( "@" | "@@" ) [ path ] ;             (* bare "@"/"@@" = current unit / its super *)
+path           = { ".." "/" } segment { "/" segment } ;   (* one tight lexer token; ".fsn" implied *)
 segment        = identifier ;
 
 pattern        = p_error | p_guarded ;
@@ -128,7 +142,7 @@ p_error        = "!" | "!" p_guarded ;                 (* bare "!" matches any e
 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_literal      = atom | "-" number ;                   (* "-" number is a negative literal *)
 p_wildcard     = "_" ;
 p_bind         = identifier ;
 
@@ -154,6 +168,57 @@ 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.
 
+A file-reference **path** is a single token, lexed only immediately after `@` or `@@`
+with no intervening whitespace: tight `/`-separated `segment`s (identifiers) with an
+optional leading `../` chain. So a `/` that is not part of such a path is division/invert:
+`@a/b` is the path `a/b`, but `@a / b` is `@a` divided by `b`. `//` is always the
+integer-quotient operator, never a path separator.
+
+There are no negative-number tokens: `-` is always the negation/subtraction operator.
+A negative literal is written `-` directly before a number — the parser folds it into a
+literal in expressions, and `p_literal` admits it directly in patterns.
+
+### 2.7 Operators (syntactic sugar)
+
+Every operator here is **pure syntactic sugar**: it desugars to a pipe into an `@OP.*`
+member (§7.6), or, for the map-pipes, into a stdlib call.
+
+```
+  -a           →  negative literal if a is a number, else  a | @OP.negate
+  /a           →  a | @OP.invert
+  ~a           →  a | @OP.not
+  a + b + c    →  [a, b, c] | @OP.sum
+  a - b        →  [a, b | @OP.negate] | @OP.sum      (numeric b folds: a - 42 → [a, -42] | @OP.sum)
+  a * b * c    →  [a, b, c] | @OP.product
+  a / b        →  [a, b | @OP.invert] | @OP.product
+  a % b        →  [a, b] | @OP.modulo
+  a // b       →  [a, b] | @OP.quotient
+  a ?? b       →  [a, b] | @OP.compare
+  a == b == c  →  [a, b, c] | @OP.equal
+  a && b && c  →  [a, b, c] | @OP.and
+  a || b || c  →  [a, b, c] | @OP.or
+  xs |: f      →  {"c": xs, "f": f} | @map
+  xs |? f      →  {"c": xs, "f": f} | @filter
+  xs |+ f      →  {"c": xs, "f": f} | @reduce
+```
+
+Folding and associativity:
+
+- A maximal run of `+`/`-` folds into one `@OP.sum` over all terms; each `-` term is
+  negated (a numeric literal folds to a negative literal, otherwise via `@OP.negate`).
+- 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`.
+
+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`.
+
+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.
+
 ---
 
 ## 3. Functions and application
@@ -231,7 +296,7 @@ Rules:
 `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.
+truthy). The operators `@OP.and` / `@OP.or` / `@OP.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
@@ -313,7 +378,7 @@ particular built-ins:
   is per-call: it is not enough for the function to have *some* error clause;
   that clause must match the specific error received. An error of a shape no
   clause catches propagates unchanged.
-- **Built-in operations (`@add`, `@divide`, `@equals`, `@Integer`, …) all
+- **Built-in and stdlib operations (`@math.divide`, `@OP.sum`, `@Integer`, …) all
   propagate** their input error without examining it. 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);
@@ -323,7 +388,7 @@ 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 the division
+  error rather than wrapping it. `!([5,0] | @math.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`
@@ -334,9 +399,10 @@ particular built-ins:
 If a `?` predicate evaluates to an error (the predicate function itself errored,
 or it was a non-function error value), that error becomes the function's return
 value immediately. Subsequent clauses are **not** tried — predicate-errors are
-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.
+treated as program failures, not as "no match." This is the key reason to keep a
+`?` predicate from raising: a predicate that can crash will short-circuit your
+whole function. A non-matching input is not a crash — it falls through to `null`
+(falsey) — so a predicate needs no `_ => false` catch-all to be safe here.
 
 ### 6.5 The standardized error payload
 
@@ -354,46 +420,48 @@ There are two origins of error values, and they differ in payload:
 #### Payload shape
 
 ```json
-{"kind": "type_error", "location": "builtin add", "operation": "add", "input": [1, "x"], "message": "expected numbers"}
+{"kind": "argument_error", "origin": "builtin", "operation": "@math.divide", "status": 0, "input": [1, "x"], "expected": ["[_ ? @Number, _ ? @Number]"]}
 ```
 
 | 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`      | yes      | The error category. Possible values are defined below.                                                                     |
+| `origin`    | yes      | Where the failing operation is *defined*. Possible values are defined below.                                               |
+| `file`      | no       | The **innermost user-code file** on the call chain. `builtin`/`stdlib` frames are skipped. The path is **relative to** `Dir.pwd`. Contains `"<inline>"` for errors in the CLI `-e` option or the REPL. Contains `"<fusion>"` for an error above all user code (e.g. `stdin` present, but `code` is not a function). Present for `builtin`/`stdlib`/`code` origins; absent for a channel/runtime origin (`input`/`output`/`interpreter`). |
+| `operation` | yes      | The operation that failed. All `@`-references are named by their **source text**. A syntactic operation uses its form (`"\|"`, `".name"`, `"[]"`, `"parsing code"`, `"parsing JSON"`). Loading the top-level program file uses `"loading code"`. |
+| `status`    | yes      | `0` or `1`. Whether the operation received an ordinary value (`0`) or an error value (`1`)                                 |
+| `input`     | yes      | The operation's input. A 0-argument operation (every `@`-reference except `@load`) carries `null`.                         |
+| `expected`  | no       | The acceptable inputs as a list of Fusion **patterns**. The input matched none of them.                                    |
+| `message`   | no       | Extra human-readable detail, e.g. `"division by zero"`. Absent whenever `expected` is present.                             |
 
-#### `kind` — the closed set
+#### Possible values for `kind`
 
 | `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 [_, _]`). |
+| `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, a target outside the jail (§9.2), no enclosing file for `@@` (§9.2). |
+| `argument_error`      | a value has the wrong shape or type for an operation: a built-in given the wrong number/shape of arguments (e.g. not a pair) or a wrong-typed value, applying a non-function, spreading a non-array/object, member access on a non-object, a wrong-typed index, or an `array`/`object`-mode input envelope of the wrong shape (§9.4). Its `expected` lists the acceptable inputs as patterns. |
 | `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`). |
+| `access_error`        | a missing object key or an out-of-range array index.                                                           |
 | `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.                                              |
+| `limit_error`         | a runtime resource limit was exceeded. `"stack level too deep"`.                                               |
+| `internal_error`      | an interpreter BUG. Please open an issue.                                                                      |
+| `serialization_error` | a result/error value has no JSON form. It contains functions or non-finite numbers. See §9.                    |
 
-#### `location` — the closed set
+#### Possible values for `origin`
 
-| `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.                    |
+| `origin`      | Meaning                                                                  |
+| ------------- | ------------------------------------------------------------------------ |
+| `builtin`     | a built-in operation (named by its `@`-reference in `operation`).        |
+| `stdlib`      | a standard-library function (named by its `@`-reference in `operation`). |
+| `code`        | user source core (a file or an inline expression (`-e`/REPL).            |
+| `input`       | the input channel (stdin). Usually syntax errors.                        |
+| `output`      | the output channel. Usually serialization errors.                        |
+| `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`.
+source, which always reports as `code`.
 
 User errors don't have to adhere to this standard.
 
@@ -402,60 +470,75 @@ User errors don't have to adhere to this standard.
 ## 7. Built-in functions
 
 All built-ins are ordinary one-argument functions, **reached with an `@` prefix**
-(`@add`, `@Integer`, …); see §9.2 for how `@name` resolves. The names in the tables
+(`@size`, `@Integer`, …); see §9.2 for how `@name` resolves. The names in the tables
 below are the built-in names; write `@` before them to use them. **Operations** return
 `!` on type-invalid or domain-invalid input. **Predicates** return `false` on any
 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                                                                |
-| `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)                                                        |
-
-### 7.2 Comparison (operations)
-
-| 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
-for the standard library, derivable from `equals` and `lessThan`.
-
-### 7.3 Boolean (operations)
-
-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`) |
+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.
+
+### 7.1 Arithmetic
+
+In source you normally write the infix sugar of §2.7 — `a + b`, `-a`, `a * b`, `a % b`,
+`a // b` — which desugars to the members below. Addition, multiplication and negation are
+`@OP.sum` / `@OP.product` / `@OP.negate` (§7.6); subtraction is `[a, b | @OP.negate] | @OP.sum`.
+Integer division/remainder are `@OP.quotient` / `@OP.modulo`. Numerically correct
+division and the other numeric functions live in `@math` (§7.6a): `@math.divide`,
+`@math.floor`, `@math.round`, `@math.abs`, `@math.log`, `@math.sqrt`, etc.
+
+### 7.2 Comparison
+
+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.
+
+### 7.3 Boolean
+
+The truthiness operators live in `@OP` (§7.6): `@OP.and`, `@OP.or`, `@OP.not`, written
+with the sugar `a && b`, `a || b`, `~a` (§2.7). They
+judge truthiness (every value is truthy except `false` and `null`), not strict
+booleans, and always return a boolean. There are no top-level `@and`/`@or`/`@not`.
+The stdlib helpers `@truthy` and `@falsey` reduce any single value to its truthiness
+by **pattern matching** (independent of any `@OP` override): `@truthy` is `true` for
+everything except `false`/`null`, and `@falsey` is its complement.
 
 ### 7.4 Strings and structure bridges (operations)
 
 | Name          | Input                       | Result                                  |
 | ------------- | --------------------------- | --------------------------------------- |
-| `length`      | string / array / object     | element/character/key count (integer)   |
-| `concat`      | `[string, string]`          | concatenation                           |
-| `chars`       | string                      | array of single-character strings       |
-| `join`        | `[array-of-strings, string]`| joined string                           |
+| `size`        | string / array / object     | element/character/key count (integer)   |
+| `join`        | `[array-of-strings, separator]` | the elements joined by the separator string |
+| `split`       | `[string, separator]`       | array split on the **literal** separator (an empty separator splits into characters), keeping empty fields |
 | `toString`    | any                         | string form of the value                |
 | `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 |
 
+`concat` (`[string, string]` → concatenation) and `chars` (string → array of its
+characters) are **standard-library** functions built on `join` / `split`, not
+built-ins.
+
+Indexed read (`x[k]`) and write (`x[k = v]`) are **core syntax**, not built-ins — there
+is no `@get`/`@set`; see §8.
+
 ### 7.5 Type predicates (predicates)
 
 Each of these functions takes any input value and returns a boolean. This set of
@@ -478,7 +561,59 @@ 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`
+### 7.6 The `@OP` object (the operators)
+
+`@OP` is a built-in **object**, reached by member access (`@OP.sum`, `@OP.and`, …),
+holding the arithmetic/comparison/boolean operators. Its members generalise to an
+**array of any length** (`sum`/`product`/`and`/`or` fold; `equal` is deep over all
+elements); `compare` reports an ordering. The infix operators (§2.7) desugar to these members.
+
+`@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).
+
+| Member        | Input                                    | Result                                                   |
+| ------------- | ---------------------------------------- | -------------------------------------------------------- |
+| `OP.sum`      | array of numbers                         | sum (`0` for `[]`)                                        |
+| `OP.product`  | array of numbers                         | product (`1` for `[]`)                                    |
+| `OP.negate`   | number                                   | negation                                                 |
+| `OP.invert`   | number                                   | reciprocal `1/x`, always a float; `!` if `0`             |
+| `OP.quotient` | `[integer, integer]`                     | integer division; `!` on a non-integer or a `0` divisor  |
+| `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.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                          |
+
+### 7.6a The `@math` object (numeric functions and constants)
+
+`@math` is a built-in object (shadowable like `@OP`) of numeric functions and two
+constants. `pi`/`e` are plain values; the rest are one-argument functions. A
+non-finite input to `round`/`floor`/`ceil`, a `log` of a non-positive number, and a
+`pow` with a complex result are `math_error`s.
+
+| Member        | Input                | Result                                                     |
+| ------------- | -------------------- | ---------------------------------------------------------- |
+| `math.pi`     | —                    | `3.141592653589793` (a value, not a function)              |
+| `math.e`      | —                    | `2.718281828459045` (a value)                              |
+| `math.round`  | number               | nearest integer (half away from zero)                      |
+| `math.floor`  | number               | floor (integer)                                            |
+| `math.ceil`   | number               | ceiling (integer)                                          |
+| `math.divide` | `[number, number]`   | quotient, always a **float**; `!` if divisor is 0          |
+| `math.sign`   | number               | `-1` / `0` / `1`                                           |
+| `math.abs`    | number               | absolute value (keeps int/float)                           |
+| `math.rand`   | `null` or a positive integer `n` | float in `[0, 1)`, or integer in `[0, n)`      |
+| `math.sin`    | number               | sine (radians), float                                      |
+| `math.cos`    | number               | cosine (radians), float                                    |
+| `math.exp`    | number               | `e^x`, float                                               |
+| `math.log`    | positive number      | natural log, float; `!` on a non-positive number           |
+| `math.pow`    | `[base, exponent]`   | `base^exp` (integer when base and non-negative integer exponent; else float); `!` on a complex result |
+| `math.sqrt`   | non-negative number  | square root (float); `!` on a negative number              |
+
+### 7.7 Special built-ins: `ENV` and `load`
 
 These resolve in the `@name` chain like other built-ins (so a sibling file of the
 same name shadows them), but they are not plain unary value functions:
@@ -495,12 +630,18 @@ same name shadows them), but they are not plain unary value functions:
 
 ## 8. Member and index access
 
+Member access (`.`), index read (`[]`), and index write (`[=]`) are **core syntax**,
+evaluated directly by the runtime. There are no `@get`/`@set` built-ins.
+
 - `x.key` — if `x` is an object containing `key`, its value; otherwise `!`.
-- `x[expr]` — if `x` is an array and `expr` is an integer in range, the element
-  (negative indices count from the end); if `x` is an object and `expr` is a string
-  key that exists, its value; otherwise `!`.
+- `x[expr]` — **read**: if `x` is an array and `expr` is an integer in range, the element
+  (negative indices count from the end); if `x` is an object and `expr` is a string key
+  that exists, its value; otherwise `!`.
+- `x[key = value]` — **write**: a **new** array/object with that one entry set; `x` itself
+  is unchanged. An array index must already exist (arrays are not extended; negative
+  indices count from the end); an object key may be new. `!` on a bad index/type.
 
-Both `.` and `[]` bind tighter than `|`.
+`.`, `[]`, and `[=]` are postfix and bind tighter than every operator (including `|`).
 
 ---
 
@@ -515,7 +656,19 @@ A `.fsn` file contains **exactly one expression**, which is its value. A file is
 
 A `@` reference takes one of these forms:
 
-- **`@`** (nothing after it) — the **current file**'s value. Used for self-recursion.
+- **`@`** (nothing after it) — the value of the **current top-level unit**: the
+  current file, or the inline (`-e`) / REPL entry being evaluated. Used for
+  self-recursion.
+- **`@@`** (super) — the built-in or standard-library value the current file
+  **shadows**: the file's own name resolved by steps 2–3 below, skipping the
+  sibling step (which would be the file itself). Lets an override refer to the
+  original method, e.g. `add.fsn` containing `@@` refers to the stdlib `add`.
+  Outside a file (inline `-e` / REPL) there is no name to take super of, so it is a
+  `reference_error` (`no enclosing file`).
+- **`@@name`, `@@dir/name`** — super with an explicit name: resolve `name` by
+  steps 2–3 below, skipping its sibling. The **stable** form of a reference — a
+  local shadow cannot intercept it (used inside an `OP.fsn` as `@@OP`, and by
+  error patterns that must stay canonical). `@@../…` is a syntax error.
 - **`@ENV`** — an object of all environment variables (string keys, string values;
   no parsing). Resolved in the `@name` chain below, so it is shadowable.
 - **`@name`** — a single bare identifier (no `/`, no `../`).
@@ -529,9 +682,9 @@ in order, first match winning:
 2. a **built-in** of that exact name (including `ENV` and `load`);
 3. a **standard-library file** at `<stdlib root>/<name>.fsn`.
 
-If none match, the result is `!`. Downward paths participate fully: `@math/sqrt`
-checks a sibling `math/sqrt.fsn`, then a built-in named `math/sqrt`, then a stdlib
-`math/sqrt.fsn`.
+If none match, the result is `!`. Downward paths participate fully: `@util/helper`
+checks a sibling `util/helper.fsn`, then a built-in named `util/helper`, then a stdlib
+`util/helper.fsn`.
 
 **Resolution of upward paths** (any reference containing `../`) is **file-only**: it
 resolves solely to a file relative to the referencing directory and never falls back
@@ -542,7 +695,20 @@ is relative to the **referencing file's** directory; built-ins and the standard
 library are global to the runtime but, per the order above, are shadowed by a sibling
 file of the same name. That shadowing is per-directory, not global.
 
-**Built-ins are reached through this same mechanism**: `@add`, `@Integer`, etc. are
+**Confinement (the jail).** File-backed resolution is confined to a *jail*: a directory
+and its subtree, set by `-j`/`--jail` and defaulting to the program's directory (the
+working directory for `-e` and the REPL). All `@`-references and the builtin `@load`
+respect the jail. Referencing a file outside the jail is a `reference_error`
+(`outside the jail`). An existing sibling outside the jail fails this way too — it does
+*not* fall back to a built-in or the stdlib, so a forbidden file fails loudly rather than
+silently resolving elsewhere. References still resolve relative to the referencing file;
+the jail only filters the result. The standard library is always reachable regardless of
+the jail, and stdin is never affected — it is plain JSON, never an `@`-reference.
+Confinement is lexical (it normalises `..`) and follows existing symlinks. It confines
+references to a directory tree; it is not a security sandbox and needs none, since Fusion
+cannot write files. Pass `--jail '*'` to disable confinement entirely.
+
+**Built-ins are reached through this same mechanism**: `@size`, `@Integer`, etc. are
 `@name` references that resolve at step 2. A *bare* identifier (without `@`) is only
 a pattern hole; it never denotes a built-in.
 
@@ -572,12 +738,19 @@ above. Recursion through functions is not a data cycle.
 
 ### 9.3 Runtime contract
 
-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` (in every input mode).
-- Non-JSON input yields a `syntax_error` at `location: "input"` (§6.5).
+The **pipe** use case (`--pipe`, and the default whenever any argument is given —
+see §9.7) reads standard input as JSON, converts it to a Fusion value `v`,
+computes `v | programFunction`, and prints the result on standard output as JSON.
+When standard input is empty, the program get evaluated and immediately becomes
+the result instead.
+
+- Input always arrives on standard input; there is no input argument.
+- **Empty input means "no input": the program's own value is the result.** A
+  `.fsn` file therefore doubles as enriched JSON data — it can compute, read
+  `@ENV`, and pull in `@`-references, then print the value with no pipeline
+  input. (Under `-!` the input is an error value instead; empty input then has no
+  payload to mark, which is a usage error — see §9.4.)
+- Non-JSON input yields a `syntax_error` at `origin: "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
@@ -613,20 +786,25 @@ 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).
+  the whole input as an error value instead (its JSON becomes the payload). `-!`
+  therefore requires input: with empty input there is no payload to mark, which
+  is a usage error (the program does not run). 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.
+  that is the price of the most lightweight marking, so `bang` is recommended only
+  between Fusion programs — for anything that must stay valid JSON, use `array` or
+  `object`.
 - **`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`.
+  `[1, payload]` for an error. Every line is valid JSON, which is why it is the
+  `--stream` default (§9.5). 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"`.
+be exactly the integer `0` or `1`) is an `argument_error` at `origin: "input"`.
 Like any input failure it flows into the program as an error and is catchable.
 
 Mode support per use case (defaults in bold):
@@ -634,29 +812,45 @@ Mode support per use case (defaults in bold):
 | Use case   | `unix`   | `bang`   | `array` | `object` |
 | ---------- | -------- | -------- | ------- | -------- |
 | pipe       | **yes**  | yes      | yes     | yes      |
-| `--stream` | no       | **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.
+case therefore excludes it. Stream defaults to `array` rather than `bang` so each
+record stays valid JSON (NDJSON, §9.5); `bang` remains available as the cheapest
+encoding for Fusion-to-Fusion pipelines. 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.
+as [NDJSON](https://github.com/ndjson/ndjson-spec) 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. Input and output default to the **array** mode
+(not `bang`) so every line is valid JSON. The media type is
+`application/x-ndjson` and the file extension for storing such a stream should
+be `.ndjson`.
+
+NDJSON conformance:
+- Every output record is a single JSON text in UTF-8, terminated by `\n`, and
+  never contains an embedded newline or carriage return.
+- Both `\n` and `\r\n` are accepted as input line delimiters.
+- A blank input line (empty or whitespace-only) carries no record, so the program
+  never runs on it. By default it is echoed as a blank output line, keeping input
+  and output aligned line-for-line. Pass `--skip-blank-lines` to drop blank lines
+  instead. Every non-blank line produces exactly one output line.
 
-- 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.
+- A program that fails to load will return the same load error for every record.
 
 ### 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:
+`fusion --repl` starts an interactive session — as does a bare `fusion` with no
+arguments at all (§9.7). 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:
@@ -677,43 +871,63 @@ relative to the working directory.
   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
+  (`fact = (0 => 1, n => [n, [n,-1] | @OP.sum | fact] | @OP.product)`), because
   the name is looked up at application time.
-- Entries report errors at `location: "code <inline>"`, like `-e` programs.
+- Entries report errors at `origin: "code"` with `file: "<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.
+statement or expression; until then 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.
+The prompt is shown in light blue, and each result is preceded **on stderr**
+by a green `✔` (a value) or a red `✗` (an error); these
+are decorations only — the result itself stays unstyled on stdout. 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]
+usage: fusion [options] <file.fsn>
+       fusion [options] -e '<source>'
        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`
+use cases (default: --repl with no arguments, otherwise --pipe):
+  -p, --pipe      apply the program to stdin; with no input, the
+                  program's own value is the result
+  -s, --stream    apply the program to each line of an NDJSON stream
+  -r, --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)
+  -e, --execute '<source>'
+                  inline program instead of a file
+  -i, --input MODE
+                  how the input marks an error value (§9.4)
+  -o, --output MODE
+                  how the output marks an error value (§9.4)
+  -j, --jail DIR  confine @-references to DIR and its subtree
+                  (default: the program's directory; '*' disables it; §9.2)
   -!              treat the input as an error value (unix input mode only)
+  -b, --skip-blank-lines
+                  drop blank input lines instead of echoing them (--stream, §9.5)
 ```
 
-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.
+**Selecting a use case.** At most one of `--pipe`, `--stream`, `--repl` may be
+given; passing two is a command-line misuse. With none, a bare `fusion` (no
+arguments at all) starts the REPL, while any other invocation is a pipe run. So
+`--pipe` is needed only to be explicit, `fusion file.fsn` already implicitly
+use `--pipe`.
+
+In the pipe use case, input comes from standard input; when standard input is
+empty, the program's own value is the result (§9.3). The stream use case also
+reads standard input. Neither accepts an input argument.
+
+Every flag has a short and a long form (`-p`/`--pipe`, `-i`/`--input`, …), except
+`-!`, which has only the short form. Each of `--input`/`--output` may only be used
+once. Multiple different modes for one direction is a misuse.
 
-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.
+A command-line misuse (an unknown flag, more than one use case, two different
+modes for one direction, 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.