12.1. Overview

The Morloc ecosystem has four parts. The compiler turns Morloc source into a build directory. The runtime library is linked into every pool and implements the shared formats. The nexus runs a compiled program, from the command line or as a server. The environment manager, mim, creates isolated installations of the other three, solves the foreign packages that programs need, and serves and freezes the result. This section says what each part owns, when each runs, where an installation keeps its files, and how the parts agree on versions.

Who invokes whom.

Stage What runs What it produces

Provision

mim downloads a compiler release and builds an environment; inside it, morloc init builds the runtime (Runtime bootstrap)

An installation

Install

morloc install fetches modules (Module resolution)

Module source in the installation

Build

morloc make, which calls back into mim to solve packages (Environment solving)

A build directory and launchers (Compilation artifacts)

Run

A launcher runs the nexus, which starts the pools (Runtime overview)

A result

Serve

The nexus as a server, started by mim (Serving)

MCP tools and HTTP endpoints

Freeze

mim builds an image of the environment (Freezing)

A container image

The compiler and mim are coupled only across process boundaries: files the compiler writes, commands it runs, and environment variables. In every such contract the compiler (or its release) writes and mim reads, so the burden of compatibility falls on mim.

An installation is two directory trees. The home holds what morloc init builds and is the same for every program; the state holds what accumulates as modules and programs are installed. They are the same directory unless the state is given its own location.

<home>/
|-- bin/           morloc-nexus, and the launcher of each installed program
|-- lib/           the runtime library and per-language libraries
|-- include/       the runtime's C header and per-language headers
|-- opt/           per-language setup state
`-- rust/          the runtime's source, kept for building Rust pools

<state>/
|-- src/morloc/plane/<plane>/<module>/   installed module source
|-- fdb/           one record per installed module, and install locks
|-- modules/       files that modules expose to foreign code
|-- exe/<program>/ installed programs: source copy and build directory
`-- snapshots/     module version pins

The home defaults to ~/.local/share/morloc. Inside an environment, mim gives each environment its own home and state, so nothing is shared between environments except downloads (Environments).

Version agreement. Three rules keep the parts consistent:

  • Compiler and nexus. A build’s manifest records the compiler’s version. The nexus runs a manifest only if it was written by the same Morloc version (Compilation artifacts).

  • Compiler and runtime. The runtime is built from the source shipped with the compiler’s own release, by that compiler, so they agree by construction. The runtime library also declares a numeric ABI version, which the nexus reports.

  • Compiler and mim. Each document the compiler hands to mim carries its own version: the dependency specification an integer, the language-support table a MAJOR.MINOR schema. A release lists these versions in its manifest so that mim can refuse, before installing anything, a release it cannot read (Runtime bootstrap).