Principles

These are the standing rules of the system’s design. Every page elsewhere is an application of them; when a proposed change makes the description below longer, the change is probably wrong.

The system, in full

• Programs import modules; modules import other modules.
• Programs and modules use endowments. An endowment is a name the shop may deny.
• An executable is a list of things to run in order to start an actor — endowments and modules and such.
• One mechanism branches module use on the target platform: a package’s own module arms.
• mcode source files are cemented into Mach pools that hold constant shapes, text, bytecode, and numbers as stone.
• Those are objects, just like any other object on an actor’s heap.

That is the whole runtime. Complexity beyond it needs a reason statable in a sentence.

Minimal C; everything that can be pit, is pit

C is the trusted computing base and the audit surface. Pit is safe by construction, because something bad can only happen where something holds a powerful endowment. So the C floor holds mechanics — the interpreter, the pool validator and mapper, the GC, the scheduler, the primitives pit cannot express — and pit holds every policy, every format writer, and every decision.

One writer per format; C reads, pit writes

C never writes what pit can write. C reads only what must be readable before any pit runs: the fixed cart header and the cart’s nota metadata. Every format C reads has exactly one writer, in pit, and the build exercises each C reader against that writer — every profile arm boots a fixture pool pressed by the emitter for that arm.

One lane

There is one execution payload: the Mach pool, mapped and run in place. mcode is the one portable form, and cementing is the one step between them, always for a named profile. A capability that would add a second way to carry or run code instead becomes a different profile handed to the same lane.

The tree carries one way to do each thing

Artifacts the system can regenerate are regenerated, not versioned around: when a format moves, its producers and consumers move together, and the committed artifacts are re-pressed. Every commit holds a source tree and boot artifacts that match, so any commit builds and boots — including cold, from the bootstrap floor.

Actors are the unit of shipping

A build’s capabilities are the actors and packages it carries. Shipping without a compiler means the cart carries no compiler fleet — the capability is absent, not disabled. Unused means absent holds at every scale: an actor that never mentions log has no logging on its heap; a cart that never compiles has no compiler in its store.

Files carry their own names

A module’s name is where it is: <package>/<file>. An endowment’s name is its filename in a package the shop draws endowments from. Listing the directory is reading the list, and the test for any resolution design: look at a file, see what it imports, find that thing immediately.

Erlang, not OTP

The core gives actors, isolation, message passing, and $couple — the lifetime binding where a coupled actor’s death takes you with it. Supervision strategies, restarts, heartbeats, and drain protocols are applications: a user writes an actor that does it. If an actor could be written to provide something, the core does not provide it.

The docs are the source of truth

docs/ — and the website generated from it — describes the target system, in positive voice: what the system does. Design decisions land here first, and code aligns to the page. Work-in-progress state lives in plans/ and is temporary by definition.