Initial framework: command language, flow layer, host build

A C framework for commanding a Pico WH robot over USB, WiFi or BLE with a
small text DSL. No hardware attached yet, so the whole stack runs on the
host against a simulated HAL and is covered by tests.

Two specifications drive the code:

  docs/grammar.md  the language — one namespace of callables (native,
                   firmware-resident, and defined over the wire), procedures
                   with named arguments and defaults, REPEAT, and the rules
                   that keep it safe on a microcontroller.
  docs/flow.md     transport, bracket-balance framing, the envelope,
                   admission, execution, abort and failsafe.

Three properties the design leans on:

  - Bodies may only reference callables that already exist, so the call
    graph is acyclic by construction, recursion is unrepresentable, and
    interpreter depth is checked at definition time rather than discovered
    at runtime.
  - Nothing blocks. The interpreter is a resumable state machine over an
    explicit frame stack, so ABORT is honoured within one tick even in the
    middle of a long move, and no program can overflow the MCU stack.
  - No queue. One outstanding statement at a time, which keeps abort to a
    single unambiguous victim and avoids inventing an answer to "the
    running program failed, does the queued one still go?".

Named arguments are resolved to the callee's parameter order at definition
time, so they cost nothing at execution.

rubo_core is target-independent. Porting to the Pico means providing a
non-blocking rubo_transport_t and a rubo_hal_t, and nothing else.

Not built yet: the Pico transport and HAL, the camera DAT/DEND bulk path,
and IF/ELIF, which is reserved in the grammar and lands with the sensors.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Hfu1EFVbpee92zvzQunsKb

host/transport_stdio.c

@@ -0,0 +1,61 @@
+/* transport_stdio.c — host transport over stdin/stdout (docs/flow.md §3).
+ *
+ * read() must never block, so stdin is put into non-blocking mode. This is
+ * the whole of what the Pico USB CDC transport will have to provide too.
+ */
+#include "rubo/rubo.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <unistd.h>
+
+static int stdio_open(rubo_transport_t *t)
+{
+    (void)t;
+    int fl = fcntl(STDIN_FILENO, F_GETFL, 0);
+    if (fl < 0) return -1;
+    return fcntl(STDIN_FILENO, F_SETFL, fl | O_NONBLOCK);
+}
+
+static int stdio_read(rubo_transport_t *t, uint8_t *buf, size_t len)
+{
+    (void)t;
+    ssize_t n = read(STDIN_FILENO, buf, len);
+    if (n < 0) {
+        if (errno == EAGAIN || errno == EWOULDBLOCK) return 0;
+        return -1;
+    }
+    if (n == 0) return -1;                 /* EOF */
+    return (int)n;
+}
+
+static int stdio_write(rubo_transport_t *t, const uint8_t *buf, size_t len)
+{
+    (void)t;
+    size_t off = 0;
+    while (off < len) {
+        ssize_t n = write(STDOUT_FILENO, buf + off, len - off);
+        if (n <= 0) return -1;
+        off += (size_t)n;
+    }
+    return (int)len;
+}
+
+static bool stdio_connected(rubo_transport_t *t) { (void)t; return true; }
+
+static void stdio_close(rubo_transport_t *t) { (void)t; }
+
+rubo_transport_t *rubo_transport_stdio(void)
+{
+    static rubo_transport_t t = {
+        .open      = stdio_open,
+        .read      = stdio_read,
+        .write     = stdio_write,
+        .connected = stdio_connected,
+        .close     = stdio_close,
+        .mtu       = 256,
+        .ctx       = NULL,
+    };
+    return &t;
+}