Appendices 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).

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.

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:

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.