Example Corpus
Use this skill whenever touching examples/ or tests/docs that reference examples.
Policy
examples/is the executable corpus.examples/illustrative/is for syntax/design examples that are not on the executable phase path.- Make this split explicit early in the phase instead of retrofitting it after examples have already been used as proof.
Rules
- If an example is used as phase proof, it belongs in
examples/. - If it intentionally uses unsupported or future-phase constructs, move it to
examples/illustrative/. - Update tests when moving examples so executable-corpus tests do not silently become parse-only.
Verification
For executable examples:
- parse succeeds
chelis fmt --inplacepreserves validitychelis checkreturns score1.0with no errors
For illustrative examples:
- parsing/round-trip expectations may still apply
- docs and tests must not imply they are executable phase proof
Writing Surf
These rules apply to every .ch you write in this repository: examples,
fixtures, and probes alike. The authority is spec/02-surf-syntax.md §0.1
(canonical forms and the bidirectional contract); §P10-P12 define the wider
set of input spellings the parser still accepts but the formatter rewrites.
spec/01-nomenclature.md is the rule spec behind chelis lint, and
crates/chelis-lint/src/rules/ is its executable enforcement; the canonical
formatter is chelis_surf::format for .ch and chelis_deep::printer for .dp.
Run chelis fmt --inplace <file> and chelis lint --check before pushing.
Spellings that are hard errors, not style:
- A nullary definition needs
():def name() -> T, notdef name -> T. This is the highest-frequency breakage; expect it on any branch predating chelis#1031 (expected function parameter list(), found Arrow). - Applying a returned value needs explicit grouping:
(f(x))(y). Ungroupedf(x)(y)is rejected; Chelis has flat multi-argument application and no implicit currying, and juxtaposition stays rejected. - The unit value is
(), the unit type isunit, and a singleton tuple is(x,); that comma is semantic. - Effects carry exact casing:
Diff,Accum,IO,Test,Resource(...). - Randomness has no effect and no handler: a draw takes an explicit key,
dropout(key_from_seed(42i64), x, 0.5f32).with seed(...)and! { Random }are the typedRetiredRandomnessparse error. - Non-primary transform arguments are named:
grad(f, wrt=x),vmap(f, axis=n); axis zero is barevmap(f). sum,cumsum,trace, andeinsumoveri8ori16returni32(spec/04§5.7.1); declare the result asi32, passaccumulator=i64tosumoreinsum, or narrow it with an explicitcast.- Pipe stages use first-argument insertion:
x |> f(y)meansf(x, y). Usex |> (fn (v) -> f(y, v))when the piped value belongs in a later position.
Style the lint rules enforce:
- prefer
def ... -> T = ...overdef ... : T = ...(surf-def-arrow-form, §3.5) - type identifiers are PascalCase (
surf-type-pascal-case, §3.1); function/value identifiers are snake_case (surf-value-snake-case, §3.2) - functions carrying the
Testeffect are namedtest_*orexample_*(surf-test-name-prefix, §10.1) - zero-arity decoration is dropped in types and kept in expressions:
Ctor()is a Deepapp, bareCtoris a Deepvar, and a zero-field record keeps{}.! {}is a declared-pure upper bound, distinct from an omitted effect clause. - canonical output omits trailing separators and prints the canonical literal spelling (shortest round-trippable float, no digit separators or redundant zeroes)
Style the formatter does not enforce:
- put types on function parameters, not on load-style top-level bindings
- use symbolic dimensions such as
batchandseqfor runtime-varying axes; keep fixed architecture dimensions concrete - do not annotate intermediate expressions when inference already determines
the type; keep meaningful intermediates like
h1,logits,probs, andloss - combine short tensor operations when the composed expression is clearer than over-decomposed single-op bindings
- treat decompiler-generated verbose load chains and checker-inserted ascriptions as debug output, not example style
- user code typically writes neither explicit
&nor explicitcopy()for fan-out into read-only primitives; auto-borrow handles it. Write&xwhen an exported API or dense signature benefits from clarity, andcopy(x)only when forking ownership for downstream consumption. Existing fixtures and migration baselines may keep explicitcopy()ordrop()calls when they prove compatibility or preserve baseline evidence. - lowered IR carries compiler-inserted
CopyandDropnodes for implicit linearity. If auto-copy/auto-drop produces unexpected IR, treat it as a structural blocker and escalate againstspec/design/implicit_linearity.mdrather than papering over it as a routine fixture bug.
Deep AST
- Every Deep node is a 3-tuple:
(tag {} children...), with the metadata map always present at element 1. The vocabulary is a closed set of 62 tags; seespec/03-deep-syntax.md. Function application isapp, names arevar, literals arelit, and RISC primitives are built-in functions, not tags. - Decompilation routes through a typed Deep-to-Surf resugaring boundary
(chelis#1031) with a total disposition for every public Deep tag, printed by
the shared Surf printer. It fails closed on malformed Deep, invalid surface
identifiers, unknown
surf_*metadata, incompatible literal metadata, and non-finite constructed values; a resugaring failure is a real defect, not output to work around. Canonical Deep and canonical Surf are two representations of one public language, bound by the three executable laws inspec/02-surf-syntax.md§0.1 (desugar(resugar(·)), formatter idempotence, and the semantic retraction). If you change either printer or the desugarer, those laws are the oracle.