myxo-lang 1.5.0

package/CONCURRENCY.md

@@ -0,0 +1,207 @@
+# Myxo Concurrency — `dispatch` / `gather`
+
+> Real multi-core parallelism, built on Myxo's own bones (the worker+Atomics pattern from `myxo-live`).
+> Honest about its shape: this is **parallelism of pure-ish, isolated tasks** — not cooperative coroutines,
+> not shared-memory threads. The isolation is the feature: it is what makes the parallelism race-free.
+
+## The model
+
+```
+dispatch f(args...)     ->  an UNSTARTED task (a handle). Nothing runs yet.
+gather [t1, t2, ...]    ->  runs every task on its own OS thread, in parallel,
+                            blocks until all finish, returns their results IN ORDER.
+```
+
+```myx
+agent slow(n) { seed s = 0
+  for each i in range(n) { s = s + (i % 7) }
+  report s
+}
+
+emit gather [dispatch slow(8000000), dispatch slow(8000000), dispatch slow(8000000)]
+```
+
+`gather` is an ordinary expression — its result is a list, so it composes with everything: `gather tasks | sum`,
+`seed [a, b] = gather [...]`, `match gather [...] { ... }`.
+
+## Why this shape (and not threads-with-shared-memory)
+
+Myxo's law is *"agents do not merge."* Shared mutable state across threads is exactly merging — and the bug
+factory (data races) that comes with it. So a dispatched task runs in **its own fresh interpreter**: it sees
+
+- the **standard library**,
+- **its own arguments**, and
+- **itself** (so recursion works),
+
+and **nothing else** — not the parent's pathways, not other user agents, not captured closure state. A task
+that reaches for a parent pathway fails *cleanly* (`unknown pathway 'x'`) rather than silently reading a stale
+copy. Isolation by construction means there is no shared state to race on. That is the whole trick.
+
+The cost of isolation is the **data boundary**: arguments and results cross threads *by value*, so they must be
+plain data — `number`, `string`, `bool`, `list`, `mesh`, `void`. Passing or returning an **agent** (code closes
+over an environment that cannot follow it across the boundary) is rejected loudly at the boundary, never shipped
+as a meaningless blob.
+
+## How it works (the mechanism is ours)
+
+The interpreter is a synchronous tree-walker, and we keep it that way. `gather` gets parallelism without going
+async by reusing the zero-dependency **worker + `Atomics` + `SharedArrayBuffer`** pattern already proven in
+`myxo-live`:
+
+1. `gather` spawns one `Worker` (`myxo-par-worker.js`) per task, handing each the agent's AST (`params` + `body`)
+   and its args as JSON, plus one shared `Int32Array` barrier counter and a private `MessageChannel`.
+2. Each worker builds a fresh interpreter, defines the agent under its own name (recursion), runs it, then in a
+   `finally` — on *every* path, success or error — posts its result (or its error) and `Atomics.add`s the
+   barrier counter and notifies. Posting before ticking means a visible tick guarantees the message is queued.
+3. The calling thread blocks on `Atomics.wait` until the counter reaches N (Node permits `Atomics.wait` on the
+   main thread; browsers do not). It then drains each channel with `receiveMessageOnPort` and returns the
+   results in input order. Workers and ports are always reclaimed in a `finally`, even on throw or timeout.
+
+**Error handling, precisely.** A task that `fail`s, throws, hits a runtime error (e.g. reaches for a parent
+pathway), or fails to even load its interpreter surfaces *promptly* as a single `gather: <message>` error —
+because the worker runs its barrier-tick from a `finally`, so any worker that executes *any* JS reports back.
+The first error wins; the whole `gather` fails (all-or-nothing, like `Promise.all`). The one case the worker
+*can't* self-report is a true hard death (OOM, `SIGKILL`) where the `finally` never runs — that is caught by
+the wall-clock timeout (default 30s), which terminates the stragglers and throws a `timed out` error. (We do
+*not* rely on a parent-side `error`/`exit` callback to release the barrier: the event loop is frozen during
+`Atomics.wait`, so those callbacks can't fire mid-gather — they exist only so a worker failure can't crash the
+parent process.)
+
+## What is honest about the performance
+
+Measured on the dev laptop (i7-8750H, 6 physical / 12 logical cores, ~2GB free RAM):
+
+- **The interpreter runs at native speed inside a worker.** Pure compute, startup excluded: main 4.70s vs
+  worker 4.65s for the same loop. There is *no* per-worker interpreter penalty.
+- **Parallelism is real.** Two CPU-bound tasks complete in ~1.05x the time of one (18.5s vs 17.4s) — two tasks
+  for the price of one.
+- **Speedup is bounded by the machine, not the language.** 4 tasks do **not** hit 4x on this box, because of
+  (a) only 6 physical cores, (b) ~2GB free RAM (large allocations like `range(8_000_000)` thrash), and
+  (c) aggressive thermal throttling under sustained all-core load. On a cooler, higher-core machine the curve
+  keeps climbing.
+- **Worker startup is ~0.2s** (a fresh interpreter + stdlib parse) and overlaps across workers. Parallelize
+  *expensive* work; for trivial work the startup dominates.
+
+## Limits (v1, on purpose)
+
+- **One worker per task per gather** (no pool yet). Fine for coarse-grained work; a pool is a future optimization.
+- **Tasks are isolated** — no shared state, no inter-task channels. Coordination is by *structure* (dispatch →
+  gather), not by message-passing between running tasks.
+- **Self-contained agents only.** Calling *other* user agents from inside a dispatched agent fails (they are not
+  defined in the worker). Inline what the task needs, or pass it as data.
+- **Not cooperative concurrency.** There is no `yield`/await; this is OS-thread parallelism with a blocking
+  barrier. A cooperative scheduler is a separate, later layer (and the road toward the Physarum scheduler).
+
+---
+
+# The Physarum scheduler — `schedule` / `flows`
+
+> Where `gather` runs a fixed list of tasks, `schedule` runs a **batch through a learning pool**. It is `route`
+> (the slime-mold *selector*) lifted to parallel batches: the same reinforce/decay law that governs memory now
+> governs **execution** — fast workers pull more flux, slow/failed ones decay and get routed around. The
+> language *becomes* the scheduler.
+
+```myx
+agent worker(chunk) {           # a worker takes a CHUNK (a list) and returns a results list, same length, in order
+  seed out = []
+  for each x in chunk { out = out + [x * x] }
+  report out
+}
+
+emit schedule("squares", [worker, worker], [1, 2, 3, 4, 5, 6, 7, 8])   # -> [1, 4, 9, 16, 25, 36, 49, 64]
+emit flows("squares")                                                   # the learned conductance of each tube
+```
+
+## What it does
+
+`schedule(name, workers, items)`:
+1. Looks up (or creates) a **named, persistent pool** of interchangeable worker-agents — `name` keys the learned
+   state, exactly like `route`. Reusing a name with different workers is rejected (no silent stale pool).
+2. **Distributes** the items across the workers proportional to conductance, via the same credit + explore-floor
+   weighted round-robin as `route`. The credit array is **persisted on the pool** across calls, so a trailing or
+   recovered worker is sampled at a rate ∝ its conductance over successive batches (not starved by small batches).
+3. Runs each worker's chunk on its **own worker thread, in parallel** (`gather`'s settled runner underneath),
+   blocks, and reassembles every result at its **original item index**.
+4. Updates each worker's conductance from its **measured per-item speed** (the worker reports its own compute
+   time): `quality = 1 + 8/(ms_per_item + 1)`, `cond ← EWMA(cond, quality)`. Fast workers climb; a worker that
+   errors decays toward the floor.
+
+`flows(name)` returns the pool's learned conductances (it also reports `route` conductances — one viewer for both).
+
+## Failover
+
+If a worker errors, its conductance decays hard and **its items reroute to the survivors** in one more parallel
+round — the slime mold routing around a damaged tube. If every worker fails (or a survivor also fails during the
+reroute), `schedule` throws rather than returning partial/silent results. Failover is **single-tier on purpose**:
+one reroute round, then surface the error. (A multi-tier cascade is a future option; one tier covers the common
+"some tubes are dead" case without unbounded retry.)
+
+## What is honest about it
+
+- **Adaptation needs more than one call.** The first batch explores (uniform-ish); conductances diverge as speed
+  is measured, so *later* batches exploit. Measured: a fast/slow pool over 4 rounds converged to roughly
+  `{fast: 7, slow: 1}` — the next batch then routes ~7× the flux to the fast tube. Same explore-then-exploit
+  honesty as `route`; the constants are hand-tuned and exploit-leaning.
+- **Timing is nondeterministic**, so exact conductances vary run to run. The guarantees that *don't* vary:
+  every item is processed exactly once, results are in item order, and a clearly-faster worker ends higher.
+- **Worker contract:** batch in, batch out (`worker(chunk) -> results`, one result per item, in order). This
+  spawns *N* threads (one per worker), not one per item — efficient for real batches. A wrong-length or non-list
+  return is a loud contract error. The `dispatch` data boundary applies: items and results must be plain data.
+- **No shared state between workers** (same isolation as `gather`) — which is exactly why distributing work
+  across them is race-free.
+
+---
+
+# Cooperative concurrency — fibers + channels (`spawn` / `give` / `take` / `yield` / `await`)
+
+> Where `gather`/`schedule` give **parallelism** (many OS threads, isolated tasks), fibers give the other half:
+> **concurrency** — many tasks interleaving on *one* thread, talking through **channels**. It's the
+> law-consistent way to do *communicating* tasks: no shared memory, the value passes hand to hand.
+
+```myx
+seed ch = channel()                              # an unbounded channel; channel(n) is bounded (backpressure)
+
+agent producer(c) { seed i = 0
+  reinforce i < 3 { give i to c                   # `give VALUE to CHANNEL` — blocks only if a bounded channel is full
+    i = i + 1 } }
+
+agent consumer(c) { seed k = 0
+  reinforce k < 3 { take x from c                 # `take NAME from CHANNEL` — parks the fiber until a value arrives
+    emit x
+    k = k + 1 } }
+
+spawn producer(ch)                                # start a fiber (cooperative, NOT a thread)
+spawn consumer(ch)                                # both run, interleaved, at program end -> 0 1 2
+```
+
+## The model
+
+- `spawn f(args)` — start a **fiber** and return a handle. Fibers run **cooperatively** on the calling thread:
+  one runs until it parks on a channel (or `yield`s), then the scheduler runs the next ready fiber. This is
+  *concurrency, not parallelism* — for real multi-core work use `gather`/`schedule`.
+- `give VALUE to CHANNEL` / `take NAME from CHANNEL` — send / receive. A `take` on an empty channel parks the
+  fiber until a value is given; a `give` to a *full bounded* channel parks until space frees. Delivery is
+  **exactly-once, FIFO**.
+- `yield` — voluntarily give up the turn (cooperative round-robin).
+- `await(fiber)` — run the scheduler and return that fiber's reported value (or re-raise its error). `drain()` —
+  run **all** fibers to completion. Spawned-but-unawaited fibers also run at program end; a failed fiber's error
+  **never vanishes** — it surfaces at `await`/`drain`/program end.
+- `channel()` unbounded; `channel(n)` bounded to `n` (backpressure). Channels are not data — they can't cross the
+  `gather`/`dispatch` thread boundary (rejected loudly).
+
+## Why it's race-free
+
+A channel is the *only* thing shared, and a value moves through it hand to hand — there is no shared mutable
+state for two fibers to clobber. The scheduler is single-threaded and **deterministic**, so a fiber program's
+output is reproducible (unlike the timing-dependent parallel side).
+
+## Honest scope (v1)
+
+- **Cooperative, not parallel** — fibers interleave on one thread. (Compose with `gather` when you need cores.)
+- **Suspension composes through** the fiber's own body and inside `when` / `match` / `for each` / `reinforce` /
+  `attempt`. It does **not** cross into a *called* agent's body (a helper a fiber calls can't `give`/`take`) — that
+  would need the whole call stack to be suspendable. Doing so is a **clear, honest error**, not a silent failure.
+- `await`/`drain` can't be called from *inside* a fiber (that would re-enter the scheduler) — coordinate with
+  channels or `yield` instead; a clean error says so.
+- A runaway fiber (e.g. `yield` forever) is bounded by a step budget and **errors**, never hangs.
+- No `select`/timeouts/closeable channels yet; deadlocks (everyone parked) are detected and reported.

package/HOW_IT_WORKS.md

@@ -0,0 +1,235 @@
+# How Myxo Works
+
+Myxo has two jobs:
+
+1. Be an independent language with its own source files, runtime behavior, standard library,
+   tooling, and release path.
+2. Connect useful external runtimes through fenced capabilities: rich bridges for runtimes like
+   Python and Node, conditional bridges such as Perl when installed, and weaker executable/CLI
+   bridges for compiled tools like C++, Rust, and Go binaries.
+
+Those jobs are separate on purpose. Myxo can run by itself. Foreign languages extend it; they do
+not define it.
+
+## 1. The Standalone Language Core
+
+A `.myx` program is real Myxo source. It is not translated into Python or C++ first.
+
+```text
+.myx source
+  -> lexer.js
+  -> parser.js
+  -> AST
+  -> interpreter.js
+  -> output + value + audit ledger
+```
+
+Current implementation:
+
+- `lexer.js` tokenizes Myxo source.
+- `parser.js` builds the AST.
+- `interpreter.js` walks the AST and enforces Myxo semantics.
+- `builtins.js` installs the core standard functions.
+- `std.myx` is a self-hosted standard library written in Myxo.
+- `myxo.js` is the CLI, REPL, formatter entrypoint, and Node embed API.
+
+That means these are Myxo language behavior, not aliases over another runtime:
+
+- `seed` creates a pathway.
+- `agent` defines a callable Myxo function.
+- `report` returns from an agent.
+- `reinforce` loops.
+- `decay` removes a pathway.
+- `attempt` / `rescue` handle failures.
+- `needs` declares external capabilities.
+- pathway strength rises when names are read.
+- routing and mesh behavior live in the interpreter.
+
+The reference engine is currently written in Node. That is an implementation fact, not the
+language identity. The independence path is to keep this Node tree-walker as the reference
+while tightening a spec and eventually adding bytecode/native or other host runtimes.
+
+## 2. Values And Execution
+
+Myxo values are intentionally small and portable:
+
+- numbers
+- strings
+- `live` / `dead`
+- `void`
+- lists
+- meshes
+- agents
+
+The interpreter stores named values in environments. A named value is a pathway. Reading a
+pathway reinforces it by increasing its strength. `mesh()`, `strength(name)`, `prune()`, and
+`metabolize()` expose that behavior to Myxo code.
+
+Agents are closures over their environment. The runtime can hot-promote pure agents by memoizing
+calls it can prove safe: plain parameters, primitive arguments/results, no capabilities, no
+observable side effects, no mutable outer-data dependency, and no stale global epoch.
+
+## 3. Builtins vs Capabilities
+
+Myxo has a hard distinction:
+
+- **Builtins** are ordinary language power: math, strings, lists, meshes, output, routing.
+- **Capabilities** are host power: database calls, Telegram, Python, C++ binaries, shell,
+  MCP tools, filesystem module loading, or anything outside the interpreter.
+
+A capability does not exist inside a script unless the host registers it.
+
+Even if the host registers it, production runners can require the script to declare it:
+
+```myx
+needs lookup, spend(max 5, total 15)
+
+emit lookup("lead")
+emit spend(4)
+```
+
+The production fence is:
+
+```text
+host allowlist
+  -> script `needs` manifest
+  -> value budget checks
+  -> call execution
+  -> audit ledger
+```
+
+If a script calls a capability it did not declare, Myxo refuses before the host is touched. Every
+allowed call and every refusal is recorded in the audit ledger.
+
+Production runners also add operational limits:
+
+- `requireManifest`: capability calls require `needs`.
+- `maxSteps`: interpreter fuel for runaway loops.
+- `timeoutMs`: live worker wall-clock timeout.
+- `moduleLoader: null`: fences `weave` unless the host grants file loading.
+
+## 4. Polyglot: How Python, C++, And Others Plug In
+
+Polyglot support is foreign-function interface, not identity.
+
+Myxo sees every foreign language call as a capability:
+
+```myx
+needs pycall(total 3)
+
+seed result = pycall("tools.py", "score", "lead-17")
+emit result
+```
+
+The outer Myxo law is the same whether the capability is implemented in Myxo, Python, C++, Node, or
+a remote tool:
+
+```text
+Myxo script -> capability name -> host bridge -> foreign runtime -> Myxo value
+```
+
+### Rich Runtime Bridge
+
+`polyglot.js` currently has rich value-mapped runners for:
+
+- Python: `pycall`, `pyeval`
+- Node: `jscall`, `jseval`
+- Perl: `plcall`, `pleval` when Perl is installed
+
+These runners use a JSON/framed-result protocol so lists, meshes, numbers, strings, booleans,
+and `void` can cross the boundary cleanly. Non-finite numbers are rejected instead of silently
+becoming null. In the current machine test run, Python and Node passed; Perl support is present
+but skips when `perl` is not on PATH.
+
+### Compiled/CLI Bridge
+
+C++, Rust, Go, and many existing tools usually plug in first as compiled executables:
+
+```text
+Myxo -> bridgeExec("my_tool.exe") -> argv/stdout -> Myxo string
+```
+
+That is intentionally weaker than the rich bridge:
+
+- stdout is the result
+- structured values need JSON discipline from the executable
+- Myxo can still fence, budget, and audit the call boundary
+
+The stronger future version is a stable Myxo FFI/wire protocol so compiled languages can expose
+structured functions instead of only command-line stdout.
+
+## 5. MCP And JAMES Are Hosts, Not The Language
+
+MCP tools are another capability catalog. `mcp-bridge.js` turns each MCP tool into a fenced Myxo
+capability. `myxo-run.js` and `myxo-live.js` are production runners for agent-written scripts.
+
+JAMES uses this by exposing a narrow `james_nx_run` surface. That is one host integration. Myxo
+must still work without JAMES:
+
+```text
+node myxo.js examples/fib.myx
+node myxo.js
+node myxo.js fmt examples/fib.myx --check
+npm test
+```
+
+## 6. Security Boundary
+
+The fence controls which verb a script may call, how often or how much it may spend, and what
+gets logged at the Myxo boundary.
+
+The fence does **not** sandbox the code inside a granted arbitrary runtime.
+
+If you grant:
+
+- `pyeval`, the script has Python eval power.
+- `jseval`, the script has Node eval power.
+- `sh`, the script has shell power.
+- a C++ executable, the script can run that executable.
+
+Budgets are argument and call-count policies. They are not CPU, filesystem, network, or
+subprocess sandboxes for whatever happens inside the granted runtime.
+
+For untrusted or model-generated scripts, expose shaped capabilities instead:
+
+```text
+good:  score_lead(id)
+bad:   pyeval(any_code)
+good:  resize_image(input, output)
+bad:   sh(any_command)
+```
+
+That is where Myxo is strongest: it gives agents narrow verbs, budgets, time/fuel limits, and an
+audit trail.
+
+## 7. The Short Version
+
+Myxo should become "another Python/C++" in independence, not in purpose.
+
+It should own:
+
+- `.myx` files
+- syntax and semantics
+- runtime behavior
+- standard library
+- CLI and REPL
+- tests and formatter
+- docs and spec
+- release path
+
+It should connect:
+
+- Python for Python work
+- C++/Rust/Go binaries for compiled work
+- Node for JS work
+- MCP/JAMES/tools for system work
+
+The point is one independent language that can coordinate many runtimes under one law:
+
+```text
+declare what you need
+stay inside the budget
+leave an audit trail
+route to the best provider
+run standalone when no foreign runtime is needed
+```

package/INDEPENDENCE.md

@@ -0,0 +1,24 @@
+# Myxo Independence Contract
+
+Myxo must be a real language, not only a wrapper around other languages.
+
+The target is this:
+
+- **Standalone first.** A `.myx` program runs as Myxo source through the Myxo CLI/runtime/stdlib without requiring Python, C++, Node scripts, shell glue, or JAMES.
+- **Own semantics.** `seed`, `agent`, `reinforce`, `decay`, `needs`, budgets, audit ledger, pathway strength, and flow routing are Myxo language behavior, not comments over another runtime.
+- **Own toolchain.** Myxo needs a CLI, REPL, formatter, tests, docs, versioning, module rules, errors, and eventually an LSP/debugger and bytecode/native runtime path.
+- **Foreign runtimes are FFI.** Python, Node, Perl, shell, MCP, and compiled binaries such as C++/Rust/Go tools are called through explicit fenced capabilities. They extend Myxo; they do not define Myxo.
+- **One outer law at the boundary.** Whether a capability is written in Myxo, Python, C++, or anything else, the Myxo caller still goes through `needs`, host allowlists, budgets, fuel/timeouts where applicable, and the audit ledger. Myxo does not sandbox arbitrary side effects inside a granted runtime; hosts should expose narrow structured verbs for untrusted callers.
+- **No hidden dependency on Nexus.** Nexus/JAMES can host Myxo, but Myxo must remain usable by itself from the command line and embeddable by other hosts.
+
+## What "another Python/C++" means here
+
+Myxo should become a peer in the toolchain: a language someone can install, run, learn, test,
+package, and ship. It does not need to replace Python for data scripting or C++ for systems
+performance. It needs to be independent the way they are independent: it owns a file format,
+runtime, standard library, behavior, documentation, and release path.
+
+## Boundary
+
+Polyglot bridging is still core. Myxo connects the useful languages, but as a conductor with its
+own score, not as a thin alias for any one of them.

package/MYXO_PROMPT.md

@@ -0,0 +1,139 @@
+# Myxo — write this language (prompt card)
+
+Myxo is a small scripting language. You will be given a task; return ONLY Myxo code. Myxo is NOT Python, NOT
+JavaScript, NOT C — do not assume their syntax. Learn it from the rules and examples below, then write.
+
+## The 6 rules you must not break
+
+1. **NO SEMICOLONS. EVER.** Statements end at the end of the line — never write `;`. `seed x = 1` then a
+   newline. A `;` is a syntax error.
+2. **Booleans are `live` and `dead`** — never `true`/`false`. `report live`, `when x { ... }`.
+3. **Functions are `agent`s; return with `report`.** `agent add(a, b) { report a + b }`. No `function`, no
+   `def`, no `return`, no `=>` for statements.
+4. **Declare a variable with `seed`, reassign with plain `=`.** `seed n = 0` then later `n = n + 1`.
+5. **`==` on two lists or two meshes compares IDENTITY, not contents** — `[1,2] == [1,2]` is `dead`. Compare
+   length + elements yourself. (Inside `match`/`expect`, equality IS structural.)
+6. **Mesh keys are strings.** `{ "a": 1 }`. The number `1` and the string `"1"` are the SAME key.
+
+## Core syntax by example (imitate these)
+
+```myx
+# variables, agents, report
+seed name = "Zero"
+agent greet(who) { report "hi " + who }
+
+# conditionals — `when` / `otherwise`, blocks in { }
+agent sign(n) {
+  when n > 0 { report "pos" }
+  otherwise when n < 0 { report "neg" }
+  otherwise { report "zero" }
+}
+
+# loop over a list, mesh (keys), or string (chars)
+agent total(xs) {
+  seed s = 0
+  for each x in xs { s = s + x }
+  report s
+}
+
+# while-loop is `reinforce COND { }`; repeat is `reinforce N times { }`
+agent countdown(n) {
+  reinforce n > 0 { emit n  n = n - 1 }
+}
+
+# lists and meshes
+seed nums = [1, 2, 3]
+seed person = { "name": "Zero", "age": 30 }
+emit person["name"]              # index a mesh by key, a list by integer (negatives from end: xs[0-1] = last)
+seed longer = nums + [4]         # + concatenates two lists; + concatenates if EITHER side is a string
+seed n = len(nums)               # len works on list/mesh/string
+
+# default + rest params, and closures
+agent log(msg, level = "info", ...rest) { report level + ": " + msg }
+agent adder(k) { report agent(x) { report x + k } }   # returns a closure
+
+# pattern matching — `match` (first arm whose shape fits runs)
+agent describe(v) {
+  match v {
+    [] { report "empty" }
+    [x] { report "one" }
+    { "kind": k } { report k }      # mesh that HAS key "kind"; binds k
+    _ { report "other" }            # wildcard
+  }
+}
+
+# errors — attempt / rescue, and fail
+agent safe_div(a, b) {
+  attempt { report a / b } rescue e { report "undefined" }   # e is a mesh { message, line, value }
+}
+
+# pipeline: x | f  ==  f(x) ; x | f(a) == f(x, a)  (piped value is the FIRST arg)
+agent inc(x) { report x + 1 }
+seed y = 5 | inc | inc          # 7
+```
+
+## Truthiness & and/or (these trip up Python/JS habits)
+
+- **Dead (falsy):** `void`, `0`, `""`, empty list `[]`, empty mesh `{}`. Everything else is live.
+- **`and`/`or` return a VALUE, not a bool** (and short-circuit): `a or b` → `a` if `a` is live, else `b`.
+  So `x or default` gives a fallback. `a and b` → `a` if `a` is dead, else `b`.
+
+```myx
+agent with_default(v, fallback) { report v or fallback }   # 0/""/[] all fall back, not just void
+```
+
+## The capability fence (only when the task mentions natives / a manifest / budgets)
+
+A script reaches the host ONLY through granted natives, and must DECLARE them with `needs` at the top.
+
+```myx
+needs lookup, spend(max 5, total 15)     # spend is budgeted: max per call, total cumulative
+
+seed r = lookup("x")
+emit "got: " + r
+attempt {
+  spend(9)                               # over the max-5 cap -> the fence refuses it
+  emit "spent"
+} rescue e {
+  emit "blocked"                         # a fence denial is catchable like any error
+}
+```
+
+Calling a native you did not `needs`-declare is refused even if the host granted it.
+
+## Concurrency (only when the task asks for parallel / fibers / channels)
+
+```myx
+# parallel: dispatch builds a task, gather runs them on real threads, results in order
+agent sq(n) { report n * n }
+agent squares(xs) {
+  seed tasks = []
+  for each x in xs { tasks = tasks + [dispatch sq(x)] }
+  report gather tasks
+}
+
+# fibers + channels (one thread, cooperative): spawn / give..to / take..from / await
+agent producer(c, xs) { for each x in xs { give x to c } }
+agent consumer(c, n) { seed s = 0  reinforce n times { take v from c  s = s + v }  report s }
+agent sum_via_channel(xs) {
+  seed ch = channel()
+  spawn producer(ch, xs)
+  seed job = spawn consumer(ch, len(xs))
+  report await(job)
+}
+```
+
+## The 5 traps (right vs wrong)
+
+| Trap | WRONG (a Python/JS habit) | RIGHT (Myxo) |
+|---|---|---|
+| Semicolons | `seed x = 1;` | `seed x = 1` (newline ends it) |
+| Booleans | `report true` | `report live` |
+| List equality | `report a == b` | compare `len` + each element in a loop |
+| Mesh keys collide | assuming `1` ≠ `"1"` as keys | they are the SAME key (keys coerce to strings) |
+| Fallback only on null | `when v == void { ... }` | `v or fallback` (0/""/[] are also dead) |
+
+## How to answer
+
+Return ONE ```myx code block. Define exactly the agent(s) the task names — no extra prose, no `main`, no
+semicolons. Prefer the patterns above; when unsure, keep it simple and let `report` return the value.