IA64 Runtime Server

This directory contains the first server-side runtime boundary for IA64.CC.

The browser can continue to run in full-client mode. Hybrid mode can send a full ia64.codemap to this server, receive the stripped ia64.runtime-codemap, store it by stable hash, create a lightweight execution session, and display a VGA snapshot through JSON or an iframe.

The current Rust runtime is intentionally conservative:

• it validates the authoring CodeMap;
• it strips source and UI metadata into the runtime CodeMap;
• it computes a stable SHA-256 hash over the runtime payload;
• it stores runtime CodeMaps under files/codemaps/;
• it keeps lightweight session metadata in the HTTP store;
• it exposes a Unicorn-backed x86 runtime, plus a mock engine for protocol tests.

Run

From this runtime directory:

make up

Or manually:

docker build -t ia64-runtime-server:latest server
docker compose up
# or, on systems with the classic Compose binary:
docker-compose up

The server listens on http://localhost:8080.

Endpoints

GET /health

Checks that the runtime server is alive.

POST /api/codemaps/compile

Accepts:

{ "codemap": { "format": "ia64.codemap", "version": 1, "...": "..." } }

Returns validation issues, the stripped runtime CodeMap, a stable runtime JSON payload and its SHA-256 hash. It does not persist anything.

POST /api/codemaps

Same input as /compile, but stores the runtime CodeMap under its hash.

POST /api/sessions

Accepts:

{ "hash": "<runtime codemap sha256>" }

Creates a lightweight in-memory session.

GET /api/sessions/{id}/snapshot

Returns the current runtime snapshot, including the per-session CPU register state, flags, segments, the current address, VGA text rows, and small memory windows around the current pointer and VGA text memory.

POST /api/sessions/{id}/step

Advances the selected runtime by one instruction-shaped tick.

POST /api/sessions/{id}/run

Advances the selected runtime by a bounded tick count. With IA64_RUNTIME_ENGINE=unicorn, each session owns an independent Unicorn x86 VM instance. IA64_RUNTIME_ENGINE=mock only advances the current address.

GET /api/sessions/{id}/vga.html?refresh=1000

Returns a VGA text-mode HTML view suitable for an iframe. The refresh parameter is optional and expressed in milliseconds.

GET /api/sessions/{id}/ws

Opens a WebSocket for streaming session control. The server sends a first hello message containing the current snapshot. The client can then send:

{ "command": "snapshot" }
{ "command": "step", "count": 1 }
{ "command": "run", "count": 1000 }
{ "command": "key", "key": "a" }
{ "command": "ping" }

Each command returns a JSON response with type, ok, session_id, hash, snapshot, and, when execution moved the VM, delta. Deltas include changed registers and a VGA screen-changed flag.

Next Runtime Step

The next implementation step is to expose more PC hardware state around the Unicorn runtime while preserving:

• stateless program identity by runtime hash;
• short-lived session state;
• JSON snapshots and deltas;
• iframe-compatible VGA rendering.