Assembling in Tyu — draft v3 on The Tyu Programming Language

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.