Unison Language Documentation

Unison is a statically-typed functional language featuring type inference, an effect system, and advanced tooling. It is built on the principle of content-addressed code, where functions are identified by a hash of their implementation rather than by name, and code is stored as its AST in a database.

Key benefits include:

• No builds: Perfect incremental compilation via a shared compilation cache.
• Non-breaking renaming: Instant renaming of definitions.
• Test caching: Deterministic tests are only rerun if dependencies change.
• Semantically-aware version control: Avoids merge conflicts caused by whitespace, import order, or formatting.

Unison can be used as a general-purpose language or with Unison Cloud for distributed systems.

A Loc {e} (Location) represents a computing context with access to specific resources. The type parameter {e} defines the abilities available at that location.

• A Loc {} supports only pure computations.
• A Loc {Remote, GPU} provides both Remote and GPU abilities.

At runtime, a Location is a composite of cryptographic tokens that authorize the use of specific hosts, ports, and abilities. This allows for secure, distributed execution where the receiving host validates the accompanying tokens before running the computation.

The v2 codebase format is a sqlite3 database that stores Unison objects using a mix of relational tables and binary blobs.

Core Tables

• hash: Stores Unison hashes in base32hex format. It is indexed for efficient case-insensitive prefix lookups.
• text: Stores all strings (definition names, builtin names, user-defined strings) for deduplication. It is indexed for exact match lookups.
• object: Stores objects identified by hash and represented as binary blobs (e.g., patches, namespace slices, terms, and decl components). The type_id field links to the object_type_description table.
• causal & causal_parent: Manage causal relationships. The causal table links a hash to its root namespace slice, while causal_parent tracks the hierarchy.

Unison uses a distributed garbage collection mechanism to manage memory across nodes. It relies on two primary tracking structures:

1. B_map: A weak map used to track local boxes. Entries are automatically removed by the weak map once they are no longer referenced in the local heap or boxes.
2. C_set: A weak set used to track all remote boxes referenced by the local heap or boxes.

To prevent premature garbage collection during value transfers (like continuations or Box.put), nodes use a Keepalive mechanism to propagate references and ensure remote boxes remain alive while being used by a new node.

The Unison codebase uses a specific repository format stored under the .unison/v1/ directory. This format organizes terms, types, paths, and dependency information using content-addressed hashes.

Note: This format is currently in DRAFT and is subject to change until a formal release.

To evaluate a successfully typechecked Unison term (p : AnnotatedTerm v a), the runtime executes the following sequence of phases:

1. let rec minimization: Reduces cycle sizes and eliminates needless cycles to prepare for ability requests.
2. lambda lifting: Eliminates lambdas with free variables by converting them into ordinary function parameters.
3. A-normal form (ANF) conversion: Moves function calls and ability requests into the body of a let or let rec to simplify runtime handling.
4. compilation: Converts ANF code into an Intermediate Representation (IR).
5. evaluation: Interprets the IR to produce a value V.
6. decompilation: Converts the value V back into a term for display in the codebase editor.