The Tyu Programming Language

The Browser REPL

Mon, 01 Jan 0001 00:00:00 +0000

Audience: anyone who wants to try Tyu right now. Purpose: use the browser REPL and find each book lab in it. Prerequisites: a browser tab. Nothing else — no toolchain, no account, no network after the page loads.

Open the REPL — or reach it any time from the site header.

# What it is

The REPL is the language running in your tab, shipped with this site and served from /repl/. It is fully static and self-contained: every artifact it loads is same-origin and SHA-256-pinned, and the page refuses to boot a mismatched artifact. No servers, no post-boot network.

Developer Documentation

Thu, 01 Oct 2026 22:30:00 +0000

Last verified against commit 109a89e (2026-06-26).

# 1. Executive Summary

Tyu is a concatenative, stack-based systems language and toolchain for embedded and simulation targets. This repository contains the compiler front end, semantic checker, IR, target-specific code generators, module packer/signing/encryption tools, loader/runtime support, and the tyu project driver that orchestrates build, run, test, and deploy workflows.

It solves a fairly specific problem: building small, verifiable system images from .mod sources, linking them with a target runtime, packaging them into .lmod containers, and then loading or executing them under a trust model that can range from fully trusted firmware to re-derived untrusted modules.

Setup

Thu, 01 Oct 2026 22:30:00 +0000

This file was the old vendor-specific setup note. It is superseded by the repository-root SETUP.md↗ — the tracked, CI-executed setup reference (tiers, prerequisites per tier, the source installer, first build via the smoke fixture). The root file is the canonical setup document; this pointer exists so old links keep working.

Glossary

Mon, 26 Oct 2026 21:09:46 +0000

This glossary defines the terms used by the tracked docs and the compiler/runtime code.

# Word

A Tyu word is a named stack transformer with declared inputs, outputs, and optional contracts. See crates/frontend/src/parse/decl.rs, crates/ir/src/lib.rs, and crates/semantics/src/types.rs for the code representation.

# Module

A .mod file is a compilation unit. A .def file is the interface record used for separate compilation. See crates/frontend/src/parse/mod.rs, crates/langc/src/iface.rs, and sysroot/Core.def.

Chapter 1 — The Rigor Is the Engine

Sun, 18 Oct 2026 21:50:10 +0000

A program is a stack of promises. The only question is who checks them: the author, at 3 a.m. — or the machine, before lunch.

— workshop wall

# 1.1 Two ways to be careful

There are two ways to write careful software.

The first is vigilance. The ritual is familiar. A function gets a precondition that isn’t expressible in the type system, so the author writes it down — in a comment, or a naming convention, or a README that everyone is sure to read. For a while, everyone who calls the function has read the comment. The code works. Then a new engineer joins, or a call site is copied under deadline, or the comment is updated on one side of a refactor and not the other. Nothing rejects the lie. The program ships. The lie ships with it, and the lie becomes a field failure — at a customer site, at 3 a.m., with a debugger that had to be driven in from nine hours away.

Chapter 2 — First Words

Sun, 18 Oct 2026 21:50:10 +0000

Data stack, data stack, does whatever a data stack does. Push a thing, push a thing, then a word consumes the two.

— workshop wall, after a hard day

# 2.1 The Practice

The Practice. Every word declares its effect on the stack, and the checker holds the body to the declaration — one term at a time, left to right, exactly the way the machine runs them.

Chapter 3 — Types: Making Illegal Values Unrepresentable

Sun, 18 Oct 2026 21:50:10 +0000

Every value is a claim about the world. A type is the claim written where the machine can read it.

— workshop wall

# 3.1 The Practice

The Practice. Every value has a type, and the type says which values make sense and which words may touch them. The checker rejects programs that break the promise before they exist — and when a value breaks it at run time anyway, the runtime traps with a name, not a shrug.

Chapter 4 — Contracts: Promises the Machine Reads

Sun, 18 Oct 2026 21:50:10 +0000

A type says what a value is. A contract says what must be true. Only one of them fits in a comment.

— workshop wall

# 4.1 The Practice

The Practice. A contract is a checked program about a claim: the checker verifies the claim’s shape at compile time, the runtime verifies the claim’s truth at the boundary, and both verifications apply to every caller, present and future.

Chapter 5 — Effects and Capabilities: The Two-Sided Law

Sun, 18 Oct 2026 21:50:10 +0000

A signature can say what arrives and what leaves. The interesting question is what happens in between.

— workshop wall

# 5.1 The Practice

The Practice. Declare what a word does; the caller decides. A word’s effects are checked against the context that calls it, and a context’s capabilities belong to the code lexically inside it — so the reviewer reads the label on the tin, and the compiler checks that the contents match.

Chapter 6 — The Stack Has a Shape

Sun, 18 Oct 2026 21:50:10 +0000

Every phrase has a height. Most languages measure it at 3 a.m., in the field, with a broken device. Tyu measures it at compile time, on paper.

— workshop wall

# 6.1 The Practice

The Practice. Every phrase has a shape — what it adds, what it removes, and how high it reaches. The checker computes the reach for every word, composes it through every call, and refuses programs whose reach cannot be bounded.

Chapter 7 — Places, Borrowing, Ownership

Sun, 18 Oct 2026 21:50:10 +0000

Copying is a decision someone made. Ownership is a decision someone has to answer for.

— workshop wall

# 7.1 The Practice

The Practice. A place has one address and a rule: one writer or many readers, never both. A pointer borrows a place and lives exactly as long as its block. Custody moves — it is never cloned. The checker keeps the ledger, and the ledger has no rounding errors.

Chapter 8 — Touching Hardware: MMIO

Sun, 18 Oct 2026 21:50:10 +0000

The datasheet is a specification. Most languages make you retype it as comments. Tyu makes you retype it as a contract.

— workshop wall

# 8.1 The Practice

The Practice. Hardware is described once, in a platform descriptor — devices named, registers placed, access rules stated. The source’s register-map is checked against that description row by row, and every access the source writes is checked against the rules. The datasheet becomes a compiler input.

Chapter 9 — Factoring: Style Becomes Proof

Sun, 18 Oct 2026 21:50:10 +0000

Until you can name it, you cannot check it. Until you can check it, you were only hoping.

— workshop wall

# 9.1 The Practice

The Practice. Factor so each word can be described in one sentence — and so every proof the checker makes attaches to the smallest unit that can carry it. How a program is divided decides where its claims live, and claims that live at interfaces get checked at every call.

Chapter 10 — Decomposition: Information Hiding, Enforced

Sun, 18 Oct 2026 21:50:10 +0000

Hide what might change. Then let the machine check that you hid it.

— workshop wall, after Parnas

# 10.1 The Practice

The Practice. A module is a decision about what might change. Its interface file is the promise the rest of the program is allowed to know, and the checker holds both sides to it: the implementation must match the interface, and callers are checked against the interface — whether or not the implementation exists.

Chapter 11 — Shared State and the Cross-Context Rule: Interrupts

Sun, 18 Oct 2026 21:50:10 +0000

The interrupt arrives in a microsecond. The race it creates ships for a year.

— workshop wall

# 11.1 The Practice

The Practice. Shared hardware is proven, not prayed over: if an interrupt can reach a resource, every access everywhere is inside a lock, the lock lowers to whatever the platform needs, and the handler’s own stack is budgeted at its binding. The race that ships for a year becomes a compile error that ships never.

Chapter 12 — Tasks and Channels: Concurrency the Platform Provides

Sun, 18 Oct 2026 21:50:10 +0000

The scheduler is not in the language. The language is what makes the scheduler safe to use.

— workshop wall

# 12.1 The Practice

The Practice. Concurrency is declared, not assumed: the platform supplies the scheduler, the effects say who may suspend, the annotations say what escapes into it, and every safety property it needs — locks, custody, bounds — is one this book has already paid for.

Chapter 13 — Field Updates on Untrusted Media

Sun, 18 Oct 2026 21:50:10 +0000

Anything that can update itself can be replaced by something else. The question is who gets the last word.

— workshop wall

# 13.1 The Practice

The Practice. A module is safe to load when everything it claims has been checked or authenticated, and the loader refuses everything else — so the daring operation, installing new code on a running device from untrusted media, becomes a checklist the machine executes.

Chapter 14 — Proving the Program: The Developer-Proof Pipeline

Sun, 18 Oct 2026 21:50:10 +0000

The kernel does not know who wrote the proof. That is the whole security model, and the whole economy.

— workshop wall

# 14.1 The Practice

The Practice. A contract you wrote is a claim. A proof makes it a theorem. The kernel — a small, independent checker — is the only judge; the toolchain’s job is to generate the claims, render them faithfully, and never let an unproven claim be mistaken for a proven one.

Chapter 15 — The Machine as Witness: Emulation in Verification

Sun, 18 Oct 2026 21:50:10 +0000

A test that cannot disagree with you is not a witness. The corpus is the cross-examination.

— workshop wall

# 15.1 The Practice

The Practice. Every semantic claim the toolchain makes is replayed by at least two independent machines, and the machines are not allowed to agree by construction: one proves, one executes, and a shared corpus of observations is the only thing either is allowed to say. When they disagree, the corpus wins and the code is wrong — and this has already happened, catching a real bug.

Chapter 14 — Epilogue: Tyu's Effect on Thinking

Sun, 18 Oct 2026 21:50:10 +0000

The Vigilance Trap is closed. Not because everyone stopped being careful — because being careful stopped being the mechanism.

— workshop wall

Chapter 1 opened with two ways to be careful, and promised the second. Look back at what “moving the promise into the program” turned out to mean, claim by claim:

The claim	The check	Where it was earned
“my stack ends where I say”	the stack-effect checker	ch. 2
“my values stay in their ranges”	subtypes, trap 21	ch. 3
“this is true whenever the word runs”	contracts, trap 20	ch. 4
“I only do what I declared”	the effect matrix	ch. 5
“my stack never rises past its shape”	the `(net, high)` monoid	ch. 6
“one writer, or many readers; custody moves”	the borrow ledger	ch. 7
“the hardware is what the descriptor says”	MMIO checking	ch. 8
“this word is one sentence”	factoring, made mechanical	ch. 9
“the interface is the whole truth”	the `.def` mirror	ch. 10
“the handler and mainline cannot race”	the cross-context rule	ch. 11
“the scheduler holds what I handed it”	effects + annotations	ch. 12
“this module may run here”	the loader’s gates	ch. 13
“this contract is a theorem”	the proof pipeline	ch. 14

Twelve claims. None of them is a comment. The daring they licensed — an interrupt sharing a device, signed code arriving from untrusted media — was not made safe by a framework or a review process. It was made safe because each claim got small enough to check, and then the checks got composed.

Search

Mon, 01 Jan 0001 00:00:00 +0000

Type to search the full documentation index. Results are ranked by title and content matches. Without JavaScript, the complete page list is rendered below the search box — use your browser’s find-in-page.

Appendix A — Language Reference

Thu, 01 Oct 2026 22:30:00 +0000

Status: condensed, verified against the compiler at draft time. Where the older tyu-technical-manual.md disagrees with this appendix, this appendix wins — it was checked against the current tree (the manual still shows the retired requires [ … ] predicate syntax, for example).

# A.1 Table A.1 — the built-in words

The compiler ships exactly sixteen words. Everything else in the vocabulary is written in Tyu (see chapter 2.8, and the sysroot sources). net is the change in stack depth; high the peak (chapter 6).

Appendix B — Error and Trap Registry

Mon, 26 Oct 2026 21:09:46 +0000

Every code in this book’s labs, with the fixture that earned it. The checker’s error codes are falsifiable claims: each one exists because a violation exists. Bands: 10xx–70xx compiler front end, 32xx–37xx typecheck, 36xx MMIO, 50xx effects/contexts, 51xx stack bounds, | 52xx loader.

# Compile-time rejections verified in this book

Code	Meaning	Lab
E1018	`main` must return exactly one value (the exit code)	1.4
E2195	legacy `requires [ … ]` predicate — use `needs [ … ]`	(migration note, ch. 4)
E2201	imported interface not found for this platform	12.6
E2203	imported symbol not exported by the interface	10.4
E2218	interface/implementation word signature mismatch	10.3
E2219	interface/implementation word effect mismatch	10.5
E3202	stack underflow	2.5
E3210	word not found	1.6
E3211	signature stack underflow at a call	(trace idiom, ch. 2)
E3212	call-site type mismatch	3.3
E3220	declared stack effect vs computed body	2.6, 6.2, 9.3
E3242	`if` cannot pop a condition	(ch. 2 notes)
E3243	`if` condition is not a bool	2.7 variant
E3246	`if` branch depth mismatch	2.7
E3251	`while` cannot pop its condition	(ch. 2 notes)
E3253	`while` condition is not a quotation	(ch. 2 notes)
E3257	`while` body is not net-zero	6.3
E3304	`bitcast` size mismatch	3.6
E3305	raw pointer cast	3.7
E3310	contract verdict count wrong (one bool on top)	4.4, 4.6
E3311	contract verdict is not a bool	4.5
E3312	contract modified its inputs (identity — a `swap`/slot-replacement now fires, slice P6)	(registry; shape rarely reachable)
E3313	contract predicate is impure (an effect, store, or spawn inside `needs`/`ensures`)	(slice P6 — a predicate is a question)
E3314	contract predicate too large (peak > 64 stack slots)	(slice P6)
E3608	MMIO bitfield is not addressable	8.6
E3611	MMIO register misaligned	8.5
E3640	MMIO without a platform descriptor	8.7
E3644	MMIO board instance not found	8.3
E3647	MMIO register-map rows disagree with the descriptor	8.4
E3760	`call`/`spawn` of an unannotated quotation	12.4
E5001	suspend where forbidden (main, lock, ISR)	5.7, 11.3
E5002	nested lock	11.2
E5004	capability missing (resource access outside its lock)	5.6
E5005	undeclared effect	5.5
E5010	`dup` of an `iso` value	7.4
E5011	implicit `drop` of an `iso` value	7.5
E5012	use after move	7.6
E5020	borrow escaped its block	7.7
E5021	conflicting live borrows of one root	7.8
E5022	`dup` of a live mutable borrow	(ch. 7 prose, verified)
E5030	ISR stack exceeds its budget	11.5
E5031	interrupt-reachable resource accessed unlocked	11.4
E5040	unbounded (self-recursive) handler	6.4

# Runtime trap codes

Hosted exit status equals the trap code.

Appendix C — Toolchain Setup (current procedure)

Sun, 18 Oct 2026 21:50:10 +0000

Temporary by the project’s own roadmap: a script/rustup-style installer will replace this procedure. Until then, this is the setup this book’s labs were verified with.

# Build the toolchain

Prerequisites: Rust (pinned by rust-toolchain.toml), fasm (flat assembler), GNU ld, cc, and — for the QEMU track and the metal interludes — qemu-system-x86_64 plus the cross binutils (gcc-arm-none-eabi, gcc-riscv64-unknown-elf). For chapter 14’s proof pipeline: Lean 4 and lake, matching the port’s pin (verification/ports/lean/lean-toolchain — v4.27.0 at draft time); with elan installed the pin resolves automatically, otherwise a matching system lean works.

Appendix D — Style Summary (one page)

Thu, 01 Oct 2026 22:30:00 +0000

The book in one page. Each rule has a chapter; each rule is checked by something.

# Claims

Every word declares its stack effect — and the declaration is true (ch. 2).
Ranges live in subtypes; choices live in enums; groupings live in structs (ch. 3).
Contracts are arithmetic about the values in view: no tautologies, no effects, no drift (ch. 4). Write them the way the prover will want them.
Declare what a word does (performs) and what it needs granted (requires); the caller decides (ch. 5).
Beyond two or three stack items, name them (=>) (ch. 2, 9).
Recursion is net-zero per level or it is rejected — keep it that way (ch. 6).
One writer or many readers, never both; a borrow’s life is its bracket; custody moves and is never cloned (ch. 7).
Hardware is named, never addressed; the descriptor wins every disagreement (ch. 8).

# Design

Factor until every word passes the one-sentence test; stop before shims (ch. 9).
Factor along the grammar: predicates keep their subject, loop bodies are net-zero, locked sections stay inline (ch. 5, 9).
A module’s .def is its constitution: exports are decisions, the mirror never drifts (ch. 10).
A shared resource is a declared resource, and the lock is bought only where reachability demands it (ch. 11).
A worker’s quotation carries its annotation; a join lives under its discharge (ch. 12).

# Field

If a fact is load-bearing, it is not a comment (ch. 1).
Checked failures are the cheapest failures: trap codes are verdicts, not embarrassments (ch. 1).
A proof states its boundary. Say what is proven, what is not, and which workstream closes it (ch. 6, 11, 13).
The mirror, the wall, and the seal are one mechanism: promises live in interfaces, interfaces are hashed, and hashes are refused on mismatch (ch. 10, 13).

# The two sentences to carry

Everything claimed, the machine checks; claims are cheap, and lies are loud.
Safety is not the brake — it is the engine: the rigor licenses the daring parts.