English for Unison Language Developers

Unison breaks enough conventional assumptions — no text files, no manual dependency versions, code identified by its hash — that discussions about it often need a sentence of setup before the actual question, just to establish which unfamiliar concept is in play.

Key Vocabulary

Content-addressed code — Unison’s model where each function definition is identified by a hash of its own syntax tree, not by a name in a file, so renaming a function never breaks anything that calls it. “We renamed this function across the whole codebase without touching a single caller — nothing actually depends on the name, only the hash.”

Codebase manager (UCM) — the tool that replaces both the file system and the build tool for Unison code, storing definitions directly and providing commands to browse, edit, and test them. “There’s no git diff to review here in the usual sense — we walk through the change inside the codebase manager, which shows exactly which hashes changed.”

Ability — Unison’s typed mechanism for describing an effect a function can perform, like network access or exceptions, similar in spirit to an effect system, checked at compile time. “The compiler rejected this function because it performs a network call but wasn’t declared with the Network ability — that’s not boilerplate, it’s a real missing declaration.”

Term / definition — the fundamental unit of Unison code, a single named value or function stored by its hash, the building block everything else — namespaces, dependencies — is composed from. “Instead of thinking in files, think in terms — each function is its own independently stored, independently hashed definition.”

Distributed computation — Unison’s ability to send a serialized function, by its content hash, to run on a remote node without needing that node to already have matching source code deployed. “We didn’t need to deploy new code to the worker nodes at all — we shipped the computation itself, by hash, and the worker fetched and ran it directly.”

Common Phrases

• “Is this actually a rename, or did the definition’s logic change too — since that would give it a different hash?”
• “Are we browsing this change in the codebase manager, or trying to diff it like a normal file?”
• “Does this function need to declare the Network (or IO) ability, or is that a real effect it’s missing?”
• “Is this one term, or are we accidentally describing several definitions bundled together?”
• “Are we shipping code to the worker, or just shipping the computation and letting it fetch by hash?”

Example Sentences

Explaining a refactor’s safety in review: “This is a pure rename in Unison — the hash is identical, so every existing caller is guaranteed to keep working without a redeploy.”

Describing an ability error: “The build failed because this function calls into IO without declaring the ability — that’s the type system catching an undeclared side effect.”

Justifying a distributed design: “We’re not managing deployed versions on each worker — we send the function by hash, and the worker executes whatever it receives.”

Professional Tips

• Explain content-addressed code early when onboarding someone — most confusion about “how do renames not break things” traces back to not knowing hashes, not names, are the real identity.
• Point people to the codebase manager instead of a text editor when they ask “where’s the file” — there usually isn’t one in the traditional sense.
• Treat an ability compile error as a legitimate missing declaration, not a formality — it usually means an undeclared side effect really exists.
• When describing distributed features, be precise about distributed computation by hash versus a conventional deploy — they solve different problems and confusing them undersells the design.

Practice Exercise

1. Explain why renaming a function in Unison never breaks its callers.
2. Describe what an ability is and why a missing one causes a compile error.
3. Write a sentence explaining how Unison ships computation to a remote worker.