fusion-lang 0.0.1.alpha2 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4300463df5e82850cc75d27151c01a6b83e3cd66b90a5c820d40f27d54787250
-  data.tar.gz: 044f7a4883952b56aa4336067c994ab78a7dd84e8116f68501c229414c91512e
+  metadata.gz: 6571414d6f0a1f977f517652742c7b2766d7a17577f0276163856ff992bc7bc0
+  data.tar.gz: 1f4f3a71cbfe0a18e18e91276b0ade75ea5c49a5b9a531097b739e8f04929b24
 SHA512:
-  metadata.gz: 0d0cd98c87c04c9cc88694ad3d4e926103334fd03d5bfadcf147050c41f63bdb17b4b1bfaad9a5cd9bc456d5ea3ec17ded24db02e4d83d4035d1f403d4d669d6
-  data.tar.gz: 38d2637d43d8cbc5c17423a329e64605cde2cb2d154207174ec482611df43b1bc1f5d8435bd1bda751528bdc4a7d029b751b0e5f3fa11d10731afe82044b745a
+  metadata.gz: e4f9a32c372aea8633c1e66ab883015674d052ca83cccfab10c693f65ac805d90b4d768e1f78a4fb1a77745c158e6a39d56fa25ff9cae16cc29c765c22480ca7
+  data.tar.gz: 7feb41d65c7be52ee4a92c820edd714b8ef28b6e0c5e9a6726d1a7c41963e9f3ff4d36b7cb89afacba1256cdc675c8a4a0c5c34d6ca5865e8106f4efe70fc4c7

data/README.md

@@ -55,16 +55,17 @@ gem "fusion-lang", require: "fusion"
 ## How to run your code
 
 ```sh
-echo '5' | fusion examples/factorial.fsn        # => 120
-echo '15' | fusion examples/fizzbuzz.fsn        # => "FizzBuzz"
-fusion examples/factorial.fsn 5                 # => 120 (input as an argument)
-fusion -e '(n => [n,2] | @multiply)' 21         # => 42 (inline program)
-printf '[1, 2]\n[3, 4]\n' | fusion --stream examples/double.fsn   # => [2,4] [6,8] (NDJSON, one value per line)
-fusion --repl                                   # interactive expressions and `name = expression`
+echo '5' | fusion examples/factorial.fsn          # => 120
+echo '15' | fusion examples/fizzbuzz.fsn          # => "FizzBuzz"
+echo '21' | fusion -e '(n => [n,2] | @OP.product)'  # => 42 (inline program)
+fusion -e '[1, [2, 3] | @OP.sum]'                   # => [1,5] (no input: the program's value is the result)
+printf '[0,3]\n[0,4]\n' | fusion --stream examples/double.fsn   # => [0,6] [0,8] (NDJSON, array mode)
+fusion --repl                                     # interactive REPL (also started by a bare `fusion`)
 ```
 
-- Input is read from stdin (or the 2nd CLI arg) as JSON and parsed into a Fusion value.
-- The file's function gets applied to this value: `value | function`
+- Input is read from stdin as JSON and parsed into a Fusion value.
+- The file's function gets applied to this value: `value | function`.
+- With no input, the file's own value is the result — so a `.fsn` file doubles as enriched JSON data.
 - The result gets printed as JSON to stdout.
 - Errors get printed to stderr instead and set exit code `1`.
 - How errors cross the boundary is configurable per side (`--input` / `--output`);

data/docs/lang/design.md

@@ -79,9 +79,9 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 ### Decisions
 
 - 🧑 ✅ Integers and floats are distinct kinds.
-- 🤖 ✅ `divide` returns an integer when evenly divisible and a float otherwise.
-- 🤖 ✅ `floor` returns an integer.
-- 🤖 ✅ `equals` is exact.
+- 🤖 ⏪ `@OP.divide` returned an integer when evenly divisible, a float otherwise. Reverted in §5.5. It is now always a float, with integer division split out to `@OP.quotient` (§5.5).
+- 🤖 ✅ `@math.floor` returns an integer.
+- 🤖 ✅ `@OP.equal` is exact.
 
 ### Alternatives
 
@@ -101,11 +101,11 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 
 ---
 
-## 1.4 Member/index access failures yield `!`
+## 1.4 Member/index access failures yield an error
 
 ### Decisions
 
-- 🤖 ✅ `x.key` on a missing key or non-object, and `x[i]` out of range or on a wrong type, yield `!` (not `null`).
+- 🤖 ✅ `x.key` on a missing key or non-object, and `x[i]` out of range or on a wrong type, yield an error (instead of `null`).
 
 ### Why the implementer decided this
 
@@ -162,7 +162,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 
 ### Decisions
 
-- 🧑 ✅ Patterns and results are mirror images using the same names — values captured by a pattern are re-inserted in the result.
+- 🧑 ✅ Patterns and results are mirror images using the same names. Values captured by a pattern are re-inserted in the result.
 - 🤖 ✅ A bare (unquoted) identifier is the binder/hole: it binds in a pattern and reads in an expression (Claude's choice to use JSON's one unused syntactic slot, rather than a sigil).
 
 ### Alternatives
@@ -232,7 +232,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - Unifies three things (structural matching, type checks, value guards) into one mechanism.
 - The "type system" is user-extensible with ordinary functions.
 - Nothing new to learn beyond `?`.
-- Predicates compose directly (`a ? @ends | @equals`) instead of requiring a wrapping function (`a ? (x => x | @ends | @equals)`).
+- Predicates compose directly (`a ? @ends | @OP.equal`) instead of requiring a wrapping function (`a ? (x => x | @ends | @OP.equal)`).
 
 ### Cons
 
@@ -274,7 +274,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - 🧑 ✅ Introduce a distinct error mode `!`, separate from `null`.
 - 🧑 ✅ `null` = legitimate absence; `!` = failure.
 - 🧑 ✅ A function is made *strict* by ending with `_ => !` (error on no match) and is otherwise *lenient* (returns `null` on no match).
-- 🧑 ✅ Total predicates end with `_ => false`.
+- 🧑 ⏪ Total predicates end with `_ => false`. Obsoleted by §2.12. Predicates no longer need a `_ => false` clause, because `null` became equivalent to `false`.
 - 🤖 ✅ Built-in operations return `!` on bad input; built-in predicates return `false`.
 - 🧑 ✅ The form of `!` (always carrying a payload) is fixed by 2.8.
 - 🤖 ✅ `!` matches **only** error patterns (not `_`, not a binder).
@@ -336,7 +336,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - 🧑 ✅ In expression position, `!expr` is a prefix operator that wraps a value as an error; in pattern position, `!pat` matches an error and destructures its payload (bare `!` matches any error without binding; `!_` does the same but admits a `?` predicate).
 - 🧑 ✅ Propagation preserves the *same* error (payload intact), so by the time you reach a catch site you still know what happened.
 - 🧑 ✅ The CLI prints the payload (as JSON) to stderr on failure and exits `1`, leaving stdout empty.
-- 🧑 ✅ **Errors propagate uniformly — they are not values.** At any moment of execution there is either a value or an error in motion, never both. Built-ins (including `@equals` and the type predicates), array and object literals, `?` predicates, and the function-value position of a pipe all propagate an encountered error. The only way to do anything with an error besides letting it propagate is to catch it in an `!pat` clause, which yields a normal value (the payload).
+- 🧑 ✅ **Errors propagate uniformly — they are not values.** At any moment of execution there is either a value or an error in motion, never both. Built-ins (including `@OP.equal` and the type predicates), array and object literals, `?` predicates, and the function-value position of a pipe all propagate an encountered error. The only way to do anything with an error besides letting it propagate is to catch it in an `!pat` clause, which yields a normal value (the payload).
 - 🧑 ✅ **No nested errors.** When `!expr` is evaluated and `expr` itself produces an error, that inner error propagates and the outer `!` is a no-op. This preserves the "never more than one error simultaneously" invariant — there is no `!!` value, ever.
 - 🧑 ✅ **Partial matching propagates the unmatched error.** A function with error clauses that match *some* error shapes (e.g. `!42 => ...`) but not the one it receives (e.g. `!"oops"`) propagates the unmatched error rather than turning it into `null`. The "no match → null" lenient default from 2.7 applies only to non-error inputs.
 - 🧑 ✅ **`!pat` is a top-level prefix in the clause grammar.** `!` is a prefix on the *clause pattern*, not on any sub-pattern: array elements, object members, and the payload of another `!` all recurse into the non-`!` pattern production. This grammar shape simultaneously enforces two things with no special-case parsing flag: (i) nested error patterns (`[!a, b]`, `{"err": !x}`, `!!42`, `!{"k": !v}`) are syntax errors, matching the runtime invariant that errors never sit inside other values; and (ii) `!pat ? pred` parses as `!(pat ? pred)`, so the `?` binds *inside* the `!`. The runtime payoff is that the predicate of `!a ? pred` naturally sees the payload, with no special case needed in `PGuard`.
@@ -347,7 +347,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - 🧑 ⏪ Keep `!` opaque with no payload (the original error model, superseded because it was too hard to debug).
 - 🤖 💭 Use a `Result`-style two-variant `Ok | Err` (hypothetical: needs new machinery; payloaded errors with propagation give the same ergonomics with two rules).
 - 🤖 ❌ Make payloads always strings (Claude's first payload sketch, e.g. `!"divide by zero"`; rejected because built-in mechanics like missing keys benefit from structured payloads).
-- 🤖 ⏪ Make errors first-class values that can be stored in collections, compared with `@equals`, and inspected by predicates (Claude implemented this reading; the designer corrected it because it creates carve-outs in propagation that contradict the "never more than one error" invariant).
+- 🤖 ⏪ Make errors first-class values that can be stored in collections, compared with `@OP.equal`, and inspected by predicates (Claude implemented this reading; the designer corrected it because it creates carve-outs in propagation that contradict the "never more than one error" invariant).
 - 🤖 ⏪ Parse `!pat ? pred` as `(!pat) ? pred` so the predicate refines the whole error rather than the payload (Claude parsed it this way; the designer corrected it to `!(pat ? pred)` so the predicate sees the payload, matching its sibling binders).
 
 ### Pros
@@ -373,12 +373,10 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 
 ### Decisions
 
-- 🧑 ✅ Every error payload produced by "the runtime" (the interpreter or a built-in function) has the **same shape**. This shape is enforced by constructing "internal errors" via `ErrorVal.internal`. The full schema is documented in [reference §6.5](../user/reference.md#65-the-standardized-error-payload).
-- 🤖 ✅ The stdlib is "ordinary unpriviledged Fusion code" and doesn't produce internal errors.
-- 🧑 ✅ However, all stdlib functions mirror the built-in error shape.
-- 🔢 ✅ During function application we differentiate between:
-  - `argument_error`: bad *input shape* (e.g. the wrong number of inputs). Constraints that could be expressed as a pattern without `?`.
-  - `type_error`: unsupported *input type* (e.g. string instead of number) or constraints between multiple inputs. Usually would require a `?` to express as a pattern.
+- 🧑 ✅ Every error payload produced by "the runtime" (the interpreter or a built-in function) has the **same shape**. This shape is enforced by constructing "runtime errors" via `ErrorVal.from_runtime`. The full schema is documented in [reference §6.5](../user/reference.md#65-the-standardized-error-payload).
+- 🤖 ⏪ The stdlib is "ordinary unpriviledged Fusion code". It didn't produce runtime errors. Reverted by §2.13. The stdlib now constructs regular `!expr` user errors, but they get marked as runtime errors afterwards.
+- 🧑 ✅ All stdlib functions mirror the built-in error shape.
+- 🔢 ⏪ During function application we differentiated `argument_error` (bad input *shape*, expressible as a pattern without `?`) from `type_error` (bad input *type*). Reverted in §2.13. Both errors got unified into a single `argument_error`.
 - 🧑 ✅ Member/index access reserves `access_error` for exactly `missing key` and `index out of range`:
   - Accessing a member of a non-object or indexing with a wrong-typed key is a `type_error` instead.
   - File-system access failures ("missing file", "directory instead of file", "permission denied") are a `reference_error` instead.
@@ -467,6 +465,53 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 
 ---
 
+## 2.13 Refining the error payload
+
+Refines §2.9: same general shape, more orthogonal fields, field values easier to match on, field values contain smarter contents
+
+### Decisions
+
+- 🧑 ✅ The error payload fields are now: `kind`, `origin`, `file` (opt), `operation`, `status`, `input`, `expected` (opt), `message` (opt).
+- 🧑 ✅ Split `location` into `origin` (where the operation is *defined*) and an optional `file` (the **innermost user-code file** on the call chain).
+- 🧑 ✅ `file` is `Dir.pwd`-relative, so it reads as the route from the location where `fusion` was called to the offending source code.
+- 🧑 ✅ Split `status` out from `input`. `status` is `0` (a value) or `1` (an error). On `1`, `input` carries the error's bare payload, so `input` is always valid JSON.
+- 🧑 ✅ `operation` now contains the failing operation's own **`@`-reference** (`@`, `@@`, `@lt`, `@math.round`, `@../mod`, `@load`) or for Built-in *syntax* its own form (`|`, `.key`, `[]`, `parsing code`). Loading the top-level program file is `loading code` (not an `@`-reference).
+- 🧑 ✅ An `@`-reference takes no argument, so its `input` is `null` and its `status` is always `0`. `@load` is the exception: it's a function taking a filename.
+- 🧑 ✅ For *access errors* the "key" appears only once:
+  - `.name` carries the static key in `operation` and the object alone in `input`
+  - `[]` is generic in `operation` and echoes the key in the `input` = `[collection, key]`
+  - `[=]` is generic in `operation` and echoes the key in the `input` = `[collection, key, newValue]`
+- 🧑 ✅ A failure to read a file (missing file, directory given, access denied) is reported as `"operation": <the literal @-reference>`, `"input": null`, `"file": <the referring call site>`.
+- 🧑 ✅ `type_error` is merged into `argument_error`. The distinction between *wrong shape* and *wrong type* didn't fit Fusion's runtime type system.
+- 🧑 ✅ `expected` lists the acceptable inputs as Fusion patterns (the input matched none); an error with `expected` never also carries a `message`.
+- 🧑 ✅ `internal_error` is the new catch-all for an unexpected host/interpreter failure. It's a Ruby error the engine caught rather than letting it crash the process (`origin` `interpreter` or `builtin`). It's an interpreter bug.
+- 🧑 ✅ A runtime resource limit being exceeded is a separate `limit_error` (currently a stack overflow, `"stack level too deep"`): the runtime gave up because a space/time budget ran out — not an engine defect. The general name (vs `stack_error`) lets future runtime resource limits share the kind.
+- 🧑 ✅ stdlib functions preemptively handle all *argument* errors. They appear atomic. No input should be able to trigger e.g. an error in a `|` operation. *Argument* errors refer to the stdlib function itself (`origin: "stdlib"`, `operation` = its `@`-reference).
+- 🧑 ✅ stdlib functions are *transparent* for *inner errors*. They can't catch every possible error from inner operations, so an inner error bubbles through unchanged. The purest example is `@map`, which knows nothing about the given `f`: an error from `f` originates from `f` and simply bubbles through `map`.
+- 🧑 ✅ stdlib higher-order functions (`@all`/`@map`) guard `f ? @Function` in every clause — a non-function `f` errors even on an empty collection — and `expected` shows the guard.
+- 🧑 ✅ `@all` short-circuits: the first falsey item yields `false`, the rest go untested.
+
+### Alternatives
+
+- 🔢 ⏪ A variable `location` string embedding the file/builtin name, with the error marker living inside `input` — split into the fixed `origin` + `file`, and the `status` field.
+- 🔢 ❌ Over-approximating `expected` patterns for `@join`/`@toObject` (e.g. `[_ ? @Array, _ ? @String]`) — they would match inputs that still fail, breaking "matches ⇒ acceptable"; `@all` keeps them exact.
+- 🔢 ❌ `operation` = the *literal source text* of the `|`'s right-hand side. Not implementable: the text isn't available where the error is born; stamping it at `apply` would relabel inner errors bubbling *through* a function (violating §2.9 transparency); and an indirect RHS like `f` is uninformative. The producer's own `@`-reference gives the same result for a direct call and stays correct otherwise.
+- 🧑 ❌ Drop `conversion_error` and have a failed conversion (e.g. `@parseNumber` of `"abc"`) return `null` (a "Maybe", as Ruby's `to_i` does). Rejected: the error payload carries more information, `| (! => null)` recovers the lenient form in one token, and forcing a catch keeps errors local — which matters with no backtraces. (A `null` would slip downstream and surface far from its cause.)
+- 🧑 ❌ Base the payload path on the jail / program directory instead of `Dir.pwd`. Rejected: `Dir.pwd` gives a path usable straight from your shell; for an installed/shebang tool invoked from elsewhere, a jail-relative path would describe the program's internal layout, which you'd then have to rebase onto your own location.
+
+### Pros
+
+- `input` is always valid JSON as the `status` now lives in its own field
+- `expected` documents the acceptable inputs as patterns a caller can reuse.
+- `origin` is directly dispatchable as the variable filename now lives in its own `file` field.
+- The roles of `file` and `operation` have been clarified and are much more helpful now.
+
+### Cons
+
+- A few `expected` patterns must reference the `@all` stdlib helper, so they aren't purely structural.
+
+---
+
 # 3. @ references
 
 ## 3.1 A file contains exactly one value
@@ -605,10 +650,10 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 
 All access goes through `@`:
 
-- 🧑 ✅ **Built-ins require `@`.** `@add`, `@Integer`, etc. A bare identifier is *only* a pattern hole; it never denotes a built-in. Built-ins cannot be shadowed by a clause's bindings — they live in a different namespace entirely.
+- 🧑 ✅ **Built-ins require `@`.** `@OP.sum`, `@Integer`, etc. A bare identifier is *only* a pattern hole; it never denotes a built-in. Built-ins cannot be shadowed by a clause's bindings — they live in a different namespace entirely.
 - 🧑 ✅ **The standard library has no prefix.** `@map` reaches it directly.
 - 🧑 ✅ **An `@name` reference (without leading `../`) resolves: sibling file → built-in → stdlib file → error.** First match wins. Consequently siblings can shadow a built-in or a stdlib function, but only for files in that directory (never globally).
-- 🧑 ✅ **Built-in/stdlib fallback is gated on `../`, not on `/`.** Downward paths (`@dir/a`, `@math/sqrt`) remain eligible for the built-in/stdlib fallback; only upward paths (`@../a`) are file-only and never fall back.
+- 🧑 ✅ **Built-in/stdlib fallback is gated on `../`, not on `/`.** Downward paths (`@dir/a`, `@util/helper`) remain eligible for the built-in/stdlib fallback; only upward paths (`@../a`) are file-only and never fall back.
 - 🧑 ✅ **A bare `@`** (nothing after it) means the current file — recursion is written this way rather than by repeating the file's own name.
 - 🧑 ✅ **`@ENV`** is a built-in evaluating to an object of environment variables (all string values, no parsing); read with member access (`@ENV.CI`).
 - 🧑 ✅ **`@load`** is a built-in taking a filename **verbatim** (no `.fsn` appended), resolved relative to the referencing file, for runtime/non-identifier filenames. Both `@ENV` and `@load` resolve in the `@name` chain, so both are shadowable by a sibling file of that name.
@@ -617,7 +662,7 @@ All access goes through `@`:
 
 - Every bare `@name` follows one precedence order (sibling → builtin → stdlib), so there are no reserved names to remember and no parser carve-outs.
 - `ENV` and `load` live in the builtin tier like everything else.
-- Gating fallback on `../` rather than on the presence of any `/` keeps downward paths (`@math/sqrt`) eligible for the stdlib, which is what stdlib subpackaging needs.
+- Gating fallback on `../` rather than on the presence of any `/` keeps downward paths (`@util/helper`) eligible for the stdlib, which is what stdlib subpackaging needs.
 
 ### Alternatives
 
@@ -635,12 +680,86 @@ All access goes through `@`:
 
 ### Cons
 
-- Built-ins are verbose (`@add` everywhere).
+- Built-ins are verbose (`@OP.sum` everywhere).
 - Shadowing is invisible at the call site (whether `@map` is yours or the stdlib's depends on directory contents).
 - A bare word that *looks* like a function reference is silently just a hole (reading an unbound one yields an error).
 
 ---
 
+## 3.7 Bare `@` also works for inline code, not only for files
+
+### Decisions
+
+- 🧑 ✅ A bare `@` is the value of the current top-level **unit**: a file (previously the only case), an inline (`-e`) program, or a REPL entry.Self-recursion works in all three cases.
+- 🧑 ✅ Interpreter context is not part of the identifier namespace. `:dir`/`:file`/`:self` are hidden values and not exposed as `__dir__`/`__file__`/`__self__`.
+
+### Alternatives
+
+- 🤖 ❌ Model inline/REPL code as a synthetic "fake file" so the existing file machinery applies — needs temp-file lifecycle or a special-cased reader, and leaves the REPL with no coherent "which file" answer.
+- 🧑 ⏪ "Bare `@` = the current file" (3.2/3.6); the "no current file for self-reference" error is gone, as it can no longer occur.
+- 🤖 🩹 Claude's first cut kept the self-value as an ordinary binding, so reading `__self__` returned an internal thunk and crashed serialization with a raw Ruby error; the designer caught it. Interpreter context now lives in its own channel, off the binding namespace.
+
+### Pros
+
+- One self-reference rule across files, inline source, and the REPL. The file path is incidental.
+- No identifier-namespace pollution. Internals stay internal.
+
+### Cons
+
+- `__dir__` is no longer exposed.
+
+---
+
+## 3.8 The jail: confining `@`-resolution to a directory
+
+### Decisions
+
+- 🧑 ✅ `-j/--jail DIR` confines `@`-resolution to `DIR` and its subtree. It defaults to the program's directory (or cwd for `-e` and the REPL). Available in every use case, the REPL included.
+- 🧑 ✅ A relative `--jail` resolves against the default jail, so `-j ..` widens to the parent; `--jail '*'` disables confinement entirely.
+- 🧑 ✅ An out-of-jail target is a `reference_error` (`outside the jail`).
+- 🧑 ✅ The stdlib is unaffected by the jail. However, an existing file outside the jail raises an error and prevents falling through to a built-in or the stdlib.
+- 🧑 ✅ `@`-references still resolve relative to the **referencing file**; the jail only filters the resolved target, it does not move the resolution base.
+- 🔢 ✅ Containment is lexical (`expand_path` normalises `..`) and confines references to a directory tree. It is **not** a security sandbox and follows existing symlinks. Fusion cannot write files, so no symlink can be planted to escape. Any encountered symlink is part of the legitimate project layout.
+
+### Alternatives
+
+- 🧑 💭 Resolve `@`-references relative to the **jail root** instead of the referencing file (a `--relative-to-jail` mode). Rejected: it would make `@name` mean `<jail>/name` everywhere and turn per-directory sibling-shadowing (3.6) into jail-global shadowing (project-rooted imports).
+- 🤖 ❌ Resolve symlinks (`realpath`) to make the jail a hard boundary. Declined: it buys nothing here (a program that cannot write files cannot plant an escaping symlink) and a real security sandbox is tricky to build.
+
+### Pros
+
+- A `.fsn` program is sandboxed to its own directory by default; reaching out is explicit (`-j ..`) or an opt-out (`-j '*'`).
+- The stdlib and stdin are untouched, so confinement never breaks an ordinary program.
+
+### Cons
+
+- Safe symlink-following rests on Fusion being unable to write files; adding a file-writing capability would mean revisiting it.
+
+---
+
+## 3.9 Super-reference `@@`
+
+### Decisions
+
+- 🧑 ✅ `@@name` (and downward `@@dir/name`) resolves `@name` while *skipping its sibling files*. It always references a builtin/stdlib and is immune to local shadowing. Bare `@@` is the special case `@@<current-file>`.
+- 🧑 ✅ Inline/REPL `@@` is a `reference_error` (`no enclosing file`). There is no filename to take "super" of.
+
+### Alternatives
+
+- 🤖 ❌ Make `@name` never refer to its own file (so `@range` inside `range.fsn` means the stdlib function). Rejected: the override would name itself (breaking relocatability) and it adds a per-file carve-out to the resolution chain.
+
+### Pros
+
+- An override delegates to the original without a separate handle, and `@name` semantics are untouched.
+- Relocatable: no file names itself.
+- `@@name` provides a stable mechanism for error-payload patterns that must stay canonical regardless of a caller's shadows.
+
+### Cons
+
+- Reaches only what you shadow under your *own* name, not an arbitrary shadowed built-in.
+
+---
+
 # 4. Runtime and CLI
 
 ## 4.1 Runtime I/O contract
@@ -649,7 +768,7 @@ All access goes through `@`:
 
 - 🧑 ✅ Read stdin as JSON → value `v`; compute `v | program`; print the result as JSON.
 - 🧑 ✅ A final `!` produces a nonzero exit code.
-- 🤖 ✅ Empty stdin is treated as `null`.
+- 🤖 ⏪ Empty stdin was treated as `null`. Superseded in 4.4: empty stdin means *no input*.
 - 🤖 ✅ Non-JSON stdin yields `!`.
 
 ### Alternatives
@@ -665,7 +784,7 @@ All access goes through `@`:
 ### Cons
 
 - No streaming; whole input must be buffered and parsed.
-- 🩹 A bare `!` with nonzero exit gives little diagnostic detail. Mitigated for internal errors by more detailed error payloads in 2.9.
+- 🩹 A bare `!` with nonzero exit gives little diagnostic detail. Mitigated for runtime errors by more detailed error payloads in 2.9.
 
 ---
 
@@ -695,21 +814,21 @@ All access goes through `@`:
 
 ---
 
-## 4.3 Internal errors and lenient JSON serialization
+## 4.3 Runtime errors and lenient JSON serialization
 
 ### Decisions
 
 - 🔢 ✅ To serialize values without a valid JSON representation, we introduce "lenient serialization". Values without JSON representation get turned into string representations (`"<function>"` and `"<Infinity>"`/`"<-Infinity>"`/`"<NaN>"`).
 - 🧑 ✅ The remaining data structure gets preserved.
-- 🔢 ✅ Internal errors (`ErrorVal.internal_error?`) get serialized leniently by default, so their info isn't obscured by a `serialization_error`.
-- 🤖 ✅ The stdlib doesn't produce internal errors.
-- 🧑 ✅ However, all stdlib functions use `@sanitize` to mimick the lenient JSON serialization and preserve as much info as possible.
-- 🧑 ✅ Ordinary values and user errors are serialized strictly to avoid surprising type conversions. If they fail to serialize, they get turned into an internal `serialization_error` and will subsequently get serialized leniently.
+- 🔢 ✅ Runtime errors (`ErrorVal#runtime?`) get serialized leniently by default, so their info isn't obscured by a `serialization_error`.
+- 🤖 ⏪ The stdlib doesn't produce runtime errors. Reverted in §2.13. stdlib errors now get marked as runtime errors.
+- 🧑 ⏪ All stdlib functions use `@sanitize` to mimick the lenient JSON serialization and preserve as much info as possible. Obsoleted by §2.13. However, `@sanitize` is kept as a utility.
+- 🧑 ✅ Ordinary values and user errors are serialized strictly to avoid surprising type conversions. If they fail to serialize, they get turned into a runtime `serialization_error` and will subsequently get serialized leniently.
 
 ### Alternatives
 
-- 🤖 ❌ The standard library could create real "internal errors" via a dedicated `@raise` primitive. Declined, because it offers little over the `!` prefix and would let any code (not just the stdlib) create internal errors. The main reason for internal errors (apart from enforcing a consistent shape) is lenient serialization.
-- 🧑 ❌ Internal errors also serialize strictly by default. Rejected, because this would turn too many errors into a `serialization_error` and would lose too much information.
+- 🤖 ❌ The standard library could create real "runtime errors" via a dedicated `@raise` primitive. Declined: it offers little over the `!` prefix and would let *any* code create runtime errors. Instead a stdlib `!{…}` is marked runtime by its construction *location* — the same benefit (lenient serialization, a consistent shape, call-site `file`), confined to stdlib source.
+- 🧑 ❌ Runtime errors also serialize strictly by default. Rejected, because this would turn too many errors into a `serialization_error` and would lose too much information.
 - 🧑 💭 All errors serialize leniently by default. Rejected, because this hides real errors (e.g. `NaN` or a function as a result) behind an automatic type conversion.
 
 ---
@@ -723,29 +842,43 @@ error value can cross the boundary.
 
 **Use cases:**
 
-- 🧑 ✅ The CLI supports three use cases: **pipe** (apply the program to one input — the 4.1 model, the default), **stream** (apply it to each line of an NDJSON stream), **repl** (interactive).
-- 🧑 ✅ **stream** keeps errors in-band and always exits `0`; a failing record (including a stack overflow) becomes that record's output line and the stream continues. Blank input lines are skipped.
+- 🧑 ✅ The CLI supports three use cases: **pipe** (apply the program to one input, §4.1), **stream** (apply it to each line of an NDJSON stream), **repl** (interactive).
+- 🧑 ✅ **pipe**: Compute `stdin | program`. Empty or whitespace-only stdin means *no input*: return `program` (evaluated on load). So a `.fsn` file doubles as enriched JSON (computations, `@ENV`, `@`-references).
+- 🧑 ✅ **stream**: Conforms to NDJSON. Keeps errors in-band and continues the stream. Always exits `0`.
+- 🧑 ✅ A blank **stream** input line is echoed as a blank output line (no computation); `--skip-blank-lines` drops it instead.
+- 🧑 ✅ **repl**: Can evaluate expressions. Also allows an assignment statement: `identifier = expression`.
+- 🤖 ✅ A command-line misuse (unknown flag, more than one use case, conflicting input/output modes, unsupported mode combination, missing program, `-!` with empty stdin) is plain usage text on stderr with exit `1`, never a payloaded error. Most are caught during option parsing, `-!` with empty-stdin while reading input.
 
 **I/O modes** — how an error is marked crossing the boundary; `--input` and `--output` are independent:
 
-- 🧑 ✅ Four modes: **unix** (plain JSON; value → stdout/exit 0, error → stderr/exit 1, as in 4.1), **bang** (a leading `!` marks an error), **array** (`[0, value]` / `[1, payload]`), **object** (`{"value": _}` / `{"error": _}`).
-- 🧑 ✅ The `-!` flag (unix input only) makes the whole input an error value.
-- 🧑 ✅ pipe supports all four modes; stream all but unix; repl has none.
-- 🤖 ✅ Defaults: pipe = unix/unix, stream = bang/bang. The non-unix modes always print to stdout and exit `0`.
-- 🤖 ✅ Empty input is `null` in every input mode; `-!` on empty input is `!null`.
+TODO: Under `-!` the input is the error payload, so empty stdin is a usage error (nothing to mark).
+
+- 🧑 ✅ Four modes: **unix** (asymmetric, Unix filter) and **bang** / **array** (`[0, value]` / `[1, payload]`), **object** (`{"value": _}` / `{"error": _}`).
+- 🧑 ✅ **unix**: input is `stdin` + `-!` flag, output is `value → stdout` + `exit 0` OR `error → stderr` + `exit 1`. stdin/stdout/stderr are always pure JSON.
+- 🧑 ✅ **bang**: shortest encoding, errors are simply a `!` prefix and thus not valid JSON.
+- 🧑 ✅ **array**: always valid JSON, error encoded via envelope: `[0, value]` / `[1, payload]`.
+- 🧑 ✅ **object**: always valid JSON, error encoded via envelope: `{"value": _}` / `{"error": _}`.
+- 🧑 ✅ `-!` requires stdin. With absent stdin, it's a usage error.
+- 🧑 ✅ pipe supports all four modes; stream all but unix (so errors stay "in-band"); repl has none.
+- 🧑 ✅ Defaults: pipe = unix/unix, stream = array/array.
 - 🤖 ✅ A malformed `array`/`object` input envelope is a catchable `argument_error` at `location: "input"` (the array tag must be exactly the integer `0`/`1`), flowing into the program like any input error.
 
 **REPL:**
 
-- 🧑 ✅ An entry is an **expression** (evaluated and printed) or a **statement** `identifier = expression` (evaluated, printed, and bound for later entries). The statement is the only construct that is not an expression.
-- 🧑 ✅ An entry is evaluated only once it parses as a whole statement/expression; an incomplete or invalid buffer keeps the entry open to finish or correct.
-- 🧑 ✅ A statement binds its identifier to the result **including an error result**; reading it back later propagates the error, exactly like reading an `@`-reference that resolved to one.
+- 🧑 ✅ An entry is an **expression** (evaluated and printed) or an **assignment statement** `identifier = expression` (evaluated, printed, and bound for later entries).
+- 🧑 ✅ An entry is evaluated only once it parses as a whole statement/expression. An incomplete or invalid buffer keeps the entry open to finish or correct.
+- 🧑 ✅ Error results can also get bound to an identifier via the **assignment statement**. When accessing them, they'll propagate regularly.
 - 🤖 ✅ Results print leniently (a function as `"<function>"`, etc.); entries report errors at `location: "code <inline>"`, like `-e`.
 - 🤖 ✅ Results go to stdout; the prompt and echoed input go to stderr (like a shell prompt), so stdout is a clean stream of results.
-- 🤖 ✅ A command-line misuse (unknown flag, unsupported mode combination, missing program) is plain usage text on stderr with exit `1` — it precedes the I/O contract, so it is not a payloaded error.
+- 🧑 ✅ `stderr` decorations are styled. Styling never touches `stdout`.
 
 ### Alternatives
 
+- 🧑 ⏪ pipe was the unconditional default — now repl on a bare `fusion`, otherwise pipe.
+- 🤖 ⏪ stream defaulted to `bang`/`bang` — now `array`/`array`, since `bang` lines aren't valid JSON.
+- 🤖 ⏪ Empty input was the value `null`, and input could also come from an inline `[json-input]` argument — now empty means *no input* and input is stdin-only.
+- 🧑 ⏪ Empty stdin under `-!` supplied `!null` — now a usage error, since there is no payload to mark.
+- 🤖 ⏪ Blank `stream` lines were silently skipped — now echoed by default, dropped with `--skip-blank-lines`.
 - 🧑 ⏪ REPL accepts only statements (the original "introduces a single statement" sketch); widened so a bare expression is also an entry.
 - 🧑 ⏪ Statements terminated by `;` (so several could share a line); dropped — completeness is decided by parsing, so a line that parses is submitted and no terminator is needed.
 - 🤖 ⏪ A statement does **not** bind an error result (mirroring pattern binders, which never capture an error). Flipped: a statement is an assignment, not a pattern match; binding an error is harmless and needs no special case.
@@ -757,11 +890,13 @@ error value can cross the boundary.
 - One small flag surface spans first-class Unix filters (pipe), bulk processing (stream), and interactive exploration (repl).
 - Errors cross the boundary in whatever shape the surrounding tool wants — exit code, `!` sentinel, or envelope — with input and output chosen independently.
 - The REPL reuses the whole language: an entry is just an expression, with assignment the one addition, and a bound error propagates like any other value-or-error (no carve-out).
+- A program with no stdin doubles as enriched JSON (computation, `@ENV`, `@`-references), and `--stream` emits valid NDJSON.
 
 ### Cons
 
 - Four error-marking modes are more surface than the original single unix contract.
 - Completeness-by-parsing submits a complete-but-maybe-unintended line (e.g. `x = 5` when more was meant) as-is.
+- Empty stdin no longer means the value `null`; to feed `null` you pipe the literal `null`.
 
 ---
 
@@ -771,9 +906,8 @@ error value can cross the boundary.
 
 ### Decisions
 
-- 🧑 ✅ No infix `+ - * / == < && …`.
-- 🧑 ✅ Arithmetic, comparison, and boolean operations are built-in functions applied to a pair, e.g. `[a, b] | @add`.
-- 🧑 ✅ Sugar is explicitly deferred, not rejected.
+- 🧑 ⏪ No infix `+ - * / == && …` until the core semantics are settled. Superseded by §5.6. Syntax sugar is now implemented.
+- 🧑 ✅ Arithmetic, comparison, and boolean operations are built-in functions reached via an `@-reference`, e.g. `[a, b] | @OP.sum`.
 
 ### Alternatives
 
@@ -786,7 +920,7 @@ error value can cross the boundary.
 
 ### Cons
 
-- Arithmetic-heavy code is verbose and harder to read (`[n, [n, 1] | @subtract | @fact] | @multiply` vs. `n * fact(n-1)`).
+- Arithmetic-heavy code is verbose and harder to read (`[n, [n, -1] | @OP.sum | @fact] | @OP.product` vs. `n * fact(n-1)`).
 
 ---
 
@@ -819,17 +953,10 @@ error value can cross the boundary.
 ### Decisions
 
 - 🤖 ✅ Only things that can't be built in Fusion itself become a builtin. Other frequently used functions become part of the standard library.
-- 🤖 ✅ The interpreter provides these builtins:
-  - arithmetic (`add`, `subtract`, `multiply`, `divide`, `mod`, `negate`, `floor`);
-  - comparison (`equals`, `lessThan`);
-  - boolean (`and`, `or`, `not`);
-  - bridges (`length`, `concat`, `chars`, `join`, `toString`, `parseNumber`, `keys`, `values`);
-  - predicates (`Integer`, `Float`, `Number`, `String`, `Boolean`, `Array`, `Object`, `Null`).
 - 🤖 ✅ `keys` must be a builtin: pattern matching can pull *known* object keys but cannot enumerate *unknown* ones, so iterating an object of unknown shape is impossible without it.
 
 ### Alternatives
 
-- 🤖 ❌ Derive `lessThan`'s siblings as built-ins too (chose to leave `lessEq`/`greaterThan`/etc. to the library).
 - 🤖 ❌ Omit `values` (derivable from `keys`).
 
 ### Pros
@@ -873,3 +1000,65 @@ error value can cross the boundary.
 
 - No way to annotate a single token mid-line; an explanatory comment must occupy its own line above the code.
 - A breaking change from the earlier `//` / `/* */` syntax (acceptable at this Alpha stage).
+
+---
+
+## 5.5 Reworking the builtins and standard library
+
+### Decisions
+
+- 🧑 ✅ Bundle the most important arithmetic and logic operations together into a single `@OP` reference.
+- 🧑 ✅ Make the `stdlib` as orthogonal as possible to `@OP`.
+- 🧑 ✅ Higher-order helpers (`map`, `filter`, `reduce`, `compact`, `flatten`, `any`, `all`) are implemented via recursion in Fusion, not hidden in Ruby. They work for both arrays and objects where possible.
+- 🧑 ✅ Provide access to more advanced mathematical operations in `@math`.
+- 🧑 ✅ Where possible, builtins and stdlib functions are n-ary instead of binary.
+
+### Alternatives
+
+- 🤖 ⏪ Keep every operator as its own builtin (the §5.3 set). Superseded: bundling into `@OP` gives a directory one place to shadow them all.
+- 🤖 ❌ Resolve `@OP` **dynamically** (at the call site) so stdlib helpers follow a foreign override. Rejected: it breaks per-directory confinement.
+
+### Pros
+
+- By bundling operators into `@OP`, the presence of an `OP.fsn` file will immediately become a warning sign that core operations might behave differently in a given directory.
+- By making the `stdlib` orthogonal to `@OP`, a shadowed `@OP` will not create footguns where `stdlib` functions still refer to the original implementation.
+
+### Cons
+
+- Not all operators with syntax sugar have been grouped into `@OP`. Exceptions are the structural operators `@map`, `@filter`, `@reduce`.
+- The few helpers that still reference `@OP` (currently only `@range`) will ignore `@OP` overrides. To make them aware of `@OP` overrides, create a copy of their `stdlib` source code next to your `OP.fsn`.
+- The native way of writing division `[a, b | @OP.negate] | @OP.product` is numerically incorrect and might produce a double rounding error. For the numerically correct division you have to use `@math.divide`.
+
+---
+
+## 5.6 Syntax sugar
+
+Implements the infix-operator sugar deferred in §5.1. Additionally adds `map` / `filter` / `reduce`
+pipe operators. Promotes `[]`/`[=]` to core syntax. Desugaring is purely syntactic. The only new
+runtime node is the `[=]` setter.
+
+### Decisions
+
+- 🔢 ✅ Precedence, tightest→loosest: postfix (`.` `[]` `[=]`) → unary prefix (`! - / ~`) → pipe (`| |: |? |+`) → multiplicative (`* / % //`) → additive (`+ -`) → `??` → `==` → `&&` → `||`. Pipe binds just under unary, tighter than every value operator.
+- 🧑 ✅ The array/object setter gets promoted to core syntax `container[key = value]`. The `@set` builtin is removed.
+- 🧑 ✅ The getter `container[key]` stays core syntax instead of becoming syntax sugar for `@get`. The `@get` builtin is removed.
+- 🧑 ✅ A maximal run of `+`/`-` folds to one `[terms] | @OP.sum`; a run of `*`/`/` to one `[terms] | @OP.product`. `-` operands are negated, `/` operands inverted.
+- 🧑 ✅ `-` is always an operator; the lexer emits no negative-number literals.
+- 🧑 ✅ A `-` before a bare numeric literal folds into a negative literal (in expressions and patterns alike); any other operand becomes `operand | @OP.negate`. In a pattern, `-` may only precede a numeric literal.
+- 🧑 ✅ `/` never folds to a literal: `a / 2` → `[a, 2|@OP.invert] | @OP.product`, so `/0` stays a runtime `math_error`.
+- 🧑 ✅ A single `/` is a path separator only inside a file-reference path; elsewhere it is division/invert. `@a/b` is the path `a/b`; `@a / b` (any space around the slash) is `@a` divided by `b`.
+- 🧑 ✅ The lexer emits a `path` token only immediately after `@`/`@@`, tight: no space after `@`/`@@`, interior slashes abutting their segments. A path starts with an identifier or `..`, never a lone `.` (so `@.map` is `.map` access on bare `@`). Bare `@`/`@@` when no tight path follows.
+- 🧑 ✅ Whitespace between `@`/`@@` and its path is no longer allowed (`@ name` is a syntax error).
+- 🧑 ✅ Runs of `==`/`&&`/`||` fold n-ary to `@OP.equal`/`@OP.and`/`@OP.or`.
+- 🧑 ✅ `??` is its own precedence level, tighter than `==` (compare produces an ordinal that `==` then tests; a boolean can't be compared).
+- 🧑 ✅ `xs |: f`, `xs |? f`, `xs |+ f` desugar to `{"c": xs, "f": f}` piped into `@map`/`@filter`/`@reduce`.
+
+### Alternatives
+
+- 🤖 ⏪ Lex negative-number literals (JSON-style). Rewound: `a-3` would be ambiguous between the literal `-3` and subtraction.
+- 🤖 ❌ Desugar every `-x` to `x | @OP.negate`, dropping literal negatives. Rejected: `-5` should stay a plain literal, not an `@OP`-routed computation.
+- 🤖 ❌ Assemble the path in the parser so `@a / b` is also the path `a/b` (divide via `(@a) / b`). Rejected: a spaced `@a / b` should read as division like every other operator.
+
+### Pros
+
+- Giving `pipe` the tightest precedence keeps the "useful reading" paren-free: a pipe's RHS has to always be a function and arithmetic never yields one, so `x|@f + 1` can only sensibly mean `(x|@f) + 1`.