fix(cluster): honor [cluster] enabled, implement cluster status, explain io_uring (#42 items 5, 6, 7)

[oreofeolurin]

Fixes items 5, 6 and the code half of 7 in #42. Docs are in floruntime/docs#9.

---

Item 5 — Raft bound its port with [cluster] enabled = false

Two faults here, both silent.

[cluster] enabled was parsed and thrown away:

// Note: "enabled" field is deprecated - cluster always runs
// Parse it for backwards compatibility but ignore
_ = table.getBool("enabled");

The operator set it, the parser read it, and nothing used it or said so.

The gate was structurally always-true:

if (self.config.effectiveRaftPort() != self.config.listen_port or ...)

effectiveRaftPort() derives listen_port + 500 when no port is configured, so this compares 9500 against 9000 — true for every single-node server. Raft always bound its port, while the banner printed the unset config value (Raft port: 0) next to a live listener on 9500. The reporter's exact observation.

Now enabled is honored, and the listener starts only when peers are actually possible — enabled = true, seeds, an explicit raft_port, or replication_factor > 1:

  Cluster:
    Node ID:    auto (will generate on start)
    Raft port:  not listening (single-node)
    Mode:       Single-node (no seeds)

$ lsof -nP -iTCP -sTCP:LISTEN | grep 9720
*:9720            # client
127.0.0.1:9721    # metrics
127.0.0.1:9722    # dashboard
                  # 10220 (raft) absent

This path was already supported — every consumer of shard.raft_network null-checks it and the field initialises to null. It was just unreachable.

Item 6 — flo cluster status returned "not implemented"

The opcode, wire format and the entire CLI renderer already existed. Only the server-side handler was missing, so the request fell through the dispatcher to its generic "not implemented" — for a command flo --help advertises in its own examples.

$ flo cluster status

Cluster Status
──────────────
Node ID:    flo-5b938c
Address:    127.0.0.1:9722
Role:       leader
Leader:     flo-5b938c
Term:       1
Members:    1

A single node answers as leader of a one-member cluster — the truthful answer rather than an error, which is what the report asked for. The node's cluster ID is now computed whether or not the Raft listener runs, so it's reportable single-node.

Item 7 (code half) — undiagnosable io_uring failure

A bare error.PermissionDenied that names neither io_uring nor seccomp is close to undebuggable cold. The reactor now explains it and names the fix, separating a blocked seccomp profile from a pre-5.1 kernel:

ERR io_uring is unavailable (PermissionDenied). Flo's event loop requires io_uring on Linux.
  * Under a container runtime's default seccomp profile the io_uring syscalls are blocked.
    Run with `--security-opt seccomp=unconfined`, or use a profile that allows
    io_uring_setup, io_uring_enter and io_uring_register.
  * On kernels older than 5.1, io_uring does not exist and Flo cannot start.

---

Tests

Unit tests pin the gate — including an explicit assertion that the old condition was true for a plain single-node config, so the bug can't come back unnoticed. E2E tests cover cluster status in table and JSON form, asserting on output rather than exit status. Both e2e tests fail against the unfixed code.

The Linux-only reactor branch can't compile on this host (macOS), and the full -Dtarget=x86_64-linux build has two pre-existing failures unrelated to this change. I type-checked it by forcing analysis of Reactor.init under -target x86_64-linux, and verified both error prongs against std's io_uring_setup mapping (EPERM → PermissionDenied, ENOSYS → SystemOutdated).

• test-unit ✅ · test-integration ✅
• test-e2e 575/579 — the 4 failures are the kv/cluster set, confirmed failing identically on a stashed baseline. Worth noting they're unchanged by the Raft gating, which is the result that matters here.

Behaviour change

A single-node server no longer listens on listen_port + 500. Anything that assumed the port was always open (a probe, a firewall rule, a health check) will see it closed — that's the intended fix, but it is a visible change.