Skip to content

Architecture Overview

Tidemark is a browser-hosted RISC-V Linux userland environment. Its architecture is about making Linux-style guest execution survive inside WebAssembly, browser workers, SharedArrayBuffer-backed memory, and host application policy.

The most important split is semantic ownership versus host orchestration:

  • The kernel owns guest-visible RISC-V, ELF, Linux syscall, process, filesystem, memory, signal, pipe, socket, and thread behavior. Its kernel supervisor also owns Linux-shaped scheduling, blocking, lifecycle, and shared-object control decisions.
  • The runtime is the TypeScript host executor. It owns worker and WebAssembly instantiation, host memory creation and copying, backing-store I/O, stdio, network bridges, host timers, state transport, and diagnostics. It executes supervisor decisions instead of defining their Linux meaning.
  • The SDK owns application-facing ergonomics, command resolution, file helpers, provider policy, and optional network/proxy helpers.

Architecture Map

flowchart TB
  System["System Model<br/>repository roles and dependency direction"]
  Execution["Execution Architecture<br/>workers, kernel exports, status loop"]
  State["State Model<br/>memory, filesystem, fd/OFD, pipes, sockets"]
  Compatibility["Compatibility Model<br/>RISC-V, ELF, Linux, POSIX contracts"]
  Host["Host Integration<br/>browser/Node workers, stdio, network"]
  Boundaries["Layer Boundaries<br/>what belongs in kernel, runtime, and SDK"]
  Tests["Testing Strategy<br/>layer-specific proof and workload gates"]

  System --> Execution
  System --> State
  Execution --> Compatibility
  State --> Compatibility
  Execution --> Host
  State --> Host
  Compatibility --> Boundaries
  Host --> Boundaries
  Boundaries --> Tests

Pages

  • System Model: the repository and layer model that separates guest semantics, browser orchestration, and application policy.
  • Execution Architecture: runtime creation, worker topology, the supervisor ABI, status/event execution, supervisor-selected resume, and fork/vfork/execve host operations.
  • State Model: guest memory, SharedArrayBuffer use, page-cache and filesystem snapshots, fd/OFD state, pipe state, socket state, and kernel-worker RPC.
  • Compatibility Model: how RISC-V, ELF, Linux syscall, and POSIX behavior are treated as compatibility contracts.
  • Host Integration: how browser and Node worker APIs, stdio, filesystem calls, and network bridges connect to the runtime without becoming guest semantics.
  • Layer Boundaries: what belongs in kernel, runtime, SDK, and application/provider code.
  • Testing Strategy: which tests prove each layer and how workload checks relate to lower-level gates.

Why This Is Not A Simple Emulator Package

A small emulator package can often expose one function like run(binary). The current Tidemark implementation has more moving parts because guest programs can interact with filesystem state, process state, pipes, sockets, signals, child processes, dynamic startup files, and host networking.

The kernel supervisor defines guest-visible ordering across:

  • runnable, blocked, and dead thread transitions,
  • futex wakes and timer-backed waits,
  • child publication, wait completion, and vfork parent resume,
  • fd/OFD, pipe, epoll, socket, signal, and filesystem control state.

The runtime has to carry out the resulting host work across:

  • kernel-worker RPCs,
  • supervisor events, operations, completions, and resume records,
  • thread-worker status messages,
  • fd/OFD and pipe snapshots,
  • fork/vfork/exec transitions,
  • filesystem snapshots and page-cache state,
  • stdio and network bridge events.

Those are not UI concerns. They are the browser-side substrate needed to execute supervisor decisions across workers and asynchronous host events.