The Tyu Programming Language on

Appendix A — Language Reference

Mon, 01 Jan 0001 00:00: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).

Chapter 1 — The Rigor Is the Engine

Mon, 01 Jan 0001 00:00:00 +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 acquires a precondition that isn’t expressible in the type system — the buffer must be at least as long as the count, the handle must not already be locked, the table must still be sorted — so the author writes the rule down in the only places left: a comment above the definition, a naming convention, a README that everyone is sure to read.

Chapter 13 — Field Updates on Untrusted Media

Mon, 01 Jan 0001 00:00:00 +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 3 — Types: Making Illegal Values Unrepresentable

Mon, 01 Jan 0001 00:00:00 +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 9 — Factoring: Style Becomes Proof

Mon, 01 Jan 0001 00:00:00 +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.

Appendix B — Error and Trap Registry

Mon, 01 Jan 0001 00:00:00 +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	(registry; shape rarely reachable)
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.

Chapter 10 — Decomposition: Information Hiding, Enforced

Mon, 01 Jan 0001 00:00:00 +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 14 — Epilogue: Tyu's Effect on Thinking

Mon, 01 Jan 0001 00:00:00 +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

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.

Chapter 2 — First Words

Mon, 01 Jan 0001 00:00:00 +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 4 — Contracts: Promises the Machine Reads

Mon, 01 Jan 0001 00:00:00 +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.

Appendix C — Toolchain Setup (current procedure)

Mon, 01 Jan 0001 00:00:00 +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).

$ cargo build --release -p langc -p tyu -p lmod-pack -p lmod-sign -p lmod-encrypt
$ export PATH="$PWD/target/release:$PATH" # tyu finds langc on PATH
$ langc --help
$ tyu help

# The two tracks

Hosted (most labs): --target=x86_64-unknown-linux-gnu — builds and runs on the computer, no simulator.
QEMU metal (chapters 8 and 6’s interlude): --target=x86_64-unknown-none --platform=x86_64-unknown-none — runs under qemu-system-x86_64.

# The commands used in this book

# build + direct run (hosted)
$ tyu build labs/.../lab.mod --target=x86_64-unknown-linux-gnu \
 --sysroot=sysroot --out-dir=build/<name>
$ ./build/<name>/image.elf

# harness run (checks the S marker, classifies the verdict)
$ tyu run labs/.../lab.mod --target=x86_64-unknown-linux-gnu \
 --sysroot=sysroot --out-dir=build/<name>

# MMIO chapters: name the platform pack, and use static link mode
$ tyu test --manifest=labs/ch08/manifest.toml \
 --target=x86_64-unknown-none --platform=x86_64-unknown-none \
 --mode=static

# inspection (the debugging habit of ch. 2)
$ langc --emit=tc labs/.../lab.mod --sysroot=sysroot # per-term stack trace
$ langc --emit=ir labs/.../lab.mod --sysroot=sysroot # IR dump

# A project manifest (optional)

tyu.toml in a project directory removes the repeated flags:

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

Mon, 01 Jan 0001 00:00:00 +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 5 — Effects and Capabilities: The Two-Sided Law

Mon, 01 Jan 0001 00:00:00 +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.

Appendix D — Style Summary (one page)

Mon, 01 Jan 0001 00:00: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.

Chapter 12 — Tasks and Channels: Concurrency the Platform Provides

Mon, 01 Jan 0001 00:00:00 +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 6 — The Stack Has a Shape

Mon, 01 Jan 0001 00:00:00 +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

Mon, 01 Jan 0001 00:00:00 +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

Mon, 01 Jan 0001 00:00:00 +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.

Search

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

Search all fourteen chapters and four appendices of Assembling in Tyu.

With JavaScript, typing searches the full book index — titles, descriptions, and prose; code blocks are stripped before indexing.
Without JavaScript, the complete page list below the search box is the catalog: use your browser’s find-in-page, or browse the sidebar.