Explanations

Explanations help you understand why the platform works the way it does. They are background reading, not step-by-step instructions — and they are ordered the way the platform is layered: foundation first, surface last.

The kernel

• What is handl? — the platform's purpose and the publication boundary.
• The arrow calculus kernel — why the six-combinator set is closed.
• The type system — types as values, unification as a three-way judgment, generator-record families, exists, split-tree coverage, effect rows, and what the checker deliberately leaves open.
• Graded algebraic theory — the theoretical frame behind the platform.
• Graded Modal Sanada Arrow Calculus — arrows + grades + Sanada's handlers, the canonical execution calculus.

The engine layer

• Language as data — a Language is a value assembled from YAML fragments; engines dispatch on data.
• Runtime — how a host evaluates programs.

The platform

• Platform architecture — the repo layers and how they compose.
• The composable host — why the platform is built around a single plugin model.
• Plugins, rules, and operations — how Plugin, RuleAcceptor, Operation, and Behavior fit together.
• Kits and manifests — how kits curate plugins and defaults.
• Options and configuration — how options are defined, resolved, and used.
• Security and trust — threat model and recommended practices.

Papers and background

The papers live in the product repos' paper/ dirs (PDFs on GitHub):

• Platform overview — the plugin/host model at a glance.
• The kernel paper (PDF) — the closed arrow calculus.
• The platform paper (PDF) — the composable host.
• Arrow support vs arrow-native — how handl compares to Haskell and other arrow-capable languages.
• Cross-repo ADR index — every public decision record, aggregated.

Design notes

Older design notes, merged here from the retired explanations/ directory:

• Library API design principles
• Design principles
• Name explanation
• handl and other polyglot runtimes

When to use another section

• If you are new to the platform, start with Tutorials.
• For practical instructions, see How-to guides.
• For function and API listings, see the Reference.
• For the research stack, see graphopt.