Curriculum

This curriculum walks through hello-chelis in a sequence that builds on prior concepts. Each step assumes you have read (or at least skimmed) the previous one.

Step 0: Mental model

Chelis has two syntax surfaces:

• Surf: the source language you write. Concise, expression-oriented, looks like a typed scripting language.
• Deep: the compiler's internal representation. Explicit, verbose, fully annotated. You can inspect Deep output for any Surf program.

Every Surf program lowers to Deep before compilation. Understanding this split clarifies error messages, optimization behavior, and the octant shell (which operates on Deep directly).

Step 1: The compiler's three execution paths

Before reading any source file, know what the compiler does with it:

Command	What it does
chelis check	Type-check and lint without executing or emitting code
chelis test	Compile and run the test suite in-process
chelis build --target c	Emit a C translation for ahead-of-time compilation

All three paths share the same type checker and Deep lowering. The difference is what happens after lowering.

Step 2: Language fundamentals

Work through the 11 files in src/basics/ in this order:

1. hellotensor : create a named-dimension tensor, print it. The "hello world" of Chelis.
2. pipeandmatch : pipe operator (|>) and exhaustive match over ADTs.
3. modulesandimports : qualified, selective, and glob import forms.
4. dimpoly : dimension-polymorphic functions with bracketed type parameters.
5. precisioncast : explicit precision casts (no implicit promotion).
6. effectsrandom : the Random effect and algebraic handlers via with seed(...).
7. linearity : consume-by-default semantics, copy(x), and &borrow.
8. gradbasic : reverse-mode AD with grad(f, wrt=w).
9. vmap : vectorized map for per-example batching.
10. jitrealize : jit and realize transforms for deferred computation.
11. macrobasic : compile-time macros.

Each file is self-contained: it compiles, runs, and prints output that demonstrates the concept.

Step 3: chelis-std patterns

After the language fundamentals, explore src/std_patterns/. These files show idiomatic usage of the standard library:

• Activations (relu, gelu, swish, softmax)
• Norms (layernorm, batchnorm, rmsnorm)
• Reductions (sum, mean, max, argmax along named dims)
• Losses (cross-entropy, MSE, huber)
• Decimal and DateTime types
• List, Dict, and iterator combinators
• Text file I/O

Step 4: Shell examples

Each shell has its own subdirectory under src/shells/:

• coral : typed dataframes, group-by, joins, rolling windows, reshape, CSV/JSON I/O, AD through frame operations.
• nautilus : special functions, probability distributions, linear algebra, statistics, distance metrics, root-finding, integration, ODE/SDE solvers, interpolation, optimization, hypothesis tests, curve fitting.
• octant : reads .tex inputs, translates them to canonical Deep with provenance metadata, then decompiles back to Surf.
• c-earchin : takes finance-flavored EARS requirements and translates them to Chelis property witnesses with span diagnostics.
• school : ML layer definitions and training loops.

Step 5: Capstones

The capstone projects in src/capstones/ integrate multiple concepts and shells:

1. Black-Scholes Greeks via grad : uses grad to compute option sensitivities.
2. Linear regression with SGD : a minimal training loop using school.
3. Transformer block : attention, layer norm, and feed-forward composed from chelis-std primitives.
4. End-to-end ML pipeline : data loading (coral), preprocessing, model definition (school), training, and evaluation in a single project that imports across shell boundaries.

After completing the capstones, you have touched every major surface of the language and its ecosystem.