One Engine, Four Habitats

This part of the book is for the people the whole book exists for: implementers. If you will build Osmol in any language, on any platform, this chapter is the architecture doctrine you agree to. Not because the reference code says so, but because the doctrine is what keeps a one-implementation language from quietly becoming a one-implementation product.

Where truth lives

The most consequential decision for a young language is where its truth lives. Languages rot when their behavior is defined by whichever implementation someone happens to run. So Osmol's truth lives above any implementation, and GOVERNANCE.md fixes the authority order:

  1. The conformance suite (when it exists): programs paired with required outcomes; see Conformance.
  2. The specification (osmol-spec-v0.1), together with the machine-checked theorems that formalize it (osmol_convergence.v and successors).
  3. The reference implementation, "which serves the two above and never overrules them."

Implementations, including the reference one, are servants of those, never masters; see Governance and Licensing for the constitutional wording. When you find the Python interpreter disagreeing with the spec, the interpreter is wrong. This book documents at least one such spot honestly (the tie-break gap).

The doctrine

One engine, four habitats. This is the whole doctrine in one line. A single Rust crate, osmol-core, written with no operating-system assumptions, contains the entire language: lexer → parser → AST → semantic analysis → diagnostics → lowering → equilibrium solver. It compiles three ways:

  • native: the osmol CLI binary;
  • wasm32: the browser playground and Cloudflare Workers;
  • FFI via UniFFI: a linked library for Android and iOS.

No habitat gets its own solver. No habitat gets its own parser. Divergence between habitats is by definition a bug in whichever habitat disagrees with the conformance suite. The moment two habitats can legitimately disagree, there are two languages wearing one name. The doctrine exists to make that outcome unthinkable, not just discouraged.

Two non-negotiables

Whatever you build, in whatever language, two properties of the core are not up for negotiation.

Determinism. Given the same declarations and the same injected human judgments, the solver must produce the identical flow trace on every platform. This requires the tie-breaking rule the dissertation fixes at spec level: among fireable flows of equal pressure, order lexicographically by (sender name, receiver name, fact). Determinism is what makes golden-file testing, membrane audits, and cross-implementation trust possible.

The Theorem 1 runtime assertion. Every solver, in every habitat, asserts at runtime that the flows executed never exceed the initial gapcount. The proof guarantees the assertion cannot trip; still we ship it, because this is how an implementation confesses instantly if it ever betrays the semantics. The Python interpreter carries this assertion today; yours must carry it too.

Four runtime shapes

The runtime is the mesh, and the mesh is four deployment shapes of the same solver (dissertation, Chapter 3):

  • Local (osmol settle): all twins in one process. This is today's Python behavior, preserved forever as the didactic and testing mode. Everything in the tutorial runs here.
  • Duo (osmold): one daemon per twin on one machine or LAN, membranes speaking the wire protocol over localhost. This is the first true mesh, the first time a delta actually crosses between processes, and also the next real rung on the ladder. See The Wire Roadmap.
  • Edge: one Cloudflare Durable Object per twin, running the same WASM build of osmol-core inside the Worker. The DO holds the twin's membrane policy, its outbound-permitted state slice, queued deltas for offline devices, and the append-only audit log. The edge executes the same solver bit-for-bit as the laptop.
  • Device: osmol-core linked into the phone through UniFFI, holding the private model, with signing keys that never leave secure hardware. The phone is the twin's body.

Four shapes, one solver, one trace.

The build order

Chapter 11 of the dissertation sequences the work so that every step is demonstrable and no step waits on a later one. Honestly marked, as of this writing:

  • Step 0, PyPI. Done. pip install osmol is real; the reference interpreter ships.
  • Step 1, the osmol-core front-end (lexer, parser, checker, all O-diagnostics). Done when osmol check matches the Python interpreter's judgments on the conformance corpus. Ahead.
  • Step 2, the Rust solver. Done when differential traces are byte-identical on the corpus. Ahead.
  • Step 3, WASM plus the osmol.dev playground. The dinner mesh settling live in a browser textarea. Ahead.
  • Step 4, duo mode over the wire protocol on localhost. Ahead.
  • Step 5, edge mode. Durable Objects and the .odb deploy path. Ahead.
  • Step 6, device mode. The Android library with hardware-held keys. Ahead.
  • Step 7, LSP and editor polish, riding alongside everything after Step 1. Ahead.

Each step's definition of done is a conformance addition: the suite grows as the ladder climbs, so finishing a step and proving a step are the same act. There are zero users today and no network transport yet. The ladder is how both stop being true, one falsifiable rung at a time.

The toolchain target

The CLI contract implementers aim at is one binary, osmol, in the modern single-tool style of go and deno (dissertation, Chapter 6):

SubcommandContract
checkcompile and diagnose; this is where O-000 lives
fmtcanonical formatting; declaration order is semantically irrelevant, so the formatter sorts speech-acts canonically
settlelocal equilibrium with the trace
tracereplay a recorded settlement
deployemit and push the deployment bundle
keysidentity and signing operations
explainthe philosophy behind each diagnostic; osmol explain O-002 answers with a paragraph, because in this language the error messages are the ethics

The reference interpreter implements only the heart of settle today. We do not hide that as a shortfall. It is the honest floor the rest of this part builds up from.