Language SDK

Syntax, descriptors, typechecking, diagnostics, editor metadata, and elaboration.

The Language SDK is the compiler-facing part of Forma Toolchain. It is the reusable substrate for defining a DSL surface, checking source, producing diagnostics, projecting editor metadata, and elaborating authored forms into Canonical IR.

It is built around a small Lisp-shaped source language, but the goal is not to make every team write the same language. The goal is to make DSLs cheap to define and safe to run.

text

source  -> reader and parser  -> descriptors  -> binding and typechecking  -> diagnostics and editor metadata  -> elaboration  -> Canonical IR

What It Owns#

The Language SDK owns the authoring and compiler substrate:

syntax and source spans
form descriptors
typechecking and validation
diagnostics
editor metadata
source-to-IR provenance
elaboration hooks
target emitter inputs

Descriptors define the shape of a language form: its head, identifiers, slots, children, bindings, validation, and construction behavior. Elaboration turns those checked forms into stable IR that runtimes and tools can consume.

OCaml Core#

The language implementation is built in OCaml because the compiler needs a compact, typed, high-integrity core for parsing, expansion, lowering, typechecking, sessions, diagnostics, and editor projections.

OCaml is the implementation substrate. Forma is the product surface. Language authors should experience a toolchain for defining DSLs, not an obligation to work directly in the compiler implementation language.

Elaboration Targets#

Forma should make it practical to elaborate one DSL into multiple host ecosystems.

The current direction is to build elaboration tooling for:

JavaScript and TypeScript targets for web, Node, SDKs, schemas, APIs, and agent tools.
Python targets for data, scripting, workflow integration, and service environments.
Rust targets for high-integrity runtimes, embedded tools, CLIs, and systems integrations.

The source language should not lower directly into one host. It should lower into Canonical IR first, then let target emitters consume that contract.

Relationship To Runtime#

The Language SDK does not decide where a system runs. It produces the checked contract. The Runtime SDK defines how that contract is installed, compared, permissioned, executed, projected, and connected to effects.

That separation lets one DSL target multiple deployments while keeping compiler behavior, source provenance, diagnostics, and editor tooling consistent.