Architecture

Forma separates language machinery from consumer-defined vocabulary.

source
  → lossless read / parse
  → macro expansion
  → core lowering
  → type inference
  → evaluation or elaboration
  → typed artifact packaging
  → JSON ABI / target backend

Engine

@formalang/ts is the TypeScript/Effect engine. It runs the browser demo, the language server, the workbench, and the default host. It is the only implementation: an OCaml engine with native, JavaScript, and WebAssembly builds was removed (see Retiring the OCaml engine). Conformance fixtures and stored goldens pin its behavior.

The engine does not own consumer concepts such as entities, endpoints, workflows, or UI components. Those arrive as ordinary preludes plus descriptor and meta hook registrations.

Host boundary

@formalang/host presents one asynchronous ABI for parsing, inference, evaluation, sessions, editor analysis, retained values, and host calls. TsLanguageHost adapts the TypeScript engine to that contract.

The host's forma JSON CLI accepts one-shot requests, a newline-delimited JSON daemon, version, and file <op> <entry> for filesystem modules. Long-lived sessions retain loaded sources, generalized definitions, and suspended host calls. Artifact caching remains planned.

version().sourceLoadSemantics reports validate-and-store for the TypeScript host: source loads validate surface grammar, descriptor application structure, module directives, and duplicate global declaration identities. References and expression types are checked during analysis. Prelude loads evaluate and infer types before atomically committing their scope; replacing a prelude rebuilds that scope so removed bindings do not survive. Prelude metachecks validate descriptor clauses, hook references, slot references, artifact validators, summary requirements, and named payload contracts against the complete bootstrapped prelude and evaluated environment. Descriptor typing hooks run during application inference; hosted helpers retain their meta evaluation contract. Kernel definitions continue through HM inference.

The TypeScript host's optional replSubmit operation checks each submission, evaluates it, and commits its value environment, inferred schemes and type registries, and source only on success. Results include a type projection. Ordinary evaluateInSession continues to evaluate snapshots; the workbench rebuilds its REPL context from current declarations so document edits cannot leave stale bindings.

Effect projection

The engine projects operational effects into the declaration and body shapes exercised by conformance/operational-effects. The TypeScript mechanics runtime executes these declarations; the Effect TypeScript generator turns supported body nodes into Effect programs. Generation throws for unsupported nodes instead of producing placeholder code. The generated program is compiled and executed against the shared operational-effects fixture in the TypeScript suite.

Artifacts use the language-ts-artifact/v1 envelope and SHA-256 over canonical payload JSON with sorted object keys. They include module identities, provenance and type summaries. Artifact fixtures check the canonical IR golden and the 58-source, 548-declaration corpus counts; both expectations were captured from the retired OCaml engine, whose MD5 hashes and envelope metadata are not compared.

The TypeScript host exposes emit, emitMany, emitBackends and artifactSummary. Registered validators check canonical domain payloads, descriptor payload contracts and HTTP declarations before packaging immutable validated declarations. artifactSummary returns validation failures or kind counts and manifest metadata. Module entries project authored imports and exports; resolution and typechecking belong to the module stage.

The surface golden check compares normalized parse, expansion, typecheck, evaluation, and IR output with stored goldens and reports differences by JSON path.

Tooling

@formalang/editor provides syntax, structural editing, diagnostics, hover, and React bindings. @formalang/ts/analysis is a workspace of preludes and documents whose language services (diagnostics, hover, completion, definitions, references, rename, document symbols, semantic tokens, and formatting) are memoized queries. Documents are typed in the scope of their preludes. @formalang/language-server projects those queries into standard Language Server Protocol requests. It starts domain-neutral and loads only preludes explicitly supplied by its consumer. Language services are implemented by the TypeScript engine only; see RFC 0004.

Structural editors build on a further set of host services: stable node ids, per-expression observation, a symbol index, id-addressed edit scripts, an outline codec, and slot affordances. Language services records their design.

The website executes the TypeScript compiler in a Web Worker. Every displayed stage is computed from the editable source in the tab; preview-only target artifacts are visibly distinguished from live compiler output.