hollow-grid-asm

Basalt Relay is a Hollow Grid custody-node world server for x86-64 Linux, written primarily in NASM assembly. A tiny C shim adapts the libwebsockets ABI. Assembly owns game rules, state transitions, protocol framing, and world content.

Public world is offline pending finished-product review (fleet stack parked on biafra). GHCR image: ghcr.io/skyphusion-labs/hollow-grid-asm (push gated by BASALT_AUTODEPLOY / version tag until re-enable).

Contract

The authority is the-hollow-grid/docs/protocol.md. Sibling ports in C, Go, and Python are implementation references, not protocol authorities.

The service provides:

• WebSocket text transport at /ws
• UTF-8 output with CRLF line endings
• @event <name> <json> as machine-readable player state
• GET /health and GET /health/deep
• standalone play when no Grid Hub is configured
• best-effort federation that never blocks local play

Default listen port: 8793.

Runtime boundary

client -> libwebsockets -> tiny C ABI shim -> NASM engine
                                             |
                                             +-> game rules, state transitions,
                                             |   and command dispatch
                                             +-> world content and the moral
                                             |   arc/economy/rescue systems
                                             +-> LocalHub memory; C only does
                                                 RemoteHub HTTP + serialize

NASM owns every rule and every in-process store that can live there: command dispatch, mutations, action menus and valence, dream selection, prune policy, LocalHub federation memory, tide clamp, the moral reckoning vocabulary, the ADMINS keeper gate, and the rest-regen + combat cadence. C is three narrow files: lws_shim.c (libwebsockets ABI, plus the ~50ms beat and a thin lws wake), format.c (serialize @event/prose from values asm chose), and grid_hub.c (RemoteHub libcurl/cJSON plus hub-backed prose wrappers). C never decides a command, moral menu, threshold, keeper, or tick cadence.

Repository guide

• docs/ARCHITECTURE.md: ownership and data flow
• docs/COMMANDS.md: required command surface
• docs/WORLD.md: Basalt Relay identity and Relay Cut
• docs/PLAN.md: phased implementation plan
• .env.example: runtime configuration

Build and run

The runtime target is linux/amd64. On an amd64 Ubuntu 24.04 host:

sudo apt-get install nasm pkg-config libcjson-dev libwebsockets-dev \
  libcurl4-openssl-dev libssl-dev
make check
./build/hollow-grid-asm --addr 127.0.0.1:8793

On another architecture, build the container:

docker build --platform linux/amd64 -t hollow-grid-asm .
docker run --rm -p 8793:8793 hollow-grid-asm

CI (ci.yml) runs make check plus blocking upstream smoke. release.yml builds the image on every push/PR; GHCR push and the fleet roll dispatch fire only on a pushed version tag (v*), never on a merge to main (#22), and only when repo variable BASALT_AUTODEPLOY is true (#20). Basalt Relay stays offline until both a tagged release and Mackaye's code review land. Fleet IaC and roll runbook live in fleet-chezmoi (system/stacks/biafra/basalt-relay/, RUNBOOK-basalt-relay-roll.md).

License

AGPL-3.0-only. See LICENSE and NOTICE.