Kio documentation

Learn Kio here — tutorials to get started, topic guides for specific tasks, case studies of complete packages, and host guides for embedding Kio in a runtime. For the precise contracts, see specs/.

Tutorials

New to Kio? Start here — these read top to bottom.

• The Kio language — a guided tour: packages, modules, functions, types, tuples and labels, sums and pattern matching, polymorphism, elaborator calls, and structural glue.
• Getting started with the tooling — one full lap of the dev loop on a tiny package: kio init, fmt, check, test, build, and sealing the contract surface with kio sig.
• Filling a shared match! result — start with an explicit target, diagnose disagreeing clauses, and then infer the same common result in either clause order.

For exact command-line behavior, see specs/cli.md.

Guides

Once you know the basics, choose the task below. Ordinary source starts with the language guides; compiler pseudo-modules are a reference for elaborator authors, not the starting point for products and sums.

Writing the language

• Understanding typechecking — where types come from, how calls share information, where bindings stop inference, and when to add annotations.
• Structural products and row types — tuples, labels, row-polymorphic parameters, access, update, and product order.
• Structural sums and pattern matching — |, named label arms, imported widen_sum!, and exhaustive match! clauses.
• Aliases, newtypes, visibility, and purity — transparent aliases, nominal and existential types, explicit recursive-data scopes, scoped exports, and transitive purity.
• Recursion — rec newtype / type groups versus rec(loop), mandatory recursive call markers, and rec(poly) / rec(cont) annotations.
• UFCS calls — .>, .>>, .<, and .<< call splices.
• Operators — fixed op declarations and the slot vocabulary.
• Variadic operators — four fold modes, compound elements, finalizers, and collection literals.
• Error handling — (T | !) sums and explicit failure flow.
• Dependency injection — capabilities as product values, labeled bundles, and row-shaped subsets.
• Higher-kinded types — kinds, type-constructor application, instance newtypes, and imported do! sequencing.

Packages and libraries

• Package files and bridges — host contracts, targets, dependencies, materialization, rehosting, and retyping.
• Using libraries — the local/Git workflow, re-rooted imports, and the reusable repository libraries.
• Dynamic loading — emitting, loading, contract-matching, instantiating, and calling a Kio' package at runtime.

Testing, documentation, and debugging

• Testing with equiv — symbolic partial evaluation, residual normal forms, and kio test.
• Writing Kiodoc — checked Markdown snippets, /// comments, references, and item directives.
• Exploring a package with kio repl — load, query, browse, and navigate modules interactively.
• Debugging with Kio' — inspect the lowered core when surface behavior is surprising.

Compiler-facing material

• Defining elaborators — the checked-term ABI, reflection, captures, diagnostics, and total compile-time recursion.
• Builtin modules — generated exhaustive reference for __intrinsics__ and __comptime__.
• The open-world story — what open-world compilation means for imports, inference, and elaborator design.

Tooling

• Shell completions for kio — generate and install bash, zsh, or fish completion scripts.
• Installing Kio from source — build the CLI and VS Code extension and configure format-on-save.

Case studies

End-to-end read-throughs of the runnable proof-of-concept packages under test-data/poc/. Everything a page shows is real code from the package itself — checked and run on every CI run, never simplified for the page. Read one when you want the whole picture of how a body of Kio fits together, not just the slice a topic guide isolates.

• The optics library — test-data/poc/optics/: lenses, prisms, and isos as function pairs, the spine palette and match! in use, an operator DSL, and every equiv law.
• Higher-kinded types — test-data/poc/hkt/: kinded brands, first-class instance dictionaries, do! pipelines over an abstract type constructor, and a derive! instance pick.
• The elaborator library — test-data/poc/elab/: the source-to-target coercion palettes (algebraic and spine), match!, derive!, and the reflected-type vocabulary, documented per form with their equiv laws.
• Dynamic loading — test-data/poc/dyn_load_prime/: a host loads a pre-compiled package from its emitted Kio' image at runtime, contract-matches it, and calls its exports through a universal existential surface.

Host integrations

How to embed a Kio package in each supported host.

• JavaScript — building with the js backend and calling into the package from JS.
• TypeScript — building with the ts backend (the JS .js plus a generated .d.ts typed skin) and calling into the package from TypeScript.
• Python — building with the python backend and calling into the package from Python.
• Java — building with the java backend and calling into the package from Java.
• Rust — building with the rust backend and calling into the package from Rust.
• Go — building with the go backend and calling into the package from Go.
• Swift — building with the swift backend and calling into the package from Swift.
• Haskell — building with the haskell backend and calling into the package from Haskell.

Snippets

Kio code snippets in these files are written in Kiodoc — GitHub-flavored Markdown plus a small set of fence-attribute directives. kio doc check validates the snippets, kio doc fmt --check gates their canonical formatting in CI, and kio doc build renders this tree, together with each module's /// doc-comments, into a per-module documentation site.