myxo-lang 1.5.0

package/VISION.md

@@ -0,0 +1,249 @@
+# Myxo — The Vision: leave nothing unimagined
+
+> Myxo is Milton's language. Its keywords *are* the Nexus law — `seed`, `reinforce`,
+> `decay`, `agent` — and its only bridge to the world is a **capability fence**: an Myxo
+> script can touch nothing the host did not explicitly hand it. This document imagines
+> Myxo **whole** — everything it becomes when perfected — and lays the honest road from
+> here to there. Dream first; the roadmap at the end is real.
+
+---
+
+## 0. The thesis — why Myxo deserves to exist
+Myxo must be independent: a language you can install, run, learn, test, package, and ship,
+not a thin prompt wrapper around Python, C++, Node, JAMES, or any one host. It should become
+a peer in the toolchain the way Python and C++ are peers: its own source files, runtime,
+standard library, errors, modules, docs, release path, and community surface.
+
+That does **not** mean Myxo should imitate Python's data ecosystem or C++'s systems niche.
+Most languages are general; Myxo wins by owning a domain that is exploding and has no good
+language yet: **the script you hand an autonomous agent.**
+
+In the agent era, code is increasingly *written by* and *executed by* AI. That code needs
+two things almost no existing language gives it natively:
+1. **Capability by construction** — the agent can only do what it was granted. Not a
+   sandbox bolted on, not a permission list checked at runtime — *absence*. "`spend()`
+   isn't blocked; it doesn't exist in this agent's universe. There's nothing to bypass."
+2. **Code that reads like intent** — `seed`, `reinforce`, `decay`, `agent`, `attempt`,
+   `rescue` — a vocabulary a human can audit at a glance and a model can emit cleanly.
+
+Plus one idea no other language has: **the program gardens itself.** Useful pathways
+reinforce, useless ones decay and get pruned — at runtime, in the language's own bones.
+
+That is the go-to claim, honestly stated: **Myxo becomes "the next go-to for coding" the way
+SQL is the go-to for queries** — independent like Python/C++, but winning by *owning the
+agent-action domain* so completely that reaching for anything else feels wrong.
+
+---
+
+## ✅ v0.6 — THE LIVING MESH IS REAL (shipped 2026-06-26, two-agent gated)
+The "gardens itself" idea above is no longer aspiration — the runtime now ACTS on pathway strength:
+
+- **Hot-promote (automatic):** a *hot* + *provably-pure* agent memoizes itself. No keyword, no cache call — the runtime watches the pathway and promotes it. `fib(30)` is instant despite ~2.7M naive calls. ("Useful pathways reinforce", executing.)
+- **`strength(name)`:** read any pathway's heat in-language.
+- **`metabolize(threshold)`:** the decay half, as an explicit VERB you call — sweeps cold pathways, reports `{reaped, count, promoted}`. (`prune` is its terse twin.)
+
+**Honest scope (the gate insisted, and it was right):**
+- "Self-optimizing" = automatic *memoization of pure agents* — a real, measurable optimization, not magic.
+- Cold-decay is **NOT** a background garbage collector. `metabolize`/`prune` are verbs the program/host invokes; there is no autonomous time-based sweep (yet).
+- Memoization is **sound, not invisible**: a value is served only from a call the runtime proved pure — plain params only; never tainted by a capability / `random` / `emit` / `weave` / a state-reading builtin (`mesh`/`strength`) / an outer write / a free DATA read (reading a free *agent* is allowed, for recursion); primitive args + result; and a global **epoch** invalidates every cache on any global write. A two-agent review found 4 real staleness bugs + a dead off-switch in the first cut — all fixed and pinned by `soundness:` tests (memo-ON must equal memo-OFF). It does NOT claim to leave mesh *strengths* identical — collapsing repeated work also collapses repeated reinforcement, by design.
+- **89 tests green.** Demo: `examples/living-mesh.myx`.
+
+---
+
+## ✅ POLYGLOT BRIDGE — Myxo connects other languages (shipped 2026-06-26, two-agent gated)
+A capability is just `name → fn`, so each language is a fenced RUNNER (`polyglot.js`). **Two tiers — honest, NOT one contract:**
+- **RICH** — `defineLang()` → value-mapped `Xcall(file,func,...args)` + `Xeval(expr)` (mesh/list/number/bool round-trip; structured returns). Built + tested here: **Python** (`pycall`/`pyeval`) and **Node** (`jscall`/`jseval`). **Perl** (`plcall`/`pleval`) is implemented and tested when `perl` is on PATH; on this machine those tests currently skip. Needs a runtime with an eval flag; Ruby (`-e`) fits the same future shape. Each harness is small but **not trivial** — it carries that language's module-load / hard-exit / JSON / eval quirks.
+- **WEAK** — `bridgeExec(cmd)` → raw stdout string in/out, *no value mapping*; the only path for compiled langs (Go/Rust/C++ binaries) + CLIs. Plus `sh`.
+
+Every cross-language call passes the outer Myxo law at the boundary: declared in `needs`, bounded by budgets (numeric first-arg = spend; otherwise = **call count**), logged in the audit ledger. Non-finite numbers are an explicit error on every rich path (never a silent null). Compiled languages currently plug in through `bridgeExec`/CLI stdout unless the host wraps them as narrower structured capabilities. Demo `examples/polyglot.myx`; 19 passing polyglot tests plus 5 Perl skips when `perl` is absent.
+
+**Honest boundary (the gate insisted, and it was right):** `pyeval`/`pycall`/`sh` are **ARBITRARY-CODE** capabilities — granting one grants the FULL power of that runtime. The fence bounds WHICH verb a script may reach and HOW MANY times, **NOT** what the code inside that verb does (the ledger logs `pyeval`, not the subprocess it spawned). For untrusted / model-generated callers, expose only **STRUCTURED** capabilities (one specific tool/function), where the fence is meaningful end to end. "Slime mold" = the governance + living-mesh strength bookkeeping; there is **no automatic language-routing yet** (a future plank). The gate caught + fixed: non-finite returns crashing raw, an `atexit` result-spoof, inert budgets on string-arg verbs, and structured-arg flattening.
+
+---
+
+## Independence contract — Myxo is not just glue
+Polyglot bridging is core, but the bridge must not become the identity. Myxo remains its own
+language with its own execution model. Foreign runtimes are FFI surfaces: Python for Python
+work, C++/Rust/Go binaries for compiled work, Node for JS work, MCP for tool catalogs. Myxo is
+the independent boundary layer that decides what can be called, how often, with what budget,
+and what gets logged. It does not sandbox arbitrary code after a host grants a broad runtime
+verb.
+
+The standalone contract is tracked in [`INDEPENDENCE.md`](INDEPENDENCE.md):
+- A `.myx` program must run from the Myxo CLI without JAMES/Nexus.
+- Myxo semantics live in Myxo: `agent`, `needs`, budgets, audit ledger, pathway strength, routing.
+- Tooling grows around Myxo itself: formatter, tests, docs, module rules, LSP/debugger, release path.
+- Other languages extend Myxo through explicit capabilities; they do not define Myxo.
+
+---
+
+## ✅ AUTOMATIC FLOW-ROUTING — the slime mold re-routes itself (shipped 2026-06-26, two-agent gated)
+`route(name, [providers])` makes interchangeable providers (agents / tools / languages) one logical capability and the runtime LEARNS which to use. **Conductance = each tube's recent QUALITY** (an EWMA of success + speed); traffic flows **proportional to conductance** (deterministic weighted round-robin) with a minimum exploratory flux per tube. `flows(name)` shows the live conductances. Verified behaviors:
+- **Converges + dominates** — a clear winner gets the lion's share (broken-vs-good → good ~100%).
+- **Instant failover** — a working provider that starts failing is dropped within ~1 call; traffic shifts to the alternative.
+- **Genuine re-balance** — because conductance tracks recent quality (not cumulative volume), a FASTER recovered provider OVERTAKES a slower incumbent — the exact thing winner-take-all could not do.
+- **Fairness** — two equally-good providers share traffic (no list-order lock-in).
+- **Does NOT route around the law** — a fence/policy denial propagates; it is never masked as a transient outage.
+- **Composes with the living mesh** — a PURE slow provider gets memoized (becomes fast), so speed-routing matters exactly where latency is real: impure I/O.
+
+**Honest scope (the gate insisted, twice):** it is **exploit-leaning** (concentrates on the best tube + a small constant exploratory flux); the dynamics are governed by **hand-tuned constants** (EWMA α, explore floor); "shortest path wins" resolves only for latency gaps the clock can measure. The first cut (winner-take-all + rare re-probe) was proven to NOT re-balance and to lock in by list order — redesigned to EWMA proportional flux, which does. Demo `examples/flow-routing.myx`; 111 tests.
+
+---
+
+## 1. Shipped today (v0.5-core, 2026-06-14)
+- Tree-walking interpreter, **zero dependencies**, CLI + REPL + embed API.
+- Values: number, string, bool (`live`/`dead`), `void`, list, mesh, agent.
+- First-class agents, closures, recursion; `seed`/`=`/`decay`.
+- Control: `when`/`otherwise`, `reinforce` (while), `reinforce N times`, `for each`.
+- **Error handling: `attempt { } rescue err { }` + `fail expr`**.
+- **Value-returning `and`/`or`** — `x or default`.
+- **A real stdlib**: strings (split/join/trim/replace/slice/find/reverse/…),
+  math (pow/log/sin/cos/round/random/PI/E), collections (sort/merge/entries/clamp/…).
+- The Law engine: strength-per-read, `prune()`, `mesh()`, `--trace`.
+- The **capability fence**: `run(src, { natives })` is the only grant surface.
+- **Modules** *(v0.3)*: `weave "strand.myx"` (flat or `as`-namespaced) + `expose name` —
+  private-by-default, run-once-cached, cycle-safe, and **fenced** (file access is granted).
+- **String interpolation** *(v0.3)*: `"strength is {m[key]}"` — nested strings + escaped braces handled.
+- **Multi-line REPL** *(v0.3)*: type an `agent` definition across lines (`..>` continuation).
+- **Variadic + default params** *(v0.3 ✅)*: `agent log(msg, level = "info", ...rest) { }`, arity-checked.
+- **Capability manifests + value budgets** *(v0.5 ✅)*: `needs lookup, notify, spend(max 5, total 15)`.
+  Undeclared capabilities are refused *even if the host granted them*; `max` caps a single call,
+  `total` caps the cumulative spend across the run — the script is bounded by **its own word**.
+- **Audit ledger** *(v0.5 ✅)*: every privileged call and refusal (name, args, outcome) handed
+  to the host via `onAudit`, even when the run fails.
+- **Stack traces + a recursion guard** *(v0.5 ✅)*: `MyxoError` carries the agent call chain
+  (innermost first, truncated when deep); runaway recursion fails as a clean Myxo error, never a raw crash.
+- **The MCP bridge** *(v0.5 ✅)*: hand `run` an MCP client and **every tool becomes a fenced
+  capability** — one Myxo script drives the whole tool catalog, each call bounded by the manifest
+  and budgets and logged in the ledger. This is the mesh: many languages/services, one law.
+  Transport-agnostic (`client.call` is synchronous; a live async server gets a sync shim).
+  See `examples/nexus-mesh.myx` + `examples/mcp-host.js`.
+- **60 passing tests.**
+
+---
+
+## 2. The full imagined Myxo (leave nothing unimagined)
+*Everything below is design, not yet built. Keywords stay in the Nexus tongue.*
+
+### 2a. Language
+- **Modules — SHIPPED in v0.3 ✅** (`weave`/`expose`, fenced, cached, cycle-safe). The next
+  composability layers ride on it: string interpolation, variadic/default params, a multi-line REPL.
+- **String interpolation — SHIPPED v0.3 ✅** — `"strength of {key} is {m[key]}"` (nested strings + `\{` escapes).
+- **Pattern matching — SHIPPED ✅** — `match SUBJECT { ["move", x, y] { } { "kind": k } { } 0 { } _ { } }`: literals / `_` / name-binds / `[list ...rest]` / `{ "key": pat }` (mesh subset), nested; first arm wins; bindings are linear (a repeated name is rejected) and arm-scoped; no match = no-op. A new `match` keyword, not `when` (`when x { foo { } }` would be ambiguous). Gate-hardened; `examples/match.myx`, `test/match.test.js`.
+- **Gradual types — SHIPPED ✅** — optional annotations `seed n: number = 5`, `agent f(x: number = 1, ...rest): list`. Enforced as **runtime contracts** (not static inference) at three boundaries — seed-init, parameter, return — AND on reassignment of a typed binding. **Opt-in via `--strict`** (and `myxo test`); a normal run stays fully dynamic and ignores them. Types: number/string/bool/list/mesh/agent/void/any (`any` opts back out). Honest scope: containers aren't element-typed (`list` = any list), no unions/generics/inference. Grammar note: param defaults now use `=` (`name: Type = default`); `:` introduces a type.
+- **Variadic + default params — SHIPPED v0.3 ✅** — `agent log(msg, level = "info", ...rest) { }`, arity-checked.
+- **Pipelines — SHIPPED ✅** — `text | lower | words | sort` reads top-to-bottom; `x | f` is `f(x)`, `x | f(a)` is `f(x, a)` (piped value = first arg). Lowest precedence, left-assoc; a `Pipe` node, fully fenced/memoized like any call.
+- **Destructuring — SHIPPED ✅** — `seed [head, ...tail] = xs`, `seed { a, b } = m` (mesh shorthand) / `seed { "k": v } = m`. Reuses the pattern engine; a non-match errors (no half-binding), bindings are linear.
+
+### 2b. The self-optimizing mesh (Myxo's signature, unique to it)
+The law is currently a *metaphor with a +1-per-read counter*. Imagine it **load-bearing**:
+- **Pathway strength is introspectable in-language** (`strength(name)`), not just globals.
+- **Hot agents auto-promote**: a frequently-called agent gets memoized / its closure cached;
+  the runtime literally makes the used paths faster.
+- **Cold code auto-prunes**: pathways below a decay threshold are swept between phases — a
+  program that *sheds the branches it stopped using*. A garbage collector that is the
+  Nexus law, not a bolt-on.
+- **`physarum.myx` becomes the scheduler**: the same Tero flow²/√flow dial that routes the
+  Physarum Mesh routes *which agents run* under load. The language and the architecture
+  become the same law (this is the [[nexus-coherence]] dream made literal).
+
+### 2c. Concurrency, the Nexus way
+- **`dispatch f(x)`** starts an agent running in parallel, returns a handle.
+- **`gather [h1, h2]`** awaits them; results flow back as a list.
+- **`channel`** — a mesh-backed signal agents push/pull on (reinforced channels survive,
+  idle ones decay). Concurrency that obeys the law instead of fighting it.
+- Async natives (the host grants an async capability; Myxo `attempt`s it, `rescue`s timeouts).
+
+### 2d. The capability ecosystem (the killer feature)
+- **Capability manifests — SHIPPED v0.5 ✅**: a script *declares* what it may touch
+  (`needs lookup, notify`); calling anything undeclared is refused **even if the host granted
+  it** — the agent can't exceed its own stated reach.
+- **Value budgets — SHIPPED v0.5 ✅**: `needs spend(max 5, total 15)` — `max` caps a single
+  call, `total` caps the cumulative spend across the run, runtime-enforced and logged. This is
+  the exact shape of the real outward gate ($5/tx, $15/day), now a *language* construct, not
+  bespoke host code. See `examples/outward-gate.myx`.
+- **Audit ledger — SHIPPED v0.5 ✅**: every privileged call and refusal (name, args, outcome)
+  is handed back to the host after the run, even on failure. The who/what/when is in the
+  runtime, not the app. See `examples/host.js`.
+- **Still to wire (the live grants)**: the *shaped* natives themselves — `james.db` read-only
+  lookup, `telegram.send`, the outward gate's one-tap Telegram approval. The fence, the
+  manifest, the budgets, and the ledger are done; what remains is binding them to the real
+  Nexus tools instead of the mock natives in `examples/host.js` / `fenced-agent.js`.
+- **Gated/staged actions** *(design)*: dangerous calls return a *pending* a human approves —
+  the approval round-trip layered on top of the budgets already enforced.
+- This is the thing that makes Myxo *the* language to hand a local model: it physically cannot
+  exceed its grant, and every outward action is logged and capped by construction.
+
+### 2e. Tooling (developer experience)
+- **Multi-line REPL — SHIPPED v0.3 ✅** (block-aware; `..>` continuation). *(Was single-line.)*
+- **`myxo fmt` — SHIPPED ✅** — an AST-based formatter (one true style); refuses invalid code.
+- **`myxo test` — SHIPPED ✅** — `test "name" { expect X is Y / is not / to fail / to fail with "…" }`, written in Myxo; `node myxo.js test <file|dir>` reports ok/FAIL and exits non-zero (incl. "no tests ran"). Myxo tests ITSELF in Myxo (`tests/lang.test.myx`); the runner's own correctness is pinned in `test/myxotest.test.js`. Two-agent gated — the gate killed every false-green (a `report`, a wrong-error `to fail`, an empty/zero-assert test, or an uncalled-function truthy can no longer pass green).
+- **LSP — SHIPPED (v1) ✅** — a stdio JSON-RPC language server (`myxo-lsp.js`, `myxo lsp`): live **diagnostics** (syntax/parse), **hover** (keyword + builtin docs), **completion** (keywords + builtins + top-level file names), and **formatting** (refuses commented files rather than stripping). Honest scope: syntax-only diagnostics (no semantic/type squiggles), top-level-only/scope-unaware completion, no go-to-definition/references/rename yet; pure analysis core unit-tested + a real stdio wire round-trip. Future: semantic diagnostics, go-to-pathway, inline strength heat-map.
+- **Debugger** — step, breakpoints, and a live **mesh-trace** (watch pathways reinforce/decay
+  as you step). No other debugger can show you a program *gardening itself*.
+- **Stack traces — SHIPPED v0.5 ✅** — `MyxoError` carries the agent call chain (innermost first,
+  truncated when deep), plus a recursion-depth guard that turns a runaway into a clean error.
+
+### 2f. Performance & interop
+- **Bytecode VM** — compile the AST to a small instruction set; keep the tree-walker as the
+  reference. Enough for loop-heavy agent scripts (today: pure tree-walk).
+- **Independent runtime path** — keep the Node tree-walker as the reference implementation, then
+  define a portable wire/spec and eventual bytecode/native runtime so Myxo is not permanently tied
+  to Node as its only engine.
+- **MCP bridge — SHIPPED v0.5 ✅** — any MCP tool auto-becomes a fenced Myxo capability
+  (`mcp-bridge.js`). Myxo is now the single fenced surface a whole tool catalog is spoken through:
+  the lookup may be Python, the send JS, the action a shell — the script only knows the verb it
+  was granted. *This is the mesh that connects all languages, by orchestration not translation.*
+- **Polyglot embedding** *(next)* — a tiny wire protocol so Python/Go/Rust *hosts* can run Myxo and
+  grant natives, not just Node. The MCP bridge connects tools; this connects hosts.
+- **Myxo ↔ JSON — SHIPPED v0.5 ✅** (in the bridge): mesh ⇄ object / list ⇄ array, so agent I/O is frictionless.
+
+---
+
+## 3. The honest roadmap
+| Version | Theme | Contents |
+|---|---|---|
+| **v0.2** ✅ | *Robust enough to write real programs* | error handling, value-`or`, full stdlib |
+| **v0.3** ✅ | *Composable* | modules, string interpolation, multi-line REPL, **variadic/default params** |
+| **v0.5** 🟢 | *The fence + the mesh, for real* | **manifests ✅, value budgets ✅, audit ledger ✅, stack traces ✅, MCP bridge ✅, the wire ✅** (`myxo-run` host-allowlist + `myxo-live` sync-over-async worker bridge + `james_nx_run` added to JAMES `mcp-server.js`) — remaining: reload the live MCP server to expose it, then `myxo fmt` |
+| **v1.0** ✅ | *A language you'd ship* | **SHIPPED** — independence · `myxo fmt` · `myxo test` · pattern matching · pipelines · destructuring · gradual types (`--strict`) · spec (`SPEC.md`) · LSP v1 · stable CLI · docs site (`docs/`). **v1.0 COMPLETE — 232 tests + 11 self-host, every plank two-agent-gated.** |
+| **v1.1** ✅ | *The endgame begun — real concurrency* | **SHIPPED** — `dispatch`/`gather`: genuine multi-core parallelism on the `myxo-live` worker+Atomics bones (zero new deps). Isolation-as-safety (a fresh interpreter per task — no shared state to race), by-value data boundary, blocking Atomics barrier, honest timeout backstop. **252 tests + 11 self-host, two-agent-gated (the gate caught a silent-NaN coercion + a crash-path hang; both fixed).** See `CONCURRENCY.md`. |
+| **v1.2** ✅ | *The signature, shipped — the Physarum scheduler* | **SHIPPED** — `schedule(name, workers, items)`: the reinforce/decay law applied to **execution**. A batch is distributed across a learning pool of worker-agents ∝ conductance, run in parallel (on `gather`'s bones), conductance updated from measured speed (fast workers pull more flux; failed ones decay and their items reroute to survivors). The mesh routes work across agents under load — the language *is* the architecture. **268 tests + 11 self-host, two-agent-gated (both gates converged on a small-batch starvation gap — fixed by persisting the pool's credit).** See `CONCURRENCY.md`. |
+| **v1.3** ✅ | *Cooperative concurrency — fibers + channels* | **SHIPPED** — `spawn` fibers + channels (`give … to` / `take … from`), `yield`, `await`, `drain`: the *concurrency* half (interleaving on one thread, communicating hand-to-hand through channels) to complement the parallelism of `gather`/`schedule`. Deterministic scheduler, exactly-once FIFO delivery, deadlock detection, no silent hang. **308 tests + 11 self-host, two-agent-gated TWICE (the re-gate of the fix pass caught a silent dropped-error I'd introduced — fixed).** See `CONCURRENCY.md`. |
+| **v1.4** ✅ | *The fence approval surface — `myxo plan`* | **SHIPPED** — `myxo plan <file>`: a static capability preview (declared `needs` vs referenced capabilities; over-grants; exit 0/1/2 for a gate). Grinding the load-bearing stat for the quest — vet a script's reach before running it. **329 tests + 11 self-host, two-agent-gated + re-gated (gates found FIVE real false-cleans incl. decoy-agent + declaration-order masking — fixed via a scope-aware two-mode analyzer; the irreducible static limit is now honestly DISCLOSED, with the runtime fence as the actual boundary).** Honest: best-effort lint, not a sound gate. |
+| **v1.5** ✅ | *Toward 100% — comment-preserving `myxo fmt`* | **SHIPPED** — the formatter now PRESERVES comments (collected from the real lexer, re-attached by line) instead of dropping/refusing them. Removed the most-cited wart. **334 tests + 11 self-host, two-agent-gated (gates found a CRITICAL: an interpolation-blind scanner FABRICATED comments from string content — fixed at the root by capturing comments in the real tokenizer; plus block-tail/placement fixes via parser end-lines).** Honest: statement-granular (a one-line-block / multiline / inline-agent trailing comment may shift to its own line; never dropped or fabricated). |
+| **v2.0** | *Deepening the signature* | channel `select`/timeouts/closeable channels, suspension across called-agent boundaries, a thread-reuse **worker pool**, multi-tier failover, the self-optimizing mesh (hot-promote/cold-prune at runtime), bytecode VM, portable runtime path |
+| **North star** | *The independent safe action-language of the agent era* | polyglot embedding, the Physarum scheduler, an ecosystem of fenced capability modules |
+
+**Honest caveat (full Max doesn't lie):** "the next go-to for coding" in the *general* sense
+is a decade-and-an-ecosystem and most languages never make it. But "the go-to for *the agent
+action layer*" is a real, winnable, expanding niche — and Myxo already has the two hardest
+pieces (the fence + the law) that no incumbent has. That is the door we walk through.
+
+---
+
+## 4. Where we actually are
+Vision is cheap without a foundation, so none of this is a promise — it shipped. v0.2 made Myxo
+robust (catches its own failures, real stdlib). v0.3 made it composable (modules, interpolation,
+multi-line REPL, variadic/default params). And v0.5 built **the thing that makes Myxo worth
+choosing over Lua, a JS sandbox, or RestrictedPython** for agent scripting:
+
+- a script declares its capabilities (`needs …`) and can't exceed them even if the host is generous;
+- those capabilities carry **value budgets** (`spend(max 5, total 15)`) the runtime enforces —
+  the exact policy the real outward gate runs in JS, now a single line of the script's own contract;
+- every privileged call and refusal lands in an **audit ledger** handed to the host;
+- failures come with a **stack trace** and runaway recursion fails clean;
+- and the **MCP bridge** turns a whole tool catalog into fenced capabilities — one Myxo script
+  drives every tool in the Nexus through one law, whatever language each tool is written in.
+
+**60 tests green.** That's the honest claim made real, and bigger than "a safe sandbox": for
+*the script you hand an autonomous agent*, Myxo is best-in-class, AND it is the **single fenced
+surface the whole tool mesh is spoken through** — safety, budgets, the audit trail, and the
+cross-language bridge are all language features, not things you bolt on. What's left for v0.5 to
+close is wiring a *live* MCP server (the async shim) so a local model's Myxo scripts do gated,
+audited, real work across the Nexus.
+
+*Companions: `README.md` (how to use what's built), `examples/host.js` + `examples/agent.myx`
+(the fence + ledger live), `examples/outward-gate.myx` (the real spend policy as a manifest),
+`examples/mcp-host.js` + `examples/nexus-mesh.myx` (the MCP bridge — many tools, one law).
+Myxo lives at `C:\Users\Milton\myxo\`.*

package/builtins.js

@@ -0,0 +1,361 @@
+'use strict';
+// builtins.js — native functions written in JavaScript and exposed to Myxo.
+// This is the host bridge: registerNative() is how the Nexus later hands real
+// capabilities (db, telegram, wallet) to Myxo scripts. The safe core lives here.
+
+const { VOID, stringify, typeName } = require('./interpreter');
+const { MyxoError } = require('./errors');
+const { performance } = require('perf_hooks');   // monotonic, sub-ms clock for the routing speed signal
+
+function need(args, n, name) {
+  if (args.length < n) throw new MyxoError(`${name} needs ${n} argument(s), got ${args.length}`);
+}
+function num(v, name) {
+  if (typeof v !== 'number') throw new MyxoError(`${name} expected a number, got ${typeName(v)}`);
+  return v;
+}
+
+// ---- automatic flow-routing: the SLIME MOLD. Providers are interchangeable ways to do one job; traffic flows
+// to the working, FASTER path (shorter path -> stronger tube); a failure decays the tube hard and fails over;
+// every tube passively decays each routing decision; faded tubes are periodically re-probed so a recovered one
+// can climb back. Convergence + automatic failover + adaptation, learned from success/failure, no manual policy.
+// PHYSARUM FLUX. Conductance = each tube's RECENT QUALITY (an EWMA of per-call success+speed), NOT cumulative
+// volume — so a slow incumbent serving 95% of traffic can't out-mass a faster challenger, and a recovered/faster
+// tube genuinely RE-BALANCES the route. Traffic is proportional to conductance via deterministic weighted
+// round-robin (credits), with a minimum exploratory flux per tube so alternatives are always sampled (a failed
+// tube triggers a switch; a clearly-better one climbs and takes over). On a call: each tube accrues credit
+// (>= its conductance, floored to the explore share); the top-credit tube is served and pays `total` back; on
+// success its conductance EWMAs toward the call's quality (fast -> high), on failure toward 0 (+ fail over). A
+// fence/policy denial PROPAGATES — the slime mold must not route around the law. Constants are hand-tuned; this
+// is exploit-leaning (it concentrates on the best tube), not a load balancer for equally-good providers.
+const ALPHA = 0.3;       // how fast conductance tracks recent quality
+const EXPLORE = 0.06;    // minimum exploratory flux share per tube
+function routeCall(interp, name, callArgs) {
+  const R = interp.routes.get(name);
+  const n = R.providers.length;
+  const total = R.cond.reduce((a, b) => a + b, 0) || 1;
+  for (let i = 0; i < n; i++) R.credit[i] += Math.max(R.cond[i], EXPLORE * total);  // flux ∝ conductance, with a floor so faded/recovered tubes still get probed
+  const order = R.credit.map((_, i) => i).sort((x, y) => R.credit[y] - R.credit[x]);
+  let lastErr = null;
+  for (const i of order) {
+    R.credit[i] -= total;                            // this tube spent a turn (traffic rotates proportionally)
+    const t0 = performance.now();
+    try {
+      const r = interp.callValue(R.providers[i], callArgs, 0);
+      const quality = 1 + 8 / (performance.now() - t0 + 1);   // recent quality: success + speed (fast ~9, slow ~1)
+      R.cond[i] = Math.max(0.05, (1 - ALPHA) * R.cond[i] + ALPHA * quality);  // EWMA toward recent quality
+      return r;
+    } catch (e) {
+      if (e && e.nxFence) throw e;                   // policy denial: do NOT route around the law
+      R.cond[i] = Math.max(0.05, (1 - ALPHA) * R.cond[i]);    // failure: quality 0 -> conductance falls; fail over
+      lastErr = e;
+    }
+  }
+  throw lastErr || new MyxoError(`route '${name}' has no working provider`);
+}
+
+// ---- THE PHYSARUM SCHEDULER. `route` picks ONE provider per call; `schedule` distributes a whole BATCH of work
+// across a pool of interchangeable worker-agents, runs the chunks on real worker threads IN PARALLEL, measures
+// each worker's throughput, and feeds that back into the SAME conductance law (EWMA of speed) — so over calls the
+// pool LEARNS its own speed profile: fast workers pull more flux, slow/failed ones decay and get routed around.
+// This is the living mesh applied to EXECUTION, not memory: the language becomes the scheduler.
+//
+// distribute(cond, m, credit): assign m work items to len(cond) workers, flux ∝ conductance, via the same
+// credit-based weighted round-robin + explore floor as routeCall. The `credit` array is PERSISTED on the pool
+// and carried across calls (like routeCall's own credit) — so a non-leading worker accrues credit over
+// successive batches and is eventually sampled at a rate ∝ its conductance, and a recovered/faster tube climbs
+// back. Without persistence the floor only guarantees sampling WITHIN one large batch (small batches starve the
+// trailers); persisting it makes the "recovered worker climbs back" promise true in the small-batch regime too.
+function distribute(cond, m, credit) {
+  const n = cond.length;
+  const total = cond.reduce((a, b) => a + b, 0) || 1;
+  if (!credit) credit = cond.map(() => 0);              // a one-off round (failover) gets fresh credit; the main pool passes its own
+  const assign = new Array(m);
+  for (let k = 0; k < m; k++) {
+    for (let i = 0; i < n; i++) credit[i] += Math.max(cond[i], EXPLORE * total);
+    let best = 0;
+    for (let i = 1; i < n; i++) if (credit[i] > credit[best]) best = i;
+    credit[best] -= total;
+    assign[k] = best;
+  }
+  return assign;
+}
+
+function scheduleRun(interp, name, workers, items) {
+  if (typeof name !== 'string') throw new MyxoError('schedule(name, workers, items) needs a name string');
+  if (!Array.isArray(workers) || workers.length === 0) throw new MyxoError('schedule needs a non-empty list of worker agents');
+  if (!workers.every(w => w && w.__agent)) throw new MyxoError('schedule workers must all be agents (each takes a chunk list, returns a results list)');
+  if (!Array.isArray(items)) throw new MyxoError('schedule needs a list of work items');
+
+  let P = interp.pools.get(name);
+  if (P) {
+    if (P.workers.length !== workers.length || P.workers.some((w, i) => w !== workers[i]))
+      throw new MyxoError(`scheduler '${name}' is already defined with different workers`);   // no silent stale pool
+  } else {
+    P = { workers: workers.slice(), cond: workers.map(() => 1), credit: workers.map(() => 0) };
+    interp.pools.set(name, P);
+  }
+
+  const m = items.length;
+  if (m === 0) return [];
+  const { runSettled, assertSerializable } = require('./myxo-concurrent');
+  const { nxToJs, jsToNx } = require('./polyglot');
+  items.forEach((it) => { try { assertSerializable(it, 'a scheduled work item'); } catch (e) { throw new MyxoError(e.message); } });
+
+  const results = new Array(m);
+
+  // Run one parallel round: distribute `idxs` (global item indices) across the workers named by `workerIdxs`,
+  // dispatch each non-empty chunk to its worker thread, update conductance from measured speed, fill `results`.
+  // Returns the workers that FAILED (so the caller can reroute their items — the slime mold's failover).
+  const runRound = (idxs, workerIdxs, credit) => {
+    const assign = distribute(workerIdxs.map(wi => P.cond[wi]), idxs.length, credit);
+    const chunks = workerIdxs.map(() => []);
+    assign.forEach((local, k) => chunks[local].push(idxs[k]));
+
+    const tasks = [], meta = [];
+    chunks.forEach((chunkIdx, local) => {
+      if (chunkIdx.length === 0) return;                       // a worker that drew no flux this round just isn't run
+      const w = P.workers[workerIdxs[local]];
+      tasks.push({ name: w.name, params: w.params, body: w.body, args: [chunkIdx.map(gi => nxToJs(items[gi]))] });
+      meta.push({ wi: workerIdxs[local], chunkIdx });
+    });
+
+    const outcomes = runSettled(tasks);                       // real parallelism; throws only on the wall-clock timeout
+    const failed = [];
+    outcomes.forEach((o, t) => {
+      const { wi, chunkIdx } = meta[t];
+      if (o.ok) {
+        const out = o.value;
+        if (!Array.isArray(out) || out.length !== chunkIdx.length)
+          throw new MyxoError(`scheduler '${name}': worker '${P.workers[wi].name || '?'}' returned ${Array.isArray(out) ? out.length + ' results' : 'a non-list'} for a ${chunkIdx.length}-item chunk — a worker must return one result per item, in order`);
+        chunkIdx.forEach((gi, p) => { results[gi] = jsToNx(out[p]); });
+        const quality = 1 + 8 / ((o.ms || 0) / chunkIdx.length + 1);   // per-item speed -> recent quality (fast ~9, slow ~1)
+        P.cond[wi] = Math.max(0.05, (1 - ALPHA) * P.cond[wi] + ALPHA * quality);   // EWMA toward it: fast workers climb
+      } else {
+        P.cond[wi] = Math.max(0.05, (1 - ALPHA) * P.cond[wi]);   // a failed worker's tube decays toward 0
+        failed.push({ wi, chunkIdx, error: o.error });
+      }
+    });
+    return failed;
+  };
+
+  const allW = P.workers.map((_, i) => i);
+  const failed = runRound(items.map((_, i) => i), allW, P.credit);   // round 1: all workers, with the pool's PERSISTENT credit
+
+  // Failover (one round): reroute the failed workers' items to the survivors. The slime mold routes around damage.
+  if (failed.length) {
+    const dead = new Set(failed.map(f => f.wi));
+    const survivors = allW.filter(i => !dead.has(i));
+    if (survivors.length === 0) throw new MyxoError(`scheduler '${name}': every worker failed (${failed[0].error})`);
+    const reroute = failed.flatMap(f => f.chunkIdx);
+    const stillFailed = runRound(reroute, survivors);
+    if (stillFailed.length) throw new MyxoError(`scheduler '${name}': ${stillFailed[0].error}`);
+  }
+  return results;
+}
+
+// Returns a plain object of name -> native fn. install() wires them in.
+function builtins() {
+  return {
+    // — sizes & types —
+    len: (a) => {
+      const v = a[0];
+      if (typeof v === 'string' || Array.isArray(v)) return v.length;
+      if (v instanceof Map) return v.size;
+      throw new MyxoError(`len expected a string, list, or mesh, got ${typeName(v)}`);
+    },
+    type: (a) => typeName(a[0]),
+
+    // — mesh helpers —
+    keys: (a) => { if (!(a[0] instanceof Map)) throw new MyxoError('keys expected a mesh'); return [...a[0].keys()]; },
+    values: (a) => { if (!(a[0] instanceof Map)) throw new MyxoError('values expected a mesh'); return [...a[0].values()]; },
+    has: (a) => { need(a, 2, 'has'); return a[0] instanceof Map ? a[0].has(String(a[1])) : false; },
+
+    // — lists —
+    range: (a) => {
+      need(a, 1, 'range');
+      const start = a.length > 1 ? num(a[0], 'range') : 0;
+      const end = a.length > 1 ? num(a[1], 'range') : num(a[0], 'range');
+      const out = [];
+      for (let i = start; i < end; i++) out.push(i);
+      return out;
+    },
+    push: (a) => { need(a, 2, 'push'); if (!Array.isArray(a[0])) throw new MyxoError('push expected a list'); a[0].push(a[1]); return a[0]; },
+    pop: (a) => { if (!Array.isArray(a[0])) throw new MyxoError('pop expected a list'); return a[0].length ? a[0].pop() : VOID; },
+
+    // — conversion & strings —
+    str: (a) => stringify(a[0]),
+    num: (a) => {
+      const v = a[0];
+      if (typeof v === 'number') return v;
+      const n = parseFloat(v);
+      if (Number.isNaN(n)) throw new MyxoError(`cannot read '${stringify(v)}' as a number`);
+      return n;
+    },
+    upper: (a) => String(a[0]).toUpperCase(),
+    lower: (a) => String(a[0]).toLowerCase(),
+
+    // — math —
+    abs: (a) => Math.abs(num(a[0], 'abs')),
+    floor: (a) => Math.floor(num(a[0], 'floor')),
+    ceil: (a) => Math.ceil(num(a[0], 'ceil')),
+    sqrt: (a) => Math.sqrt(num(a[0], 'sqrt')),
+    max: (a) => { need(a, 1, 'max'); return Math.max(...a.map(x => num(x, 'max'))); },
+    min: (a) => { need(a, 1, 'min'); return Math.min(...a.map(x => num(x, 'min'))); },
+    pow: (a) => { need(a, 2, 'pow'); return Math.pow(num(a[0], 'pow'), num(a[1], 'pow')); },
+    log: (a) => { need(a, 1, 'log'); const x = num(a[0], 'log'); return a.length > 1 ? Math.log(x) / Math.log(num(a[1], 'log')) : Math.log(x); },
+    sin: (a) => Math.sin(num(a[0], 'sin')),
+    cos: (a) => Math.cos(num(a[0], 'cos')),
+    tan: (a) => Math.tan(num(a[0], 'tan')),
+    round: (a) => { need(a, 1, 'round'); const x = num(a[0], 'round'); const f = Math.pow(10, a.length > 1 ? num(a[1], 'round') : 0); return Math.round(x * f) / f; },
+    random: (a) => {
+      if (a.length === 0) return Math.random();
+      if (a.length === 1) return Math.floor(Math.random() * num(a[0], 'random'));
+      const lo = num(a[0], 'random'), hi = num(a[1], 'random');
+      return lo + Math.random() * (hi - lo);
+    },
+
+    // — strings —
+    split: (a) => { need(a, 2, 'split'); return String(a[0]).split(stringify(a[1])); },
+    join: (a) => { need(a, 2, 'join'); if (!Array.isArray(a[0])) throw new MyxoError('join expected a list'); return a[0].map(x => stringify(x)).join(stringify(a[1])); },
+    trim: (a) => String(a[0]).trim(),
+    replace: (a) => { need(a, 3, 'replace'); return String(a[0]).split(stringify(a[1])).join(stringify(a[2])); },
+    repeat: (a) => { need(a, 2, 'repeat'); return String(a[0]).repeat(Math.max(0, num(a[1], 'repeat'))); },
+    chars: (a) => [...String(a[0])],
+    starts: (a) => { need(a, 2, 'starts'); return String(a[0]).startsWith(stringify(a[1])); },
+    ends: (a) => { need(a, 2, 'ends'); return String(a[0]).endsWith(stringify(a[1])); },
+
+    // — generic sequence ops (string OR list) —
+    slice: (a) => {
+      need(a, 2, 'slice'); const s = a[0];
+      if (typeof s !== 'string' && !Array.isArray(s)) throw new MyxoError(`slice expected a string or list, got ${typeName(s)}`);
+      const end = a.length > 2 ? num(a[2], 'slice') : s.length;
+      return s.slice(num(a[1], 'slice'), end);
+    },
+    find: (a, interp) => {
+      need(a, 2, 'find'); const s = a[0];
+      if (typeof s === 'string') return s.indexOf(stringify(a[1]));
+      if (Array.isArray(s)) { for (let i = 0; i < s.length; i++) if (interp.equals(s[i], a[1])) return i; return -1; }
+      throw new MyxoError(`find expected a string or list, got ${typeName(s)}`);
+    },
+    reverse: (a) => {
+      const s = a[0];
+      if (typeof s === 'string') return [...s].reverse().join('');
+      if (Array.isArray(s)) return s.slice().reverse();
+      throw new MyxoError(`reverse expected a string or list, got ${typeName(s)}`);
+    },
+
+    // — list mutation & mesh ops —
+    shift: (a) => { if (!Array.isArray(a[0])) throw new MyxoError('shift expected a list'); return a[0].length ? a[0].shift() : VOID; },
+    unshift: (a) => { need(a, 2, 'unshift'); if (!Array.isArray(a[0])) throw new MyxoError('unshift expected a list'); a[0].unshift(a[1]); return a[0]; },
+    sort: (a, interp) => {
+      if (!Array.isArray(a[0])) throw new MyxoError('sort expected a list');
+      const xs = a[0].slice();
+      const cmp = a[1];
+      if (cmp && (cmp.__agent || cmp.__native)) xs.sort((p, q) => num(interp.callValue(cmp, [p, q]), 'sort comparator'));
+      else xs.sort((p, q) => (typeof p === 'number' && typeof q === 'number') ? p - q : stringify(p) < stringify(q) ? -1 : stringify(p) > stringify(q) ? 1 : 0);
+      return xs;
+    },
+    entries: (a) => { if (!(a[0] instanceof Map)) throw new MyxoError('entries expected a mesh'); return [...a[0].entries()].map(([k, v]) => [k, v]); },
+    merge: (a) => { need(a, 2, 'merge'); if (!(a[0] instanceof Map) || !(a[1] instanceof Map)) throw new MyxoError('merge expected two meshes'); return new Map([...a[0], ...a[1]]); },
+
+    // — the Law engine: introspect and prune the living mesh —
+    mesh: (_a, interp) => {
+      const m = new Map();
+      for (const row of interp.meshSnapshot()) m.set(row.name, row.strength);
+      return m;
+    },
+    prune: (a, interp) => {
+      const threshold = a.length ? num(a[0], 'prune') : 1;
+      let removed = 0;
+      for (const [name, e] of [...interp.globals.vars]) {
+        if (!e.system && e.strength < threshold) { interp.globals.vars.delete(name); removed++; }
+      }
+      if (removed) interp.epoch++;   // reaping a global pathway IS a global write -> invalidate memo caches (parity with `decay`); else a memoized caller keeps ghost-serving a reaped dependency
+      return removed;
+    },
+    // — the living mesh: introspect heat, and metabolize (decay cold + report promoted) —
+    strength: (a, interp) => {
+      const name = a[0];
+      if (typeof name !== 'string') throw new MyxoError('strength(name) needs a string pathway name');
+      const e = interp.globals.vars.get(name);
+      return e ? e.strength : 0;     // 0 = pathway absent or never read
+    },
+    metabolize: (a, interp) => {
+      const threshold = a.length ? num(a[0], 'metabolize') : 2;
+      const reaped = [];
+      for (const [name, e] of [...interp.globals.vars]) {
+        if (!e.system && e.strength < threshold) { interp.globals.vars.delete(name); reaped.push(name); }  // cold decays
+      }
+      if (reaped.length) interp.epoch++;   // same as prune: a reaped pathway invalidates every memo cache that could depend on it
+      let promoted = 0;
+      for (const rec of interp.memo.values()) if (rec.cache.size > 0) promoted++;   // hot pure agents that promoted
+      const m = new Map();
+      m.set('reaped', reaped);
+      m.set('count', reaped.length);
+      m.set('promoted', promoted);
+      return m;
+    },
+    // — automatic flow-routing (the slime mold): route(name, [providers]) -> a router; flows(name) -> conductivities —
+    route: (a, interp) => {
+      const name = a[0], providers = a[1];
+      if (typeof name !== 'string') throw new MyxoError('route(name, [providers]) needs a name string');
+      if (!Array.isArray(providers) || providers.length === 0) throw new MyxoError('route needs a non-empty list of providers');
+      if (!providers.every(p => p && (p.__agent || p.__native))) throw new MyxoError('route providers must all be agents');
+      const existing = interp.routes.get(name);
+      if (existing) {
+        if (existing.providers.length !== providers.length || existing.providers.some((p, i) => p !== providers[i]))
+          throw new MyxoError(`route '${name}' is already defined with different providers`);   // no silent stale providers
+      } else {
+        interp.routes.set(name, { providers: providers.slice(), cond: providers.map(() => 1), credit: providers.map(() => 0) });
+      }
+      const rname = name;
+      // `impure: true` -> calling a router TAINTS the caller (like random/flows): a router is stateful (conductance
+      // EWMA) and nondeterministic (weighted pick), so a plain agent that only calls it must NEVER be memoized —
+      // otherwise the first answer freezes in the cache and the whole Physarum routing law dies inside a pure caller.
+      return { __native: true, name: 'route:' + name, capability: false, impure: true, fn: (callArgs, ip) => routeCall(ip, rname, callArgs) };
+    },
+    flows: (a, interp) => {
+      const name = a[0];
+      const m = new Map();
+      const R = interp.routes.get(name) || interp.pools.get(name);   // one viewer for both routers and scheduler pools
+      if (!R) return m;
+      const nodes = R.providers || R.workers;
+      nodes.forEach((p, i) => {
+        let key = p.name || ('p' + i);
+        if (m.has(key)) key = key + '#' + i;   // disambiguate duplicate names so none is lost from view
+        m.set(key, Math.round(R.cond[i] * 100) / 100);
+      });
+      return m;
+    },
+    // — the Physarum scheduler: distribute a batch across a learning pool of worker-agents, in parallel —
+    schedule: (a, interp) => scheduleRun(interp, a[0], a[1], a[2]),
+
+    // — cooperative concurrency: channels + the fiber scheduler —
+    channel: (a) => {
+      let cap = Infinity;
+      if (a.length) {
+        cap = num(a[0], 'channel');
+        if (!Number.isInteger(cap) || cap < 1) throw new MyxoError('channel(capacity) needs a positive whole number');
+      }
+      return { __channel: true, buf: [], cap, recvW: [], sendW: [] };
+    },
+    drain: (a, interp) => { interp.pump(); interp.checkAllFibersDone(); return VOID; },   // run ALL fibers to completion
+    await: (a, interp) => {                                       // run the scheduler, then resolve THIS fiber (not the whole pool)
+      const f = a[0];
+      if (!(f && f.__fiber)) throw new MyxoError(`await needs a fiber (from spawn), got ${typeName(f)}`);
+      interp.pump();
+      if (f.error) throw f.error;
+      if (f.done) return f.result;
+      throw new MyxoError('the awaited fiber is deadlocked — blocked with no one to unblock it');   // only blame f, not unrelated parked fibers
+    },
+  };
+}
+
+// Wire every builtin into an interpreter as a system native.
+function install(interp) {
+  const table = builtins();
+  for (const [name, fn] of Object.entries(table)) interp.registerNative(name, fn);
+}
+
+module.exports = { builtins, install };