sysl

Verification

2026-08-16T01:26:07.924728867Z

Contracts give sysl require, ensure and invariant, and every one of them is a branch and a trap. This page is the other half: the vocabulary a specification needs that an executable condition does not supply on its own, and the backend that discharges the result.

One clause means one thing. The prover and the running program read the same sentence. There is no proof-only build, no specification subset the compiler declines to execute, and a check the prover proves redundant is still compiled — a program whose emitted code depended on whether a prover was available, and on how long it was given, is one nobody could reason about. The single exception is ghost code, and it is legible in the source rather than in a flag.

`for all` and `for some`

A quantifier over an integer range, universal and existential. It is an ordinary bool, usable wherever one is:

var a = [2, 4, 6]

print(for all i in 0..<3 do a[i] % 2 == 0)
print(for some k in 0..<3 do a[k] > 5)
print(for some k in 0..<3 do a[k] > 9)

true
true
false

all and some stay ordinary identifiers — they are read as keywords only directly after for, and only when a name follows. So a loop over a variable called all is still a loop:

for all in 0..<3 do print(all)

0
1
2

The separator is do, the word every loop header already uses. The predicate extends as far to the right as an expression can, exactly as a closure’s body does, so for all i in r do P(i) && Q(i) quantifies over the conjunction. Written as the second arm of a chain, a quantifier is parenthesized:

var a = [2, 4, 6]

print(a[0] == 2 && (for all i in 0..<3 do a[i] > 0))

true

An empty range takes each quantifier’s identity. A conjunction over nothing is true and a disjunction over nothing is false — these are not conventions, and getting them the other way round breaks every proof that reasons about the first iteration of anything. A range whose bounds are the wrong way round is empty too, which is what for all i in 0..<n - 1 needs when n is zero:

print(for all i in 0..<0 do false)
print(for some i in 0..<0 do true)

var n = 0

print(for all i in 0..<n - 1 do false)

true
false
true

Both forms short-circuit: for all stops at the first counterexample, for some at the first witness. That is observable, because a predicate may trap, so it is specified rather than left to the emitter.

`invariant` and `variant` on a loop

Both are written as the leading statements of a loop’s body, in the position require and ensure take at the top of a function. Written as statements rather than as slots in each loop’s header, one rule serves all five loop forms:

sum_to(n: int) -> int
    var i = 0
    var s = 0

    while i < n
        invariant i >= 0 && i <= n
        variant n - i
        s += i
        i += 1

    s

print(sum_to(5))

invariant is checked on every entry to the body — on arrival at the loop, and again before each subsequent iteration. It is not checked on the way out: that is where the clause is written, and a clause that also ran on exit would be checking something the loop is no longer doing.

variant is a live termination check. The measure is taken at the top of each iteration and compared against the previous one; a run that fails to decrease traps. So a loop that stops making progress stops, rather than running forever:

@test("a loop that stops decreasing stops", should_trap)
spins()
    var i = 0

    while i < 10
        variant 10 - i
        if i == 3 then i -= 1
        else i += 1

    print(i)

The measure is not required to be non-negative. A strictly decreasing integer unbounded below still fails to prove termination, and that failure belongs to the prover — making it a runtime trap would refuse programs that terminate for a reason the clause does not capture.

Both words are contextual, so a value may still be called either:

f() -> int
    var invariant = 7
    var variant = 35

    invariant + variant

print(f())

A clause written after ordinary work is not an invariant, and is refused:

f() -> int
    var i = 0

    while i < 2
        i += 1
        invariant i > 0

    i

an 'invariant' belongs at the head of a loop's body

`variant` on a function

The same word in a function’s contract block declares what decreases at a recursive call:

gcd(a: int, b: int) -> int
    require b >= 0
    variant b
    if b == 0 then a
    else gcd(b, a % b)

print(gcd(48, 18))

A function’s variant may read only its parameters, and that restriction is what makes the check local. At a direct self-call the compiler has both the current parameter values and the arguments about to replace them, so it evaluates the measure twice — once as it stands, once with the arguments in the parameters’ own slots — and traps when the second is not less than the first. No hidden argument travels with the call, and nothing is kept between calls.

Scoping is what enforces the restriction: the clause is analyzed before the body, in a scope holding the parameters alone, so a name from the body is simply undefined there.

The check happens before the call, so unlike an ensure it survives the tail-call transform and a @tailrec function may carry one:

@tailrec
walk(n: int, acc: int) -> int
    variant n
    if n == 0 then acc
    else walk(n - 1, acc + n)

print(walk(4, 0))

The check reaches direct self-calls only. Mutual recursion between two functions with measures is a proof obligation for sysl prove and is not checked at runtime — there is no call site at which both halves of the measure are in hand.

`@pure`

An annotation, checked by the compiler, refused on violation. A caller of a pure function can observe nothing about the call but its result:

@pure
square(x: int) -> int = x * x

@pure
fact(n: int) -> int
    require n >= 0
    if n <= 1 then 1
    else n * fact(n - 1)

print(square(7), fact(5))

49 120

What it may do: read its parameters and any const or val; declare and mutate its own locals; call other pure functions; recurse; use every control-flow form; allocate; and trap.

What it may not do: call a function that is not pure, including any extern; write through a *T, into a &T‘s field, or into any storage it did not create; perform I/O; contain an asm block; call through a closure, or dispatch through a trait object.

A write is examined through its path, not its root — so storage the call made is the call’s, however deep the indexing goes:

@pure
sum(a: [4]int) -> int
    var b = a
    var t = 0

    b[0] = 99

    for i in 0..<4
        t += b[i]

    t

var xs = [1, 2, 3, 4]

print(sum(xs))

A pure function may allocate, which is a deliberate departure from other languages’ purity checks. A caller cannot observe an object that did not exist when the call began, and banning allocation would put every string operation out of reach. The question allocation raises is a real one and sysl answers it elsewhere — no alloc answers it for a whole module, at the point of allocation. Two annotations for two questions:

@pure
shout(s: string) -> string = s + "!"

print(shout("hi"))

hi!

Writing through a reference the function was handed is refused, since that is what a caller sees:

@pure
f(p: *int) -> int
    *p = 5
    1

print(f(null))

a '@pure' function writes through a reference to storage it did not create

So is I/O, which is the same rule reaching a call rather than a store:

@pure
f(x: int) -> int
    print(x)
    x

print(f(1))

which is not marked '@pure'

Purity is not inferred. A function is pure because it says so — inference would let an unrelated edit to a leaf break a caller three levels up with no annotation anywhere naming the promise. Nothing in the standard library is annotated yet, so a pure function today reaches the language and other pure functions the program wrote.

`@reads` and `@writes` — what a call may touch

@pure says a call touches no module storage at all. Most functions worth reasoning about are not that, and the looser form says which storage they touch:

static var count: int = 0
static var limit: int = 100

@reads(limit)
@writes(count)
bump()
    if count < limit then count += 1

bump()
bump()
print(count)

A frame names module storage, so these are static var — the entry file’s spelling for it. A var in a module of its own is the same storage and is named the same way.

A frame is what makes a call something other than an eraser. Given f() with nothing written down, everything a prover knew about module state after the call is true — any variable might have changed. The annotation is the only thing that stops that, which is why it matters more than the convenience of writing it down suggests.

The compiler holds an annotated function to three rules. In the body, a read of a variable needs it in @reads or @writes, and a write needs it in @writes. At a call, the callee’s frame must fit inside the caller’s. And an annotated function may call only annotated or @pure functions — not through a value, not through a trait object, and with no asm block — because each of those is a call site with no declaration to consult.

@writes permits reading. count += 1 is a read and a write of one variable, and a form that common should not have to be declared twice:

static var count: int = 0

@writes(count)
bump()
    count += 1

bump()
bump()
bump()
print(count)

Writing any part of a variable is writing the variable. After buf[i] = b the storage holds something different, which is the only question a prover is asking — so an array reached by index belongs under @writes, not @reads:

static var buf: [4]u8
static var pos: usize = 0

@reads(buf)
@writes(pos)
put(b: u8)
    buf[pos] = b
    pos += 1

put(65)

a function with a frame writes 'buf', which its '@writes' does not name

Writing no frame is not the same as writing an empty one. A function with no annotation has effects nobody has written down and may call and be called by anything, exactly as before frames existed; @reads() @writes() is the positive claim that it touches nothing. That difference is what lets the discipline start at the leaves and climb at whatever pace its author sets, rather than arriving as a flag day. @pure is @reads() @writes() plus the further bans above, so writing a frame beside it is refused as saying one thing twice.

`@ghost` — what costs nothing to say

Everything above executes, and that has a cost in exactly one place: a specification is often more expensive than the code it specifies. invariant is_sorted(a, i) is the right invariant for an insertion sort’s outer loop, it is O(n) where the body is O(n), and checking it every iteration turns an O(n²) sort into O(n³).

@ghost marks a declaration that exists for the specification alone. It is erased before codegen and costs nothing at run time:

@ghost
is_sorted(a: []int, n: int) -> bool = for all i in 0..<n - 1 do a[i] <= a[i + 1]

insertion(a: []int, n: int) -> int
    ensure is_sorted(a, n)
    var i = 1

    while i < n
        invariant is_sorted(a, i)
        variant n - i
        var j = i

        while j > 0 && a[j - 1] > a[j]
            variant j
            var t = a[j - 1]

            a[j - 1] = a[j]
            a[j] = t
            j -= 1

        i += 1

    n

var xs = [5, 2, 9, 1, 7]

print(insertion(xs, 5))
print(xs[0], xs[1], xs[2], xs[3], xs[4])

5
1 2 5 7 9

Two rules make erasing it sound:

Nothing executable may call a ghost function. If it could, erasing the declaration would change what the program computes.
A clause that calls one is a clause that does not run. Given the first it cannot run — the callee is not there — so the only question was whether to allow such a clause at all.

The second is the one exception to “a clause means one thing”, and it is acceptable because it is visible in the source: a reader asking whether a clause executes reads the names in it. What sysl refuses is a switch, where one program has two meanings depending on how it was built.

An ordinary clause beside a ghost one is untouched, and still traps:

@ghost
positive(n: int) -> bool = n > 0

f(n: int) -> int
    require n >= 0
    require positive(n)
    n

print(f(3))

Calling a ghost function from code that runs is refused:

@ghost
positive(n: int) -> bool = n > 0

print(positive(1))

is '@ghost', so it exists for the specification and is not there when the program runs

A ghost function’s own body is ordinary code and may read real state freely — that is the whole point of an is_sorted.

`sysl prove`

sysl prove <file> translates a module to WhyML, the input language of the Why3 platform, and discharges the resulting goals with whichever provers Why3 is configured with.

$ sysl prove gcd.sysl
Goal gcd'vc.
Prover result is: Valid (0.01s, 165 steps).

every goal was discharged

--emit-whyml prints the translation instead of proving it, which is what to reach for when a goal will not go through.

A proof is not a build. Nothing is emitted and nothing about sysl build changes. A module that fails to prove still compiles and still runs, with every check this page describes. What the prover buys is finding out before the program runs rather than at the trap.

Integer overflow is a proof obligation

sysl’s plain integer arithmetic wraps; WhyML’s int is the mathematical integers, which do not. Translating a + b to a + b would prove theorems about a language sysl is not — silently, which is the worst kind of wrong. So in code every arithmetic operation goes through a checked wrapper whose precondition is that the true result is representable:

let add_i32 (a b: int) : int
  requires { -2147483648 <= a + b <= 2147483647 }
  ensures  { result = a + b }
= a + b

A program that stays in range gets the mathematical model, which is exact for it. One that might not gets a failed goal naming the operation — so n * 2 for an n known only to be non-negative does not discharge, and the same function with require n <= 1000 does. --overflow ignore drops the obligations for somebody reasoning about the rest of a function first.

Every integer parameter carries its own range as a precondition, which is not an extra demand on the caller: it is the fact that the argument had the type it was declared with.

Terms and programs

WhyML separates terms, which are mathematics and may appear in a requires, from programs, which have state and may not. @ghost is what decides which world a function lands in — a ghost function becomes a predicate, and every other function becomes a program. So a contract that calls an ordinary function is refused, with the sentence that says to mark it.

That also means a ghost function’s body must be one expression: a specification is mathematics, so it may not declare a variable or run a loop.

What is translated

The scalar fragment: functions whose parameters, locals and result are integers and booleans; arithmetic and comparison; if; while; local variables and assignment; require, ensure, result, old, both quantifiers, loop invariant and variant, function variant, and @ghost declarations.

Anything else is refused by name — “the proof backend does not translate an array or a slice” — so that a gap in the translator reads as a gap in the translator, and not as a program the prover disliked. Arrays are the largest absence.

Installing Why3

Why3 installs through opam and has no Homebrew formula:

$ opam install why3 alt-ergo
$ why3 config detect

A shell that has not run eval $(opam env) will not see one that is installed. Z3 works as the prover too, and Why3 finds it once why3 config detect has run.

Vectors

2026-08-16T01:26:07.924728867Z

<N>T holds N lanes of T — the same values an [N]T holds, in the same order — with one difference: its operators work on every lane at once.

val a: <4>f32 = [1.0, 2.0, 3.0, 4.0]
val b: <4>f32 = [10.0, 20.0, 30.0, 40.0]

val c = a + b

print(c[0], c[3])

11 44

That + is one machine instruction computing four additions. The two type constructors differ by one bracket pair because a vector is an array that computes lane-wise, and the spelling says so: [4]f32 is storage, <4>f32 is a register.

You never have to ask whether a machine can run this. A vector wider than the hardware becomes several registers, and one on a machine with no vector unit at all becomes ordinary scalar operations — so <4>f32 compiles for a Cortex-M0 exactly as it compiles for an Apple M-series, and the only thing that changes is how fast it goes. The question a program asks is how wide to go where it cares about speed, never whether it may write one.

Writing one down

A literal fills the lanes, and it has to fill all of them: the lane count is part of the type, so there is no equivalent of a slice dropping its length.

val v: <4>int = [1, 2, 3, 4]

print(v[0], v[3], v.len)

1 4 4

A scalar broadcasts — the splat, and the commonest thing any vector code does. Write the scalar and it goes into every lane, at a binding, at an operator, at a return, anywhere a vector is wanted:

val zero: <4>f32 = 0.0
val ones: <4>f32 = [1.0; 4]

half(v: <4>f32) -> <4>f32 = v * 0.5

print(zero[0], ones[3], half(ones)[0])

0 1 0.5

A declaration with no initializer starts every lane at the lane type’s zero.

A lane is read by a constant index. This is the one subscript in sysl that is not checked while the program runs, and the reason is that there is nothing to check against: a vector has no address, and an out-of-range lane read has no defined answer at the machine level rather than trapping. So the index has to be a literal or a const, and it is checked where it is written:

val v: <4>f32 = [1.0, 2.0, 3.0, 4.0]

print(v[4])

<4>f32 has lanes 0 to 3, and this is 4

If you need a computed index, you want the values in an array — whose checked subscript already answers.

What the operators do

A vector has exactly the operators its lane has, applied to every lane. Both sides must be the same vector, or one side a scalar that broadcasts:

lanes	operators
an integer	`+` `-` `*` `&` `\|` `^` `<<` `>>`, and unary `-` `~`
a float	`+` `-` `*` `/`, and unary `-`
`bool` (a mask)	`&` `\|` `^`

Integer / and % are refused, and it is worth knowing why rather than reading it as an omission. Scalar integer division traps on a zero divisor and on the one signed overflow; a register traps as a whole or not at all, so a vector would either drop the check or trap for lanes that were perfectly fine. No processor sysl targets has an integer vector divide anyway, so the loop you write instead is what the hardware was going to do:

val a: <4>int = [10, 20, 30, 40]

f() -> unit
    val b = a / a

'/' is not defined on <4>int

There is no promotion, exactly as there is none between scalars. Two different widths, or two different lane types, are two different types:

val a: <4>f32 = [1.0, 2.0, 3.0, 4.0]
val b: <8>f32 = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]

f() -> unit
    val c = a + b

'+' needs matching types, got <4>f32 and <8>f32

Masks, and the lane-wise `if`

A comparison between vectors yields a mask — a <N>bool. It is an ordinary value: bind it, combine it, reduce it.

val a: <4>f32 = [1.0, 5.0, 3.0, 7.0]

val small = a < 4.0

print(small.any(), small.all())

true false

select is how a mask chooses, and it is a method rather than a keyword because it cannot be if. An if branches — it evaluates one side or the other — and a register has no way to take one branch in two lanes and the other in the remaining two. So both sides are computed and the mask picks between the results, lane by lane:

val a: <4>f32 = [1.0, 5.0, 3.0, 7.0]
val b: <4>f32 = [4.0, 2.0, 6.0, 0.0]

val lo = (a < b).select(a, b)
val clamped = (a > 4.0).select(4.0, a)

print(lo[0], lo[1], clamped[1], clamped[3])

1 2 4 4

Either side of a select may be a scalar, which broadcasts — (v > hi).select(hi, v) is what clamping looks like and needs no construction written around the bound.

Two masks combine with the bitwise operators, and not with &&. That is not an oversight: && short-circuits, and there is no such thing as short-circuiting per lane.

val a: <4>int = [1, 2, 3, 4]

val inside = (a > 1) & (a < 4)

print(inside.any(), inside.all())

true false

For the same reason a comparison chain has no lane-wise form. 1 < a < 4 joins its two links with &&, so it is refused rather than quietly turned into an & that would look like the scalar spelling and mean something different:

val a: <4>int = [1, 2, 3, 4]

f() -> unit
    val m = 1 < a < 4

compare two vectors at a time and combine the masks with '&'

Reductions

A reduction collapses a vector to one scalar. sum, min and max are a numeric vector’s; any and all are a mask’s.

dot(a: <4>f32, b: <4>f32) -> f32 = (a * b).sum()

val v: <4>f32 = [3.0, 1.0, 4.0, 1.5]
val w: <4>f32 = [1.0, 2.0, 3.0, 4.0]

print(v.sum(), v.min(), v.max(), dot(v, w))

9.5 1 4 23

A float sum is computed as a tree rather than left to right, which is what makes it worth an instruction instead of a loop — so it may differ in the last bit from adding the lanes yourself in order. An integer sum wraps at the lane width, exactly as scalar integer arithmetic does.

Reaching memory

A vector holds the lanes a kernel computes with; an array or a slice holds the data a program has. Two methods move a run between them, and they belong to the array or the slice rather than to the vector — what the move needs is an address and a length, and a vector has neither.

var xs: [8]f32 = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]
var out: [8]f32

val v: <4>f32 = xs.load(2)

out.store(0, v * 10.0)

print(v[0], v[3], out[0], out[3])

3 6 30 60

xs.load(i) reads the run of lanes starting at element i; out.store(i, v) writes one back. The store needs a slice or an array it may write, so a []const T is refused exactly as xs[i] = v would be.

These are two ordinary words, so a load or store you have declared yourself wins: an impl block for a slice answers before the compiler’s does, and only a receiver with no member of that name reaches these. sysl.sync.Atomic has had a load and a store of its own since long before vectors existed, and they still mean what they meant.

Where the width comes from

A load takes its width from whatever receives the value. A slice has whatever length it has, so it cannot say — and guessing would be the one mistake that silently takes the wrong run. A binding’s annotation says it, and so do a parameter and a declared result:

first(v: <4>f32) -> f32 = v[0]

grab[const W: usize](xs: []const f32) -> <W>f32 = xs.load(0)

var xs: [8]f32 = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]

val annotated: <4>f32 = xs.load(4)
val declared: <2>f32 = grab(xs[..])

print(annotated[0], first(xs.load(1)), declared[1])

5 2 2

An operand of an operator is such a place too, so a load standing beside a vector reads its lane count off it. There are three tiers, which is 01‘s literal rule with one more step: an operand carrying a type of its own is read first, a load is read at what that one said, and a bare literal is read last at whatever the two of them settled.

var xs: [4]f32 = [1.0, 2.0, 3.0, 4.0]
val by: <4>f32 = 10.0
var out: [4]f32

out.store(0, xs.load(0) * by + 1.0)

print(out[0], out[3])

11 41

What is not such a place is one where any width would do. A store takes whatever it is handed, so every width type-checks and there is genuinely nothing to infer:

f(xs: []const f32, out: []f32)
    out.store(0, xs.load(0))

how many lanes it takes is the vector type's to say

Say it on a binding there, which is one line and reads better in a kernel anyway.

What the run promises

It is bounds-checked, and checked as a whole run. xs.load(3) on a five-element array traps even though element 3 exists, because elements 3 through 6 do not. This is the only vector operation with a run-time test: everything else is a register operation that cannot fail, and a vector is not a hole through which a program reaches past the end of an array.

A partial run at the end traps too, and the scalar tail is yours to write. An array whose length is not a multiple of the width ends with fewer elements left than there are lanes; the kernel below is what that looks like.

The alignment claimed is the element’s. A []f32 promises four bytes and says nothing about where a run begins, so a vector’s own alignment would be a claim the type does not support. Every machine sysl targets has an unaligned vector load costing what the aligned one costs on aligned data, so the honest number is also the free one.

volatile elements are refused rather than quietly widened. One access per element is not one access, and a single instruction cannot promise per-lane ordering. volatile <4>u32 is the spelling that means something, and it qualifies the whole register.

f(regs: []volatile u32) -> u32
    val v: <4>u32 = regs.load(0)

    v[0]

the qualifier cannot be kept

A *T is refused for a different reason: it carries no length, so there is nothing to check the run against. Take a slice of the elements first.

One kernel, every width

This is what the feature is for, and it needs nothing of its own: a lane count is a value parameter, so it binds from the argument the way an array’s length does.

scale[const W: usize](v: <W>f32, by: f32) -> <W>f32 = v * by

val four: <4>f32 = [1.0, 2.0, 3.0, 4.0]
val eight: <8>f32 = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]

val a = scale(four, 2.0)
val b = scale(eight, 3.0)

print(a[3], b[7], a.len, b.len)

8 24 4 8

Neither call writes a width. One body is compiled twice, and the two hold different instructions — four lanes wide and eight. The mask inside a generic kernel follows the same width, so a comparison in there is a <W>bool and the select chooses at whatever W turned out to be:

clamp_low[const W: usize](v: <W>f32, lo: f32) -> <W>f32 = (v < lo).select(lo, v)

val four: <4>f32 = [1.0, -2.0, 3.0, -4.0]
val two: <2>f32 = [-1.0, 5.0]

print(clamp_low(four, 0.0)[1], clamp_low(two, 0.0)[0])

0 0

For comparison, the C answer to the same problem is to write the kernel once per instruction set behind #ifdef — Box2D’s contact solver carries four copies of itself, and more than half of that file is those copies.

A kernel over an array

Put the two halves together and the loop a real kernel runs is one body too — the loads, the arithmetic and the store all take their width from W, and the scalar tail picks up whatever the last run could not:

scale[const W: usize](xs: []const f32, out: []f32, by: <W>f32)
    var i: usize = 0

    while i + W <= xs.len
        val v: <W>f32 = xs.load(i)

        out.store(i, v * by)
        i += W

    while i < xs.len
        out[i] = xs[i] * by[0]
        i += 1

val src: [10]f32 = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]

var four: [10]f32
var eight: [10]f32

val by4: <4>f32 = 3.0
val by8: <8>f32 = 3.0

scale(src[..], four[..], by4)
scale(src[..], eight[..], by8)

print(four[0], four[9], eight[0], eight[9])

3 30 3 30

Ten elements is not a multiple of either width, so both instantiations take the tail — and the two answers agree, which is what says one body serves both registers.

by is a vector rather than an f32, and that is where W enters. A written type argument at a call is refused, so a kernel whose every parameter is a slice has no way to be told its width. This is rarely felt, because a SIMD kernel’s constants are broadcast across the lanes anyway — but it is worth knowing before a signature is designed around it.

What a vector does not have yet

Shuffles and swizzles. There is no way to rearrange lanes in one step. A gather is a loop that writes the elements into a scratch array and one load to pick the whole run up — correct everywhere, and still not the single instruction a shuffle would be. This is the reason the section above is a stronger claim about arithmetic than about loading: a gather is what changes between hand-written SIMD variants, and it is the half that does not generalise over a width.

A masked load or store. A run that would reach past the end traps rather than reading the lanes that exist and leaving the rest alone. Write the scalar tail, which is what the kernel above does and what C’s SIMD code does.

A place in a C signature. A vector may not cross to a C function in either direction. Which register it would arrive in differs by target and by which instruction-set extensions the other side was compiled with, and guessing would produce a call that links and corrupts its arguments rather than one that fails to link. Pass the lanes through memory — a *f32 and a count, which is what C’s own SIMD-taking functions take:

extern "process_lanes" process(v: <4>f32) -> unit

how a vector reaches a C function differs by target

Lanes

A lane is a scalar: an integer, a float, bool or char. An aggregate cannot be one — there is no such thing as a vector of structs — and neither can a volatile type, since per-lane access ordering is not something a single load can give. volatile <4>u32 is the spelling that means something, and it qualifies the whole register.

struct Point
    x: int
    y: int

f() -> unit
    var v: <4>Point

a vector's lanes are scalars

A constrained lane is fine, and computes at its base exactly as a scalar of that subtype does:

type Small = int within 0..100

f() -> unit
    val v: <4>Small = [1, 2, 3, 4]
    val w = v + v

    print(w[0], w[3])

f()

2 8

Values and bindings

2026-08-16T01:26:07.924728867Z

Naming a value

Three keywords, differing in what may happen to the thing afterwards:

var count = 3            // storage that may change
val limit: int = 10      // storage that may not
const step: int = 2      // not storage at all — a value known while compiling

count = count + step
print("count:", count, "of", limit)

count: 5 of 10

var and val are the pair most languages have. const is the different one: it is not a variable that happens to be fixed, it is a value the compiler substitutes wherever the name appears, so there is nothing at run time to read. That is why it insists on its type being written and on having a value — a const with either missing is refused rather than inferred, because a name with no storage and no value is nothing at all.

limit writes its type for a reason worth knowing early, because it is the first place the file’s top level behaves differently from the inside of a function. These statements are at module level, and a module-level val is part of the module’s surface — something another file can see — so its type is stated rather than inferred from whatever happens to be on the right today. The same val limit = 10 inside a function infers happily, because a local is nobody else’s business.

A module-level val may hold a value the program had to build — a reference, a slice, a string put together while running. Storage that exists for the whole run is never let go of, so the count it takes is never given back, which is what a static is. What the value is decides only when the storage gets filled: numbers, characters, booleans, string literals and tables of them are complete before the program starts, and anything else is built by a prologue that runs before the first statement.

print takes any number of arguments, renders each one, and puts a space between them. It comes from sysl, the standard module — the one module a file may name without importing it.

The scalar types

Integers are an open family: i8, i16, i32, i64 and the unsigned u8 … u64, with isize and usize for the pointer-width pair. The common ones also have friendly names, and those are what ordinary code uses:

friendly	is
`int`	`i32`
`byte`	`u8`
`short`, `long`	`i16`, `i64`
`uint`, `ushort`, `ulong`	`u32`, `u16`, `u64`
`real`	`f64`

Floats are a closed set — f32 and f64 — because IEEE 754 defines those and not an open family. real is f64, and it is the width arithmetic reaches for unless a program says otherwise.

Then bool, char, and string.

Every width is its own type

This is the part that catches people arriving from C. A width is a type, not a hint, and no value changes width on its own:

var small: byte = 200
var wide: u64 = 18446744073709551615

print("byte:", small + 100, small >> 3)
print("u64 max:", wide)

byte: 44 25
u64 max: 18446744073709551615

small + 100 is byte arithmetic, so it wraps at 256 and gives 44. It does not quietly become an int because the answer would not fit — the type said byte, and byte is what the arithmetic is. An unsuffixed literal like 100 takes the type of what is around it, which is what lets that line be written without a suffix on every number.

The family is open, and that is not a figure of speech

i8 through i64 are the widths with familiar names, not the widths that exist. iN and uN are an open family parameterized by a bit width, so u12, i5 and u256 are types you may write, and each is its own type with its own arithmetic — a u12 wraps at 4096 because that is what twelve bits hold:

struct Pixel
    red:   u5
    green: u6
    blue:  u5
end Pixel

var p = Pixel(31u5, 40u6, 17u5)

var counter: u12 = 4000

print("wraps at 4096:", counter + 100u12)
print("and divides:", counter / 7u12)
print("packed:", int(p.red), int(p.green), int(p.blue))

wraps at 4096: 4
and divides: 571
packed: 31 40 17

That is the reason the rule above is worth stating as “a width is a type” rather than “there are eight integer types”. A 16-bit colour pixel really is a 5-bit field, a 6-bit field and another 5-bit field, and writing it that way gets the wrapping and the range checking for free instead of hand-masking them out of a u16.

Storage rounds up to whole bytes and an alignment the machine has — a u12 occupies two bytes — so a narrow width buys correct arithmetic rather than tight packing. The reference has the ceiling and the two costs at extreme widths.

Ask for a wider type and the compiler will not do it silently:

var small: byte = 200
var wide: int = small
print(wide)

cannot initialize 'wide': declared int but the value is byte

The fix is to say so, and every conversion is written with call syntax:

var small: byte = 200

print("widened:", int(small))
print("truncated:", int(3.9))
print("divided:", f32(7) / f32(2))
print("code point:", u32('A'))

widened: 200
truncated: 3
divided: 3.5
code point: 65

int(3.9) truncates rather than rounds, and f32(7) / f32(2) is float division because both operands are floats — writing 7 / 2 would have been integer division giving 3. Which one you get follows from the types, and the types are written down.

Characters are not small integers

A char is one Unicode scalar value. It compares and prints, and it does not do arithmetic:

var letter = 'é'

print("char:", letter, 'a' <= letter, char(9731))

char: é true ☃

Ordering is defined, so 'a' <= letter answers. Adding 1 to it is not, because “the next scalar value” is rarely what a program that wrote letter + 1 actually meant. When the code point is what you want, u32(letter) says so and char(9731) goes back the other way.

Assignment is an expression

It yields the value assigned, which is what lets a chain work and a condition read normally:

var a = 0
var b = 0

a = b = 7
print("both:", a, b)

both: 7 7

A binding takes a comma list too, so two names can be introduced, or swapped, in one line:

demo()
    val lo, hi = 1, 10
    var x, y = 3, 4

    x, y = y, x
    print("range:", lo, hi, "swapped:", x, y)

demo()

range: 1 10 swapped: 4 3

The right-hand side is evaluated before anything is stored, so x, y = y, x is a swap and needs no temporary.

This one is inside a function rather than at the top level, and it has to be. A binding that names several things has nowhere to write a type, and a module-level binding is required to have one — so the comma form is a local’s convenience, and the compiler says exactly that if you try it at module level.

Next: control flow, where the same “it yields a value” idea turns out to cover if, match and the loops as well.

Types

2026-08-16T01:26:07.924728867Z

sysl’s types fall into four groups: scalars (numbers, bool, char), the built-in string, the aggregates you build (arrays, slices, structs, enums), and the modes that decide where a value lives (T, &T, *T). This page covers the first three. The modes have a page of their own, because they are about storage rather than shape.

There is no implicit conversion anywhere in the language. Every width change, signedness change, and float/integer crossing is written as a cast, and a cast that could lose information is written and seen.

Integers are an open family

iN and uN are not a fixed set of four sizes. They are an open family parameterized by an arbitrary bit width: i5, u3, u12, i128 are all types you may write, and none of them needed the compiler to have heard of them. LLVM supports integers of any width natively, so this is a capability of the target rather than something sysl emulates.

var small: u3 = 5
var odd: i5 = -7
var wide: u12 = 4000

print(small, odd, wide)

5 -7 4000

That openness is the reason the iN spelling exists at all. If the integers were only four sizes, carrying both iN names and C-style names would be two spellings for every type and no benefit. Instead there are two layers, each earning its place: iN/uN is the general mechanism, and a short list of aliases covers the common widths.

alias	is	alias	is
`byte`	`u8`	`short`	`i16`
`ushort`	`u16`	`int`	`i32`
`uint`	`u32`	`long`	`i64`
`ulong`	`u64`	`real`	`f64`

C’s “how wide is long?” problem — the usual reason to distrust names like these — does not apply, because each width is pinned by definition. long is exactly i64, on every target, always.

But that is an anti-ambiguity guarantee, not an ABI promise, and the difference matters at a foreign boundary. On a 64-bit host every alias happens to match its C namesake, which is what makes them safe in extern code there. On a 32-bit target C’s long is 32 bits while sysl’s is still exactly 64 — so precise FFI should use the explicit-width names, which match C’s int32_t and int64_t on every target. Note also that i8 has no alias: there is no settled C-style name for a signed byte worth adopting.

Arithmetic wraps

Integer arithmetic wraps at the declared width, and this is defined behaviour rather than a checked error. i5 wraps mod 2⁵ exactly as i32 wraps mod 2³².

var small: byte = 250

print(small + 10)

Overflow is therefore not a trap source. See errors and traps for what is.

Storage is not `N / 8`

An integer’s alignment rounds up to the smallest width the target names, and its stride rounds up to that alignment. A u12 occupies two bytes aligned to two; a u96 occupies sixteen aligned to sixteen. This is LLVM’s rule, and it matters anywhere a width is stated rather than derived.

Where the width stops

Up to 64 bits everything is a machine instruction. Past that the arithmetic is still native — the back end expands a wide multiply or divide inline, with no runtime routine behind it — and decimal rendering becomes the language’s own job, since C’s printf has no length modifier that wide. So a value past 64 bits renders through a digit loop and is refused a %d.

The ceiling is LLVM’s own 2²³ − 1, and a wider width is a diagnostic naming it. That is a statement about the toolchain, not about the design.

var wide: u256 = 1
var i = 0

while i < 200 do
    wide = wide * 2u256
    i = i + 1

print(wide)

1606938044258990275541962092341162602522202993782792835301376

Two costs are worth knowing before reaching for an extreme width, because neither is guarded against: the digit buffer is stack space proportional to the width, so a width near the ceiling overflows the frame, and sizing it evaluates 2^N at compile time. Nothing reaches either without asking for it by name.

The narrowest widths

N ≥ 1 has no exception at its low end. u1 is a single binary digit. i1 holds {-1, 0} — one bit of two’s complement, where the only bit is the sign bit. It is degenerate but entirely consistent, and nothing special-cases it: abs at i1 answers -1 because -1 is that width’s most negative value, exactly as abs at any width answers its own minimum, and signum never returns +1 because no value of the type is positive. If you want a bit, write u1 or bool.

Floating point is a closed set

fN is not open — only the IEEE widths exist, because there is no meaningful f37. f32 and f64 are the two the back end supports today.

Only the default width gets an alias, and it is deliberately named real rather than float, because float means 32-bit to every C, C++, Rust and Java programmer and real promises nothing it does not keep.

var a: f32 = 1.5
var b: real = 2.25

print(a + 1.0, b / 2.0)

2.5 1.125

A float renders in the shortest form that round-trips, so a value with no fractional part prints without one.

`usize` and `isize`

Pointer-width integers, and they are distinct types from every uN — not aliases for u64. That is required by the target scope: aliasing usize to u64 would be correct only if every target were 64-bit, and a 32-bit embedded target is squarely in scope.

A length, an index, and sizeof are all usize.

var xs = [10, 20, 30]
var n: usize = xs.len

print(n, xs[1])

3 20

`bool`

true and false, and nothing coerces to it. if x = 0 is a type error rather than a subtle bug, because if requires a bool and an assignment yields what was assigned. There is no integer-as-condition rule to memorize.

`char`

One Unicode scalar value — a codepoint up to 0x10FFFF, excluding the surrogate range. It is its own type, aliased to neither u8 nor u32.

Keeping it distinct is what lets “a character” and “a byte” stay different ideas, which a language with a UTF-8 string has to do. Conversion to u32 is total and written u32(c); conversion from u32 is partial, and has both a checked form that traps and a fallible form that returns an Option.

`unit` and `never`

unit is the type with exactly one value — what a function that returns nothing returns. It is a real type, so it composes: a Fn() -> unit needs no special case in the callable machinery.

never is the type with no values, and it is what an expression that does not finish has. A call to exit has type never, as does a return or a break considered as an expression. Because there are no values of it, never is a subtype of everything — which is what lets a match arm that aborts sit beside arms that produce an int without the arms disagreeing.

`string`

A validated UTF-8 string, three words wide. It is immutable, indexing it by byte position gives bytes, iterating it gives chars, and + concatenates but will not accept a non-string operand. Strings is the full account — the representation, the validity guarantee, and every form that makes new bytes — and the operations that live in the library are under sysl.text.

Fixed arrays and slices

Two sequence types where many languages have one.

type	what it is
`[N]T`	a fixed array: `N` elements, a value, no header, length known while compiling
`[]T`	a slice: a view of elements someone else owns — `{ owner, pointer, length }`
`[]const T`	a slice that may be read and not written

An array is its elements, so copying one copies all of them and passing one by value passes the whole thing. A slice names elements that live somewhere else, and copying a slice copies the three-word header rather than the data.

var a = [1, 2, 3]
var b = a

b[0] = 99

var v: []int = a[..]
v[1] = 88

print(a[0], a[1], b[0])

1 88 99

The disagreement in that program is the whole distinction: writing through b did not touch a because b is a copy, and writing through v did because v is a view.

Both carry a length, so every index is checked. Arrays and slices is the full account — writing one down, storage sized while running, the indexing and slicing rules, and what a view keeps alive.

Vectors

A fourth sequence shape, and the one that is not storage at all.

type	what it is
`<N>T`	a vector: N lanes of `T` in a register, whose operators work on every lane at once

It holds the same values an [N]T holds, in the same order — the two type constructors differ by one bracket pair because a vector is an array that computes lane-wise:

val a: <4>f32 = [1.0, 2.0, 3.0, 4.0]
val b: <4>f32 = [10.0, 20.0, 30.0, 40.0]

print((a + b)[3], (a * 2.0)[0], (a * b).sum())

44 2 300

That + is one instruction doing four additions, and the 2.0 broadcasts into every lane. A lane is read by a constant index, which is the one subscript in the language not checked while the program runs — a register has no address to check against. A run of an array or a slice moves into a vector and back with xs.load(i) and xs.store(i, v), which are checked, because those have addresses.

A machine with no vector unit is not a special case: the back end turns a vector into as many registers as it needs, or into ordinary scalar operations, so <4>f32 compiles everywhere sysl compiles. Vectors is the full account — masks and select, the reductions, and writing one kernel that is compiled for more than one register width.

Structs

A named product type. Fields are declared one per line, and a struct is a value — assigning one copies it.

struct Point
    x: int
    y: int
end Point

var p = Point(1, 2)
var q = p

q.x = 99

print(p.x, q.x)

1 99

Structs may carry methods, an invariant, and a visibility modifier per field. A struct may also be declared opaque, which withholds its layout from everyone outside its own module — a different axis from visibility, covered under modules.

Enums

Two shapes under one keyword. A simple enum is a set of named discriminants with an underlying integer type; a data enum gives variants payloads, making it a sum type.

enum Color
    Red
    Green
    Blue

enum Shape
    Circle(r: real)
    Rect(w: real, h: real)

area(s: Shape) -> real = s match
    Circle(r)  -> 3.14159 * r * r
    Rect(w, h) -> w * h

print(int(Green), area(Circle(1.0)), area(Rect(2.0, 3.0)))

1 3.14159 6

Option[T] and Result[T, E] are ordinary data enums declared in the standard library, with no compiler privileges — which is why you can write your own and have it work identically.

A variant belongs to its enum

Two enums in one module may each name a variant Failed, and neither has to be renamed. What a bare name means is settled where it is used, by the type expected there — an argument, an annotated binding, a return and a field all supply one, so the short form is what you normally write:

enum Shape
    Circle(r: int)
    Square(side: int)

enum Hole
    Circle(r: int)
    Slot(len: int)

area(s: Shape) -> int = s match
    Circle(r)    -> 3 * r * r
    Square(side) -> side * side

depth(h: Hole) -> int = h match
    Circle(r) -> r
    Slot(len) -> len

val s: Shape = Circle(2)

print(area(s), depth(Circle(5)))

12 5

Where two enums answer and nothing says which, that is a diagnostic rather than a quiet choice — a construction that picked the first-declared enum would be a line whose meaning changed when somebody added an unrelated enum above it:

enum Shape
    Circle(r: int)
    Square(side: int)

enum Hole
    Circle(r: int)
    Slot(len: int)

var s = Circle(1)

print(1)

'Circle' is a variant of 'Shape' and 'Hole', and nothing here says which — qualify it, as 'Shape.Circle'

Shape.Circle(1) is what that line wants. The qualified form works at a construction exactly as it works in a pattern.

This is Rust’s arrangement — a variant is namespaced under its enum — without Rust’s use site, where Link::Failed is required everywhere unless a scope opts into use Link::*. A variant still may not share a name with a constant, a val, a module var or an extern variable: two variants of a name are told apart by the enum they belong to, and a variant and a constant have nothing to be told apart by.

Type aliases

type Name = Existing introduces a second spelling for a type, interchangeable with the first. It creates no new type and no checking: an alias is for shortening a name that has grown long, not for distinguishing two uses of the same representation.

When you want a genuinely distinct type — one the compiler will not let you confuse with its base — that is a constrained type, written with new, and it is covered under contracts.

Function types

A callable’s type is written with Fn:

apply(f: &Fn(int) -> int, x: int) -> int = f(x)

print(apply(n -> n * 3, 7))

A named function used where a callable is expected is the capture-free case of the same thing — there is no separate “function pointer” concept to learn. A raw C function pointer, for a foreign boundary, is spelled *extern(A) -> R and is covered under the foreign interface.

A parameter passed by name

A parameter written with the arrow and nothing on its left takes an expression the call does not evaluate, and the body evaluates at each use:

static var built: int = 0

message() -> int
    built += 1
    42

log(on: bool, m: -> int)
    if on then print(m)

log(false, message())
log(true, message())
print(built)

42
1

message() ran once, not twice: the first call never evaluated its argument. That is the form’s whole purpose — an argument a callee may not want should cost nothing to offer.

Each use is an evaluation, because each use is a call — so a body that names the parameter twice runs the argument twice. A body wanting one evaluation binds it to a val first.

It costs nothing at runtime. x: -> T has the type Fn() -> T, so it lowers to a bounded type parameter exactly as the ordinary bare arrow does — one specialized copy per call site, called directly, with no allocation.

x: () -> T is the neighbouring form and keeps its meaning. Same type, different call site: there the caller constructs the callable and the body calls it.

twice(f: () -> int) -> int = f() + f()

print(twice(() -> 21))

Traits and generics

2026-08-16T01:26:07.924728867Z

sysl has one polymorphism mechanism, and it is called trait. A type takes part in a trait only through an explicit impl Trait for Type; there is no structural conformance, so a type never satisfies a trait by coincidence of method names.

What varies is not the mechanism but how you spell the parameter:

[T: Trait] — a bound on a generic. Monomorphized, direct calls, no indirection.
&Trait / *Trait — a trait object. One copy of the code, dispatched through a table.

Same trait, two strategies, and no dyn keyword: the memory-mode sigil already says everything one would.

A trait, and an implementation

trait Greet
    name(self) -> string
    greet(self) -> string = "hello, " + self.name()

struct Cat
    tag: string

impl Greet for Cat
    name(self) -> string = self.tag

var c = Cat("mimi")

print(c.greet())

hello, mimi

A member written as a bare signature is one an implementation must supply. One written with a body is a default that every impl inherits unless it writes its own.

Defaults are what let a trait grow: adding a member with a default does not break the implementations that already exist, which is the difference between a trait a library can evolve and one frozen at its first release.

A default’s body may assume of its receiver exactly what its own trait declares, and nothing more. That is not a restriction bolted on — it is what a default is, since the body has to serve every implementing type and the trait is all they have in common. It is checked once, at the trait, even when nothing implements the trait at all.

Any type may carry an `impl`

Including the built-ins, which is not a convenience but a requirement — a Show that cannot cover int is a Show no library can be written against:

trait Show
    show(self) -> string

impl Show for int
    show(self) -> string = "int " + str(self)

impl Show for bool
    show(self) -> string = if self then "yes" else "no"

var n: int = 5

print(n.show(), true.show())

int 5 yes

Where an impl may live is the one restriction: in the module that declares the trait, or in one that declares a type named in the subject. That is Rust’s orphan rule, and it costs nothing — retrofitting still works, because impl MyTrait for TheirType lives with MyTrait. What it buys is that resolving a bound inspects only the modules a use site already depends on, with no global search and no dependency edge the source does not show.

Generics, and what an unbounded parameter may do

A type parameter list in square brackets makes a function, struct or enum generic:

struct Pair[A, B]
    first: A
    second: B

    swapped(self) -> Pair[B, A] = Pair(self.second, self.first)

var p = Pair(1, "one")
var q = p.swapped()

print(p.first, p.second, "/", q.first, q.second)

1 one / one 1

Pair asks nothing of A and B, and it does not need to. With no bound, a parameter may be copied, assigned, passed, returned, and stored — which is exactly what a container does.

That baseline is bigger here than in Rust, and the memory chapter is why: every sysl value is copyable, since assignment copies and copying a value holding a &T retains it. So there is no Copy bound to write, ever. “Hold and hand along any T“ is free and unmarked.

Type arguments are inferred, and from two directions — from the arguments (Pair(1, "one") gives A = int, B = string) and from the expected type, for the cases the arguments cannot settle. A parameter that neither direction determines is an error asking for an annotation, never a silent default.

A bound is a trait

What an unbounded T may not do is anything that assumes structure: no operator, no method call, no field access, no subscript. Each of those is a capability some types have and others do not, so each needs a bound that guarantees it:

trait Show
    show(self) -> string

impl Show for int
    show(self) -> string = "#" + str(self)

describe[T: Show](x: T) -> string = "<" + x.show() + ">"

var n: int = 7

print(describe(n))

<#7>

And here is the whole payoff. Drop the bound and the error lands on the definition that is wrong, not on some caller three files away that instantiated it with the wrong type:

trait Show
    show(self) -> string

describe[T](x: T) -> string = x.show()

'show' needs 'T: Show'

The diagnostic names the bound to write, which is its whole job. That is definition-checked generics — the Swift/Kotlin/Scala consensus, and the opposite of a C++ template, whose errors arrive at instantiation wearing the callee’s insides.

Multiple bounds join with +: [T: Ord + Hash] asks for both.

A field is the one exception, and it proves the rule. Every other unlicensed use names the bound that would allow it, because that is the diagnostic’s whole job. A field names none — a trait promises behaviour and a field is layout, so no bound could ever supply one. Reaching a value’s data through a generic means going through a member the bound declares, which is also what lets two types satisfy one bound while storing the value differently.

Operators are trait methods

Which is why a bound is all it takes to write arithmetic over a parameter:

sum[T: Add](a: T, b: T) -> T = a + b
biggest[T: Ord](a: T, b: T) -> T = if a < b then b else a

print(sum(3, 4), sum(1.5, 2.25))
print(biggest(3, 9), biggest("apple", "pear"))

7 3.75
9 pear

+ is Add, < is Ord, == is Eq. Nothing about generics is special-cased for operators; an operator on a T simply requires the bound that supplies it, the same as a method call does.

A type’s own parameters carry bounds too, in the same brackets and meaning the same thing — and that is where a type says what it assumes. struct SortedList[T: Ord] holds every application of the type to the promise, and lets its members be checked at their definitions rather than at each use.

A bound is declared once, at the type, and is in force everywhere its parameters appear: a member’s signature and body, a field’s type, a variant’s payload. It is not restated per member.

Monomorphization

Each distinct set of type arguments produces its own specialized function or aggregate. sum called at int and at real emits two functions; Pair[int, string] and Pair[int, int] are two layouts.

That is what lets bounds be checked once at the definition and still lower to direct, inlinable code with no dictionary passed at run time. The cost is code size, which is the standard trade and the right default for a systems language — with the dynamic path below available whenever one copy is what you actually want.

Variance does not arise. Variance is about when G[A] may stand in for G[B], which needs a subtyping relation to be interesting, and sysl has none among concrete types. Box[Cat] and Box[Animal] are simply unrelated. That deletes a whole category of design difficulty, and it should stay deleted: polymorphism over a set of types is a bound or a trait object, never a covariant container.

Trait objects

When the set of types is open or genuinely heterogeneous, monomorphizing is impossible or wasteful. A trait object is a fat pointer — two words, the method table for the type it forgot, and the value itself:

trait Shape
    area(self) -> int

struct Rect
    w: int
    h: int

impl Shape for Rect
    area(self) -> int = self.w * self.h

struct Square
    side: int

impl Shape for Square
    area(self) -> int = self.side * self.side

total(shapes: []const &Shape) -> int
    var t = 0

    for s in shapes do t += s.area()

    t

var shapes: [2]&Shape = [Rect(3, 4), Square(5)]

print("total:", total(shapes))

total: 37

The sigil says who owns the second word, and nothing else changes between the two. &Shape is an ARC-owned object — the data word is the reference-counted box the value sits in, and letting go of it needs no more knowledge of the payload than letting go of any &T does. *Shape is a raw fat pointer, unmanaged like every *T, and it is what a kernel passes around when there is no allocator.

Erasure is a coercion, applied wherever an object type is expected — an argument, a declared variable, an array element, a struct field. Above, each Rect(3, 4) is constructed, boxed because a &Shape was expected, and then erased, which is the ordinary “write the construction and it is allocated” rule with one more step. Because the coercion applies per branch, an if or a match whose arms are different concrete types meets at one trait object — which is the point of having them.

What an object offers is the trait’s methods and nothing else. No dereference, no fields, no comparison, and no way back to the concrete type.

But the two halves of this page’s opening meet at a bound. An object carries a table of the trait’s members, which is exactly what a bound asks for — so a [T: Shape] function takes a &Shape as readily as it takes a Rect, with an indirect call where the other gets a direct one. The choice between static and dynamic is about what the caller holds, not about which functions it can reach, and a library written against bounds is not closed to a program that erased.

Object safety

Erasure forgets the type, so a member may promise nothing that depends on knowing it. A trait can be made into an object when every member has a receiver and mentions Self nowhere but there.

That second rule excludes every trait in the operator catalogue — add(self, rhs: Self) -> Self first among them — and that is the right answer rather than a limitation. An operator over two values of one type is a question about types known while compiling, so those traits are for bounds.

A trait may require another

trait Reader: Fallible says that implementing Reader obliges implementing Fallible too. The requirement is checked at the impl, not at the bound — so [T: Reader] gets both traits’ members without having to name both, and a type that forgot one is told at its own declaration rather than at somebody’s call.

Where the required trait’s members all have defaults, satisfying it is one line with no block under it:

trait Fallible
    failed(*self) -> bool = false

trait Source: Fallible
    take(*self) -> int

struct Counter
    n: int

impl Fallible for Counter

impl Source for Counter
    take(*self) -> int
        self.n += 1
        self.n

var c = Counter(0)

print(c.take(), c.take(), c.failed())

1 2 false

That is the shape the standard library’s byte surface uses: Reader and Writer each require Fallible, so a type that is both carries one failed rather than two that nothing at a call site could tell apart.

A trait may take type arguments

Every trait so far has been a property of one type — a Cat greets, a Rect has an area. A trait with parameters says something about a relation between types instead: what a sink accepts, what a conversion converts from, what an iterator yields.

The arguments are written in the same place wherever the trait is named — impl Sink[int] for Buffer, a bound [X: Sink[int]], an object &Sink[int] — and they mean the same thing in each. What that buys is the rule underneath: a type implements a parameterized trait once at each argument list, so two implementations on one type are ordinary rather than a conflict:

trait From[T]
    from(x: T) -> Self

struct Temp
    tenths: int
end Temp

impl From[int] for Temp
    from(x: int) -> Temp = Temp(x * 10)

impl From[real] for Temp
    from(x: real) -> Temp = Temp(int(x * 10.0))

var a = Temp.from(21)
var b = Temp.from(21.5)

print(a.tenths, b.tenths)

210 215

Temp has two members called from, and what says which a call means is the argument list. The resolution is determined, not preferred: a call is answered by the one implementation whose parameters match the types the arguments have, and nothing ranks two candidates — so a call matching none of them is reported rather than resolved to the nearest.

Which is exactly why the arguments have to appear where they can be seen at a call. A trait parameter that shows up only in a return type leaves the call with nothing to select on:

trait Into[T]
    into(self) -> T

struct Reading
    raw: int
end Reading

impl Into[real] for Reading
    into(self) -> real = f64(self.raw) / 10.0

impl Into[string] for Reading
    into(self) -> string = "raw " + str(self.raw)

var r = Reading(215)

var celsius: real = r.into()

print(celsius)

'into' comes from 2 implementations of one trait on Reading, and the arguments do not say which was meant

Rust answers that one with turbofish and inference from the expected type. sysl’s own written type arguments do not reach it: x.into[Celsius]() would name a member’s own parameters, and what is ambiguous here belongs to the implementation rather than to into. Writing the conversion as From[T] — where the thing being converted is an argument — is the shape that needs no such machinery at all.

This is also the mechanism the error handling chapter points at. A ? that converts a callee’s error into the caller’s needs an AppError that is From[IoError] and From[ParseError], and those are two argument lists rather than two implementations of one thing.

Implementing `Display`

The trait worth writing first, because it is what print and str reach:

struct Point
    x: int
    y: int

impl Display for Point
    display(self, out: *Writer, fmt: FormatSpec) =
        display_pad(("(" + str(self.x) + ", " + str(self.y) + ")").bytes, out, fmt)

var p = Point(3, 4)

print(p)
print("as text:", str(p), "padded:", f"${p}%10s")

(3, 4)
as text: (3, 4) padded:     (3, 4)

Note the shape of the signature: a value renders itself into a *Writer rather than returning a string. That is what makes rendering allocation-free — a program in a kernel supplies its own sink with an ordinary impl — and str(x) is then the same rendering aimed at a buffer.

Writer is the first trait the language itself forms objects of, and display_pad is where every implementation ends up: it applies the FormatSpec to the finished bytes, which is why the parts are gathered before anything is padded. A specifier describes the field the whole value occupies, so %10s on a point pads the point and not its first number.

Next: modules and the standard library — how a program is split up, and what comes in the box.

Traits

2026-08-16T01:26:07.924728867Z

sysl has one polymorphism mechanism, and it is the trait. It is nominal: a type participates in a trait only through an explicit impl Trait for Type, and never by coincidence of method names. From that one mechanism come both dispatch strategies — static, through a generic bound, and dynamic, through a trait object.

trait Greet
    name(self) -> string
    greet(self) -> string = "hello, " + self.name()

struct Cat
    tag: string
end Cat

impl Greet for Cat
    name(self) -> string = self.tag

var c = Cat("ada")

print(c.greet())

hello, ada

Two things are on display. A trait’s member is either a bare signature, which an implementation must supply, or a signature with a body, which is a default every implementation inherits unless it writes its own. And an implementation’s members become the type’s own, so c.greet() is called exactly as an inherent method is.

Declaring a trait

A trait’s members are the three kinds a type’s members are, declared the same way and distinguished the same way:

member	form	reached as
method	`area(self) -> int`	`x.area()`
property	`size -> int`	`x.size`, with no parentheses
associated function	`zero() -> Self`	`T.zero()`, through the type

A property is asked for by dropping the body from its declaration form, and supplied by an implementation writing that body:

trait Sized
    size -> int

struct Box
    w: int
    h: int
end Box

impl Sized for Box
    size -> int = self.w * self.h

var b = Box(3, 4)

print(b.size)

Nothing about a property’s dispatch differs from a method’s: it has a receiver, it simply never spells one, so it takes a table slot beside the methods and a bound licenses reading it exactly as one licenses calling them.

Which kind a member is has to match between the trait and the implementation, and that is a real check rather than a formality — a property and an associated function both have no receiver to compare, so size(self) -> int would otherwise quietly stand in for size -> int.

Self is the implementing type, written wherever a signature has to name it. Inside a generic impl it is the subject applied to that block’s parameters, so -> Self and -> Box[T] are the one signature conformance compares.

A default may assume exactly what its own trait declares

That is not a restriction bolted on; it is what a default is, since the body must serve every implementing type and the trait is all they have in common. So a default’s body is checked once, at the trait, as the generic function it is — one type parameter, Self, bounded by the trait. A default calling a member the trait does not declare is reported at the trait, on its own line, even when nothing implements the trait at all.

It may not read a field of its receiver either. A bound promises behaviour and a field is layout, so no bound could ever license one — see generics.

What a default buys beyond convenience is that a trait can grow: adding a member with a default does not break the implementations that already exist, which is the difference between a trait a library can evolve and one frozen at its first release.

A trait whose every member has a default leaves nothing to write, so the block is optional and the opt-in is the point of writing it:

trait Loud
    volume(self) -> int = 11

struct Amp
    n: int
end Amp

impl Loud for Amp

var a = Amp(1)

print(a.volume())

The body a program runs is a copy per implementing type, materialized under that type’s own name. That is monomorphization with Self for the parameter, so everything downstream — an ordinary call, a table slot, the escape summary — finds a function that exists and needs to know nothing about where it came from.

Replacing a default says `override`

An implementation may write the member itself instead of taking the trait’s body, and when it does it says so — replacing a default is the same act as replacing an implementation, and takes the same keyword:

trait Loud
    volume(self) -> int = 11

struct Amp
    n: int
end Amp

impl Loud for Amp
    override volume(self) -> int = self.n

var a = Amp(4)

print(a.volume())

Leave it off and the member is refused, because the reader of an impl block wants to know which of its members are replacing something and which are supplying what the trait asked for — a question that otherwise means opening the trait to find out:

trait Loud
    volume(self) -> int = 11

struct Amp
    n: int
end Amp

impl Loud for Amp
    volume(self) -> int = self.n

print(1)

trait 'Loud' supplies a body for method 'volume', so writing one here replaces it — say 'override volume', or leave the member out to keep the trait's

And it is refused where nothing is replaced. A member answering a bare requirement — the ordinary case, and every member of most impl blocks — supplies what the trait asked for rather than replacing a body, so the keyword would be saying something untrue:

trait Sized
    size -> int

struct Box
    w: int
    h: int
end Box

impl Sized for Box
    override size -> int = self.w * self.h

print(1)

trait 'Sized' declares property 'size' without a body, so this member supplies what the trait asked for rather than replacing anything — 'override' says a body was replaced

The rule costs almost nothing, because an implementation content with a default writes no member at all — across the whole of sysl’s own library, guides and examples, exactly two members replace one.

Conformance is explicit, always

A type that happens to have a member of the right name and shape does not satisfy a trait. There is no structural conformance, and the impl is what documents the intent:

trait Named
    label(self) -> string

struct P
    n: string

    label(self) -> string = self.n
end P

announce[T: Named](x: T) -> string = x.label()

print(announce(P("ada")))

'announce' requires its type parameter 'T' to implement 'Named', but P does not

Nominal is the consensus among the languages sysl takes from — Swift protocols, Kotlin interfaces, and Scala traits are all nominal — and it kills accidental conformance, where a type satisfies a promise purely because two names collided.

Retrofitting is preserved. You may impl your trait for a type you do not own; you just do it explicitly rather than by implicit structural match.

The two dispatch strategies

A trait is used two ways, and this is the pivot a programmer faces every time polymorphism comes up.

	`[T: Trait]` — static	`&Trait` / `*Trait` — dynamic
what happens	one specialized copy per concrete `T`	one copy of the code, dispatched through a table
the call	direct, inlinable	indirect, not inlined
the value	by value, no indirection	behind a fat pointer, always
the set of types	fixed at compile time	open
cost	code size	one indirect call
reach for it when	the type is known — the overwhelming majority	the collection is heterogeneous, or the boundary is a plugin

Static is the default:

trait Named
    label(self) -> string

struct Dog
    n: string
end Dog

struct Cat
    n: string
end Cat

impl Named for Dog
    label(self) -> string = "dog " + self.n

impl Named for Cat
    label(self) -> string = "cat " + self.n

announce[T: Named](x: T) -> string = x.label()

print(announce(Dog("rex")), announce(Cat("ada")))

dog rex cat ada

Dynamic is the escape hatch for genuine runtime heterogeneity:

trait Shape
    area(self) -> int

struct Rect
    w: int
    h: int
end Rect

struct Square
    s: int
end Square

impl Shape for Rect
    area(self) -> int = self.w * self.h

impl Shape for Square
    area(self) -> int = self.s * self.s

var shapes: [2]&Shape = [Rect(2, 3), Square(4)]

print(shapes[0].area(), shapes[1].area())

6 16

Same trait, two strategies, chosen by how you spell the parameter — a bound for static, a sigil-carried trait object for dynamic. There is no dyn keyword either way, because the sigil already says everything one would.

The two are not separate worlds. A trait object satisfies a bound on the trait it dispatches through, so announce above takes a &Named as readily as it takes a Dog — the table it carries holds exactly the members the bound names:

trait Named
    label(self) -> string

struct Dog
    n: string
end Dog

impl Named for Dog
    label(self) -> string = "dog " + self.n

announce[T: Named](x: T) -> string = x.label()

var d: &Named = Dog("rex")

print(announce(Dog("rex")), announce(d))

dog rex dog rex

So the table above is about what the caller holds, not about which functions it can reach. A library written against bounds is open to a program that erased, and needs no second signature written the other way. See generics for what the rule rests on — an object type is a concrete type, so nothing about monomorphization changes to allow it.

Any type may carry an `impl`

impl Show for int is as ordinary as impl Show for Point, and impl Show for []int is as ordinary as either. This is not a convenience: a trait that cannot cover int is a trait no library can be written against, and the library’s own Display is the first thing that needs it.

trait Double
    twice(self) -> int

impl Double for int
    twice(self) -> int = self * 2

print(5.twice(), (2 + 3).twice())

10 10

Every type has one owner key its members are filed under: a struct or an enum by the name it was declared with, everything else by its one canonical name. So impl Show for int and impl Show for i32 are the single implementation they are rather than two, and two spellings of one type collide as the duplicate they are.

An impl‘s subject is a type reference, not an identifier, so the types with no name of their own carry an implementation exactly as the named ones do:

trait Total
    total(self) -> int

impl Total for [3]int
    total(self) -> int = self[0] + self[1] + self[2]

var a: [3]int = [1, 2, 3]

print(a.total())

An array’s length is part of its type, so [2]int and [3]int are two types and may implement the same trait differently.

Two subjects are refused, each because an implementation for it would be about nothing:

a memory mode — *Point, &Point. A mode is a way of holding a Point rather than a type beside it, and a member call already sees through one level of * or & to find the receiver’s members, so an impl for the mode would register members nothing could reach;
a trait object — *Show. An impl says how one particular type behaves, and which type it holds is precisely what an erased value has forgotten.

struct P
    v: int
end P

trait Show2
    show2(self) -> int

impl Show2 for *P
    show2(self) -> int = 1

print(1)

'*P' is a way of holding a P rather than a type of its own — write the 'impl' for P

A compiler-provided member is out of reach for the same reason a field is. len on a slice or an array, and bytes on a string, are reached ahead of the member table rather than through it, so an impl declaring one would register a member no reader could find.

Where an `impl` may live

An impl is unnamed — nothing at a use site says which one to apply — so resolving T: Show or 5.show() means searching for an implementation. Once a program is more than one module, that search needs a bound, or it would range over every module in the program, which is exactly the property that makes separate compilation impossible.

An impl Trait for Type may appear only in the module that declares Trait, or in one that declares a type named in Type. Resolving a bound therefore inspects only the modules a use site already depends on in order to write the trait and the type down. No global search, and no dependency edge the source does not show.

This is Rust’s orphan rule, and it costs nothing:

retrofitting still works — impl MyTrait for TheirType lives with MyTrait, and the trait’s module licenses it;
impl Show for int still works — a built-in has no module of its own, so its owner key belongs to the library, and every impl on one is licensed by its trait’s module instead;
a composed type is the module’s when anything named in it is — override impl Display for []Point is licensed by Point, while a block for []int names nothing outside the library and has no home. (It says override because the library implements Display for every slice; the two rules are separate, and a slice of your own struct needs both — coherence to have a home, and override to outrank the block already covering it);
a type parameter is not a local type, so impl[T: Display] Display for []T is refused however its bound is written. Making every printable slice printable is the library’s job.

What the rule forbids is the case with no home: a foreign trait implemented for a foreign type, where two unrelated modules could each supply a different implementation and no rule picks one.

An impl is part of its module’s public surface. Adding, removing, or changing one is an interface change visible to everything downstream — the same reasoning that puts implicit-resolution schemes out of scope. See modules.

An `impl` covers a generic type as a whole

A block may declare type parameters of its own, written directly after the keyword:

struct Box[T]
    v: T
end Box

trait Show
    show(self) -> string

impl[T: Display] Show for Box[T]
    show(self) -> string = "box of " + str(self.v)

var b = Box(41)

print(b.show())

box of 41

That is one implementation for every Box, and its members are monomorphized per receiver exactly as a generic type’s own members are.

Its subject must be the type applied to the block’s parameters and nothing else — each argument one parameter, each parameter used once, all of them spoken for:

struct Box[T]
    v: T
end Box

trait Show2
    show2(self) -> int

impl Show2 for Box[int]
    show2(self) -> int = 1

print(1)

'Box' is generic, so an 'impl' for it covers every instantiation at once — write 'impl[T] Show2 for Box[T]'

A generic type has one key for all of its instantiations, so an implementation for some of them would be a second implementation for a key that holds one. Overlapping implementations, and the specialization rule that would be needed to pick between them, are deliberately not in the language.

The parameters are matched to the arguments by position in the subject, not by the order they were declared in, so impl[X, Y] Show for Pair[Y, X] reads as it looks.

Conditional conformance

A bound on the block is what makes the conformance conditional. In the Box example above, a Box[T] implements Show precisely when T implements Display — so Box[int] does and a Box of something unprintable does not.

That question is asked one step in and composes: under impl[T: Show] Show for Box[T], a Box[Box[int]] conforms exactly when Box[int] does, which is what makes a conditional implementation usable on nested types at all.

struct Box[T]
    v: T
end Box

trait Show
    show(self) -> string

impl Show for int
    show(self) -> string = "i"

impl[T: Show] Show for Box[T]
    show(self) -> string = "b" + self.v.show()

var b = Box(Box(1))

print(b.show())

bbi

Everything that asks whether a type conforms asks it the same way — a generic function’s bound, an erasure to a trait object, print reaching for a Display — so an instantiation that fails the condition is refused at each of them while its siblings are not.

What the bounds buy beyond deciding conformance is that the members become checkable at their definition: a block states what it assumes, so its bodies are walked once against those bounds alone, and a method calling something no bound licenses is reported on its own line with nothing instantiated.

A shape is covered the same way

A composed type has no name to be generic over, but it has a shape, and a block with type parameters may match that instead:

trait Count
    count(self) -> usize

impl[T] Count for []T
    count(self) -> usize = self.len

var xs: []int = [1, 2, 3, 4]

print(xs.count())

Everything above holds unchanged: the subject is the shape applied to the block’s parameters and nothing else, so impl[T] Count for [][]T is refused because the element is a shape rather than a parameter, and so is a fixed element:

trait Count
    count(self) -> int

impl[T] Count for []int
    count(self) -> int = 1

print(1)

'int' fixes the element type, and an 'impl' with type parameters covers every slice — write one of the block's own parameters here

Two things are the shape’s own. A composed type is filed under the whole of itself — []int, not [] — so a shape needs a key the types it covers do not have, and dropping the arguments is what makes one; a lookup finding nothing under the type’s own key falls back to it. And because an array’s length is not something a parameter can stand for, the length stays part of the shape: [2]T and [3]T are two shapes, each covering every element type at its own length.

A string is not covered by []T. It is a view of bytes that are valid UTF-8, and that invariant is the whole difference between it and a []u8 — a block written for every slice has said nothing about it. "hi".bytes is a []u8 and is covered.

A shape and a written-out type overlap, and an unmarked overlap is refused. Both blocks would say how a []int renders, so whichever is written second is refused and the diagnostic names the one already there:

trait Show2
    show2(self) -> int

impl Show2 for []int
    show2(self) -> int = 1

impl[T] Show2 for []T
    show2(self) -> int = 2

print(1)

'[]int' already implements 'Show2', and this 'impl' would implement it for every slice — including that one

That is the default and it is worth keeping: two blocks that overlap are usually a mistake — a duplicate written by accident, or one put in the wrong module — and refusing them is how that gets found.

`override` — when the overlap is deliberate

An implementation may say override, and then it wins:

trait Show2
    show2(self) -> int

impl[T] Show2 for []T
    show2(self) -> int = 2

override impl Show2 for []int
    show2(self) -> int = 1

var xs: []int = [7, 8]
var ss: []string = ["a"]

print(xs.show2(), ss.show2())

1 2

The keyword goes on the overriding side, not the overridden one. That is the whole of the design, and it is the opposite of C#’s virtual/override pair and of Rust’s unstable default: both of those make the general implementation grant permission in advance, and a library author cannot know which of their implementations somebody will need to replace. Intent is something the writer of the override has and the writer of the original does not.

It grants no permission, so what it buys is the diagnostic. An unmarked second implementation is still refused exactly as above.

The overriding side is always a type written out in full. A shape is one key and so is a generic type’s name, and the blocks that would sit under those are already refused — impl[T] Show2 for [][]T matches a shape’s argument by its shape, and impl Show2 for Box[int] fixes one instantiation of a block covering every instantiation. So there is nothing below either of them to be more specific than, and marking one says so:

trait Show2
    show2(self) -> int

override impl[T] Show2 for []T
    show2(self) -> int = 2

print(1)

'override' says this block replaces a more general one, and '[]T' is the general kind — an implementation for a shape or for a generic type covers every type it matches at once, so there is nothing below it. The override is written on the block for one type spelled out in full

An override that overrides nothing is refused, which is the check in the other direction and the one that earns its keep later: a library drops or narrows the implementation a program was overriding, and without this the override silently becomes the only one while still claiming to replace something.

trait Show2
    show2(self) -> int

override impl Show2 for []int
    show2(self) -> int = 1

print(1)

'[]int' says 'override', but nothing else implements 'Show2' for it — an override replaces an implementation that covers the type more generally, and there is none to replace

What keeps this sound is coherence rather than the keyword. The hazard a rule like this usually brings is two method tables for one type — a []Point erased to a *Show2 picking one implementation at one site and the other elsewhere. An impl may live only in the module declaring the trait or in one declaring a type named in the subject, so a program cannot write impl[T] Display for []T at all — []T names no type of its own. The only override anybody can write across a module boundary is one that names their own type, so there is exactly one per type and it lives with that type; and any site that can write []Point down already depends on the module declaring Point. One type, one table.

The cost that remains, stated plainly: a library can no longer rely on its own implementations. What override buys is that every such site is greppable rather than invisible.

A trait may take type parameters

A trait declares parameters in the same bracketed list every other generic declaration writes, and an implementation says which arguments it supplies:

trait Sink[T]
    put(*self, x: T) -> int

struct Buffer
    n: int
end Buffer

impl Sink[int] for Buffer
    put(*self, x: int) -> int
        self.n += x

        self.n

var b = Buffer(0)

print(b.put(3), b.put(4))

3 7

Sink is not one promise but a family of them: Sink[int] and Sink[string] say different things, and which one a Buffer makes is the implementation’s to state. That is what a trait needs before it can describe a relation between two types rather than a property of one — what a sink accepts, what a conversion converts from, what an iterator yields.

The arguments are written in the same place in all three positions a trait is named, and mean the same thing in each:

position	written
a bound	`f[X: Sink[int]](x: X)`, and the body’s `x.put(…)` then takes an `int`
an implementation	`impl Sink[int] for Buffer`
a trait object	`&Sink[int]`

A trait’s own parameters carry bounds too — trait Get[T: Show] — and everything applying the trait supplies them, exactly as everything applying a bounded struct does.

A parameter may carry a default, and Self is the case the feature exists for: trait Scale[R = Self] is the operand type, usually the implementing type, so impl Scale for P is the impl Scale[P] for P it reads as and [T: Scale] asks for Scale[T]. See generics for how defaults are filled.

One implementation per argument list

A type may implement a trait once at each argument list, and the argument list is what tells two implementations apart:

trait Sink[T]
    put(self, x: T) -> string

struct Buf
    tag: string
end Buf

impl Sink[int] for Buf
    put(self, x: int) -> string = self.tag + " int"

impl Sink[string] for Buf
    put(self, x: string) -> string = self.tag + " string"

var b = Buf("b")

print(b.put(1), b.put("x"))

b int b string

A second impl Sink[int] for Buf beside those is refused — that one is already there.

This is the one place the “a trait’s members become the type’s, and a type’s members are one namespace” rule is qualified, and the qualification is narrow. A Celsius with both blocks has two members called from, and what says which a use means is the argument list, which every way of reaching one already carries: an operator carries its pair of operands, a bound names the arguments, a trait object is formed at written arguments, and a named call passes values whose types are the arguments.

The resolution is determined, not preferred. Nothing ranks two candidates: a call is answered by the one implementation whose parameters are the types the arguments have, and a call answering to none of them or to more than one is reported rather than resolved. So c.mul(2) where the candidates take a Complex and a real is refused — an integer literal is neither, and picking the nearest would be the specialization rule this language does not have.

Two limits fall out of “several implementations are told apart inside one namespace”:

a property has no arguments, so two implementations both supplying one leave nothing to select with, and reading it is refused;
a shape and a type of that shape are filed under two different owner keys, and a member lookup takes one or the other and never both — so a second implementation split across that boundary would be one no call could reach.

A generic block may write its own parameter as a trait argument — impl[T] Index[usize, T] for Buf[T] says a Buf[int] implements Index[usize, int] and nothing else. That is what lets a container carry the type of what it holds in the trait it implements, without an associated type to derive it from.

A trait may require another trait

trait Word: Add + BitXor — written after the name, with the same : and the same + a bound uses, because it asks the same thing of the implementing type.

trait Named
    label(self) -> string

trait Greet: Named
    greet(self) -> string = "hello, " + self.label()

struct P
    n: string
end P

impl Named for P
    label(self) -> string = self.n

impl Greet for P

var p = P("ada")

print(p.greet())

hello, ada

A required trait is a promise the trait makes rather than one each declaration repeats. [T: Greet] then licenses label; a default body in Greet may use it, since what a default may assume is exactly what its trait promises; and a &Greet object carries the required trait’s members in its table.

The requirement is checked at the impl, not at the bound, and the diagnostic belongs on the declaration that cannot keep its word:

trait Named
    label(self) -> string

trait Greet: Named
    greet(self) -> string = "hi"

struct P
    n: string
end P

impl Greet for P

print(1)

'Greet' requires 'Named', so 'P' has to implement that too — write 'impl Named for P'

Checking at the impl is also what keeps conformance a plain lookup: by the time anything asks whether a type implements a required trait, an implementation of it is already registered. The question is held until every impl has been seen, since the block supplying a required trait may be written below the one that needs it.

The table carries the required trait’s slots

A trait’s members are the required traits’ members, depth-first with each trait taken once, followed by its own. Both the table and the call sites indexing into it are laid out from that one list, so a required trait’s method is one indirect call, exactly like the trait’s own. The alternative — a word in the table pointing at the required trait’s own table — costs a second load on every such call and buys one thing sysl does not have: an upcast.

So a &Sub cannot become a &Super, and that is the price of the choice rather than an oversight. Nothing is unwritable for want of it: what a program does with a required trait is call its members, which works.

The diamond needs no rule of its own. D: A + C with both A: B and C: B carries B‘s members once, because the walk takes each trait the first time it reaches it. What is refused is two traits in one closure declaring a member of the same name — and the reason is the table, not the namespace. Two unrelated traits may each name a member of one type, because a call says which by naming the trait; two traits inside one requirement closure are laid out as one table, and a call through a &Sub has already forgotten everything that could have said which slot it meant.

trait L
    len2(self) -> int

trait R
    len2(self) -> int

trait Both: L + R
    both(self) -> int

print(1)

'R' and 'L' both declare 'len2', and a trait's members become the implementing type's — so 'Both' cannot require both

A trait may not require itself, directly or around a cycle:

trait Loop: Loop
    step(self) -> int

print(1)

trait 'Loop' requires itself, through Loop -> Loop

Two rules close the section. A trait may not require one that reaches less far than it does, since implementing the trait means implementing the required one — a requirement the implementer cannot name leaves the trait unimplementable from outside. And Self in a requirement’s arguments is the type implementing the requiring trait, so trait Vector: Scale[Self] asks that whatever implements Vector can be scaled by its own type — which is the same requirement trait Vector: Scale writes when Scale defaults its parameter to Self.

Trait objects

A trait object is a fat pointer — two words, the method table for the type it forgot and the value itself:

{ ptr vtable, ptr data }

The sigil says who owns the second word, and nothing else changes between the two:

written	the data word is	who frees it
`*Trait`	the value’s own address	nobody — raw and unmanaged, like every `*T`
`&Trait`	the reference-counted box the value sits in	ARC, exactly as for the `&T` it was erased from

*T and &T on a concrete type are thin pointers; on a trait they are fat. The trait-ness makes them fat, and that is why there is no dyn.

The table is per (trait, type, sigil), two flavours rather than one because the data word means different things: an entry has to reach a receiver, and from a box that is one step further in than from a bare value. Where the data word already is the receiver an implementation declared, the entry names that implementation itself; otherwise it names a small adapter that steps over the box header, loads the value, or both. So the common case costs one indirect call and nothing else.

Object safety

Erasure forgets the type, so a member may promise nothing that depends on knowing it. A trait may be made into an object when every member:

has a receiver. An associated function has nothing to dispatch on. A property does have one — by value, and unwritten — so a trait asking for a property is as safe to erase as one asking for a method.
mentions Self nowhere but that receiver. A second Self would have to be the same forgotten type as the first, which is exactly the fact an object no longer carries, and a Self result has no size to hand back.
does not take &self, for a *Trait only. &self asks for its receiver inside a box, and a raw object points straight at a value. A &Trait carries one, so it accepts such a member.
takes no .... A call to a variadic names the callee’s whole function type, because that is how it says where the declared parameters stop and the tail begins, and a slot in a table is one word and names none.

trait Scale
    scale(self, k: int) -> Self

struct P
    v: int
end P

impl Scale for P
    scale(self, k: int) -> P = P(self.v * k)

grow(s: &Scale) -> int = 0

print(1)

'scale' of 'Scale' mentions 'Self' away from its receiver, and an erased value has forgotten which type that is — so there is no '&Scale' to form

The middle rule excludes every trait in the operator catalog — add(self, rhs: Self) -> Self first among them — and that is the right answer rather than a limitation: those traits describe an operator over two values of one type, which is a question about types known at compile time. They are for bounds.

A trait that requires an unerasable one is unerasable itself, and the diagnostic names the trait the offending member came from. A built-in that satisfies a requirement by the compiler’s rule cannot be erased through it either — a table holds function pointers, and a scalar’s add is an instruction.

What that bites is the operator catalog at written arguments, and only that. Add[int, int] declares add(self, rhs: int) -> int — no Self anywhere — so it is a formable object type, and an int belongs to it by the compiler’s rule; &Add[int, int] = 3 is therefore refused, and the diagnostic says why rather than reporting a plain mismatch.

Display and Hash are not among them: every built-in reaches both through an impl, so a *Display carries an int, a u256, a string or a float alike, a &Hash carries anything that hashes, and a heterogeneous array of either is ordinary code. The rest of the catalog — Eq, Ord, Bits, Signed — names Self away from the receiver, so object safety refuses the type before a value gets that far.

Forming and using one

Erasure is a coercion, applied wherever a trait-object type is expected: at an argument, a declared variable, an assignment, a returned value, an array element, a struct field. &r erases to *Shape; a &Rect erases to &Shape; and a plain Rect(3, 4) where a &Shape is expected is boxed and then erased, which is the ordinary “write the construction and it is allocated” rule with one more step.

A *Trait will not take a bare value. A raw pointer needs an address, and taking one of a temporary silently is how a program acquires a dangling pointer:

trait Shape
    area(self) -> int

struct Rect
    w: int
end Rect

impl Shape for Rect
    area(self) -> int = self.w

var s: *Shape = Rect(2)

print(s.area())

a *Shape points at a value, so it needs an address — write '&' in front of the Rect to take one

Because the coercion applies per branch, an if or a match whose arms are different concrete types meets at one trait object, which is the point of having them:

trait Shape
    area(self) -> int

struct Rect
    w: int
    h: int
end Rect

struct Square
    s: int
end Square

impl Shape for Rect
    area(self) -> int = self.w * self.h

impl Shape for Square
    area(self) -> int = self.s * self.s

var wide = true
var s: &Shape = if wide then Rect(2, 3) else Square(4)

print(s.area())

What an object offers is the trait’s members and nothing else: no dereference, no fields, no comparison.

trait Shape
    area(self) -> int

struct Rect
    w: int
    h: int
end Rect

impl Shape for Rect
    area(self) -> int = self.w * self.h

var s: &Shape = Rect(2, 3)

print(s.w)

a &Shape has no fields, and trait 'Shape' declares no 'w'

A call is checked against the trait’s signature, which stands in for every implementation because conformance is exact.

An object keeps one trait and what that trait requires. A bound may name several traits because a bound is a list; a trait-object type names one because it is a type. So a value implementing Shape and Display keeps only the first when it becomes a &Shape — unless Shape requires Display, which is what makes the difference between the object being printable and not. A multi-trait object type (&(Shape + Display)) would be a second way to say the same thing and a worse one, since it puts at every use a fact that belongs on the trait.

The two sigils do not convert

*Trait and &Trait are two types and neither is accepted for the other.

In the direction that would matter — lending a counted object to something that only wants to ask it questions — this is sharper than it is for plain references, which have a spelling for it: &*r is the address of the place *r, so a &T reaches a function written against *T with the crossing into the unsafe tier written down at the call. An object has no dereference, so &*o says nothing, and a function that only reads a shape has to exist once per sigil. That is recorded as a gap rather than settled; what is missing is a spelling, and any spelling must keep the crossing greppable.

The other direction stays refused for a stronger reason: a raw object points at a value with no count to take a share of, so accepting one where a counted object is wanted would be inventing ownership.

An object cannot be erased a second time

trait Shape: Display puts Display‘s slots in a &Shape‘s table, and a [T: Display] bound is satisfied by the object — but a &Display is not, and the difference is worth being exact about. A bound asks what may be called through the value, and the table answers it. Forming an object asks what may be assembled from the value’s type, and a table is laid out from a type’s implementations, which an object has none of.

trait Shape: Display
    area(self) -> int

struct Rect
    w: int
    h: int
end Rect

impl Shape for Rect
    area(self) -> int = self.w * self.h

impl Display for Rect
    display(self, out: *Writer, fmt: FormatSpec) = display_pad("a rect".bytes, out, fmt)

var o: &Shape = Rect(3, 4)
var d: &Display = o

a &Shape has forgotten which type it holds, so there is nothing for a &sysl.Display to be built from

Display‘s members really are in that table — they are laid out inline, so that a required trait’s method stays the one indirect call the trait’s own methods are. What is missing is a name for that run of slots. This is the upcast flattening gives up, and it is the reason it is worth giving up: every call through a &Shape costs one indirection instead of two.

There is no way back to the type

An object cannot be asked what it forgot. There is no cast and no test, and the spelling a reader reaches for first is not one either — a type is not a pattern, so s is Rect reads Rect as an ordinary binding, which matches anything:

trait Shape
    area(self) -> int

struct Rect
    w: int
    h: int
end Rect

impl Shape for Rect
    area(self) -> int = self.w * self.h

var s: &Shape = Rect(2, 3)

if s is Rect then print("yes") else print("no")

this pattern matches every &Shape, so the test is always true — take the value apart with 'match', or bind it with 'var'

This is a decision, not an omission. A downcast is the one operation that makes erasure a lie: every other rule here says an object offers the trait’s members and nothing else, and a type test would say that it also secretly offers its identity, which is what the table pointer is and what the type deliberately stops promising. Languages that offer it need a whole parallel mechanism to do so, and that mechanism is the honest price rather than a small addition to this one.

The cost is real and worth writing down beside the decision. A program that wants to count the circles in a catalogue has to be told, so it declares a kind property every implementation answers with a constant — a hand-maintained copy of exactly the fact the object’s first word already is.

Reaching a trait’s members without a value

A trait may declare a member with no receiver — an associated function — reached through the type rather than through a value of one:

trait Zero
    zero() -> Self

impl Zero for int
    zero() -> int = 0

start[T: Zero]() -> T = T.zero()

var n: int = start()

print(n)

T.bits() inside a generic body, Self.bits() inside a member’s, and u32.bits() from anywhere are the same member reached through three spellings of its type.

A built-in may carry one. Through a bound the name is the parameter, which every type has whether or not it has one of its own — so impl Word for u32 may declare bits(), and impl Float for real declares the zero, the one, the epsilon, and the two values no literal spells. What stays refused is the case the rule was really about: a composed type has no name at all, so an impl for []int still refuses a member with no receiver.

It is static dispatch only, and nothing was added to keep it that way. Object safety already excludes a member with no receiver, because a table slot is selected by the receiver and there is nothing here to select with. A trait declaring one is usable as a bound and not as an object, exactly as one that mentions Self twice already is.

One gap the mechanism makes visible: a routine can be entirely about a type and mention it nowhere in its signature, and such a function cannot be called, because inference reads the binding and a call cannot write its type arguments. describe[T: Word]() -> string is well-formed and unreachable. Taking a value of T is the workaround.

Next: generics.

The time module

2026-08-16T01:26:07.924728867Z

sysl.time is arithmetic on dates and lengths of time. It is three files and seven types, and almost everything worth saying about it is a distinction the type system holds for you — a point on the timeline is not a length of one, and a reading on a wall clock is neither. Every library that blurs those has the same class of bug in it, and the blur is what the types here refuse.

It requires no capability: every name below is reachable on a target with no operating system.

import sysl.time.*

var launch = date_at(2026, 3, 8)
var meeting = datetime_at(2026, 3, 8, 9, 30, 0)

print(date_text(launch), weekday_name(weekday(launch)))
print(datetime_text(meeting))
print(day_of_year(launch), leap_year(2026))

2026-03-08 Sunday
2026-03-08 09:30
67 false

The two quantities

// A point on the timeline, counted from 1970-01-01T00:00:00Z.
struct Instant
    us: long

// A length of timeline, with no place on it.
struct Duration
    us: long

// How far a zone's wall clock is set from UTC, in whole minutes.
struct Offset
    minutes: int

Both are counts of microseconds, and that is the one representation choice worth arguing about. A long of nanoseconds runs out in 1678–2262 — close enough to today to look fine in every test and fail on a birth date. A long of microseconds reaches ±292,000 years. Nothing here needs to resolve a nanosecond, and a range that quietly ends is a worse defect than a precision that never begins.

Offset is minutes rather than hours because India is at +05:30 and Nepal at +05:45, and a library that assumes whole hours works everywhere its author has lived.

import sysl.time.*

var epoch = Instant(0i64)
var later = epoch + hours(50i64)

print(whole_days(since(later, epoch)), odd_hours(since(later, epoch)))
print(whole_hours(since(epoch, later)))
print(epoch < later, later == epoch + days(2i64) + hours(2i64))
print(whole_hours(-hours(3i64)), whole_hours(hours(3i64) * 4i64))

2 2
-50
true true
-3 12

Which operations exist is the whole design. An instant may be compared with an instant, subtracted from one, and moved by a duration. Two instants may not be added, because the sum of two points on a timeline is not a point on it — and asking for one says so:

import sysl.time.*

var a = Instant(0i64)
var b = Instant(1i64)

print(since(a + b, a))

'+' between sysl.time.Instant and sysl.time.Instant needs 'sysl.Add' — it implements 'sysl.Add[sysl.time.Duration]'

That diagnostic is exact about what went wrong: Instant does implement Add, at Duration, and this call asked for it at Instant.

The difference of two instants is the operator

import sysl.time.*

var a = Instant(0i64)
var b = a + hours(3i64)

print(whole_hours(b - a))
print(whole_hours(a - b))

3
-3

Two rows of Sub sit on Instant, and the type of the right operand is the whole of what selects between them. Subtracting a Duration lands further along the timeline and answers an Instant; subtracting an Instant measures across it and answers a Duration. An operator trait carries its result as Out as well as its operand as Rhs, which is what lets one type do both — the same mechanism Mul uses to give a vector space four products.

This section used to be this module’s report against the language: the most frequently written operation in any date-time library could not be spelled with its own operator, because Sub‘s result was fixed to the type on the left. That is what Out answered, and the gap it describes is closed.

since(later, earlier) is still here and is the same subtraction under a name that says which end is which — later - earlier is right and earlier - later is just as easy to write, as the second line above shows.

Reading a duration back

import sysl.time.*

var d = hours(50i64) + minutes(7i64) + seconds(30i64)

print(whole_days(d), odd_hours(d), odd_minutes(d), odd_seconds(d))
print(whole_hours(d), whole_minutes(d), whole_seconds(d))
print(seconds(90i64) == minutes(1i64) + seconds(30i64))
print(whole_minutes(days(1i64)))

2 2 7 30
50 3007 180450
true
1440

Two families, and the difference between them is the whole reason both exist. whole_hours is the duration in hours — fifty of them. odd_hours is the hours left over after the whole days — two. A caller stating a length to somebody who has to check it wants the first row; a caller formatting one wants the second, and getting them confused is how 2 days, 50 hours gets printed.

Both truncate toward zero, so a negative duration reads as a negative count of each part rather than borrowing across them.

days(1) is a length of exactly 24 hours, and it is not “a day”. A day that a zone’s clocks move through is 23 or 25 hours long, so a calendar day is not a fixed length of timeline at all. That question belongs to the civil types below, which is why plus_days is theirs and not a Duration‘s.

Below the second

millis and micros construct, whole_millis and whole_micros read back. The representation is microseconds, so those are the shortest lengths this module can name — and they are the two an embedded program reaches for, since a blink loop wants 120 milliseconds and seconds(1) is not it.

import sysl.time.*

var d = millis(120i64)

print(whole_millis(d), whole_micros(d), whole_seconds(d))
print(whole_micros(micros(7i64)))

120 120000 0
7

All three numbers on that first row are true of one length: it is a hundred and twenty milliseconds, and it is no seconds at all.

Scaling reads one way round only:

import sysl.time.*

var d = seconds(3i64)

print(whole_seconds(d * 3))
print(whole_seconds(2i64 * d))

'*' needs matching types, got long and sysl.time.Duration

d * 3 is what is written instead, and the count is an ordinary literal — a bare number beside a duration takes the long the one impl Mul names rather than the int a literal with nothing to take would fall back to. An operator’s implementation is written for the type on its left, and nothing may be written for long, so the commutativity a reader expects of multiplication is not something this module could have supplied.

Writing a duration number-first

Every unit is also a property on any integer, so a length can be written the way a datasheet writes one — the number, then the unit:

property	the constructor it mirrors
`5.us`	`micros(5)`
`5.ms`	`millis(5)`
`5.s`	`seconds(5)`
`5.minutes`	`minutes(5)`
`5.hours`	`hours(5)`
`5.days`	`days(5)`

import sysl.time.*

print(whole_millis(250.ms), whole_micros(250.ms))
print(whole_hours(2.hours + 90.minutes), odd_minutes(2.hours + 90.minutes))
print(whole_millis(250.ms * 4))

250 250000
3 30
1000

The short units are symbols and the long ones are words, which is a split about where each is used rather than a compromise. A timeout, a poll interval and a debounce are the sub-second end, they are written constantly, and ms is the spelling every datasheet already uses — sleep(5.ms) and join(ssid, pw, auth, 20.s) say at a glance what millis(5) and seconds(20) say a moment later. At the other end the number is small and the line is not dense, so 30.days costs nothing and says more than 30.d would.

There is deliberately no 5.min: it would sit beside sysl.math‘s min(a, b) and the type-level int::Min, meaning something different in each position.

The constructors stay, and the two spellings are not a duplication. A duration built from a computed value reads better as millis(n) than as n.millis, and the free functions are what most code that takes a length as an argument is written against.

The properties are one blanket implementation over the whole integer family, so a receiver narrower than the representation widens on the way in rather than overflowing at its own width:

import sysl.time.*

val n: u8 = 200

print(whole_micros(n.ms))

A selective import has to name the trait, which is the one place DurationUnits is written down by anybody using it — a member is reached through the trait that declares it, so importing millis does not bring ms along with it:

import sysl.time.{Duration, DurationUnits, whole_micros}

import sysl.time.* needs nothing said.

There is no matching set for Instant. A point on the timeline has no natural 5.<unit> — five of what, from when? — so naming one still means saying which epoch it is counted from.

The calendar

// Proleptic Gregorian — the Gregorian rules run backwards through the years before anybody
// agreed to them.
struct Civil
    year: int
    month: int
    day: int

// Days since 1970-01-01, signed.
struct LocalDate
    day: int

// Microseconds since midnight.
struct LocalTime
    us: long

struct LocalDateTime
    date: LocalDate
    time: LocalTime

A day number, not packed civil fields. Year, month, day, hour and minute as bit fields inside one word is the design most people reach for, and the arithmetic says no: packing to the nanosecond needs 30 bits for the nanosecond, 17 for the time of day and 9 for the day and month, which is 56 — leaving 8 bits of year, a range of ±128 years, which is not a calendar. A count fits more comfortably at the same width and costs nothing to compute with, because comparing, subtracting and adding a length of time are one instruction each on a count and an unpack-recompute-repack on packed fields. Only “what month is it” wants the fields, and that is the rare question — paid for where it is asked.

Proleptic Gregorian is a decision and not an oversight. The alternative is a calendar with a ten-day hole in it whose position depends on which country you ask.

import sysl.time.*

var d = date_at(2026, 3, 8)

print(year_of(d), month_of(d), day_of(d), month_name(month_of(d)))
print(day_of_year(d), weekday_name(weekday(d)))
print(days_in_month(2026, 2), days_in_month(2024, 2))
print(leap_year(2000), leap_year(1900), leap_year(2024))
print(date_at(1970, 1, 1).day, date_at(1969, 12, 31).day)
print(weekday_name(weekday(date_at(1970, 1, 1))))

2026 3 8 March
67 Sunday
28 29
true false true
0 -1
Thursday

Dates before the epoch are ordinary values rather than a special case. The day number is signed and Hinnant’s civil-from-days algorithm never branches on it — it shifts the epoch to the start of a 400-year era, after which every quantity is non-negative and each leap rule becomes one exact division. days_from_civil and civil_from_days are inverse over the whole int range, which is the property worth asserting rather than any particular date.

The weekday falls out of the same count: 1970-01-01 was a Thursday, so shifting by four puts Sunday at zero. Nothing here needs to know which day a week starts on.

Adding to a calendar

import sysl.time.*

print(date_text(plus_months(date_at(2026, 1, 31), 1)))
print(date_text(plus_months(date_at(2024, 1, 31), 1)))
print(date_text(plus_years(date_at(2024, 2, 29), 1)))
print(date_text(on_or_after(date_at(2026, 3, 8), Tuesday)))
print(datetime_text(plus_days(datetime_at(2026, 3, 8, 9, 30, 0), 7)))

2026-02-28
2024-02-29
2025-02-28
2026-03-10
2026-03-15 09:30

Months are added by the calendar rather than by counting days, and the day is clamped where the target month is shorter. The 31st of January plus one month is the 28th or the 29th of February, whichever that year has. Every library that offers this makes the choice, and clamping is the one that keeps “the last day of the month” landing on a last day. plus_years is plus_months by twelve, which is what makes the 29th of February behave on a non-leap year without a rule of its own.

plus_days on a wall clock reading is not adding a length of time to it. Seven days later is the same clock face seven rows down the calendar, whatever the timeline did in between; across a change of a zone’s clocks the two answers differ by an hour. Both are right — they answer different questions, which is why they are spelled differently. And why this is refused:

import sysl.time.*

var d = date_at(2026, 3, 8)

print(date_text(d + days(1i64)))

'+' needs matching types, got sysl.time.LocalDate and sysl.time.Duration

on_or_after is the first date on or after a given one falling on a given weekday, which is what “every Tuesday” means once a rule has been given a starting point.

Rendering

import sysl.time.*

var t = time_at(9, 30, 7)

print(date_at(2026, 3, 8))
print(time_text(t), time_text(time_at(9, 30, 0)), time_text(LocalTime(500000i64)))
print(datetime_at(2026, 3, 8, 9, 30, 0))
print(offset_text(Offset(330)), offset_text(Offset(-480)), offset_text(Offset(0)))

2026-03-08
09:30:07 09:30 00:00:00.500000
2026-03-08 09:30
+05:30 -08:00 Z

All five types implement Display, so a value goes straight into a print or an interpolation; the *_text functions are the same renderers reached by name, for a caller that wants the string.

Seconds appear only when there are any. A meeting at half past nine is written 09:30 by every human being who has ever written one down, and a renderer insisting on 09:30:00 is reporting its representation rather than its value. The microseconds appear on the same terms — and a renderer that showed a value to the second while dropping what is below it would be reporting something the value does not say.

Z for a zero offset is a spelling rather than a special case: ISO 8601 writes it that way, and parse_offset reads it back as zero.

Reading text back

// Why a parse refused, at the granularity a caller can act on.
enum TimeParseError
    BadShape(at: usize)
    OutOfRange(what: string)
    Trailing(at: usize)

import sysl.time.*

parse_date("2026-03-08") match
    Ok(d) -> print(d)
    Err(e) -> print("refused:", e)

parse_time("09:30") match
    Ok(t) -> print(t)
    Err(e) -> print("refused:", e)

parse_time("09:30:07.5") match
    Ok(t) -> print(t)
    Err(e) -> print("refused:", e)

parse_datetime("2026-03-08T09:30") match
    Ok(x) -> print(x)
    Err(e) -> print("refused:", e)

parse_datetime("2026-03-08 09:30:07") match
    Ok(x) -> print(x)
    Err(e) -> print("refused:", e)

parse_offset("+05:30") match
    Ok(o) -> print(o)
    Err(e) -> print("refused:", e)

2026-03-08
09:30
09:30:07.500000
2026-03-08 09:30
2026-03-08 09:30:07
+05:30

One format, and it is ISO 8601. Not a pattern language, not a locale, not a list of alternatives tried in turn — YYYY-MM-DD, HH:MM[:SS[.ffffff]], and the two joined by a space or a T. That is the format the renderers above produce, so the pair round-trips, and it is the format every machine-readable timestamp in the world is already written in. A pattern language is a bigger feature than this module and belongs above it.

Both join characters are read because both are written: ISO 8601 says T, and datetime_text writes a space because that is what a person reads.

A fraction of fewer than six digits means what it says — .5 is half a second, not five microseconds.

What a parse refuses

import sysl.time.*

parse_date("2026-02-30") match
    Ok(d) -> print(d)
    Err(e) -> print("refused:", e)

parse_date("2026-13-01") match
    Ok(d) -> print(d)
    Err(e) -> print("refused:", e)

parse_date("2026/03/08") match
    Ok(d) -> print(d)
    Err(e) -> print("refused:", e)

parse_date("2026-03-08T") match
    Ok(d) -> print(d)
    Err(e) -> print("refused:", e)

parse_time("24:00") match
    Ok(t) -> print(t)
    Err(e) -> print("refused:", e)

refused: day is out of range
refused: month is out of range
refused: not the expected shape at byte 4
refused: unexpected text at byte 10
refused: hour is out of range

A parse checks the calendar, not only the shape, and the first line is the whole reason to say so. 2026-02-30 is four digits, a dash, two digits, a dash and two digits — it is exactly the right shape and it is not a date. Without holding the day against the month’s real length, the civil conversion accepts it silently and hands back the 2nd of March, which is the failure mode a caller has no way to notice.

The three cases are separated by what a caller would do about them. A shape error is a message about the format; a range error is a message about the value; a trailing error usually means the text held something more that the caller meant to split off first. BadShape and Trailing carry a byte offset for the reason sysl.text‘s BadDigit carries one: a message naming where is worth writing and cannot be reconstructed afterwards.

A fixed offset, which is not a zone

import sysl.time.*

var t = Instant(1772548200000000i64)

print(at_offset(t, Offset(-300)))
print(at_offset(t, Offset(330)))
print(from_offset(at_offset(t, Offset(-300)), Offset(-300)) == t)
print(timestamp_text(t, Offset(-300)))
print(timestamp_text(t, Offset(0)))
print(timestamp_text(Instant(1772548200500000i64), Offset(-300)))

2026-03-03 09:30
2026-03-03 20:00
true
2026-03-03T09:30:00-05:00
2026-03-03T14:30:00Z
2026-03-03T09:30:00.500000-05:00

Both directions are total, and that is the whole difference between an offset and a zone. An offset is a number; a zone is a rule with a history. Ask a zone what instant a wall clock reading names and the honest answers are one, none and two — the hour a spring-forward deletes has no instant in it, and the hour an autumn-back repeats has two. Ask an offset and there is exactly one, always, which is why this pair is a pair of plain functions and a zone conversion could never be.

Most programs that handle timestamps need only this. A timestamp on a wire, in a log line or in a database column already carries the offset that was in force when it was written: the sender resolved the zone, and what arrived is the record of that decision. Reading one back needs no table, no update cadence and no filesystem — which is exactly what makes it the library’s business, where the zone is not.

The renderer is written for machines, and it is the odd one out

timestamp_text breaks two of this page’s own rules, on purpose. The seconds are present even at zero, where datetime_text drops them; the date and time are joined by a T rather than a space; and the offset is flush against the time.

That is RFC 3339, the profile of ISO 8601 that JSON APIs, logs and databases actually agree on, and it requires the seconds. The rule that a renderer should not report what a value does not say is the right rule for a person glancing at a meeting time and exactly the wrong one for a parser with a grammar — so the two renderers are two renderers. The fraction is still omitted when it is zero, because RFC 3339 makes that part optional and .000000 on every timestamp is six characters of noise on the wire.

import sysl.time.*

var t = Instant(1772548200000000i64)

print(parse_timestamp("2026-03-03T09:30:00-05:00").unwrap_or(Instant(0i64)) == t)
print(parse_timestamp("2026-03-03 09:30-05:00").unwrap_or(Instant(0i64)) == t)
print(parse_timestamp("2026-03-03T14:30:00Z").unwrap_or(Instant(0i64)) == t)
print(parse_timestamp("2026-03-03T20:00:00+05:30").unwrap_or(Instant(0i64)) == t)

true
true
true
true

The parser reads more shapes than the renderer writes. It takes the space as well as the T, and a time with no seconds as well as one with them, because what arrives was written by somebody else — while the renderer emits one form, because a wire format with options is a wire format everybody implements differently. Liberal in what it accepts, strict in what it sends.

All four of those lines name the same point on the timeline, which is the point: the offset is not decoration on the reading, it is what turns the reading into an instant.

An offset is not optional

import sysl.time.*

print(str(parse_timestamp("2026-03-03T09:30:00").unwrap_err()))
print(str(parse_timestamp("2026-03-03T09:30:00-25:00").unwrap_err()))
print(str(parse_timestamp("2026-03-03T09:30:00Z ").unwrap_err()))

not the expected shape at byte 19
offset hour is out of range
unexpected text at byte 20

A date and a time with no offset name a wall clock reading, not an instant, and parse_datetime is what reads one of those. Defaulting the missing offset to UTC would be inventing the fact the format exists to carry, and it is the single most common way a timestamp ends up hours wrong in a system that never notices.

Reading a clock — `sysl.posix.time`

Everything above is arithmetic, and arithmetic needs a value to start from. Obtaining one is asking the environment what time it is, so it is a module of its own — the same split sysl.rand and sysl.posix.rand make, and for the same mechanical reason: a capability requirement is module-wide, so a now() written beside Instant would take the whole calendar away from every freestanding program that only wanted to add two durations.

There are two clocks, and the return types are the distinction rather than a detail.

import sysl.posix.time.{now, monotonic}

// The wall clock: a point on the timeline, comparable with one taken on another machine.
print(now().us > 1577836800000000)

// The monotonic clock: a length of time from an origin nobody specifies.
var t0 = monotonic()
var n: long = 1

for i in 0..<200000
    n = n * 31 + long(i)

var took = monotonic() - t0

print(took.us > 0)
print(n != 0)

true
true
true

now answers an Instant — a point counted from 1970, which is the one to stamp something with. It is also the clock a person and an ntpd are both allowed to set, so two readings of it can differ by anything at all, including a negative amount.

monotonic answers a Duration, not an Instant, and that is the whole of the design. It is counted from an origin the module deliberately does not name — boot, usually — so a single reading means nothing and only the difference of two does. It cannot be set and never goes backwards, which is what makes it the one to measure with. Giving it a type that no calendar function accepts is what stops a measurement being mistaken for a timestamp:

import sysl.posix.time.monotonic
import sysl.time.instant_text

print(instant_text(monotonic()))

error: 't' of 'sysl.time.instant_text' is sysl.time.Instant, but sysl.time.Duration was given

Both require posix.

What a freestanding target does instead

Nothing in the library, and deliberately nothing shared with it. A board’s clock is a board’s decision: two boards carrying the same chip — so the same target — can count time from a different RTC, which is precisely the case a compile-time switch on the target cannot express. So an embedded environment supplies a module of its own with these two function names, in its own package, and a program picks its clock by which one it imports.

What that gives up, for now, is a program that compiles unchanged against both a host clock and a board’s. The shape that would buy it is a symbol declared in capability-free sysl.time that a host module and a board package alike link an implementation of — sysl.harness‘s attach one layer down — and it is not built, for want of a second thing that needs it. The names above are chosen so that adding it later moves no caller.

What is not here

The zone, as distinct from the offset above. A wall clock reading becomes an instant only once somebody says where the wall is, and answering that from a name — America/New_York rather than -05:00 — needs the IANA time zone database — a table that changes several times a year, which a standard library either ships and lets go stale or reads from the host and thereby needs a filesystem. Both are decisions with costs, and neither belongs in a module whose whole claim is that it is arithmetic. The date and time guide builds a fixed-offset zone over this module and shows what the real thing would take.

wall_us and wall_of are the seam a zone conversion starts from: they read a LocalDateTime as a single count measured from the same origin as an Instant, which is what the count would be if the offset happened to be zero.

The clock, in this module. There is no sysl.time.now(), because reading one is a capability rather than arithmetic — clock_gettime is a call into the environment, and this module has no requires line. An Instant is a value a freestanding target can compute with; where it comes from is the caller’s to say, and on a host the answer is sysl.posix.time above.

Next: sysl.sync — atomics and the spinlock, which require nothing at all.

sysl.posix.threads

2026-08-16T01:26:07.924728867Z

sysl.posix.threads is where the capability lands. Everything on the sysl.sync page is reachable from a module that has given up its allocator and its operating system; nothing here is, because creating a thread needs a scheduler underneath it.

@no_posix

import sysl.sync.*
import sysl.posix.threads.spawn

var a = Atomic(0)

print(a.load())

this reaches 'sysl.posix.threads', which requires 'posix', and this module declared 'no posix' — an environment capability gates which modules exist, so a module that gave one up may not reach one that needs it

Note where that lands: at the import, not at the call. A capability a module has given up decides which modules exist for it, so a program that cannot spawn is a program whose author never sees the name — and the sysl.sync import on the line above is untouched, which is the split working exactly as it is meant to.

The module declares one requirement, and the namespace it sits in says the same thing twice over:

module sysl.posix.threads
@requires(posix)

What is here is pthreads, which is the whole claim and the reason the module lives under sysl.posix beside sysl.posix.tty and sysl.posix.rand. A module in that namespace is one a freestanding target does not get, and the path is enough to know it without opening the file.

There was a fourth capability, threads, and it was removed rather than renamed. It gated this one module, and it read as a claim that the compiler tracks whether a scheduler exists — which it does not, and which nothing in the library was gated on. A board running FreeRTOS or Zephyr has threads and no POSIX: it does not reach this module, and it binds its own kernel as a package, because no capability could have made pthread_create appear on it. So @no_threads is now an unknown capability, and the three that remain are heap, os and posix.

name	what it is
`spawn(body, arg)`	starts a thread, answering `Option[Thread]`
`Thread.join`	waits for one, answering whether it waited
`current()`	the calling thread’s own handle
`yield_now()`	offers the processor away — a hint, not a wait
`Mutex[T]`	mutual exclusion that owns what it protects

`spawn` takes an address, not a callable

import sysl.posix.threads.*

struct Job
    input: i32
    output: i32
end Job

square(j: *Job)
    j.output = j.input * j.input

var job = Job(12, 0)
var t = spawn(&square, &job).unwrap()

t.join()

print(job.input, job.output)

12 144

&square is the address of a named function, and the parameter’s type is *extern(*T) -> unit — C’s own shape, because pthread_create is underneath. A closure will not do, and the refusal is worth seeing in both of the ways a reader will hit it. Written bare, the argument has nothing to infer its parameter type from, because T is what is being inferred:

import sysl.sync.*
import sysl.posix.threads.*

var counter = Atomic(0)
var c = spawn(a -> a.add(1), &counter)

print(c.is_some())

'a' has no type here — nothing says what this closure takes, so write it

Write the type in and the real mismatch surfaces:

import sysl.sync.*
import sysl.posix.threads.*

var counter = Atomic(0)
var c = spawn((a: *Atomic[i32]) -> a.add(1), &counter)

print(c.is_some())

'body' of 'sysl.posix.threads.spawn' is *extern(*sysl.sync.Atomic[int]) -> unit, but a closure was given

Two reasons, and neither is a limitation waiting to be lifted. A closure would have to be boxed for the new thread to reach it, which needs an allocator this module could otherwise do without; and its captures would be values crossing a domain boundary through a box whose shape says nothing about what is in it. The address of a named function has neither problem, and what travels beside it is an ordinary parameter — which is what lets the crossing rule be asked at all.

A body with nothing to read is passed `null`

spawn is generic in what the body reads, so T is inferred from the body and the ptr_cast to C’s shape happens once, inside. A body with nothing of its own writes null, and the type it would otherwise have had to invent is one the body’s own signature already gave:

import sysl.posix.threads.*

quiet(state: *int)
    print("nothing to read")

spawn(&quiet, null).unwrap().join()

nothing to read

null has no type of its own, so at a parameter still being solved it is set aside until the arguments that have one are read — here the &quiet, whose *extern(*int) -> unit says T is int. It is refused only where nothing says: a call with no other argument to read is an error asking for the type rather than a guess.

`join` does not carry the result back

It answers a bool — whether it waited — and nothing else. That is the crossing rule rather than an oversight: a result coming out of another domain is a value crossing a boundary, which is what a channel is for, and the channel is not written. So a body that has something to say writes it through the address it was given, which is what the Job above does.

The Thread value is a handle rather than the thread. Copying one copies the handle, and joining either copy joins the one thread; joining twice is undefined in POSIX and is not checked here, for the same reason SpinLock.unlock checks nothing — the word it would take to notice is paid by every correct program. The id field is public so that a program can hand it to a POSIX call this module does not wrap, such as pthread_detach or a scheduling parameter, since the alternative is a wrapper per call.

The pointer is the sharing. Two threads reading and writing what is at that address is a data race unless something orders them, and the two things that order them are on the sysl.sync page.

What may be at that address

spawn is declared @crossing(arg), which is how a facility says a parameter hands a value to another concurrency domain (memory). It is why the state a thread is given is checked rather than taken on trust: a raw pointer carries no refcount of its own, and the annotation is what asks the compiler to look through it at the object that actually crossed.

import sysl.posix.threads.*

struct Cell
    n: int
end Cell

struct State
    cell: &Cell
end State

look(s: *State)
    print(s.cell.n)

var c: &Cell = Cell(1)
var st = State(c)

print(spawn(&look, &st).is_some())

what 'arg' of 'sysl.posix.threads.spawn' points at reaches another concurrency domain, so every count inside it has to be atomic

A plain &Cell has a non-atomic count, so two threads retaining it is exactly the race the model exists to prevent — and until the annotation existed, this program compiled and ran. Writing &sync Cell in the field and at the allocation is the whole fix: the count becomes atomic, and the same program is accepted.

Nothing here is special to this module. A package binding FreeRTOS or Zephyr writes the same line above the wrapper it already has, and gets the same refusal at its own callers’ calls.

import sysl.sync.*
import sysl.posix.threads.*

bump(a: *Atomic[i32])
    for i in 0..<10000
        a.add(1)

var counter = Atomic(0)
var t1 = spawn(&bump, &counter).unwrap()
var t2 = spawn(&bump, &counter).unwrap()
var j1 = t1.join()
var j2 = t2.join()

print(j1, j2)
print(counter.load())

true true
20000

A SpinLock works across real threads exactly as it does in the single-threaded program on the other page, and this is where its “guards nothing by construction” becomes concrete — the lock is a field beside the data, and remembering that total is what guard guards is the programmer’s job:

import sysl.sync.*
import sysl.posix.threads.*

struct Shared
    guard: SpinLock
    total: i32
end Shared

add_up(s: *Shared)
    for i in 0..<10000
        s.guard.lock()
        s.total = s.total + 1
        s.guard.unlock()

var sh = Shared(SpinLock(0), 0)
var s1 = spawn(&add_up, &sh).unwrap()
var s2 = spawn(&add_up, &sh).unwrap()

s1.join()
s2.join()

print(sh.total)

Take the atomic away and it is a race

import sysl.posix.threads.*

racy(p: *i32)
    for i in 0..<100000
        *p = *p + 1

var n = 0
var r1 = spawn(&racy, &n).unwrap()
var r2 = spawn(&racy, &n).unwrap()

r1.join()
r2.join()

print(n)

That program is a data race by definition: two threads, one word, no synchronization. On the run that produced this page it printed 200000 — the right answer. It is not on the site as a checked program for exactly that reason, and the reason is the lesson: a race that gives the right answer on the machine you tested it on is why the model is built out of things you can grep for rather than things you can test for. *T is one of the two spellings that share on purpose, and it is the unchecked one.

`Mutex[T]`

Mutex[T] owns what it protects, which is the whole difference against SpinLock. Both of its fields are private, so there is no way to reach the value that does not go through lock or try_lock:

import sysl.posix.threads.*

var m = Mutex.new(7)

print(m.value)

field 'value' of 'sysl.posix.threads.Mutex' is private to 'library/sysl/posix/threads/mutex.sysl', the file that declares it

Private is the entirety of what “owns” means here. With value public, reading it would be an unsynchronized read of the very thing the type exists to synchronize, and the type would be a spinlock with a suggestion attached.

The private field does a second job: it puts the positional constructor out of reach, so Mutex.new is the only way in and there is no way to build one that starts out held.

import sysl.posix.threads.*

var built = Mutex(0, 5)
var p = built.lock()

print(*p)

the constructor names every field of 'sysl.posix.threads.Mutex' in order, and 'held' is private to 'library/sysl/posix/threads/mutex.sysl', the file that declares it — build it through an associated function of its own

`lock` answers an address, and releasing is written

Rust returns a guard whose destruction releases the lock. sysl has a destructor now and deliberately does not use it here: a destructor runs for a value held behind a &T, so a guard would mean a heap allocation per lock — on the one path where the whole point is to hold a lock for as few instructions as possible. defer m.unlock() is the idiom, the same one sysl.fs uses for close, and for the same reason.

import sysl.posix.threads.*

inc(m: *Mutex[i32])
    for i in 0..<10000
        var p = m.lock()

        defer m.unlock()
        *p = *p + 1

var mx = Mutex.new(0)
var a1 = spawn(&inc, &mx).unwrap()
var a2 = spawn(&inc, &mx).unwrap()

a1.join()
a2.join()

var mp = mx.lock()

print(*mp)

mx.unlock()

defer is block-scoped, not function-scoped, so the defer inside that loop body runs at the end of each iteration — which is what makes it usable for a lock taken in a loop at all, and is the point at which sysl’s defer and Go’s stop agreeing.

The mistake this shape cannot prevent is holding on to the address past the unlock. Nothing takes it away from you, and nothing will tell you.

try_lock never waits and answers an Option[*T], which is the ordinary shape for “it might not have worked”:

import sysl.posix.threads.*

var q = Mutex.new(5)
var g = q.try_lock()

print(g.is_some(), *g.unwrap())

var again = q.try_lock()

print(again.is_some())

q.unlock()

var third = q.try_lock()

print(third.is_some())

q.unlock()

true 5
false
true

Neither lock nor try_lock takes an Ordering, and neither does unlock, because a lock’s orderings are fixed by what a lock means. The exchange that takes it is an acquire and the store that frees it is a release, and that pairing is what publishes everything the holder wrote to whichever thread takes the lock next. It is the whole of what makes the data safe to touch.

It is not built on `pthread_mutex_t`

The reason is a build property rather than a preference, and it is worth spelling out because it is the same argument that keeps the standard library buildable for targets nobody has tried yet.

A caller-allocated opaque C type is one of the three things the compilation model names as reachable from C and from nothing else. Its size lives in a header, and it differs both between platforms and between two libcs on the same platform — 64 bytes on Darwin, 40 under glibc on x86-64, 48 on aarch64, 40 again under musl. #if can ask which operating system this is, but not which libc. So a transcribed byte count would compile everywhere and be checked nowhere, which is precisely the failure that section is about.

The way to read a header is C, and the standard library deliberately includes none: it reaches libc by symbol alone, which is what lets it go on building for any target the toolchain can lower for.

private[sysl] extern "pthread_create" c_pthread_create(
    t: *usize,
    attr: *u8,
    body: *extern(*u8) -> *u8,
    arg: *u8,
) -> int
private[sysl] extern "pthread_join" c_pthread_join(t: usize, result: **u8) -> int

Every one of those is a scalar handle or an address. A pthread_t is one word on both platforms this builds for — a pointer on Darwin, an unsigned long under glibc — and usize is the spelling that is both. Transcribing that is safe in a way transcribing a layout is not, and it is the only transcription in the module.

So Mutex[T] is three atomic operations and a yield: an acquiring exchange to take it, a relaxed load between attempts, and a releasing store to free it. What that costs is a context switch per contended attempt, where a futex would cost none. A futex-backed mutex is what a binding library carrying its own C shim would add; it is not something the standard library can reach.

The spin is not SpinLock‘s, either. A failed exchange gives the processor up rather than turning round again, so a waiter cannot starve the holder the way a pure spin can on one core, and the hold may be as long as it likes. What it does not do is sleep: there is no wait queue.

`yield_now` and `current`

import sysl.posix.threads.*

print(yield_now())

var me = current()
var mine = current()

print(me.id == mine.id)

true
true

yield_now is a hint, not a wait. A thread that yields is still runnable and may be handed the processor straight back; what it is for is the spin in Mutex.lock, where the thread holding the lock may not be running at all and nothing else in the loop would make it so. It answers whether the system took the offer.

current() is what a body compares against to learn that it is not the thread that spawned it.

There is no `async`

No async, no await, and no task runtime — in the language or in this module. Threads are what sysl offers for doing two things at once, and this page is all of it.

It is deferred rather than refused, and the difference is worth knowing if you are deciding whether to build on threads something you would rather have written as tasks. The shape it would take here is settled: futures compiled to state machines, sized at compile time, with no allocation inherent in a future and the executor an ordinary library. What stands between that and being built is a schedule. Nothing on this page changes when it arrives — a thread will still be a thread.

What you get in the meantime is worth having, and both halves of it are things an await costs a language that has one. sysl has no actor reentrancy hazard — the trap where an actor’s state changes across an await — because there is no await-based interleaving. And blocking is honest: a thread that waits is a thread that waits, with no cooperative-scheduling model to reason about on top of it, and no way for one stalled task to stall nine others you never looked at.

How strong this is

Honestly weaker than Rust or Swift 6, and worth saying plainly rather than implying a guarantee the language cannot keep.

	checked	not checked
crossing a domain	what a `@crossing` parameter is handed, structurally	a boundary nobody marked — no annotation, no question
refcount races	what a `&sync T` may hold, structurally	—
mutating shared state	—	use a `Mutex`; nothing enforces it
the kernel tier	—	`*T`, spinlocks, orderings — as in C

This module is where the first row stops being theoretical. spawn is declared @crossing(arg), so the pointer it takes is looked through and a state whose counts are not all atomic is refused where the call is written. That is also why this API takes an address rather than a value: a spawn taking a T would be claiming the copying half of the crossing rule, which belongs to a channel and is not written.

The unchecked half of that row is where the annotation is absent. A facility with no @crossing on it is a boundary the compiler was never told about, and there is no way to guess one: a scheduler in a package looks like any other function until somebody writes the line.

So a data race requires you to have shared something on purpose. Sharing takes &sync or *T, both of which are greppable and neither of which is what an ordinary value is. What remains permanent is the race you can write by putting a mutable field in a &sync T, because it is the cost of not having a borrow checker.

Next: sysl.args — how argc and argv become a []string, and the two layers that read options out of them.

The text module

2026-08-16T01:26:07.924728867Z

A string is an immutable, validated []u8, and the language gives it a few things directly: its length, its bytes, a boundary-checked substring, and a cursor over its characters. Everything a program then does with text — validate, classify, search, trim, split, join, build, parse — is sysl.text, and none of it is a language feature.

One piece of the module is reached without being named. s.chars is a member the compiler provides, and it calls this module’s chars_of by key rather than by resolving the word — so walking characters costs a program nothing, not even an import line:

var s = "héllo"

print(s.len, s.bytes.len)

for c in s.chars
    prints(str(c))
    prints(".")

prints("\n")
print(s[0..<1], s.bytes[1])

6 6
h.é.l.l.o.
h 195

Six bytes and five characters, and s.bytes[1] is 195 — the first half of é. That is the whole of what this module is about: the two counts are different numbers, and every operation here is explicit about which one it works in.

What is in it

The module is seven files, and the boundaries between them are arguments rather than filing:

file	holds	why it is a file
`utf8.sysl`	`from_utf8`, `from_utf8_lossy`, `Utf8Error`, `char_from_u32`, `from_cstring`, `is_char_boundary`, `Chars`, `CharIndices`	the validity seam — what turns bytes into text
`ascii.sysl`	trait `Ascii`, implemented for `u8` and `char`	classification, named for the range it answers over
`find.sysl`	trait `Search`, implemented for `string` and `[]const u8`	everything that makes no new bytes
`edit.sysl`	`split`, `fields`, `join`, `repeat`, `replace_all`, `to_upper`, `to_lower`	everything that does — so it needs an allocator
`parse.sysl`	`ParseError`, `parse_bool`/`int`/`long`/`uint`/`ulong`/`real` and the `_base` forms	the direction `str(x)` does not go
`build.sysl`	`StrBuilder`, `CString`, `str_builder_with_capacity`	gathering text, and the copy C reads
`width.sysl`	`char_columns`, `columns`	data, not algorithm — 499 ranges of the Unicode Character Database

Two of those rows carry the module’s whole design, and they are worth reading before anything else.

Ascii and Search are each written once over two receivers. sysl had no overloading when they were written, so the obvious shape was two sets of functions — is_digit for a byte and some suffixed twin for a character; a search over string and another over []u8. The older sysl did exactly that and paid 1,630 lines of near-identical code for it. A trait says “either of these” instead: each implementation supplies two or three members and every operation is a default written once against them.

The find/edit split is the allocator, not taxonomy. A search answers with an offset or a bool; a trim answers with a view of what it was given. Neither makes a byte that was not already there, so all of find.sysl is reachable under no alloc — and a program that only searches never links an allocator on account of a join it does not call. That is demonstrated below, because the compiler enforces it.

Characters and bytes

operation	spelling	cost
byte length	`s.len`	O(1)
byte at an index	`s[i] -> u8`	O(1), bounds-checked
substring	`s[a..b] -> string`	O(1), shares; bounds-checked and boundary-checked
the bytes	`s.bytes -> []const u8`	O(1) view
the characters	`s.chars -> Chars`	O(1) per step
concatenation	`a + b`	O(n), allocates

Every row but one yields a value or a view. s.chars yields a sequence, and it has to: the decoding is what makes the scalar values, so there is nothing a string could hand out the way a container hands out a view of its storage. So Chars carries a position and answers “the next one”, which is the whole of the iteration protocol.

The cursor validates nothing, and does not need to — a string is well-formed UTF-8 by construction, so the decoder reads the width off the lead byte and takes the continuation bytes as given. A Chars built over a []u8 that is not a string is an ordinary struct over ordinary bytes: it gives the garbage-in answer and never reads past the end, since every byte it takes goes through the slice’s own bounds check.

Driving a cursor by hand

A for walks a copy of a cursor, so a loop over s.chars cannot be asked afterwards where it got to. A program that needs to know drives the cursor itself, and Chars offers three things by value for exactly that — offset, peek and count, none of which consume anything:

import sysl.text.{char_indices, is_char_boundary}

var s = "héllo"

print(s.len, s.chars.count())
print(s.chars.peek().unwrap())

var cur = s.chars

print(cur.offset)
print(cur.next().unwrap())
print(cur.offset, cur.count())

for pair in char_indices(s.bytes)
    print(pair.0, pair.1)

print(is_char_boundary(s.bytes[1]), is_char_boundary(s.bytes[2]))
print(s[1..<3])

6 5
h
0
h
1 4
0 h
1 é
3 l
4 l
5 o
true false
é

Read the char_indices column downward: 0, 1, 3, 4, 5. The jump from 1 to 3 is é being two bytes wide, and it is the entire reason this walk exists. The offset reported is each character’s first byte, so a slice built from two of them lands on boundaries by construction — which matters, because s[a..b] traps on a mid-codepoint bound rather than handing back something that is not text.

is_char_boundary asks the same question of a single byte: one mask and one comparison, since a continuation byte is the only one matching 10xxxxxx. It is what a program walking backwards, or snapping an arbitrary offset onto a boundary, would otherwise write inline.

What that shape is for

This is a lexer, and it is why offset and peek are on the cursor at all — without them a scanner has to index bytes by hand and decode a second time:

import sysl.text.Ascii

scan(src: string)
    var cur = src.chars

    while cur.peek().is_some()
        var start = cur.offset
        var c = cur.peek().unwrap()

        if c.is_alpha()
            while cur.peek().unwrap_or(' ').is_alnum()
                cur.next()

            print("word  ", src[start..<cur.offset])
        elif c.is_digit()
            while cur.peek().unwrap_or(' ').is_digit()
                cur.next()

            print("number", src[start..<cur.offset])
        else
            cur.next()
end scan

scan("let x1 = 42")

var s = "héllo"
var walked = 0

for c in s.chars
    walked += 1

print("after the loop the cursor is untouched:", s.chars.offset, walked)

word   let
word   x1
number 42
after the loop the cursor is untouched: 0 5

src[start..<cur.offset] is an O(1) substring sharing the source’s bytes — a token costs a retain and no copy.

Validating bytes into text

from_utf8(b: []const u8) -> Result[string, Utf8Error]
from_utf8_lossy(b: []const u8) -> string
from_cstring(p: *u8) -> Result[string, Utf8Error]
char_from_u32(u: u32) -> Option[char]

struct Utf8Error
    offset: usize
    truncated: bool

The compiler supplies exactly one primitive here — from_utf8_unchecked, which takes a []u8 as a string with nothing looked at — and the validator on top of it is ordinary sysl. Nothing in a byte-by-byte scan needs anything the language does not already offer. What no sysl body can write is the last line, because every safe route to a string already carries the guarantee.

The validator is Unicode’s well-formedness table rather than a decode-then-range-check, and the difference shows in what it costs to be right: in the table the lead byte fixes the legal range of the byte after it — E0 demands A0..BF, ED only 80..9F, F0 demands 90..BF, F4 only 80..8F — so an overlong encoding, a surrogate, and a value past 10FFFF are all rejected at the second byte by the same test, before any code point is assembled.

Utf8Error carries the offset and one distinction beyond it:

import sysl.text.from_utf8

var good: [3]u8 = [104, 195, 169]
var cut: [2]u8 = [104, 195]
var surr: [3]u8 = [237, 160, 128]

from_utf8(good) match
    Ok(t) -> print("ok", t)
    Err(e) -> print("refused", e.offset, e.truncated)

from_utf8(cut) match
    Ok(t) -> print("ok", t)
    Err(e) -> print("refused", e.offset, e.truncated)

from_utf8(surr) match
    Ok(t) -> print("ok", t)
    Err(e) -> print("refused", e.offset, e.truncated)

ok hé
refused 1 true
refused 0 false

truncated is the only thing a caller can act on differently. The second input is h followed by a lead byte with its continuation missing — more bytes would fix it, which is exactly the case a program reading a stream in chunks is in. The third is a surrogate: no continuation could rescue it, and reading further is reading past an error. A taxonomy of fault names would give a caller more to match on and nothing more to do.

The bytes are copied, not viewed, which is why this entry requires an allocator. A []u8 is writable and a string is not, so sharing would let a later write through the slice change a value that had already been checked. Copying is what makes the validation mean anything afterwards.

char_from_u32 is the same shape one scalar down — the fallible half of u32 -> char, refusing a surrogate or anything past 10FFFF, where the plain char(u) conversion traps instead. It is a free function because a scalar has no member namespace to hang a char.try on.

When a refusal is the wrong answer: `from_utf8_lossy`

A Result is right when the bytes ought to be valid, and wrong when they carry whatever was sent. Text off a wire, out of a serial port, or in a file somebody else wrote is the second case, and a program reading it usually wants something it can show a person rather than a fault it can only report. from_utf8_lossy keeps what is well-formed and puts U+FFFD where the rest was.

import sysl.text.from_utf8_lossy

var cut: [3]u8 = [97, 226, 130]
var stray: [3]u8 = [97, 255, 98]

print(from_utf8_lossy("héllo".bytes))
print(from_utf8_lossy(cut))
print(from_utf8_lossy(stray))

héllo
a�
a�b

One replacement per maximal ill-formed subsequence, not one per byte. The second input is a followed by two thirds of a euro sign: those two bytes are one truncated character, so they become one U+FFFD and not two. That is what Unicode recommends, and it is the part a hand-rolled skip-a-byte-and-retry loop gets wrong.

It walks the same table from_utf8 does, so the two cannot come to disagree about which bytes are text — they differ only in what they do about the ones that are not. Valid input costs a single walk and no allocation at all.

Classification: `Ascii`

trait Ascii
    code(self) -> u32
    to_upper(self) -> Self
    to_lower(self) -> Self

    is_ascii(self) -> bool
    is_digit(self) -> bool
    is_upper(self) -> bool
    is_lower(self) -> bool
    is_alpha(self) -> bool
    is_alnum(self) -> bool
    is_space(self) -> bool
    is_hex_digit(self) -> bool
    is_punct(self) -> bool
    is_print(self) -> bool
    is_control(self) -> bool
    digit_value(self, base: int) -> Option[int]

Three members are required; every classifier below the line is a default written once over code(). Adding one is a line in the trait and nothing in either implementation.

The name is the promise. This answers over the ASCII range and nothing else — a value at or above 128 answers false to every question rather than being guessed at. That is what is_ascii is for: it distinguishes “not a letter” from “not a letter I can see”. Real Unicode classification needs property tables, which must not be in a kernel, so it belongs to a library above this one.

The older sysl called the equivalent module unicode and classified nothing above 127, so every caller read a promise the code did not keep. This name exists to avoid that.

import sysl.text.Ascii

print(u8('7').is_digit(), u8('7').is_alpha(), u8('7').digit_value(10).unwrap())
print(u8('f').digit_value(16).unwrap(), u8('z').digit_value(16).is_none())
print('é'.is_ascii(), 'é'.is_alpha(), 'é'.to_upper())
print('A'.to_lower(), u8('a').to_upper())

true false 7
15 true
false false é
a 65

Two things in that last line. 'é'.to_upper() is é — both conversions are total, leaving anything that is not a letter of the other case exactly as they found it, which is what makes mapping one over arbitrary text safe rather than merely defined. And u8('a').to_upper() prints 65, not A: it answers in the receiver’s own type, and a u8 renders as a number. That is the only reason the two conversions are per-implementation at all — the arithmetic is identical.

digit_value(base) is here rather than beside the parsers because it is a question about a character, and because parsing wants exactly this and nothing else from a digit. Letters count from ten in either case, so base 16 and base 36 need no separate spelling, and a base outside 2..36 answers None for every input rather than trapping — the caller that passed it is the one that can say what to do about it.

Searching and trimming: `Search`

trait Search
    view(self) -> []const u8
    slice(self, lo: usize, hi: usize) -> Self

    is_empty(self) -> bool
    starts_with(self, prefix: Self) -> bool
    ends_with(self, suffix: Self) -> bool
    index_of(self, needle: Self) -> Option[usize]
    last_index_of(self, needle: Self) -> Option[usize]
    index_of_byte(self, b: u8) -> Option[usize]
    last_index_of_byte(self, b: u8) -> Option[usize]
    contains(self, needle: Self) -> bool
    has_byte(self, b: u8) -> bool
    count_of(self, needle: Self) -> usize

    trim(self) -> Self
    trim_start(self) -> Self
    trim_end(self) -> Self
    trim_matches(self, cutset: Self) -> Self
    trim_start_matches(self, cutset: Self) -> Self
    trim_end_matches(self, cutset: Self) -> Self

Two required members carry all of it. view is the whole of what a string and a []const u8 disagree about — the bytes to look at. slice is what lets a trim answer with a view rather than a copy, and it is required rather than defaulted because a default cannot build a Self.

There is deliberately no len: both implementations already have one the compiler provides, and a trait member of that name would hide it rather than agree with it.

import sysl.text.Search

var s = "  hello, world  "

print(s.trim())
print(s.contains("world"), s.index_of("world").unwrap())
print("aaa".count_of("aa"), "--x--".trim_matches("-"))
print("path/to/file.txt".last_index_of_byte(u8('/')).unwrap())
print("// comment".starts_with("//"), "file.txt".ends_with(".txt"))

hello, world
true 9
1 x
7
true true

"aaa" contains one "aa", not two. Counting is non-overlapping and left to right, which is the same rule replace_all substitutes by — so the number count_of reports and the number of replacements made always agree.

index_of answers with an Option rather than the older sysl’s -1, because a sentinel is a value the type calls ordinary and every caller has to remember to check.

A byte-level search over UTF-8 is correct, not a shortcut

UTF-8 is self-synchronizing: a continuation byte is distinguishable from a lead byte, so a well-formed needle cannot match starting anywhere but at a character boundary. So these ignore encoding entirely, and an offset one of them returns is always safe to slice at.

Trimming whitespace is safe from the other side of the same fact — every whitespace byte is ASCII, so every byte removed is a whole character and every bound left behind is one the receiver already had.

A cutset is a set of bytes, and that is the group’s one caveat. A non-ASCII character in a cutset is its bytes and not itself, so such a cutset can cut a character in half — which for a string is a trap rather than a wrong answer. The whitespace trims are the ones without a caveat.

The second implementation, and what it is for

Search is implemented for []const u8 as well, and that receiver is the point of the trait: bytes that are not text, or not yet — what a program has read off a socket or a file before it knows whether it is UTF-8.

import sysl.text.Search

var raw: [3]u8 = [104, 105, 33]
var needle: [2]u8 = [105, 33]

print(raw[..].contains(needle), raw[..].index_of(needle).unwrap())
print(raw[..].starts_with([104u8]), raw[..].is_empty())
print("  hello  ".bytes.trim().len)

true 1
true false
5

raw[..] is a []u8 — writable — and the implementation is written for []const u8. It resolves because a []T is accepted wherever a []const T is wanted: the read-only bit is part of one type rather than making two, and a receiver is such a place. The reverse does not hold, and must not: a member written for a []T may write through its receiver.

The half that allocates

split, fields, join, repeat, replace_all, to_upper and to_lower are free functions over string, not members of Search. A trait default cannot write them — it would have to build a Self out of new bytes, and there is no way for a trait to say how. That is the honest boundary of the write-it-once trick, and it falls exactly where the allocator does.

import sysl.text.{split, fields, join, repeat, replace_all, to_upper, to_lower}

var parts = split("a,b,,c", ",")
var words = ["x", "y", "z"]

print(parts.len, parts[0], parts[2] == "", parts[3])
print(fields("  one   two  ").len)
print(join(words, "-"))
print(repeat("ab", 3), repeat("ab", 0) == "")
print(replace_all("aaa", "aa", "b"))
print(to_upper("héllo"), to_lower("HÉLLO"))

4 a true c
2
x-y-z
ababab true
ba
HéLLO hÉllo

to_upper("héllo") is HéLLO. The é is untouched, which is the ASCII promise made visible rather than merely stated. These walk characters rather than bytes and go through push_char, so every way into the builder still carries the UTF-8 guarantee and no unchecked primitive is named — and it works because Ascii for char is total, so a character outside the range is re-encoded to exactly the bytes it arrived as. A byte map would be the faster loop and would need a raw-byte way into a builder, which is the one thing the builder deliberately does not offer.

split drops nothing and fields drops whitespace. Adjacent separators yield an empty piece between them and a separator at either end yields an empty piece outside it, so "a,b,,c" is four pieces of which the third is empty. fields is not split on a space: a run of whitespace separates two fields rather than producing empty ones between them, which is what reading a line of columns wants.

What splitting hands back are views. A piece shares the bytes of the string it came from and costs a retain, so split allocates the vector and not the text. The older sysl copied every piece, for want of an O(1) substring to hand out — this is where the representation pays off most visibly.

Two edges are deliberate and share a reason: an empty separator yields the whole string as one piece, and an empty pattern in replace_all matches nowhere. The byte-level reading of either would cut multi-byte characters apart, and the character-level reading is what s.chars already is.

The split is enforced, not documented

A module that has given up its allocator can search and trim all it likes:

@no_alloc

import sysl.text.Search

var line = "  key = value  "

print(line.trim())
print(line.index_of("=").unwrap(), line.trim().starts_with("key"))
print(line.trim_matches(" ").len)

key = value
6 true
11

…and reaching into the other file is refused at compile time, naming the allocating call it found:

@no_alloc

import sysl.text.join

var words = ["a", "b"]

print(join(words, "-"))

this reaches 'sysl.buf.Buf.extend.byte', which makes heap storage, and this module declared '@no_alloc'

That diagnostic names sysl.buf, three calls down, because alloc is checked on what a module calls rather than on which modules it depends on — the standard library is exactly why. Inferring it per module would put the whole of sysl.text on one side of a line that runs through the middle of it.

Gathering text: `StrBuilder`

a + b allocates a fresh buffer every time, so gathering n pieces that way copies everything it has so far on every step. A builder keeps one growable buffer and pays for each piece once.

import sysl.text.str_builder

var b = str_builder()

b.push("n=")
b.push_int(42)
b.push(" ok=")
b.push_bool(true)
b.push(" x=")
b.push_real(1.5)
b.push_char('!')

print(b.len)
print(b.finish())

19
n=42 ok=true x=1.5!

Every way in carries the guarantee. push takes a string, push_char takes a char, and the four renderers take a number or a bool — UTF-8 is closed under appending any of them, so finish hands back a plain string rather than something a caller has to validate.

That is why a builder is not a Writer. A public write taking a []u8 would be from_utf8_unchecked with a longer name and none of its greppability. The two shapes look interchangeable and are not: a Writer is a sink for bytes and a builder is a producer of text.

push_int, push_uint, push_real and push_bool exist so that gathering a number costs no allocation. The spelling without them is push(str(n)), which builds a whole reference-counted string — a heap object with a refcount and a deallocation hook — copies its bytes out, and drops it, for a value whose text is a couple of dozen bytes and is wanted only inside this buffer. A stack array and one snprintf is the same rendering with none of that.

They agree with str to the byte, and that is the property that makes the cheap path a substitute rather than a second rendering: a program that builds half a line with a builder and half with an interpolation must not be able to tell which half a number came through. push_real is %g for the same reason.

They take long and ulong rather than one member per width — the bargain the print family makes. Overloading would give a set of members one name; it would not give them one body, which is what the widening buys. The difference is that print has the compiler widening its arguments and a member cannot:

import sysl.text.str_builder

var b = str_builder()
var k: int = 42

b.push_int(k)

'n' of 'sysl.text$StrBuilder.push_int' is long, but int was given

So a narrower value is written b.push_int(long(k)) — and a caller who would rather not is describing push(str(k)), which still works, still costs the allocation, and still saves the quadratic copying that made a builder worth having. A value of any other type is pushed that way too.

str_builder_with_capacity(n) starts one with room, skipping the reallocate-and-copy at each doubling on the way up to n. It is a guess and nothing depends on it: too small and the buffer grows the way it always does, too large and the slack goes with the rest. join uses it, because join can compute the answer’s length before it starts.

finish copies rather than lending, so a builder may go on being appended to and the string already taken out of it does not change. And len is a property rather than a method, which the compiler will point out:

import sysl.text.str_builder

var b = str_builder()

b.push("hello")

print(b.len())

'len' is a property of 'sysl.text$StrBuilder' — read it as 'value.len', without '()'

Reading a value back: the parsers

enum ParseError
    Empty
    BadDigit(at: usize)
    Overflow
    BadBase(base: int)

parse_bool(s: string) -> Result[bool, ParseError]
parse_int(s: string) -> Result[int, ParseError]
parse_long(s: string) -> Result[long, ParseError]
parse_uint(s: string) -> Result[uint, ParseError]
parse_ulong(s: string) -> Result[ulong, ParseError]
parse_real(s: string) -> Result[real, ParseError]

parse_int_base(s: string, base: int) -> Result[int, ParseError]
parse_long_base(s: string, base: int) -> Result[long, ParseError]
parse_ulong_base(s: string, base: int) -> Result[ulong, ParseError]

str(x) renders and nothing read back, which is a gap a program feels immediately — an argument, a configuration field and a number in a file are all text. The digits are easy; the library exists for the edges.

import sysl.text.{parse_int, parse_int_base, parse_long, parse_ulong, parse_bool, parse_real}

print(parse_int("42").unwrap(), parse_int("-42").unwrap())
print(parse_int_base("ff", 16).unwrap())
print(parse_long("-9223372036854775808").unwrap())
print(parse_ulong("18446744073709551615").unwrap())
print(parse_bool("true").unwrap(), parse_real("1.5").unwrap())

42 -42
255
-9223372036854775808
18446744073709551615
true 1.5

long‘s most negative value comes back with no special case, and that is the whole trick. The signed range is asymmetric — the magnitude of MIN is one larger than the largest positive value — so a parser that builds a magnitude and negates at the end cannot represent it at any point. These accumulate on the negative side, which covers the entire range with one path and leaves only a positive result of MIN‘s magnitude to refuse, just before the final negation.

The overflow test happens before the arithmetic that would overflow, because integer arithmetic wraps rather than trapping: a product that has already wrapped is not a number a later comparison can learn anything from.

The unsigned range is not the signed one with the sign removed. "ffffffffffffffff" is an ordinary 64-bit mask that overflows every signed parse there is, so a systems language needs the unsigned direction to read back what its own literals are written in. No sign is accepted there, not even +: a leading - on an unsigned value is a question with no good answer.

Refusing, and saying why

ParseError‘s four cases are separated by what a caller would do about them rather than by taxonomy — an empty field is often a default, a bad digit is a message to a user, an overflow is a wider type or a refusal, and a bad base is the program’s own mistake rather than the input’s. Each renders through Display, so a refusal can be printed without being matched on:

import sysl.text.{parse_int, parse_int_base, parse_long, parse_bool, parse_real}

print(parse_int("").unwrap_err())
print(parse_int("12abc").unwrap_err())
print(parse_int("2147483648").unwrap_err(), parse_long("2147483648").unwrap())
print(parse_int_base("10", 99).unwrap_err())
print(parse_bool("True").unwrap_err())
print(parse_real("1.5x").unwrap_err())

no digits to read
not a digit at byte 2
value too large for its type 2147483648
99 is not a base between 2 and 36
not a digit at byte 0
not a digit at byte 3

Four things are visible there.

BadDigit carries the offset, for the reason Utf8Error does: a message naming where is worth writing and cannot be reconstructed afterwards. "12abc" fails at byte 2.

Trailing garbage is refused. "12abc" is not 12, and "1.5x" is not 1.5 — which for the float means checking C’s end pointer, since strtod on its own stops where it likes and reports success.

Overflow is relative to the type asked for. 2147483648 is a perfectly good long and is not an int, so parse_int refuses the same text parse_long accepts. What the caller asked for is an int, and there is no honest int to hand back.

parse_bool accepts exactly the two spellings str produces. "True", "yes" and "1" are each somebody’s convention and none is this library’s; a program wanting one writes three lines that read as the policy they are.

parse_real goes to C’s strtod for the reason the float half of str goes to snprintf: correctly rounded decimal-to-binary conversion is hard to get right, easy to get subtly wrong, and the two directions must agree or a value will not survive being written and read back. It costs one allocation, since C reads a NUL-terminated pointer and a string carries a length instead.

A parse in a `Result` is not the value

import sysl.text.parse_int

print(parse_int("41") + 1)

'+' needs matching types, got sysl.Result[int, sysl.text.ParseError] and int

That is the type doing its job. The usual shape is to let ? carry the refusal outward:

import sysl.text.{split, parse_int, ParseError, Search}

read_port(line: string) -> Result[int, ParseError]
    var parts = split(line, "=")
    var n = parse_int(parts[parts.len - 1].trim())?

    Ok(n)
end read_port

print(read_port("port = 8080").unwrap())
print(read_port("port = eighty").unwrap_err())

8080
not a digit at byte 0

The C boundary

A string carries a length and has no terminator, so passing one to C is an explicit, allocating conversion — and CString owns the copy, because a language with no manual free has to say who frees it:

import sysl.text.{cstring, from_cstring}

extern strlen(p: *u8) -> usize

var cs = cstring("hé")

print(cs.len, strlen(cs.ptr))

from_cstring(cs.ptr) match
    Ok(t) -> print("back", t, t.len)
    Err(e) -> print("refused", e.offset)

3 3
back hé 3

cs.ptr is the *u8 an extern taking a char * is given, and cs.len is the byte length not counting the terminator, so that it agrees with the s.len it came from. The pointer carries an ordinary *T‘s rule: it is valid while the CString is held.

The hazard the explicitness exists for survives, and it is worth stating as an equation:

import sysl.text.cstring

extern strlen(p: *u8) -> usize

var cs = cstring("a\0b")

print(cs.len, strlen(cs.ptr))

3 1

Both numbers are right. sysl counts three bytes because carrying a length is the whole point; C stops at the interior NUL. Neither can be made to be the other, which is exactly why a conversion is written rather than inferred.

from_cstring is the other direction — a string copied out of the NUL-terminated bytes a C function handed back, which every binding needs the moment a C library reports anything in words. The copy is not optional: the bytes belong to C, a static buffer it may reuse on the next call or storage the caller is about to free, and a string outlives the call that produced it. But it is one copy, and it is from_utf8‘s — slicing the *u8 names the bytes where C left them without taking any hold on them, and validation is what turns that borrowed run into a string owning its own.

It is fallible for the same reason from_utf8 is: nothing about a char * promises well-formed UTF-8, and a C library reporting in a non-UTF-8 locale is the ordinary case rather than a corrupt one.

For a literal, none of this is needed — c"…" is a plain *u8 pointing at read-only data, with no allocation and no copy. That form is on foreign functions.

How wide is it on screen: `columns`

s.len is bytes and a Chars walk counts scalar values. Neither is what a terminal draws, and a program laying anything out in columns — a table, a progress bar, anything with a border on the right — is asking a third question:

import sysl.text.{columns, char_columns}

print(columns("café".bytes))
print(char_columns('日'))
print(columns("日本".bytes))

4
2
4

char_columns(c: char) -> usize — two for the East Asian wide and fullwidth forms, none for a combining mark or a format character, one for everything else. A control character answers zero, which is the honest answer to a question it does not really have: a terminal does not draw \n in a column, it acts on it.
columns(text: []const u8) -> usize — the sum over a run of UTF-8. It takes bytes rather than a string so that text being assembled can be measured without being copied into one first; s.bytes is what a caller holding a string passes.

This is data rather than algorithm, which is the whole reason it belongs to the library. The rule is two lines long; what makes it right is 499 ranges out of the Unicode Character Database, and no program should be carrying its own copy of those.

A format specifier cannot answer this and is not meant to. f"${s}%-10s" counts bytes, exactly as C’s %-10s does, so café padded to ten is short by one column and naïveté by two — and the error differs between two cells of the same column, which is the worst way to be wrong. The specifier keeps its equivalence with snprintf; layout asks here instead, by name. Only the caller knows where the next border falls, so what the library owes it is a number, not a padded field.

A no alloc module may use all of it. The tables are static, the search allocates nothing, and a program that calls neither function links neither table.

Reaching the module

Everything above the free surface needs an import, and a trait needs to be in scope for its members to be reachable — which the compiler says in those words:

import sysl.text.split

print(split("a b", " ").len)
print("  x  ".trim())

string has 'trim' from sysl.text.Search, and that trait is not in scope here — import it to reach the member

import sysl.text.Search is the fix, and it is worth reading as a feature rather than a hoop: a member arriving on string from three modules away, with nothing in the file saying so, is how a program becomes unreadable. The import forms are the same ones every module uses.

One conversion is easy to write backwards, since text and bytes are so nearly the same thing here:

import sysl.text.from_utf8

print(from_utf8("hi").unwrap())

'b' of 'sysl.text.from_utf8' is []const byte, but string was given

from_utf8 goes bytes to text. The other direction is s.bytes, is free, and needs no function at all — a string is already a validated []u8, so there is nothing to check on the way out. (Note that the compiler renders u8 as byte in diagnostics.)

Next: sysl.regex — a pattern over that same text, matched without backtracking.

sysl.term

2026-08-16T01:26:07.924728867Z

sysl.term is forty-odd const strings and nothing else. Each one is an ANSI escape sequence, and writing one into the output stream is how a terminal is told to change colour, start underlining, or clear itself.

import sysl.term.*

print(f"${red}${bold}error${reset}: the file was not there")

A sequence is written where the text it affects is written, because that is what it is — a mark in the stream rather than a property of a string. There is no coloured-string type here and nothing to wrap: red is text that happens to be invisible, it concatenates like any other text, and reset is how you stop.

Why constants, and what that buys

A string literal is immortal — it lives in the program’s own image with no owner and no reference count — so naming forty of them costs nothing at run time and nothing in storage. That is what lets this module declare @no_alloc, and it is the point of the whole design: colouring a line is exactly what a program that has given up its allocator most wants to do, and a facility such a program could not use would be no facility at all.

@no_alloc
@no_os

import sysl.term.*

main()
    print(f"${green}ok${reset}")

The module requires no capability at all, so an interrupt handler can name a colour.

The colours

Eight, each with a bright variant and a background form. The arithmetic between them is the specification rather than a coincidence: a background is its foreground plus ten, and a bright colour is its ordinary one plus sixty.

import sysl.term.*

// An escape is invisible, so this reads the parameter back out of one.
code(s: string) -> int
    var n = 0

    for b in s.bytes
        if b >= u8('0') && b <= u8('9') then n = n * 10 + int(b - u8('0'))

    n

main()
    print(code(red), code(bright_red), code(on_red), code(on_bright_red))

31 91 41 101

foreground	bright	background	bright background
`black`	`bright_black`	`on_black`	`on_bright_black`
`red`	`bright_red`	`on_red`	`on_bright_red`
`green`	`bright_green`	`on_green`	`on_bright_green`
`yellow`	`bright_yellow`	`on_yellow`	`on_bright_yellow`
`blue`	`bright_blue`	`on_blue`	`on_bright_blue`
`magenta`	`bright_magenta`	`on_magenta`	`on_bright_magenta`
`cyan`	`bright_cyan`	`on_cyan`	`on_bright_cyan`
`white`	`bright_white`	`on_white`	`on_bright_white`

default_color and on_default put each back to whatever the terminal was using.

Emphasis, and why `reset` is not enough

name	what it does
`bold`	heavier, or brighter on a terminal with no bold face
`dim`	fainter
`italic`	slanted, where the terminal has it
`underline`	underlined
`blink`	blinking, where the terminal allows it
`reverse`	foreground and background swapped
`hidden`	not shown, but still selectable
`strike`	struck through
`reset`	all of the above, and the colours, off at once

ANSI has no way to end one attribute and leave the others — reset ends everything there is. So a program that wants its colour back without losing an emphasis writes default_color rather than reset, and one that has ended a colour inside an underlined field has to open the underline again afterwards.

The screen and the cursor

name	what it does
`clear_screen` / `clear_line`	the whole screen, the whole line — neither moves the cursor
`clear_below` / `clear_to_line_end`	from the cursor onwards
`home`	the top left corner
`hide_cursor` / `show_cursor`	a program that hides it owns showing it again, including on the way out
`save_cursor` / `restore_cursor`	one remembered position, the terminal’s own — these do not nest

clear_screen is nearly always written with home after it, since clearing does not move anything.

Whether to write escapes at all — `sysl.posix.tty`

Naming a colour and deciding to use one are different questions, and they live in different modules. Everything above asks for no capability at all, so an allocator-free, OS-free program can reach it. Asking whether output is a terminal needs isatty, which needs posix — and a capability requirement is module-wide, so one function here would have taken all forty constants away from the programs this module is arranged for. The answer sits in sysl.posix instead, and the split shows up in the import, which is honest about what the second one costs.

It is sysl.posix.tty rather than sysl.term.tty, and the namespace is the point. Everything under sysl.posix requires that one capability, so a freestanding target reaches none of it — which is now visible in the import line rather than only in the module’s own header. What this needs is isatty(3) and termios, so that is where it belongs, however much it reads as terminal handling.

name	answers
`is_tty(fd)`	is this descriptor a terminal?
`color_wanted()`	does the environment want colour — `NO_COLOR` unset or empty, `TERM` not `dumb`?
`color_on(fd)`	both, for one descriptor
`color()` / `color_err()`	both, for standard output and standard error

Ask once and keep the answer. Each of these is a system call or an environment scan, and nothing a running program does changes what they say.

import sysl.term.{red, reset}
import sysl.posix.tty.color

main()
    val paint = color()
    val on    = if paint then red else ""
    val off   = if paint then reset else ""

    print(f"${on}error${off}: not found")

error: not found

That output is the point rather than an accident: this page’s programs run with their output captured, so color() answers false and the escapes are never written — which is exactly what the same program does in a pipeline or redirected to a file.

is_tty is worth having alone: a progress bar, a spinner and a prompt are all worth suppressing when output is a pipe, and none of them is about colour. So is color_wanted — a --color=always flag overrides the descriptor without overriding the user’s NO_COLOR, and that is exactly this function.

NO_COLOR is about the variable being there rather than about its value. Present and non-empty turns colour off whatever it contains, so NO_COLOR=0 means no colour, while set-and-empty does not. A program reading it as a boolean and looking for "1" has misread the convention.

Taking the terminal over — `sysl.posix.tty.raw`

A terminal at a shell is in cooked mode: the kernel’s line discipline echoes what is typed, honours backspace, and hands the program a whole line at Enter. That is why sysl.io.console_lines is all a hosted program usually needs — something else is doing the editing.

raw() puts that out of the way, so a program sees each keystroke as it is typed.

name	does
`raw()`	cbreak mode — keystrokes arrive as typed, nothing is echoed. Answers whether it worked
`cooked()`	puts back what `raw` changed, and only that
`flush()`	pushes out what C is holding — a prompt with no newline after it
`tty_writer()`	standard output as a sink that flushes what it is given

raw() answering false is not an error — it is the other situation. With input redirected from a file or a pipe there is no terminal to change, and an editor is the wrong facility anyway: nothing is being typed and nothing should be echoed. So a program picks its reader from the answer, and prog < script.txt goes on working.

import sysl.io.{stdin, console_lines}
import sysl.posix.tty.{raw, cooked}

main()
    var input = stdin()

    if raw()
        print("a terminal")
        cooked()
    else
        var cursor = console_lines(&input)

        print("a pipe")

a pipe

That output is the point rather than an accident, exactly as above: this page’s programs run with their input closed, so raw() declines and the cooked path is what runs.

What it sets, and the one thing it gives up

-icanon -echo -isig opost onlcr. Output translation is asserted rather than assumed — nothing here turns it off, so leaving it out looked safe, and a terminal that arrives without it makes every print stair-step down the screen while the editor’s own output looks fine.

Signals go, and that is a choice rather than a limitation. Leaving isig alone would keep Ctrl-C interrupting, which reads like a feature for a REPL. It used not to be available at all: a program interrupted in cbreak mode must restore the terminal from a signal handler, and restoring meant allocating a command string and forking a shell, neither of which is async-signal-safe — so the handler deadlocked rather than tidying up. That was a fact about stty, and restoring is now one tcsetattr on a saved struct, which POSIX lists as async-signal-safe. The handler is still not written, because -isig means there is no signal to catch and every exit is an ordinary one. Ctrl-C arrives as byte 3 for the editor instead.

What that costs is worth saying plainly: a program that has stopped responding can no longer be interrupted from its own terminal, and the escape is kill from another one. What it buys is that the terminal is never left broken, and that a hosted program behaves exactly like one on a board — which never had signals to disable.

It is termios, through a shim, and it used to be stty through system. struct termios is caller-allocated and laid out differently on every platform, which is the transcription the library refuses — so the structure stays in C and a file descriptor is all that crosses. The shim sits in a per-OS directory (modules), which is what keeps a #include <termios.h> away from a target that has no terminal to configure.

Three things follow: no shell is forked to set two flags; cooked restores what was actually there, from a saved struct, where naming icanon echo isig to put back would restore a different terminal from the one it found; and it works when standard input is not the shell’s, since the shim is handed a descriptor where stty acted on whatever it inherited.

Reading a line — `sysl.term.edit`

The other half of what a console needs, and the reason it exists: a terminal with no line discipline gives a program nothing. Over a serial cable there is none at all; at a hosted terminal raw() has just removed it. Either way nothing appears as it is typed and a mistake cannot be corrected — which is not a program that reads badly but a program that looks broken.

editor(r, w) is a line editor over a *Reader and a *Writer. It answers whole lines through Iterate[string], the same as sysl.io.lines and console_lines, so the three are interchangeable at a call site and a program chooses by what is producing its input.

import sysl.io.{bytes_reader, bytes_writer}
import sysl.term.edit.editor

main()
    var typed = bytes_reader("one\rtwo\r".bytes)
    var echo  = bytes_writer()
    var ed    = editor(&typed, &echo)

    for line in ed
        print(line)

one
two

keys	do
`←` `→` `Home` `End`	move within the line — and `Ctrl-A` / `Ctrl-E` / `Ctrl-B` / `Ctrl-F`
`Backspace` `Delete`	at the cursor, not only at the end
`Ctrl-U` `Ctrl-K`	kill the line, or from the cursor on
`↑` `↓`	the last 64 lines — and `Ctrl-P` / `Ctrl-N`
`Ctrl-C`	abandon the line and answer an empty one
`Ctrl-D`	end the input, on an empty line only

The line is held as characters and measured in columns. A cursor is an index rather than a byte offset, so a half character can never be left behind by a backspace — one never enters the line. And a wide character occupies two columns, so erasing a CJK character or an emoji clears both; an editor counting characters leaves half of one on the screen.

Both spellings of an arrow key are read. ESC [ D is CSI and ESC O D is SS3, and a terminal chooses between them by whether application cursor key mode is on. Reading only the first is not a simplification — it means a left arrow inserts a stray D into the line.

What it is not

There is no completion, no multi-line editing and no absolute cursor addressing. A program wanting those wants linenoise. A line that wraps past the terminal’s width redraws wrong, which is the honest cost of moving the cursor by writing \b: it stops at column zero rather than climbing to the row above.

It asks for nothing of the platform — no capability, no C — which is what lets the same program run at a terminal and over a cable. It does allocate: the line is a Buf[char] and the answer is a string.

The prompt, and why the editor pokes its sink

The editor prints no prompt and is not told one. Every movement it makes is relative, so it never needs to know how far along the row the line starts, and a caller goes on printing its own prompt — which is what makes a REPL’s continuation prompt the caller’s business rather than a field here.

What it does do is hand its sink a zero-length write before waiting for a keystroke. A hosted sink buffers — putbytes goes through C’s putchar, which line-buffers a terminal — so a prompt with no newline after it would sit in the buffer until something wrote one, which is one keystroke too late. The poke gives a buffering sink its chance, and keeps the obligation off every caller that prints a prompt. A board pays nothing for it: a sink with no buffer writes no bytes.

What is deliberately not here

Anything that takes a number. Moving the cursor to a row and column means building ESC [ row ; col H, and building a string is an allocation — the one thing the module is arranged to avoid. The sequences above are the ones whose text is fixed; a program that wants the others writes f"\u{1b}[${row};${col}H" and knows what it is spending.

table

2026-08-16T01:26:07.924728867Z

Cells of any type that renders, laid out in columns that line up. A column is a promise about where the next border falls, so the program has to know how wide text looks — and that is a different question from how many bytes it is and from how many characters it is.

The axis: text measured for display. Every other program in the set treats a string as bytes to be copied or compared. Nothing else asks how wide one appears, and the moment something does, two plausible answers turn out to be wrong.

Deliberately not modelled: multiple border styles, Markdown and TSV output, row spanning, and wrapping a cell wider than its column. Each is more of the same layout, and none of them asks the language anything the program does not already ask.

What it found

A FormatSpec‘s width is a byte count, so it cannot lay out a column. The specifier’s width and precision count bytes, as C’s do, and display_pad pads to that. A table is the program that minds: café is five bytes and four columns, so a field padded to a byte count is short by one — and short by one per non-ASCII character, so two cells of one column come out wrong by different amounts and the column is ragged rather than merely narrow. There is no correction to apply afterwards.

So the program ignores the specifier’s width entirely, hands every cell the neutral spec, and does its own padding over a count it asks the library for. That division is right — only the caller knows where the next border falls — but it means the one field a table would have used is the one it cannot use, and a program that trusted it would produce a table that is wrong only for text that is not ASCII, which is the worst way to be wrong.

Settled in the core traits: the specifier keeps counting bytes and keeps its equivalence with snprintf, because a specifier is for printf-shaped output. Laying anything out asks columns instead.

A character is not a column either. The first version of this program counted characters, which is right for café and Zürich and wrong for 日本 — two characters occupying four terminal columns. It was recorded as a boundary rather than solved, on the grounds that the East Asian Width table from UAX #11 is data rather than language and had nowhere to live.

That reason was already false when it was written, and that is the more useful half of the finding. Module-level const and val had landed the day before, and four other programs in the set were already using them — datetime carries a transition table built by a function at module level, which is the exact shape a width table needs. An absence is worth checking against the language as it is today rather than as it was when the habit formed. This one cost a paragraph explaining why something could not be done that could.

columns now lives in sysl.text, backed by the Unicode Character Database, and the program measures 日本 and a decomposed café as correctly as it measures ASCII. What the program keeps is the call, not the table.

Ask the library before reporting an absence — the same correction png recorded. This program was most of the way to writing up “a rendered value cannot become a string“: the sink answers a []u8, and two earlier programs had wanted from_utf8 and not had it. It was already there. What that would have cost was not just a false note — the checks were written twice, once comparing bytes by hand, before the conversion was looked for.

What the assertion is

The program checks the property that actually matters, which a byte count would have passed:

even(text: []const u8) -> bool
    val want = columns(line(text, 0))
    var i = 1

    while i < usize(lines(text))
        if columns(line(text, i)) != want then return false

        i += 1

    true
end even

Every line the same width on screen is the whole of what it means for a table to line up. A program that measured wrongly would still pass a byte-equality check and produce a table nobody could read, so the assertion is written in the same unit the renderer is.

sysl.sys

2026-08-16T01:26:07.924728867Z

sysl.sys is the one module in the standard library with no surface at all. Every name in it is private[sysl], so the whole of it is closed to a program:

import sysl.sys.sysl_putchar

print(sysl_putchar(104))

'sysl.sys.sysl_putchar' is private to module 'sysl'

That is not a page with nothing to say, though — it is the page about a seam. Every declaration in the standard library that is not sysl lives here, which means the surface a host has to supply can be read off two files, and the question “what would a freestanding target have to provide?” has a place to be answered.

Nothing in it is reachable, by any route

A fully-qualified path is refused for the same reason a bare one is. Being able to see a name is not being able to use it:

import sysl.sys.*

print(sysl.sys.sysl_sqrt(2.0))

'sysl.sys.sysl_sqrt' is private to module 'sysl'

And the glob import above is worth looking at twice, because it is not itself refused — it succeeds, and brings in nothing:

import sysl.sys.*

print(sysl_putchar(104))

undefined function 'sysl_putchar'

private[sysl] means the module sysl and its whole subtree, so every other part of the standard library may reach these and no program may. Putting a name here is therefore a decision about the library’s own workings rather than an addition to its surface — which is exactly what a reader wants a module like this to mean.

The `sysl_` prefix, and what it buys you

Every extern here is bound to a sysl_-prefixed sysl name while going on resolving to the ordinary C symbol:

module sysl.sys
@link("m")

private[sysl] extern "putchar"   sysl_putchar(c: int) -> int
private[sysl] extern "llvm.sqrt" sysl_sqrt(x: f64) -> f64
private[sysl] extern "cbrt"      sysl_cbrt(x: f64) -> f64

An extern’s symbol is not qualified and cannot be. It names something the linker already has, and the linker knows nothing about sysl’s modules. So the sysl-side name is what had to move, and moving it is what keeps putchar, sqrt, pow, floor, read, memchr and strtod free for a program to declare itself:

import sysl.text.cstring

extern "putchar" putchar(c: int) -> int
extern "sqrt" sqrt(x: f64) -> f64
extern "strtod" strtod(p: *u8, end: **u8) -> real

putchar(104)
putchar(105)
putchar(10)

print(sqrt(2.0))

var s = cstring("3.5 and the rest")
var endp: *u8 = null
var v = strtod(s.ptr, &endp)

print(v)

hi
1.41421
3.5

Those three names are the program’s, bound to the same three symbols the library is bound to, and nothing collides. Spending seven ordinary words out of every program’s namespace would have bought nothing, and guide/fft had already declared its own sqrt before there was a module to ask.

The two halves

platform.sysl — what the library asks of the C library it is hosted on, and the whole of it:

symbol	what the library uses it for
`putchar`	every byte `print` and `prints` emit
`snprintf`	formatting a number into text
`read`	`sysl.io`‘s `FdReader`, and `stdin()` under it
`memchr`	`find_byte`, and the line splitting built on it
`strtod`	`parse_real`

math.sysl — what sysl.math asks of the machine and of the C mathematics library. Roots, exponentials and logarithms; powers and hypot; the circular and hyperbolic trigonometry; the four roundings; fmod; and the two sign-bit operations.

Two entry points per operation

C names the float widths apart, so sqrt takes a double and sqrtf a float, and both are declared. Overloading could give the pair one sysl name, and deliberately does not here: these are the raw declarations, and a name that did not match the symbol it resolves to is the one thing this module exists not to do. sysl.math is where the width stops being visible, and it stops there by dispatching on the receiver’s type rather than by a caller choosing which one they meant.

The intrinsics are spelled the same twice for a different reason: one base name, two widths, and the compiler derives .f64 or .f32 from the signature.

`llvm.` or libm — which is which, and why

Two kinds of declaration, told apart by the namespace the link name is in. A name beginning llvm. is an intrinsic: the back end recognises it and emits the machine’s own instruction, and there is no symbol for a linker to find. Everything else is libm’s, resolved at the link.

The split is not stylistic — it is which operations the hardware has. A square root, an absolute value, a sign transfer and the four roundings are instructions on every machine sysl targets. A sine is not, on any of them, so asking LLVM for llvm.sin would produce a call to the same libm function this file already names, one indirection later.

on the machine	in libm
`sqrt`, `fabs`, `copysign`	`cbrt`, `exp`, `exp2`, `log`, `log2`, `log10`
`floor`, `ceil`, `round`, `trunc`	`pow`, `hypot`, `fmod`
	`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`
	`sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh`

What that buys beyond speed is a program that needs no libc. A freestanding target has no libm to link against, so the whole module used to be hosted-only. The operations in the left column now work on a bare machine, and only the transcendentals in the right one do not.

`round` goes away from zero

llvm.round is C’s round, and it is not llvm.roundeven‘s rule. The two differ at exactly the inputs a rounding is chosen for, so the one adopted here is pinned by a test rather than assumed from the name:

import sysl.math.Float

print(2.5.round(), 3.5.round(), (-2.5).round())
print(2.5.trunc(), (-2.5).trunc(), 2.5.floor(), (-2.5).floor())

3 4 -3
2 -2 2 -3

Banker’s rounding would have answered 2 4 -2 on the first line. All four roundings answer in the float’s own type, because a floor that returned an integer would be undefined for the operands that do not fit one — and the caller who wants an integer is the one who knows the range.

Where the line is drawn

The transcendentals are here and most of the comparisons are not, and the line is what the machine can do that sysl’s operators cannot. A range-reduced sine is an algorithm. So, less obviously, are the two sign operations — because they read and write the sign bit directly, and a sign bit is something no comparison can see.

An absolute value written the obvious way is wrong, and here is the proof:

import sysl.math.Float

var z = -0.0
var hand = if z < 0.0 then -z else z

print(1.0 / z, 1.0 / z.abs(), 1.0 / hand)

-inf inf -inf

-0.0 < 0.0 is false — no comparison distinguishes a negative zero from a positive one — so the negation never runs and the magnitude comes back negative. abs clears the sign bit and gets it right. The only way to see the difference is to divide into it, which is what the program does.

copysign is on the same side of the line for the same reason:

import sysl.math.Float

print(3.0.copysign(-1.0), (-3.0).copysign(1.0), 0.0.copysign(-1.0) == 0.0)
print(1.0 / 0.0.copysign(-1.0))

-3 3 true
-inf

Read those two lines together. The third value on the first line says the result compares equal to positive zero; the second line says it is nevertheless a negative zero. That gap is the whole argument: a sysl body written out of comparisons cannot produce this value or detect it, so the operation has to be the machine’s.

Everything that is a comparison and nothing more — signum, is_finite, is_nan, the interpolation — sysl.math writes in sysl and calls nothing.

`link "m"`

The module carries a link "m" directive, and the reason it names the library rather than the flag is that where libm lives is the target’s answer: a file of its own on ELF, part of libSystem on Darwin, absent from a freestanding machine.

The driver used to carry this instead, and every ELF link was handed -lm whether or not the program computed anything — because the compiler had no way to be told and this file had no way to say. Now the requirement travels with the declarations that create it.

Why it is a leaf

sysl.sys needs nothing. It imports no module, calls no sysl function, and reports no error — and that is a property worth protecting rather than an accident of how small it is.

The clearest illustration is a module that is not here. args_of converts C’s argc/argv into a []string, which sounds exactly like platform business — but it calls print and exit, which are sysl‘s, and sysl reaches sysl.sys for its printing. Putting both in one module would make the two depend on each other, which the acyclic module graph refuses. So it lives in sysl.args instead, and what is left here is a leaf.

A declaration that reports its own failure in words is not a leaf, because reporting is itself a dependency. That is the shape to look for when deciding whether something belongs at the seam.

That is the last module. Back to the section index for the tree, or to the language reference for what the compiler itself accepts.

sysl.sync

2026-08-16T01:26:07.924728867Z

sysl.sync is two types and five names, and the most important thing about it is what it does not require. There is no requires clause on the module at all, so a program that has given up its allocator and its operating system can still reach every name in it:

@no_alloc
@no_os

import sysl.sync.*

var hits = Atomic(0)
var guard = SpinLock(0)

guard.lock()
hits.add(1)
guard.unlock()

print(hits.load(), guard.held)

1 0

That is the whole reason this module exists apart from sysl.posix.threads. A word the processor can touch indivisibly is something a bare machine has; a thread is not, because creating one needs a scheduler underneath. A module’s capability requirement is module-wide, so putting one type that needed posix in here would have taken Atomic[T] out of reach of the allocator, the scheduler, and the interrupt handler — the three pieces of code that need a lock before there is anything to schedule.

name	what it is
`Ordering`	the five C11 orderings — `Relaxed`, `Acquire`, `Release`, `AcqRel`, `SeqCst`
`Atomic[T]`	one word, and the nine operations that touch it indivisibly
`SpinLock`	mutual exclusion held by spinning rather than by sleeping

This is the *T tier of concurrency in the same sense *T is the unsafe tier of memory: nothing here is checked, everything is greppable, and it is how a kernel is written. What sits above it — Mutex[T], spawn, and the crossing rule — is on the sysl.posix.threads page.

`Ordering`

An ordering is not a property of the value. Every ordering reads the same bits; what differs is the promise about what else is guaranteed to have happened around the read. That is why it is an argument rather than something fixed on the variable: the same word is read with Relaxed in a statistics counter and with Acquire in the handoff that publishes a structure, and only the operation knows which it is.

These are C11’s and LLVM’s, named the same way. Nothing here is sysl’s invention, so the standards text and the machine documentation a reader already has apply unchanged.

ordering	what it promises
`Relaxed`	nothing but indivisibility — correct for a counter read once at the end
`Acquire`	everything the releasing thread wrote before its release is visible here afterwards
`Release`	everything written before this becomes visible to whoever acquires it
`AcqRel`	both, for a read-modify-write that is a handoff in each direction at once
`SeqCst`	every thread agrees on one order for all `SeqCst` operations in the program

SeqCst is the strongest and the slowest, and it is what every method here defaults to, because it is the one that makes an ordinary program behave the way its author read it.

A load and a store take three of the five

A release publishes the writes that came before it, and a load makes none; an acquire sees what a release published, and a store reads nothing. So Release and AcqRel name loads that do not exist, Acquire and AcqRel name stores that do not exist, and no machine has an instruction for any of them. Ordering answers the question directly, which is what lets a wrapper taking an ordering as a value check it:

@no_alloc
@no_os

import sysl.sync.*

print(SeqCst.orders_a_load(), Release.orders_a_load(), AcqRel.orders_a_load())
print(SeqCst.orders_a_store(), Acquire.orders_a_store(), AcqRel.orders_a_store())

true false false
true false false

Read the two rows against each other: SeqCst is in both, and it is worth being clear that this is not a special case. It is stronger than an acquire rather than a release in disguise, and stronger than a release rather than an acquire in disguise, so it orders either operation. AcqRel is in neither, because it is exactly the ordering that asks for both halves at once.

This is a fact about what the operations are, not about any particular machine, and a stronger processor would not lift it.

The ordering is written at the call

Below Atomic[T] sit nine forms in the language’s raw tier, beside sizeof and ptr_cast. Each is one machine instruction that no sysl body could have written, and each takes an address:

atomic_load(p, ord)                  atomic_swap(p, v, ord)
atomic_store(p, v, ord)              atomic_cas(p, expected, desired, ord)
atomic_add / _sub / _and / _or / _xor(p, v, ord)
atomic_fence(ord)

The ordering on one of these has to be one of Ordering‘s names, spelled there, because it becomes a keyword in the emitted instruction rather than a value the instruction reads. An ordering held in a variable is well-typed sysl that cannot be lowered:

import sysl.sync.*

var q = Atomic(0)
var ord = Acquire

print(atomic_load(&q.v, ord))

'atomic_load' spells its ordering into the instruction, so it has to be one of Ordering's names written here — not a value carrying one. Where a caller chooses, branch on their choice and write a call per ordering

The last clause is the whole implementation strategy of the module above: each method on Atomic[T] is a match from the ordering it was given to the ordering it writes, one arm per name. That is also what core::sync::atomic does in Rust, for the same reason.

And it costs nothing. At every ordinary call the scrutinee is a constant, so the match folds away and the method call becomes the single instruction it names. Measured on AArch64 at -O1: a.add(1) is ldaddal, a.add(1, Relaxed) is ldadd, a.load(Acquire) is ldapr, and a.store(v, Release) is stlr.

The module is the gate

The five names live in sysl.sync and nowhere else, and none of the nine forms accepts a name a program declared for itself. So a program that never imported the module has no ordering it can write, and the raw tier is closed to it by the ordinary rules about names rather than by a rule of its own. Importing the type is not importing the names:

import sysl.sync.Atomic

var a = Atomic(0)

print(a.load(Relaxed))

undefined name 'Relaxed'

import sysl.sync.* is therefore the ordinary way to reach this module — there are seven names in it, five of them are orderings, and a program using the sixth almost always wants some of the five.

A fence has no wrapper, and the omission is deliberate

atomic_fence(ord) is the fence. It is a barrier the whole thread passes through rather than an operation on any one location, so there is no value for it to be a member of and nothing for a struct to hold. What a free function beside it could add is the default — and the default is what it could not survive, because Relaxed is refused:

import sysl.sync.*

atomic_fence(Relaxed)

a fence is nothing but its ordering, so 'Relaxed' would ask for a barrier that orders nothing — write 'Acquire', 'Release', 'AcqRel' or 'SeqCst', or drop the fence

A wrapper taking an Ordering would need a Relaxed arm, and the only two things that arm could do are call a form that refuses it or quietly do nothing. Softening that diagnostic is worse than writing the form out, so the form is what a program writes.

`Atomic[T]`

Atomic[T] is an ordinary struct with one field, and its methods take the address of that field and hand it to the forms above. There is nothing else to it, and that is the point: the type a program reaches for lives in the library where a reader can open it, rather than inside the compiler where they cannot.

@no_alloc
@no_os

import sysl.sync.*

var a = Atomic(0)

a.store(7)

var was = a.swap(9)

print(was, a.load())

7 9

Every method takes a *self receiver, including load — and that is worth stating, because a read looks like it should not need one. A self receiver is handed a copy of the struct, and the address of a copy is not the address the other threads are writing to. It would compile, it would be atomic, and it would read the wrong word.

Every read-modify-write answers what was there before

That is the property, and it is what makes an atomic increment usable as a ticket: every caller gets a different number and none of them is skipped.

@no_alloc
@no_os

import sysl.sync.*

var next = Atomic(0)
var t1 = next.add(1)
var t2 = next.add(1)
var t3 = next.add(1)

print(t1, t2, t3, next.load())

0 1 2 3

The same shape covers the bitwise members. or is how a flag is set in a word other threads are setting their own flags in, and the answer tells the caller whether it was the one that set it:

@no_alloc
@no_os

import sysl.sync.*

var flags = Atomic(0b1100)
var o = flags.or(0b0011)
var n = flags.and(0b0110)
var x = flags.xor(0b1111)

print(o, n, x, flags.load())

12 15 6 9

`cas` answers the value it found

Not a bool, and not an Option. A caller learns whether it swapped by comparing the answer against what it expected — one comparison it was going to make anyway — and on failure the answer is the value to retry against, so the whole retry loop is one line:

@no_alloc
@no_os

import sysl.sync.*

var slot = Atomic(1)
var seen = slot.load()

while slot.cas(seen, seen * 10) != seen
    seen = slot.load()

print(seen, slot.load())

1 10

Nothing else is running here, so the exchange succeeded the first time round and the body never ran — which is the ordinary case, and the reason the loop is worth writing this way rather than as a bool plus a second load.

Naming another ordering

An ordering on the surface is a parameter with a default, and this is the one place in the design where the ordering is not written at the raw call — it is written at this call, one level up:

@no_alloc
@no_os

import sysl.sync.*

var stats = Atomic(0)

for i in 0..<5
    stats.add(1, Relaxed)

print(stats.load(Acquire))

What `T` may be

An integer of 8, 16, 32 or 64 bits, or a pointer — what the machine has an instruction for. Nothing in the declaration says so, and there is no bound that could: sysl’s integers are an open family, so u12 is a type a program may name and no impl list could have covered it. What refuses the type is the form inside, where the instruction would have had to be chosen:

import sysl.sync.*

var wide = Atomic(0u12)

print(wide.load())

'atomic_load' is one machine instruction, and a machine has one for 8, 16, 32 and 64 bits — u12 is 12, so there is nothing to emit

An aggregate is refused for a different reason and with a different message, because it is a different mistake — there is no width to round to, and what the author wanted was a lock:

import sysl.sync.*

struct Point
    x: i32
    y: i32
end Point

var here = Atomic(Point(1, 2))

print(here.load().x)

'atomic_load' reaches a word the machine can touch indivisibly — an integer of 8, 16, 32 or 64 bits, or a pointer — and Point is neither

A float is in the same position, and it is the one people are most surprised by — a real is 64 bits wide and there is still no instruction that loads one atomically as a float:

import sysl.sync.*

var f = Atomic(1.5)

print(f.load())

'atomic_load' reaches a word the machine can touch indivisibly — an integer of 8, 16, 32 or 64 bits, or a pointer — and real is neither. An aggregate is what a 'SpinLock' or a '&sync Mutex[T]' is for (`06`)

The arithmetic members are refused on a pointer, and for a third reason again: an address plus a number is a question the raw tier does not answer.

import sysl.sync.*

var raw: *u8 = null
var ap = Atomic(raw)
var sum = ap.add(raw)

print(sum == null)

'atomic_add' is arithmetic, and what an address plus a number means is the question the raw tier does not answer — use 'atomic_swap' or 'atomic_cas' to change a pointer, or do the arithmetic on a 'usize' beside it

Read where those four diagnostics point. The caret is on a line in library/sysl/sync/atomic.sysl, not on the line the program wrote — because the form that refuses is inside the method, and the method is ordinary library sysl like everything else here. It is the honest place for it to land, and it is also the clearest demonstration on this page that Atomic[T] really is a struct somebody wrote rather than a type the compiler knows about.

The narrowing on `load` and `store` lands at run time

This is the one check in the module that does, and the reason is exactly the boundary the module sits on. The form refuses a releasing load where the name is written, and it cannot see a name that arrived in a variable — which is precisely what a method taking an Ordering hands it. So load and store carry a require over the two predicates above.

import sysl.sync.*

var a = Atomic(0)

print(a.load(Release))

That compiles, and the process traps when it runs: the contract clause lowers to a trap instruction, so there is no message and no unwinding, the shell reports signal 5, and anything still sitting in the output buffer never reaches the terminal. It folds away entirely wherever the ordering was written at the call, which is every ordinary use.

What the check buys is that an ordering that cannot be honoured stops the program rather than being quietly promoted to SeqCst. Promotion would be sound — it is strictly stronger — and it is not what the author asked for, which is the more useful thing to find out.

Reading the field directly

Atomic[T].v is not hidden, and that is deliberate rather than an oversight:

@no_alloc
@no_os

import sysl.sync.*

var done = Atomic(0)

done.store(1, Release)

print(done.v)

A thread that knows it is alone with the value — the one that built it, or the one left after every other has been joined — is entitled to the cheap read, and hiding it would only have meant a method doing the same thing less visibly. Everywhere else it is a data race, and it is greppable, which is the bargain the whole *T tier makes.

`SpinLock`

The lock a kernel has before it has a scheduler. Blocking means handing the processor to something else, which means there is something else to hand it to — and the allocator, the scheduler’s own run queue, and an interrupt handler are all code that has to take a lock before any of that exists.

@no_alloc
@no_os

import sysl.sync.*

var lk = SpinLock(0)
var first = lk.try_lock()
var second = lk.try_lock()

print(first, second, lk.held)

lk.unlock()

var third = lk.try_lock()

print(lk.held, third)

lk.unlock()
lk.lock()

print(lk.held)

lk.unlock()

true false 1
1 true
1

try_lock never spins and answers whether it took the lock; lock spins until it is free. Neither takes an Ordering and there is no overload that does, because a lock’s orderings are fixed by what a lock means: the exchange that takes it is an acquire, the store that frees it is a release, and that pairing is the whole of what makes the guarded data safe to touch.

Three things it will not do for you

It guards nothing by construction. A spinlock is a flag beside the data, and what the data is stays the programmer’s to remember. That is the difference against Mutex[T], which owns what it protects — and it is deliberate, because the code that needs a spinlock is code that is also reaching through raw pointers, where a type that owned its contents would have nothing coherent to own.

Nothing checks that the releasing thread is the one that took it, or that it was held at all. That would be a second word to maintain on every take, paid by every correct program, to diagnose a bug the discipline below already asks the reader to hold to.

A thread that spins burns its processor for as long as it waits. So this is right only where the hold is short and bounded: a few instructions under the lock, no allocation, no system call, and above all no second lock. Where a wait may be long, or where the holder might be descheduled mid-hold, the answer is a Mutex[T] and a real blocking primitive underneath it. On one processor with no preemption a spin is a deadlock outright — nothing can release what nothing else is running to release.

Why the flag is not an `Atomic[i32]`

It is used as exactly that, and it is written as three raw calls anyway. SpinLock is declared in the same file as Atomic[T], and a lock whose entire implementation is three atomic operations reads better as those three than as a wrapper around a wrapper.

The implementation is worth reading for one detail, which is that lock does not spin on the exchange:

while atomic_swap(&self.held, 1, Acquire) != 0
    var busy = atomic_load(&self.held, Relaxed)

    while busy != 0
        busy = atomic_load(&self.held, Relaxed)

A read-modify-write has to take the cache line exclusively every time round, so waiters spinning on the exchange itself fight each other for the line — and worse, they fight the holder trying to write the release, which is the one thread whose progress everybody is waiting on. A relaxed load spins in a shared line and costs nobody anything.

What is not here

volatile is not a synchronization tool, and the mistake is worth naming because C’s own reference material used to recommend the qualifier for shared variables. It constrains the compiler — it stops accesses being elided, merged, or reordered relative to one another — and says nothing about other cores, about ordering, or about tearing. It is for device memory and for nothing else. Two threads sharing a counter want Atomic[T]; a volatile counter is a race with a keyword in front of it.

&sync T is the language’s, not this module’s. The sigil that makes a reference’s refcount atomic is a spelling the compiler checks, and it lives on memory. It makes the reference safe to share and not the object safe to mutate — the fields are still mutable through any alias — so &sync Mutex[T] and &sync Atomic[i32] are how shared mutable state is actually reached.

There is no channel yet. The message-passing half of the model — where the rule about which values may cross a domain boundary is meant to be enforced — is not written. Until it is, that rule is specification with nothing asking the question, which the sysl.posix.threads page says more about, since that is where it becomes visible rather than theoretical.

Next: sysl.posix.threads — spawning, joining, and the mutex above the spinlock.

Structs and methods

2026-08-16T01:26:07.924728867Z

A struct is its fields

struct Point
    x: int
    y: int
end Point

var p = Point(6, 7)

print("point:", p.x, p.y)

point: 6 7

Construction is positional and uses the type’s own name. There is no new, and no allocation has happened: p is a value, it lives in this frame, and it is exactly as big as its fields.

A struct is copied when you assign it, the same as any other value:

struct Point
    x: int
    y: int
end Point

var a = Point(1, 2)
var b = a

b.x = 99

print("a:", a.x, "b:", b.x)

a: 1 b: 99

That is worth pausing on if you are used to a language where every object is a reference. b = a copied the point. If you want two names for one object, you ask for it — and that is the memory chapter.

Methods

A member with a self receiver is a method. The sigil on self says how the method takes the instance, exactly as it would on any other parameter:

struct Vec2
    x: int
    y: int

    // A read that does not touch the original takes `self` by value.
    sum(self) -> int = self.x + self.y

    // `*self` is a raw pointer to the instance, so the writes land in the caller's value.
    shift(*self, dx: int, dy: int)
        self.x += dx
        self.y += dy
end Vec2

var here = Vec2(3, 4)

print("before:", here.sum())
here.shift(10, 20)
print("after:", here.sum())

before: 7
after: 37

self by value gets a copy, which is what a read wants and what stops a method that only reads from being able to write. *self is the receiver a mutating method takes, and it is spelled with the same sigil that means “raw pointer” everywhere else — because that is what it is.

There is no this and no implicit receiver: self is written, and a field access through it is written too.

Properties and associated functions

A member with no parameter list is a property — it reads like a field but is computed:

struct Rect
    w: int
    h: int

    area -> int = self.w * self.h
    perimeter -> int = 2 * (self.w + self.h)
end Rect

var r = Rect(3, 4)

print("area:", r.area, "perimeter:", r.perimeter)

area: 12 perimeter: 14

Note the missing parentheses at the call: r.area, not r.area(). The convention that goes with that spelling is that a property is cheap — anything that allocates or loops is a method, so that the parentheses warn you.

A member with no self at all is an associated function, called through the type name. It is where a named constructor goes, since the positional Rect(w, h) covers only one shape:

struct Rect
    w: int
    h: int

    area -> int = self.w * self.h

    square(n: int) -> Rect = Rect(n, n)
end Rect

print("square:", Rect.square(5).area)

square: 25

Next: memory — the three modes, and the chapter that makes sysl a different language rather than a different syntax.

Strings

2026-08-16T01:26:07.924728867Z

A string is the slice from the last chapter with one thing added and one taken away: its bytes are guaranteed to be well-formed UTF-8, and nothing may write through it. Everything else — the three words, the O(1) substring, the retain on slicing — is the slice machinery unchanged.

That guarantee is not decoration. It is what lets char mean “a Unicode scalar value” rather than “whatever these bytes turned out to be”, and it is why there are no replacement characters anywhere in the language: there is nothing to repair.

Bytes and characters

A string is measured and indexed in bytes, and decoded into characters:

var s = "naïve"

var chars = 0

for c in s.chars do chars += 1

print("bytes:", s.len, "chars:", chars, "last byte:", s[s.len - 1])

bytes: 6 chars: 5 last byte: 101

Six bytes and five characters, because ï takes two. s[i] is a u8 — a byte, not a character — and s.chars is a cursor that decodes them one scalar value at a time.

That is Go’s choice rather than Swift’s, and the reason is placement: grapheme clusters need Unicode break tables, tables must not be in a kernel, and making them the default would put s.len at O(n) for every program that only wanted a byte offset. Grapheme clusters are a library built over this, not the thing underneath.

A substring shares its parent’s bytes and costs no copy:

var path = "/usr/local/bin"

print("front:", path[..<4], "back:", path[11..], "whole:", path.len)

front: /usr back: bin whole: 14

Two checks happen there rather than one. The bounds are checked, as on any slice — and the ends are checked for landing between characters. Slicing through the middle of a multi-byte character traps, because the alternative is a string that is not valid UTF-8, and the whole type rests on that not being possible.

The sharing has the hazard Go’s has: a two-byte substring of a two-megabyte string keeps the whole buffer alive. The operation that copies out of it is named — s.copy() — and the hazard is documented rather than encoded in a second type.

Joining

+ joins two strings and += appends onto a slot. Both allocate a fresh buffer; UTF-8 is closed under concatenation, so nothing is re-validated.

var name = "sysl"
var greeting = "hello, " + name

greeting += "!"

print(greeting, greeting.len)

hello, sysl! 12

+ is strict. It joins a string to a string and to nothing else:

print("n=" + 5)

'+' needs matching types, got string and int

That is the same no-implicit-conversion stance the numeric operators take. The written conversion is str(x), which renders a value into its string form:

print("count: " + str(3 * 14))
print(str(true) + " " + str('é') + " " + str(2.5))

count: 42
true é 2.5

Every case but a string allocates a fresh buffer. A bool renders to one of two literals and allocates nothing at all, and a struct or an enum renders through its Display implementation.

Interpolation

Writing str at every splice gets old, so a literal may carry a prefix:

var n = 42
var word = "left"
var ratio = 2.0 / 3.0

print(s"n is $n, and twice that is ${n * 2}")
print(f"[${n}%6d] [${word}%-6s] ${ratio}%.3f")
print(raw"a\nb")

n is 42, and twice that is 84
[    42] [left  ] 0.667
a\nb

s"…" splices $name or ${ expression }, each rendered by str — so s"a${e}b" is exactly "a" + str(e) + "b", and interpolation is not a new kind of value. f"…" adds one thing: a hole may be followed by a printf specifier controlling width, precision and justification, checked against the value’s type while compiling. raw"…" leaves a backslash as an ordinary character.

Note where the specifier sits — after the hole, not in a separate format string at the front. The value and the way it is formatted stay next to each other, which is the whole reason for the spelling.

Literals that span lines

var doc = """
    to whom it may concern:
    the indentation you see here is not in the value
    """

print(doc.len)
print(doc)

73
to whom it may concern:
the indentation you see here is not in the value

The content starts on the line after the opening delimiter, and each line’s incidental indentation is dropped — the strip is the least-indented line with content, together with the closing delimiter’s own line when it sits alone. So the closing delimiter is the control: move it left and the value keeps more indentation, right and it keeps less.

This matters more in an indentation-sensitive language than elsewhere. A block written inside a deeply nested body would otherwise carry that body’s indentation into its value, and how deep a piece of code sits is not something its data should record.

Trailing blanks are dropped too, since whitespace at the end of a line is invisible in a source file. A trailing space that is meant is written \u{20}, which survives because escapes are decoded after the trimming. And a \ at the end of a line joins it to the next, which is what the form is really for: a blob of embedded data written over twenty lines is a single constant, where the same data assembled with + would allocate and copy once per piece.

Comparison, and matching

== and < compare the byte sequences, which for well-formed UTF-8 is also codepoint order. Normalization is not applied — a composed é does not equal a decomposed one:

describe(cmd: string) -> string
    cmd match
        "add" -> "combines"
        "del" -> "removes"
        _     -> "unknown"

print(describe("add"), describe("nope"), "add" < "del")

combines unknown true

Swift compares by canonical equivalence, which is right for user-facing text and surprising in systems code, where a string is usually a path, a device name, or a protocol token that has to compare as the bytes it is. Normalization is a library operation, applied where it is wanted and visible when it costs something.

Building text a piece at a time

+= in a loop copies everything gathered so far on every step. StrBuilder keeps one growable buffer instead:

import sysl.text.str_builder

var b = str_builder()

b.push("items:")

for i in 1..3
    b.push_char(' ')
    b.push(str(i))

print(b.finish())

items: 1 2 3

The two ways in are the two that keep the guarantee: a push takes a string and a push_char takes a character, and UTF-8 is closed under appending either — so finish hands back a plain string that nobody has to validate. That is exactly why a builder is not a Writer: a public write taking arbitrary bytes would be an unchecked constructor with a friendlier name.

Coming from bytes

Bytes a program computed are the one route into a string that can fail, so it is the one that returns a Result:

import sysl.text.from_utf8

var good: [3]u8 = [104, 105, 33]
var bad: [2]u8  = [104, 255]

from_utf8(good) match
    Ok(s)  -> print("text:", s)
    Err(e) -> print("bad at", e.offset)

from_utf8(bad) match
    Ok(s)  -> print("text:", s)
    Err(e) -> print("bad at", e.offset, "truncated:", e.truncated)

text: hi!
bad at 1 truncated: false

The error carries the offending offset and one distinction a caller can act on: whether the input merely ended mid-sequence, which more bytes would fix, or holds something no continuation could rescue.

The bytes are copied rather than viewed, and that is deliberate — a slice is writable, so sharing would let a later write change something that had already been checked. Copying is what makes the validation mean anything afterwards.

Talking to C

A sysl string carries a length and may hold a NUL as an ordinary byte, so there is no free conversion to the shape C reads. For a literal there is no conversion needed at all — the compiler emits a NUL after every string literal in read-only data, and c"…" is that constant’s address:

extern printf(fmt: *u8, ...) -> int

printf(c"%d items\n", 7)

7 items

No allocation, no copy, no runtime. For a string that is not a literal, cstring(s) allocates a NUL-terminated copy and hands back a CString that owns it — and the hazard the explicitness exists for is worth stating as an equation: for cstring("a\0b"), cs.len is 3 and C’s strlen(cs.ptr) is

Both are right, and neither can be made into the other.

Literals cost nothing

A string literal is bytes in read-only data with no owner at all — the owner word is null, and retain and release both test for that and do nothing. So a literal needs no allocation, no refcount traffic, and not even an instruction to build.

That is what lets allocator-free code hold, pass, compare and slice strings: panic messages, device node names, format fragments. Anything derived from a literal by slicing is immortal too, because it shares the owner — which is to say it shares having none.

The rule for the whole type is that the type is not gated, the allocating operations are. Holding, passing, comparing, indexing, slicing and iterating any string are free; the ones that make new bytes — +, str, copy(), from_utf8, str_builder, cstring — are the ones a no alloc module may not reach.

Next: enums and patterns — where Option and Result come from, and what match can really do.

Strings

2026-08-16T01:26:07.924728867Z

A string is a three-word owning view of validated UTF-8 bytes — the same shape every slice has, with one thing added and one taken away:


`owner`	the counted buffer keeping the bytes alive, or null for immortal bytes
`ptr`	the first byte of this string — an interior pointer into the owner’s bytes
`len`	the length in bytes, not characters

Added: the bytes are guaranteed well-formed UTF-8. Taken away: nothing may write through it. Every rule on the arrays page about indexing, slicing, length and ownership is therefore true here too, and this page is the two differences and what follows from them.

ptr is separate from owner because a substring must name a range inside its parent’s buffer while still keeping that parent alive. Two words cannot do both jobs: with only {ptr, len}, release has no way back to the buffer header, so either substrings copy or lifetime goes unchecked. The third word buys O(1) substring sharing for eight bytes.

That is the trade against the three languages this came from. Go’s two words work because a garbage collector owns the bytes and can find the object from an interior pointer; sysl has no collector, so those two words leave lifetime unanswered. Swift’s packed sixteen hide three representations behind a discriminator, require an allocator unconditionally, and carry a grapheme-cluster element type whose break tables cannot be in a kernel. Rust’s split — a &str view against an owning String — is the honest two-word answer, and the price is that every signature and every programmer chooses between two types. One type at three words is the trade this language prefers.

Validity

Every string is well-formed UTF-8. This follows char, which already enforces that its value is a Unicode scalar value: a string that could hold arbitrary bytes would make decoding partial again, and would hand a decoder a way to produce a char that cannot exist.

This is Swift’s guarantee rather than Go’s. Go strings are arbitrary bytes that are UTF-8 by convention, so its decoder must substitute U+FFFD and advance one byte on malformed input. Here there is no repair path, because there is nothing to repair.

from	spelling	behaviour
a literal	`"héllo"`	validated while compiling
bytes	`from_utf8(b: []const u8)`	validates; the error names the byte offset
bytes, trusted	`from_utf8_unchecked(b)`	unsafe — the long name is the point: it stays greppable
a `char`	`string(c)`	encodes one scalar value

import sysl.text.from_utf8

var good: [2]u8 = [0xC3, 0xA9]
var bad: [2]u8 = [0xC3, 0x28]

from_utf8(good) match
    Ok(t) -> print("ok", t.len, t)
    Err(e) -> print("bad", e.offset)

from_utf8(bad) match
    Ok(t) -> print("ok", t.len)
    Err(e) -> print("bad at", e.offset, "truncated:", e.truncated)

ok 2 é
bad at 0 truncated: false

Utf8Error carries one thing besides the offset: whether the input merely ended in the middle of a sequence. That is the only distinction a caller can act on differently — more bytes would fix an unfinished sequence and could never fix a wrong one — which is why it is a field rather than a taxonomy of fault names nobody would match on. The pair above is the difference: C3 28 is a lead byte followed by something that is not a continuation, so no amount of further input rescues it.

The validator is Unicode’s well-formedness table, not a decode-then-range-check, and the difference is not stylistic. In the table the lead byte fixes the legal range of the byte after it — E0 demands A0..BF, ED only 80..9F, F0 demands 90..BF, F4 only 80..8F — so an overlong encoding, a surrogate, and a value past 10FFFF are all rejected at the second byte, by the same test, before any codepoint is assembled. Written the other way each needs its own check and each is its own chance to be forgotten.

from_utf8 copies rather than views. A string could in principle share a []u8‘s owner, which would make the conversion O(1) — but a slice is writable and a string is not, so a later write through the slice would change a value that had already been checked. Copying is what makes validation mean anything afterwards, and it is why that entry requires an allocator.

The division of labour is the reason from_utf8 is not built in. The compiler supplies exactly one primitive — from_utf8_unchecked, which is a []u8 taken as a string with nothing looked at — and the validator on top of it is ordinary sysl in sysl.text. What no sysl body could do is that last line, because every safe route to a string already carries the guarantee.

var bytes: [3]u8 = [104, 105, 33]

print(from_utf8_unchecked(bytes))

hi!

It needs no import: it is a compiler primitive, deliberately in the same category as a raw pointer, because breaking the UTF-8 invariant breaks char‘s invariant downstream.

Immortal bytes

A string literal is bytes in read-only data with no owner at all — the owner word is null, and retain and release both test for that and do nothing. Three consequences:

A literal costs no allocation and no refcount traffic. It is a constant, so it needs no instruction to build either.
Allocator-free code can hold, pass, compare, index and slice literals.
Any string derived from a literal by slicing is immortal too, because it shares the owner.
A module-level val holds one with no code running first. Module storage may hold a built string too, and never releases it; a literal is the case that needs no prologue at all.

A sentinel refcount in a header would say the same thing. The null owner is better because it is not string-specific: it is already how a slice of static storage says “nothing to keep alive”, so immortality needs no mechanism of its own.

Granularity: bytes and scalar values

A string is indexed and measured in bytes, and decoded into char — Unicode scalar values. Grapheme clusters are a library built over the scalar view, not the element type.

The reason is where the Unicode data would have to live. Grapheme breaking needs tables that must not be in a kernel, and making the default element type the one that requires them would put a length at O(n) and force an opaque index type on every program that just wants a byte offset. Go’s choice is right for a systems language; Swift’s is right for an application language.

operation	spelling	cost
byte length	`s.len`	O(1)
byte at an index	`s[i] -> u8`	O(1), bounds-checked
substring	`s[a..b] -> string`	O(1), shares; bounds-checked and boundary-checked
bytes	`s.bytes -> []const u8`	O(1) view
scalar values	`s.chars`	O(1) per step, total — no replacement characters
copy out	`s.copy()`	O(n), allocates; releases the parent
concatenation	`a + b`	O(n), allocates
repeated append	`str_builder()`	amortized

var s = "héllo"

print(s.len, s[0], s[1], s[2])

var count = 0

for c in s.chars do count += 1

print(count, s.bytes.len)

6 104 195 169
5 6

Six bytes, five characters, and the é is the two bytes 195 169 sitting where one index used to be enough. That gap between the two counts is the whole of what this section is about.

Indexing gives a byte, and there is no way to write one

var s = "hello"

s[0] = 65

a string is immutable, so its bytes have no address to write through

s.bytes does not open a way round it, and gets a diagnostic of its own that says why:

var s = "hello"

s.bytes[0] = 65

'bytes' views the string's own storage rather than a copy of it — so writing through one is writing the string

The bytes are a []const u8, which is the type that records exactly this, and the way out is the one that type always names: copy them into a []u8 of your own first.

Slicing is boundary-checked

var s = "héllo"

print(s[0..<1], s[1..<3], s[3..])

h é llo

s[a..b] must land on scalar-value boundaries at both ends. Landing mid-character traps, in the same runtime-safety category as a bounds check and a failed char(u):

var s = "héllo"

print(s[0..<2])

Byte 2 is the second half of the é, so that program stops there — no message, no unwinding.

Go permits the mid-character slice and lets you build an invalid string with it. That option is closed here by the validity guarantee, and it is closed for a string that arrived through from_utf8 exactly as it is for a literal: validating at the door is worth nothing if something downstream may undo it.

Walking the characters

s.chars is a cursor — a value implementing Iterate[char] — and it is the one row of the table above that could not be a value or a view. Every other row yields a value; this one yields a sequence, and the decoding is what makes the scalar values, so something has to carry a position and answer “the next one”.

The cursor validates nothing. A string is well-formed by construction, so the decoding reads the length off the lead byte and takes the continuation bytes as given — which is why the cost is O(1) per step and why there are no replacement characters to hand back.

A for walks a copy of a cursor, so a loop cannot be asked afterwards where it got to. A program that needs to know drives the cursor itself, and gets three more answers, all by value, so asking consumes nothing:

var s = "héllo"
var cur = s.chars

print(cur.offset, cur.count(), cur.peek().unwrap())

cur.next()

print(cur.offset, cur.peek().unwrap())

0 5 h
1 é

That shape is a lexer’s, and it was underserved before those existed: a reader with only “the next one” indexes bytes by hand and decodes a second time to find out where it is.

char_indices is the paired walk, yielding each character with the offset of its first byte — Rust’s name, for Rust’s reason. That the offset is the first byte is what makes it directly usable: a slice built from two reported offsets lands on boundaries by construction, and since s[a..b] traps on a mid-character bound, that is a guarantee rather than a convention.

import sysl.text.char_indices

var s = "héllo"

for pair in char_indices(s.bytes)
    val (i, c) = pair
    print(i, c)

0 h
1 é
3 l
4 l
5 o

The offsets go 0 1 3 rather than 0 1 2, which is the two-byte é visible from the other side. It wraps a Chars rather than decoding for itself, so there is one decoder and the two cursors cannot come to disagree about a width.

is_char_boundary is the same question about a single byte — one mask and one comparison, since the continuation byte is the only one matching 10xxxxxx. It is what a program walking backwards, or snapping an arbitrary offset onto a boundary, would otherwise write inline:

import sysl.text.is_char_boundary

var s = "héllo"
var b = s.bytes

print(is_char_boundary(b[1]), is_char_boundary(b[2]), is_char_boundary(b[3]))

true false true

Comparison is by bytes

==, < and the rest compare the byte sequences. For well-formed UTF-8 that is also codepoint order, so the ordering is the useful one. A literal is also a pattern, matched by the same comparison:

var s = "héllo"

print("abc" < "abd", "abc" == "abc", s == "héllo")

var verdict = "yes" match
    "no" -> 0
    "yes" -> 1
    else 2

print(verdict)

true true true
1

Normalization is not applied. Swift’s == compares by canonical equivalence, so a composed "é" equals a decomposed one — correct for user-facing text, surprising and expensive in systems code, where a string is usually a path, a device name, or a protocol token that must compare as the bytes it is. Normalization and collation are library operations, applied where they are wanted and visible when they cost something.

Concatenation

a + b joins two strings and s += t appends onto a slot. Both allocate: the result is a fresh buffer — an ordinary counted heap object — so it owns a count of its own and frees itself like any other reference. UTF-8 is closed under concatenation, so the validity invariant is preserved for free and nothing is re-checked. The operands are copied out rather than aliased, so an operand that was itself a substring keeps no hold on the result.

var a = "hé"
var t = a + "llo"

t += "!"

print(t, t.len)

héllo! 7

+ is strict: it joins a string to a string and nothing else.

var n = 7

print("n=" + n)

'+' needs matching types, got string and int

That is the same no-implicit-coercion stance the numeric operators take, where a mixed-width sum is an error asking for a conversion. The way to build a string out of values of other types is interpolation, where the conversion is written where it happens; making + polymorphic over “anything with a string form” would reintroduce exactly the invisible conversion the rest of the language refuses.

+ is the only arithmetic operator a string defines. The rest are rejected as they are for any type that does not define them.

Rendering a value

str(x) is the written conversion from a value to its string form — the counterpart to the strict +, and what interpolation is built on.

print(str(42), str(true), str('é'), str(2.5), str("already"))

42 true é 2.5 already

type	result
integer	its decimal digits, with a sign for a negative signed value
`bool`	`"true"` or `"false"`
`char`	the one scalar value’s UTF-8
float	the same `%g` rendering `print` gives it
`string`	itself, unchanged

Every case but a string allocates a fresh buffer; a string is returned as it is, and a bool renders to one of two immortal literals and allocates nothing. An integer is rendered without the C library — the digits are divided out into a scratch buffer, which is correct even for the most negative value because the magnitude is taken in unsigned arithmetic. A float goes through snprintf, the one case that needs libc, chosen so that str(x) and print(x) can never disagree.

Any other type renders through Display. A struct or an enum carrying an impl writes itself into a growable buffer, and the bytes that land there become the string — so str of a user type is an ordinary call, and str of one without an implementation names the impl to write:

struct Point
    x: int
    y: int
end Point

var p = Point(1, 2)

print(str(p))

write an 'impl sysl.Display for Point' to say how it renders

A reference, a pointer, a slice and an array remain errors, since none of them can carry an impl.

Interpolation

An interpolated string is a literal with a prefix, and inside it $name or ${ expression } splices a value in. $$ is one literal dollar.

var n = 7

print(s"n is $n, ${n * 2} doubled, $$5")

n is 7, 14 doubled, $5

Each spliced value is rendered by str, so the same rules apply: a primitive renders, and a type with no string form is an error at the splice. The whole thing desugars to the machinery already built — s"a${e}b" is exactly "a" + str(e) + "b" — so an interpolation is not a new kind of value, just a concise way to write a concatenation. A hole holds a full expression, which may itself interpolate, and an empty literal segment beside a hole is dropped, since it is the identity under +.

This follows Scala’s interpolators, and deliberately not a printf-style format string in the default form: the value and the text around it stay where they are read, and the conversion is str applied at the splice rather than a directive parsed out of a separate string.

Format specifiers

f"…" adds one thing: a hole may be followed by a printf specifier controlling width, precision, sign and justification.

var n = 7

print(f"${n}%03d|${2.5}%08.2f|${"hi"}%-5s|")

007|00002.50|hi   |

A hole with no specifier renders through str exactly as in an s"…" string. A specifier binds only to the % written immediately after a hole, so a bare % elsewhere in the text — f"${n}%d done, 100% sure" — is ordinary text. Keeping the specifier beside its value is the point of putting it after the hole rather than in a separate format string.

The conversion is checked against the value’s type while compiling:

var n = 7

print(f"${n}%s")

format '%s' expects a string, but the value has type int

%d %i %x %X %o %u want an integer, %f %e %g %E %G a float, and %s a string. An unsigned conversion reads the value at its own width — %x of an i32 -1 is ffffffff, of a u8 255 is ff — while %d keeps the value’s sign. A string is copied NUL-terminated so that C’s %s can apply width and precision, which means an interior NUL ends the field there, as it does for any %s.

s, raw and f are only prefixes when written directly against the opening quote. Used as ordinary names they are unaffected, so s + raw and f + 1 are ordinary expressions.

Literals

Double-quoted and UTF-8, with the usual escape table. A one-quote literal may not span a line break, and a comment marker inside one is ordinary text. raw"…" does no escape decoding:

print(raw"a\nb".len, "a\nb".len, raw"a\nb")

4 3 a\nb

Text blocks

A literal that spans lines is written """ … """. The content begins on the line after the opening delimiter, which is what gives the indentation rule an anchor: the opening delimiter’s own column then means nothing, so the form reads the same at any depth of nesting.

run() -> string
    val block = """
        one
          two
        three
        """
    block

print(run().len)
prints(run())

16
one
  two
three

Three things happen to a line inside a block that do not happen inside "…".

Its incidental indentation is dropped. The strip is the least indented line that carries content, together with the line the closing delimiter sits on when it sits alone on one — so the closing delimiter is the control, and there is no margin character to remember. Move it left and the value keeps more; right and it keeps less. This matters more here than in a free-form language: a block written inside an indented body would otherwise carry that body’s indentation in its value, and the depth a piece of code sits at is not something its data should record.

Its trailing blanks are dropped, because whitespace at the end of a line is invisible in a source file and would otherwise enter the value unseen. One that is meant is written \u{20}, which survives because escapes are read after the trimming rather than before it. A carriage return goes with the rest of a line’s trailing whitespace, so a block means the same thing in a file with either line ending.

A \ at the end of a line joins it to the next, which is the form’s reason for existing: embedded data wants no line breaks in its value at all.

digest() -> string
    """
    dead\
    beef\
    cafe
    """

prints(digest())

deadbeefcafe

The joining happens in the lexer, so a block is a single constant — where the same data assembled with + allocates and copies once per piece.

Whether the value ends with a newline needs no rule of its own: a closing delimiter alone on its line is reached after the last content line’s break has been taken, and one that follows content is reached before any break at all. A lone " inside a block is ordinary text, which is the other thing the form buys; a block cannot end with one, and \" writes it.

The prefixes are orthogonal to the quote form. c""", s""", f""" and raw""" all compose, since a prefix says how a literal is read and the quote form says how it was written. A raw block does no escape decoding, so nothing joins its lines.

Making new bytes

Four operations produce a string that is not a substring of one already there.

s.copy() stops a substring holding its parent alive. Slicing is O(1) and shares the buffer, which carries Go’s hazard with it: a small substring keeps the whole parent buffer alive. Swift addresses that with a distinct Substring type you must explicitly copy out of; sysl does not add a type for it — the operation that copies out is named, and the hazard is documented rather than encoded.

var big = "the quick brown fox"
var piece = big[4..<9]
var alone = piece.copy()

print(piece, alone, piece == alone)

quick quick true

string(c) encodes one scalar value:

print(string('é').len, string('a'))

2 a

str_builder() gathers text without rebuilding what it already has. Concatenation allocates a fresh buffer each time, so building a string a piece at a time with += copies everything it has so far on every step:

import sysl.text.str_builder

var sb = str_builder()

sb.push("n=")
sb.push_int(42)
sb.push_char('!')

print(sb.finish())

n=42!

Every way in carries the guarantee. A push takes a string, a push_char takes a char, and the four renderers take a number or a bool — UTF-8 is closed under appending any of them, so finish hands back a plain string rather than something a caller has to validate. That is why a builder is not a Writer: a public write taking a []u8 would be from_utf8_unchecked with a longer name and none of its greppability.

push_int, push_uint, push_real and push_bool exist so that gathering a number costs no allocation — push(str(n)) builds a whole counted string, copies its bytes out, and drops it, for a value whose text is a couple of dozen bytes and is wanted only inside this buffer. They agree with str to the byte, which is the property that makes the cheap path a substitute rather than a second rendering: a program that builds half a line with a builder and half with an interpolation must not be able to tell which half a number came through.

finish copies rather than lending, so a builder may go on being appended to and the string already taken out of it does not change. The alternative — handing over the storage and leaving the builder empty — would save a copy at the cost of a form whose meaning depends on how many times it has been called.

cstring(s) is the fourth, and it is the next section.

C interop

A string has no terminator, so passing one to C is an explicit, allocating conversion. CString owns the copy: Go’s version hands back a raw pointer and requires a matching free, and sysl has no manual free to match, so the result is a value whose bytes go when it does. It offers two things — cs.ptr, the *u8 a C function takes, and cs.len, the byte length not counting the terminator, so that it agrees with the s.len it came from.

import sysl.text.cstring

extern strlen(s: *u8) -> usize

var cs = cstring("a\u{0}b")

print(cs.len, strlen(cs.ptr))

3 1

That disagreement is the whole reason the conversion is written rather than inferred. For cstring("a\u{0}b"), cs.len is 3 and C’s strlen is 1. Both are right, and neither can be made to be the other. The pointer carries a raw pointer’s rule: valid while the CString is held, and keeping it past that is the ordinary raw-pointer mistake rather than a new one. Passing cstring(s).ptr straight into a call is safe, since the temporary lives for the statement; storing that pointer and using it later is not.

The literal case needs no allocation at all, and is spelled c"…". The compiler emits a NUL byte after every string literal in read-only data — one byte, not counted in len — so a literal is already sitting in memory in exactly the shape C reads. c"…" is that constant’s address: a plain *u8, no allocation, no copy, no runtime.

extern strlen(s: *u8) -> usize

print(strlen(c"hello"))

It is a distinct literal form rather than an inferred optimization, and deliberately: whether an expression is literally a literal is not something a reader should have to work out, and a rule that silently allocates for s but not for "…" hides a cost the language promises to show. It is Rust’s c"…" and Zig’s null-terminated literal, for the reason both added it.

A c"…" containing an interior NUL is a compile error rather than a truncation:

extern strlen(s: *u8) -> usize

print(strlen(c"a\u{0}b"))

a C string ends at its first NUL, so it cannot contain one

An ordinary "a\u{0}b" is unaffected — it has three bytes and prints as three, because carrying a length is the whole point — and only the free ride to C is lost, which is exactly where the diagnostic belongs.

The allocator-free subset

The type is not gated; the operations that make new bytes are. Legal under no alloc: holding, passing, comparing, indexing, slicing, iterating and releasing any string — including a heap-backed one handed in from outside, which frees itself through its own deallocation hook.

@no_alloc
@no_os

var name = "/dev/console"
var tail = name[5..]

var count = 0

for c in name.chars do count += 1

print(tail, name.len, name[0], count, tail == "console", name < "/dev/null")

console 12 47 12 true true

A module-level val may hold one, which is where a table of messages lives — and here the point is not that it may but that it costs nothing: a literal allocates nothing, so the table is complete before the program starts and a module with @no_alloc may carry it (declarations):

@no_alloc

val messages: [3]string = ["out of range", "not permitted", "no such device"]

var i = 2

print(messages[i], messages[i].len, messages[0][0..<3])

no such device 14 out

A const could not have served that: a constant is folded into its uses and has no address, so there is nothing to index at i.

Requiring an allocator: from_utf8, copy(), concatenation, string(c), str_builder() and cstring — every operation that produces new bytes.

@no_alloc

var greeting = "hello"
var full = greeting + " world"

print(full)

the string two strings join into needs an allocator, and this module declared '@no_alloc'

The diagnostic finishes with the rule that makes the subset usable: such a module may hold and release storage made elsewhere, and may make none of its own. So a module that only ever uses literals sees only immortal strings and its retain and release compile away entirely; one that is handed a heap-backed string pays ordinary refcount traffic and still links no allocator.

What lives in the library

Everything the compiler writes for itself is reachable without an import, and everything a program writes by name is sysl.text. A literal, +, str(x), an interpolation and s.chars are all desugarings, so they cost no import — even s.chars, whose cursor is the library’s, because the compiler names it by key rather than by resolving the word.

Named at the call site, and so imported: from_utf8, char_from_u32, str_builder, cstring, char_indices, is_char_boundary, the parse_* family, the text operations split, fields, join, repeat, replace_all, to_upper and to_lower, the Search and Ascii traits, and the types Utf8Error, ParseError, Chars, CharIndices, StrBuilder and CString. The split is the one the modules page describes: what a program cannot avoid needing arrives free, and what it has to ask for it asks for.

Relationship to slices

A string is exactly an immutable, validated []u8 — the same three words, the same retain-on-slice, one implementation underneath. Everything on this page about sharing and immortality is the general slice rule rather than a string special case, and ownership crosses a no alloc boundary for the general reason: every counted object carries a pointer to the function that frees it.

The one string-specific addition is the validity invariant. A []u8 may hold any bytes and a string is the subset that is well-formed UTF-8, which is why converting between them is checked in one direction and free in the other.

	Go	Swift	Rust	sysl
size	16 B	16 B packed	24 B / 16 B	24 B
representations	1	3	2 types	1
owns its bytes	the collector does	yes	`String` yes, `&str` no	yes
O(1) substring	yes	yes, `Substring`	yes, `&str`	yes
valid UTF-8 guaranteed	no	yes	yes	yes
element	byte / `rune`	grapheme cluster	byte / `char`	byte / `char`
comparison	bytes	canonical equivalence	bytes	bytes
NUL-terminated	no	privately	no	no
usable without an allocator	no	no	`&str` yes	yes

Next: traits.

Statements and control flow

2026-08-16T01:26:07.924728867Z

if, match, while, loop and for are expressions. Each yields a value, so each can initialize a binding, be a function’s body, or feed a branch of another. In statement position the value is simply unused and the same forms read as ordinary control flow.

That removes the statement/expression split that forces C’s temporary-and-reassign dance (int label; if (…) label = …; else label = …;), and it makes one rule — the last expression is the value — uniform across functions, branches, arms and loops.

Blocks

A block is an indented run of statements, and its value is its trailing expression. There are no braces and no statement terminator: a newline ends a statement, and indentation opens and closes a block. See lexical structure for the layout rules and how a long expression is continued across lines.

Where a block’s own value is unused, the block has none — its type is unit whatever the last line yields — and that propagates inward, into the branches of an if, the arms of a match, and the else of a loop. This is what lets branches merely do things without being made to agree on a value nobody asked for:

var full = false
var len = 0
var wrapped = true

if wrapped
    full = true
else
    len += 1

print(full, len)

true 0

Without that rule, full = true (a bool) and len += 1 (an int) would be two branches with nothing to meet at. Statement position starts at a statement, at a loop body, and at the body of a function that returns nothing.

A block stands wherever a construct puts one, and a binding’s = is one of those places — see the value may be an indented block. The rules there are the ones above, unchanged: the trailing expression is the value, and what the block binds goes out of scope with it.

The statement forms

Everything that can stand as a statement:

form
an expression	including every control-flow form, since they are expressions
`var` / `val` / `const`	a binding — see declarations
`ref name = place`	a second name for one place — see memory
`a, b = x, y`	a multiple assignment, which is not an expression
`return`, `break`, `continue`	transfers of control
`defer stmt`	what to run on the way out of this block
`require` / `ensure`	a contract clause — see errors and contracts
`import`, `impl`, and the declarations	a declaration is a statement, so a function may be nested in one

`if`

if cond with an indented block, elif for each further test, and an optional else. The inline form puts then between the condition and a one-line body.

label(n: int) -> string = if n % 2 == 0 then "even" else "odd"

grade(n: int) -> string
    if n >= 90
        "A"
    elif n >= 80
        "B"
    else
        "C"

print(label(4), label(7), grade(95), grade(85), grade(70))

even odd A B C

elif is sugar: each one nests into the else branch of the one before, so no separate node exists and no rule about it has to be learned.

An if used for a value needs an else. A missing one leaves the open branch at unit, which is a diagnostic wherever a value was wanted. In statement position a missing else is ordinary.

An if may be closed with end if, which is optional everywhere and reads well when the block is long enough that its extent has stopped being obvious:

var n = 3

if n > 0
    print("positive")
end if

positive

end is a soft word — an ordinary identifier everywhere except immediately before a construct keyword — so end remains usable as a name. The same marker closes while, for, loop, a struct and an enum.

`match`

value match, then an indented list of pattern -> body arms. The keyword goes after the value, as in Scala and for Scala’s reason: a match is a transformation of the thing to its left, so writing it there is what lets one feed another.

enum Tier
    Bronze
    Silver
    Gold

fee(t: Tier) -> int
    t match
        Bronze -> 0
        Silver -> 10
        Gold   -> 25

print(fee(Bronze), fee(Silver), fee(Gold))

0 10 25

A match used for a value must be exhaustive; one written for effect need not be, which follows the same rule the block-value discard does. Everything about the left side of an arm — the pattern grammar, guards, alternatives, bindings — is on patterns and matching.

Loops

Five forms, and each is an expression.

form	when
`while cond`	test before each iteration
`do … while cond`	test after each iteration, so the body runs at least once
`loop`	no test at all; something inside leaves it
`for x in seq`	walk a range, an array, a slice, or an `Iterate`
`for init; cond; step`	a stride, a descent, a compound test, several variables

`for x in`

The ordinary walk, and preferred wherever it fits: it names one thing instead of three and cannot get any of them wrong.

var xs = [4, 5, 6]

for x in xs
    print(x)

for i in 0..<2
    print(i)

`break` carries a value, and `else` supplies the other one

break expr leaves the nearest loop and makes expr the loop’s value. An optional else block, written after the body as in Python, runs when the loop finishes normally — the condition turned false or the sequence ran out, with no break — and its trailing expression is the loop’s value on that path.

var mixed = [1, 3, 4, 5]
var odds = [1, 3, 5]

var found = for x in mixed
    if x % 2 == 0 then break x
else -1

var none = for x in odds
    if x % 2 == 0 then break x
else -1

print(found, none)

4 -1

That turns the most common reason to leave a loop early — find the first element satisfying a predicate — into one expression whose type states, through the mandatory else, what happens when nothing is found. It is the same discipline that gives references no null and errors a Result: the loop cannot fall through to an undefined value.

With no else, normal completion yields unit — so a value-carrying break without one is refused:

var xs = [1, 2, 3]

var found = for x in xs
    if x == 2 then break x

print(found)

this loop breaks with a int but has no 'else' to give a value when it finishes normally

Every break value and the else value share one type, which becomes the loop’s. A bare break with no else is the ordinary statement loop, of type unit.

`do … while`

The test goes at the foot, so the body runs before anything is asked. The body is an indented block with the while on the line that closes it, or a single statement on one line.

digits(n: int) -> string
    var rest = n
    var s = ""

    do
        s = str(rest % 10) + s
        rest /= 10
    while rest > 0

    s

var i = 0

do i += 1 while i < 4

print(digits(0), digits(4071), i)

0 4071 4

Written as a while, digits prints nothing for 0. The value rules are while‘s: a break carries the loop’s value, and an else runs when the test at the foot finally fails.

continue runs the test, and that is what the form is for. The shape written instead is loop with the test inverted at the bottom:

loop
    body
    if !cond then break        // NOT the same loop

That has no test for a continue to reach, so the first continue added to it jumps over the exit and the loop never leaves — the same trap the three-clause for exists to avoid, where a continue skips the step.

The test takes no is binding, and cannot read what the body declared: it guards nothing, because the body it belongs to has already run.

do
    var k = 1
while k < 2

undefined name 'k'

do is never ambiguous with the do that introduces a one-line body. That one only ever follows a loop header on the same line, so it is never a statement’s first token; a do that starts a line opens this form and nothing else.

`loop`

A loop with nothing to test. It runs until something leaves it, which is what while true was always being used to say.

var n = 0

var stop = loop
    n += 1

    if n == 4 then break n * 10

print(stop, n)

40 4

Two things follow from the condition being gone rather than merely constant. It takes no else — an else runs on normal completion, and this loop has none — so a value-carrying break needs nothing beside it, which is why the program above compiles where the for above it did not.

And a loop nothing breaks out of has type never, so it may stand as the last thing a function owing a value does, with nothing after it to supply one:

serve(handle: () -> unit) -> int
    loop
        handle()

That is the fact while true cannot state. A condition is an expression the analyzer does not evaluate, so a loop written that way looks like one that might finish, and the code after it looks reachable.

The three-clause `for`

C’s counted loop without the parentheses, as Go writes it — every other header in the language is parenthesis-free, and parentheses here would be structure rather than grouping. Each of the three clauses may be left out.

var total = 0

for var i = 0; i < 10; i += 1
    if i % 2 == 0 then continue

    total += i

var down = ""

for var i = 3; i > 0; i -= 1
    down += str(i)

print(total, down)

25 321

The step is why the form exists, and it is not sugar for a while. continue runs the step before testing again, so the skipped iterations above still advance — which is the whole reason that loop terminates. Written as a while the increment sits at the foot of the body, where the first continue anybody adds later walks straight past it: a bug the shape of the code invites and nothing about it warns of.

The second loop is the other reason: a descent is not something a range says.

An absent condition never turns false, so such a loop ends only through a break and takes no else — exactly as loop does, and loop says it better.

Labels

A 'label written before the loop keyword names that loop, and break 'label / continue 'label then act on it rather than on the nearest enclosing one. This is the only way to leave or restart an outer loop from inside a nested one.

var grid = [[1, 2], [3, 4]]

var hit = 'outer for row in grid
    for x in row
        if x == 3 then break 'outer x
else -1

print(hit)

A labeled break carries a value exactly as a bare one does, meeting that loop’s other breaks and its else at one type. continue takes a label but never a value.

The sigil is a leading apostrophe, as in Rust, and deliberately not the :-suffix some languages use: a bare break outer would be ambiguous with break expr carrying a value that happens to be named outer, and the apostrophe keeps a label and a value textually distinct. It does not collide with a character literal — 'a' closes its quote and is a character, 'a does not and is a label.

A label is in scope only inside its own loop’s body. Naming a loop that does not enclose the break, or reusing a label already in scope, is an error rather than a silent miss.

`return`

A function’s body yields its trailing expression, so return is for leaving early. It takes the same comma list a multi-result signature declares:

divmod(a: int, b: int) -> int, int
    if b == 0 then return 0, 0

    a / b, a % b

var q, r = divmod(17, 5)
var z, w = divmod(17, 0)

print(q, r, z, w)

3 2 0 0

`defer`

ARC gives back a &T, a string and a slice’s backing without being asked. It knows nothing about the rest: a descriptor from open, a FILE* from fopen, a block from malloc, a lock taken from a mutex. Until those are released by hand, a correct program is one that never takes an early exit — which ? makes the normal way to leave a function.

defer <statement> runs that statement on the way out of the block containing it. The resource is released beside the call that took it, once, rather than at every exit.

work()
    defer print("second")
    defer print("first")

    print("body")

work()

body
first
second

What runs, and when

A deferred statement belongs to its block — a loop body, a branch arm, or the function body itself — and runs when control leaves that block by any ordinary route: falling off the end, return, break, continue, or a ? taking its failure arm.

Several in one block run last-registered-first, as above, so they undo in the reverse of the order they were set up — the order that lets a later one depend on an earlier one’s resource.

A defer runs only if control reached it. It is a statement, not a declaration: one after an early return never registered, and one in a branch never taken did not either.

The whole statement runs at the exit, so everything in it is read there — not where the defer stands:

show()
    var n = 1

    defer print(n)

    n = 2

show()

Go differs here: it evaluates a deferred call’s arguments where the defer stands and runs the call later, which needs somewhere to keep each captured argument until then — a slot per deferred statement, sized and laid out per call. Reading everything at the exit needs nothing kept. This is Zig’s rule, and it changes nothing for the form’s purpose: defer fclose(f) releases the handle bound above it, and a program that rebinds f in between has changed which file is open, so closing the one that is actually open is the behaviour wanted.

A trap runs nothing. A trap aborts without stack cleanup, and defer does not qualify that: a broken invariant means the program’s model of itself is already wrong, and running cleanup against that state is how a corrupt program writes its corruption to disk on the way down. defer releases a resource; it does not restore an invariant.

Why the block and not the function

Go’s defer runs at function exit. The difference is invisible for the common case — a resource taken at the top of a body and released when the body ends, where the function is the block — and shows up in a loop:

for i in 0..<2
    defer print("close", i)

    print("open", i)

open 0
close 0
open 1
close 1

Block scope closes each iteration’s resource at the end of that iteration, so the program holds one at a time. Function scope would hold all of them until the function returned — and, the part that decides it, would need somewhere to record a number of pending statements that no compiler can bound. That is a per-frame list whose length is discovered while running, which is precisely the machinery that a freestanding target under no alloc has nowhere to put. Block scope needs no runtime state at all: the statement is emitted at each edge that leaves the block, exactly as ARC’s own releases already are.

Go has two reasons for its choice and sysl has neither. recover only works inside a deferred call and a panic unwinds one frame at a time, so the frame has to be the unit; and mutating a named result is how Go wraps an error on the way out. sysl has no unwinding and no named results. The languages that came later without recover — Zig, Swift — both put defer at the block.

Where it sits against the rest of the model

A deferred statement runs before the block’s ARC releases, so every local it names is still alive when it runs, including the one holding the resource being closed. Leaving from the middle unwinds outward: the innermost block runs its deferred statements and then gives up its counts, then the block outside it does the same, up to the function’s own.

It owns nothing and allocates nothing. defer takes no count, makes no box, and adds no word to any value; a program that does not use it emits nothing for it. That is what keeps it available under no alloc, where the resources it releases are the only ones there are.

What it is not is a destructor. A destructor belongs to a type and runs wherever a value of that type dies; defer belongs to one place in one body and runs for the resource that body took. Both exist and neither replaces the other: defer covers every site a program can name, and a destructor covers the deaths it cannot — a resource inside a container, or inside a struct inside a container, dies at a point with no expression in the source.

Next: declarations.

The slices module

2026-08-16T01:26:07.924728867Z

sysl.slices is what a program does to a []T once it has one. Everything here is a free function rather than a member of anything, which is the same call sysl.math made for min: a built-in slice is indexed by the compiler walking to an address, so none of this goes through a trait, and what each function needs is written in its own bound.

Nothing here allocates and nothing here needs a capability. That is deliberate and it is load bearing — this is the module a C binding reaches into, and it is reachable from a target with no allocator and no operating system.

import sysl.slices.{sort, is_sorted, binary_search}

var xs = [5, 3, 8, 1, 9, 2]

sort(xs)

print(xs)
print(is_sorted(xs))

[1, 2, 3, 5, 8, 9]
true

Looking things up

index_of and last_index_of answer an Option[usize] rather than a sentinel — a library answering -1 hands back a number that indexes when it should not, and usize has no negative to spare in any case.

import sysl.slices.{index_of, last_index_of, contains, min_index, max_index}

var xs = [1, 2, 3, 2, 5]

print(index_of(xs, 2).unwrap(), last_index_of(xs, 2).unwrap())
print(contains(xs, 5), contains(xs, 4))
print(min_index(xs).unwrap(), max_index(xs).unwrap())

1 3
true false
0 4

The extremes answer an index rather than a value, because the index answers both questions: an element is one subscript away, and a caller that wanted to modify the extreme element could not have got there from a copy. Ties go to the first, which is the choice min makes and for the same reason.

Comparing and rearranging

import sysl.slices.{equal, starts_with, ends_with, reverse, fill, swap}

var a = [1, 2, 3, 4]

print(equal(a, [1, 2, 3, 4]))
print(starts_with(a, [1, 2]), ends_with(a, [3, 4]))

reverse(a)
print(a)

swap(a, 0, 3)
print(a)

fill(a, 7)
print(a)

true
true true
[4, 3, 2, 1]
[1, 3, 2, 4]
[7, 7, 7, 7]

Two sorts, and neither of them allocates

sort is unstable, works in the slice it was given, and uses no extra storage. It is an introsort: insertion sort below sixteen elements, a median-of-three quicksort above that, and heapsort once the recursion has gone deeper than a well-behaved input ever would — which is what holds the worst case at O(n log n) rather than letting a chosen input make it quadratic.

sort_stable keeps equal elements in the order they arrived, and merges through scratch the caller supplies. That is the honest shape: a stable sort needs somewhere to merge into, and a library that allocated on your behalf would be unusable on the targets this module exists to stay available on. It answers false if the scratch is shorter than the slice.

import sysl.slices.sort_stable

var xs = [(2, 1), (1, 1), (2, 2), (1, 2)]
var scratch = [(0, 0); 4]

print(sort_stable(xs, scratch))
print(xs)

true
[(1, 1), (1, 2), (2, 1), (2, 2)]

Both come in a _by form taking a comparison, which is where the work actually is — the Ord forms are one line handing it <. The comparison is a bare arrow, so it is monomorphized and inlined rather than boxed, and the pair costs nothing over one function.

import sysl.slices.sort_by

var xs = [1, 5, 3, 2]

sort_by(xs, (a, b) -> b < a)

print(xs)

[5, 3, 2, 1]

Which one you want is a real question. sort is faster and says nothing about equal elements; sort_stable promises their order survives. That only matters for a type whose equality does not mean identity — a record ordered on one field — and when it matters, it matters a great deal.

Why these are written in sysl rather than calling qsort

It is the first question anybody arriving from C asks, and the answer is not that the C library is slow.

The binding is perfectly writable. guide/qsort in the compiler’s repository writes it in a dozen lines, and everything it needs is in the language: the address of a per-instantiation comparison, the address of a slice’s storage, and the size of an element.

What decides it is what this module promises. sysl.slices requires no capability, which is a promise made to every machine sysl builds for — and several of those are freestanding, where there is no C library to call at all and qsort is an undefined symbol at the end of somebody’s link. On a hosted machine the same promise fails more quietly: glibc’s qsort sorts by merging into a temporary buffer and calls malloc to obtain one, while Darwin’s sorts in place. One source text therefore allocates on one platform and not on the other.

Neither fact is visible to the compiler, because what is behind an extern is behind it. A module whose whole selling point is that it needs nothing cannot offer a function whose needs are unknowable.

Two smaller reasons stand behind that one. There is no portable stable sort in a C library — mergesort and heapsort are BSD extensions, present on macOS and absent from glibc, and ISO C has only the unstable qsort — so a binding could have replaced sort and never sort_stable. And a bound comparison is an indirect call per step, where a monomorphized [T: Ord] body inlines the same comparison.

Searching a sorted slice

binary_search answers a pair: whether the value was found, and the index it is at or would be inserted at.

import sysl.slices.binary_search

var xs = [1, 3, 5, 7, 9]

val (found, at) = binary_search(xs, 5)
val (missing, where) = binary_search(xs, 4)

print(found, at)
print(missing, where)

true 2
false 2

The insertion point is wanted on a miss and is the expensive half of the answer, so throwing it away would mean computing it twice. An Option[usize] does exactly that; a Result[usize, usize] — Rust’s spelling — keeps it but calls a miss a failure, which it is not.

Where several elements compare equal, the answer is the index of the first. That makes it a function of the values rather than of how the search happened to land, which is what lets two searches of one slice be compared.

The slice must already be sorted by the same order you are searching with. Nothing checks it — that would cost a linear scan on every search and defeat the point — and the answer for an unsorted slice is unspecified rather than wrong in some particular way.

Handing a slice to C

Every binding to a C library needs a pointer to a slice’s first element, because C’s convention is a pointer beside a length. as_ptr and as_mut_ptr are that, and they exist here because every binding was otherwise writing them.

import sysl.slices.as_ptr

var xs = [10, 20, 30]

print(*as_ptr(xs))
print(as_ptr(xs[0..<0]) == null)

10
true

An empty slice answers null. An empty slice is a real input — a length of zero is a loop that does not run — but &xs[0] on one is an out-of-bounds index and traps rather than yielding the pointer C would have accepted.

The cost, said plainly: ISO C leaves passing a null pointer to memcpy undefined even at a length of zero, and a small number of libraries assert non-null on entry. Every real interface takes the pair (null, 0), and the length is what says not to look — but a binding whose C asserts otherwise must pass storage it owns rather than an empty slice.

slab

2026-08-16T01:26:07.924728867Z

One region of bytes carved into fixed blocks, with the free list threaded through the free blocks’ own storage. The first literate program in the set — its findings ran to sixty lines of header comment before anything executable appeared, which is the length at which a comment stops being one, so slab.lsysl is a document with the program indented inside it.

It reads perfectly well unrendered, which is the point of the format — but sysl weave guide/slab/slab.lsysl -o slab.html sets it as one, and sysl tangle on the same file prints the program the compiler reads out of it. See the CLI.

The axis: raw storage — reinterpreting bytes as a typed pointer, asking what a type’s storage costs, and the address arithmetic between the two. Nothing else in the set touches any of it. kernel is allocator-free but never makes storage; it is handed three fixed tables and indexes them. This is the other side of that: the thing a program with no allocator would have to write before it could have one, which is why it is written with no allocator itself.

It is generic in what it holds, and that is the point rather than a flourish. A slab over one hardcoded struct needs no sizeof at all — a literal block size would do — so the generic form is what makes the measurement load-bearing, and it is the shape a real allocator has.

The free list is intrusive: a free block holds the address of the next free block in its own first bytes, so the list costs no storage beside the region. That is what a slab allocator is, and it is only writable because a *u8 can be read as a **u8 and back:

link(b: *u8) -> **u8
    ptr_cast(b)
end link

next_free(b: *u8) -> *u8
    *link(b)
end next_free

What it found

A region declared the obvious way is not aligned for what gets carved out of it. A [N]u8 is aligned to one, because that is what a byte needs, so every load through the resulting pointer is unaligned — which x86 tolerates and which faults on some of the targets this language is for.

The allocator therefore rounds its own base up, exactly as a real one does, paying up to alignof(T) - 1 bytes of the region.

When this guide was written that was the only thing a program could do, and it is not any more. @align(n) asks for a boundary and gets it — on a struct declaration, or on the var that holds the region, which is the shorter way to say it for one region in particular. See attributes. What has not changed is that it is the right behaviour here: a slab is handed a slice it did not declare, so it cannot know what its caller’s region is aligned to and rounding up is exactly what the rounding is for. The finding was that the allocator had no choice; the answer is that its caller now does.

sizeof is what makes a container generic, and alignof is what makes it correct. With only the first, a slab over any T still lays its blocks at whatever offset the region began at. The two arrived together for this reason rather than by tidiness.

A block has to be wide enough to hold the list that threads it. sizeof(T) >= sizeof(*u8) is a real precondition — a slab of u16 cannot store an address inside a free block — and it is a require rather than a comment because both sides are constants the compiler already knows. A language without sizeof could not have stated it at all.

Nothing checks a reinterpreted pointer, and nothing should. ptr_cast hands back a *T aimed at bytes that hold no T yet; the caller writes one before reading one, and no rule here says so. That is the raw tier behaving as specified — the same assertion an unchecked index already is — and it is why the whole file is greppable for the three operations that take on the risk.

An allocator may call its function alloc, and this one does. It could not always: the capability clause used to be written as the two ordinary words no alloc, which reserved both, so the most natural name in the whole program was the one name it could not have and this file called it take. Capabilities are attributes now — @no_alloc, @requires(...) — and an attribute’s name is an ordinary identifier, so the words came back. The general lesson is the one the old note was groping at: a capability written as grammar spends a word out of every program’s namespace, and alloc is the word the code that provides the capability wants most.

The one thing the compiler still refuses is a &T. An early draft tried to hand back a counted reference, on the grounds that a slab block outlives its user. It cannot: ARC would have no count to own, and the safe subset relies on a &T being a live object. So an allocator’s result is a *T and stays in the raw tier, which is where a caller reaching for one already is.

It is allocator-free and still cannot say so — but not for the reason first recorded. no alloc has shipped; what keeps it out of this directory is the clause’s own shape, since a capability is a property of the module and the checks next door render a str on nearly every line. bytecode is the program that got to carry it, and the difference is only that its machine already lived in a module of its own.

Deliberately not modelled

More than one block size, coalescing, and returning the region. The first is a different allocator, and the other two need a heap this program is written without.

Source · Back to the guide programs, or on to the reference.

simd

2026-08-16T01:26:07.924728867Z

Box2D’s contact_solver.c writes the same solver four times — AVX2, NEON, SSE2 and a scalar fallback, selected by #if — and over half of that 2120-line file is those four copies. This program asks whether sysl can write it once.

The axis: one body, more than one register width. Every other program in the set is written for one machine shape. This is the one where the width is the variable, and the interesting part is that the mechanism is not a vector feature at all.

The lane count is an ordinary value parameter

A <N>T is N lanes of T. What makes one kernel serve several widths is that N can come from a value parameter, exactly as [N]T reads an array’s length:

solve[const W: usize](vn: <W>f32, mass: <W>f32, bias: <W>f32) -> <W>f32
    val impulse = (bias - vn) * mass

    // The impulse a contact applies can only push, never pull — so a negative one is clamped away.
    return (impulse < 0.0).select(0.0, impulse)
end solve

Nothing in that body names a width. W is read off the argument, the mask impulse < 0.0 is a <W>bool because the vector it compares is a <W>f32, and select chooses at whatever width the mask has. Called with four lanes and with eight, it is two bodies holding different instructions from one piece of source — fmul <4 x float> in one and fmul <8 x float> in the other.

The clamp is why select is a method rather than an if. Some lanes want it and others do not, and a branch takes one path for the whole register. Both sides are computed and the mask picks per lane. That a mask is an ordinary value — it binds, combines with &, and reduces with any and all — is what keeps the solver’s convergence test to one word instead of a loop with an early exit.

What it found

A vector may not cross to C, and the refusal had to be built. The scope said it was refused and nothing implemented it, so an extern taking a <4>f32 emitted the declaration and made a call whose convention nothing had checked. Which register a vector arrives in differs by target and by which extensions the other side was compiled for — so the failure mode is a call that resolves and corrupts its arguments, not one that fails to link, which is precisely what a boundary check exists to prevent. The shape that does cross is the one C’s own SIMD-taking functions take: a pointer to the lanes. The FFI reference carries the rule.

v += 1.0 was refused while v = v + 1.0 beside it worked. The compound form did not broadcast its scalar, so two spellings defined to reach the same instruction disagreed about it. That is the kind of gap a program finds and a suite does not: a suite tests the form it was written for, and a program writes whichever one reads better.

A vector’s lanes could not reach memory, and that was the main finding. There was no way to move a <W>f32 into a [W]f32 or a []f32, and no way to build one from a run of a slice — so a kernel could compute a batch of results and had nowhere to put them. At a parameterised width it could not be written at all, since a lane index must be a constant and a [const W] body has no constant to write. It was reported rather than worked around, because the workaround would have been per-width and would have been copied.

xs.load(i) and xs.store(i, v) are what closed it, and this is the loop the finding said could not be written:

batch[const W: usize](vn: []const f32, mass: []const f32, bias: []const f32, out: []f32, relax: <W>f32)
    var i: usize = 0

    while i + W <= vn.len
        val v: <W>f32 = vn.load(i)
        val m: <W>f32 = mass.load(i)
        val b: <W>f32 = bias.load(i)

        out.store(i, solve(v, m, b) * relax)
        i += W

    while i < vn.len
        out[i] = scalar_solve(vn[i], mass[i], bias[i]) * relax[0]
        i += 1
end batch

The tail is the caller’s and it is written out rather than hidden, because every kernel over real data has one: an array whose length is not a multiple of the register’s width ends with fewer elements left than there are lanes, and a load of that run traps rather than reading past the end. A masked load would answer it in one instruction and sysl has none; a scalar loop answers it in three lines, which is what C’s SIMD code writes anyway.

relax is a vector rather than an f32, and it is a choice rather than a workaround. The relaxation factor of a Gauss-Seidel step is a constant broadcast across the lanes, and every real SIMD solver passes its constants as vectors for that reason — so the parameter says what the kernel does, and W falls out of it.

It was also, when this program was written, the only way W could enter. Both halves of that have since moved: a load takes its width from what receives the value, and an operand is such a place now, so xs.load(i) * by reads its lane count off by; and a written type argument at a call is what a kernel with no vector parameter uses, so add[8](a, b, out) says the width where the reader is standing. This program’s findings are what closed both.

There is still no shuffle, and the gather is where that shows. A real solver reads its bodies through an index table — body 17 in lane 0, body 3 in lane 1 — and moving eight scattered velocities into lane order costs a scratch array and a pass of scalar stores:

gather(xs: []const f32, at: []const usize) -> <8>f32
    var scratch: [8]f32

    for i in 0..<at.len
        scratch[i] = xs[at[i]]

    return scratch.load(0)
end gather

That is better than the eight written-out lane writes it replaces, and it is still not one instruction. The store is what makes the loop possible: a lane index has to be a constant, because a vector has no address to bounds-check against and a computed lane would be LLVM’s poison rather than a trap — while an array index is checked and may be computed. Putting the lanes somewhere a subscript works is how “check every lane” gets to be an ordinary for.

It is also the honest limit on the claim this program set out to test. Box2D’s four copies differ in the gather-and-transpose half and agree about the arithmetic, so write it once is a true statement about the solver and a weaker one about the loading.

Source · Back to the guide programs, or on to the vectors reference.

shapes

2026-08-16T01:26:07.924728867Z

A catalogue of shapes behind one trait: the dynamic half of the trait system.

The axis: forgetting the type. Every other program in the set knows the type of everything it computes with. This one does not, and that is the whole exercise — a &Shape is a fat pointer that has forgotten what it points at, and the only thing left to do with it is ask the trait’s questions and believe the answers.

Why it needs two families

The shapes come in two kinds, and the second is what makes the problem worth writing.

Four of them are leaves — a circle, a rectangle, a triangle, a polygon — and each answers out of its own fields. The other three are combinators: a group is a shape made of shapes, and a move and a scale each wrap one shape and adjust what it says.

A combinator holds &Shape, so it holds something it cannot name, and a group of groups is dynamic dispatch calling itself. A trait-object design that only ever holds leaves has not been tested; one that holds arbitrary other objects of the same trait has.

What it exercises

Erasure is a coercion, applied per position. Each concrete shape is constructed, boxed because a &Shape was expected, and then erased — the ordinary “write the construction and it is allocated” rule with one more step. Because the coercion applies per branch, an if or a match whose arms are different concrete types meets at one trait object, which is the point of having them.

Object safety is what makes the trait usable this way. A trait can be made into an object when every member has a receiver and mentions Self nowhere but there. Shape‘s members answer questions about the shape and never hand another one back at its own type, so it qualifies — where the whole operator catalogue does not, add(self, rhs: Self) -> Self being the clearest case. That exclusion is the right answer rather than a limitation: an operator over two values of one type is a question about types known while compiling.

A bounding box is a plain struct rather than a shape. It is the answer to a question about a shape and not another thing to dispatch on — a distinction that is easy to lose when everything in sight is a trait object, and the reason the file says so out loud.

Source · Next: scheduler — OS shapes, and reference graphs mutated through references.

sha2

2026-08-16T01:26:07.924728867Z

SHA-224, SHA-256, SHA-384 and SHA-512, plus HMAC over them: one implementation, two word widths.

The axis: generic arithmetic. The message schedule, the round function, the padding, the streaming buffer and the digest are written once and serve four functions. What varies by width is reached through a Word bound — the width itself, the round count, the constant table and the four mixing functions. What varies per digest rather than per width is an argument instead: SHA-224 and SHA-256 are the same word type, and a type may implement a trait once at a given argument list.

That last sentence is the design constraint doing real work rather than a limitation being worked around. Two things that differ per width belong in the bound; two things that differ within one width cannot, and become parameters. The program is the demonstration that the line falls in a usable place.

What it exercises

A conversion may be written at a type parameter, in both directions. T(b) builds a word out of a byte and u8(x) takes one back out, each resolved once the instantiation says what the width is. The pair being symmetric is what lets the byte-order code be written once — bytes arrive most significant first, so a word is built by shifting each one in from the bottom, and that loop is the same code at 32 and 64 bits.

A bound written at a type is inherited by every member. The hash-in-progress struct declares Word once, and its members do not restate it. That is the answer to the repetition the free functions above it show, and it is the concrete reason a container is a better place to put a bound than a pile of functions is — a point the generics reference states as a rule and this program measures in lines.

Static tables. The round constants are large fixed arrays of words, which is the other half of what “generic arithmetic” needs: a table per width, reachable from generic code, with no allocation and no initialization step. That is a module-level val doing exactly what it is for.

Source · Next: shapes — the dynamic half of the trait system.

scheduler

2026-08-16T01:26:07.924728867Z

A priority scheduler: tasks, locks, and the run loop that decides who gets the next tick.

The axis: OS territory. The first program in the set where sysl has to behave like systems code rather than like an application. A run queue, a priority, a task that blocks and a task that wakes it are the shapes a kernel is made of, and they are made of &T graphs mutated through references: a lock points at its owner, the owner points back at the lock it holds, and a waiter points at what it is waiting for while that thing points at the waiter.

The centrepiece is priority inheritance, because it is the one place all of it has to work at once. A low-priority task holding a lock a high-priority task wants is lent the waiter’s urgency until it lets go — which means finding the holder in the ready queue and moving it, the decrease-key the heap exists for. Run the same three tasks with the lending switched off and the schedule is the classic unbounded inversion; switch it on and the urgent task waits for the critical section instead of for an unrelated third task. Both traces can be worked out on paper, and the program asserts them character by character.

What it found

The wait graph is a reference cycle. A blocked task points at the lock and the lock’s waiter list points back at the task; an owner and the lock it holds are a second cycle. weak is exactly the tool for it, and at the time this was written the compiler knew nothing but the reserved word. What saved the program is that a scheduler takes its own graph apart — every wait ends in a wakeup and every lock is released — so its last section asserts that nothing is left holding anything.

That is a property worth having anyway, and here it was standing in for a guarantee the language should have been making. weak T has since shipped, and a program of this shape can now say which edge of a cycle does not own.

A Buf grew and shrank at its end and nowhere else — answered. Every list a scheduler keeps is one that things leave the middle of, and taking a waiter out was compact-then-pop, because there was no remove and no truncate to say it in one step. Buf has both now, so the program’s helper is a search and one call.

What that exposed is worth more than the lines it saved: the hand-written version removed every copy of the value, because compacting keeps whatever does not match, while the name said one and the callers all meant one. A scheduler never has a task in a list twice, so nothing was wrong — and nothing was checked either. Reaching for the library function is reaching for a decision somebody has already made carefully.

A task is fifteen fields with no names at the call site and no defaults — half answered. A task control block is exactly the shape that pays for this: mostly state that starts empty and is written later by somebody else.

The names arrived. A constructor’s fields are named parameters like any other, so the program writes all fifteen by name — which is worth most for the four that are the same bare 0 and would swap without anything noticing. The defaults did not, and that half is a decision rather than an absence: a field declares no default, on the grounds that what an unwritten field gets is the constructor’s business and not the field’s. So the helper stays to spell the zeroes, and is now a body that says what it is doing rather than a row of fifteen positional arguments.

A nullary generic cannot be told what it is making. buf[&Mutex]() is not the syntax: call-site type arguments are deliberately absent, since a type-argument list and an index are the same grammar. Where the value lands somewhere already typed there is nothing to do — the buf() filling a task’s list takes its element type from the field — so it is a var that has to say it. The reach for the other spelling is natural enough that the compiler used to answer it with “the thing being called must be a name”; it now names the rule and the annotation instead, which was this program’s one change to the compiler rather than to itself.

No enum renders itself. str on one is refused — helpfully, naming the impl Display that would answer it — for a data-carrying enum and a plain one alike. So the state description is a hand-written match from six variants to their own six names, which the compiler already knows: they are the words the match arms are written with. Other programs write a describe too, but for a message built out of a payload; this is the first whose rendering is nothing but the name.

&T is Eq, and that is what identity costs — nothing. Address equality is what “is this the lock you actually hold” and “did the heap take its own root off the end” are written with. Worth recording as a positive: a language without it forces a unique name compared as a string, which is wrong in a way that only shows up once two objects are named alike.

Source · Next: kernel — the same machine with no heap at all.

ring

2026-08-16T01:26:07.924728867Z

A bounded ring buffer: fixed storage, indices that cannot leave it, and the whole of what “this ring is consistent” means written into the types and the contracts rather than into the checks.

The axis: the constrained-subtype surface — within ranges, the :: attributes they expose, require/ensure/old, and struct invariants. kernel gives its tables bounded identities and then never asks one a question; until this program nothing in the set had read an attribute or written a contract at all. A ring buffer is the smallest subject needing all of them at once, because every bug a ring buffer has is an index that went somewhere it should not have — and those are the bugs a range type exists to make unwritable.

Like kernel against scheduler, it is written to be compared: two buffers under the same scenarios, one keeping the fact of where the ring ends once and the other keeping it twice. Every check runs both and asserts they agree, so the difference between the two implementations is the measurement.

What it found

A derived subtype’s attributes handed back its base, which made the whole :: surface unusable by the only kind of subtype that needs it. Slot::Last was a byte, Slot::Succ took one, and the loop variable of Slot::Range was one — so every use of an attribute had to be cast back into Slot, undoing the new that made it a type at all. The sibling surface next door had it right all along: a simple enum’s First, Last, Succ and Pred are the enum.

It was invisible until this program because a transparent subtype is its base, and every test the attributes had used a transparent one. Fixed in the compiler — the attributes are the subtype, and Valid alone takes the base, because asking whether a value is a Slot is only a question about something that is not one yet.

The successor of the last slot is a trap, not a wrap. Slot::Succ steps within the range and refuses at Last, which is exactly right for a counter and exactly wrong for a ring — the one operation a ring buffer is made of is the step that goes round. So the modular successor is written by hand out of %. That is not a defect; it is what the attributes mean. Succ is the step that stays inside a range, and a ring’s step does not.

An invariant relating two fields is a claim about the representation, not about the code. The tracked buffer keeps head, tail and count, so tail == (head + count) % capacity — and a push that writes tail and then count traps at the first of the two, on a state that was on its way to a perfectly good one.

The reflex is to call that a wart and reach for a way to suspend the check. It is not a wart: the invariant is the compiler pointing out that the struct carries one fact twice. The other buffer — head and count, with tail computed — has no invariant to break because there is nothing left to disagree. The mid-update trap found a redundant field, which is what it is for.

There are two honest two-field designs and the clause rules out neither: this one, and the embedded classic that keeps head and tail and derives the count, paying one unused slot to tell a full ring from an empty one. That second is what an interrupt-driven ring wants, because a producer and a consumer then write disjoint fields and neither has to touch a shared count. What the clause refuses is only the third design that keeps all three.

Where the fields genuinely cannot be ordered, the way out costs the whole struct. The only form that moves two fields without being seen between them is whole-struct assignment, which restates the buffer to move two bytes — thirty-two bytes copied per push against three written here, and for a ring sized like a real one the entire storage, per element. An invariant across two fields makes the container’s own update cost the size of the container.

Ordering the writes is enough more often than it looks. A watermark relates two fields too, and needs none of the above, because raising the ceiling before the floor keeps every intermediate state legal. The whole-struct form is the last resort, not the first: ask whether an order exists, and only then whether the representation is redundant.

A program’s own run cannot check its contracts; a test can. A violated require traps, so no check in the run can be the one that breaks it — the program would die rather than report, and the run would look truncated instead of failed. Every refusal the run asserts therefore comes from a total operation that answers instead of trapping.

What the trap itself needs is somewhere that outlives the process it ends, and that is a @test(should_trap) function: it runs in a process of its own and passes by not coming back. This is the program that first needed them, and they live beside the code they are about rather than being restated in a language the ring is not written in.

Source · Next: slab — raw storage, and the first of the two literate programs in the set.

Regular expressions

2026-08-16T01:26:07.924728867Z

sysl.regex compiles a POSIX Extended Regular Expression and matches it against text. Two types are the whole of the surface: a Regex, which is a compiled pattern, and a Match, which is what one found.

import sysl.regex.regex

var re = regex("([a-z]+)@([a-z.]+)").unwrap()

re.find("write to ed@example.com today") match
    Some(m) -> print(m.text(), "from", m.group(1).unwrap(), "at", m.group(2).unwrap())
    None -> print("no address")

ed@example.com from ed at example.com

What it costs

Matching is a Pike VM — Ken Thompson’s 1968 NFA simulation, extended by Rob Pike to carry capture positions. Every branch of the pattern is followed at once rather than one at a time with backtracking, so the work is the input length times the pattern length, and no pattern makes it worse than that.

That is a guarantee rather than a typical case. (a|a)*b against a run of as with no b is the standard demonstration: a backtracking engine has to try every way of splitting the run between two identical alternatives, which at forty characters is a trillion attempts and will not finish.

import sysl.regex.regex

var re = regex("(a|a)*b").unwrap()
var hay = ""

for _ in 0..<40 do hay += "a"

print(re.is_match(hay))

false

The price of that guarantee is the feature backtracking buys and this cannot have: there are no backreferences. (a)\1 is not a pattern that matches a doubled character; \1 is an escaped 1.

The bound is on matching, and the other end needs bounding too. An interval is expanded into that many copies of what precedes it, so intervals stack multiplicatively: a{200}{200}{200} is sixteen characters and eight million instructions, and one more factor is a billion. A pattern is therefore refused if it would lay out more than a hundred thousand — far past anything written on purpose, and what keeps a pattern arriving from somewhere untrusted from exhausting memory before it ever runs.

import sysl.regex.{regex, describe}

regex("a{200}{200}{200}") match
    Ok(_) -> print("compiled")
    Err(e) -> print(describe(e))

the pattern expands past 100000 instructions

Compiling

regex answers a Result, because a pattern is text and text can be wrong. Compiling is separated from matching on purpose — it is the expensive half, and a program matching in a loop should compile once outside it.

import sysl.regex.{regex, describe}

regex("(a") match
    Ok(_) -> print("compiled")
    Err(e) -> print(describe(e))

a group is never closed, opened at 0

Every refusal carries the offset in the pattern where the trouble is, and RegexError is an enum, so a program that wants to treat one case differently from another can match on it rather than reading a message.

What a match reports

Spans, as byte offsets into the input — always on character boundaries, so one is directly what s[a..<b] takes.

import sysl.regex.regex

var m = regex("[0-9]+").unwrap().find("order 1234 shipped").unwrap()

print(m.start(), m.end(), m.text())

6 10 1234

A capture group is asked for by number, and the answer is an Option. That is not caution: there is a real difference between a group that took no part in the match and one that matched the empty string, and a span alone cannot tell them apart.

import sysl.regex.regex

var either = regex("(a)|(b)").unwrap().find("b").unwrap()
var empty = regex("(a*)b").unwrap().find("b").unwrap()

print(either.group(1).is_some(), either.group(2).unwrap())
print(empty.group(1).is_some(), s"[${empty.group(1).unwrap()}]")

false b
true []

Group 0 is the whole match and always took part, which is why text() unwraps it for you.

Walking a text

find_all gives every match, left to right and not overlapping.

import sysl.regex.regex

var words = regex("[a-z]+").unwrap()
var all = words.find_all("the quick brown fox")

for i in 0..<all.len()
    print(all.at(i).start(), all.at(i).text())

0 the
4 quick
10 brown
16 fox

A pattern that can match the empty string would otherwise be found at the same place for ever, so the walk resumes one character past an empty match. a* over "bb" therefore finds three: before each b, and after the last.

import sysl.regex.regex

print(regex("a*").unwrap().find_all("bb").len())

The anchors keep speaking about the whole text, not about where a search resumed. That is why find_all takes a starting position rather than searching a shortened input — the obvious way to write it would hand ^ a fresh beginning to match against at every step.

import sysl.regex.regex

print(regex("^ab").unwrap().find_all("abab").len())

Replacing and splitting

Both are written in terms of find_all, so all three agree about what the matches are.

import sysl.regex.regex

var assign = regex("([a-z]+)=([0-9]+)").unwrap()

print(assign.replace_all("x=1, yy=22", "\\2:\\1"))

1:x, 22:yy

The replacement is not a pattern, but it may name the groups the match found: \1 through \9 for those groups, \0 for the whole match, \\ for a backslash. A group that took no part contributes nothing rather than the two characters that named it.

Note the doubling. \2 is not one of sysl’s string escapes and the compiler refuses it, so a replacement naming group 2 is written "\\2" — the same doubling a pattern needs for "\\.".

split answers the pieces between the matches, empty ones included — a splitter that drops them loses a field.

import sysl.regex.regex

var parts = regex(",").unwrap().split("a,b,,c")

print(parts.len())
for i in 0..<parts.len() do print(s"[${parts.at(i)}]")

4
[a]
[b]
[]
[c]

The pattern syntax

POSIX ERE, in full.

form	means
`a`	the character itself
`.`	any one character, newline included
`^` `$`	the beginning and the end of the text
`[abc]` `[a-z]` `[^a-z]`	a bracket expression, a range, a negated one
`[[:alpha:]]`	a named class — see below
`(e)`	a capture group, numbered by where its `(` is
`e*` `e+` `e?`	zero or more, one or more, zero or one
`e{n}` `e{n,}` `e{n,m}`	exactly, at least, between
`ab`	`a` then `b`
`a\\|b`	`a` or `b`
`\x`	the character `x`, ordinary whatever it usually means

The twelve named classes are alpha, digit, alnum, upper, lower, space, blank, print, graph, cntrl, punct and xdigit. Each is the corresponding member of sysl.text.Ascii, so each answers over the ASCII range and false above it.

import sysl.regex.regex

var word = regex("[[:alpha:]][[:alnum:]_]*").unwrap()

print(word.find("  n42_ok!").unwrap().text())

n42_ok

Two positional rules inside a bracket expression are worth knowing because they are the way to include the awkward characters. A ] first is an ordinary ], and a - first or last is an ordinary -.

import sysl.regex.regex

print(regex("[]-]+").unwrap().find("a]-]b").unwrap().text())

]-]

A backslash inside a bracket expression is an ordinary character, as POSIX requires — so [\t] is the two characters backslash and t, not a tab.

Characters, not bytes

A string in sysl is UTF-8 by construction, and this engine matches over its characters. So . is one character however many bytes it occupies, and the span it reports is one a slice can cut — where a byte-stepping matcher would hand back half of a character.

import sysl.regex.regex

var m = regex("..").unwrap().find("héllo").unwrap()

print(m.text(), m.end())

hé 3

The same holds in a pattern: [é-ü] is a range between two characters, not between four bytes.

Leftmost, then longest

POSIX asks for the match that begins earliest, and among those the one that runs longest. Both hold here, and the second is where POSIX and Perl part company: given a|ab against "ab", Perl takes the first alternative that works and answers a.

import sysl.regex.regex

print(regex("a|ab").unwrap().find("ab").unwrap().text())

ab

What is not implemented is POSIX’s rule for the subexpressions. The whole match is leftmost and longest; a capture group inside it holds what the preferred path through the pattern gave it, which is the greedy reading rather than the one POSIX derives for each group in turn. Go and Rust make the same choice, and it shows on patterns like (a|ab)(c|bcd).

What is not here

Basic Regular Expressions. \( opens a group in BRE and is a literal parenthesis here, which is the opposite convention. Only ERE is implemented.
Backreferences, for the reason above: they are what makes matching NP-hard, and the whole point of this engine is that it cannot be made slow.
Lazy quantifiers. a*? is not a lazy star; ERE has no such thing, and it reads as a star made optional again.
Flags — no case-insensitive mode, no multiline mode. [[:alpha:]] and an explicit \n say both, at the cost of saying them.

Looking at what a pattern became

The tree and the program are both public, and both render, for a caller asking why their pattern does what it does.

import sysl.regex.{parse, compile_pattern, show, dump}

print(show(parse("a(b|c)*").unwrap()))
print(dump(compile_pattern("a?").unwrap()))

seq(lit(a), star(group1(alt(lit(b), lit(c)))))
0: save 0
1: split 2, 3
2: char a
3: save 1
4: accept

Next: sysl.buf — the growable sequence everything here builds on.

The rand module

2026-08-16T01:26:07.924728867Z

sysl.rand is a named, seedable, reproducible pseudo-random generator and the distributions that are easy to get wrong.

This is not a source of unpredictability, and nothing here should be used as one. The generator is completely determined by its seed — which is exactly what a test that must reproduce, a simulation that must replay, and a shuffle all want, and exactly what a key, a token, a nonce or a password reset must not have. Anyone who can see a handful of outputs can compute the state and every output that follows. A cryptographic generator is a different thing with a different implementation, and it is not in this module under any name.

import sysl.rand.rng

var g = rng(42, 54)

print(g.below(6), g.below(6), g.below(6))
print(g.boolean())

3 3 2
true

Those numbers are not illustrative — they are what that seed produces, every run, on every machine. That is the whole point of the module.

The algorithm is named so it can be checked

It is PCG32 — PCG-XSH-RR with a 64-bit state and 32-bit output, from M. E. O’Neill’s PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation (2014). The library’s own tests pin it against the reference implementation’s first outputs, because a generator nobody can identify is one nobody can verify.

The state advances by an ordinary linear congruential step, and the output is a permutation of the state’s high bits rather than the state itself. That second step is what a bare congruential generator lacks, and it is why its low bits are notoriously poor — here every bit of the output is a product of the whole state.

Seeding is the caller’s, and that is what keeps it portable

rng(seed, seq) takes two arguments because the stream is not the seed. Two generators with the same seed and different seq produce different, equally good sequences — which is what a program wanting several independent streams from one seed needs, and what seeding from consecutive seeds does not reliably give.

import sysl.rand.rng

var a = rng(7, 1)
var b = rng(7, 1)
var c = rng(7, 2)

print(a.next_u32() == b.next_u32())
print(a.next_u32() == c.next_u32())

true
false

Nothing in sysl.rand reads a clock or asks the operating system for anything, so it compiles and runs on a freestanding target.

Taking a seed from the host — `sysl.posix.rand`

A program that wants a different sequence each run needs entropy, and that needs an operating system. It is a module of its own so that importing the generator cannot drag one in behind it — the same split sysl.term and sysl.posix.tty already make.

It sits under sysl.posix rather than under sysl.rand because getentropy(2) is what it is, and that is the rule the whole namespace follows: a module there is one a freestanding target does not get, and the path says so without the file having to be opened.

import sysl.rand.rng
import sysl.posix.rand.seed_from_os

var g = rng(seed_from_os().unwrap_or(0), 1)

print(g.below(100) < 100)

true

It answers an Option rather than trapping: a program that cannot get entropy usually has a reasonable fallback — a fixed seed and a line in its log saying so — and a library that aborted would take that choice away. It requires posix.

`below` is where this module earns its keep

The obvious next_u64() % n is not uniform whenever n does not divide 2⁶⁴: the low residues come up more often, by a margin that is invisible in a handful of draws and is a real defect in a simulation or a shuffle. below rejects the unfair tail of the range instead, which is exact, terminates with probability one, and expects under two draws.

import sysl.rand.rng

var g = rng(99, 3)
var counts: []int = [0; 6]

for i in 0..<6000
    counts[usize(g.below(6))] += 1

print(counts[0] > 850 && counts[0] < 1150)
print(counts[5] > 850 && counts[5] < 1150)

true
true

range(lo, hi) is the same thing over a signed interval, half-open at the top. unit() answers a real in [0, 1) from 53 bits — the width of a real‘s mantissa, so no representable value is unreachable and none is thrown away — and never returns 1.0, which is the property every caller scaling by a range depends on.

Shuffling

import sysl.rand.rng

var g = rng(2024, 1)
var xs = [1, 2, 3, 4, 5]

g.shuffle(xs)

print(xs.len)

Fisher-Yates, walking down: each position from the end takes a uniformly chosen element from those at or below it. The whole difficulty is drawing that index without bias, which is below‘s job — the loop itself is three lines.

It lives here rather than in sysl.slices because it is a fact about a generator, and because sysl.slices is the module a C binding reaches into: acquiring a random-number generator by asking for a slice operation would be a poor trade.

qsort

2026-08-16T01:26:07.924728867Z

qsort is handed a slice’s storage, the width of an element, and a comparison — and then it calls that comparison back, once per step, for as long as the sort runs. This program binds it and checks its answers against sysl.slices‘ own sort on the same data.

The axis: a callback across the C boundary. Every other program in the set either stays inside sysl or reaches out to C and gets an answer back. This is the one where C reaches in. It is the smallest honest example of the shape, and it needs three things at once — the address of a function that is generic in the element type, the address of a slice’s storage, and the size of an element.

The binding, in full

private extern "qsort" c_qsort(base: *u8, n: usize, size: usize, cmp: *extern(*u8, *u8) -> int)

private compare[T: Ord](a: *u8, b: *u8) -> int
    var x: *T = ptr_cast(a)
    var y: *T = ptr_cast(b)

    if *x < *y then -1
    else if *y < *x then 1
    else 0
end compare

sort_libc[T: Ord](xs: []T)
    if xs.len < 2 then return

    c_qsort(ptr_cast(as_mut_ptr(xs)), xs.len, sizeof(T), &compare[T])
end sort_libc

compare is one function per element type, and that is the whole trick. qsort is told the width of an element and otherwise moves anonymous bytes; the only thing that knows what those bytes are is that body, and it knows because the compiler made a copy of it for each T a program sorted. A C programmer does the same thing by hand and writes the cast themselves — which is exactly what the two lines at the top of the body are.

The two comparisons are not clumsiness either. C’s convention has three answers — negative, zero, positive — and < has two, so there is no third answer to read off a single test.

What it found

The obvious trampoline had no address, and now it has one. The natural shape is C’s own signature with the cast inside it — compare[T: Ord](a: *u8, b: *u8) -> int — and T appears in neither parameter nor result. An address settles a generic function’s instantiation from the expected type, and the expected type here is *extern(*u8, *u8) -> int, which does not mention T at all. There was nothing to read, and no annotation written anywhere else could have supplied it.

So the argument is written where the address is taken: &compare[T], which was the first position in the language to take written type arguments and the case that earned them anywhere. This program is why they exist. What it had to be written as before was a trampoline over *T rather than *u8, a second ptr_cast of the function pointer, and a val whose only job was to be somewhere to put the type — a shape imposed by the language rather than chosen, and one every C callback would have copied, since every one of them fixes its signature and leaves the payload type to its caller. The FFI reference has the form and what its brackets can hold.

There was no clock, and now there is. sysl.time had Instant, Duration and the calendar between them, and nothing in the library read one — no monotonic counter and no wall clock. So this program could compare the two sorts for correctness and not for cost, which was half of why it was written. Binding clock_gettime here would have answered the question and put a hand-rolled clock into the reading material, which is the thing a guide program is least allowed to teach, so it was reported instead and the answer is sysl.posix.time.

The program’s last section uses monotonic, and the type is the part worth noticing: it answers a Duration rather than an Instant, so one reading means nothing and only the difference of two does. That is the clock a measurement wants — the wall clock is the one somebody can set, and a sort timed across an ntpd adjustment would come out negative. On a hundred thousand pseudo-random ints the library’s sort runs in roughly seventy per cent of C qsort‘s time, which is the comparison this program was written to make: sysl’s is monomorphized against the element type, and qsort‘s comparison is reached through a pointer it cannot see through.

Why this is not in the standard library

sysl.slices requires no capability, which is a promise made to every machine sysl builds for — including the freestanding ones, where there is no C library and qsort is an undefined symbol at the end of somebody’s link. The slices page has the rest of the argument, including the part that has nothing to do with speed: glibc’s qsort allocates a merge buffer and Darwin’s does not, and the compiler cannot see through an extern to know which it got.

That is why the binding lives here, where a reader can see the whole of what it costs on one screen, rather than in a module whose selling point is that it needs nothing.

Source · Back to the guide programs, or on to the reference.

png

2026-08-16T01:26:07.924728867Z

A PNG reader: the chunk layer, the checksum, the filters, and the pixels underneath them — including its own inflate.

The axis: the byte level. Everything here is arithmetic on bytes somebody else laid out. A PNG is a signature, then a sequence of chunks, each one a big-endian length, a four-letter name, that many bytes, and a CRC of the name and the bytes together. The pixels are in the chunks named IDAT, concatenated and then deflated; what comes out is not the image but one filter byte per row followed by a row of differences, and the image is what is left after each row is reconstructed from the row above it and the pixel to its left.

Which is to say: three separate byte orders, four separate length units — bytes, samples, pixels, rows — and a checksum over each of the two layers. Being wrong by one anywhere in that produces an image, just not the right one. That is what the problem is for.

What it exercises

Naming what a file can be wrong about. A reader of somebody else’s format needs a lot of error cases, and naming them individually is the difference between “this file is broken” and a report that says where and what. That is an enum with a variant per failure, carried in a Result — the shape the language pushes you toward, and the one a byte-level reader wants anyway.

unit as a payload. This program and bytecode have nothing in common and both paid for the same missing thing: a fallible step that yields no value. Two independent programs reporting one absence is what moved it from a nuisance to a language change, and it is the clearest example in the set of why findings are written down rather than worked around.

The one piece of mathematics is the Paeth predictor, and the magnitude it needs comes from sysl.math rather than from a private helper this file writes. The integers are an open family, so Signed is a trait the compiler supplies membership for at every width — which is what stops a byte-level program from having to write its own abs for the width it happens to be using.

Worth noticing

The program carries its own fixtures rather than reading a file, so the whole thing is checkable with no filesystem and no os capability. That is not incidental to a guide program: the set has to keep passing across compiler changes, and a test that needs a file on disk is a test that fails for a reason unrelated to the language.

Source · Next: fft — a type the program defined, and floating point.

Patterns and matching

2026-08-16T01:26:07.924728867Z

match is an expression: it yields a value in value position and reads as ordinary control flow in statement position. Its shape is a scrutinee and a sequence of arms, each an ordered list of patterns, an optional guard, and a body.

classify(n: int) -> string
    n match
        0         -> "zero"
        1 | 2 | 3 -> "small"
        4..10     -> "medium"
        else         "large"

print(classify(0), classify(2), classify(7), classify(99))

zero small medium large

The keyword goes after the value. A match is a transformation of the thing to its left, and writing it there is what lets one feed another: x match … match … reads in the order the values flow. It binds looser than every operator, so the scrutinee is the whole expression written before it — a < b match chooses on the comparison, and parentheses are what narrow it.

The else arm carries no ->. The arrow separates a pattern from what to do when it matches, and else is not a pattern — it is the fallback, and it takes its body the way an if‘s else does.

classify(n: int) -> string
    n match
        0    -> "zero"
        else -> "other"

print(classify(0))

the 'else' arm takes its body directly, with no '->' — 'else' names no pattern to separate one from

Two evaluation guarantees:

The scrutinee is evaluated exactly once. A side-effecting scrutinee runs one time, and the arms test against the resulting value.
Arms are tried top to bottom, and the first whose pattern matches — and whose guard, if any, holds — wins. That first-match rule is what makes a specific arm above a general one behave as written.

The pattern forms

pattern	example	matches
wildcard	`_`	anything, binds nothing
`else` arm	`else …`	anything; the catch-all spelling in tail position
literal	`0`, `'a'`, `"hi"`, `true`	a value equal to the literal
range	`3..7`, `0..<10`, `'a'..'z'`	a value in the range
bind	`r`, `other`	anything, and binds it to the name
variant	`Circle(r)`, `Empty`, `Shape.Empty`	that variant, binding each sub-pattern to a field
nested	`Wrap(Val(v))`	a variant whose payload itself matches a sub-pattern
struct, positional	`Point(a, b)`	a struct, binding every field by position
struct, named	`Point{x, y}`, `Point{x: a}`	a struct, binding fields by name; unlisted fields unconstrained
tuple	`(a, b)`, `(a, _)`	a tuple, by position
named	`c @ Circle(r)`	what the sub-pattern matches, binding the whole value too

Literal patterns match any type with equality; range patterns need a contiguous order. The two gates are deliberately different. A literal pattern works on the integers, char, string, and bool — matching a boolean by pattern is the natural spelling, and it is exhaustive with both arms present and no catch-all:

word(b: bool) -> string
    b match
        true  -> "yes"
        false -> "no"

print(word(true), word(false))

yes no

A range pattern is restricted to the numeric types and char, the types over which a contiguous interval is meaningful. string is deliberately excluded: "a".."z" has no useful meaning. A string is matched by literal or by binding.

The bare-name rule

A bare identifier in pattern position is a nullary-variant pattern when it names a nullary variant of the scrutinee’s enum, and a binding otherwise.

enum Shape
    Empty
    Circle(r: int)

name(s: Shape) -> string
    s match
        Empty     -> "empty"
        Circle(r) -> "circle " + str(r)

print(name(Empty), name(Circle(3)))

empty circle 3

A bare name that happens to be a data variant is a diagnostic rather than a silent binding, which closes the classic trap where a misspelled or payload-carrying variant quietly becomes a catch-all:

enum Shape
    Empty
    Circle(r: int)

name(s: Shape) -> string
    s match
        Empty  -> "empty"
        Circle -> "circle"

print(name(Empty))

variant 'Circle' carries data — match it as 'Circle(…)'

Rust and Swift reach the same resolution; sysl makes the data-variant case a hard error rather than a lint.

A qualified name is a pattern wherever a bare one is. Shape.Empty matches exactly as Empty does — the scrutinee’s type already settled which enum is meant. What a qualified name cannot be is a binding: no program declares a name with a dot in it, so one that resolves to neither a variant nor a constant is a diagnostic rather than a new local.

A backticked name references rather than binds

The rule above resolves a bare name against a narrow set — the scrutinee’s nullary variants, then the constants — and binds otherwise. Everything outside that set is therefore unreachable by a bare name: a val, a local, a parameter. Each is storage read while the program runs, so there is no value for a compile-time pattern to compare against.

A backtick-quoted name says the test was meant, and the arm becomes an ordinary equality against whatever the name holds when the match runs:

describe(n: int, limit: int) -> string
    n match
        `limit` -> "at the limit"
        else "elsewhere"

print(describe(10, 10), describe(3, 10))

at the limit elsewhere

Written bare, limit would bind — matching everything, and leaving the second arm unreachable. The two spellings are the whole of the difference, and that is the point: a reader does not have to know what is in scope to know which was meant.

Three things follow. A quoted name that resolves to nothing is a diagnostic, not a new local. A const still folds to its literal, so quoting one changes nothing but the reader’s certainty. And a runtime equality tells exhaustiveness nothing, so an arm written this way never discharges a case and a catch-all stays required.

It cannot stand at a binding, where there is no other arm to take when the value differs:

val limit: int = 10
val (`limit`, b) = (3, 4)

print(b)

a binding cannot test a value

Alternatives may not bind

1 | 2 | 3 is one arm matching any of three literals. An arm whose alternatives bind is rejected, because the body cannot know which alternative matched and therefore cannot know a binding’s origin:

enum Box
    One(v: int)
    Two(v: int)

get(b: Box) -> int
    b match
        One(v) | Two(v) -> v

print(get(One(1)))

alternative patterns joined by '|' cannot bind a name

This is stricter than Rust, which permits A(x) | B(x) when every alternative binds the same names at the same types. The rule here is simple and unambiguous: an arm with | binds nothing.

A name may be bound twice in one match, but not in one pattern

Each arm is its own scope, so two arms may reuse a name freely. Inside one pattern a repeat is refused, because a pattern binds once however deeply it nests, and a second binding of the name would quietly stand for a different part of the value:

struct Point
    x: int
    y: int
end Point

var p = Point(3, 3)

p match
    Point(v, v) -> print(v)

'v' is bound twice in one pattern, and the second would quietly stand for a different part of the value — rename it, or compare the two in a guard

The reading it stops is the tempting one: Point(v, v) looks like a test that the two fields are equal, and it is not one — no pattern here compares two parts of the value. That is what a guard is for. Scala, Rust, OCaml and Haskell all refuse it for the same reason.

`n @ pat` — matching and naming at once

A pattern that takes a value apart leaves the arm holding only the parts. Where the arm wants the whole as well — to hand it on, to store it, to return it — @ binds it beside them:

enum Shape
    Circle(r: int)
    Rect(w: int, h: int)

area(s: Shape) -> int
    s match
        Circle(r) -> r * r * 3
        Rect(w, h) -> w * h

describe(s: Shape) -> string
    s match
        c @ Circle(r) -> "circle r=" + str(r) + " area=" + str(area(c))
        other -> "other, area=" + str(area(other))

print(describe(Circle(2)))

circle r=2 area=12

Without it the arm has to choose: destructure and lose the value, or bind it and test the shape a second time inside the body.

A binding is not a test, so a named arm covers exactly what the sub-pattern covers — no else is owed that would not have been owed anyway, and none becomes unreachable. It nests, the part after the @ being an ordinary pattern: whole @ One(part @ Val(n)) names three things at three depths. It is also read at an is test and at a binding, where var whole @ Point{x, y} = p gives the value a name alongside its fields.

The name must be one a program could declare, so a qualified name is refused — what a binding introduces is a local, and a name with a dot in it is not one.

This @ and an annotation’s are the same character and never compete. An annotation’s is a prefix, on its own line above a declaration; this one is infix, between a name and a pattern. No declaration may stand where a pattern is read, so neither position is reachable by the other form — the arrangement Scala has carried for twenty years.

Struct patterns

A struct is destructured two ways, and they are a division of labour rather than two spellings of one thing.

struct Point
    x: int
    y: int

describe(p: Point) -> string
    p match
        Point(0, 0) -> "origin"
        Point{x: a} -> "x is " + str(a)

print(describe(Point(0, 0)), describe(Point(5, 1)))

origin x is 5

Positional (Point(a, b)) is total. It mirrors construction — sysl builds a struct positionally, so tearing it apart positionally is symmetric — and it must name every field, with _ to skip one. Adding a field to the struct therefore turns each positional match into a checked arity error, the way a new enum variant does. This is the handle-everything tool.

Named-field (Point{x, y}) is partial by default. It binds by field name, so it is order-independent, supports renaming ({x: a} binds field x to a), and matches a subset — any field left unlisted is simply unconstrained. Adding a field never breaks a named pattern. This is the grab-what-I-need tool. There is no .. token, because positional already covers the total case.

Point(a, b) is textually identical to a variant pattern but not ambiguous: the compiler resolves it by what Point denotes. A struct type is a struct pattern; an enum variant is a variant pattern — the same name resolution the bare-name rule uses.

A tuple pattern is a struct pattern with the name left off. (a, b) binds both components, (a, _) binds one, and nesting works. A tuple has one shape, so a tuple pattern is irrefutable and discharges its column for exhaustiveness exactly as a struct pattern does.

Both forms compose with everything else: a struct pattern nests inside a variant pattern and vice versa, and each bound sub-pattern is itself any pattern in this table.

A pattern at a binding

match is not the only place a pattern stands. A val or var binding takes one too:

struct Counter
    n: int
end Counter

pair(c: *Counter) -> (int, int)
    c.n = c.n + 1
    (1, 2)

once()
    var c = Counter(0)

    val ((p, q), r) = (pair(&c), 3)

    print(p, q, r, c.n)

shape()
    val ((x, y), _) = ((3, 4), 5)
    var (lo, hi) = (0, 10)

    hi += 1

    print(x, y, lo, hi)

once()
shape()

1 2 3 1
3 4 0 11

The value is evaluated exactly once, which is the same guarantee a scrutinee gets and for the same reason: it is analyzed into a temporary no program can name, and every part is a field read of that. pair() runs one time above however many names come out of it — the 1 on the end of the first line is the count.

A var pattern makes every name it binds assignable and a val pattern makes each write-once, exactly as the single-name forms do. A _ binds nothing and skips its part.

That once-only rule is also what makes the obvious swap correct, since both parts of the right-hand side are read before either name is bound:

show()
    var (a, b) = (1, 2)
    val (c, d) = (b, a)

    print(a, b, c, d)

show()

1 2 2 1

Only an irrefutable pattern may stand there

A binding has no other arm to take. So the patterns allowed at one are exactly those that cannot fail — a tuple pattern, either struct form, a name, a wildcard, and those nested inside one another — and everything in the table above that is a test is refused by name.

A struct qualifies because it has exactly one shape, which is the same property that makes a tuple pattern irrefutable, and both spellings of it stand here:

struct Point
    x: int
    y: int
end Point

struct Pair
    both: (int, int)
end Pair

show()
    val Point{y, x} = Point(3, 4)
    val Point(a, b) = Point(5, 6)
    val (Point{x: px}, k) = (Point(7, 8), 9)
    val Pair((lo, hi)) = Pair((10, 11))

    print(x, y, a, b, px, k, lo, hi)

show()

3 4 5 6 7 9 10 11

The two forms differ in what they must account for, and it is the difference they have in a match. The named form may leave fields out, and an unlisted one simply binds nothing — there is no exhaustiveness to discharge at a binding, so nothing has to stand in for it. The positional form names every field, so a struct that grows one turns each positional binding into a checked to-do rather than a binding that quietly goes on binding the same names:

struct Point
    x: int
    y: int
    z: int
end Point

show()
    val Point(x, y) = Point(1, 2, 3)

    print(x)

show()

struct 'Point' has 3 fields, but 2 sub-patterns were given

That Name(…) is a struct pattern here at all is the ordinary resolution rule: the spelling reads as a variant pattern until the value’s type settles it, exactly as it does in an arm.

A literal is a test:

show()
    val (1, b) = (1, 2)

    print(b)

show()

a binding cannot test a value — this pattern matches only some values, and a binding has no other arm to take when it does not match

So is a range, and the diagnostic is the same one, because it is the same objection.

A variant is a choice among shapes, which is a different objection and gets its own words:

enum Shape
    Circle(r: int)
    Square(s: int)
end Shape

show()
    val (Circle(r), b) = (Circle(1), 2)

    print(r, b)

show()

a binding cannot choose among variants — this pattern matches one of several shapes, and a binding has no other arm to take when the value has another

Each of those belongs in a match, where the arm that does not match has somewhere to fall through to.

The shape has to line up

A tuple pattern is irrefutable for the tuple it describes, so the arity is checked where it is written rather than at run time:

show()
    val (a, b, c) = (1, 2)

    print(a)

show()

this pattern takes 3 parts, and a (int, int) has 2 parts to give it

Taking apart something that is not a tuple at all is refused in its own words, because the mistake is a different one — there is no shape to disagree about:

show()
    val (a, b) = 5

    print(a)

show()

one int is not something to take apart — only a tuple is

And a name may appear once:

show()
    val (a, a) = (1, 2)

    print(a)

show()

'a' is named twice in one binding

Guards

An arm may carry an if guard, evaluated after its pattern matches.

band(n: int) -> string
    n match
        1..10 if n > 5 -> "high"
        1..10          -> "low"
        else              "out"

print(band(7), band(2), band(50))

high low out

Three rules:

A guard runs only when its pattern has already matched, never for an arm that was ruled out, so a side-effecting guard fires exactly on the arms whose shape fits.
A failed guard falls through to a later overlapping arm. The two 1..10 arms above are the first-match rule plus fallthrough, not a partition into disjoint cases.
A guarded arm does not count toward exhaustiveness. The compiler cannot prove a guard holds, so a guarded arm never discharges a variant’s obligation — a match covered only by guarded arms still needs a catch-all. This is Rust’s rule, and it is what keeps exhaustiveness a real guarantee rather than a formality.

Exhaustiveness

A match on a data enum must cover every value or carry an unguarded catch-all, and a gap names what is missing:

enum Shape
    Circle(r: int)
    Rect(w: int, h: int)

area(s: Shape) -> int
    s match
        Circle(r) -> r * r

print(area(Circle(2)))

match on 'Shape' is not exhaustive; missing Rect (add an 'else' arm)

That is the central payoff of a closed sum type: adding a variant turns every non-catch-all match on it into a checked to-do list.

Four rules decide what counts as covered.

Coverage is about which values are guaranteed handled, not which tags appear, and the arms answer that together. Some(Halt), Some(Push) and None cover an Option[Op] between them even though none of them covers a variant on its own — and Some(0) alone does not cover Some, because a Some holding a non-zero value slips through.

What is missing is named at the depth it is missing at. A gap inside a payload reports as missing Some(Push) rather than as missing Some, and a column no arm narrowed stays a _ standing for all its values, rather than expanding into one line per combination behind it.

A type is covered by listing its values only when it has a finite, known set of them — an enum’s variants, a struct’s single shape, bool‘s two. Everything else is covered by a wildcard or a binding and by nothing shorter, which is why 1 -> … and 2 -> … on an int still need an else.

A scalar match must be exhaustive only when it is used for a value. In statement position a non-exhaustive scalar match is fine — the unmatched case is a no-op. An enum match is exhaustive-checked in both positions, because falling off the end of one has no defined result even for effect. That asymmetry is what is exists to relieve; see expressions.

A catch-all is a wildcard or a bind in tail position, carried by an unguarded arm. else and _ are the same thing to the analyzer; else is the conventional spelling in tail position, _ the one that reads inside a | or a nested pattern.

What a match is worth

A match used for a value takes the common type of its arms. When every arm yields the same non-unit type, that is the match’s type; a match whose arms only do things is unit.

An arm that does not finish constrains nothing. An arm that aborts or returns has type never, so it is set aside before the others are compared:

first(o: Option[int]) -> int
    o match
        Some(v) -> v
        None    -> return 0

print(first(Some(41)) + 1, first(None))

42 0

Exhaustiveness is unaffected — a diverging arm still has to be reachable by a pattern that covers something.

Disagreeing arm types are a diagnostic, not a silent unit. When the arms yield different non-unit types and nothing unifies them, the match is a type error reported at the match rather than a quiet fallback that surfaces later as a confusing error at the use site.

A &T context reaches each arm, not the whole match. Under a &Point expectation, an arm yielding a bound &Point payload and an arm building a fresh Point meet at &Point — the value arm is boxed on its own and the reference arm passes through untouched. Boxing the whole match instead would fail, because an arm that is already &Point cannot un-become a value.

Refcounts survive destructuring

Pattern matching obeys the memory model with no special rule, and both obligations are exactly where a hand-written tagged union in C leaks or double-frees.

Binding a &T payload out of an enum retains it. Full(p) -> p hands the bound reference past the frame of the enum it came from, so the payload is retained on bind and released once when the binding dies — the extracted reference outlives the enum, and the count is exact.

A binding under a failed guard is released exactly once. When Full(p) if p.x > 100 fails and control falls through, the p bound for the guard is released before the next arm is tried, with no double free and no leak.

Matching through a reference

Selection auto-dereferences one level, but match does not: matching a &Enum or a *Enum against its variants is written match *e — the same explicit one-level dereference Go asks for on a type switch.

That keeps “am I matching the reference or the thing” a visible question, and it is the one place a reference to an enum needs the *.

Next: memory.

Packages

2026-08-16T01:26:07.924728867Z

A project’s configuration and its list of dependencies are one file, package.hocon, at the project root. It says who this package is, what machines it is built for, what those machines provide, and what it depends on.

The file is optional. A single-file program has none, and gets the defaults: the project root is the directory the compiler was given, the target is the machine it is running on, and that target provides everything. sysl run hello.sysl needs no ceremony.

package {
  name    = "geom"
  version = "1.4.2"
}

targets {
  default = "aarch64-macos"
}

capabilities { heap = false }

requires { os = true }

dependencies {
  json  { git = "github.com/edadma/sysl-json", version = "1.4.0" }
  regex { git = "github.com/edadma/sysl-regex", version = "0.4.0", mount = "re" }
  local { path = "../experiment" }
}

What a project is called

package.name is what a directory project’s executable is called. A directory is a project because it holds .sysl files, not because anybody said so, so a project has no identity of its own unless this block gives it one. Without a name the output takes the directory’s:

myproj/main.sysl        ->  myproj/myproj
myproj/package.hocon    ->  myproj/tool
  package { name = "tool" }

Requiring the file was the other way to answer this, and it is deliberately not what happens: it would give every project an identity and charge every project the ceremony, when a scratch directory holding one .sysl file is the cheapest thing in the toolchain and worth keeping cheap.

A file project is outside this. sysl build foo.sysl writes foo beside the caller, whatever a package.hocon sitting in the same directory says — the name came from the path you typed, and a config quietly moving the executable would be a worse surprise than anything it fixed.

The name reaches the filesystem, so it has to be a single path segment. ., .., anything holding a separator, and the empty string are refused when the file is read, rather than being sanitized into something that would build a differently-named executable without saying so.

Capabilities

Whether the machine has a heap, an operating system or POSIX is a project engineering decision, and this is where it is stated. The compiler’s registry of targets deliberately carries no capabilities: a target’s ABI is measured and its capabilities are policy, so the ABI is the registry’s and the policy is yours.

capabilities { heap = false }

That is the project’s own statement and it applies to every target the project builds for. A capability the file does not mention is provided — the prior is that a machine can do everything, which is what every build had before there was a file to say otherwise, so what a config records is what a machine cannot do.

A target block layers over it, per capability, for the one machine that differs:

capabilities { heap = false }

targets {
  default = "thumbv7em-freestanding"
  aarch64-macos { capabilities { heap = true } }
}

Only the capabilities a target block names are overridden; everything else still comes from the project’s own block. Writing the statement only inside target blocks — which was once the only place it could go — keys it to a machine’s name, so a project building for three targets says it three times and cannot say it at all for a target the registry already has without a block that reads as redefining the machine.

`capabilities` against `requires`

The two blocks point in opposite directions and neither substitutes for the other:

block	says	about
`capabilities`	this machine has these	the target being built for
`requires`	this package cannot be built without these	the host it needs

requires { heap = true } buys one clean error when the package is built for a machine without one, instead of an error at every &T. A false there says nothing — a package does not need a facility not to exist — and is refused rather than quietly dropped, naming the two places that do mean it.

`heap`, and the module’s own `@no_alloc`

The capability is heap, a facility the machine either has or has not. A module’s promise that its own code does not use one is spelled @no_alloc, a conduct. They are two words because they are two statements, and each is refused where the other belongs.

For compatibility with packages already published, alloc is still accepted in this file and read as heap. Write heap.

One heap, and the package that names it

Having a heap is one question; which heap is another. A program allocates through one pair of C functions, and a package that brings its own says which:

allocator {
  alloc = "pvPortMalloc"
  free  = "vPortFree"
}

Saying it settles the pair for the whole program, not for the package that said it. Every allocation the compilation emits calls that pair — a string concatenation, a Buf growing, a box the reference counter builds — and every release gives the storage back to it. Declare nothing anywhere and the pair is libc’s malloc and free, which is what a program depending on nothing that says otherwise gets.

It is the program’s pair rather than the package’s, because there is one heap. Ownership is settled by reference count, so which code frees a thing is not knowable when a package is written: a Buf filled inside an RTOS package and handed back is freed by the application, and one built by the application and passed in is freed by the package. Two allocators would make every one of those crossings a heap boundary that no signature marks.

A package declares it rather than a target, and that is deliberate. The obvious alternative is a target fact — the machine knows it is a Cortex-M — and it does not survive contact: thumbv7em does not imply FreeRTOS, two RTOSes on one chip want different pairs, and a bare-metal program on that chip wants libc’s. What knows the answer is the package carrying the heap.

Two that disagree, and two that agree

Two packages naming different pairs is refused when the dependency graph is resolved:

two packages name different allocators, and a program has one heap — 'freertos' names
pvPortMalloc / vPortFree; 'arena' names arena_alloc / arena_free. Drop one of the
declarations, or depend on only one of them

Refused there rather than at the link, because the link will not refuse it: both symbols resolve, the program builds, and it hands one allocator’s storage to the other’s free at run time.

Two packages naming the same pair unify to it. That is the ordinary case rather than a coincidence — a kernel package and a driver built on it both name the kernel’s allocator, and neither has to know whether the other did.

Both halves are said or neither is; half a pair is refused, since storage taken from one heap and given back to another is the one outcome worse than not building. The project’s own manifest may declare a pair too, which covers an application with its own arena and no dependency that has one.

Whichever road the package arrived by. A package named in dependencies and the same package handed over as a --lib source root declare the same thing and settle the same question — this is a property of the package, not of the flag that reached it.

A library artifact is built for one allocator

A .syslib‘s object half is compiled code, and it calls the pair by name. So an artifact is built for one allocator exactly as it is built for one machine, and a program that allocates another way refuses it:

geom.syslib allocates through malloc / free and this program allocates through
pvPortMalloc / vPortFree — a program has one heap, so a library compiled against
another cannot be linked into it. Rebuild the library against this one

That refusal is sharper than the one for a mismatched target, and deliberately so: an artifact for the wrong machine is eventually refused by a linker that cannot read the object at all, while an artifact for the wrong allocator is refused by nothing. Recording the name is the only place it can be caught.

The standard module is under the same rule and needs nothing done about it — its cache is keyed by the pair among the other things it is keyed by, so a program that names an allocator gets a standard module built for that allocator, built on demand and announced on stderr.

What it does not do

Naming the pair says which functions the program uses. It says nothing about where the program may use them, and that distinction matters on a real RTOS: pvPortMalloc suspends the scheduler and is not usable from an interrupt handler, while sysl allocates implicitly — a string operation, a growing buffer, a box. Code reachable from a handler is the caller’s to bound, and @no_alloc is how it is bounded.

Headers a package needs and does not carry

A capability is answered by the target, and there is nothing for anybody to go and do. A header is answered by a path on a machine the package has never seen, and that is the other thing a package may need of its environment.

Most bindings carry the C they include — sqlite3, qcbor, monocypher and termbox2 all vendor their library’s source, so a relative include resolves and no flag is involved. A package binding something the consumer’s build system owns cannot do that. pico2 is the case: lwIP’s headers live in an 81 MB pico-sdk clone that only the consuming project has, and vendoring a copy would be vendoring the thing the package exists not to reimplement.

requires {
  headers { lwip = "lwIP's headers — the pico-sdk carries them at lib/lwip/src/include" }
}

The consumer says where they are:

sysl build . --include-path lwip=$PICO_SDK_PATH/lib/lwip/src/include

The package names the requirement and the driver supplies the path. That is the same split as @link("png") and --link-path: a path in a committed file would be one machine’s directory layout published as though it were a property of the package, and an environment variable read out of the consumer’s shell would be a build that works for whoever wrote it.

The value is the reason, not a path. It is prose for a person — what the headers are and where they come from — quoted back at whoever has to find them. A name on its own would report that something called lwip is missing and leave the reader to work out what that is.

What it buys is the refusal

--include-path always worked, and a consumer who passed it always built. What did not exist was any way for the package to say it needed one, so a build without the flag failed inside a C compiler that names the header and knows nothing about sysl, the package, or the flag:

fatal error: 'lwip/tcp.h' file not found

Now the build stops before clang runs, naming all three:

github.com/sysl-lang/pico2 needs the 'lwip' headers and nothing supplied them — lwIP's headers,
the pico-sdk carries them at lib/lwip/src/include. Say where they are with
'--include-path lwip=<dir>'

A bare --include-path is not an answer, deliberately. The check is about what a build says it has rather than what it might happen to find; reading a bare path as an answer would let a consumer satisfy the requirement by accident and never learn they had.

It is asked only where C is actually compiled, so emit-llvm and prove are not held up by a path they would never open.

build-lib compiles C, so it is asked too — and it is asked for its own manifest and nothing else. That is the narrowest scope of any command here, and it follows from the same rule rather than being an exception to it: build-lib compiles the C of the tree it was handed and no other, so a --lib source root’s declaration is not charged to a library built against it. That build never opens the root’s header, and the root is asked for it when the root is built itself.

This is the road a package is packaged by, so it is the one that matters most to whoever is publishing one — and it was the last to be asked. Until it was, building a declaring package into an artifact answered with fatal error: 'lwip/tcp.h' file not found out of the package’s own shim, and, worse, a bare --include-path satisfied the requirement in effect, because nothing was asking. A requirement that can be met by accident on the machine that built the artifact and nowhere else is exactly what the paragraph above exists to prevent.

It is asked whichever way the package arrived

A package reaches a build by three roads, and the declaration is worth the same on each — though they do not all need the same thing from it.

how the package arrived	what happens
named in `dependencies`	its manifest comes with the graph, and the requirement is asked
handed over as a `.syslib`	nothing is asked, because nothing is needed
given as a `--lib` source root	its manifest is read for this, and the requirement is asked

The artifact needs no header at all, which is worth knowing before going to look for a flag to pass. build-lib measures a c const and a c type while it builds and stores the answer — the value, and the integer a typedef turned out to be — rather than the C that produced it, so a consumer of a .syslib needs neither a clang nor the library’s headers. There is nothing left to require.

The header requirements, the allocator and the dependencies are read from a --lib root. That flag names a source root, which need not be a package at all, and one that is not has nothing to declare — so a root with no package.hocon goes on building exactly as it always did.

All three are read for one reason: each is a property of the package rather than of the road the package arrived by. A directory handed over with --lib is the same package as one named by a coordinate, so it brings its heap, its header requirements and what it is written against either way.

The allocator used to be read only from a coordinate, and the two roads then disagreed in silence: the package’s own objects came out of its heap and every string, Buf and box in the same program out of libc’s, with nothing said at any point. A silent mixed heap is worse than a rule somebody has to know, which is what decided it.

The dependencies were the last of the three. Read only by coordinate, the same directory gave a build the package’s sysl and nothing it was written against, and what came back was a page of unresolved names pointing into a package you did not write — naming neither the missing dependency nor a flag. They are fetched now, into the same graph the project’s own go through, so version selection sees every claim at once and a package two roots share is one copy at one version. What a root’s manifest binds is reachable from your own files as well, which is no more true of a dependency’s name than it always was of the root’s own modules.

build-lib is the one command that refuses them instead, and that is not an inconsistency: it compiles one tree into an artifact for one machine and does not reach the network, so it has nothing to fetch with. It says so, and names --lib as what to write instead.

What is still not read is the rest of the manifest. A root’s capabilities are the program’s to state, and they have none of the one-answer-per-program character that makes the allocator settle for everybody.

A library the machine already has, found by asking it

A headers requirement puts the path in your hands, which is right when the headers belong to your build — lwIP’s live in your pico-sdk clone and nothing else could know where that is. It is more than is needed for an ordinary installed library, because most of them answer the question themselves. pkg-config is how: a .pc file installed beside the library says where its headers are and what its link line is, on this machine.

requires {
  pkg_config { sdl3 = "SDL3 — brew install sdl3, or Debian's libsdl3-dev" }
}

sysl run .

That is the whole command. Before this, the same program wanted the layout of your machine typed out — and typed out correctly, which for the box2d demo meant knowing that cairo’s headers are in include/cairo while SDL3’s want the directory above SDL3:

sysl run . --link-path /opt/homebrew/lib \
           --include-path cairo=/opt/homebrew/include/cairo \
           --include-path sdl3=/opt/homebrew/include

The split is the same one as before: the package names the requirement and something else supplies the path. What changed is who that something else is — the machine, rather than a person copying its layout onto a command line. Nothing the package wrote is a path, and no code the package supplied is run; the compiler asks a well-known tool a question, exactly as it already asks clang what a c const measures to.

One declaration answers both halves. A package binding an installed library needs its headers to compile and its library to link, and having one of those is not a build. --cflags feeds every C compilation in the tree and --libs feeds the link line — including the -Wl,-rpath that decides whether a dynamically-linked program finds its library at run time, which is the part a hand-written --link-path quietly leaves out.

The name is the one pkg-config files it under

It cannot be derived, and the two things it might have been derived from are both wrong. The @link directive is one: the sdl3 package writes @link("SDL3") and the module is sdl3, because -lSDL3 and sdl3.pc are two naming conventions that happen to share a word. A headers requirement’s name is the other, and worse: a name that happened to match some .pc file on your machine would satisfy a requirement nobody answered — met by accident on the machine that built it and nowhere else.

What happens when it cannot be answered

Your own flags win and stop the probe. --include-path <name>=<dir> answers this exactly as it answers a header requirement, so a hermetic build, a hand-built prefix or a machine with a broken .pc is never at the mercy of what happens to be installed.

A build for another machine is not asked at all. pkg-config answers for the machine it runs on, and a cross build’s headers and library are the target’s. A freestanding program compiled against your laptop’s /opt/homebrew would link and be wrong somewhere you cannot see it, so a target that is not this machine is refused rather than answered:

this project needs the 'sdl3' library and this is a build for 'thumbv7m-freestanding' rather than
for this machine, so there is nothing to ask where it is — SDL3 — brew install sdl3. Say where it
is with '--include-path sdl3=<dir>' and '--link-path <dir>'

A machine without pkg-config is exactly where it was before, with the refusal the previous section describes plus a sentence naming what was looked for. The two failures are told apart, because they send you to different places: pkg-config missing is one install away and says nothing about the library, where a pkg-config that does not know the module means the library itself is not there.

macOS ships no pkg-config and the libraries do not bring one — brew deps cairo lists fifteen packages and it is not among them — so brew install sysl installs it as a dependency of the compiler.

Dependencies

A dependency is a git repository and a version. There is no registry, no account to create, and no name to reserve.

dependencies {
  json { git = "github.com/edadma/sysl-json", version = "1.4.0" }
}

The coordinate is cloned over HTTPS and the tag v1.4.0 is what gets read. A path dependency names a directory instead, for a package being developed alongside its consumer:

dependencies {
  helper { path = "../helper" }
}

sysl build fetches whatever the machine has not got, so adding a dependency is an edit to this file and nothing else. Fetched packages are cached under the machine’s cache directory and shared by every project on it.

A coordinate is identity, not a URL. https:// on the front is refused rather than stripped: the coordinate is what a package’s module names are derived from, so two spellings of one package would link as two incompatible copies of it.

The major version rides in the coordinate

From the second major version on, a breaking change makes a new coordinate:

dependencies {
  json { git = "github.com/edadma/sysl-json/v2", version = "2.1.0" }
}

A module’s name is part of every symbol it emits, so two versions of a module named json would emit the same symbol names for different code. One version per module is where the linker puts things whether or not anyone plans for it, and /v2 is what planning for it looks like. 0.x and 1.x ride in the bare path.

Which version you get

The version chosen for a package is the highest minimum anybody asked for — not the newest that exists:

your project     depends on json 2.1.0
       json 2.1.0 depends on buf  1.2.0
       text 3.0.0 depends on buf  1.4.0
                                  ------
                       buf resolves to 1.4.0

Three things follow from that, and they are the reason for it:

Adding a dependency cannot silently upgrade an unrelated one. The only versions in play are ones some manifest names.
Builds are reproducible without a lockfile, because the selection is a pure function of the manifests.
Upgrading is an edit. Nothing quietly walks everything forward; you raise a minimum here and the graph is recomputed.

The cost is the honest one: you do not automatically get the newest patch release.

What a dependency’s modules are called

A package is a tree of modules, and its modules come in under their own names. A module is a directory of source files, so a package holding sqlite/ is reached exactly as its own documentation shows it:

sqlite.open("db.sqlite")

The name is the module’s, not the package’s — sqlite3’s package is called sqlite3 and its module is sqlite, and reaching the second does not mean saying the first.

A name is a module path, not a first segment. Every package published under sysl-lang puts its source under a reverse-DNS prefix, so what it offers is a dotted path:

sh/sysl/table/table.sysl       →  sh.sysl.table

sh/ and sh/sysl/ hold no source, so neither is a module and neither is a name that package offers. Two packages laid out this way therefore do not collide, which is the point of the convention: a project may depend on sqlite3, linenoise and table at once and import all three under the names their own documentation shows.

A binding covers the module it names and everything below it, so sh.sysl.table.Style reaches the same package and keeps its tail.

Two packages cannot quietly share a name. If two dependencies both offer a json, or one offers a json and your own project has a json/ directory of source, the build stops and says so rather than picking one. So does one offering a path inside another’s — a package offering sh.sysl and one offering sh.sysl.table share no name, but an import of sh.sysl.table could be read as either, and resolving it to the longer would be a rule nobody wrote down.

“Your own modules” includes every --lib source root, since a root’s modules are filed under your project’s names rather than under a prefix of their own. So a root that declares a dependency offering a name the root itself declares is refused in the same words, and the message names the root as you gave it. Without that, the root’s own module answered, its dependency’s was unreachable, and the build was green — the silent winner the whole rule exists to refuse.

Write a mount to say what one of them is called here:

dependencies {
  theirs { git = "github.com/edadma/sysl-json", version = "1.4.0", mount = "ejson" }
}

which hangs that whole package under one segment, so its json is ejson.json and your own json is untouched. A mount is yours alone: another project may mount the same package differently, and both still link one copy of it.

`sysl.sum`

sysl.sum sits beside package.hocon and should be committed. It records a content hash for each package and version the project resolved, and a fetch whose content does not match is refused:

github.com/edadma/sysl-json v1.4.0 sha256:6f1b…

What it protects against is the class of change a version number cannot describe — a tag moved to point at different commits, a repository rewritten, a mirror serving something other than what the author published. In all three the version number is exactly what it was.

It is not a lockfile: version selection is already a function of the manifests, so there is nothing to record about which versions were chosen. The first time a package is seen it is trusted and recorded; reviewing the line that appears is the part a person does. A path dependency gets no entry, because a directory beside you is expected to change.

No build scripts, ever

A package cannot run code at build time. Not a hook, not a script, not a plugin. sysl add and sysl build read and write files and run nothing.

Most of what other ecosystems need build scripts for is compiling vendored C, and sysl already compiles a library’s C declaratively — the linker inputs a package needs are @link attributes in its source, not a program that computes them. What that buys is most of the supply-chain story: a package that cannot execute during installation cannot exfiltrate anything during installation.

Modules and the library

2026-08-16T01:26:07.924728867Z

Every program on this site so far has been one file with no header, and that is not a special form — it is a module that happens to be unnamed. This chapter is what happens when there is more than one.

A module is a directory

The files under oskit/arch/ make up the module oskit.arch; the files under std/fs/ make up std.fs. Every declaration in every file of the directory is a member of the one module, so splitting a growing module into more files adds no new module and changes no import.

Each file states which module it contributes to, and the compiler checks the name against where the file sits:

module oskit.arch

halt()
    print("halted")

That is Scala’s package and Go’s directory-package, and it pays off directly for the target: an OS subsystem is a directory — an arch layer, a server, a driver — so the module is the subsystem, and the subsystem is the unit an importer depends on.

A file with no header at all is in the anonymous root module, whose name is the empty path. Nothing can name it, so its declarations are visible to its own files and to nothing else — which is the right way round for the place a program starts, and it is why a one-file program’s names sit exactly where they always did.

Where a program starts

A top-level statement is not a declaration. A declaration is hoisted and belongs to the module as a whole; a statement runs, and running happens in an order — so one file of a program carries the statements it runs, and a second that carries any is an error naming both.

That file is the program’s entry file, and its top level is a body: a val or var there is a local initialized where it stands, and a function there reads the bindings above it.

A program may instead declare main, which is the other way of writing the place a program starts:

main(args: []string)
    print("the work runs here, with", args.len, "argument")

the work runs here, with 1 argument

A program starts in one place, so it writes one or the other and never both. What main gets at that a statement cannot is the arguments: a statement has nowhere to receive them, because it is not a call and has no parameter list.

A program in which no file carries a statement is a complete program that does nothing. That is what a tree of pure declarations compiles to, which is what it should compile to — a library is not an error.

Visibility

A top-level declaration is public by default. Two modifiers restrict it, and they are one keyword with an optional scope:

form	visible to
`private`	this file
`private[own_module]`	every file of this module
`private[ancestor]`	the named ancestor module and its whole subtree
(unmarked)	any module that imports it

module oskit.arch

exported() -> int = 42

private lookup(fd: int) -> int = fd

private[arch] reset(c: int) = print("reset", c)

The bare form being file-scoped is a deliberate divergence from Scala, and it costs nothing: module-private is exactly private[own_module], the degenerate case of the scoped form. What it buys is the one level that provably never crosses a file boundary, which is the level at which a declaration can be fully inferred and given internal linkage.

The honest cost is that the everyday module-internal helper is now the wordier private[arch] rather than a bare private. The alternative spends a whole keyword to save a bracket.

A restriction is about naming, not existence. A file-private declaration still belongs to its module and still spends its name there, so a sibling file cannot declare something else of that name.

Hiding the shape is a different axis

Visibility decides who may say a name. It does nothing about a type’s layout: a private field still occupies its place, counts toward the size, shifts the fields after it, and takes part in the ABI. Anyone who can name the type can still be built against its shape.

opaque is the other axis. Inside the declaring module the struct is ordinary:

opaque struct Conn
    fd: int
    live: bool
end Conn

open(n: int) -> Conn = Conn(n, true)

describe(c: *Conn) -> string = "fd " + str(c.fd)

var c = open(7)

print(describe(&c), c.live)

fd 7 true

Outside it, the type is incomplete — the same thing C’s struct foo; is — and the only thing anyone may say about it is *Conn:

import net.Conn

var c: Conn        // refused: no size out here
var p: *Conn       // fine — a pointer needs no shape

Everything refused outside is refused for one reason: constructing, reading a field, taking an element, a by-value parameter or result, sizeof, alignof, offsetof, a by-value self method. Each needs a size or an offset, and the size is exactly what is being withheld — so it is one rule rather than fifteen.

The by-value self method is the case worth pointing at, because it looks like an ordinary call and is not. The function was compiled by the library, but what crosses the boundary is the caller’s copy, laid out as the fields stood when that caller was built — so adding a field would break it silently, which is the failure the modifier exists to prevent. *self and &self need no shape, and are what an opaque type’s methods use.

A struct may also be opaque with no body at all, which is how a C handle is bound: nothing in sysl lays a Dir out, and the storage is libc’s.

The payoff is that a field may move with nothing downstream recompiled. The reach is the declaring module exactly — not a subtree, the way private[M] widens — because the files of a module already share one scope and are already the unit that recompiles together.

Imports

A public member is always reachable fully-qualified — sysl.math.max(2, 7) needs no import at all. Nothing is required to see a member; an import exists only to shorten the reference:

import sysl.math.{max, min}
import sysl.math as m

print(max(3, 9), min(3, 9))
print(m.max(2, 7))
print(sysl.math.max(1, 4))

9 3
7
4

An import is a dotted path through the module tree, and how the path ends decides what you get:

import sysl.math.max              // max(a, b)      — one member, unqualified
import sysl.math.{max, min}       // several
import sysl.math.*                // every public member
import sysl.math                  // math.max(a, b) — the module itself
import sysl.math.{max as bigger}  // a member, renamed
import sysl.math as m             // m.max(a, b)    — the module, renamed

Ending the path at a member binds that member under its own name, so calls to it lose their qualifier entirely. The braces do that for several members at once, and * for every public member of the module.

Ending it at the module binds the module’s last name segment instead — so sysl.math becomes math, and calls keep exactly one level of qualification. That is the self-documenting middle ground: math.max says at the call site where the name came from without listing members up top, where the wildcard says nothing and the explicit list has to be maintained.

as renames whatever the path ended at, member or module. It is what you reach for when two modules offer the same name, and the only way to resolve that collision without writing the full path at every use.

If you happen to know Scala 3, these are its import forms unchanged — including as and *.

Imports usually sit just below the header, but one may also appear inside a block, scoped to it, for a name wanted in one function only.

Resolution is innermost-first: a local binding shadows an imported name, and the fully-qualified path is always available to break a tie. Two wildcard imports offering the same name make an unqualified use of it an error naming both — including when one of them is the standard library, which is auto-imported into every file. That is deliberate: the alternative is a precedence tier that makes the library quietly lose to whatever a program imported, which is the silent capture the error exists to prevent.

Capabilities ride along

A capability clause narrows a module, and it is written in the header on a line of its own:

module oskit.arch
@no_alloc

halt()
    print("halted")

Because the module is the directory, the clause is a property of the directory — so it must appear in every file of the module, and the compiler rejects a module whose files disagree. The redundancy is the point: you can never open a file in a no alloc module and fail to see that it is.

The other direction is requires, and the standard library uses it: sysl.fs is requires os, because a filesystem is something the environment either has or does not, and everything under sysl.posix — threads, tty, rand — is requires posix, because pthreads, termios and getentropy are what those modules are made of. A freestanding target importing either is told so at the import, and the namespace is that same fact put where a reader meets it first.

That is also why the atomics live apart from the threads. sysl.sync requires nothing, so a module that has given up both its allocator and its operating system can still import it — which is the point, since a spinlock and an atomic counter are what a kernel has before it has anything else. A module’s requirement is module-wide, so one type in there needing a scheduler would have taken the whole module out of the kernel’s reach.

Propagation is over the module graph, which is acyclic — so a module’s effective requirement is computed in a single sweep rather than an iterated fixpoint, and a no alloc module importing one that requires an allocator is an error at the import, not deep in code generation.

Naming a library the linker needs

The header has one other inhabitant. An extern says which symbol it wants and never where that symbol lives, so a module binding a C library says it with link:

module image.png
@link("png")
@link("z")

extern "png_create_read_struct" create(ver: *u8, err: *u8, fn: *u8) -> *u8

A directive names a library, never a flag, and that is the whole design. Where a library lives is a property of the machine being built for: the mathematics is a separate file on Linux, part of libSystem on macOS, inside the CRT on Windows, and absent entirely from a freestanding target that has no libc to hold it. A directive spelling -lm would be right on one of those and wrong on three, and the author could not be told so by any compiler running on the machine that wrote it — the link that fails is somewhere else. So the file names m and the driver decides what that becomes, including deciding it becomes nothing.

Unlike a capability, link is not required to agree across a module’s files, because it describes something narrower: a capability is a property of the whole module, while a link requirement belongs to the externs in one file — and a module that keeps its foreign declarations together has nothing for its other files to repeat.

The standard library

The library is a module, not a set of names threaded in beside your program. sysl itself is auto-imported into every file, which is why nothing so far has had to import anything to call print — and what earns that is that it holds what the language desugars onto, which a program cannot avoid needing. Everything else is a submodule you ask for by name, because a submodule is an offer rather than part of the language.

module	what is in it
`sysl`	`print`, `Option`, `Result`, `Display`, `Writer`, `Iterate`, the operator traits
`sysl.buf`	`Buf[T]`, the growable sequence, and `ByteSink`
`sysl.text`	`from_utf8`, `StrBuilder`, `Chars`, `CString`
`sysl.io`	`Reader`, `stdin()`, `lines()`
`sysl.fs`	files and paths — `read_text`, `write_bytes`, `exists`, `rename`, and `IoError`
`sysl.math`	`max`, `min`, `pi`, the float functions, the integer traits `Signed` and `Bits`, and the integer arithmetic above them — `pow`, `gcd`, `lcm`, `divmod`, `is_power_of_two`, `next_power_of_two`
`sysl.regex`	POSIX Extended Regular Expressions — `regex`, `Regex`, `Match`
`sysl.sync`	`Atomic[T]`, `SpinLock`, and the five memory orderings — requires nothing
`sysl.posix.threads`	`spawn`, `Thread.join`, `yield_now`, and `Mutex[T]`
`sysl.args`	command-line options — `Scan`, `Cli`, and `args_of` for a raw `argv`
`sysl.sys`	the platform seam — what a freestanding target replaces

The split is one rule: what a program cannot avoid needing arrives free, and what it has to ask for it asks for. An array literal and a for loop are in the language, so nothing imports them. A sequence that grows is a thing a program decides it wants, so it says so:

import sysl.buf.{Buf, buf}
import sysl.text.str_builder
import sysl.math.max

var widths: &Buf[int] = buf()

widths.push(3)
widths.push(11)
widths.push(7)

var widest = 0

for i in 0..<widths.len() do widest = max(widest, widths[i])

var b = str_builder()

b.push("widest of ")
b.push(str(widths.len()))
b.push(" is ")
b.push(str(widest))

print(b.finish())

widest of 3 is 11

Nothing there is a language feature. Buf is ordinary sysl over a slice it replaces when it runs out; StrBuilder is ordinary sysl over a Buf[u8]; and both are importable rather than free because a program that wants neither should link neither.

Reading input

sysl.io is the one that needs a word, because it is where the iteration protocol earns its keep:

import sysl.io.{stdin, lines}

var src = stdin()

for line in lines(&src)
    print("read:", line)

lines hands back a cursor, and for walks anything implementing Iterate — so the loop reads a line at a time out of a 4 KiB chunk rather than pulling the file into memory. A Reader is a trait with one method, so the same loop reads a socket, a ring buffer, or a test fixture, and a freestanding target substitutes one body.

Separate compilation

A module is compiled once and linked, which is what the acyclic import graph buys. The standard library itself is an artifact — a real ar archive — and the compiler builds it for you when nothing usable is at the default path, announced on stderr and in well under a second. It lives in your cache directory under a fingerprint of the library it was built from, so every project on the machine shares one and a new compiler makes its own without disturbing the old. There is no bootstrap step to run and none to remember.

Next: contracts — types that carry a rule, and functions that state what they require.

Modules

2026-08-16T01:26:07.924728867Z

A module is a directory of source files, and its name is that directory’s path relative to the project root, with the separators read as dots. The files under oskit/arch/ make up the module oskit.arch; those under std/fs/ make up std.fs. Every declaration in every file of the directory is a member of the one module, so splitting a growing module into more files adds no new module and changes no import.

Each file states which module it contributes to, in a header, and the compiler checks the declared name against where the file sits:

module oskit.arch

halt()
    print("halted")

That is Scala’s package and Go’s directory-package. It pays off directly for the target: an OS subsystem is a directory — an arch layer, a server, a driver — so the module is the subsystem, and the subsystem is the unit an importer depends on and the unit a capability clause narrows.

The files of one module must all name it the same way, because the module is the directory, so its name is a property of the directory rather than of any file in it. Each file is held to the name its location gives it, which is the stronger rule: the file that strayed is reported on its own line rather than as a disagreement with whichever sibling happened to be read first.

A file with no header is in the anonymous root module, whose name is the empty path. That is what lets a program be one file with no ceremony — the one-file case is not a special form, it is a module that happens to be unnamed. And because its name is empty, nothing can name it: its declarations are visible to its own files and to nothing else. That is the right way round for the place a program starts — the root reaches down into the modules it is built out of, and they do not reach back up.

A module and a type of its parent may not spell one path. A dotted reference takes the longest prefix that names a module, so a module geom.Point alongside a type Point in geom would take geom.Point.dist outright and leave the type’s member no spelling at all. The two stay distinct declarations either way — what collides is the path a program writes — so the second is refused with a diagnostic rather than settled by a silent choice.

Visibility

A top-level declaration is public by default. Two modifiers restrict it, and they are one keyword with an optional scope:

form	visible to
`private`	this file
`private[own_module]`	every file of this module
`private[ancestor]`	the named ancestor module and its whole subtree
(unmarked)	any module that imports it

module oskit.arch

exported() -> int = 42

private lookup(fd: int) -> int = fd

private[arch] reset(c: int) -> int = c

private[oskit] struct FrameHeader
    magic: int
end FrameHeader

M resolves innermost-outward. The argument is a simple name, not a path, matched against the enclosing module names from the declaring module outward, first hit winning — so private[geom] inside geom/mesh/geom/tri binds to the nearer geom. A name matching no enclosing module is an error; there is no way to name an unrelated module, so a visibility scope is always a contiguous subtree containing the declaration. Because the name is resolved where it is declared, moving a subtree elsewhere does not change what its internal annotations mean.

Why file-scoped and not module-scoped. This is a deliberate divergence from Scala, where private means the enclosing class or package. Making the bare form file-scoped costs nothing in expressiveness — module-private is exactly private[own_module], the degenerate case of the scoped form — and it buys the one level that provably never crosses a file boundary, which is the level at which a declaration can be fully inferred and LLVM internal linkage applies. The cost is honest: the everyday module-internal helper is private[arch] rather than a bare private, so the common case is the wordier one.

There is no pub keyword. Rust makes a declaration private until pub; Scala and Kotlin make it public until restricted, and that is the precedent here. The low-ceremony common case — a small module whose declarations are meant to be used — writes no modifier, and encapsulation is the deliberate act.

A restriction is about naming, not about existence

A modifier decides who may write a name; it never makes a second namespace. A file-private declaration still belongs to its module and still spends its name there, so a sibling file cannot declare something else of that name. The five declaration forms take a modifier; an impl takes none, having no name for one to restrict; and an enum’s variants carry the enum’s own, since a type nobody outside may name is not one whose variants they may construct.

A name a file may not reach is not a candidate for it. Resolution passes over one and goes on through the file’s imports rather than stopping there — a file that wrote import util.width said which width it meant, and a sibling file’s private helper of that name is not an answer to it. Where nothing else answers at all, the restriction is then reported, because at that point it is the whole story and a better one than an undefined name.

A wildcard offers only what is visible; a selector is refused where it is not. A wildcard has claimed nothing, so a name it cannot see is simply not among what it brings in, and cannot make another module’s name ambiguous either. Naming something deliberately is the opposite case, and being told at the import that it is private is more use than an undefined name at every shorter spelling it would have bound.

A declaration may not be more visible than the types it names

What a declaration says about itself has to be as nameable as the declaration is. A private struct beside a public function returning it would hand every module a value of a type none of them may name: they could hold it, pass it on, and read its fields, and the one thing they could not do is write the type down.

private struct Point
    x: int
end Point

make() -> Point = Point(1)

print(make().x)

'make' is public, but its result names 'Point'

The comparison is between two reaches, and every reach is a contiguous region because private[M] may only name an enclosing module: a type restricted to a subtree may stand in a signature restricted to that subtree or to anything inside it, and never the other way round. A bare-private declaration is exempt in every case — it is read in one file, and a type it can name at all is visible there.

“Signature” is the shorter word for it, and the rule is not about signatures. It is about everything a declaration says about itself, so it reaches the forms that have no signature at all: a field, an enum variant’s payload, a type parameter’s bound and its default, and the declarations that are a name and one type — a const, a module-level val and an extern variable. It reaches everything a caller has to be able to write: a struct’s fields and a variant’s payload, since neither has a visibility of its own; a type argument, since Box[Point] names Point as much as a bare Point does; a trait behind a memory mode; a member of a type or a trait; and a bound, since a trait a caller cannot name leaves it unable to say what is being asked of it.

The const was not always among them: a constant was held to being a scalar, and every scalar is a builtin nobody may restrict, so there was nothing to reach the question with. A transparent subtype of a scalar is a constant’s type now, and that is a declared type somebody may make private — so the rule stated in advance for a hole that did not yet exist is the rule that closes it.

An impl block is outside the rule, in both directions. Implementing a private trait for a public type adds a member nobody outside can ask for by trait; implementing a public trait for a private type makes a public promise about a type that stays unnameable. Neither leaks a name, and a private type reaching a caller through a trait’s signature is a leak in the trait, which is where it is reported.

Rust refuses this and Scala allows it; this follows Rust. The refusal is what makes private mean something a reader can rely on, and it is additive in the safe direction: forbidding it now rules out nothing a later rule would have had to keep allowing, while allowing it and tightening later would break programs.

Anything visible outside its file states its types

A declaration visible beyond the file that declares it carries explicit types. Inference is available only at the bare-private level — the one level that provably never crosses a file boundary — which is why the two rules are really one.

Most of it the syntax already enforces: parameter and field types are mandatory, and a return type is written or its absence means unit. What the rule genuinely binds is the two declarations that are a name and a type — a const and a module-level val, both below.

Why: it makes interface extraction parse-only. A file’s exported surface can be read off its syntax tree without resolving a name, checking a body, or having compiled anything the file imports. That is what a fast, parallel, and eventually incremental build rests on. Scala infers types for public members and pays for it with a far heavier extraction step; this is a deliberate divergence, and it is cheap here precisely because sysl’s signatures were already explicit for other reasons.

Imports

A module reaches another module’s members two ways, and the first needs no import at all.

import sysl.math.{max, min}

print(max(2, 7), min(2, 7), sysl.math.max(10, 3))

7 2 10

A member is always reachable fully-qualified by its module path. Nothing is required to see a public member; an import exists only to shorten the reference.

An import is a dotted path through the module tree, and how the path ends decides what you get:

import sysl.math.max              // max(a, b)      — one member, unqualified
import sysl.math.{max, min}       // several
import sysl.math.*                // every public member
import sysl.math.{max as bigger}  // a member, renamed
import sysl.math.max as bigger    // the same, unbraced
import sysl.math                  // math.max(a, b) — the module itself
import sysl.math as m             // m.max(a, b)    — the module, renamed

Those are Scala 3’s import forms unchanged. The unbraced as belongs to the bare-path form alone, where exactly one thing is being named: after a wildcard there is nothing for one word to rename, and a selector list carries its own as per name, so both are refused rather than quietly ignored. It renames whatever the path turned out to name — a member or a module — because which of the two it is is settled by the same longest-prefix rule everything else uses, and a reader wanting a shorter word should not have to know the answer first.

A module brought in by name is a prefix wherever a written path is:

import sysl.math as m

print(m.max(4, 9))

import sysl.math makes math.max(p), math.Float, and [T: math.Float] all work, because the leading segment of a dotted reference is read through the imports where it is not already a module. Two rules keep those from ever both applying: a module reached by the name it already has asks for what is already true and binds nothing, and an import may not be given a name that a module path already begins with. The second is a refusal rather than a precedence rule on purpose — a binding that is both would make fs.read mean one thing in a file that imported fs and another in the file beside it, and as costs one word.

Resolution

An unqualified name is looked for in the module it is written in, then among the file’s imports, then in the library, and nowhere else. A sibling module’s names are not in scope unqualified, and neither are the root module’s, which have no path to be reached by at all.

Resolution is innermost-first. A local binding shadows an imported name; the fully-qualified path is always available to break a tie or reach a name deliberately not imported.

The three steps rank a name by where it was written, not by what kind of thing it is. A function, a const, a module-level val, an extern variable and an enum variant are different kinds of declaration, and a bare name may be any of them — a program’s own answers before an import’s, and an import’s before the library’s, whichever kind each one is. The library declares a stdout(); a program that declares storage of that name reaches its own, and the library’s is still there under the path that names it.

val stdout: int = 7

sysl.stdout().write("the library's\n".bytes)
print(stdout + 1)

the library's
8

situation	result
a wildcard offers a name that is also defined locally or imported selectively	the more specific one wins
two wildcards both offer one name	an unqualified use is a compile error naming both
two selectors bind one name, or two statements do	reported at the second import

A wildcard offers a name; a selector binds one. That is the whole of the difference: a wildcard neither collides with a selective import of a name it also offers, nor with a second wildcard over the same module, because it has claimed nothing.

import sysl.math.*

max(a: int, b: int) -> int = 99

print(max(1, 2))

Binding one name twice is a mistake, and is reported at the second import rather than at whichever use first found two answers:

import sysl.math.max
import sysl.math.max

print(max(1, 2))

'max' is already imported

The standard module counts as one of those wildcards. sysl is auto-imported into every file, so a written import a.* where a declares an Option of its own is the two-wildcard case, and an unqualified Option in that file is a compile error naming both — it does not shadow the library’s. That is deliberate: the alternative is a precedence tier that makes the library quietly lose to whatever a program imported, which is the same silent-capture problem an explicit conflict is being reported to avoid.

Every step is filtered by visibility, the library’s included. A member the library keeps to itself is not an answer to a program’s bare name, exactly as a sibling file’s private helper is not.

A dotted reference names a module by the longest prefix of it that is one. A program holding both a and a.b reads a.b.f as a.b‘s f rather than as a‘s b. Everything left of the module prefix is the ordinary form — read(…), Point(…), Shape.Circle(…) — which is why qualified access needed no second resolution path beside the unqualified one.

An import binds a name, not a kind. The same spelling may be a type in one module and a function in another, so what an import records is which path a name stands for; which of them a use meant is settled by what that position asks for. One import therefore serves a type, a function, a trait, and an enum variant without saying which it expected to be.

Where an import may stand

Imports normally sit just below the module header, but — following Scala — an import may also appear inside a block, scoped to it, for the case where a name is wanted in one function only:

widest(a: int, b: int, c: int) -> int
    import sysl.math.max

    max(max(a, b), c)

print(widest(3, 11, 7))

A block import lasts as long as the block’s local bindings do and shadows whatever the file imported under the same name. It takes effect where it is written: the statements above it have imported nothing.

An import is not an executable statement, whatever it looks like — it binds a name and runs nothing, so a file may import freely without becoming the one file of the program that carries its statements.

A file’s imports are not its dependency list. Because a qualified reference needs no import, a file can depend on a module without naming it in any header — the dependency appears only in a body. Two consequences follow, and they are the price of the convenience above: building the module graph requires parsing rather than a header scan, and the cycle check below needs real resolution rather than a textual match, since a local named std makes std.fs a field access and not a module reference.

Capabilities are a module property

A capability annotation narrows the module, and it is written in the file header below module, each on a line of its own:

module oskit.arch
@no_alloc

Because the module is the directory and the capability is a property of the module, a narrowing must appear consistently in every file of the module — a module whose files disagree is rejected. The redundancy buys local legibility: you can never open a file in a @no_alloc module and fail to see that it is one. A file that declares no module may still carry one, since the anonymous root module is a module like any other.

The other direction is @requires(...), which takes a list because a module often needs more than one capability at once — the POSIX regex binding is @requires(heap, posix), since a regex_t is caller-allocated and regcomp is POSIX.

The heap has two names, and they say different things. The capability is heap and the clause that gives it up is @no_alloc:

heap names a facility — whether the machine being built for has one. It sits beside os and posix, and it is what a project states in package.hocon, because whether there is a heap is a project engineering decision.
@no_alloc names conduct — a promise this module’s code does not allocate, and so does not need a heap to exist. A promise is about an action, which is why it reads as a verb.

So @no_alloc narrows away heap: I do not allocate, therefore I do not need one. Each spelling is refused where the other belongs, naming it, since somebody who wrote one meant the other. The other three capabilities need only one word, because for them giving the facility up and not using it are the same act.

What @no_alloc promises, exactly: no execution that begins in this module’s own code makes heap storage. It is a portability claim — this module can be compiled into a project that has no heap — and its worth is that the compiler holds you to it while you are developing on a machine that does have one, rather than at the far end when you first build for the board.

They are annotations rather than grammar, which is what keeps alloc, no and requires available as ordinary names; see attributes.

@link is the header’s other inhabitant and is deliberately not held to agreeing. @link("z") names a library the file’s externs need, and the files of a module may each name their own — because what is being described differs. A capability is a property of the whole module, so files that disagreed would describe different modules, while a link requirement is a property of the externs in one file.

Propagation is over the module graph. A module’s effective requirement is its own uses plus the requirements of every module it imports, transitively, and the whole graph must fit the target. A @no_alloc module importing a @requires(heap) module is an error at the import, not deep in codegen. Because the graph is acyclic, propagation is a single sweep in reverse topological order — each module’s requirement set is final before any importer of it is visited — rather than an iterated fixpoint.

Two of the capabilities are checked differently, and the difference is worth knowing:

heap is finer than the declaration, and the standard library is why. Inferring it per module would put the whole of sysl on one side of a line that runs through the middle of it, since print allocates nothing and from_utf8 does — so the inferred half is asked of what a module calls rather than of which modules it depends on.
os and posix are exactly the declaration, since they gate which modules exist rather than what the language allows. The edge the rule is stated over is the reference graph rather than the import graph, which is load-bearing: a qualified path reaches another module with no import at all, so a rule about imports would have missed the shorter of the two ways to write the mistake.

The target’s half needs no clause at all

A module’s effective set is the target’s intersected with its own narrowing, so a capability is out of reach whichever of the two removed it — and both are answered at the same edge. @no_os is the half you can see in the file. The other half is the machine: on a target whose package.hocon says os = false, every module of the program is one that may not reach sysl.fs, with nothing written anywhere. A print(exists("/tmp")) in a program with no clause at all is refused:

error: this reaches 'sysl.fs', which requires 'os', and 'aarch64-none-elf' does not provide it — a
target's capabilities are what 'package.hocon' declares, so either this reference cannot be made on
this machine or the config is understating it

The message names the config rather than a clause, because that is where the answer is. Where the module did write @no_os, that is what it hears about instead — a reader sent to the config over something they said in their own header would go and change the wrong file.

A library’s own modules are exempt, and that is what makes the rule usable. The modules this question is asked of are the ones the compilation is producing: your program’s own. The standard module’s are not, and neither are a --lib source root’s or a fetched package’s. A library holding one POSIX module is not a library a POSIX-less target cannot use — it is a library one module of which your program cannot reach, and refusing at that module’s own @requires would refuse your build over a file you did not write and cannot change. So the refusal lands at the reference, which is a line somebody chose to write, and a program that never names the module hears nothing.

A generic answers for what it wrote, not for what its caller chose

A generic has no execution until a type is chosen, and whoever chose it is usually somebody else. So the promise is asked of the generic’s body as written, and a monomorphized instance answers for nothing at all. An allocator-free library may therefore be instantiated at a type whose impl allocates: the library promised nothing about a type it never saw.

module lib
@no_alloc

trait Sink
    put(*self, s: string)

twice[S: Sink](s: *S, msg: string)
    s.put(msg)
    s.put(msg)

put is the caller’s choice, so the program below is accepted although its impl allocates on every call — and it is accepted whether or not lib carries the clause, which is the point of it being a promise about lib‘s own conduct.

import lib.*
import sysl.text.cstring

struct Loud
    n: int

impl Sink for Loud
    put(*self, s: string)
        val c = cstring(s)
        self.n += 1

main()
    var l = Loud(0)
    twice(&l, "hi")
    print(l.n)

What the generic itself constructs is unchanged by the type argument, so it is charged where it is written, at every instantiation:

@no_alloc

boxed[T](x: T) -> &T = x

print(*boxed(3))

a reference needs an allocator, and this module declared '@no_alloc'

The same rule answers the two cases that look like ways around it. A trait’s default body is written once, in the trait’s own file, so a default that allocates is that module’s conduct however the implementing type is chosen. And a generic that reaches an allocator through another generic is still its own module’s, since a call in a generic body leads to the body that was written.

Nothing is given up where the promise is load-bearing. On a target with no heap every module is allocator-free with no clause written anywhere, so the module that chose the type is itself checked, and the walk from its body goes straight through the instance to whatever the type argument dragged in. What the rule gives up is a refusal aimed at the wrong file.

Platform selection — `<os>`

A module’s implementation may be split across operating systems by a directory named __<os>__. Such a directory selects but does not name: it is not a module, contributes no segment to any name, and the files inside it belong to the directory that holds it — exactly as if they had been written there.

sysl/fs/path.sysl              module sysl.fs, on every target
sysl/fs/__linux__/dirent.c     that module's C on Linux, absent everywhere else
sysl/fs/__macos__/dirent.c     that module's C on macOS

An importer writes import sysl.fs and names its members. Which files went into it is not something they can see or have to know — the module name is unchanged by the selection, and that invariant is the point of the feature.

The vocabulary is the operating systems a target can have, and no more: __macos__, __linux__, __windows__, __freestanding__. These are the same words #if linux uses, because they are the same idea. A directory of the __x__ shape naming anything else is an error — a misspelled __linx__ read as an ordinary module directory would compile nothing on any target and be reported, much later, as a missing function.

Exactly one operating system is true of a target, so at most one of these directories is selected at any one level. There is no precedence to remember and no tie to break. Files sitting directly in a directory are compiled for every target; the folders add to them rather than replacing them, so shared code stays where it is and only the part that differs moves.

sysl/posix/time/time.sysl              the whole API, written once
sysl/posix/time/__linux__/clock.sysl   the one primitive that differs
sysl/posix/time/__macos__/clock.sysl

That layering is how to use this: put the smallest private primitive in the folder and build the public surface once, outside it. A public API duplicated per operating system is two APIs, and they will drift.

A __<os>__ directory may not be nested inside another. Two axes — an operating system and a processor, an operating system and a libc — are not what this is for: the second axis is #if inside the file, or the C preprocessor inside the .c, which is where the world already keeps that knowledge.

A directory this target did not select is not read at all — not compiled, not analyzed, not parsed. That is what lets it hold a .c including a header this machine does not have, and it is also the cost: a Linux implementation is checked by a build on Linux and by nothing else.

It exists for the C

Everything above is true of .sysl files, and they are the smaller half. A module that differs by platform can usually say so with #if in one file — but a .c cannot carry a sysl attribute, and it will not be given a sysl-shaped name. The path is the only place its selector could go.

That is what a directory buys over a filename suffix, and it is why the suffix this section used to describe was never built: a grammar over sysl filenames would have selected everything except the one kind of file the feature is for. A library may carry C has the rest — and the standard library’s own sysl.fs.entries is the worked example, four lines of C under each of two folders, reaching a struct dirent whose layout no sysl file could honestly transcribe.

The module graph is acyclic

Two modules may not depend on each other, directly or through a chain. The dependency graph is a DAG, and a cycle in it is a compile error naming the modules on the cycle. This is Go’s rule, and a deliberate divergence from Scala, where a package’s compilation units may depend on each other freely.

The graph is over references, not over imports. A member of another module is reachable by its full path with no import at all, so a file can depend on a module its header never mentions. An edge is whatever resolution found — a call, a type named in a signature or a field, a trait named as a bound or behind a memory mode, a variant, a generic instantiated from elsewhere. An import contributes an edge of its own on top of those, because a file’s imports are meant to be readable as what it needs, and a dependency that came and went with a use would not be.

The anonymous root module sits outside the graph: nothing can depend on it, having no name for another module to write.

The standard module does not sit outside it. Writing print records an edge on sysl like any other reference, and that is deliberate. For a program the edge is inert — nothing in the library can point back at a program’s module, so it can never close a cycle — but within the library it is the whole of what keeps the split honest. sysl reaches sysl.sys for the C functions its printing is built on, so sysl.sys may name nothing of sysl‘s, which is why it holds the externs and nothing else. Read as edges: sysl.sys needs nothing; sysl reaches sysl.sys; sysl.buf reaches sysl; sysl.text reaches sysl and sysl.buf; sysl.io reaches all four. Every edge runs away from the standard module and none runs back, which is what makes any of them removable from a program that never asks.

Three things follow from acyclicity:

Modules can be compiled in dependency order, and independent modules in parallel. A topological sort exists, so a module’s imports are all fully known before it is checked. A cyclic graph would force the whole strongly-connected component to be checked as one unit — which is the same as saying it was never really more than one module.
Capability propagation is a sweep, not a fixpoint.
A cycle is a design error, and the fix is cheap. Two directories that need each other are either one module drawn along the wrong line — merge them, which changes no import, since a module is a directory and its file count is not part of its name — or they share something that belongs in a third module both import. Neither fix costs an importer anything.

Within a module, cycles are free and carry no ceremony. All files of a directory share one scope, so mutually recursive functions and types across sibling files need no forward declaration and no ordering: the analyzer collects every signature in the module before it checks any body. The restriction is on the directory graph, never on how a module’s own files refer to one another.

Where a program starts

A top-level statement is not a declaration. A declaration is hoisted and belongs to the module as a whole; a statement runs, and running happens in an order — and a module’s files have no order at all, being one unordered scope. So one file of a program carries the statements it runs, and a second that carries any is an error naming both. That file is the program’s entry file, and its top level is a body: what it declares is local to it, which the section below is about.

A program starts in one place. Statements at the top of a file and a main are two ways of writing that place, so a program that writes both is refused:

print("initialization")

main(args: []string)
    print("then main, with", args.len, "argument")

a program starts in one place, and this 'main' is a second — whichever of the two the program means, the other belongs inside it

Whichever of the two the program means, the other belongs inside it. What a main has that statements do not is a parameter list, so a program that wants the arguments writes main and puts inside it what it would otherwise have written above:

main(args: []string)
    print("initialization")
    print("then the work, with", args.len, "argument")

initialization
then the work, with 1 argument

What main gets at that a statement cannot is the arguments. A statement has nowhere to receive them — it is not a call, so it has no parameter list, and a program’s arguments are not a module-level anything. There are exactly two signatures:

main()
    print("no arguments wanted")

no arguments wanted

args is a slice of string. What the platform hands a program is C’s pair — a count and a vector of NUL-terminated byte runs — and neither appears in a sysl signature anywhere. The library converts the pair, finding each run’s end, validating its bytes, and copying them into strings the program owns, so an argument outlives the vector it came from and holds no memory the platform is still responsible for. The zeroth element is the program’s own path, because that is what the platform passes. An argument that is not UTF-8 stops the program, with the offset of the byte that made it ill-formed.

main names one function in a program, wherever it is written — even in two different modules, where nothing else would collide, and even at the two signatures above:

main()
    print(1)

main(args: []string)
    print(2)

'main' is where a program starts, so there is one — a second declaration of it would overload the name, and a program has one beginning rather than a set of them

That is the reason C reserves the name: it is not a name the program calls, it is the name the platform calls, so two would leave which one the program is to whichever was emitted last. Otherwise it is an ordinary function, and may be called by the program too.

A main may answer with a Result[unit, E], which is what lets ? reach the top of a program:

import sysl.fs.{read_text, IoError}

main() -> Result[unit, IoError]
    val text = read_text("/nonexistent/file")?

    print(text)

    Ok(())

That program prints nothing and exits 1, having written error: no such file or directory to stderr. Without the form, every fallible call in main ends in .unwrap(), which reports the failure as a panic naming the line that gave up rather than the thing that went wrong.

Three parts of it are decided rather than incidental. The unit is not decoration — a value main answered with would have nowhere to go, since what the platform takes is a status. E must be Display, because the report is the whole point and an error nobody can render would exit non-zero having said nothing. And the status is 1 rather than something read off the error: a status is one byte and an error is a value, so mapping one onto the other is the program’s business, and exit is how a program that wants to choose says so.

Nothing else is admitted:

main() -> int = 0

'main' yields nothing or a 'Result[unit, E]', so it may not result in int — a program's exit status is not something a signature can say

A program in which no file carries a statement is a complete program that does nothing. The entry point exists, runs nothing, and succeeds. That is what a tree of pure declarations compiles to, which is what it should compile to — a library is not an error.

The entry file is a body, and what it declares is local to it

val and var at the top of the entry file are locals: initialized where they are written, in the order the statements around them run. A function declared there is a nested function (functions), so it reads and writes the bindings above it with nothing passed in:

var counter = 0

bump()
    counter += 1

bump()
bump()

print(counter)

That is the whole point of the arrangement, and it is what a script wants: a sequence that is a sequence. A val bound from what the statements above it produced is ordinary here, and could never be a module member — a module member is bound before any statement runs.

A helper pays nothing for this unless it uses it. Whether a function at the top of the entry file belongs to the body is settled by whether it reads one of the body’s bindings. One that reads none is an ordinary module function: generic if it says so, addressable, passable as a value, and reachable from another file. Only one that reads a binding is nested, and only that one takes the nested function’s limits.

`static` — asking for the module instead

A val or var in the entry file that should be the module’s says so:

static val table: [3]int = [1, 2, 3]

sum() -> int = table[0] + table[1] + table[2]

print(sum())

It is then hoisted, laid into the object file, visible to every file of the module, and initialized before any statement runs — which is also why its initializer may not call a helper that reads the body: at that moment there is no body yet.

A static var is the same storage, written — assignment at every depth and &, which is what the word var already means, and which a val refuses because a val promises its storage is written once:

static var ticks: int = 0

tick() = ticks += 1

tick()
tick()
print(ticks)

Its initializer may be absent, which a val‘s may not — the type’s zero is what it starts at, and that is the cheapest form and the one an arena wants.

It holds a counted value, and the last one it holds is never released. A string, a slice, a &T, a weak T and anything built out of them are all module storage; every assignment during the run gives back the count it replaces, and the only release with nowhere to go is the one at exit — which is the release a static is defined by not taking.

static var current: string = ""

set(s: string) = current = "[" + s + "]"

set("one")
set("two")
print(current)

[two]

That was refused until the reason behind it was read again: storage lasting the whole run has no line to write a release on, which is true and is a description of a static rather than an argument against one. What the refusal cost was the shape every callback interface needs — a C function that calls back takes an address and an opaque word, so a binding offering a sysl closure has to keep it where the trampoline finds it again, and module storage is the only storage that outlives the call.

What is refused instead is a type with no zero and no initializer, which is a narrower rule about a different thing. A &T has no zero, because there is no such thing as a reference to nothing; an enum has none either, since a zeroed tag names no variant in particular. A string and a slice both zero to the empty one and need nothing written. It is the same question a local declared with no initializer is already held to.

struct Cell
    v: int

static var cell: &Cell

'cell' needs a value: storage with no initializer starts at its type's zero, and &Cell has none — the same rule a local with no initializer is held to. A 'string' and a slice both start empty and need no value written; a reference and an enum need one

A destructor takes the same ruling and for the same reason: a value in module storage never reaches a count of zero, so its drop does not run when the program ends.

static is meaningful only in the entry file, since only that file has a body for a declaration to not belong to. In a file with a module header, or a headerless file carrying no statements, everything is the module’s already and the modifier is refused rather than ignored. A function never takes it either: settled by what it reads, the modifier would be redundant on one and impossible on the other.

So everywhere else the same storage is written plain var, and it is the same declaration — visibility, the shared value namespace, the initializer graph and the release rule all answer for it exactly as above:

module counter

var count: int = 0

bump() = count += 1

The two spellings never compete, because the modifier is needed precisely where there is a body to be asking about. Reading them side by side: static var in the file the program starts in, var anywhere else, one kind of module storage.

Visibility is the part of that worth writing out, because a module with state usually wants it — the functions that maintain the storage are public and the storage itself is nobody’s business:

module counter

private var count: int = 0

bump() = count += 1
peek() -> int = count

Both spellings take one, so private static var says the same thing in the file the program starts in.

A var does not decide which file the program starts in. That is settled by what a file runs, and declaring storage runs nothing — a file holding a counter is no more the program’s beginning than one holding a table. Where a file carries a statement that is not a binding, it is the entry file and every other file’s top-level vars are their module’s. Where nothing runs anywhere, a single headerless file of bindings is still a body, so a one-file var n = 1 means what it always did.

That word is load-bearing: a file naming a module is never the program’s beginning, and it is the sentence at the top of this section seen from the other side — a header means everything the file declares is the module’s already, so there is no body for a binding to belong to instead. A library is the shape that tests it, being files and no beginning anywhere.

`const` — a value

A const is a module member: hoisted, order-free, visible to the whole module and beyond it under the ordinary rules, and never running at all.

const capacity: usize = 512
const window: int = 1 << 15

type Slot = usize within 0..<capacity

var table: [capacity]u8 = [0; capacity]

print(table.len, window, capacity)

512 32768 512

Why it exists at all, when a nullary function already serves every use in an expression: an array bound is a compile-time constant and a call is not. Without const, a program carries [512]u8 next to a capacity() function and a comment asking the reader to keep the two in step.

The type is always written — not because it could not be inferred from the initializer, but because the rule that anything visible outside its file states its types is what keeps interface extraction parse-only. Writing it is also what fixes the literal’s type, so const capacity: usize = 512 needs no suffix on the 512.

And the type is a scalar, or a transparent subtype of one. The first half is the shape of what a constant expression can produce rather than a restriction anybody chose — there is no aggregate literal to fold to, and a table would be storage rather than a value. The second half follows from a transparent subtype being its base, so a constant declared at one is a literal at an integer, a float or a char — and its range is checked while compiling:

type Age = int within 0..150

const oldest: Age = 122

print(oldest)

type Age = int within 0..150

const oldest: Age = 200

which Age does not admit — it holds 0 to 150

That check is the one thing a constant gets that a val of the same type gets only at run time, and it is what a c const is really for: a number nobody chose — a sizeof, a config macro out of somebody else’s header — held to what this program can actually do with it.

A new type is refused, because reaching one from its base is a written conversion and a constant is the value it was written as, so there is nowhere on the line to write one. A where predicate is refused too, because a predicate is checked where a value is made and a constant is folded into its uses rather than made anywhere — admitting one would be a check the declaration claims and the program never gets.

A constant expression is a literal; a const; a conversion; a unary -, ! or ~; or a binary arithmetic, bitwise, shift, or comparison operator applied to constant expressions. Integers, floats, bool and char fold.

There are no calls, and a string constant’s initializer must be a literal — since + on strings allocates, and a compile-time concatenation would be a different operation wearing the same spelling:

size() -> int = 4

const called: int = size()

print(called)

the value of 'called' is not a constant expression

A function call in a constant expression is a request for compile-time evaluation of arbitrary code, which is a language of its own.

“A const“ above means the declaration, not a spelling of it. A constant reached by its full path is the same constant as one reached by an import, and the two fold alike in every position below — what decides is what the name resolves to, and the three steps above are the whole of how a name resolves:

import bits.byte_width

var packed: [byte_width]u8            -- imported
var padded: [bits.byte_width]u8       -- the same declaration, named through its module

It is worth saying only because the two spellings are different enough to be implemented separately, and once were. A c const is no different: a binding keeps its measured constants in a sub-module of their own, so every consumer names them qualified.

Where a constant may stand: anywhere an expression may, plus the four places a literal was previously the only thing accepted — an array bound, an enum discriminant, a pattern, and the bounds of a within range:

const Limit: int = 3

enum Op
    Halt = Limit
    Push

classify(n: int) -> string
    n match
        Limit -> "at the limit"
        else     "other"

print(classify(3), classify(1), int(Op.Halt), int(Op.Push))

at the limit other 3 4

All four go through the same fold, which is the property worth keeping: they accept the same expressions because they ask the same question, rather than several grammars agreeing by coincidence.

The pattern position is the one worth saying out loud, because it is where other languages have come to grief: a name in a pattern binds unless it resolves to something, and Rust’s rule that a lowercase const in a pattern binds instead of matching is a documented trap. Here it cannot arise — a pattern name already resolves against the enum variants in scope before it is taken as a binding, and a constant joins that same resolution rather than adding a second one.

A constant has no address. It is folded into each use and occupies no storage, which is why it needs no initialization order, why a no alloc module may hold one, and why &capacity is not a thing to write. That is also what rules it out for a table, which is indexed at a value only known while running and therefore has to be somewhere.

A cycle between constants is reported at the declaration, naming the loop:

const a: int = b
const b: int = a

print(a)

constant 'a' is defined in terms of itself: a → b → a

Two things a constant is not. Not an enumeration — a set of related named values is a simple enum, which is the type-safe replacement for a pile of constants; if a second constant would be the obvious neighbour of the first, the declaration wanted was an enum. And not a value generic — parameterizing over a length is [const N: usize], which is this declaration with the initializer left to the caller. The two are one idea in two positions, and this one had to come first: a value cannot be passed as an argument before it can be named.

`val` — a thing

A val is a thing, where a const is a value. As a module member it is read-only storage that exists for the whole run; as a local it is the immutable counterpart of var, in the same frame with the same lifetime. One keyword at both levels, because it is one idea at both — and which one it is follows the file it is written in: the module’s everywhere except the entry file, whose top level is a body, and where static asks for the member.

static val order: [8]usize = [3, 1, 4, 1, 5, 9, 2, 6]

at(i: usize) -> usize = order[i]

var i: usize = 0
var total: usize = 0

while i < order.len
    total += at(i)
    i += 1

print(total, order[2])

31 4

The whole difference from a const is an address. A constant is folded into every use, which is what lets it size an array and what stops it from being one. A val sits somewhere, so it may be indexed at a value only known while running, iterated, and reached into. The rule for a reader is short: if it has to be indexed or pointed at, it is a val.

Because it is read while running, a val is the one module-level name that cannot size a type or stand in a pattern:

val limit: usize = 4

var table: [limit]u8 = [0; 4]

print(table.len)

an array length must be a constant — a literal, or a 'const' naming one

Naming one in a pattern with a bare name is an error rather than a quiet binding, for the same reason — a bare name there would bind rather than match, and the diagnostic names what to write instead:

static val limit: usize = 4

check(n: usize) -> string
    n match
        limit -> "at the limit"
        else     "other"

print(check(4))

a bare name here would bind rather than match

What to write is the backticked form, which says the test was meant and compares against whatever the val holds when the match runs:

static val limit: usize = 4

check(n: usize) -> string
    n match
        `limit` -> "at the limit"
        else     "other"

print(check(4), check(9))

at the limit other

The rest of what a module-level val may hold — read-only at every depth, and the []const T a slice of one yields — is on declarations.

Separate compilation

A library is built into one file and linked against, rather than recompiled by everything that uses it:

sysl build-lib mylib -o mylib.syslib     # compile the library once
sysl run prog.sysl --lib mylib.syslib    # link a program against it

--lib takes either an artifact or a source tree, and which one is read off the name. How a library shipped is the shipper’s business; a program that depends on one should not have to write down which form it got. Given a source tree the library is simply more modules, and the rules at the top of this page do the rest.

An artifact has two halves, and the split is the whole design. A declaration with no type parameters is compiled ahead of time into object code by whoever built the library, and a program that calls it declares the symbol and links the body. A generic has nothing to compile until a caller fixes its type arguments, so it crosses as the tree it was parsed into and is monomorphized in the consuming program. Rust’s .rlib makes the same split for the same reason.

The metadata carries every declaration, not only the generic ones: a call into the precompiled half still has to be type-checked, and the tree is where the signature is. What the symbol list adds is which of those the consumer must declare rather than emit a second time.

Five consequences, each a thing a reader would otherwise have to discover:

An artifact is for one machine, and both halves pin it. The object half obviously does; the tree half does because a library may gate on the machine it is built for, which makes two artifacts built from one source two different sets of declarations. So an artifact records its target and is refused by a build for another — refused rather than left to the linker, which would eventually complain about object formats in a message saying nothing about which library or why.
A library carries no entry point. A main of its own would collide with the one belonging to whatever links it.
Nothing is pruned when a library is built. A program is lowered from main outwards because what it cannot reach is dead; a library has no main and every public declaration is a potential entry, so all of them are emitted and the linker discards what a given program never calls.
A library defines its own declarations and nobody else’s. A library that prints reaches the library’s own printing surface exactly as a program does — but emitting those would put a copy in every artifact, so two libraries that both printed could not be linked into one program. They are declared in the artifact and defined in the consuming program.
A library may not sit in the anonymous root module. A library is reached by naming its module, and the root module has no name, so nothing depending on it could write a path to what it declares.

A library may be built on another library, and --lib is how one gets there:

sysl build-lib sdl3 -o sdl3.syslib
sysl build-lib sdl3-ttf --lib sdl3.syslib -o sdl3-ttf.syslib

build-lib takes --lib exactly as a compilation does, and for the same reason: a library whose declarations are written in another library’s types does not compile without them. sdl3-ttf‘s Font renders to an sdl3 Surface, so a package that could not say so would have to be a module inside its dependency rather than a package of its own. Nothing about the artifact changes, because the fourth bullet above already governs it — the dependency’s compiled half is declared here and defined by whatever program links both.

What build-lib does not do is fetch. A dependencies block is a coordinate to resolve over the network, and a command whose whole job is to compile one tree into an artifact for one machine does not go looking — so a package that declares dependencies and is handed no library is refused, naming the dependency and the flag that answers it. Such a package writes its dependency down twice, once in package.hocon and once on the command line, and that is the price of a compile step that is offline by construction.

The container is an ar archive, which is what an .rlib is and for the same reason: the linker already reads one, so the compiled half needs no unwrapping and a member is pulled in only to resolve something a program actually left undefined. The metadata rides inside it wrapped in a real object file, as one private constant in a section of its own, so nothing ever gives the linker a reason to pull it in and it costs the linked program nothing.

The standard module is built the same way, and linked by default. Which library a compilation is compiled against is a parameter of it rather than an ambient fact — which is what lets two cores be handed to two compilations and compared — but the parameter has a default, and the default is found rather than named. A compilation that finds no standard module at the default path builds one, in well under a second, announcing it on stderr. That is not the silent substitution a compiler must never make: a rebuild compiles against this library, from its own source, held to the same fingerprint on the way back in. Nothing is substituted, so there is nothing to be misled about.

The standard module’s source ships with the compiler and is read off disk — share/sysl/library under the install prefix, found from the binary’s own location the way rustc finds its sysroot. Running out of a checkout, it is library/ in the tree. You can read it, and you can edit it: a changed file changes the library’s fingerprint, so the next compilation builds an artifact of its own rather than picking up a stale one. SYSL_LIB names a library root outright, which is what a broken install needs and nothing else does. A compiler that cannot find its library names every path it tried.

The default path is keyed by a fingerprint of the library, so every compilation of the same library on the machine finds the same artifact — and a rebuild therefore publishes by rename: it is assembled beside its destination and moved onto it. Two builds may run at once; a reader gets the whole of one artifact or the whole of the other, and a rebuild that fails leaves the one that was already there.

An artifact named on the command line is never rebuilt, and one that cannot be read stops the compilation — corrupt, truncated, built by another sysl, or built from other sources. Someone who wrote down which standard module to compile against is owed the truth about that one.

What is deliberately absent

absent	why
a file as a module	the file is a contribution, not a unit; there is no per-file namespace and no import of a file
a `pub` keyword	public is the unmarked default; its absence is public
relative or wildcard-path imports	an import names a module by its full dotted path from the project root, so a reference means the same thing wherever the importing file sits
auto-import beyond the standard module	a module earns visibility by being imported or fully qualified
implicits — Scala’s `given`/`using`	a term selected by searching the scope would let a change anywhere alter what resolves in a file that did not change, so a module’s interface would no longer bound its blast radius

The last is the sharpest of them. Scala pays for implicits with per-file used-name tables and API diffing, and that machinery is the cost of the feature rather than an implementation detail of it. The one search sysl does perform, for a trait impl, is bounded to two modules by the coherence rule for exactly the same reason.

Next: errors and contracts.

Memory

2026-08-16T01:26:07.924728867Z

This is the chapter that makes sysl a different language rather than a different syntax. Everything before it would have read much the same in half a dozen languages; nothing after it reads right until you know this.

A systems language is used for the control it gives you over where things live and when they die. The two well-known ways to keep that control and stay safe are a garbage collector, which takes away the when, and a borrow checker, which keeps both but asks you to prove your program correct to a checker as you write it. sysl takes a third road: reference counting, with the choice of mode written on each declaration.

The three modes

mode	what it is	who frees it
`T`	a value — on the stack, in a register, or inline in something bigger	nobody; it goes when the frame does
`&T`	a counted reference to a heap object	the compiler, when the last reference goes
`*T`	a raw pointer — C’s pointer	you

The choice is per declaration, not per type. The same struct Point can be a value here and a heap object there, and it is the declaration that says which:

struct Point
    x: int
    y: int
end Point

var here = Point(1, 2)              // a value, in this frame
var shared: &Point = Point(3, 4)    // on the heap, counted

print("value:", here.x, "reference:", shared.x)

value: 1 reference: 3

Look closely at those two lines, because the difference between them is the whole idea: the constructions are identical. Point(3, 4) did not ask to be on the heap. The annotation &Point is an expectation, and writing an ordinary construction where a &T is expected is what puts the object there.

There is no allocation keyword

No new, no malloc, no Rc::new, no .clone(), no wrapper type to learn. The positions that create a reference are the ones that already state a type — a declared local, a parameter, a return type, a struct field, an enum variant’s payload:

struct Process
    id: int
    priority: int
end Process

spawn(id: int) -> &Process = Process(id, 0)

var p = spawn(7)

print("spawned:", p.id)

spawned: 7

The return type says &Process, so the construction in the body allocates. Somewhere with no expectation at all, a construction is a value. That is the whole rule.

References are shared, and mutable through any alias

There is no borrow checker, so there is no exclusivity rule to satisfy. Many references may point at one object, and any of them may write to it:

struct Account
    owner: string
    balance: int
end Account

deposit(a: &Account, amount: int)
    a.balance += amount

var shared: &Account = Account("ada", 100)
var alias = shared

deposit(alias, 40)

print("balance:", shared.balance, "same object:", shared == alias)

balance: 140 same object: true

alias = shared did not copy the account — it made a second reference to it, and incremented the count. Compare that with the struct chapter, where b = a on a value copied it. Same syntax, and the declared mode is what decides.

If you are coming from Rust: yes, that is two live mutable aliases, and yes, it is allowed. Handing that back is the deliberate trade. Reference counting pays for it at run time — a retain here, a release there — and buys a language you can be productive in on the first day.

A reference is never null

A &T always points at a live object. There is no null reference to check for and no way to make one, which removes an entire category of bug rather than diagnosing it.

Something that may be absent is therefore an Option, and that is what makes a linked structure look the way it does:

struct Item
    label: string
    rest: Option[&Item]
end Item

count(list: Option[&Item]) -> int
    list match
        Some(item) -> 1 + count(item.rest)
        None -> 0
end count

var last: &Item = Item("c", None)
var middle: &Item = Item("b", Some(last))
var items: &Item = Item("a", Some(middle))

print("length:", count(Some(items)), "head:", items.label)

length: 3 head: a

The match is not ceremony around a null check — it is the only way to get at the item, so the absent case cannot be forgotten.

Cycles, and `weak`

Reference counting has one honest weakness: a cycle of strong references keeps itself alive. A parent holding its children while each child holds its parent is the shape that does it, and it is common enough to have a purpose-built answer.

A weak T is a non-owning reference. It does not keep its referent alive, and when the last strong reference goes away it simply becomes empty:

struct Node
    label: string
    parent: weak Node
end Node

parent_of(n: &Node) -> string
    n.parent.get() match
        Some(p) -> p.label
        None -> "(none)"
end parent_of

var root: &Node = Node("root", None)
var child: &Node = Node("child", root)

print("root's parent:", parent_of(root))
print("child's parent:", parent_of(child))

root's parent: (none)
child's parent: root

Reading one is a question, asked with get(), and the answer is Option[&T] — a live strong reference, or None. So a weak reference can never dangle: by the time you have something to use, you have proved it is still there.

There is no operator that makes a weak reference. A &T becomes one wherever a weak T is what was asked for, which above is the struct field. Reach for weak when you have a genuine cycle, and not before.

When the last reference goes

ARC returns the storage and releases whatever the value held. What it cannot do is close a descriptor, unmap a region, or hand a handle back to the C library that made it — those live behind a raw pointer or an integer, and nothing about either says it is owned. impl Drop for T is where that is said, once, beside the type:

struct Handle
    id: int

impl Drop for Handle
    drop(self) = print("closing", self.id)

hold()
    var h: &Handle = Handle(7)
    print("working")

hold()
print("done")

working
closing 7
done

defer (in statements) is the other way to say it, and neither replaces the other: defer covers every site a program can name, and a destructor covers the deaths it cannot — an element of a container that goes out of scope dies at a point with no expression in the source. The reference has the four limits, of which the one to know first is that a destructor runs for a value held behind a &T.

`*T` — the way out

The third mode is C’s pointer, and it is exactly as safe as C’s pointer. It is spelled with a sigil you can grep for, which is the point: the unsafe tier is visible in the source rather than hidden behind a keyword nobody scans for.

bump(n: *int)
    *n += 1

var counter = 41

bump(&counter)

print("counter:", counter)

counter: 42

&x takes the address of something and *p reads or writes through a pointer, both as in C. Nothing is counted, nothing is checked, and a pointer can dangle. In exchange it costs nothing at all, which is what a device driver, an allocator, or the inside of a data structure sometimes needs.

A pointer is also how a type reaches itself without an Option — and selecting through one needs no ->, because there is nothing else . could mean:

struct Node
    value: int
    next: *Node
end Node

var third = Node(3, null)
var second = Node(2, &third)
var first = Node(1, &second)

var walk = &first
var total = 0

while walk != null
    total += walk.value
    walk = walk.next

print("chain:", total)

chain: 6

null exists for *T and only for *T. That is the trade the three modes make explicit: the one place a null can appear is the one place you asked for C’s rules.

`volatile` — storage the program is not the only one writing

ptr_cast gets a driver to a register block; it does not get it a correct one. An optimizer is entitled to assume that reading the same storage twice gives the same value, that a store nobody reads is a store nobody needs, and that two accesses in a row may be merged into one wider access. Every one of those is false at a device, and the last of them is why a poll loop can spin forever on the first value it read.

So sysl has C’s qualifier, spelled where C spells it — in the type:

struct Gpio
    input:  volatile u32
    output: volatile u32
    shadow: u32
end Gpio

var block = Gpio(0b1010, 0, 0)
var regs: *Gpio = &block

regs.output = 0b0110
regs.shadow = regs.output

print(regs.input, regs.output, regs.shadow)

10 6 6

A volatile place is one whose reads and writes are effects rather than value computations, so the compiler emits exactly the accesses the source wrote, exactly once each, in the order written.

Two things about it are worth carrying away. It constrains the compiler, not the machine — no atomicity, no ordering against another core, no protection from a torn read, so a program reaching for this word to share a counter between threads has written a race with a keyword in front of it. And it is per field, which is what shadow above is there to show: a driver keeps ordinary values beside its registers, and a qualifier on the whole struct would sweep them in and make every touch of a cached flag an unoptimizable access.

It also qualifies storage, never a value — which is the rule the spelling follows from:

var x: volatile u32 = 0

print(x)

'volatile u32' is the type of *storage*, and this is a value — what a read of a volatile place hands back is an ordinary 'u32'. The qualifier goes where the storage is named: a struct field, an element, or the pointee of a '*T', as '*volatile u32'

What a load hands back is a number, and a number is not somewhere a device can write.

`ref` — a name for a place

A place can be deep, and the two ways to shorten one both cost something. var t = self.tasks[i] binds a copy, so every read and every write walks the path from the table again. &self.tasks[i] gives the name back — and gives up bounds checking, within checking, invariant re-checking and the guarantee at the top of this chapter, all in one step.

That is a cliff rather than a gradient, which is what ref is for. It binds a name to the place:

struct Bank
    slot: [3]int

    set(*self, i: usize)
        ref e = self.slot[i]

        e = e + 42
end Bank

var b = Bank([1, 2, 3])

b.set(1)

print(b.slot[0], b.slot[1], b.slot[2])

1 44 3

The place is evaluated once, where the binding is written — the index is computed once, the bounds are checked once — and what the name means afterwards is the storage that was found, not the expression that found it. A later i += 1 leaves e naming the element it always named.

It is a declaration, never a type

Which is the whole of why it can exist in a language with no borrow checker. ref may be written only as a local declaration: there is no ref type, so one cannot be a field, a parameter, a return type, an element, or a type argument. It cannot be captured by a closure, and it does not outlive the block that declares it.

That restriction is what keeps the compiler’s knowledge complete. A *T is a type, so the moment one exists it can be carried somewhere the compiler has lost the path it came from. A ref never travels, so the analyzer still holds the place expression, at the point it was written, in the same body.

At run time a ref stores an address. At compile time it remembers a place. Both halves matter. The address is what makes sixty-five path walks one. The remembered place is what keeps every check a *T would have severed — the invariants of every struct the place lies inside, the within on a constrained slot, the read-only-ness of storage reached through a val, and the bounds check the subscript owed.

So a ref is not a fourth memory mode. It introduces no representation, no new type, and nothing that can be stored: it is a second way to say a place the three modes already describe.

What may be written

A ref’s initializer must be a place. A call result has no address, so there is nothing for the name to mean:

make() -> int = 7

demo()
    ref x = make()

    print(x)

demo()

'ref' names a place — a local, a field, an element, or a dereference — and this expression has no address for 'x' to name

A ref inherits the place’s writability and gets no modifier of its own — so a ref into a val may be read and not written, exactly as the val may. Stating it twice would only create the chance to state it wrong.

Note also that this is the built-in subscript. A user type’s b[i] goes through the Index trait, which is a call rather than a walk to an address, so there is no place there for a ref to name.

The one rule: what may move underneath it

A stored address is only as good as the storage staying where it is. C# has ref locals and needs no rule like this, because a tracing collector keeps the old array alive when the variable is pointed at a new one; sysl has no collector in this tier, so the same program would dangle:

struct Table
    cell: []int

    swap(*self)
        ref e = self.cell[0]

        self.cell = [0; 8]

        print(e)
end Table

var t = Table([1, 2, 3])

t.swap()

'e' is a 'ref' standing on storage this assignment would release, so the name would be left pointing at freed memory

While a ref is live, no step of its place that could come to name different storage may be assigned, and no mutating method may be called on a prefix of one. The check is local and decided from types alone; it never asks where the ref is used, which is the question that would need lifetimes.

The second half is the one that catches a call rather than an assignment. A *self method may write any part of its receiver, so a live ref into that receiver is refused the call — whether or not that particular method reassigns anything, because deciding otherwise would mean reading the callee’s body, and a module compiles against its imports’ signatures and never their bodies:

struct Table
    cell: []int

    grow(*self)
        self.cell = [0; 8]
end Table

var t = Table([1, 2, 3])

ref e = t.cell[0]

t.grow()

e = 5

'e' is a 'ref' standing on storage this call could release, since a '*self' method may write its receiver

Which steps are hazards falls out of the model rather than being a list, and the discriminator is ownership, not indirection. Only a step that releases something when it is overwritten can strand a ref:

a &T step and a view step are hazards, because overwriting either drops what it held and that release may be the last;
a *T step is not. A raw pointer owns nothing, so p = q frees nothing and the storage a ref found through it stays exactly as alive as it was — no more, and no less;
a field, a fixed array, or an element of one is not either: that storage is the enclosing object’s bytes, so assigning to it overwrites the bytes rather than moving them.

The *T exclusion is not a concession, it is what makes the feature usable where it is wanted most. A program that reaches its tables through a *Self receiver has no owning step anywhere in the chain, so it is asked for nothing at all — every self.…() call stays legal, and the ref costs it exactly nothing:

struct Task
    state: int
    prio: int
end Task

struct Kernel
    tasks: [4]Task

    advance(*self, i: usize)
        ref t = self.tasks[i]

        t.state = 2
        t.prio = t.prio + 1
end Kernel

var k = Kernel([Task(0, 7); 4])

k.advance(2)

print(k.tasks[2].state, k.tasks[2].prio, k.tasks[0].prio)

2 8 7

A ref to a slot that holds a reference

ref r = self.node, where node is a &Node, names the slot and not the object in it. So the binding takes no count — nothing new holds the object — and r = other is the assignment self.node = other by another name, releasing what was there and retaining what arrives, in that order.

The distinction matters because the other reading is available and wrong: if binding retained, a ref would be a &T with extra steps, and the count it took would keep an object alive past the write that replaced it.

Where it comes from

The form is old, and none of the languages this tour has been comparing itself to have it — Swift, Kotlin, Scala and Go are all silent. Ada’s renames is the general case and evaluates the name once at the declaration; Fortran’s ASSOCIATE is the closest in shape, being block-scoped and deliberately not a type; C#’s ref locals are the closest in spelling. C# also shows what the restriction is worth: having added ref returns and ref fields, it spent several releases building the escape analysis that keeping the form local avoids entirely.

Scala’s by-name parameter is the thing this is not. x: => T re-evaluates at every use; a ref evaluates once and remembers what it found.

What this costs

Less than you would think, because the compiler knows when counting is pointless. A local that never escapes its frame is not heap-allocated at all; a closure that does not outlive its frame is inlined rather than boxed; a slice of a local array stays on the stack when nothing takes a view of it away. You do not annotate any of that, and you cannot get it wrong — try to return a view of a local buffer and the compiler will tell you.

What remains is a retain and a release at the points where a reference is genuinely shared. That is the price of not having to prove anything to a borrow checker, and it is the trade the whole language is built around.

Next: arrays and slices — two types that lean on everything in this chapter.

Memory

2026-08-16T01:26:07.924728867Z

Every value in a sysl program lives in one of three ways, and the declaration that names it is what says which. This page is the whole of that model: what each mode costs, what it guarantees, how a reference is made, when storage moves without being asked, and where the guarantees stop.

If you do not write *T, you cannot segfault. The safe subset — values, references, weak references, arrays, and slices — has no use-after-free, no null dereference, no out-of-bounds access, and no dangling pointer. The single unsafe primitive is the raw pointer, and it is greppable: a program’s exposure to C’s hazards is exactly the lines with a * in the type. A driver has them and an application does not, and you can tell which by looking.

The three modes

mode	what it is	who frees it	needs an allocator
`T`	a value — on the stack, in a register, or inline in something bigger	nobody; it goes when its frame or its container does	no
`&T`	a counted reference to a heap object	the compiler, when the last reference goes	to make one
`*T`	a raw machine pointer	you	no

struct Point
    x: int
    y: int
end Point

var here = Point(1, 2)
var shared: &Point = Point(3, 4)
var raw: *Point = &here

print(here.x, shared.x, raw.x)

1 3 1

The choice is per declaration, not per type. The same struct Point is a value in the first line, a heap object in the second, and a pointer’s target in the third. This is C’s arrangement rather than Swift’s or Scala’s, where a type is struct or class once and for all, and systems code depends on it: a page-table entry, a temporary in a loop, and a shared configuration object may all be the same type held three ways.

Value is the unmarked default, and the kernel is why. A module that has given up the allocator cannot make a reference. If the reference were the bare default, the unmarked spelling would be the one that is illegal exactly where value semantics matter most — every kernel struct would need a mark, and would hit “references need an allocator” on its most natural form. With value as the default, T is usable in both worlds, *T covers pointers, and &T appears in allocator-free code only where something else handed one over.

`T` — values

A value lives inline: in a stack slot, in a register, or embedded in the struct or array that contains it. Assignment and argument passing copy it, exactly as in C.

struct Counter
    n: int
end Counter

var a = Counter(1)
var b = a

b.n = 99

print(a.n, b.n)

1 99

There is no move semantics and no use-after-move. a is still a whole Counter after b = a, and it always will be — the concept of a value that has been given away does not exist here, so neither does the class of error built on it.

A value containing a &T field is still a value: copying it retains that field, so the copy is independently safe and the original is untouched. That is the one thing a copy does beyond moving bytes, and it is what makes “values are simple” true rather than approximately true.

Values need no allocator and are always safe.

`&T` — counted references

A &T is a reference to a heap object managed by ARC: the compiler emits the retains and releases, and the object is destroyed the moment the last strong reference to it goes away. It is:

shared and freely aliased — many references may point at one object;
mutable through any alias — there is no borrow checker and no exclusivity rule;
non-null — a &T always points at a live object;
automatically managed — no free, and no place to forget one.

struct Counter
    n: int
end Counter

var a: &Counter = Counter(1)
var b = a

b.n = 99

print(a.n, b.n, a == b)

99 99 true

Compare that with the value example above: the same two lines, and the declared mode is the only difference. b = a copied a Counter there and made a second reference here.

Two live mutable aliases is what Rust exists to prevent, and permitting them is the deliberate trade. Reference counting pays for it at run time — a retain here, a release there — and buys a language with no lifetimes, no borrow checker, and nothing to prove to a checker as you write.

References compare by address. == and != on a reference or a pointer ask whether the two name the same object, which is the only question a bare address can answer, and there is no ordering on either.

There is no allocation keyword

A reference is made by writing an ordinary construction where a &T is expected. The expectation is what puts the object on the heap:

struct Process
    id: int
    priority: int
end Process

spawn(id: int) -> &Process = Process(id, 0)

var p = spawn(7)
var q: &Process = Process(8, 1)
var v = Process(9, 2)

print(p.id, q.id, v.id)

7 8 9

Process(id, 0) in the body allocates because the return type says &Process. Process(8, 1) allocates because the annotation says so. Process(9, 2) does not, because nothing asked — with no expectation at all, a construction is a value.

No new, no malloc, no Rc::new, no .clone(), and no wrapper type. The positions that fix the expectation are the ones that already state a type for generic inference:

position	example
a declared local	`var p: &Point = Point(1, 2)`
a parameter	`f(p: &Point)`, called as `f(Point(1, 2))`
a return type	`-> &Point`, with a construction as the result
a struct field	`Item("a", Node(1))` where the field is `&Node`
an enum variant’s payload	`Some(Node(1))` where the payload is `&Node`

An element of an array or slice, a part of a tuple, a generic argument, and a parameter of a callable type all ask the same way. The rule is about the types and not about the syntax: a T written where a &T is expected goes on the heap, whatever produced it.

A prefix & on a construction was considered as an explicit mark and not taken — it would collide with address-of, which is a different operation producing a different type.

The expectation reaches each branch

An if, a match, and a loop yield their value through their branches, so a &T expectation reaches each branch on its own rather than the expression as a whole:

struct Point
    x: int
    y: int
end Point

var origin: &Point = Point(0, 0)
var far = true
var p: &Point = if far then Point(9, 9) else origin

print(p.x, p.y)

9 9

That is what lets a value branch and an already-reference branch meet at &Point. Boxing the whole expression instead would fail, because a branch that is already a &Point cannot un-become a value — something that is already a reference passes through untouched.

It is also what lets a scalar be referenced without int needing a constructor of its own:

var n: &int = 41

print(*n + 1)

A reference is never null

There is no null in the safe subset and no way to make one, so there is no null dereference to diagnose. Something that may be absent is an Option[&T], and getting at it is a match:

struct Item
    label: string
end Item

show(o: Option[&Item]) -> string
    o match
        Some(i) -> i.label
        None    -> "(none)"

var it: &Item = Item("a")

print(show(Some(it)), show(None))

a (none)

The match is not ceremony around a null check. It is the only route to the item, so the absent case cannot be forgotten rather than merely being unwise to forget.

What a heap object costs

Every ARC object carries three header words: the strong count, a pointer to the function that destroys it, and a weak count. Release decrements the strong count; at zero it calls through the hook, which releases whatever the payload holds and returns the storage to the heap the object came from — one heap for the whole program, libc’s unless a package named another pair.

Putting the destructor behind a hook rather than inline at each release site is what makes letting go of a reference type-erased — one instruction sequence, no static type. Slices need exactly that, since a []T gives no clue what type of object its owner word points at.

One word per object buys three things:

ARC works the same everywhere. A module that never allocates can still retain and release, because the free path calls back into the heap the object came from. The operations are a few instructions and depend on no runtime.
Several heaps coexist. A kernel heap, a server’s heap, and an arena are different allocators, and an object frees itself into the one that made it, wherever it is dropped.
There is no boundary rule to learn. Ownership crosses an allocator-free edge like any other value.

Teardown is iterative, so depth is bounded. Destroying the head of a long chain of references would recurse one frame per node if a destructor called the next destructor. It does not: an object whose count reaches zero is pushed onto a worklist, reusing its now-dead refcount slot as the link, and the first release to hit zero drains the list in a loop. A structure of any depth comes apart in O(1) stack. The worklist is per thread, because it is scratch space a drain uses rather than state anything shares.

On a freestanding target the worklist is asked for rather than assumed, since there is no thread pointer to key it on. A &sync release that reaches zero fetches it through one weak symbol, __sysl_arc_reaper, which answers with a head pointer and a draining flag belonging to the running task:

struct sysl_arc_reaper { void *head; unsigned char draining; };

/* FreeRTOS, say: whatever this runtime keeps per task. The storage is the port's to give out and
   must last as long as the task — set when the task is created, never shared with another:

       static struct sysl_arc_reaper slots[MAX_TASKS];
       vTaskSetThreadLocalStoragePointer(task, 0, &slots[n]);            */
struct sysl_arc_reaper *__sysl_arc_reaper(void) {
    return pvTaskGetThreadLocalStoragePointer(NULL, 0);
}

Define nothing and the program uses the single slot it carries, which is right for a machine where nothing schedules — the overwhelming case, and why the symbol is weak. Define it in an RTOS port and &sync T means on that target what it means everywhere else. This is the arrangement &sync‘s counts are already under there: with no ldrex/strex beneath it an atomic increment becomes a call to an __atomic_* the board defines, and on a two-core part that needs a hardware spinlock.

The header is the same three words for every object whether or not anything weakly references it, which is what keeps the type-erased release path expressible at all. The cost is eight bytes on an allocation that already cost a malloc, and it lands only where the feature is used: values, fixed arrays, and *T buffers have no header, so allocator-free code pays nothing for a mechanism it never touches.

`weak T` — breaking cycles

A weak T does not keep its referent alive. When the last strong reference goes, the object is destroyed and every weak reference to it becomes empty.

struct Node
    label: string
    parent: weak Node
end Node

parent_of(n: &Node) -> string
    n.parent.get() match
        Some(p) -> p.label
        None    -> "(none)"

var root: &Node = Node("root", None)
var kid: &Node = Node("kid", root)

print(parent_of(root), parent_of(kid))

(none) root

weak T is a type, not an operator. There is nothing that makes one; a &T becomes a weak T wherever a weak T is what the context asked for — the struct field above, an argument, a declared local, a returned value. That is the same rule that makes a &T out of a T, so both & and weak live at the boundaries a program annotates and neither appears in a body.

The conversion goes one way. A weak T is not a &T and never silently becomes one, because becoming one is the operation that can fail.

The & is in the mode already, so weak &T is the word said twice — and it is refused rather than read as a weak edge to a box holding a reference, which is not a thing sysl has:

struct Node
    v: int
end Node

var r: &Node = Node(1)
var w: weak &Node = r

'weak Node' is already a weak edge to a counted Node, so the '&' says the mode a second time — write 'weak Node'

Reading one is a question, and it is get(). The answer is Option[&T]: a live strong reference with a count taken for the caller, or None. Nothing else may be done to a weak reference — no field selection, no method call, no ==:

struct Node
    label: string
    parent: weak Node
end Node

var root: &Node = Node("root", None)
var kid: &Node = Node("kid", root)

print(kid.parent.label)

may be gone, so nothing is read off one directly

Every road to the object goes through the Option, which is what makes “a weak reference never dangles” a fact about the language rather than a promise about the programmer.

The parentheses are not decoration. .len is a property — a fact about the value, the same answer every time it is asked — while get() is a question about the world: two calls a moment apart may disagree, and the answer costs a count. sysl puts the parentheses on the second kind.

An empty weak reference is written None, and it is the same state whether the object is gone or there never was one. This None is not an Option — it is the empty value of the weak reference itself, chosen because it is exactly what get() will hand back for it.

It is also the zero value of weak T, which is the one place weak T parts company with &T: there is no such thing as a reference to nothing, so &T has no zero. A struct with a weak field therefore still has one, and an uninitialized declaration of it is still a declaration:

struct Node
    label: string
    parent: weak Node
end Node

var n: Node

n.parent.get() match
    Some(p) -> print("held")
    None    -> print("empty")

empty

A weak reference may not be made from a value with nowhere else to live. Constructing into a weak position would box the value and then weaken it, leaving the weak edge as the object’s only holder — and the object dead before the statement ended:

struct Node
    label: string
    parent: weak Node
end Node

var kid: &Node = Node("kid", Node("root", None))

print(kid.label)

a weak reference does not keep Node alive, and nothing else here holds this one

The only default a weak T parameter can have is None, and that falls out rather than being decided. A default is produced afresh at each call that omits it, in a scope holding none of the caller’s locals, so what it names would have to outlive every frame — and every candidate that names an object is closed off. A construction is refused by the rule above; a top-level var is a local of the entry point; and a module-level val counts nothing, which a reference does. What is left is the one value that holds nothing:

struct Node
    label: string
    parent: weak Node
end Node

adopt(child: string, parent: weak Node = None) -> string
    parent.get() match
        Some(p) -> child + " of " + p.label
        None    -> child + " of nobody"

var root: &Node = Node("root", None)

print(adopt("a"), adopt("b", root))

a of nobody b of root

weak sync T is refused, naming the concurrency chapter. Upgrading an atomic weak reference is a compare-and-swap loop against a count another thread may be driving to zero underneath it, and that is written when there is something to race with.

Everything a &T may point at, a weak T may be taken of: a struct, a scalar, an array, a generic instantiation, a trait object, and a type parameter.

`*T` — the raw pointer

*T is a bare machine pointer, exactly like C’s: no length, no count, no checks, manual lifetime. It is the only unsafe primitive over data, it needs no runtime, and it is how a kernel, a driver, or an allocator’s own internals are written.

bump(n: *int)
    *n += 1

var counter = 41

bump(&counter)

print(counter)

Anything C can do through a pointer, sysl can. The pointer is where the language’s guarantees stop, so it carries C’s whole surface rather than a safer subset of it — a subset would only mean a kernel that could not be written here.

`null` exists, and only here

null is the absent raw pointer. It has no type of its own and takes the *T its context expects, the way a bare None takes its type argument:

struct Node
    value: int
    next: *Node
end Node

var third = Node(3, null)
var second = Node(2, &third)
var first = Node(1, &second)

var walk = &first
var total = 0

while walk != null
    total += walk.value
    walk = walk.next

print(total)

That program is also the answer to “how does a type reach itself” — see recursive types below.

A generic parameter is a context like any other, and it answers late. A callee still being solved has no type at that position yet, so an argument with none of its own is set aside until the ones that have have been read, and is then taken against the parameter it turned out to stand at:

two[T](a: *T, b: *T) -> bool = a == b

var x: int = 3

print(two(&x, null), two(null, &x))

false false

Either order answers alike, because waiting is not queueing. Setting an argument aside cannot lose the solution — one with no type of its own has nothing to contribute to it — so the parameter is settled by the other arguments or by nothing at all. Nothing at all is refused rather than defaulted: a call with no other argument to read is asked what the pointer points at.

one[T](a: *T) -> bool = true

print(one(null))

'null' takes its type from its context, and there is none here

Arithmetic: two directions, one spelling each

var buf: [8]int = [10, 20, 30, 40, 50, 60, 70, 80]
var base = &buf[0]
var third = &buf[2]

print(*third, third - base, base - third, *(&base[3]))

30 2 -2 40

p - q between two pointers of the same pointee is an isize, and it counts elements, not bytes — C’s ptrdiff_t. It is signed because the order of the operands is the programmer’s, and it is the exact inverse of &p[n]: indexing takes an address and a count to an address, and the difference takes two addresses back to a count, both striding by the pointee.

It is here because the interior-pointer half of libc needs it. memchr, strchr, strrchr, strstr and memmem all hand back a pointer into a buffer the caller owns, and without a difference every one of them is callable and useless, because nothing could turn the answer into an index.

Offsetting stays &p[n]. p + n is not spelled, deliberately: indexing already exists and already strides by the pointee, and a second spelling for one address would be a second thing to keep in step. p + q names no address and is refused too.

Two pointers of different pointee types have no shared element to count, and are refused by the ordinary matching-types rule rather than by one of this operator’s own:

var n = 1
var c = 'x'
var pn = &n
var pc = &c

print(pn - pc)

'-' needs matching types, got *int and *char

A counted &T has no arithmetic at all, keeping the equality it always had and nothing more:

struct Point
    x: int
end Point

var a: &Point = Point(1)
var b: &Point = Point(2)

print(a - b)

operator '-' is not defined for &Point

Arithmetic is a property of the unsafe mode, not of holding an address.

Whether two pointers into unrelated objects may be subtracted is the programmer’s business, as p[i] past the end already is.

Bounds safety follows length, not pointers

The out-of-bounds hazard is governed by whether a value carries its length, independently of where it was allocated:

arrays and slices carry their length, so indexing is bounds-checked in every context — hosted or allocator-free, over static, stack, or heap memory;
*T carries no length, so it is the one unchecked primitive. p[i] reads the ith element and p[0..<n] views n of them, both exactly as C does and both unchecked, because there is no length to check against and supplying one is the programmer’s assertion.

So even low-level, allocator-free code stays bounds-safe by choosing slices, and reaches for *T where it must — an MMIO window, a page table, a buffer a C function filled. That choice is the point.

Places

A place is something with an address: a local or parameter, a dereference, an element, and a field of any of them. Everything else — a call result, an arithmetic result, a freshly built struct — is a value with no address to take.

operation	what it does
`&place`	yields a *`T`** — C’s address-of, with C’s result
`*p`	reads through a `*T` or a `&T`, and is itself a place
`p.f`	selects, dereferencing one level automatically on both `*T` and `&T`

& on a place yields a raw pointer, never a reference. A place lives in a frame or inside another object, so there is no count to take a share of. Reaching a &T means being handed one or constructing one, and taking the address of a local is therefore inherently in the unsafe tier — which is right, because it can dangle and nothing promotes it.

Selection is the only implicit dereference. p.x is (*p).x and p.x = 9 writes through the pointer — Go’s rule, with no ->. Matching a reference to an enum against its variants is match *e.

The shorthand stops at one level, so reaching through a **T is written:

struct Point
    x: int
    y: int
end Point

var p = Point(1, 2)
var pp = &p
var ppp = &pp

print(pp.x, (*ppp).x)

1 1

Leaving the step out is a diagnostic rather than a second implicit dereference, and it says how many levels are left:

struct Point
    x: int
    y: int
end Point

var p = Point(1, 2)
var pp = &p
var ppp = &pp

print(ppp.x)

selection reaches through one level of indirection and **Point has more

Assignment, compound assignment, and ++/-- all take a place, so the same three forms work on a variable, on a field, and through a pointer with nothing special said about any of them.

An element carries one wrinkle the other three do not. A slice’s elements and a pointer’s live wherever the storage is, which is somewhere the expression naming them is not, so they have an address whether or not the expression naming them does. That is what makes rows(g)[i] = v write through to the grid rather than into the view the call handed back. An array’s elements are the array, so they are places exactly when the array is. A string’s bytes are never one: writing a byte of UTF-8 is how a string stops being UTF-8, and that is refused as immutability rather than as the absence of an address.

The hazard on the other side of that rule is the one dangle a single statement can produce. If a temporary view is the only holder of its buffer, the buffer is released at the end of the statement, and &f()[i] is a pointer to freed storage before the next line runs. That is the unsafe tier behaving as advertised — & yields a raw pointer, a raw pointer can dangle, nothing promotes it — and it is called out because every other dangle needs the pointer to be carried somewhere first.

`ref` — a name for a place

A place can be deep, and until ref the two ways to shorten one both cost something. var t = self.tasks[i] binds a copy, so every read and every write walks the path from the table again; &self.tasks[i] gives the name back and gives up bounds checking, within checking, invariant re-checking, and the guarantee at the top of this page, all in one step. That is a cliff rather than a gradient.

ref binds a name to a place.

struct Task
    state: int
    prio: int
end Task

struct Kernel
    tasks: [4]Task

    advance(*self, i: usize)
        ref t = self.tasks[i]

        t.state = 2
        t.prio = t.prio + 1
end Kernel

var k = Kernel([Task(0, 7); 4])

k.advance(2usize)

print(k.tasks[2].state, k.tasks[2].prio, k.tasks[0].prio)

2 8 7

The place is evaluated once, where the binding is written — the index is computed once, the bounds are checked once — and what the name means afterwards is the storage that was found, not the expression that found it. A later i += 1 leaves t naming the element it always named. Scala’s by-name parameter is the thing this is not: x: => T re-evaluates at every use, which would save no check and would silently make t follow a later change to i.

It is a declaration, never a type

This is the whole of why it can exist in a language with no borrow checker. ref may be written only as a local declaration. There is no ref type, so a ref cannot be a field, a parameter, a return type, an element, or a type argument; it cannot be re-pointed at a second place once bound; it cannot be captured by a closure; and it does not outlive the block that declares it.

A ref of a ref is not a re-pointing and is ordinary — one more name for the place the first one stands for, with the walks following through it:

var xs: [3]int = [1, 2, 3]

ref a = xs[1]
ref b = a

b = 42

print(xs[0], xs[1], xs[2])

1 42 3

At run time a ref stores an address. At compile time it remembers a place. Both halves are load-bearing. The address is what makes sixty-five path walks one. The remembered place is what keeps every check a *T would have severed:

a write through the ref re-runs the invariant clauses of every struct the place lies inside, found by the same outward walk, because the walk still has the whole place to walk;
a ref into a val, or into an element of one, is read-only, since reaching into read-only storage keeps the property;
a ref to a within-constrained slot is checked on assignment exactly as the slot is;
and the bounds check a subscript owes is paid once, at the binding, rather than not at all.

A ref is therefore not a fourth memory mode. It introduces no representation, no new type, and nothing that can be stored: it is a second way to say a place the three modes already describe.

What may be written

A ref’s initializer must be a place, and a call result has no address for the name to mean:

make() -> int = 7

demo()
    ref x = make()

    print(x)

demo()

'ref' names a place — a local, a field, an element, or a dereference — and this expression has no address for 'x' to name

A ref inherits the place’s writability and gets no modifier of its own. A ref into a val may be read and not written, exactly as the val may. Stating it twice would only create the chance to state it wrong.

A user type’s subscript is not a place. b[i] on a container goes through the Index trait, which is a call rather than a walk to an address, so there is nothing there for a name to mean. A ref reaches the built-in subscript, which is the one that indexes storage.

The one rule: what may move underneath it

A stored address is only as good as the storage staying where it is. C# has ref locals and needs no rule like this, because a tracing collector keeps the old array alive when the variable is pointed at a new one. sysl has no collector in this tier, so the same program would dangle:

struct Table
    cell: []int

    swap(*self)
        ref e = self.cell[0]

        self.cell = [0; 8]

        print(e)
end Table

var t = Table([1, 2, 3])

t.swap()

'e' is a 'ref' standing on storage this assignment would release, so the name would be left pointing at freed memory

While a ref is live, no step of its place that could come to name different storage may be assigned, and no mutating method may be called on a prefix of one. The check is local, decided from types alone, and never asks where the ref is used — which is the question that would need lifetimes.

Which steps are hazards falls out of the model rather than being a list, and the discriminator is ownership, not indirection. Only a step that releases something when it is overwritten can strand a ref:

step	hazard?	why
a `&T`	yes	overwriting it drops what it held, and that release may be the last
a view (`[]T`)	yes	the same — a view owns its buffer
a `*T`	no	a raw pointer owns nothing, so `p = q` frees nothing
a field, a fixed array, or an element of one	no	that storage is the enclosing object’s bytes

Two words carry the rule, and between them they keep the set small. A step is held still when it is an owning step that the path goes through — so the place itself is never in the set, because an assignment to it is what writing through the ref is. ref r = h.node names the slot, so r = other and h.node = other are one statement written two ways and neither is refused, while h = other on a &Holder is.

The *T exclusion is not a concession. A program that reaches its tables through a *Self receiver has no owning step anywhere in its chains, so it is asked for nothing at all — which is exactly the advance above, where the rule costs the program nothing.

The mutating-call half is the conservative one, deliberately. A *self method may write any part of its receiver, so a live ref into that receiver is refused the call whether or not that particular method reassigns anything:

struct Table
    cell: []int

    grow(*self)
        self.cell = [0; 8]
end Table

var t = Table([1, 2, 3])

ref e = t.cell[0]

t.grow()

e = 5

'e' is a 'ref' standing on storage this call could release, since a '*self' method may write its receiver

Deciding otherwise would mean reading the callee’s body, and a module compiles against its imports’ signatures and never their bodies. The cost is one refusal in a program that could have written the ref one line later.

What this does not do is make a *T safe, and it does not try. A ref’s place may be rooted at a pointer, and whether that points anywhere is the raw tier’s ordinary bargain. What the rule buys is that the storage a ref names cannot be released by the block that named it.

A ref to a slot that holds a reference

ref r = self.node, where node is a &Node, names the slot, not the object in it. So the binding takes no count — nothing new holds the object — and r = other is the assignment self.node = other by another name, releasing what was there and retaining what arrives, in that order. Reading r produces the reference and takes a count for the reader exactly as reading the field would.

Where it comes from

The form is old and lives outside this language’s usual references, none of which have it. Ada’s renames is the general case and evaluates the name once at the declaration; Fortran’s ASSOCIATE is the closest in shape, being block-scoped and deliberately not a type; C#’s ref locals are the closest in spelling. C# also shows what the restriction is worth: having added ref returns and ref fields, it spent several releases building the escape analysis that keeping the form local avoids entirely.

Recursive types

A type may reach itself through an indirection, and only through one. next: *Node is pointer-sized and legal, as is next: Option[&Node]; a struct holding itself by value has no finite size:

struct Node
    value: int
    next: Node
end Node

print(1)

type 'Node' contains itself, so it has no finite size

The rule is per cycle rather than per field: a cycle is legal as soon as one edge on it is a *T or a &T, so mutually recursive types work as long as the loop passes through a pointer or a reference somewhere.

Slices keep their backing alive

A slice is three words, not two:

[]T = { owner: *Buf, ptr: *T, len: usize }        // 24 bytes on a 64-bit target

ptr and len name the range; owner keeps the bytes alive. A bare {ptr, len} view can outlive the buffer it views — Go gets away with it because its collector finds the object from an interior pointer, and sysl has no collector — so the slice carries the owning reference itself. Taking a slice retains, dropping one releases, slicing stays O(1) and allocation-free, and “a slice never dangles” becomes true rather than aspirational.

tail() -> []int
    var xs: []int = [1, 2, 3, 4]

    xs[2..]

var t = tail()

print(t.len, t[0], t[1])

2 3 4

The buffer xs named is gone as a name before print runs, and the slice is still valid, because the slice is one of its owners.

owner is null when there is nothing to keep alive — a slice of static data, of a *T buffer, or of a fixed array whose storage outlives every view of it. Retain and release on such a slice are no-ops, so allocator-free code slicing a static or stack buffer pays nothing at all. This is the same immortality rule string literals use, generalized.

A string is then exactly an immutable, validated []u8, and the two share one representation and one implementation.

Escape analysis

The owner word answers “who keeps this alive” for every slice except one: a slice of a local fixed array. That storage is a stack slot, valid until the frame returns and no longer.

slice of	`owner`	safe to keep?
a heap buffer	the buffer	yes — retained
static data, a string literal	null (immortal)	yes — never freed
a `*T` region	null	the programmer’s problem, like every `*T`
a local fixed array	null	only while the frame lives

The compiler finds the slices for which that matters, and the programmer writes nothing. There is no @escaping, no lifetime parameter, and no “this result views that argument” marker anywhere in a signature. Go is the precedent; Rust’s lifetimes and Swift’s @escaping are the alternative, and both charge the programmer for what a compiler can work out.

What escapes

A slice whose origin is a local array escapes if it can be reached after the frame returns — that is, if it is:

returned, directly or nested inside whatever carries it back: a struct, an enum, an Option, a tuple, or one slot of a multi-result list;
stored into anything that outlives the frame — a global, a field reached through a &T, or an aggregate that is itself stored somewhere that outlives the frame;
passed as an argument the callee keeps;
captured by a closure that itself escapes;
assigned into a local that escapes — the rule is transitive, resolved as a fixpoint over the function’s own locals.

Everything else needs no allocation: indexing, iterating, sub-slicing into a local that stays local, comparing, and passing to a callee that only reads.

Crossing a call

Two facts about a function are enough to keep the caller’s analysis local and exact, and both are inferred from the body rather than written:

per parameter — does the callee let this argument outlive the call?
for the result — which parameters may the returned value be a view of?

They are computed bottom-up over the call graph and recorded in module metadata. Recursion starts optimistic and iterates to a fixpoint, so a self- or mutually-recursive function converges on the truth rather than on the conservative answer.

Two cases get the pessimistic answer instead — every parameter kept, the result viewing everything:

a call through a trait object, because which body it reaches is a word read at run time, so there is no one summary to consult. Reading through a concrete type or through a bounded type parameter is unaffected, since monomorphization turns the second into a direct call too;
a function whose body is not available — an extern, which is the declaration form for exactly that. The foreign side may retain what it was given, and nothing here can tell.

What happens when a slice escapes

With an allocator, the array is promoted. It is allocated as an ARC buffer instead of a stack slot, the slice’s owner points at it, and nothing else about the program changes:

render() -> []u8
    var line: [8]u8

    line[0] = 104u8
    line[1] = 105u8

    line[0..<2]

var l = render()

print(l.len, l[0], l[1])

2 104 105

The array keeps its type, and only its storage moves. A promoted [8]u8 is still a [8]u8: its length is still a compile-time constant, it is still a value that copies on assignment, and every index and store is emitted exactly as an unpromoted one’s is. What changes is where the name’s address points, and that a view of it carries that buffer as its owner. Rewriting the declaration into a []u8 would have been the other way to do it and is wrong — it changes the type at every use, and an array is a value type where a view is not.

Which array moves is decided by the root of the escaping view. An index step is walked through, because an element of a local array of arrays is part of that array’s storage; a field step is not, because that storage belongs to a struct. Only arrays that are both sliced and escaped are promoted.

Two roots have nowhere to be promoted to, and are diagnostics rather than promotions — an array a caller passed by value, which is the caller’s layout, and an array that is a field of a struct on the frame:

first_two(a: [4]int) -> []int = a[0..<2]

print(first_two([1, 2, 3, 4]).len)

a slice of an array this frame owns is returned, so it would outlive the array, and the storage is not this body's to move — it is a field of a value, or an array a caller passed by value. Declare it as a '[]T', which makes a buffer of its own and owns it, or as a '&[N]T' where the length is fixed

Without an allocator it is always a compile error. Under no alloc there is nothing to promote into, so every promotion becomes a refusal reported at the view that leaves the frame. That is how every other allocation-gated feature behaves in the allocator-free subset — growable arrays, escaping closures, and &T creation are all compile errors there — so it introduces no new rule.

Promotion is silent, not hidden

Silent promotion earns the obvious objection: an allocation appears that nothing in the source asked for. The answer is discoverability rather than ceremony — --explain-escapes reports every promotion the compiler made and the route that forced it:

$ sysl build --explain-escapes tty.sysl
tty.sysl:31:12: 'buf' is promoted to the heap, because this view of it is returned

One line per array, in source order, on stderr, accepted by every subcommand. The position is the view that forced the move rather than the declaration, because that is the half a reader cannot work out for themselves. This is Go’s -m, and it is the right shape: the common case costs no reading, and “why did this allocate?” always has an answer. A program that must not allocate says so with no alloc, and then the compiler enforces it rather than reporting it.

The idiom worth reaching for first, even where an allocator exists, is the last one: return a count and let the caller slice its own buffer. That is what snprintf does, what Rust’s buffer writers do, and what most kernel code wants.

Reinterpreting storage

An allocator carves bytes and hands back a typed pointer — that is the whole of what an allocator does. A driver takes an address the datasheet gives as a number and reaches the register block at it. Both need a way to say which type some bytes are, and both are cases the raw tier already committed to.

Three directions, two spellings, because they are not equally dangerous:

written	direction	tier
`usize(p)`	a pointer as a number	an ordinary conversion
`ptr_cast(n)`	a number as a pointer	unsafe
`ptr_cast(p)`	one pointee type as another	unsafe

A pointer becomes an integer through the ordinary conversion syntax, because it is an ordinary conversion: usize is wide enough to hold any address by definition, so it is total and loses nothing, and the result is a number that cannot be dereferenced. isize takes one too, which is what a program comparing addresses against a signed offset wants.

struct Node
    value: int
end Node

var arena: [64]u8 = [0u8; 64]
var n: *Node = ptr_cast(&arena[0])

n.value = 42

print(n.value, sizeof(Node), usize(n) == usize(&arena[0]))

42 4 true

The target type comes from whatever receives the result — the same way va_arg, a bare None, and a bare null all take theirs. Where that is not where a reader wants to say it, it may be written on the form: ptr_cast[*Node](&arena[0]) is the written type-argument list at a special form. Where neither says which pointer is wanted, the program is told to annotate what receives it:

var arena: [64]u8 = [0u8; 64]
var p = ptr_cast(&arena[0])

print(1)

'ptr_cast' reads an address as a pointer to some type, and nothing here says which

ptr_cast never produces a &T. A reference is a safe-tier value — non-null, refcounted, and relied on by everything the safe subset promises — and an address invented from bytes has no count for ARC to own and no object to be non-null about:

struct Node
    value: int
end Node

var arena: [64]u8 = [0u8; 64]
var n: &Node = ptr_cast(&arena[0])

print(n.value)

'ptr_cast' never produces a reference: a '&T' is counted and non-null, and an address read out of bytes carries no count for anything to own — read it as a '*T'

A weak T is refused for the same reason, and the fat types — a slice, a string — for that reason and one more: they are wider than an address, so there is nothing to reinterpret. What comes out is a *T, and reaching anything else from it is the ordinary route through *p.

sizeof, alignof and offsetof, which measure what is being carved, are on the expressions page.

Device memory

ptr_cast gets a driver to the register block. It does not get it a correct driver, and the missing half is this: an optimizer is entitled to assume that reading the same storage twice yields the same value, that a store nobody reads is a store nobody needs, and that two accesses in a row may be one wider access. Every one of those assumptions is false at a device. while regs.status == 0u32 do () is a loop that reads a register until the hardware changes it, and a compiler that hoisted the read out would spin forever on the first value it saw.

So sysl has C’s qualifier, spelled the way C spells it — in the type:

struct Uart
    status: volatile u32
    data:   volatile u32
    baud:   u32
end Uart

var block = Uart(1, 0, 115200)
var regs: *Uart = &block

regs.data = 65

print(regs.status, regs.data, regs.baud)

1 65 115200

A volatile place is one whose reads and writes are effects, not value computations. It may change without the program changing it, and reading it may itself do something. So the compiler emits exactly the accesses the source wrote, exactly once each, in the order written — never adding, dropping, merging, or moving them relative to one another.

It constrains the compiler, not the machine. No atomicity, no ordering against another core, no protection from a torn read. C spent two decades learning this; for talking to another thread the tools are &sync T, Mutex[T], Atomic[T] and explicit orderings, and none of them is spelled volatile. A program that reaches for this word to share a counter has written a race with a keyword in front of it.

It qualifies storage, and a value read out of storage is an ordinary value

This is the rule everything else follows from. regs.status above has type u32 — not volatile u32 — because what a load hands back is a number, and a number is not somewhere a device can write. What is qualified is the place, and the qualifier lives in the three types that name a place somebody else owns:

written	what is qualified
`status: volatile u32`	a struct field
`bank: [4]volatile u32`	an element — a GPIO bank
`p: *volatile u32`	a pointee — the lone register

Everywhere else the type being written is the type of a value: what a var holds, what a parameter receives, what a function hands back, what a type argument stands for.

var x: volatile u32 = 0u32

print(x)

'volatile u32' is the type of *storage*, and this is a value — what a read of a volatile place hands back is an ordinary 'u32'. The qualifier goes where the storage is named: a struct field, an element, or the pointee of a '*T', as '*volatile u32'

The diagnostic says which spelling was wanted, because a program that writes var x: volatile u32 almost always meant *volatile u32.

Per field, not per aggregate. C also allows volatile struct Uart; sysl does not, and the block above shows why. baud is a shadow value the driver keeps in ordinary memory beside the registers, and every real device header has one — a reserved word, a cached configuration, a software flag. A qualifier on the whole struct would sweep it in:

struct Uart
    status: u32
end Uart

var p: *volatile Uart = null

print(1)

a register block is qualified one field at a time

Qualifying per field is the same power with the opt-out, it is what CMSIS and every other vendor header already does, and it makes the restriction below a check on one scalar instead of a walk of a type.

Only a scalar or a raw pointer may be qualified. The promise is about the load and the store the source wrote, so it is only meaningful where an access is one instruction:

a counted value is refused outright — a &T, a weak T, a slice and a string come with retains and releases the compiler places, and a retain that may not be elided is not a request anybody could act on;
a trait object is refused for a plainer reason: it is two words, so touching one is two accesses whatever the source says, and the table beside the value is this program’s rather than a device’s;
a constrained subtype is refused, and this one is about trust rather than instructions. A Level = int within 0..7 is the claim that a value has been checked; a register holds whatever the device put there. So the register is declared at the base type and what comes back is converted — one written conversion, checked, at the point the value arrives;
a data enum is refused — a tag beside a payload is more than one access however it is written.

A simple enum is admitted, since it is its underlying integer: it is one load, and it is the spelling a register’s mode field wants. So is a bitfield, which is the one case where the access reaches more than the field named — the qualifier applies to the container the field is bits of, so a write is a read-modify-write of the whole of it. @packed on attributes states that rule and what it costs a driver.

A struct that holds a register carries no invariant. A check is a call taking every field, so it reads the whole block however few fields the clause names — an invariant written over the shadow value beside the registers would make writing that shadow an access to the device. There is nothing to hold the clause true either: a device changes a register between the check and the instruction after it. A register is checked where it is read.

What the compiler does with it

A qualified access lowers to LLVM’s load volatile / store volatile, which is exactly the barrier this needs: it stops the reordering, elision and merging above, and stops nothing else. There is no runtime cost and no runtime component.

A qualified field is reached at its own address, not lifted out of the block. Reading a Uart to find out what is in status would also read data, and reading a data register is how a FIFO is popped — so a qualified field gets a place walk, one getelementptr and one load volatile, with nothing else touched.
A whole block copied is a copy of every register in it. var u = *regs is one access to each, which is as much an effect as one access to one of them, so the aggregate access is marked too. Whether a driver wants that is the driver’s business; what it does not get is a silent unqualified read of hardware.
An address taken of a register is the address of a register. &regs.status has type *volatile u32, so a driver may hand one register to a helper and every access the helper makes is still an access to a device. Without that, a driver would have to be one function.
A type parameter never binds to a qualified type. The loads and stores a generic body emits are its accesses, written once and shared by every instantiation, so it cannot promise to have written the ones a particular caller had in mind.

volatile is not reserved. It is special only in front of another type, so a program with a variable, a field, a function, or a type of its own by that name still compiles — the same arrangement sync has after &:

var volatile = 7

print(volatile + 1)

[]const T composes with it and means a different thing. const is a property of the view — these elements may not be written through this handle — while volatile is a property of the element. A read-only device register is []const volatile u32, and both words are doing work.

Where `defer` sits

defer is the model’s answer for what the language does not own: a descriptor from open, a FILE* from fopen, a block from malloc, a lock taken from a mutex. ARC gives back a reference, a string, and a slice’s backing without being asked, and knows nothing about those.

Three facts place it against everything above:

A deferred statement runs before the block’s ARC releases, so every local it names is still alive when it runs — including the one holding the resource it is closing. Leaving from the middle unwinds outward: the innermost block runs its deferred statements and then gives up its counts, then the block outside it does the same.
It owns nothing and allocates nothing. defer takes no count, makes no box, and adds no word to any value; a program that does not use it emits nothing for it. That is what keeps it available under no alloc, where the resources it releases are the only ones there are.
A trap runs nothing. A trap aborts without stack cleanup, and defer does not qualify that: a broken invariant means the program’s model of itself is already wrong, and running cleanup against that state is how a corrupt program writes its corruption to disk on the way down.

A destructor

impl Drop for T says what a type does when the last reference to one of its values goes. It declares one member, drop(self), and it answers nothing:

struct Handle
    id: int

impl Drop for Handle
    drop(self) = print("closing", self.id)

hold()
    var h: &Handle = Handle(7)
    print("working")

hold()
print("done")

working
closing 7
done

It is for the resource the language does not manage. ARC returns the storage and releases whatever the value holds; what it cannot do is close a descriptor, unmap a region, or hand a handle back to the C library that made it. Those live at the far end of a *T or behind an integer, and nothing about either says it is owned. The destructor is where that is said, once, beside the type.

defer is the other way to say it, and neither replaces the other. defer close(f) covers every site a program can name. Under ARC a value can also die where there is no site to write one — and that case is the whole argument for this being a capability rather than a shorthand:

struct Handle
    id: int

impl Drop for Handle
    drop(self) = print("closing", self.id)

hold()
    var xs: []&Handle = [Handle(1), Handle(2)]
    print("holding", xs.len)

hold()
print("done")

holding 2
closing 2
closing 1
done

Nothing in that program names the moment either element dies. The slice goes, and its elements go with it — so no defer could have been written, and a leak there would not be something the author could have prevented. Where both would work, the destructor is the better one: it is written once, and a caller cannot forget it.

It costs nothing to have. Release already calls through a per-payload hook, and a destructor is a call at the top of that hook. A type without one produces exactly the hook it always did.

The four limits, each a consequence of where it runs

It runs before the value’s own references are released, so it is handed self intact and a field may be read to close what it names. It borrows rather than taking a count — the count is already zero, and taking one would resurrect the object into a second teardown.

It is not called for a value that never reached the heap. A value type is copied, and a copy is not a second resource: there is no single point of death to hook, and running it per copy would close one descriptor several times. So a destructor is for a type held behind a &T, and a program that puts one on a type it then passes by value gets no destructor rather than a wrong one.

It is not called for a value in a reference cycle, whose count never reaches zero. That is not a new consequence of this feature but the existing cost of counting rather than collecting — the storage already leaks there. A weak T is what breaks a cycle.

It is not called for module storage when the program ends. Storage that lasts the whole run is never let go of, so its count never reaches zero. There is no exit pass and there will not be one: a process exiting is what returns what it held, and running destructors at exit is the feature C++ has spent decades regretting, because the order two statics come apart in has no good answer. What it costs is that a buffered writer held in a static is not flushed at exit; the program flushes it.

No order is promised among siblings. Two values that die together — the elements of a slice, the fields of a struct — come apart in an order that follows the teardown worklist, which today makes it last-to-first. A program that needs one before another has to say so.

Crossing a concurrency domain

A &T permits aliasing and mutation through any reference, which is safe within one concurrency domain and nowhere else: its refcount is non-atomic, and two threads touching it would race. So a &T may not leave its domain, and crossing one copies by default — which is what process IPC does anyway, and what keeps the ordinary path free of atomics.

The exception is &sync T, whose refcount is atomic. It is a distinct type from &T with no conversion either way, and which one an object is is chosen where it is allocated:

struct Cell
    n: int
end Cell

send(c: &sync Cell) -> int = c.n

var c: &Cell = Cell(1)

print(send(c))

'&Cell' and '&sync Cell' are distinct types, and neither converts to the other: a count is atomic or it is not from the moment the object is allocated, and a conversion would put an ordinary retain beside an atomic one. Allocate Cell as a '&sync Cell' where it is constructed

A conversion would put an ordinary retain beside an atomic one, so the count is atomic or it is not from the moment the object exists. &sync T makes the reference safe to share, not the object safe to mutate — that still wants a Mutex.

`@crossing` — where the rule is asked

The rule above says what may cross. @crossing says where: it is the annotation a facility writes above the function that hands a value to another domain, naming the parameters it hands it through. sysl.posix.threads.spawn is declared with one, and so is any package binding a scheduler of its own:

struct Cell
    n: int
end Cell

struct State
    cell: &Cell
end State

@crossing(s)
start(s: *State) -> int = s.cell.n

var c: &Cell = Cell(1)
var st = State(c)

print(start(&st))

what 's' of 'start' points at reaches another concurrency domain, so every count inside it has to be atomic

A *T parameter is looked through, and that is the whole of what the annotation buys. A raw pointer carries no refcount of its own, which says nothing about the object at the far end — and the object at the far end is what crossed. Everything else is asked about the parameter’s own type. Hold the cell as a &sync Cell and the same program compiles.

It costs nothing at run time: no code is emitted, no signature moves, and a program that satisfies it is the program it would have been without the line. What it adds is the refusal, made at each call — so a generic facility is asked afresh for every set of type arguments, exactly as a &sync Box[T] is.

A boundary nobody marks is not examined. The annotation is how a library author says a domain begins here, and there is no way for the compiler to guess: a scheduler in a package looks like any other function until somebody writes the line.

Hazard summary

segfault source	prevented in the safe subset by
use-after-free / double-free	ARC on `&T`; `weak` degrades to `Option` and never dangles
null dereference	non-null references; nullable is `Option`
out-of-bounds	length-carrying arrays and slices, checked everywhere
slice outliving its buffer	the slice’s `owner` word retains it; escaping locals are promoted
refcount race across threads	`&sync T` is atomic; a `&T` may not cross a domain, checked at a `@crossing` parameter
dangling or wild pointer	impossible without `*T`

Only *T opts out, and it opts out visibly.

One hazard is not on that list: racing on the fields of an object two threads deliberately share. Preventing that needs proof of exclusive access, which is the thing this language trades away, so it is answered by a Mutex and by convention rather than by the type checker. It takes &sync or *T to reach the situation at all, so it is at least as greppable as everything else here.

The two worlds, one language

Application, server, utility: T and &T, plus weak, slices, and arrays. Safe, pleasant, ARC-managed.
Kernel, driver, allocator-free: T, *T, fixed arrays, slices, and manual malloc/free. A module that never creates a &T emits no allocation and no allocator dependency, exactly like C, and stays bounds-checked wherever it uses arrays and slices.

The boundary is not a convention — it is compiler-enforced through the allocator capability. What it gates is allocation, not ownership. Allocator-free code may hold, pass, copy, and drop a &T or a heap-backed slice that something else created: retain and release are a few instructions, and the free path goes through the object’s own deallocation hook. What it may not do is make one. That is what lets a driver keep the &Device its bus manager handed it, and a no alloc parser read a heap-backed slice it was given — neither of which is expressible if ownership stops at the boundary.

Next: arrays and slices — the two sequence types, and what a view keeps alive.

matrix

2026-08-16T01:26:07.924728867Z

A vector space and the matrices over it, then Gaussian elimination on top.

The axis: an operator whose result is neither operand’s type. A * v gives a vector and A * B gives a matrix, so one type carries three implementations of one trait — Mul[Vector, Vector], Mul[Matrix, Matrix] and Mul[real, Matrix]. Each is selected by the type of the right operand, and each declares what it hands back.

Nothing here is a method that wanted to be an operator, which is the whole point of the exercise. This is the program that demonstrates parameterized traits carrying real weight: a type implements a trait once at each argument list, so three multiplications on one type are ordinary rather than a conflict, and the argument list is what tells a call which it meant.

Contrast datetime, where the same mechanism does not rescue Instant - Instant -> Duration. The difference is exactly which position the varying type is in: here the result is named by the row that was selected, and there it would have had to be named by a row that could not exist.

What it exercises

A matrix is a handle exactly as a vector is. The cells are stored row-major in one &Buf[real], so the operators build fresh values and copy is how a caller stops sharing. That makes the memory question visible in a place people usually do not think about it: a linear-algebra type is a container, and whether B = A shares or copies is a decision the language makes you write down.

Gaussian elimination is where the numerics land. Pivoting, and the fact that a comparison against zero is the wrong test for a float, are what the second half is about — and they are ordinary sysl, because the operator work in the first half means the algorithm reads as the algorithm.

Source · Next: ring — ranges, attributes, contracts, and invariants.

The math module

2026-08-16T01:26:07.924728867Z

sysl.math is four files and three traits, and the interesting thing about it is that the three traits are written three different ways — because the types they cover are three different shapes. Above them sit the free functions, which are not members of anything and say in a bound what they need. It requires no capability at all: every name here is reachable under no alloc and on a target with no operating system.

@no_alloc
@no_os

import sysl.math.{Float, Bits, min, pi}

var two = 2.0
var u = 0b1011u8

print(two.sqrt(), pi, min(3, 7))
print(u.count_ones(), u.rotate_left(1u32))

1.41421 3.14159 3
3 22

The constants

import sysl.math.{pi, tau, e, sqrt2, ln2, ln10}

print(pi, tau, e)
print(sqrt2, ln2, ln10)

3.14159 6.28319 2.71828
1.41421 0.693147 2.30259

Those are the full-precision values printed by %g‘s six significant digits, which is what print does with a float. The constants themselves carry every digit a real holds.

All six are real, which is the width they are correct to and the width arithmetic reaches for unless a program says otherwise. An f32 program writes f32(pi): the conversion is a constant the compiler folds, so it costs nothing at run time, and one declaration per constant is better than two that could drift apart.

They are digits rather than expressions. tau is written out rather than as 2.0 * pi, because a constant is a value and not a computation — and the last bit of a doubled binary64 is not always the last bit of the correctly rounded product.

tau earns its place beside pi because it is the one that appears in the arguments to sin and cos: a whole turn is tau, a quarter turn is tau / 4.0, and no factor of two has to be carried around to remember it.

`Float`

trait Float: Eq + Ord + Neg + Add + Sub + Mul + Div

    // The type's own values, asked without a receiver.
    zero() -> Self
    one() -> Self
    max_value() -> Self
    epsilon() -> Self
    infinity() -> Self
    nan() -> Self
    pi() -> Self

    // Required — each width binds these to its own libm entry point.
    sqrt(self) -> Self
    cbrt(self) -> Self
    exp(self) -> Self
    exp2(self) -> Self
    ln(self) -> Self
    log2(self) -> Self
    log10(self) -> Self
    pow(self, exponent: Self) -> Self
    hypot(self, other: Self) -> Self
    sin(self) -> Self
    cos(self) -> Self
    tan(self) -> Self
    asin(self) -> Self
    acos(self) -> Self
    atan(self) -> Self
    atan2(self, x: Self) -> Self
    sinh(self) -> Self
    cosh(self) -> Self
    tanh(self) -> Self
    asinh(self) -> Self
    acosh(self) -> Self
    atanh(self) -> Self
    floor(self) -> Self
    ceil(self) -> Self
    round(self) -> Self
    trunc(self) -> Self
    fmod(self, divisor: Self) -> Self
    abs(self) -> Self
    copysign(self, sign: Self) -> Self
    to_radians(self) -> Self
    to_degrees(self) -> Self

    // Answered by the trait, once, for both widths.
    signum(self) -> Self
    recip(self) -> Self
    square(self) -> Self
    log(self, base: Self) -> Self
    lerp(self, to: Self, t: Self) -> Self
    is_nan(self) -> bool
    is_infinite(self) -> bool
    is_finite(self) -> bool

A trait rather than two sets of functions. The shape was forced by a language decision that has since been reversed, and is kept because it is the better one anyway. sysl had no overloading when this was written, so free functions could not call the square root of a real and the square root of an f32 by one name — it would have needed sqrt and sqrtf the way C does. Two free sqrts would resolve correctly today.

What the trait still buys is the half overloading does not: a member that is arithmetic over the others — the logarithm in an arbitrary base, the hypotenuse — is written once as a default and inherited by both widths, where two free functions would need it twice and could disagree. Dispatch on the receiver is worth having for its own sake too: x.sqrt() is the same three words whichever width x is, and changing a declaration from f32 to real sends nobody editing call sites.

The split between what is required and what is answered is where the mathematics is. A method whose result C computes — a range-reduced sine, a correctly rounded root — is required, and each width binds it to its own libm entry point. A method that is arithmetic over the others is a default, written once and inherited by both. So log in an arbitrary base exists in exactly one place, and adding a third floating-point width would be 38 bindings and no new mathematics.

import sysl.math.{Float, tau, e}

var two = 2.0
var three = 3.0
var eight = 8.0
var hundred = 100.0
var eightyone = 81.0
var quarter = tau / 4.0

print(two.sqrt(), eight.cbrt())
print(e.ln(), two.exp2())
print(hundred.log10(), eight.log2(), eightyone.log(three))
print(two.pow(10.0), three.hypot(4.0))
print(quarter.sin(), quarter.cos())

1.41421 2
1 4
2 3 4
1024 5
1 6.12323e-17

Four of those lines are decisions rather than arithmetic.

ln is spelled for what it is, rather than as C’s bare log — which reads as though it were the general one and is the single most common way to get a base wrong. log(base) is the general one, and it is the default written over ln.

log2 and log10 are required separately rather than left to that default, because reading them back through a ratio loses digits that libm keeps.

hypot is not (x*x + y*y).sqrt(). The squares of operands near the top of the range overflow to infinity when the answer itself is perfectly representable; libm’s does the scaling that avoids it.

cos(tau/4) is 6.12e-17 and not zero, which is not a bug in anything — a quarter turn is not exactly representable in binary, so the argument handed to cos is not exactly π/2. This is the ordinary floating-point fact, and the page shows it rather than choosing an example that hides it.

Rounding, sign, and the rest

import sysl.math.Float

var half = 2.5
var neg = -2.5
var three = 3.0
var seven = 7.5
var four = 4.0
var zero = 0.0
var ten = 10.0
var one = 1.0

print(half.floor(), half.ceil(), half.round(), neg.trunc())
print(neg.abs(), three.copysign(-1.0))
print(seven.fmod(2.0))
print(four.recip(), three.square(), zero.lerp(ten, 0.25))
print(one.atan2(one).to_degrees())
print(neg.signum(), zero.signum())

All four rounding functions answer in the float’s own type. A floor that returned an integer would have no answer for the operands that do not fit one — the caller who wants an integer is the caller who knows the range, and casts.

round goes away from zero at a half, which is C’s rule and not the banker’s rounding a printed value gets. trunc goes towards zero, which is what a cast already does.

fmod is not %. The integer types have Rem and the floats do not, because a float remainder is a library operation rather than an instruction. It keeps the sign of the receiver.

atan2 takes the two coordinates rather than their ratio, which is what lets it tell the four quadrants apart, and the receiver is the vertical coordinate — matching the argument order the name has had since Fortran.

lerp is written a + (b - a) * t rather than a * (1 - t) + b * t. The second form is exact at t = 1 and this one is exact at t = 0, and starting where you said you would start is what a caller notices.

signum answers a zero with that zero rather than with a one it cannot justify: it is a pair of comparisons, so it does not see a negative zero, and a NaN satisfies neither comparison and leaves by the same arm holding itself. abs and copysign are the other two readings of a sign, and those do see a negative zero, because they work on the bit.

Hyperbolics, and where they have no answer

import sysl.math.Float

var one = 1.0
var two = 2.0
var half = 0.5
var below = 0.5
var outside = 2.0
var neg = -3.0

print(one.sinh(), one.cosh(), one.tanh())
print(one.sinh().asinh(), two.cosh().acosh(), half.tanh().atanh())
print(neg.asinh(), below.acosh().is_nan(), outside.atanh().is_nan())

1.1752 1.54308 0.761594
1 2 0.5
-1.81845 true true

The three inverses are the ones with domains. acosh wants an argument of at least one, atanh one strictly between −1 and 1, and asinh is defined everywhere — which is why the third line asks two of them for an answer they do not have.

Outside a domain the answer is a NaN, not a trap. That is the same thing asin and acos do outside theirs: a float has a value meaning no answer, and the library hands it back rather than stopping the program. It is quiet, so a program that can reach outside a domain should say what it does about it — is_nan is the test, and a NaN that flows on will keep failing every comparison it meets.

The type’s own values

import sysl.math.Float

var f: f32 = 2.0f32

print(real.epsilon(), real.max_value())
print(f.sqrt(), f32.pi(), f32.epsilon())

2.22045e-16 1.79769e+308
1.41421 3.14159 1.19209e-07

These are members with no receiver, reached through the type, and they are what makes the defaults possible at all: a signum needs a one to answer with and a recip needs a one to divide, and neither can be written in a body shared by two widths unless there is a way to ask a type for its own one. Self.one() is that way, so a routine bounded by [T: Float] can build a value of a width it has never met.

epsilon is what a convergence test should be written against — a loop that stops when two iterations agree to within a few epsilons stops at the right point at both widths, where a literal tolerance does not.

The two that no literal spells get bodies that say what they are: infinity() is 1.0 / 0.0 and nan() is 0.0 / 0.0. Dividing a float by zero is not the error dividing an integer by zero is — IEEE 754 says what the answer is, and this is where the library says it too.

The only thing that stays per width beyond the libm bindings is the pair of angle conversions, whose factor is π over 180 — and 180 is not something a zero and a one can be built up into.

NaN, and what compares to it

import sysl.math.{Float, infinity, nan, min}

var one = 1.0

print(nan().is_nan(), infinity().is_infinite(), one.is_finite())
print(min(nan(), one).is_nan(), min(one, nan()).is_nan())

true true true
true false

is_nan is self != self — the only value not equal to itself, which is both the definition and the test, and the reason an equality check cannot be used to look for one. is_infinite asks whether the magnitude exceeds the largest finite value, a condition only the two infinities meet and which a NaN fails the way it fails every comparison.

That second line is the one to read carefully. min(nan(), 1.0) is a NaN and min(1.0, nan()) is 1.0, and neither is a bug. A NaN is less than nothing and greater than nothing, so the single comparison each of these makes is false whichever way round the operands go, and both fall through to the arm holding the first argument.

That is said here rather than worked around. Propagating a NaN from one argument position while dropping it from the other is what C’s fmin was criticised for — and the alternative is a comparison per argument on every call, to spare a case a caller can see coming. A program that must reject a NaN tests for one.

`min`, `max` and `clamp` are not `Float`‘s

import sysl.math.{min, max, clamp}

var half = 2.5

print(min(3, 7), max(3, 7), clamp(12, 0, 10))
print(min("b", "a"), max(half, 1.5))
print(clamp(-5, 0, 10), clamp(5, 0, 10))
print(min((1, 2), (1, 3)))

3 7 10
a 2.5
0 5
(1, 2)

They are generic over Ord, and that is why they are in a file of their own. Nothing about picking the smaller of two things is arithmetic: min over the integers is the same three words as min over the floats, over a string, over a tuple, and over any type a program has written an lt for. A version living on Float would have been the narrowest useful one and would have left every other type asking why.

A tie answers with the first argument. min is written if b < a then b else a rather than the other way round, and for types whose equality does not mean identity — a record ordered on one field, a pair ordered on its first — which of two indistinguishable values comes back is something a caller can observe. Taking the first is what makes a fold over a sequence stable.

clamp tests the low end first, so an inverted range answers low. There is no check that the two bounds are the right way round: a bound is nearly always a constant or a length at the call site, and a contract is the tool for saying so where it is not.

Comparing floats that were computed

Binary floating point does not hold 0.1 + 0.2 == 0.3, so a program that checks a computation against a written-down number needs a tolerance rather than an equality:

import sysl.math.{approx_eq, approx_eq_rel, nan, infinity, Float}

print(approx_eq(0.1 + 0.2, 0.3, 1e-12), approx_eq(1.0, 1.5, 0.1))
print(approx_eq(infinity(), infinity(), 0.0), approx_eq(nan(), nan(), 1.0))
print(approx_eq_rel(1e18, 1e18 + 1000.0, 1e-6), approx_eq_rel(1.0, 1.5, 1e-6))

true false
true false
true false

approx_eq takes an absolute tolerance, which is what a delta comparison is. approx_eq_rel scales it to the larger of the two operands, so the tolerance reads as a fraction — 0.001 means “within a tenth of a percent” whatever the magnitude — and is the one to reach for when the values could be any size. Near zero the relative form becomes strict, since the scale goes to zero with the operands; that is the case the absolute form is for.

Two behaviours are worth knowing rather than discovering. Identical infinities are close, because both functions test equality before subtracting — inf - inf is a NaN, and the subtraction alone would call a value unequal to itself. And a NaN is close to nothing, including another NaN, whatever the tolerance, which falls out of the comparisons and agrees with ==.

Each has an assertion beside it, which stops the program and names both values and the tolerance rather than answering bool:

import sysl.math.assert_approx_eq

assert_approx_eq(0.1 + 0.2, 0.3, 1e-12)
assert_approx_eq(0.1 + 0.2, 0.3, 1e-12, "the sum")
print("both held")

both held

assert_approx_eq_rel is the same against the relative test. They live here rather than beside assert_eq in the core, and that is forced rather than chosen: Float is declared in this module and reaches Eq, Ord and the arithmetic traits in the core, so sysl.math depends on sysl — and a float assertion written in the core would point an edge back the other way, which the module graph refuses. Anyone writing float assertions imports this module already, since it is where the float functions are.

Mixing types is refused, as everywhere else in the language:

import sysl.math.min

print(min(1, 2.0))

'b' of 'sysl.math.min' is int, but real was given

`Signed` and `Bits` — a different mechanism

trait Signed
    abs(self) -> Self
    signum(self) -> Self

trait Bits
    count_ones(self) -> u32
    count_zeros(self) -> u32
    leading_zeros(self) -> u32
    trailing_zeros(self) -> u32
    leading_ones(self) -> u32
    trailing_ones(self) -> u32
    reverse_bits(self) -> Self
    rotate_left(self, n: u32) -> Self
    rotate_right(self, n: u32) -> Self

Neither of these has an impl block anywhere, and neither could. Float is a trait with an impl per width because there are exactly two widths. The integers are an open family: i5 and u12 are types a program may name, so there is no finite list of scalars to write an impl for, and five blocks covering i8 through isize would leave i128 and every narrow width without one — a worse surface than none at all.

So membership is the compiler’s, by the same rule that makes an int an Add without anything having written impl Add for int. What is in the source file is the part a declaration can say: the names, the signatures, and what each one means.

The trait still has to be in scope to be reached. That is what a compiler-provided membership does not change — it settles which types have the member, not which files may name it:

import sysl.math.pi

var x = 2.0

print(pi, x.sqrt())

real has 'sqrt' from sysl.math.Float, and that trait is not in scope here — import it to reach the member

Importing the module is not the same as importing the trait: pi is in scope on that line and sqrt is not.

Signed covers the signed widths only; Bits covers both signednesses, because a bit pattern is a bit pattern:

import sysl.math.Signed

var u = 5u8

print(u.abs())

type 'byte' has no method 'abs'

`Signed`

import sysl.math.Signed

var n = -42
var z = 0
var m: i32 = -2147483647 - 1
var big: i128 = -170141183460469231731687303715884105727

print(n.abs(), n.signum(), z.signum())
print(m.abs())
print(big.abs(), big.signum())

42 -1 0
-2147483648
170141183460469231731687303715884105727 -1

At the most negative value, abs answers that value again. The magnitude is one larger than the width can hold, and plain integer arithmetic in sysl wraps — so this is what the two’s-complement negation beside it already does, and the alternative would be a member that traps where the - next to it does not.

signum answers in Self rather than a fixed width, so it can be multiplied back into a value of the same type — which is what a signum is usually for.

`Bits`

import sysl.math.Bits

var u = 0b1011u8
var zero8 = 0u8
var all8 = 255u8
var wide: u32 = 1u32

print(u.count_ones(), u.count_zeros())
print(u.leading_zeros(), u.trailing_zeros())
print(u.leading_ones(), u.trailing_ones())
print(u.reverse_bits(), u.rotate_left(1u32), u.rotate_right(1u32))
print(zero8.leading_zeros(), zero8.trailing_zeros())
print(all8.leading_ones(), all8.count_zeros())
print(wide.leading_zeros(), wide.rotate_right(1u32))

3 5
4 0
0 2
208 22 133
8 8
8 0
31 2147483648

Every one of these is a shift-and-mask loop a program would otherwise write, and every one is a single instruction on the machines sysl targets — count_ones is popcnt, leading_zeros is lzcnt or clz, the rotations are rol and ror. That is the case for a member rather than a comment recommending a loop.

Zero answers the width, at both ends, rather than being undefined the way the bare machine instruction is on some targets — 0u8.leading_zeros() is 8 and so is its trailing_zeros. That is what makes leading_zeros usable as “how far left is the top bit” with no special case in front of it, and what makes the same program print the same number on every machine.

count_zeros is worth having rather than left to a subtraction, because the width is the fact the caller would otherwise have to know and this is the member that already knows it. leading_ones and trailing_ones are the same pair counted over set bits, so -1 answers the width and 0 answers nothing.

The rotation amount is taken modulo the width, so every amount is meaningful and none of it is undefined — which is the whole reason to call this rather than write (x << n) | (x >> (w - n)), an expression that shifts by the width when n is zero and is undefined when it does. The amount is a u32 rather than Self, because how far to rotate is a count of bit positions and not a value of the type being rotated: a narrow receiver would otherwise be unable to state an amount its own width cannot hold.

reverse_bits is not a byte order. The width is the receiver’s, so it is a different function at every type.

There is deliberately no `swap_bytes`

import sysl.math.Bits

var w: u32 = 7u32

print(w.swap_bytes())

type 'uint' has no method 'swap_bytes'

Reversing the byte order needs a whole number of bytes and at least two, so a u24 has no answer to it and a u4 has none either. Every member of Bits is total over every integer type, because a [T: Bits] body is written once and instantiated later — a member that worked at u32 and not at u24 would turn a bound that was supposed to have proven an operation into a failure at somebody else’s instantiation.

A program that means to reorder bytes has the shifts, and knows its own width while writing them.

The arithmetic above the operators

Six free functions sit above Signed and Bits, and they are what the operators do not give you:

pow(base, exponent)          gcd(a, b)                lcm(a, b)
divmod(a, b) -> T, T         is_power_of_two(x)       next_power_of_two(x) -> Option[T]

@no_alloc
@no_os

import sysl.math.{pow, gcd, lcm, is_power_of_two, next_power_of_two}

print(pow(2, 10), pow(3, 0u32))
print(gcd(12, 18), lcm(4, 6), lcm(21, 6))
print(is_power_of_two(8), is_power_of_two(0))
print(next_power_of_two(17).unwrap_or(-1))

1024 1
6 12 42
true false
32

Free functions, and the bound is the specification

None of these is a trait member, and the reason is the one this page already gave for min. A member has to belong to a trait, and the trait is what decides which types have it — but nothing here is a question about a bit pattern, which is what Bits collects, nor about having a sign, which is what Signed collects.

What each one actually needs is written in its own bound instead:

function	bound
`pow`	`Mul + Ord`
`gcd`	`Rem + Eq + Ord + Sub`
`lcm`	`Rem + Eq + Ord + Sub + Div + Mul`
`divmod`	`Div + Rem`
`is_power_of_two`	`Bits + Ord`
`next_power_of_two`	`Bits + Ord + Shl + Sub`

Read gcd‘s: Rem because Euclid’s algorithm is a remainder loop, Sub and Ord because it has to answer a magnitude — and deliberately not Signed, which would have shut the unsigned widths out of a function that serves them perfectly well.

That is also the thing a trait member could not have offered. The memberships of Bits and Signed are the compiler’s, and no program can join them — so a member would have been closed to a program’s own numeric type forever, where a bound is satisfied by whoever satisfies it.

When one is not, the bound is what says so, by name:

import sysl.math.is_power_of_two

print(is_power_of_two(8.0))

'sysl.math.is_power_of_two' requires its type parameter 'T' to implement 'sysl.math.Bits', but real does not

And these are ordinary names in the module, so they are reached the way pi is — by importing them, not by importing the module:

import sysl.math.pi

print(gcd(12, 18), pi)

undefined function 'gcd'

`pow`

@no_alloc
@no_os

import sysl.math.pow

print(pow(2, 10), pow(-3, 3u32))
print(pow(2, 64u32), pow(2u8, 9u32))

1024 -27
0 0

The exponent is a u32 and not a T, because how many times to multiply is a count rather than a value of the type being multiplied — the same reason rotate_left takes one. A negative exponent has no answer among the integers, and saying so in the type is better than a trap:

import sysl.math.pow

print(pow(2, -1))

the literal -1 does not fit uint

An overflowing power wraps, as every other integer operation in the language does. pow(2, 64) at int is 0 and pow(2u8, 9) is 0, both arrived at honestly — the doubling that overflows is a * like any other. A program that needs to know writes the check it needs.

The implementation is repeated squaring, so the exponent costs a logarithmic number of multiplies rather than a linear one.

This one is the integers’. Its bound admits a real, and the body does not:

import sysl.math.pow

print(pow(2.0, 10u32))

cannot initialize 'acc': declared real but the value is int

A float raises through Float‘s own member — 2.0.pow(10.0) — which takes its exponent as a Self rather than a count, because a float exponent is a meaningful thing to have and an integer one is not the same operation.

`gcd` and `lcm`

@no_alloc
@no_os

import sysl.math.{gcd, lcm}

print(gcd(12, 18), gcd(-12, 18), gcd(12, -18), gcd(-12, -18))
print(gcd(7, 0), gcd(0, 7), gcd(12u8, 18u8))
print(lcm(4, 6), lcm(0, 5), lcm(21, 6))

6 6 6 6
7 7 6
12 0 42

Neither ever answers a negative, and how gcd gets there is worth reading. The magnitude is taken at the end rather than at the start: % truncates, so Euclid’s loop over negative operands arrives at the right divisor already, carrying the wrong sign, and one comparison at the end fixes it. Doing it at the start would have meant negating both operands first — two operations instead of one, and a signed-only one at that.

Because the negation is written zero - x rather than -x. Unary minus requires Neg, which the language gives to the signed integers alone, while Sub is every integer’s — so that one spelling is what keeps gcd(12u8, 18u8) on the third value of the second line.

gcd(x, 0) is x, which is both the identity the loop already produces and the answer number theory gives: everything divides zero, so the largest divisor the pair has in common is x‘s own.

lcm divides before multiplying — a / gcd(a, b) * b and not a * b / gcd(a, b) — because the product of the operands overflows at half the width where the answer itself would fit, and the quotient is exact by construction, gcd being a divisor of a. That is the same reason hypot is not sqrt(x*x + y*y). A zero operand answers zero rather than dividing by one, since gcd(0, 0) is zero and reaching the division would be a division by it.

`divmod`

@no_alloc
@no_os

import sysl.math.divmod

show()
    val q, r = divmod(17, 5)
    val nq, nr = divmod(-17, 5)

    print(q, r)
    print(nq, nr)

show()

3 2
-3 -2

Both are the operators’ own, so both truncate toward zero and the remainder takes the sign of the dividend. The reason to call this rather than write the two operators is that it says once what a reader would otherwise have to check twice: that the same two operands feed both.

It answers a result list and not a tuple, because the pair travels from callee to caller and nothing afterwards needs to hold the two together. A caller that does need to hold them writes the tuple itself.

A binding naming several things is a local form — its parts have nowhere to write a type — so the top of a program, which is a body, takes one exactly as a function does:

import sysl.math.divmod

val q, r = divmod(17, 5)

print(q, r)

3 2

Asking for the module’s storage instead is what has nowhere to put the types, and is refused:

import sysl.math.divmod

static val q, r = divmod(17, 5)

print(q, r)

a module-level 'val' states its type, and a binding that names several things has nowhere to write one — declare 'q' and 'r' separately

`is_power_of_two` and `next_power_of_two`

@no_alloc
@no_os

import sysl.math.{is_power_of_two, next_power_of_two}

print(is_power_of_two(8), is_power_of_two(0), is_power_of_two(-8), is_power_of_two(1))
print(is_power_of_two(-128i8), is_power_of_two(128u8))
print(next_power_of_two(17).unwrap_or(-1), next_power_of_two(16).unwrap_or(-1))
print(next_power_of_two(0).unwrap_or(-1), next_power_of_two(-5).unwrap_or(-1))
print(next_power_of_two(200u8).is_some(), next_power_of_two(128u8).unwrap_or(0u8))
print(next_power_of_two(100i8).is_some(), next_power_of_two(60i8).unwrap_or(0i8))

true false false true
false true
32 16
1 1
false 128
false 64

is_power_of_two is one set bit and a comparison against zero, and the second line is why the comparison is there. -128i8 has exactly one bit set — count_ones answers 1 — and it is emphatically not a power of two. A comparison costs nothing and is the whole of the difference.

next_power_of_two answers an Option, and that is what totality costs here. 200u8‘s next power is 256, which no u8 holds. Wrapping to zero would be silently wrong, and a trap would make a library function rule that a caller’s arithmetic is a bug — so the absence goes in the type, where a caller has to look at it. Values at or below one answer 1, negatives included: one is the smallest power of two and every negative is below it.

The last two lines are the same width answering differently, and they are the reason the implementation works at all. 128 fits a u8 and does not fit an i8, because the top bit of a signed byte is the sign — so next_power_of_two(100i8) is none while next_power_of_two(128u8) is 128. The body does not ask which T it has, which is a question a generic body has no way to put: it performs the shift and compares the result against zero, since a signed shift that has reached the sign bit comes back negative and an unsigned one never does.

Next: sysl.time — instants, durations, and the calendar between them.

lisp

2026-08-16T01:26:07.924728867Z

A Lisp small enough to read in one sitting: seven kinds of value, three special forms, nine builtins, and a reader that knows integers, symbols and parentheses. It is not here to be a Lisp. It is here because a Lisp cannot avoid the one thing reference counting cannot do.

The second literate program in the set, after slab: a .lsysl file is Markdown whose four-column-indented part is the program, so the argument for each arm of eval sits beside that arm. As a comment above the function, nobody would read it where it mattered. sysl weave guide/lisp/lisp.lsysl -o lisp.html sets it as a document — its derivations included — and sysl tangle prints just the program. See the CLI.

The axis: the reference cycle. sysl’s headline memory claim is that it counts references rather than checking borrows, and the honest cost of that choice is a cycle — an island of objects that all point at each other, that nothing outside can reach, and whose counts therefore never reach zero. weak T exists in the language for this and no other reason, and until this program nothing in the set showed why anyone would reach for it. json is a tree; scheduler‘s graphs are mutated but acyclic in the direction that matters; and kernel sidesteps the question entirely by giving objects indices instead of references.

A Lisp closes the loop on the first useful thing anyone types:

(define (fact n) (if (= n 0) 1 (* n (fact (- n 1)))))

The closure has to see the environment it was written in, or the recursive call could not find fact. The definition puts that closure into that environment. Env → &Closure → &Env, and neither count will ever be zero again.

The interpreter is built twice

Lambda carries the edge back to its environment in two spellings, and exactly one is ever filled:

struct Lambda
    params: &Buf[string]
    body: &Value
    held: Option[&Env]
    seen: weak Env
end Lambda

An interpreter is made one way or the other. Both run the same source to the same answers — the page below is not about a bug, and there is no wrong output anywhere in it. What differs is only what is left over afterwards.

How it is measured, which is the part worth stealing

sysl has a destructor now, and this program deliberately does not use one — which is worth reading, because the technique below is what a program reaches for when a destructor is the wrong tool. A destructor would perturb what it measures: giving Env one means every environment does work as it dies, on the path being timed. Asking instead costs the objects nothing. A weak reference does not hold its referent alive, so a buffer of one witness per environment ever created is a live-object counter that needs no runtime support and perturbs nothing it counts:

after_run(src: string, owning: bool) -> &Buf[weak Env]
    var ws: &Buf[weak Env] = buf()
    var i: &Interp = interp(owning, ws)

    finish(i, src)

    ws
end after_run

The interpreter is a local, so it and everything it owns are released before the witnesses are returned. That release is the measurement. What still answers afterwards is what the run could not get back. Every number below is a weak reference being asked whether it still resolves.

What it found

What leaks is one environment per environment a definition lands in. That is not the same as one per program and not the same as one per call, and the difference is what decides whether a naive interpreter is usable. Every top-level define binds into the same globals frame, so (fact 10) and a program making five hundred more calls leave the same single environment alive:

program	environments made	alive after the interpreter went
one definition, eleven calls	12	1
two definitions, five hundred more calls	513	1
a definition inside a function, called three times	4	4

The third row is the one that was not guessed. Move the definition inside a function and the identical rule reads the other way: each call makes a frame, each frame gets a closure pointing back at it, and nothing is reclaimed at all. The first two rows were the prediction; the third came from asking. That is the argument for having a count rather than an opinion.

The cure costs more than the disease. Making the back-edge weak means something else has to own every environment, and the only owner available is the interpreter — so nothing is freed until the whole run is over. The naive interpreter holds one environment forever; the careful one holds every environment until it exits, which the same counter reads as 12 alive where the naive one reads 1. ARC offers a choice between two leaks here and there is no third option, because the cycle is the semantics rather than an artefact of how the semantics were encoded. This is the program that says plainly what reference counting does not do.

Breaking a cycle turns a total operation into a partial one. held is an &Env and always answers; seen is a weak Env and answers Option[&Env]. The interpreter unwraps it on a path that cannot fail — the owner table is exactly what makes it so — and the unwrap is written anyway. That is the honest price of weak, and it shows up as code rather than as a caveat.

“Not optimized” was a statement about sysl and not a prediction about the stack. eval and apply are mutually recursive, which is the one kind of tail call sysl does not turn into a jump, so eval carries the loop itself — a tail position reassigns expr and env and goes round again. The claim that made that necessary turned out to need qualifying: built at the default -O1 a mutual recursion ten million deep returns an answer, because LLVM’s sibling-call pass does what sysl declined to, and the identical source built --optimize 0 segfaults. The loop stays either way — what rescued it is a back-end pass rather than a guarantee, and the first argument too large for a register takes it away again. The functions chapter now says so; it did not before this program was written.

Three recursive walks, and one limit closes all of them. The reader, the renderer, and the non-tail arms of eval each recurse on nesting — and nothing but the reader ever makes a nested value, since cons grows a list to the right and every walk over one is a loop. So the depth cap belongs in the reader and nowhere else, and a form the reader accepted is one the other two are already bounded on. That is a property of how the values are represented rather than of the code, and it is why the cap is one constant instead of three.

A hundred thousand cons cells come apart without a stack. Teardown is iterative — a count reaching zero drains a worklist rather than recursing — so dropping a long list is O(1) in stack depth whatever its length. Confirmed here at a scale a recursive release would not have survived.

Everything the interpreter refuses is stated in tests.sysl instead, because a refusal traps and a trap ends the run rather than reporting into it. The split is itself a claim about where a failure comes from: a malformed text arrives from outside, so the reader answers with a Result the run can check; a malformed program is a bug in the thing being run, and the interpreter stops the way sysl stops.

Lexical structure

2026-08-16T01:26:07.924728867Z

sysl is read in two passes that are worth keeping separate in your head. A lexer turns characters into tokens and, because the language is indentation-sensitive, also inserts the tokens that open and close blocks. Only then does a parser see anything. Most of the surprises in a layout-sensitive language happen in the first pass, which is why it gets its own page.

Source text

Source is UTF-8, and the encoding is not configurable. A non-ASCII character is legal in a comment, a string literal, and a character literal; identifiers are ASCII (see below).

Line endings may be LF or CRLF. A file need not end in a newline.

Comments

// A line comment runs to the end of the line.

/* A block comment
   may span lines. */

var x = 1 /* and may sit inside a line */ + 2

print(x)

There is no documentation-comment form with special syntax. Doc text is an ordinary comment above the declaration it describes.

Identifiers

An identifier starts with a letter or _ and continues with letters, digits, or _. Letters are ASCII A–Z and a–z.

Case is significant. Capitalization is not enforced anywhere, but the convention the standard library and this documentation follow is PascalCase for types and traits, snake_case for everything else — and the syntax highlighting treats a capitalized name as a type, so following it makes code read correctly on a page.

Quoted identifiers

A name written between backticks may be anything the rule above refuses — a reserved word, or a name carrying spaces and punctuation:

var `item count` = 3
val `match`: int = 5

struct `Grid Cell`
    `row index`: int
end `Grid Cell`

It is a name and nothing more: `match` is the identifier match. A contextual word written this way is an ordinary name rather than the word — `end` names something, and does not close a block.

Two characters may not appear inside, and a newline ends the search rather than the name, so an unclosed backtick is reported on the line that opened it. A backtick cannot appear at all, since there are no escapes inside. A . cannot either: a qualified name is carried as a dotted string, so a dot inside one part could not be told from the separator between two.

A module path is written with plain names only, for the same reason — module my.mod, never module `my mod` . A module names a directory, and its parts are what the file system holds.

The form does a second job in a match arm, where a backticked name references a variable already declared rather than binding a new one.

Reserved words

Forty words are reserved and may not be used as identifiers:


`alignof`	`as`	`break`	`const`	`continue`
`defer`	`do`	`elif`	`else`	`ensure`
`enum`	`extern`	`false`	`for`	`if`
`impl`	`import`	`in`	`loop`	`match`
`module`	`null`	`offsetof`	`override`	`private`
`ref`	`require`	`return`	`self`	`sizeof`
`static`	`struct`	`then`	`trait`	`true`
`type`	`val`	`var`	`weak`	`while`

alloc, no and requires are not among them, though they read like keywords where they appear. A capability is written as an attribute — @no_alloc, @requires(os) — and an attribute’s words are matched as ordinary identifiers, which is the point of spelling capabilities that way: no word is spent, so an allocator may still call its function alloc.

Type names are deliberately not among them. int, usize, f32, bool, string and the rest are predeclared identifiers that the analyzer resolves, exactly as in Go and Swift. That is what lets the iN / uN / fN families stay open: u12 and i5 are types you may write without the lexer having heard of them, and no list of widths has to be maintained anywhere.

A few words are contextual — special only where the grammar expects one, and ordinary identifiers everywhere else: is, not, invariant, new, within, where, and the c of a c const or c type block. You may name a variable where; you may not name one while.

The last of those is the clearest case for why the language spends so few words. c is the most common one-letter name in code that handles characters, and what keeps it available is the keyword that follows it: nothing else in sysl puts one after a name, so each pair can only be the one thing, and the word costs nobody anything.

Reserved identifiers

An identifier that begins and ends with __, holding only capitals and underscores in between, belongs to the language. Nothing may declare one — not a function, a type, a val, a field, a parameter, a type parameter, or a local.

__FILE__        reserved
__MY_THING__    reserved — and not a built-in, which is a different thing from being available
____            reserved — the middle may be empty
___             not reserved — the markers may not overlap, so four characters is the shortest
__file__        not reserved — the middle is not capitals
__FILE_         not reserved — one underscore short, and so an ordinary name

The shape is reserved rather than the names in it, which is what makes every future addition non-breaking: a release that adds a new built-in cannot collide with a name you already declared, because the shape was never yours to declare. C reserves the same territory and diagnoses nothing in it; here taking it is refused where it is written.

These are predeclared identifiers, like the type names above — not reserved words, and absent from the table.

The restriction is on sysl names only. The string an extern links to is untouched, which matters because a C library’s own symbols live in exactly this space:

private extern "__errno_location" errno_location() -> *i32

The built-ins

identifier	type	value
`__FILE__`	`string`	the file’s name, as a diagnostic prints it
`__LINE__`	integer	1-based line
`__COLUMN__`	integer	1-based column
`__FUNCTION__`	`string`	the enclosing function’s name
`__DATE__`	`string`	build date, `Mmm dd yyyy` (UTC)
`__TIME__`	`string`	build time, `hh:mm:ss` (UTC)

__LINE__ and __COLUMN__ are ordinary integer literals, so each takes the type its context asks for and is range-checked with it.

A built-in written as a default argument reports the caller. A default is evaluated at the call, standing where the argument would have been written, so this needs no special mechanism:

where(line: int = __LINE__) -> int = line

print(where())
print(where())

3
4

That is how the standard library’s assert names the line it failed on, and why its message is optional. Where a default fills another default, the outermost call is the one reported.

__DATE__ and __TIME__ make a build non-reproducible, in the way C’s do. They are worth having for a firmware build stamp and worth not reaching for otherwise.

Literals

Integers

Decimal, hexadecimal (0x), binary (0b), and octal (0o). An underscore may appear between digits and is ignored, so long groupings stay readable. A canonical type name may be written as a suffix; without one the literal takes its type from context.

var dec = 1_000_000
var hex = 0xFF
var bin = 0b1010_1010
var oct = 0o755
var suffixed = 42

print(dec, hex, bin, oct, suffixed)

1000000 255 170 493 42

The scan is greedy and validated afterwards rather than stopping at the first character that does not fit. That is why 42abc is one bad literal and a clear diagnostic, rather than 42 followed by an identifier and a confusing parse error further along.

An unsuffixed literal adopts the type its context expects, provided the value fits — var x: u8 = 42 makes 42 a u8, and var x: u8 = 300 is a compile error. This is not implicit promotion: the literal simply is that type.

Floating point

A literal containing a . with a digit on each side, or an exponent, is floating point. Its default type is real (f64); a suffix selects another width.

var f1 = 3.14
var f2 = 2.5e3
var f3 = 1e-3

print(f1, f2, f3)

3.14 2500 0.001

Note the rendering: a float prints in the shortest form that round-trips, so 2.5e3 shows as 2500 and carries no .0. Hexadecimal, binary and octal have no floating-point form.

Characters

A char literal is one Unicode scalar value in single quotes. Nine escapes are named, and anything else is written with the braced \u{...} form.

escape	meaning
`\n`	line feed, U+000A
`\t`	tab, U+0009
`\r`	carriage return, U+000D
`\b`	backspace, U+0008
`\f`	form feed, U+000C
`\0`	NUL, U+0000
`\\`	backslash
`\'`	single quote
`\"`	double quote
`\u{H…}`	one to six hex digits, any Unicode scalar value

var ch = 'A'
var nl = '\n'
var bs = '\b'
var uni = '\u{1F600}'

print(int(ch), int(nl), int(bs), int(uni))

65 10 8 128512

The named set is C’s, and is deliberately no larger: the escape a programmer reaches for should be the one every language they might arrive from has. The notable absence is \e for the escape character, U+001B, which some shells and Perl accept — it is a GNU extension rather than standard C, and Rust and Go both refuse it. Terminal code writes '\u{1b}' and gives it a name.

var esc = '\e'

print(int(esc))

unknown escape sequence '\e'

\u{...} is braced rather than a fixed four hex digits because a scalar value may need up to six — the fixed-width form is what forces surrogate pairs into source text, and sysl’s char is a scalar value rather than a UTF-16 code unit, so there is nothing to pair.

Strings

A plain string is double-quoted and decodes the same escapes a char does.

There are several other quote forms, each marked by a prefix on the opening quote:

form	what it is
`"…"`	a `string` — validated UTF-8, with escapes decoded
`c"…"`	a C string — the same value with the terminator C expects, read as `*u8`
`s"…"`	interpolated: `${expr}` holes rendered with `str`
`f"…"`	interpolated with a printf specifier allowed after each hole
`raw"…"`	no escape processing — a backslash is a backslash

Any of them may also be written tripled as a text block, which spans lines and strips the common leading indentation so the text lines up with the code around it rather than against the left margin.

The forms are told apart at the token, so nothing downstream has to remember which quote produced a given value.

Loop labels

A label is 'name — an apostrophe and an identifier, the form Rust uses. It is told from a character literal by the absence of a closing quote: 'a' is the character a, and 'a is the label a.

`true`, `false`, `null`

Reserved words rather than library constants. null exists for *T and only for *T.

Operators and delimiters

The operator set is closed — there are no user-defined operator symbols, and no way to add one. Operators are tokenized by longest match, so ..< wins over .., and <<= over <<.

=  +=  -=  *=  /=  %=  &=  |=  ^=  <<=  >>=
||  &&  !
==  !=  <  >  <=  >=
..  ..<  ...
|  ^  &  ~
+  -  *  /  %  <<  >>
++  --
(  )  [  ]  {  }  .  ?
.*
,  ::  :  ->
#  ;

Two of these are worth a note. .* is lexed as one token — the tail of a wildcard import — which is possible because a . is otherwise only ever followed by a name. And ; is only a separator inside a three-clause for header: it is deliberately not a statement terminator, because a line already ends a statement and a token that could also end one would give the language two answers to the same question.

@ opens an annotation and # opens a directive, and between them they are a declaration’s only prefixes that are not words. Nothing in the expression grammar spells either, so neither needs lookahead to recognize. The two are told apart by the sigil and not by the margin, though a directive is taken by a pass that runs before the lexer and reads only column 1 — so an indented # reaches the grammar like any other token, and attributes says what it is told there.

Layout

sysl is indentation-sensitive. Indenting opens a block and dedenting closes it; there are no braces around statement blocks, and a newline ends a statement.

count(n: int) -> int
    var total = 0

    for i in 1..n
        total += i

    total

print(count(4))

Brackets suspend the rule

Inside (, [ or {, layout stops applying until the bracket closes — so an argument list, an array literal, or a parenthesized expression may be broken across lines however you like, and the indentation of the continuation lines means nothing.

An unbracketed line continues after an operator

The rule is the narrowest one that works: an operator that cannot finish an expression continues the line. After +, &&, ==, << or a prefix ! something must follow, so a newline there cannot have been the end of a statement and there is nothing ambiguous to resolve.

var total = 1 +
    2 +
    3

var ok = total > 5 &&
    total < 10

print(total, ok)

6 true

What is excluded follows from the same rule rather than from taste:

= and -> are binary but already open an indented block — a function body, a match arm, a binding’s value — and one token cannot mean both “the block starts here” and “the line goes on”. A value too long for its line therefore goes under the = as a block rather than after it as a continuation.
++, -- and ? are postfix, so a line ending in one is already complete.
.., ..< and ... can be complete too: s[..] is the whole range, and int... is a variadic tail.
. would work, but the continuation style worth having for a call chain puts the dot at the start of the next line, which needs the opposite mechanism.

The one hazard

A continuation line that is dedented has its dedent swallowed along with the newline, so a trailing operator can hold a block open further than it looks. Every language that joins lines has this, including on brackets.

It is documented rather than guarded against, and the reason is worth knowing: guarding would mean the indentation of a continuation line carried meaning, and the entire point of continuing a line is that it does not.

kernel

2026-08-16T01:26:07.924728867Z

A priority scheduler with no heap: the same machine as scheduler, built out of a fixed table and index numbers instead of &T and a run-time allocator.

The axis: a program that allocates nothing. Every task, every lock, every list and the trace of the run live in one struct the checks declare as an ordinary local, so the whole machine is a few tens of kilobytes of storage decided while compiling. Nothing in it makes a &T, a Buf or a string — one function is the exception, and it is the seam where the machine hands its answer to the reporting.

It is written to be compared, not just to work. The shared scenarios produce byte-identical schedules to the scheduler’s, so the two programs check each other and the difference between them is a measurement of what reference counting was buying.

Why it cannot say `no alloc`

It is checked rather than asserted: in the emitted code, no function of the machine calls an allocator. The no alloc clause would say that in the source instead, and this is the program where it does not fit — a capability is a property of the module, both files here are the root module, and the checks build a string on nearly every line. Even the machine’s own file would be refused, because the seam that renders the trace is in it. bytecode carries the clause instead, and the only difference is that its machine already lived in a module of its own. slab sits in exactly the same position.

What the difference turned out to be

An index carries nothing, so the table travels with it. A &Task was a task; a TaskId is a number that means something only beside the table. So every method of the run queue takes the table as a parameter — and not because it wants to look at the tasks, but because the queue’s own links live inside them. A data structure that owns no storage cannot be asked a question on its own.

There was no local name for the task being worked on, and this program is what asked for one. Binding a copy meant every read and every write repeated the path from the table: thirteen occurrences of one subscript in a single function, where the scheduler next door wrote one name. Taking its address would have given the name back as a *Task — the mode this program exists to do without, and one that drops the bounds and within checking that made the indices worth having.

Answered by ref: the eighty-three paths through the two tables became forty-three, the walk is made once, the subscript is bounds-checked at the binding instead of at each use, and the name stays inside every check a written-out path gets — which is the half a pointer could not have. What it costs here is nothing at all, and that is a property of this program rather than of the feature: the rule holding storage still while a ref stands on it asks only about steps that own what they point at, and a fixed table reached through a raw receiver has none.

A subtype bounds the slot but cannot spell “no slot”. TaskId is u8 within 0..<200, so a number that is not a task cannot be made into one and every table index is in range by construction. What it cannot do is carry the sentinel a kernel would have used — 255 is not a TaskId — so an empty link is Option[TaskId], a tag beside the byte. The tag is the honest version and the checking is worth the byte; it is just not the representation the technique is famous for.

Three bounded identities cannot be confused, and that is the payoff. A task number, a lock number and a priority level are three u8s with three ranges, and because within subtypes are new they are three types. Handing a lock number to something expecting a task is the bug a table-driven kernel actually makes, and here it does not compile.

An array bound and a within bound name the same const. The table’s size and the range of what may index it are one fact written once, so the two cannot drift apart. A bound is a constant expression, folded like an array bound and an enum discriminant, so this is as ordinary as the array beside it — and the last magic number is gone.

A method on a table entry copies the entry. A receiver is a value and there is no reference to take, so calling a method on a table slot would copy a task with its whole program in it. The predicates are therefore free functions over the state enum, and every method of the machine takes a raw self including the ones that only read.

Storage that is never allocated is never freed either. The one thing that gives anything back in a program like this is a frame at return, which is why every section of the checks is a function rather than a run of statements.

Source · Next: datetime — a conversion that can succeed twice.

json

2026-08-16T01:26:07.924728867Z

A JSON reader and writer, checked by round-tripping: parse a document, render it, parse the result, and assert the two trees agree.

The axis: recursive ownership. A JSON document is the smallest honest example of a value that contains itself — an array holds values, and a value may be an array — so the type cannot be written at all without an indirection, and every walk over it has to take the reference apart:

enum Json
    Null
    Bool(b: bool)
    Num(n: long)
    Str(s: string)
    Arr(items: &Buf[&Json])
    Obj(fields: &Buf[Field])
end Json

Field is a struct holding a name and a &Json, and the & on that value is the edge that makes the cycle finite.

Numbers are integers, and that is a deliberate narrowing rather than a shortcut. A round trip is the assertion the program is checked by, and a float would make the check about the renderer’s digits instead of about the tree. Floats are another program’s axis.

What it found

A pattern does not reach through a reference. Field selection does — p.x works on a &T — so the asymmetry is a thing to learn rather than to guess. Every walk in the program starts *j match, which is the rule the reference now states outright: selection dereferences one level on its own and match does not, because “am I matching the reference or the thing” should stay a visible question.

There was no way to build a string out of bytes a program computed. This is the big one. The only sources of a string were a literal, a slice of an existing string, concatenation, and str — so unescaping was written as “copy the source between the escapes, and append a literal for each”, and \uXXXX reached text only through str(char(n)), a rendering function standing in for a constructor.

Answered by from_utf8, which validates a []u8 into a string. parse_string now gathers into one sink and converts once at the end, and an escape writes the bytes it encodes rather than being rendered into a string that is immediately concatenated away. The structure that had been forced is now the structure that is wanted — which is the best outcome a finding has.

There were no constants. A value shared by several functions had to be a nullary function. const was added afterwards, for a reason this program did not turn up on its own: a nullary function reads perfectly well in an expression, and what it cannot do is be an array bound.

There was no growable collection. An array and an object were each a linked list built by appending through the tail reference — honest for a tree of references, and not what the data is. Answered by Buf[T] reaching the standard library — sysl.buf, which a program asks for by name rather than getting for nothing: an array became a &Buf[&Json] and an object a &Buf[Field]. That deleted two list-cell structs, both tail-threading loops, and the two recursive renderers.

Worth noticing

The depth limit is private const max_depth: int = 64, and the finding above is why it can be. What a nullary function could never be is an array bound, which is the case that motivated the form: as declarations puts it, a const is folded into every use and has no address, and being usable where a constant is demanded is exactly what that buys.

Source · Next: hashmap — the trait system under load.

The io module

2026-08-16T01:26:07.924728867Z

sysl.io is the input half of the byte surface. It is a module rather than part of the core for a reason that reads as an asymmetry and is not: print is a keyword, so what it desugars onto cannot be behind an import a program has not written — while nothing in the language desugars onto reading. A program that never takes input never has these names, and one that does said so.

trait Reader: Fallible
    read(*self, into: []u8) -> []const u8

struct FdReader
    fd: int
    bad: bool

fd_reader(fd: int) -> FdReader
stdin() -> FdReader

find_byte(b: []const u8, c: u8) -> Option[usize]
line_text(b: []const u8) -> string
try_line_text(b: []const u8) -> Result[string, Utf8Error]

enum LineEnding
    Lf
    CrOrLf

struct Lines
    getline(*self) -> Option[string]
    try_getline(*self) -> Option[Result[string, Utf8Error]]

lines(r: *Reader) -> Lines
console_lines(r: *Reader) -> Lines
lines_ending(r: *Reader, ending: LineEnding) -> Lines

That is the whole module. Its shape is Writer turned around, deliberately: one method on bytes, a latch rather than a Result, and *self on both so a source can be stateful and still object-safe for a raw trait object — which is what lets a reader need no allocator.

The latch is required, not declared

Reader requires Fallible rather than declaring a failed of its own, and so does Writer. That is what lets one type be a reader and a writer at once: a trait’s members become the implementing type’s, so two traits each declaring their own failed could not both be implemented for one file. An open file is both, which is why sysl.fs works at all.

Leaving it out is caught at the impl, with the line to write:

import sysl.io.Reader

struct Memory
    src: []const u8
    at: usize
end Memory

impl Reader for Memory
    read(*self, into: []u8) -> []const u8 = into[0..<0]
end Memory

'sysl.io.Reader' requires 'sysl.Fallible', so 'Memory' has to implement that too — write 'impl sysl.Fallible for Memory'

failed defaults to false, so a source that cannot fail — an in-memory buffer, a fixed device — writes impl Fallible for X with no block at all and says nothing about failure.

`read` answers with the prefix it filled

import sysl.io.Reader

struct Memory
    src: []const u8
    at: usize
end Memory

impl Fallible for Memory

impl Reader for Memory
    read(*self, into: []u8) -> []const u8
        var n = self.src.len - self.at

        if n > into.len then n = into.len

        for i in 0..<n do into[i] = self.src[self.at + i]

        self.at += n
        into[0..<n]
    end read
end Memory

var m = Memory("alpha\nbeta".bytes, 0)
var r: *Reader = &m
var window: [4]u8

var got = r.read(window)

print(got.len, got[0], got[3])

var more = r.read(window)

print(more.len, more[0])
print(m.failed())

4 97 104
4 97
false

It hands back a slice rather than a count, and that is the one place this surface improves on read(2). A slice already is a length and a pointer: got.len is the count and got is what to look at, so there is no way to be handed the one and forget to apply it to the other — which is the mistake read(2)‘s signature invites every time it is called. It costs nothing, since a view is three words either way.

The caller supplies the storage, and it has to be writable:

import sysl.io.{Reader, stdin}

var r = stdin()
var frozen: []const u8 = "hi".bytes

var bad = r.read(frozen)

a '[]const byte' views elements it may not write, and a '[]byte' is a licence to write them — so the one does not become the other

That is the read-only view rule in the direction it does not travel. A []T goes where a []const T is wanted; the reverse would be a licence nobody granted.

Empty means the end; `failed` means it ended badly

Reading empty says end of input and says only that. Whether input ended badly is a separate question, and the two are separate because a caller who does not care should not have to ask, and a caller who does should not have to unwrap a Result at every read to find out.

That mapping is read(2)‘s own — zero for the end, -1 for a failure — so nothing is being conflated to make the surface tidy.

import sysl.io.{Reader, lines}

struct Flaky
    left: int
    bad: bool
end Flaky

impl Fallible for Flaky
    override failed(*self) -> bool = self.bad

impl Reader for Flaky
    read(*self, into: []u8) -> []const u8
        if self.left <= 0
            self.bad = true
            return into[0..<0]

        self.left -= 1
        into[0] = u8('x')
        into[1] = 10
        into[0..<2]
    end read
end Flaky

var f = Flaky(2, false)
var n = 0

for line in lines(&f)
    n += 1

print(n, f.failed())

2 true

The loop ended and the question is still answerable. That is the whole reason the next section’s cursor is shaped the way it is.

`lines` borrows its reader

import sysl.io.{Reader, lines}

struct Memory
    src: []const u8
    at: usize
end Memory

impl Fallible for Memory

impl Reader for Memory
    read(*self, into: []u8) -> []const u8
        var n = self.src.len - self.at

        if n > into.len then n = into.len
        if n > 6 then n = 6

        for i in 0..<n do into[i] = self.src[self.at + i]

        self.at += n
        into[0..<n]
    end read
end Memory

var text = "alpha\nbeta\r\ngamma"
var m = Memory(text.bytes, 0)

for line in lines(&m)
    prints("[")
    prints(line)
    prints("]")

prints("\n")
print(m.failed(), m.at)

[alpha][beta][gamma]
false 17

This reader hands back at most six bytes at a time, so "beta\r\n" spans two reads and "gamma" arrives with no newline after it at all. Both come out whole, and the \r is gone.

A trailing \r leaves with the \n, so text written on either system reads the same. That is bufio.Scanner‘s choice rather than C getline‘s, and it is the right one for a language whose string is bytes: a program that did not strip it would find line == "beta" false on half the world’s files.

lines takes a *Reader, and the & is not decoration:

import sysl.io.{lines, stdin}

var r = stdin()

for line in lines(r)
    print(line)

a *sysl.io.Reader points at a value, so it needs an address — write '&' in front of the sysl.io.FdReader to take one

A for iterates a copy of its iterator. A Lines that owned its reader would latch a failure onto a copy the caller cannot reach, and failed would be decorative — you could ask it, and the answer would be about a cursor that no longer exists. Borrowing leaves the reader named in the caller’s scope, which is what makes r.failed() answerable after the loop, the only moment the question matters. The price is one line at the call site.

Three more decisions inside the cursor

It scans the slice read returned, not the one it offered. Those are the same memory for a reader that fills what it was given, so the distinction is free — and it is what lets a reader hand back a view of a buffer of its own, never touching the offered one, and still be read correctly. Taking the length from the answer and the bytes from the offer is how the two could have disagreed, and there is nowhere for them to.

A line that fits in one read is never copied. The cursor scans its buffer in place; only a line spanning two reads is gathered, into a Buf[u8] that is then reused. So the cost is proportional to the input rather than to the input times the number of refills.

A line is found with memchr, through find_byte — libc’s scans a word at a time where a sysl loop could not:

import sysl.io.find_byte

print(find_byte("a,b".bytes, u8(',')).unwrap(), find_byte("abc".bytes, u8('z')).is_none())

1 true

That function is what pointer difference is for: memchr answers where with an address, and an index is that address minus the first. It is public because a program scanning for a delimiter of its own wants exactly it.

An empty read ends the cursor for good. A caller reading again past the end gets None every time rather than a second chance, which is right for the sources read(2) serves.

Validation happens where the bytes arrive

getline yields a string, not bytes — so input is checked for well-formed UTF-8 at the boundary it came in at, which is where the language puts that check. Ill-formed input stops the program, naming the byte offset within the line.

That severity is affordable because the layer underneath is public. A caller who would rather inspect than trap reads bytes through Reader and validates them itself with from_utf8, which is what having two layers is for. line_text is exported for the same reason: a program doing its own framing can still get the \r handling and the validation without reimplementing either.

When stopping is the wrong severity

Reading a file you expect to be text, stopping is right — there is nothing sensible to do with the rest, and carrying on puts the mistake a long way from its cause. Reading a serial port it is not, and on a freestanding target it is worse than not: exit there is a halt with no supervisor to notice it, so one mistyped byte hangs the board.

try_getline is the same walk reporting instead, and try_line_text the same conversion. Two answers nest — the Option says whether there was a line at all, the Result says whether it was text:

import sysl.io.{lines, stdin}

var r = stdin()
var c = lines(&r)

loop
    c.try_getline() match
        None -> break
        Some(line) ->
            line match
                Ok(s) -> print("[", s, "]")
                Err(e) -> print("not text, at byte", e.offset)

getline is written in terms of it, so there is one place that decides where a line ends and one that decides what to do about bytes that are not text.

A terminal does not end a line the way a file does

lines() splits on \n, which is right for a file and for a pipe. A terminal sends a bare \r when Enter is pressed, so a cursor splitting on LF never sees a line at all: it waits forever, prints nothing, and looks hung, with nothing to grep for, because nothing has gone wrong — the line has not ended.

console_lines is the same cursor taking CR, LF and CRLF alike. Which is right is a property of where the bytes came from, which the library cannot know: a \r in the middle of a pipe’s line is a \r, and a \r from a console is a line. So the caller says, and lines() is unchanged.

import sysl.io.*

struct Typed
    src: []const u8
    at: usize
end Typed

impl Fallible for Typed

impl Reader for Typed
    read(*self, into: []u8) -> []const u8
        var n: usize = 0

        while n < into.len && self.at < self.src.len
            into[n] = self.src[self.at]
            self.at += 1
            n += 1

        into[0..<n]

var keys = Typed("one\rtwo\r\nthree\n".bytes, 0)

for line in console_lines(&keys)
    print("[", line, "]")

[ one ]
[ two ]
[ three ]

A bare \r ends the line immediately rather than waiting to see whether an \n follows, because on a bare-CR terminal it never does and waiting inside the read would hang until the next keystroke. What that costs is that the \n of a \r\n may arrive in a later read than its \r, so the cursor remembers it is owed one across the refill — which is the case a hand-rolled console reader gets wrong, producing a spurious empty line between every pair.

lines_ending(r, e) is the two written out, for a caller holding the policy as a value.

Echo and editing are not a line cursor’s business — one is about the terminal and the other about the line — and they have to come from somewhere, because a terminal in raw mode shows nothing as it is typed and a mistake cannot be corrected without them.

They come from sysl.term.edit, which is this trait’s other consumer: it edits where nothing else will, and hands back whole lines through the same Iterate[string] a Lines does. So the two are interchangeable at a call site, and which one a program wants is decided by whether anything else is already doing the editing — the kernel, on a cooked terminal, and nothing at all over a serial cable.

Reading from memory, and writing to it — `bytes_reader` and `bytes_writer`

Every Reader and every Writer above is a file descriptor, and for a long time that was all there was — which made a whole class of code awkward to reach: anything taking a *Reader could only be exercised by arranging for real input to arrive on a real descriptor.

import sysl.io.{bytes_reader, bytes_writer, lines}
import sysl.text.from_utf8

main()
    var src = bytes_reader("one\ntwo\n".bytes)
    var out = bytes_writer()

    for line in lines(&src)
        out.write(line.bytes)
        out.write("|".bytes)

    print(from_utf8(out.view()).unwrap_or("?"))

one|two|

A bytes_reader borrows what it reads rather than copying it, so one over a large buffer costs three words; what that asks is that the bytes outlive the reader, which is the ordinary rule for a slice. A bytes_writer grows to fit, and view() hands back everything written so far — a caller wanting text calls from_utf8 on that view and gets to decide what an ill-formed sequence means, which is right here, because whatever wrote those bytes is the thing under suspicion.

bytes_reader_at_most(b, n) hands back at most n bytes per read, however much room it was offered, and it earns its place: anything reading a stream has cases that arise only when a unit of input straddles two reads — the two bytes of a \r\n, an escape sequence, the continuation bytes of one character. Those are exactly the cases a hand-rolled reader gets wrong, and a reader that always empties itself in one go can never produce them. It is also what a slow source honestly looks like: a serial port hands over what has arrived, not what was asked for.

`FdReader` and `stdin`

import sysl.io.{lines, stdin}

var r = stdin()

for line in lines(&r)
    print(line)

if r.failed() then print("input ended badly")

stdin() names the descriptor a program is started with, so a caller does not have to know it is zero, and fd_reader(fd) takes any other. FdReader is the only reader the library supplies — the mirror of ByteSink being the only writer.

That symmetry is what makes the freestanding story two functions long. The seams a target with no C library replaces are exactly putbytes‘ body and FdReader.read‘s. Swap those two for a write and a read syscall and everything above them is unchanged: every renderer, every Display, the whole of lines, and every impl Reader a program wrote for itself.

Next: sysl.fs — files and paths, and the capability that gates them.

Installation

2026-08-16T01:26:07.924728867Z

Install

brew install sysl-lang/tap/sysl

That is a native binary — there is no JVM under it and nothing to start up. It brings LLVM with it, which sysl needs at runtime: the compiler emits textual LLVM IR and hands it to clang to assemble and link, and llvm-ar is what builds a library into a .syslib.

It also brings pkgconf. A package that binds an installed C library can name it — requires { pkg_config { sdl3 = "…" } } — and sysl asks pkg-config where that library’s headers and link line are, so building against SDL3 or cairo needs no flags. macOS ships no pkg-config and the libraries do not bring one, so the formula does.

Check it, and see what it offers:

sysl --version
sysl --help

macOS on Apple silicon, and Linux on x86_64 and arm64. The tap picks the right one for the machine it is run on. Anything else builds from source, below.

The Linux binaries need glibc 2.34 or newer — Ubuntu 22.04, Debian 12, RHEL 9, and anything later. That is a property of the machine they were built on rather than of sysl, and it is the one way an install can fail that the formula cannot check for you: version GLIBC_2.34 not found from the dynamic loader is this, and not a corrupted download. On an older distribution, build from source.

Your first compile

echo 'main()
    print("Hello, sysl!")' > hello.sysl
sysl run hello.sysl

The first run prints a line on stderr about building the standard module. That is expected and it happens once — see below.

sysl build compiles without running, leaving an executable you can ship:

sysl build hello.sysl -o hello
./hello

Build from source

The compiler is a Scala 3 cross-project, so the path in is a clone and an sbt build. You want this if you are working on sysl, or if you are on a platform the tap has no binary for.

	why
JDK 17+	the compiler is written in Scala and runs on the JVM
sbt 1.12+	builds it
clang	sysl emits textual LLVM IR; clang assembles and links it
llvm-ar	only for building a library — a `.syslib` is an `ar` archive of objects
pkg-config	only for a package that names an installed C library; without it, say where the library is with `--include-path` and `--link-path`

clang is the only one most systems already have — pkg-config is common on Linux and absent from a stock macOS. On macOS the Xcode command-line tools supply one; on Debian and Ubuntu it is the clang package.

llvm-ar matters only when you build a library of your own, and it has to be the LLVM one: a .syslib holds objects for the machine it was built for, and a platform archiver indexes only its own format and silently drops the rest. On a Mac, Homebrew keeps its LLVM deliberately off the PATH, so sysl looks in /opt/homebrew/opt/llvm/bin as well. --ar names one anywhere else.

git clone https://github.com/sysl-lang/sysl.git
cd sysl
sbt syslJVM/compile

The JVM target is the one to develop against. JS and Native cross-targets exist in the build, and the Native one is what the released binary is built from:

SYSL_RELEASE=1 sbt syslNative/nativeLink

Without SYSL_RELEASE that links in debug mode, which is much faster and is what you want while working on the compiler.

Check it

./run-example.sh

That compiles examples/hello.sysl all the way to a native binary and runs it. If you see Hello, sysl! followed by a page of output, everything is in place.

To run a different file, name it — and anything after a -- goes to the program rather than to sysl:

./run-example.sh examples/args.sysl -- -n one two

Under the script is the CLI, which you can call directly:

sbt "syslJVM/run run examples/hello.sysl"

The standard library

Every program is compiled against the standard module, and its source ships with the compiler. An install puts it at share/sysl/library under the install prefix — on a Homebrew Mac that is $(brew --prefix)/share/sysl/library — and the compiler finds it from its own location, the way rustc finds its sysroot. Running out of a checkout, it is the library/ directory in the tree. Nothing has to be configured, and there is no variable to set.

The directory was called lib/ until it was renamed, and both spellings are still looked for with the new one first — so a compiler installed before the change, and a checkout that has not been updated, both go on working.

It is meant to be read. The library is ordinary sysl, laid out as an ordinary sysl library, and every function in it is one a program could have written; sysl build-lib <root> --std is the same command that builds anybody else’s.

You do not have to build the artifact, either: when nothing usable is at the default path, the compiler builds it out of that source, says so on stderr, and gets on with the compilation. A fresh install just works.

It goes in your cache directory — ~/Library/Caches/sysl/ on macOS, ~/.cache/sysl/ on Linux, or wherever XDG_CACHE_HOME points — under a fingerprint of the library it was built from. So it is built once per machine rather than once per project, nothing is written into your source tree, and installing a compiler with a different library gets its own entry instead of a stale hit. Nothing there is ever evicted, and everything in it is derived: deleting the directory costs one rebuild.

Two flags matter when you want something other than that. --std-lib <path> names an artifact explicitly, and an artifact you named is never rebuilt behind your back — if it will not read, the compilation stops and says so. --no-std-lib compiles the standard module from its source instead of linking a prebuilt one, with no toolchain involved at all, which is the path the compiler’s own test suite takes.

Optimization

-O names the level handed to clang, spelled the way clang spells one — -O2, -Os, -O0 — and it reaches every object a build produces rather than only the final link. It can also be written --optimize 2.

The default is -O1, not off. That is worth knowing because it is unusual: -O0 is a different instruction selector rather than merely a slower one, it is the mode a back end’s own test suite covers least, and a real miscompile was found living there. If you drop to -O0 to make something easier to debug and the behaviour changes, suspect that before your program.

If something goes wrong

clang: command not found — sysl got as far as emitting IR and had nothing to hand it to. Install clang and try again. Installing from the tap brings LLVM with it, so this is a built-from-source problem.

llvm-ar complaints when building a library — you have the platform archiver, not LLVM’s. Point at LLVM’s with --ar /path/to/llvm-ar.

cannot find the standard module's source — the compiler could not find the library it ships with, and the message lists every path it tried. From a package install that means the install is incomplete: reinstall it. From a checkout it usually means the working directory is not in the tree. Either way SYSL_LIB=/path/to/library names the library root outright, where the root is the directory holding sysl — that is, the library above library/sysl, not library/sysl itself.

sbt is slow on the first run — it is downloading Scala and the dependency tree. This happens once.

Inline assembly

2026-08-16T01:26:07.924728867Z

asm reaches the instructions no library can wrap: the privileged ones, the ones that talk to a bus rather than to memory, and the handful that change the machine the library is running on. It is the one construct that steps outside the language, and it is shaped so that stepping outside costs as little as possible — you supply instructions, and nothing else.

What you do not supply is the interesting part. Which register an operand lands in, how the value gets there, what the block destroys, how a label avoids colliding with its own second expansion, how an operand is spelled in the emitted template: each is something the compiler knows, and each is something that, written by hand, is a comment nothing checks.

sysl does not ship named functions for “disable interrupts” or “flush the TLB” that expand to each machine’s instruction. Assembly is the primitive; the architecture layer above it is ordinary sysl that you write. What the language contributes is that the layer can be checked.

One arm per architecture

An asm statement is a head with architecture arms indented under it. Exactly one is selected — the one naming the processor being compiled for — and the others contribute nothing:

arch_cli()
    asm
        [x86_64]           "cli"
        [aarch64]          "msr daifset, #2"
        [riscv64, riscv32] "csrci mstatus, 8"
        [thumb]            "cpsid i"
        [craft]
            "csrr t0, status"
            "li t1, -3"
            "and t0, t0, t1"
            "csrw status, t0"
            clobbers "t0", "t1"
        [wasm32]           unavailable "a wasm module has no interrupts to disable"

An arm names one processor or several, spelled as #if spells them: aarch64, x86_64, riscv64, riscv32, thumb, x86, wasm32, craft. A name outside that set is an error rather than a machine nobody has heard of.

wasm32 is the one that is not a processor, and it will not carry instructions at all: a wasm module has no registers to name and no assembler behind it. Its arm is therefore always empty or unavailable — both forms are below — which makes it the standing reminder that these arms are about targets rather than about chips.

craft is 16-bit, and its arms are the ones worth reading twice. It has three-operand arithmetic and eight registers, so mv and add are spelled as RISC-V spells them — but it has no logical immediate and no bit-clear on a control register, so clearing one bit of status is a read-modify-write through two scratch registers rather than the one instruction every other machine here writes. That is what a deliberately small instruction set costs, stated where somebody can see it.

riscv32 and thumb are one board’s two halves, which is why they are usually written together in what follows. The RP2350 boots either a pair of Cortex-M33s or a pair of RV32IMAC cores, and a microcontroller is what inline assembly is mostly for. thumb rather than arm names the Arm one because a Cortex-M executes Thumb only — an arm written for A32 would assemble for a machine that cannot run it, and the name is what says so.

Here is a whole program. yield, pause and nop are each their machine’s hint that a spin loop is spinning, which is about as small as a real use of this construct gets:

spin_hint()
    asm
        [x86_64]           "pause"
        [aarch64, thumb]   "yield"
        [riscv64, riscv32] "nop"
        [craft]            "nop"
        [wasm32]

spin_hint()
print("hinted")

hinted

Square brackets rather than a match arm’s ->. Brackets are already what sysl writes around things resolved at compile time — a type parameter list, Option[T] — and the arrow is what it writes between a runtime pattern and its body. An architecture is not a value being tested: the arms not chosen do not exist in the output at all.

Every architecture needs an answer

The arms must cover every processor a target can be built for, not merely the one you are building for now. A missing arm is an error on every build:

halt()
    asm
        [x86_64] "hlt"

halt()

this assembly has no arm for 'aarch64', 'riscv64', 'riscv32', 'thumb', 'wasm32' or 'craft'

This is the rule #if follows one level up, where every condition is checked in the branches being skipped as well as the one being taken. Here it reaches past whether a branch parses to whether one exists — so a forgotten processor is found by whoever forgot it, rather than by whoever first builds for the machine that was left out.

When there is genuinely no answer

Some assembly is unportable in principle rather than by omission. outb and inb are x86’s; every other processor here reaches devices through memory and has no equivalent at all. Such an architecture says so, and says why:

port_out(port: u16, value: u8)
    asm
        [x86_64]
            "outb {value}, {port}"
            in port : "dx"
            in value : "al"
        [aarch64, riscv64, riscv32, thumb, craft, wasm32] unavailable "port I/O is x86-only; devices are reached through memory"

The x86-64 build compiles that. A build for a processor the arm covers is refused, and the reason travels into the diagnostic — which is the whole of what this form buys over leaving the arm out, since leaving it out fails every build instead:

port_out()
    asm
        [x86_64] "outb %al, %dx"
        [aarch64, riscv64, riscv32, thumb, craft, wasm32] unavailable "port I/O is x86-only; devices are reached through memory"

port_out()

port I/O is x86-only; devices are reached through memory

When the answer is no instruction

An arm written with nothing under it is an answer too: this processor needs no instruction. A memory barrier is free on a machine that never reordered the accesses in question, and unavailable would be false there — the operation is available, it simply costs nothing.

barrier()
    asm
        [x86_64]
        [aarch64]          "dmb ish"
        [thumb]            "dmb sy"
        [riscv64, riscv32] "fence rw, rw"
        [craft]
        [wasm32]

An empty arm cannot be confused with a forgotten one, because a forgotten arm is not empty — it is absent, and absent is the error above.

Operands are values, not registers

An operand names a variable already in scope, gives its direction, and gives the register class or the machine register it must occupy. The template refers to it by that same name in braces:

copy(n: int) -> int
    var v: int = 0
    asm
        [x86_64]
            "movl {n}, {v}"
            in n : reg
            out v : reg
        [aarch64, thumb]
            "mov {v}, {n}"
            in n : reg
            out v : reg
        [riscv64, riscv32, craft]
            "mv {v}, {n}"
            in n : reg
            out v : reg
        [wasm32] unavailable "there are no registers for an operand to land in"
    v

print(copy(7))

reg means any general-purpose register the allocator likes, and it is the only class there is. Where an instruction demands a particular register, name it — quoted, because it is the assembler’s name and not sysl’s:

out_byte(port: u16, value: u8)
    asm
        [x86_64]
            "outb {value}, {port}"
            in port : "dx"
            in value : "al"
        [aarch64, riscv64, riscv32, thumb, craft, wasm32] unavailable "port I/O is x86-only"

A bare word is sysl’s and a quoted word is the assembler’s. That rule decides every case in the construct: reg is a class this language names, "dx" is a register only the assembler knows, and instruction text is quoted because sysl does not read it.

The class slot is required even though reg is currently the only class. Writing it keeps every operand line one shape, so a second class arrives as a peer rather than as the exception to an invisible default.

The : here is not a type annotation. An operand names a variable that already has a type, so there is nothing left to declare — the slot holds a class or a register.

What an operand may be

An operand must be a plain variable, and its type must fit a general-purpose register: the integers, the pointers, bool. A float needs a floating class, which does not exist yet.

Reading and writing the same variable is refused, because it is two operands and so possibly two registers — the instructions would read one and write another:

f()
    var n: int = 1
    asm
        [x86_64]
            "addl {n}, {n}"
            in n : reg
            out n : reg
        [aarch64, thumb, riscv64, riscv32, craft]
            "add {n}, {n}, {n}"
            in n : reg
            out n : reg
        [wasm32] unavailable "there are no registers for an operand to land in"

f()

both read and written here

Only the selected arm’s operands are checked, since the others describe machines this build is not for. So a mistake in an arm is reported by a build for that arm’s processor — which is the same bargain exhaustiveness makes, one level down.

What the block destroys

An arm may name registers it destroys beyond its operands:

f()
    asm
        [x86_64]
            "nop"
            clobbers "rax", "rdx"
        [aarch64, riscv64, riscv32, thumb, craft, wasm32] unavailable "x86 only here"

Memory and the condition flags are assumed clobbered, always, and cannot currently be given back. That is the conservative direction on purpose: assuming them costs optimization quality across a handful of instructions, and not assuming them costs a value kept in a register the block overwrote — a wrong answer with nothing to point at.

Registers cannot be treated the same way. “Everything is clobbered” is a legal assumption and a useless one, so the registers an arm destroys are the one part of its effect you have to state.

What the compiler owns

Operand substitution and its escaping. $ is LLVM’s own operand marker, so a $ you write — an x86 immediate, movq $1, %rsi — is doubled by the compiler rather than by you. A doubled brace is a literal one, which is not a nicety: ARM writes register lists as {r0-r3}, so push {{lr}} is how you spell push {lr}.

Label uniqueness. A label in an arm is local to that arm’s expansion, and a block emitted twice gets two distinct labels. A label in inline assembly is otherwise a global symbol, and the second definition is a duplicate the assembler rejects for reasons you cannot do anything about from where you are standing.

Line joining. Instructions are separate strings on separate lines, each able to carry a comment. This is the difference between an assembly routine that can be read and a six-instruction spinlock written on one line with \n between the instructions.

The constraint string, which you never write, because a constraint that disagrees with the instruction text is not detectable by reading either one.

The words this construct spends

None of them is reserved. asm, unavailable, out, reg and clobbers are contextual: each is recognized in exactly one position and is an ordinary identifier everywhere else — including inside an assembly block, in any other position.

f() -> int
    var out = 1
    var reg = 2
    var clobbers = 3
    var asm = 4
    out + reg + clobbers + asm

print(f())

in is a reserved word already, for for x in xs, and is reused here rather than added to.

Where assembly may not go

Not in a require or ensure condition — and there is no check that says so, because there is no way to write it: a contract’s condition is an expression and assembly is a statement. A contract is a claim the compiler reasons about and an assembly block is precisely what it cannot reason about, so the two never meeting is a property to rely on.

Nothing about a block’s contents is understood, including whether control comes back. The compiler does not read the instructions, so it cannot know that a jump to a reset vector never returns — and it does not try. A function declared -> never with an assembly body is taken at its word, exactly as anything else declared not to return is:

arch_reset() -> never
    asm
        [x86_64]
            "cli"
            "1: hlt"
            "jmp 1b"
        [aarch64]
            "msr daifset, #2"
            "1: wfi"
            "b 1b"
        [thumb]
            "cpsid i"
            "1: wfi"
            "b 1b"
        [riscv64, riscv32]
            "csrci mstatus, 8"
            "1: wfi"
            "j 1b"
        [craft]
            "csrr t0, status"
            "li t1, -3"
            "and t0, t0, t1"
            "csrw status, t0"
            "wfi"
            clobbers "t0", "t1"
        [wasm32] unavailable "a wasm module cannot halt its host"

The promise is yours to keep here, which is true of the instructions themselves anyway.

What is not here yet

inout — a read-modify-write operand. The instructions wanting one are the exchange and compare-exchange family, which sysl.sync already covers.
Giving memory and the flags back, which is an optimization over an answer that is currently always correct.
A floating register class. It cannot be a single one: bare-metal RISC-V has no floating registers to name.

hashmap

2026-08-16T01:26:07.924728867Z

A hash map, generic in its key and its value. Chained: a bucket is a list of entries, an entry is a &Entry so the list can hold itself, and the bucket array grows by doubling with everything rehashed.

The axis: the trait system under load. A container is where bounds, the behaviour they promise, and ownership all have to agree at the same time — the map hashes and compares a key it knows nothing else about, it holds keys and values it did not make, and it hands entries back out while still owning them. Nothing else in the set asks for all three at once.

What it found

There was no Hash in the core catalogue. There were Eq and Ord — enough to sort with, not enough to key on — so the map declared its own, with an impl for every key type it wanted to support. That was never a style problem. Coherence lets an impl live only with its trait or with its type, so two libraries that each declare a Hash can never share a key type’s implementation, and a program using both writes the same hash twice.

Hash is now a core trait, which deleted a trait, two impls and an avalanche function from the program. The built-in mixing is the same splitmix64 finalizer the map used to carry, in the one place every container can reach it.

An enum has no zero value, so an array of them could not be declared. var cells: [16]Option[&Entry[K, V]] is refused. Answered by the repeat form [None; n], which fills storage from a value instead of from a zero — before that, it was sixteen Nones written out.

Generically it was worse, and the reason has since narrowed. A repeat needs a value in its value position and a bound could promise none, so a generic container could not make its own storage unless it already held something to fill it with. A trait member may now have no receiver, so a bound can promise a value and [K.blank(); n] is ordinary code.

What is left is worth being exact about, because it is a real remaining limit rather than a fixed one: no trait sysl ships declares such a member, so a container over every K still cannot make a [16]K. A container over the types a program names can, by declaring the trait itself. The map’s table stays Option[…] — and now because None needs nothing of K and V, rather than because nothing else was available.

Storage could not be asked for at a size worked out while running. The table was a fixed directory of fixed blocks with its capacity in its own type: it doubled up to max_blocks and then stopped, staying correct with lengthening chains. Answered by an array form written where a []T is expected making storage of its own that the view owns — so the table became one flat run of buckets that doubles for as long as there are keys. That deleted a directory, a block, two constructors, two constants, and the ceiling.

A bucket is named rather than re-indexed. ref bucket = self.cell[self.index(k)] names the slot, so put and remove each hash once and walk the table once instead of writing the path out at every read and write. That is ref doing the job it exists for, in the first program that wanted it.

Source · Next: bytecode — the module system, end to end.

The harness module

2026-08-16T01:26:07.924728867Z

sysl.harness is how a program checks itself on the machine it was built for. It is the same shape as C’s Unity, and it exists for the same reason: the host’s test runner cannot follow the code onto a board.

sysl test is the host’s answer and cannot be this one. It starts a process per test, selects one by argv, and reads the verdict out of an exit status. A microcontroller has no processes, no argv and nobody to read an exit status. So the checking has to be written in the language and linked into the image, and what comes out is a report on a wire.

The two are not rivals. Use sysl test for everything that can run on the machine you are typing on — it is faster, it isolates each test in its own process, and it needs no arrangements. Reach for this when the thing you want to check only exists on the target: a driver against real registers, a timing loop, arithmetic at a width the host does not have.

Nothing here allocates, opens anything, or asks the system for a service. Its state is a fixed number of bytes laid into the image, and every value it prints renders itself into a sink rather than into a fresh string.

A suite

import sysl.harness.*

adds()
    check_eq(2 + 2, 4)

holds()
    check(1 < 2, "one is less than two")

run("adds", &adds)
run("holds", &holds)
finish()

<page>:9:adds:PASS
<page>:10:holds:PASS
2 tests, 0 failed

The file is <page> because this example is a block on a web page; where you run it, it is your file’s name.

A test is an ordinary function of no arguments, and run names it and calls it. The name is written twice on purpose — once as the function and once as the string — because the string is what the report says, and a report that said adds when the interesting thing was addition after the clock was reconfigured would be worse for having been derived automatically.

&adds is a pointer to a function, not a closure. run takes *extern() -> unit, which is one word and one copy of run for the whole suite; a bare arrow would be a bound over Fn, monomorphized per test — thirty tests, thirty copies of the runner — and flash is what a target has least of. The cost is the &, and the restriction that a test body captures nothing, which is what a test body is anyway.

A failure says where, and what the values were

import sysl.harness.*

adds()
    check_eq(2 + 2, 5)

run("adds", &adds)
finish()

<page>:4:adds:FAIL: got 4, want 5
1 tests, 1 failed

A passing test reports the line of the run that named it and a failing one the line of the check that failed — 6 and 4 here. Both fall out of the same rule and neither is a special case: run, skip and every check take file and line as defaulted parameters, and a default is evaluated at the call, so __FILE__ and __LINE__ written once in each declaration hold whatever line the reader wrote. You never pass either.

The line is file:line:test:verdict, which is Unity’s order, so the editors and CI filters that already read that format read this one.

That is the whole difference between this and a program printing characters as it goes. A board that says abcdyx4 has told you something went wrong and nothing about which check, on which line, with which values.

got then want, which is the order assert_eq takes next door and the order a failure is read in.

A failing check does not stop the test. Unity aborts with longjmp; sysl has none, and an unwind that skipped a scope would skip the releases that scope owes. So a failure is recorded and the test runs on — and only the first failure in each test is reported, because the ones after it are usually the same failure seen again through worse state.

The checks


`check(cond, msg = "")`	a condition that has to hold
`check_eq[T: Eq + Display](got, want)`	two values that have to be equal, both rendered when they are not
`check_slice_eq[T: Eq + Display](got, want)`	the same for a `[]const T`, naming the index that differs

One generic member stands in for Unity’s several hundred assertion macros and does more than they can: TEST_ASSERT_EQUAL_* covers a fixed list of C’s own types and falls back to a hex dump of the bytes for anything a program defined, while a bound reaches any type at all that can say whether two of it are equal and write itself down.

check_slice_eq says where, because a report that two slices differ sends its reader to find out — and finding out is a loop nobody wants to write at each call, least of all on a board where the way to look is a debugger and a stopped core:

import sysl.harness.*

bytes()
    check_slice_eq([u8(1), u8(2), u8(3)], [u8(1), u8(9), u8(3)])

run("bytes", &bytes)
finish()

<page>:4:bytes:FAIL: got 2, want 9 at index 1
1 tests, 1 failed

Length first, since a length mismatch explains every index after the shorter one.

Three verdicts, because a board needs the third

import sysl.harness.*

reads_adc()
    check(true)

run("reads_adc", &reads_adc)
skip("reads_thermocouple", "no part fitted")
finish()

<page>:6:reads_adc:PASS
<page>:7:reads_thermocouple:SKIP: no part fitted
1 tests, 0 failed, 1 skipped

On the host a test that cannot run is usually a test that should be deleted; on a target it is routine — the part is not fitted, the bus is wired for the other variant, the flash is the smaller one. Counting those as passes says something false and counting them as failures says something worse, so they are counted as themselves.

skip takes the name rather than the body, because the body is exactly what is not going to be called.

Saying where the report goes

attach points the framework at a writer of your own, which is what a board does before it runs anything:

import sysl.harness.*
import board.*

attach(console())

Given none, it writes to standard output — resolved on first use, which matters to every program that never mentions testing: a module’s storage is initialized in every image the library is linked into, and a sink stored eagerly would put a trait object through the reference counter, whose release path names free. A program on a bare board would acquire a call to an allocator it has not got. A null pointer is a stored zero and reaches nothing.

A board’s console is ordinary sysl. A UART is a volatile store through a pointer, which is a language feature, so reaching one needs no asm, no semihosting and no C library:

module board

struct Uart
    data: volatile u8

val UART: usize = 0x10000000
val regs: *Uart = ptr_cast(UART)

putc(c: u8)
    regs.data = c

struct Console
end Console

impl Fallible for Console

impl Writer for Console
    write(*self, bytes: []const u8)
        for b in bytes do putc(b)
end Console

val uart: *Console = ptr_cast(0usize)

console() -> *Writer = uart

That is a real one — QEMU’s virt puts a 16550 at 0x10000000, and the compiler’s own board tests use these lines.

Writer requires Fallible, so the empty impl Fallible is not a formality — it takes the default failed, which answers false. A UART that cannot fail has nothing to add.

Console has no fields, so its receiver is a null pointer. A trait object is two words, a method table and a datum, and write here never looks at the datum — everything it needs is the module’s own regs. Given nothing to point at, ptr_cast(0usize) is the honest spelling; the alternative would be to take the address of a temporary, which is a dangling pointer with better manners.

And it has to be a module of its own rather than the file your statements are in. An impl member cannot see a root file’s top-level bindings, so write could reach neither regs nor putc. One directory down it is ordinary code.

The verdict, and what to do with it


`tests_run() -> int`	how many ran
`failures() -> int`	how many failed
`skipped() -> int`	how many were skipped
`finish() -> i32`	print the tally, and answer `0` if everything passed
`quiet: bool`	when true, nothing is printed and only the counters move
`reset()`	zero the counters, for a suite that runs more than once

finish returns rather than exits, and that is the whole of what makes this framework portable. A hosted program writes exit(finish()). A board has no exit: semihosting has SYS_EXIT, RISC-V’s virt has a magic register, a real one has whatever pin somebody soldered. None of that belongs inside a framework that would then only build for the target it had heard of — so finish hands the number back and the board signals it however it signals things.

reset deliberately leaves the sink alone. A board attaches once at startup, and a reset that undid that would send the second pass of a looping self-test to a console the board does not have.

What it is not

It does not discover tests. run is a call, so the suite is a list you wrote. On a host sysl test collects @test functions for you; here there is no runner to do the collecting, and a list in source is the honest form.
It has no fixtures, no setup and no teardown. A test body is a function; what it needs, it calls first.
It does not time anything. A clock is the board’s and there is no portable one to ask.

Generics

2026-08-16T01:26:07.924728867Z

A type parameter list in square brackets makes a function, struct, or enum generic. A parameter name stands for a type not yet known, and may appear anywhere a type may — a parameter type, a return type, a field type, a variant payload, a local annotation.

id[T](x: T) -> T = x

struct Pair[A, B]
    first: A
    second: B
end Pair

var p = Pair(1, "one")

print(id(7), id("hi"), p.first, p.second)

7 hi 1 one

Three further declarations take parameters without declaring a type of their own: an impl block, whose subject is a generic type or a composed shape applied to them; a member, which may be generic over types of its own beyond its type’s; and a trait, which is then a family of promises rather than one. All three are on traits.

`[]` means type application in a type, indexing in an expression

Square brackets are reused for two things, disambiguated by position, with no new token:

in a type, Box[int] and Result[Box[int], string] apply type arguments to a generic type, and nesting is ordinary;
in an expression, a[0] indexes, and never reads as a type application.

The reuse is unambiguous because a type and an expression never occupy the same grammatical slot. What it looks like it costs is explicit type arguments at a call head — id[int](7) reads as “index id by int, then call” — but only to the parser. The compiler resolves the head first, and a function is not a thing that can be indexed, so there is no second reading to protect:

id[T](x: T) -> T = x

print(id[int](7), id[string]("s"))

7 s

The nearest binding wins, which is the rule every call form follows. A local standing over a function’s name makes the brackets an index again, and its author is never told about a feature they did not reach for.

Writing the type arguments

Five heads take the list. A value argument is written exactly as a type one is, since the two share a list and a position:

written	what it names
`id[int](7)`	a function, qualified or not
`chunk[8]()`	a value parameter — `[const N: usize]`
`Pair[int, real](1, 2.5)`	a constructor
`x.pick[int](3)`	a method — its own parameters, not the receiver’s
`Maybe[int].Just(1)`	a variant, which is a construction of its type
`va_arg[int](ap)`	a special form: `va_arg` and `ptr_cast`

Inference is still what supplies them nearly everywhere, and a list inference would have found is noise. What earns the syntax is a signature neither direction of inference reaches — a kernel whose width is a value parameter it names in no argument and answers unit with:

add[const W: usize](a: []const f32, b: []const f32, out: []f32)
    var i: usize = 0

    while i + W <= a.len
        val l: <W>f32 = a.load(i)
        val r: <W>f32 = b.load(i)

        out.store(i, l + r)
        i += W
end add

val xs: [8]f32 = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]
val ys: [8]f32 = [10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0]
var out: [8]f32

add[4](xs[..], ys[..], out[..])

print(out[0], out[7])

11 88

Written without the brackets there is nothing anywhere to say what W is, and the message says so rather than naming an annotation that cannot exist:

add[const W: usize](a: []const f32, out: []f32)
    val v: <W>f32 = a.load(0)

    out.store(0, v)
end add

var xs: [8]f32
var out: [8]f32

add(xs[..], out[..])

'W' is in neither the parameters of 'add' nor its result

Two things stay inferred. A type pack — ..A — stands for a list of types rather than one and has no expression spelling, so its instantiation is always solved. And an associated function selected from an applied type, Box[int].of(1), reads its type’s parameters and its own from a single solve; the annotation on the binding reaches it, and unlike the kernel above there is always one, since an associated function has a result.

There is also a hole shared with the address form: the brackets read the expression grammar, so a type the two grammars do not spell alike has no form there. []int, weak T, volatile T, <4>f32 and a callable are refused by the parser. The annotation reaches every one of them.

The address form came first: &f[T] names one instantiation of a generic function, and the case that earned it is a C callback whose signature mentions the type parameter nowhere. See the FFI reference.

Construction

Applying a generic type names a concrete instance: Box[int] is the type of a box of int, Pair[int, string] a pair. Constructing one is the ordinary construction, with the type arguments inferred from the arguments — Box(41), Pair(1, "one") — or written on the name, which means what the annotation means: Pair[int, real](1, 2.5) fixes the instantiation and checks the fields against it. The memory mode is the usual per-declaration choice: Box(41) is a value unless a &Box[int] is expected.

Inference is bidirectional

Type arguments are inferred, and from two directions.

From the arguments. id(7) infers T = int, and inference reaches through a generic construction, so every nested parameter is solved at once:

struct Box[T]
    v: T
end Box

id[T](x: T) -> T = x

var b = id(Box(id(5)))

print(b.v)

From the expected type, when the arguments cannot determine a parameter. A nullary generic has nothing in its argument list to fix T, so the declaration supplies it and the return type flows inward:

empty[T]() -> Option[T] = None

var e: Option[real] = empty()

e match
    Some(v) -> print("some", v)
    None    -> print("none")

none

The model is unification: each parameter is solved by matching the declared parameter and return types against the actual argument types and the expected type. When a parameter is left undetermined by both directions, that is a compile error asking for an annotation on the binding — never a silent default and never a stuck inference variable.

A literal is consulted last, because a literal has no type of its own to offer. It takes one from where it appears, and a parameter still being solved is not yet a place that can give it one. So what is already a type settles the parameter first, then the expected type, and a literal’s default only where nothing else reached it:

pick[T: Add](a: T, b: T, c: T) -> T = a + b + c

print(pick(1, 2, 250u8))

That is a u8 because one argument knew and two did not, while id(7) is still an int because none did. Once the parameter is a type the literals are read against it — the same order the operand rule uses inside an expression.

A parameter is solved to the type that was written. Where that is a transparent subtype, the parameter carries the subtype rather than the base it is stored as — and it does so however the call said which type it is at:

type Age = int within 0..150

widest[T]() -> T = T::Max

val written = widest[Age]()
val expected: Age = widest()

print(int(written), int(expected))

150 150

The routes have to agree, because from the reader’s side they are three ways of saying one thing. Writing Age at the call, handing an Age as an argument, and annotating the binding Age are each a way of naming the type this call is at; an answer that depended on which one was available would be an answer about the call rather than about the type.

That a transparent subtype is its base — an Age stands where an int is asked for, and the reverse — is unchanged, and holds for every value that flows. A type parameter is not a value: it is the name a body is written about, and the body may ask it something its base would answer differently. T::Max is the only such question there is.

null is not consulted at all — it waits, and what separates it from a literal is that it has no default to be consulted for. The argument that cannot contribute is set aside, the rest solve the parameter, and it is then read against what they said:

two[T](a: *T, b: *T) -> bool = a == b

var x: int = 3

print(two(&x, null), two(null, &x))

false false

Either order answers alike, since waiting is not queueing — and setting it aside cannot lose the solution, because an argument with no type of its own has nothing to unify. Where nothing else reached the parameter it is refused rather than defaulted: inference does not invent a pointee.

one[T](a: *T) -> bool = true

print(one(null))

'null' takes its type from its context, and there is none here

A parameter that names no type parameter is not part of the question, and its argument is checked against it exactly as a plain callee’s is:

at[T](x: T, n: usize) -> string = str(n)

print(at("v", 7))

That is worth saying because inference has to look at the arguments before it knows what anything is, which would otherwise cost a generic callee the rules that need an expected type — a parameter’s type fixing an unsuffixed literal, and the coercions to &T and to a trait object. A declaration having a T somewhere does not make its usize any less a usize.

Members and associated functions

A method never asks the question. Its receiver already is a Box[int], so the type’s arguments are read rather than solved.

An associated function has no receiver, which puts it in the position a generic free function is always in — so it is inferred by exactly the rule above and needs no machinery of its own:

struct Box[T]
    v: T

    of(x: T) -> Box[T] = Box(x)
end Box

var b = Box.of(41)

print(b.v)

Self in the signature is the type applied to its own parameters, so writing -> Self and writing -> Box[T] infer alike.

A member’s own type parameters are inferred the same way. The receiver says what the type’s arguments are and nothing about the member’s, which leaves those exactly where the rule already reaches:

struct Pair[A, B]
    first: A
    second: B
end Pair

struct Box[T]
    v: T

    with[U](self, x: U) -> Pair[T, U] = Pair(self.v, x)
end Box

var b = Box(1)
var p = b.with("x")

print(p.first, p.second)

1 x

The two lists are held to their bounds separately and under the name each was written in. That they must not collide is the one thing the two-list form adds, and it is settled by refusing a member that spells one of its own the way its type spells one of its.

Bounds

A type parameter is bounded by a trait, and the bound is what the body of a generic is allowed to assume about the parameter.

An unbounded parameter permits only what every type supports

With no bound, T may be used only for the operations every sysl value has — which, because of the memory model, is a genuinely useful set: copied, assigned, passed, returned, and stored in a struct field, an enum payload, an array, or a slice.

That set is exactly id[T], Box[T], Pair[A, B], and every other container: they move data around without inspecting it, and they need no bound.

struct Box[T]
    v: T
end Box

keep[T](x: T) -> Box[T] = Box(x)

var a = keep(5)
var b = keep("hi")

print(a.v, b.v)

5 hi

Every sysl value is copyable — assignment copies, and copying a value holding a &T retains it — so there is no Copy bound to write, ever. That is a real simplification over Rust, where T is move-by-default and T: Copy / T: Clone litter generic signatures. Here, “hold and hand along any T“ is the free, unmarked baseline.

What an unbounded T may not do is anything that assumes structure: no operator, no method call, no field access, no index. Each is a capability some types have and others do not, so each requires a bound that guarantees it — and each is refused at the definition, naming the bound to write:

sum[T](a: T, b: T) -> T = a + b

print(sum(2, 3))

'+' needs 'T: sysl.Add'

A subscript is among them, because a subscript is Index‘s one method, so it is asked of the bounds exactly as a dot call is.

A field is the exception that proves the rule. Every other unlicensed use names the bound that would allow it — the diagnostic’s whole job is to say what to write. A field names none, because a trait promises behaviour and a field is layout, so no bound could ever supply one:

first[T](x: T) -> int = x.v

print(1)

'T' is a type parameter, so it has no fields to read — a field is layout, and no trait declares a property 'v' that a bound could promise instead

It is therefore settled outright at the definition rather than deferred to the types that turn up: first[T](x: T) = x.v is wrong even if every call happens to pass a type with a v. Reaching a value’s data through a generic means going through a member the bound declares, which is also what lets two types satisfy one bound while storing the value differently.

x.v is spelled like a field and need not be one, so the diagnostic is reached only after looking for a property of that name: a property is behaviour, a trait may declare one, and reading it through a bound is as ordinary as calling a method.

A bound is a trait, written `[T: Trait]`

sum[T: Add](a: T, b: T) -> T = a + b

smaller[T: Ord](a: T, b: T) -> T = if a < b then a else b

print(sum(2, 3), smaller(9, 4))

5 4

a + b inside sum type-checks because T: Add promises the operator; drop the bound and sum fails at its own definition, pointing at the line that made the unsupported assumption. That is the whole payoff over the template model: the error lands on the definition that is wrong, not on some caller three files away that instantiated it with the wrong type. It is the Swift/Kotlin/Scala consensus — all three check bounds at the definition, and only C++ defers to instantiation.

Operators are available through bounds because operators are trait methods: + is Add, < is Ord, == is Eq.

Multiple bounds join with +: [T: Ord + Hash] requires both. The + reads unambiguously in a bound position, since it stands between trait names rather than values.

A bound is the trait applied, so it carries the trait’s own type arguments where it has any:

written	means
`[X: Sink[int]]`	the body’s `x.put(…)` takes an `int`
`[X: Into[Y], Y]`	and `Y` is solved at the call
`[X: Into[Y], Y: Display]`	a body that may also print what the conversion yields

The arguments are ordinary types, which is what lets one name another parameter of the same declaration — and what a body may then do with that parameter is what its bounds promise. Inference does not run backwards through a bound: a parameter appearing only there is solved from the result type or annotated.

A trait object satisfies a bound on the trait it dispatches through

A bound asks whether the members it names can be called on the value. A *Trait or a &Trait has forgotten which type it holds, but it carries a table of exactly those members — so it answers yes, and one generic function takes both a concrete type and the object erased from it:

trait Shape
    area(self) -> int

struct Rect
    w: int
    h: int

impl Shape for Rect
    area(self) -> int = self.w * self.h

total[T: Shape](x: T) -> int = x.area()

var o: &Shape = Rect(3, 4)

print(total(Rect(3, 4)))
print(total(o))

12
12

Nothing about monomorphization is bent to allow it. An object type is a concrete type — a pair of words — so the body is instantiated at &Shape exactly as it is at Rect, once each. What differs between the two instantiations is what x.area() compiles to: a direct call in one, an indirect call through the table in the other. That is the same difference the two instantiations would have had anyway, and it is decided the same way — by looking at the type the parameter was bound to.

It is total, and that is a property of object safety rather than a promise made here. A trait with a member that cannot be dispatched — one mentioning Self away from its receiver, say — has no object at all in sysl, rather than an object missing that member. So a &Shape existing is already the proof that every member of Shape is reachable through it, and there is no “this method is unavailable on the object” case for a bound to trip over.

It follows for required traits with no rule of its own. trait Shape: Display puts Display‘s slots in the object’s table, and a bound on a trait is already satisfied wherever a bound on one that requires it is — so a show[T: Display](x: T) takes the same o.

What an object still does not satisfy is a bound on any other trait: the table is what answers, and a trait with no slots in it has nothing to answer with.

trait Shape
    area(self) -> int

trait Weighed
    weight(self) -> int

struct Rect
    w: int
    h: int

impl Shape for Rect
    area(self) -> int = self.w * self.h

heft[T: Weighed](x: T) -> int = x.weight()

var o: &Shape = Rect(3, 4)

print(heft(o))

'heft' requires its type parameter 'T' to implement 'Weighed', but &Shape does not

Satisfying a bound is not the same as being erasable again. A bound asks what may be called through a value; forming an object asks what may be assembled from its type, and a table is laid out from a type’s implementations. An object has none, so a &Shape cannot be turned into a &Display even though Display‘s slots are sitting inside its table — a run of slots in one table is not a table of its own ([traits]({{< ref “traits” >}})).

A type’s own parameters carry bounds too

The same bracketed list, in the same place, means the same thing on a struct or an enum — and that is where the type says what it assumes:

struct SortedPair[T: Ord]
    lo: T
    hi: T

    ordered(self) -> bool = self.lo < self.hi
end SortedPair

var s = SortedPair(1, 2)

print(s.ordered())

true

It buys two things, worth stating separately.

Everything applying the type must supply it, wherever the application is written — a declared parameter, a result, a field of another type, a variant’s payload, a construction:

struct SortedPair[T: Ord]
    lo: T
    hi: T
end SortedPair

struct P
    v: int
end P

var s = SortedPair(P(1), P(2))

print(1)

'SortedPair' requires its type parameter 'T' to implement 'sysl.Ord', but P does not

Where the argument is itself a type parameter, the answer is what its own bounds promise, so a function taking a SortedPair[U] must bound U by at least what SortedPair asks. A bound is satisfied by a bound, one step out.

And the type’s members may assume it, so they are checked at their definition. That is what having somewhere to write the bound is for: a member of a generic type is walked once, with the parameters standing in for themselves, by the same pass that walks a bounded generic function — so a method calling something no bound licenses is reported on its own line whether or not anything instantiates the type. A generic type’s fields are laid out once the same way, which is what catches a field applying another bounded type to this one’s parameter.

A bound is declared once, at the type, and is in force everywhere its parameters appear — a member’s signature and body, a field’s type, a variant’s payload. It is not restated per member. Restating it is Rust’s rule and its own users regret it; declaring once is the Swift/Kotlin behaviour and the one that matches how the bound reads.

A parameter may carry a default

A parameter of a trait, a struct, or an enum may name the type to use where a use leaves it out:

struct Pair[A, B = A]
    x: A
    y: B
end Pair

total(p: Pair[int]) -> int = p.x + p.y

print(total(Pair(1, 2)))

The bound comes first and the default last — [R: Show = Self] — and either may be written without the other. Four rules govern them:

Defaults are filled left to right, each resolved under the arguments already fixed, so a default may name a parameter written before it, and naming one written after it is the forward reference it looks like.
They are a suffix. A parameter with no default may not come after one that has, because arguments are written in order and nothing could leave out the earlier one and still supply the later.
The filling happens before anything is keyed on the arguments, so Pair[int] and Pair[int, int] are one instantiation rather than two that happen to have the same fields.
A default is exposed like a field. A public declaration may not default to a type that reaches less far than it does, or a caller who leaves the argument out ends up holding something they could not have written and cannot name. And a default may not lead back to the declaration it belongs to, directly or through another’s.

Self is the case the feature exists for. In a trait’s default it means the implementing type, exactly as in a method’s signature — so impl Scale for P is the impl Scale[P] for P it reads as, and [T: Scale] asks for Scale[T]. A struct and an enum have no implementing type, so Self in one of their defaults is refused. Neither has a trait object: an object has forgotten which type it holds, so a default of Self has nothing to name and the argument is written out.

Only those three declarations may carry one. A function’s, a method’s, and an impl block’s type parameters are solved from what they are given rather than written where they are used, so there is no argument list with a gap for a default to fill:

f[T = int](x: T) -> T = x

print(f(1))

'T' is a type parameter of the function 'f', whose type parameters are solved from what it is given rather than written where it is used — so '= int' has nothing to stand in for

What would be useful there is a fallback for an inference that found nothing, which is a different feature; f[T = int](x: T) is refused rather than quietly meaning that.

Converting through a parameter

A conversion is the one capability with no bound to promise it, because a conversion is between the concrete scalar kinds rather than something a trait declares. Both directions are written, and both are checked at each instantiation rather than at the definition:

low[T](x: T) -> u8 = u8(x)

make[T](b: u8) -> T = T(b)

var n: int = make(7)

print(low(321), n)

65 7

T(b) is a conversion written where the parameter’s name stands, resolved at each instantiation, so the two directions of one conversion are one rule. An instantiation at a constrained subtype or a simple enum takes that type’s own checked cast, since the scalar conversion has no meaning for either and the form written under the type’s name does — so T(x) at an Age is the Age(x) a reader would have written, trap included.

Construction is deliberately not among the forms it reaches. A struct’s positional constructor takes a field list rather than a value, and a generic body filling in an unknown struct’s fields by position is not something to arrive at by accident:

struct P
    v: int
end P

make[T](b: u8) -> T = T(b)

var p: P = make(7)

print(p.v)

cannot convert byte to P

T(b) stays a conversion at every instantiation, so at a struct it is refused exactly as u8(x) at one is — naming the struct, and not quietly becoming a constructor. What a container that wants to build a T reaches for is a bound that says so.

The parameter wins over a declaration of the same name, which closes an inconsistency rather than opening one: var y: T inside a [T] body has always meant the parameter, so T(x) one line later means it too.

Monomorphization

Each distinct set of type arguments produces its own specialized function or aggregate. id called at int and at real emits two functions; a Box[int] and a Box[string] are two distinct layouts. The IR carries exactly one definition per instantiation, not one per call.

That is why bounds can be checked once at the definition yet lower to direct, monomorphic code with no dictionary passed at runtime.

The cost is code size, the standard monomorphization tradeoff — C++ templates and Rust generics make the same one. It is the right default for a systems language, where the direct, inlinable call matters and the dynamic path is available when one copy is preferable.
Recursion is fine. A recursive generic function recurses at a fixed instantiation, so it monomorphizes like any other.

Variance does not arise

There is no variance question in sysl, by construction. Variance is about when G[A] may stand in for G[B], and that needs a subtyping relation to be interesting — which sysl does not have among concrete types. There is no inheritance, and a trait bound is a constraint rather than a supertype relation between values.

trait Animal
    noise(self) -> string

struct Cat
    n: string
end Cat

impl Animal for Cat
    noise(self) -> string = "meow"

struct Box[T]
    v: T
end Box

hear(b: Box[&Animal]) -> string = b.v.noise()

var c = Box(Cat("ada"))

print(hear(c))

'b' of 'hear' is Box[&Animal], but Box[Cat] was given

Box[Cat] and Box[&Animal] are simply unrelated types. That deletes an entire category of design difficulty that afflicts languages with nominal subtyping, and it should stay deleted: polymorphism over a set of types is expressed by a bound or a trait object, never by a covariant container.

A parameter may stand for a value

A type parameter stands for a type. A parameter written const stands for a value — which is what lets one declaration cover every array length:

total[const N: usize](xs: [N]int) -> int
    var t = 0
    for i in 0..<N do t = t + xs[i]
    t

var a: [3]int = [1, 2, 3]
var b: [5]int = [10, 20, 30, 40, 50]

print(total(a))
print(total(b))

6
150

N is inferred from the argument exactly as a type parameter is: matching [3]int against [N]int binds N to 3, the way matching Box[int] against Box[T] binds T. Inside the body N is an ordinary usize — it can be looped to, computed with, and passed on.

total at N = 3 and at N = 5 are two functions, the same way id at int and at real are two: the value joins the type arguments the instantiation is keyed on, so the length is a constant inside each copy.

It is the same `const` as everywhere else

A constant is declared const NAME: Type = expr. A value parameter is that declaration with the initializer left for the caller, so [const N: usize] is existing grammar in a new position rather than a new idea.

The marker is not decoration. [N: usize] on its own is indistinguishable from a bounded type parameter — [T: Ord] has the same shape — and only name resolution could tell them apart, by asking whether the thing after the colon is a trait or a type. A trait name misspelled into a type name would then silently change what kind of parameter it is.

Which values

Integers, bool, char, and a simple enum’s variants. A value parameter puts a value into a type’s identity, so the compiler has to decide when two of them are the same value and has to write one into a mangled name — and each of these compares and mangles.

A type declares its value parameters the same way, and its arguments are written out rather than inferred, because a type has no call to infer them from:

struct Buf[const N: usize]
    data: [N]byte

struct Flag[const B: bool]
    v: int

var buf: Buf[4] = Buf([1, 2, 3, 4])
var on: Flag[true] = Flag(1)

print(buf.data.len, on.v)

4 1

Buf[2] and Buf[4] are two types with two layouts, and neither stands where the other is wanted.

A member reads the parameter as an ordinary value of its declared type, and the two lengths are two bodies rather than one compiled at whichever came first:

struct Buf[const N: usize]
    used: usize

    room(self) -> usize = N - self.used
end Buf

var a: Buf[8] = Buf(3)
var b: Buf[2] = Buf(1)

print(a.room())
print(b.room())

5
1

Floats are excluded: NaN != NaN under the ordinary comparison, which would make a type unequal to itself. Strings are excluded until two spellings of one text are one value.

What may be written with `N`

N may stand as an array’s length, and a body may compute with it freely. What neither may do is carry the result of a computation into a type:

f[const N: usize](xs: [N]int) -> [N + 1]int = xs

print(1)

this length does arithmetic on 'N'

Deciding that N + 1 and 1 + N are one type — and that 2 * N and N + N are — is type-level arithmetic, which is a feature of its own.

Writing a type parameter where a length belongs is refused for the mirror reason, since a length is a value:

f[T](xs: [T]int) -> usize = 0

print(1)

'T' is a type parameter, and an array's length is a value rather than a type

What it is for: a fixed array renders

impl[const N: usize, T: Display] Display for [N]T is one block covering every array there is, which is why print takes one:

var a: [3]int = [1, 2, 3]
var b: [2]string = ["x", "y"]

print(a)
print(b)

[1, 2, 3]
[x, y]

Before this, a length was part of a type’s shape: [2]T and [3]T were two shapes with no way to be generic over the difference, so no library could implement a trait for arrays in general.

An array still has two shapes an impl may match — the length written out, and the length as a parameter — and the written-out one is more specific, so it is found first. A block for [2]T still wins over a block for [N]T on arrays of two, which is the same “written-out beats a parameter” ordering override uses.

A member declares its own

A method’s parameter list is its own, exactly as a function’s is — so it may take a value parameter that the type’s parameters know nothing about. The type’s are fixed by the receiver; the member’s are solved at the call:

struct Sum
    seen: usize

    take[const N: usize](*self, xs: [N]int) -> usize
        self.seen = self.seen + N
        N
end Sum

var s = Sum(0)

print(s.take([1, 2, 3]))
print(s.take([4, 5]))
print(s.seen)

3
2
5

Both calls reach one written method and neither passes a length, because N is read off the argument the same way it is for a free function.

A parameter may stand for a list of types

A type parameter stands for one type and a const parameter for one value. A parameter written .. stands for a list of types — a pack — which is what lets one declaration cover every tuple:

joined[..A: Display](t: (..A)) -> string
    var s = ""

    for const i in 0..<A.len
        if i > 0 then s = s + "-"

        s = s + str(t.i)

    s

print(joined((1, 2)))
print(joined((1, "two", true, 4.5)))

1-2
1-two-true-4.5

Three things are new there and each does one job.

..A declares the pack, and (..A) is the tuple of it — the only spelling a pack has, wherever it is declared. It matches a tuple of any arity, and the arity is inferred from the argument exactly as an array’s length is: a (int, string, bool) matched against (..A) binds A to those three.

The bound distributes over the members. [..A: Display] says every type in A implements Display, and that is the whole of the bound syntax a pack needs — the ordinary [T: Display] read over a list. It is what makes the membership answerable before any body is compiled, so a tuple holding something unprintable is refused where it is written:

struct Point
    x: int
    y: int

joined[..A: Display](t: (..A)) -> string = str(t.0)

print(joined((1, Point(2, 3))))

Display

for const is unrolled. Its range must be known when the program is compiled — A.len is how many types the pack stands for — and the body is repeated once per value, with i folded in as a compile-time usize. Each copy is type-checked on its own, which is the point: the parts of a tuple have different types, so t.i is a different selection in each copy and one written line covers all of them.

t.i at a compile-time i is the selection t.0 already is, with the position arriving as a constant rather than as a literal. It reaches the parts of a tuple and nothing else — a struct’s fields have names, and a number does not address one.

What a `for const` will not do

A range computed at run time cannot be unrolled, and the ordinary for is what walks one:

f(n: usize)
    for const i in 0..<n
        print(i)

f(3)

must be known at compile time

break and continue are refused as well. There is no loop at run time for either to act on: the copies are straight-line code inside whatever the for const was written in, so a break would leave that loop — one copy at a time, and silently. A loop written inside the body is an ordinary loop and breaks out of itself as usual.

return does work, and it is what Eq and Ord on a tuple are written with — an unrolled copy is straight-line code in the enclosing function, so a return in one is an ordinary return.

What it is for: the catalog covers every tuple

impl[..A: Display] Display for (..A) is one block covering every tuple there is, and Eq, Ord and Hash are each one more. Before this, a tuple’s arity was part of its shape: a pair and a triple were two shapes with no way to be generic over the difference, so the library wrote a row per arity and stopped at three — and a tuple of four parts implemented nothing.

A tuple now has three shapes an impl may match, and they are found most specific first: the tuple written out in full, then one arity, then every arity.

trait Tag
    tag(self) -> string

impl[..A: Display] Tag for (..A)
    tag(self) -> string = "any"

impl[A: Display, B: Display] Tag for (A, B)
    tag(self) -> string = "pair"

override impl Tag for (int, int)
    tag(self) -> string = "two ints"

print((1, 2).tag(), (1, "x").tag(), (1, 2, 3).tag())

two ints pair any

That is the same “written-out beats a parameter” ordering an array’s two shapes have, one rung longer — and the override is the separate rule it has always been. Coherence says where a block may be written; override says which of two blocks that both have a home answers. A block for a tuple written out in full is the specific one, so it is the one that says so.

A member declares one too, unless a trait requires it

A pack stands in a method’s own parameter list on the same terms a value parameter does, and for the same reason — the list belongs to the member:

struct Row
    n: usize

    take[..A: Display](*self, t: (..A))
        for const i in 0..<A.len
            self.n = self.n + str(t.i).len
end Row

var r = Row(0)

r.take((1, "abc", true))
print(r.n)

A trait’s member is refused, and not for a reason about packs. No member a trait requires may declare parameters of its own of any kind: a table slot cannot hold a function that does not exist until a call names its types. A pack is one more way of writing that list, so it meets the rule already there.

trait Take
    take[..A: Display](self, t: (..A)) -> usize

declares type parameters of its own, which a trait's member may not

A struct, an enum and a trait are refused a pack for a different reason — their parameters are their shape, and there is nothing to spread a list over. A member has no shape of its own, so that reason never reached one.

This is not variadic functions

A pack is a compile-time list of types. C’s ellipsis is a run-time walk over untyped storage (ffi), and the two share nothing. There is also no pack expansion: a pack cannot be spread into a call’s arguments, and (..A, int) cannot append to one. The unrolled loop stands in for expansion, in the one direction the catalog needs.

What is deliberately not here

absent	why, and what to write instead
explicit type arguments at a call	`id[int](7)` collides with indexing; annotate what receives the result. At an address they are written — `&f[T]`
`where` clauses	the inline `[T: A + B]` list is the settled baseline; an out-of-line form is a possible ergonomic addition
type-level arithmetic (`[N + 1]T`)	a value parameter may stand as a length but not be computed with in a type; deciding that `N + 1` and `1 + N` are one type is a feature of its own
pack expansion (`f(..a)`, `(..A, int)`)	a pack may be matched and walked, not spread into an argument list or appended to; `for const` is what stands in for it
higher-kinded parameters (`F[_]`)	excluded, not deferred — it pushes inference toward undecidable, and abstraction over containers is served by traits and bounds

The first of those has one position where the annotation costs more than a word. A nullary generic has no argument to be inferred from, so buf() and map() are solved by what receives the result and nothing else — and buf[u8]() is the first thing a reader tries. That form is refused by name, naming the annotation that stands in for it, rather than by a general complaint about a callee that is not a name.

Next: modules.

Functions

2026-08-16T01:26:07.924728867Z

Two bodies

A function is a name, a parameter list, a return type, and a body. When the body is one expression it goes after =:

add(a: int, b: int) -> int = a + b

print("3 + 4 =", add(3, 4))

3 + 4 = 7

When it is more than that, indent it under the header and drop the =. The trailing expression is what the function yields — there is no return to write, though return exists for leaving early:

classify(n: int) -> string
    var doubled = n * 2

    if doubled > 100 then "big"
    else "small"

print(classify(60), classify(3))

big small

An optional end marker closes a declaration and names it. It is worth writing on anything long enough that the closing indentation is off the screen:

factorial(n: int) -> int
    var acc = 1

    for i in 2..n do acc *= i

    acc
end factorial

print(factorial(10))

A function that returns nothing simply says nothing:

announce(what: string)
    print("***", what, "***")

announce("no return type")

*** no return type ***

Defaults, and names at the call site

A parameter may carry a default, and defaults fill from the right — so what a call writes decides how many are taken:

tag(text: string, open: string = "[", close: string = "]") -> string = open + text + close

print(tag("all"), tag("half", "<"), tag("none", "{", "}"))

[all] <half] {none}

The default is an expression evaluated at each call, not one value computed once and shared. That matters as soon as a default allocates: every call gets its own.

An argument may also be given by name, which is what rescues a call site that would otherwise be a row of anonymous literals:

window(x: int = 0, y: int = 0, width: int = 80, height: int = 24) -> string
    str(width) + "x" + str(height) + " at " + str(x) + "," + str(y)

print(window(width = 132, y = 10))

132x24 at 0,10

A positional argument may not follow a named one — once a call starts naming, it names.

One name, several functions

A name may be declared more than once. Which declaration a call means is decided by the arguments it passes — how many, and what type each is:

show(x: int) -> string = s"int $x"
show(x: string) -> string = s"str $x"

print(show(1))
print(show("a"))

int 1
str a

Never by what they return, though: two declarations differing only in the result have no call that tells them apart, and the second is refused where it is written. The reference has the rest, including what happens when a call fits two of them.

Closures

A function that takes a function writes the parameter’s type with an arrow. One parameter needs no parentheses; two or more, or none, take them:

apply(f: int -> int, x: int) -> int = f(x)
combine(f: (int, int) -> int, a: int, b: int) -> int = f(a, b)

print(apply(x -> x + 1, 5), combine((a, b) -> a * b, 6, 7))

6 42

A closure body sees the names around it, which is what makes it worth having rather than passing a plain function pointer. Naming one captures it, and there is no capture list to write:

apply(f: int -> int, x: int) -> int = f(x)

var factor = 10

print(apply(x -> x * factor, 5))

What capture does, exactly

This is the one place closures will surprise you if you arrive from Kotlin, Swift or JavaScript, so it is worth meeting now rather than in a debugger. Capturing a value copies it in. The closure gets its own, and writing to it does not touch the original:

each3(f: int -> unit)
    for i in 0..<3 do f(i)

var total = 0

each3(i -> total += i * i)
print("the outer total is still", total)

the outer total is still 0

Nothing went wrong there. total is an int — a value — and capturing a value copies it, so the closure incremented a copy that went away when it did. This is not a special rule for closures; it is the same copy discipline a by-value parameter or a struct field follows, applied at the moment the closure is formed.

To accumulate, capture something that is shared. A &T is a counted reference, so capturing one retains it rather than copying what it points at, and everybody sees the same object:

import sysl.buf.{Buf, buf}

each3(f: int -> unit)
    for i in 0..<3 do f(i)

var seen: &Buf[int] = buf()

each3(i -> seen.push(i * i))
print("collected:", seen.len())

collected: 3

Which of the two you get is decided by the captured variable’s type, not by anything written at the capture site — so it is the same question the memory chapter is about, and knowing that chapter is knowing this rule.

The compiler also works out how long a closure needs to live. One that does not outlive its frame is inlined and costs nothing; one that escapes — stored in a field, returned — is heap-boxed and counted. You do not choose between them, and you cannot get it wrong.

Next: structs and methods — giving a type some data, and then some behaviour.

The fs module

2026-08-16T01:26:07.924728867Z

sysl.fs is the first module in this section that a target may simply not have. Its files open with two lines rather than one:

module sysl.fs
@requires(os)

Nothing here is language, and nothing here can be given a body on a target with no filesystem under it: a freestanding image has no fopen to call and no errno to read. So the clause is not a warning — it is a fact about which module exists, and it is checked at the import:

@no_os

import sysl.fs.exists

print(exists("/tmp"))

this reaches 'sysl.fs', which requires 'os', and this module declared 'no os' — an environment capability gates which modules exist, so a module that gave one up may not reach one that needs it

That is the difference between os and alloc worth holding on to. alloc is checked on what a module calls, because the standard library has allocating and non-allocating halves running through the middle of it. os is checked on the module boundary, because it decides which modules exist at all — there is no half of sysl.fs that works without one.

Three tiers, and the line between them is the allocator

tier	names	what it costs
whole file	`read_text`, `read_bytes`, `write_text`, `write_bytes`, `append_text`, `append_bytes`	storage the size of the file — allocates by nature
open file	`open`, `create`, `append`, `open_update`, `create_update`, and `File`‘s members	a buffer the caller already has
path	`exists`, `readable`, `writable`, `is_file`, `is_dir`, `size_of`, `make_dir`, `remove_file`, `remove_dir`, `rename`	one C call each

Reading a whole file is asking for storage the size of the file, so the top tier could not have been written any other way. Keeping it apart from File is what lets the middle tier stay honest: opening and reading in chunks needs only a buffer the caller brought, and works in a module that must not allocate.

The whole-file tier

import sysl.fs.{write_text, read_text, append_text, read_bytes, remove_file, exists}

var path = "/tmp/sysl-fs-doc-1.txt"

write_text(path, "hello\n").unwrap()

print(read_text(path).unwrap().len)

append_text(path, "again\n").unwrap()

print(read_bytes(path).unwrap().len)
prints(read_text(path).unwrap())

remove_file(path).unwrap()

print(exists(path))

6
12
hello
again
false

Each of these opens, does the one thing, and closes — and closes through defer, so the handle is released down the failing paths too. That is the idiom the module is written to demonstrate: a scope releases what the scope said it would. A destructor is the other way to say it and wants the handle behind a &T; these functions never let one escape, so the scope is enough.

read_bytes reads in chunks and grows rather than sizing itself from the file’s length first. That costs a little copying and buys the case that matters — a file being written while this reads it, and anything whose length is not a fact until the read ends. The loop stops on the first empty read, and asks afterwards whether the reading ended badly, which is the split Reader was built around.

Bytes that are not UTF-8 stop the program rather than becoming an error case. That is deliberate: answering with an error instead would put a case in IoError that no filesystem ever reports, and would make every program reading its own configuration handle a failure that means its build is broken. The severity is affordable because the layer underneath is public — a caller who would rather inspect than trap reads read_bytes and validates it with from_utf8.

`IoError`

enum IoError
    NotFound
    PermissionDenied
    AlreadyExists
    NotADirectory
    IsADirectory
    DirectoryNotEmpty
    TooManyOpenFiles
    NoSpaceLeft
    Interrupted
    NotOpen
    Other(code: int)

    code(self) -> int
    message(self) -> string

impl Display for IoError

Every Result this module hands back carries one. It is an enum rather than a bare int for the reason Result carries its error as a type parameter at all: a caller that wants to act on why wants to match, and a match over named cases is exhaustive where a comparison against a number is a guess that compiled.

The cases are the ones a program branches on, and everything else arrives as Other carrying the number. A library that mapped every errno to a name of its own would be a table nobody could keep current and a program could not extend — and the number is what a reader looks up anyway.

code() answers for every case, not only Other: the named ones hand back the code they were recognised from, which keeps the question answerable without a second table. message() is a sentence in the terms the operation was asked in rather than in C’s, and the Display impl is what makes print(e) say it:

import sysl.fs.read_text

read_text("/tmp/sysl-fs-doc-missing.txt") match
    Ok(s) -> print("read", s.len)
    Err(e) -> print("refused:", e, e.code())

refused: no such file or directory 2

errno is read at the failure, not wherever the caller got round to asking. Every call in the module reports with a private why() that reads it on the spot, because there is nothing between the two that could overwrite it — and fclose is a call like any other, which sets errno to whatever it thought.

`File`

struct File
    closed(*self) -> bool
    flush(*self) -> Result[unit, IoError]
    close(*self) -> Result[unit, IoError]
    tell(*self) -> Result[long, IoError]
    seek(*self, to: long) -> Result[unit, IoError]
    size(*self) -> Result[long, IoError]
    at_end(*self) -> bool

impl Fallible for File
impl Reader for File
impl Writer for File

open(path: string) -> Result[File, IoError]          // an existing file, for reading
create(path: string) -> Result[File, IoError]        // makes one, or empties one that was there
append(path: string) -> Result[File, IoError]        // writes at the end
open_update(path: string) -> Result[File, IoError]   // read and write; fails if it is not there
create_update(path: string) -> Result[File, IoError] // read and write; empties what was there

A File is C’s buffered FILE *, not a file descriptor, and that is the load-bearing choice. A descriptor would mean open(2), and open(2) means O_CREAT, O_TRUNC and O_APPEND — three constants whose values differ between platforms and which nothing in the program could check. fopen takes a mode string, which C standardises, so the same three intentions cross the boundary as text that is right everywhere. The five functions above are named for what they mean rather than for the mode string each becomes.

The buffering comes with it, and is the second reason: a Writer that reached the operating system once per write would make rendering into a file cost a system call per fragment, and the rendering surface writes in fragments.

What is given up is the descriptor itself. A program that needs one — to poll it, to hand it to a child — should say open(2) for itself, which is what sysl.io‘s FdReader is already shaped for. The two live side by side on purpose: Reader is about bytes arriving, not about where a program got its handle.

It is a `Reader` and a `Writer`, whole

import sysl.fs.{write_text, open, remove_file}
import sysl.io.lines

var path = "/tmp/sysl-fs-doc-3.txt"

write_text(path, "alpha\nbeta\ngamma\n").unwrap()

var f = open(path).unwrap()

for line in lines(&f)
    prints("[")
    prints(line)
    prints("]")

prints("\n")
print(f.failed(), f.at_end())

f.close().unwrap()
remove_file(path).unwrap()

[alpha][beta][gamma]
false true

lines(&f) works over a file with nothing in sysl.fs knowing about lines, because impl Reader for File is the trait unmodified. Everything that renders into a sink renders into a file for the same reason.

That is also why Fallible is a required trait rather than a member each of them declares. failed takes no arguments, so a failed from Reader and another from Writer would be two members of one name on one type and a call could not say which it meant — on a file, which is both. One shared latch leaves a single answer that each of them reaches.

Reaching a trait member still needs the trait in scope:

import sysl.fs.open

var f = open("/tmp/sysl-fs-doc-3.txt").unwrap()
var window: [4]u8

f.read(window)

sysl.fs.File has 'read' from sysl.io.Reader, and that trait is not in scope here — import it to reach the member

Position and size

import sysl.fs.{write_text, open, size_of, remove_file}
import sysl.io.Reader

var path = "/tmp/sysl-fs-doc-4.txt"

write_text(path, "0123456789").unwrap()

print(size_of(path).unwrap())

var f = open(path).unwrap()
var window: [4]u8

f.seek(6).unwrap()

var got = f.read(window)

print(f.tell().unwrap(), got.len, got[0])
print(f.size().unwrap())

f.close().unwrap()
remove_file(path).unwrap()

10
10 4 54
10

size asks the file rather than measuring it. It was a seek to the end and back — four calls to answer one question — because the alternative was fstat, and struct stat is laid out differently by each platform’s headers: a program transcribing one holds numbers nothing checks, and being wrong about them reads the wrong bytes rather than failing. A shim beside the module reads the header and one field crosses, so the refusal costs nothing here any more. It never moves the position, which is why tell still reports 10 afterwards — where the seek version moved it and put it back, leaving it at the end of the file if anything failed in between.

Where there is no shim, the seek is still what runs. sysl.fs requires os rather than posix, so it reaches a Windows target that has no per-OS directory here — and fseek/ftell are ISO C, so that path goes on working exactly as it did.

size_of(path) is the same question without an open file in hand; it opens, asks, and closes, so a missing file answers NotFound rather than zero — the distinction a caller sizing a buffer needs and the one a bare number could not carry.

Closing, and using a file after it

import sysl.fs.{create, remove_file}
import sysl.io.Reader

var path = "/tmp/sysl-fs-doc-5.txt"
var f = create(path).unwrap()

f.close().unwrap()

print(f.closed(), f.at_end())
print(f.close().is_ok())
print(f.seek(0).unwrap_err(), f.seek(0).unwrap_err().code())

var window: [4]u8
var got = f.read(window)

print(got.len, f.failed())

remove_file(path).unwrap()

true true
true
the file is not open 9
0 true

Four rules are in that output.

Closing is the program’s to do, and defer f.close() is how it is written. Dropping a File without closing it leaks the handle until the program exits, the same as in C.

A destructor is the other way to arrange it, and File deliberately does not have one: a destructor runs for a value held behind a &T, so giving File one would mean a heap box per open file and would take the choice away from a program that would rather not have one. What a destructor is for is the resource that dies where no defer can be written — inside a container, inside a struct inside a container — and a handle a function opens and closes is not that.

close is idempotent, and the second call is not merely tolerated — it is the case defer creates. A function that closes on one path and defers the close for the others reaches the end having done both.

Every other member checks the flag first, and none of them may skip it. fclose releases the handle, so the pointer the struct holds afterwards names storage C has freed; reaching it would be a use-after-free rather than a call that fails. What comes back instead is NotOpen, which is EBADF — the code the operating system reports for the same mistake made one layer down.

A read on a closed file latches rather than answering quietly empty. An empty read means end of input, and a program told that would conclude it had read the whole file when what it had done was close it too early. So got.len is 0 and failed() is true, and the two together are the truth.

A failure from close is a real one, incidentally: the flush it performs is where a full disk finally reports. A program that cares about its output checks the close and not only the writes.

A File is a struct and therefore a value, so passing one to a function makes a second File. It holds its state behind a &FileState rather than holding the pointer directly, and that is what makes close answerable at all: every copy shares one state, so closing either is closing the file, and closing it twice is harmless rather than a use-after-free. A value type holding the pointer would have made that mistake easy.

The path tier

import sysl.fs.{write_text, exists, is_file, is_dir, readable, writable, rename, remove_file, size_of}

var a = "/tmp/sysl-fs-doc-6a.txt"
var b = "/tmp/sysl-fs-doc-6b.txt"

write_text(a, "x").unwrap()

print(exists(a), is_file(a), is_dir(a), readable(a), writable(a))
print(is_dir("/tmp"), is_file("/tmp"))

rename(a, b).unwrap()

print(exists(a), exists(b), size_of(b).unwrap())

remove_file(b).unwrap()

print(exists(b), remove_file(b).unwrap_err())

true true false true true
true false
false true 1
false no such file or directory

exists answers false for a path that exists under a directory the program may not search, which is the one way it differs from the question it looks like it is asking. That case cannot be told from absence without a second call whose answer would already be stale — and every caller that matters, one about to open the file, gets the truth from the open.

is_dir asks by opening the path as a directory. DIR * is opaque, so it needs nothing about the platform beyond two symbols, which is what makes it the one question about a path’s kind the module can answer honestly. is_file is then “exists and is not a directory” — a device or a socket answers true, which is right for what callers use it for: whether opening it as a file could work.

remove_file refuses a directory rather than removing it. It is unlink, where C’s own remove quietly does either; two names for two intentions is what lets a program that meant one of them find out it had the other. remove_dir is rmdir and needs the directory empty, reporting DirectoryNotEmpty — the one code in the whole set whose number the two platforms disagree about, which is why it is read through a call rather than written as a literal.

rename replaces whatever was at the destination, is one operation as far as anything watching is concerned when both paths are on the same filesystem, and fails rather than copying when they are not. That is rename(2)‘s contract and worth knowing, since a program moving a file across devices has to read and write it itself.

make_dir makes one directory and needs its parent to be there. Making a chain is a loop over path separators, and where a separator is is a question about paths rather than about the filesystem — which this module does not answer. It asks for 0o777, letting the process umask narrow it: asking for less would override the environment’s decision rather than defer to it.

Listing a directory

import sysl.fs.{entries, make_dir, write_text, remove_file, remove_dir}

var dir = "/tmp/sysl-fs-doc-entries"

remove_dir(dir)          // in case an earlier run of this page left it behind
make_dir(dir).unwrap()
write_text(dir + "/one.txt", "a").unwrap()
write_text(dir + "/two.txt", "b").unwrap()

var names = entries(dir).unwrap()

print(names.len())
print(names.at(0) == "one.txt" || names.at(0) == "two.txt")

remove_file(dir + "/one.txt").unwrap()
remove_file(dir + "/two.txt").unwrap()
remove_dir(dir).unwrap()

print(entries(dir).unwrap_err())

2
true
no such file or directory

. and .. are left out, because every caller drops them: a program listing a directory is asking what is in it, and a recursive walk that forgets the filter does not terminate. The order is the filesystem’s — not sorted, and not stable between two listings of one directory. A program that wants an order applies one.

A name that is not UTF-8 stops the program, exactly as read_text does with a file’s contents and for the same reason: answering with an error would put a case in IoError that no filesystem ever reports. POSIX names are bytes, so this is reachable rather than theoretical.

This is the one thing in the module answered by C rather than by a bare extern. readdir hands back a struct dirent whose name field sits at an offset the two platforms disagree about, which is the transcription the rest of the module refuses — so a four-line shim returns the char * and nothing in sysl learns the layout. It sits in a __<os>__ directory (modules), which is what keeps it off a target with no directories to list.

What is absent, and why

Anything stat would answer — timestamps, ownership, a mode — for the reason size is a seek.

The rule the whole module is written under is one sentence: a question that can be answered by a call whose signature is all there is to get right is answered here, and one that cannot is absent. No C structure is transcribed. One header is included, in the shim behind entries, which is the shape the rest of this list should take as it shrinks: a question C can answer in three lines is answered by C, and one that would need a structure transcribed into sysl is still not answered at all. Where that leaves a gap, an extern of one’s own — or a .c of one’s own — is the honest way across it, and foreign functions is where that is written up.

Argument types

import sysl.fs.write_text

write_text("/tmp/sysl-fs-doc-x.txt", 42)

'text' of 'sysl.fs.write_text' is string, but int was given

import sysl.fs.write_bytes

write_bytes("/tmp/sysl-fs-doc-x.txt", "text")

'bytes' of 'sysl.fs.write_bytes' is []const byte, but string was given

write_bytes wants bytes and s.bytes is how a string supplies them — free, since a string already is a validated []u8. write_text is the same call with that step written in.

And every one of these answers with a Result, which has to be opened before the file inside it is:

import sysl.fs.open

var f = open("/tmp/sysl-fs-doc-x.txt")

f.close()

type 'sysl$Result' has no method 'close'

? inside a function that returns a Result, or unwrap() in a program that would rather stop, are the two ways through. Errors and contracts has the rest.

Next: sysl.math — the float functions, and the integer traits.

Coming from C

2026-08-16T01:26:07.924728867Z

Most of C comes across unchanged. You still choose where a value lives, you still have a pointer, you still have sizeof, and there is still no runtime underneath deciding things for you. What changes is a short list, and this page is that list — read it and the tour will mostly be confirming what you already expected.

The map

C	sysl
`int`, `char`, `unsigned`	`int`, `byte`, `uint`	a width is a type; nothing promotes
`T *`	`*T`	the same pointer, spelled so you can grep for it
`malloc` / `free`	`&T`	construct where a `&T` is expected; the count frees it
`T a[N]`	`[N]T`	a fixed array — it converts to a view, and the length comes with it
a `T *` plus a length	`[]T`	one value that carries the length
`const T *`	`[]const T`	the read-only-ness is in the type and travels with it
`char *`	`string`	validated UTF-8, with a length, and no terminator
`struct`	`struct`	the same thing
a `union` and a tag beside it	`enum`	one construct, and the arms are checked
`typedef`	`type`, or `c type`	`type` narrows or renames a scalar; a bare alias is refused. `c type` is for a typedef in a header, whose width the C compiler answers for
`#define MAX 512`	`const MAX: usize = 512`	folded into every use, no storage, usable as an array bound
`static` at file scope	`private`
a header	a module	no `#include`, no include guard, no forward declaration
`NULL`	`null`	on a `*T` and nowhere else
`errno`, a returned `-1`	`Result[T, E]` and `?`
`assert.h`	`assert`, and `require` / `ensure`
`printf`	`print`, and `f"…"`
a function pointer	`*extern(A) -> R`
`sizeof`, `_Alignof`, `offsetof`	`sizeof`, `alignof`, `offsetof`	over any type
`volatile T *`	`volatile` on the field	the storage is qualified, not the pointer to it
`goto`	a labelled `break` / `continue`

The allocation is a construction

There is no malloc and no free, and no keyword took their place. Writing an ordinary construction where a &T is expected is what puts the object on the heap:

struct Node
    value: int
    next: weak Node
end Node

var head: &Node = Node(1, None)

print(head.value)

Node(1, None) is the same expression that would have built a value; the annotation &Node is what makes it a heap object with a count. When the last reference goes, so does the object — there is no line to write and no line you can forget to write.

weak Node is the other half of the same story, and it is the field a C programmer will reach for without thinking. A parent pointer, a back-link, an entry in an index: in C those are just pointers, and the reason they work is that they do not own. weak is that, said out loud — it does not keep the object alive, and reading it is a question rather than an assumption.

An array converts, and the length comes with it

In C, an array in an expression becomes a pointer to its first element and the length is gone — which is why every C function taking a buffer takes a count beside it, and why the two can disagree. sysl has the same convenience and none of the loss: an array converts where a view is asked for, and what it converts to carries the length.

var buf: [4]int

buf[0] = 10
buf[1] = 20

var view: []int = buf

print(view.len, view[1])

4 20

[4]int is the storage; []int is a view of it — three words rather than one: owner, pointer, length. So a function that takes a buffer takes one parameter, and the call reads as it does in C:

zero(xs: []int)
    for i in 0..<xs.len do xs[i] = 0

var a = [1, 2, 3]

zero(a)

print(a[0], a[2], a.len)

0 0 3

a is still a [3]int, and zero cannot be told a wrong length because it was not told one. The explicit a[..] writes the same conversion; what you reach for it for is part of the array rather than all of it — a[1..], a[..<2].

Every index through a view is bounds-checked against the length it carries. That is the one cost sysl adds here, and it buys the class of bug C’s decay makes unfindable.

Widths are types, and nothing promotes

C’s usual arithmetic conversions are absent. byte arithmetic is byte arithmetic:

var small: byte = 200

print(small + 100, int(small) + 100)

44 300

The first wraps at 256 because both operands are byte; the second is int arithmetic because the conversion was written. Neither happened by accident, and no rule about ranks or signedness has to be recalled to predict which one you got. Values has the family, which is open — u12 and i5 are types you may write.

A string is not a `char *`

var s = "héllo"

print(s.len, s.chars.count())

6 5

Six bytes and five characters, and the difference is the point: a string is UTF-8 that has been validated, and it carries its length rather than ending at a NUL. s.len is bytes because that is what indexing and slicing are in; s.chars walks scalar values. There is no cheap byte that is also a character, so the two are never confused.

When you need C’s shape at a boundary, cstring(s) builds one — a terminator and a pointer, for passing to a C function. Strings has both directions.

A tagged union is one construct

enum Shape
    Circle(r: real)
    Square(side: real)
end Shape

area(s: Shape) -> real = s match
    Circle(r)  -> r * r
    Square(a)  -> a * a

print(area(Circle(2.0)), area(Square(3.0)))

4 9

In C this is a struct holding a tag and a union, and nothing checks that the tag you branched on is the member you read. Here the tag and the payload are one value, the payload is reachable only through the arm that established it, and a match missing an arm is a compile error rather than a silent fall-through. Circle(2.0) constructs — there is no Shape. to write, because a variant name belongs to its enum.

The pointer is still there

*T is C’s pointer with C’s rules, and it is deliberately the ugly one to write:

struct Node
    value: int
    next: weak Node
end Node

var p: *int = null

print(p == null, sizeof(int), sizeof(Node), alignof(u64))

true 4 16 8

null belongs to *T alone. Selection through one is ordinary — p.field is C’s p->field, with no operator of its own to remember — and it is unchecked, exactly as it is in C. That is what a raw pointer is for: it is how you talk to hardware, to a foreign library, and to memory you are managing yourself, and the compiler stays out of it.

sizeof and alignof take any type, not just a name, and answer with what the target actually lays out.

Two refusals worth meeting early

A reference is never null, so there is no failure to test for:

struct Point
    x: int
    y: int
end Point

var r: &Point = null
print(r.x)

a &Point always points at a live object — an absent one is Option[&Point]

That is the whole trade: C’s T * answers two questions at once — where is it and is there one — and sysl splits them. &T is the first, Option[&T] is both, and *T is still there for when you want C’s answer.

Nor does a reference do arithmetic:

struct Point
    x: int
    y: int
end Point

var p: &Point = Point(1, 2)
var q = p + 1
print(q.x)

'+' needs matching types, got &Point and int

Walking memory is a *T‘s job, and a []T is what you want nine times out of ten — it is the pointer-and-length pair C makes you carry by hand, with the bounds check that pair was always for.

What C has and sysl does not

A static inside a function. There is no per-function persistent storage, and there is no module-level var either — modules has why the keyword is taken. State that outlives a call goes in a struct the caller owns and passes in, which is what a C program ends up doing anyway the first time it needs two of anything.
An untagged union. A union whose discriminant lives somewhere else has no spelling. Where the discriminant is real, an enum is it; where the point is reinterpreting bytes, that is ptr_cast and it is in memory.
A bitfield declarator. There is no unsigned x : 5, and nothing is missing by its absence: inside a @packed struct a u5 field already occupies exactly five bits, so a width is written where every other width is. What sysl adds is that the two things C leaves to the implementation — which end the bits fill from, and whether one may cross a byte — are fixed by the language. volatile unsigned x : 3 carries over as well, and means what it means in C: a volatile access of the container, so a write is a read-modify-write of it. attributes has the rules.
goto. Not even a reserved word. A labelled break or continue reaches the case that actually comes up, which is leaving a nested loop.
The preprocessor. No macros, no textual inclusion, no include guards. const covers a #define of a value, a module covers a header, and #if covers platform gating — attributes has the closed set of symbols it may test.

What sysl checks that C does not

Every index against a length. Every match for a missing arm. Every numeric conversion, because none of those is implicit — a value never changes width on its own, whatever the surrounding expression wants. Every contract you write with require and ensure, in every build: there is no release mode that drops them, and no flag that strips a bounds check either. And a reference that is counted rather than freed by hand, which is the one that turns a class of bug into a class of question you no longer have to ask.

What is implicit is a different kind of thing, and none of it loses information. An ordinary construction becomes a &T where one is expected, a &x becomes a trait object where one is expected, an array form written where a []T is wanted makes storage of its own, and a []T is accepted where a []const T is wanted — the direction that takes a permission away, never the one that grants it. Each of those adds an owner or removes a licence. None of them changes a value’s width, which is the implicit conversion C actually has and the one this page is about.

You do not have to start over

A language is adopted a file at a time or not at all, and both directions across the boundary are open.

sysl on top, your C underneath. An extern declares a symbol the linker already has, and @link("z") names the library that resolves it. Nothing is generated and no header is parsed — you write the declarations you use and no more, and one nothing calls costs the output nothing. A .c file dropped in any module of the tree is compiled with it, which is how the parts a header hides — a macro, a sizeof only the header knows, an untagged union — get reached at all.

Your C on top, sysl underneath. @export publishes a plain, unmangled symbol, entered under your machine’s C convention — so a struct crosses it by value exactly as it does one of your own functions — and sysl build-c writes a static archive and a C header for your existing build to consume:

module mylib

@export("mylib_add")
add(a: i32, b: i32) -> i32 = a + b

$ sysl build-c mylib -o libmylib.a
wrote libmylib.a
wrote libmylib.a.h

#include "libmylib.a.h"

int main(void) { return mylib_add(2, 3); }

$ clang main.c libmylib.a -o app

The exported signatures are the C-shaped ones — scalars, pointers, function pointers — because that is what a C prototype can say. What you write is a boundary file: one module whose job is the surface, holding the handful of functions the C side calls, with everything behind it written in whatever shapes sysl prefers. That is the same facade a C++ or Rust library grows for the same reason, and the FFI reference has the whole of what may cross.

Next: the tour, which starts from the beginning and does not assume you read this.

Your first program

2026-08-16T01:26:07.924728867Z

Put this in hello.sysl, anywhere you like:

print("Hello, sysl!")

var width = 6
var height = 7
print("area =", width * height)

Run it:

sysl run hello.sysl

(From a source checkout instead of an installed binary, that is sbt "syslJVM/run run hello.sysl".)

Hello, sysl!
area = 42

What is not there

No main. No imports. No class wrapped around the statements to give them somewhere to live. A sysl file is a module, and statements written at its top level run in order — so the smallest program is the code you actually meant to write.

A main is available when you want one, and you want one as soon as you care about the program’s arguments:

main(args: []string)
    print("started as:", args[0])
    print(args.len - 1, "argument(s) given")

print came from sysl, the standard module — the one module a file may write the names of without importing it, because it holds what the language desugars onto. It takes any number of arguments, converts each one to text, and separates them with spaces.

What the compiler did

run is one command of several, and it did four things in a row: parsed and checked the source, emitted textual LLVM IR, handed that to clang to assemble and link against the standard library archive, and ran the binary that came out. The binary is real — there is no interpreter and no VM underneath it.

build stops after producing that binary instead of running it, and test runs the @test functions in a directory. The tour uses run throughout.

Where to go next

The tour starts here and builds up. It is meant to be read in order, and every program in it is one you can paste into a file and run.

The command line is the other direction: the rest of the subcommands, the flags they share, and what each one leaves as an exit status. Nothing in the tour needs it.

fft

2026-08-16T01:26:07.924728867Z

The discrete Fourier transform, twice: the O(n log n) one everybody uses and the O(n²) one that is the definition.

Having both is the point. The fast transform is a rearrangement of the slow one, and a rearrangement is exactly the kind of thing that can be subtly wrong and still produce plausible numbers — so the slow one is kept as the thing to compare against. Published values then anchor the pair, since two implementations by the same author agreeing proves only that they agree.

The axis: an algorithm checked against its own definition. Every other program in the set is checked against values somebody else wrote down, and this one is too — but it also carries the thing it is supposed to be equal to, and runs it. A spot check accepts a plausible number; the definition does not.

The complex arithmetic used to be this program’s own, and is now sysl.math.complex. That is the ordinary end of a guide program’s life: it was written here because there was nothing to import, the friction it turned up is what moved the language, and once the type existed there was no reason for a second copy of it. Nothing in the language knows what a complex number is — the operator traits are still the whole mechanism, and the program still leans on them hardest.

What it found

The width of an integer type is askable, and the first draft said it was not. This is a finding that got retracted, which is worth as much as one that stands. The header originally recorded that the machine word width could not be obtained at a type parameter; it can — count_ones() + count_zeros() is the width by construction, at whatever Self turned out to be. That is what sysl.math means by keeping the second of that pair rather than leaving it to a subtraction, and it means nothing has to hard-code 64.

What actually stops the closed form is the empty shift. Bits.reverse_bits reverses the whole width, so bit-reversing an index would be v.reverse_bits() >> (w - bits) — and a one-sample transform reaches that with bits at zero, since bit_width(1) is trailing_zeros(1), which is zero. A shift by the full width is the case the instruction does not define, so the loop stays.

That is the more useful shape of finding: not “the language cannot express this” but “the language expresses it and the machine has an edge case”, which no amount of language design removes.

A trait written for somebody else’s type has to find a name that is still free. What survived the move to the library is sum — the generic total that starts at a value the type promised rather than at xs[0], which is what keeps an empty sequence from needing an Option in the signature. The trait behind it wanted a zero() -> Self, and could not have one: a trait’s members become the implementing type’s, and Complex already declares a zero. So the member is called identity, for what it is rather than for the value it answers. The more ordinary the concept, the likelier that collision is — and there is no way to name the member the trait means apart from the name it goes under.

Source · Next: sha2 — one algorithm at two widths.

The foreign interface

2026-08-16T01:26:07.924728867Z

sysl has no functions built into the compiler that a program could not have written. Option and Result are library enums, unwrap is a library member, print is library sysl reached by a desugaring. The one thing a program genuinely cannot write for itself is the first call out of sysl — into libc on a hosted target, into a driver primitive on a bare one.

extern is that seam, and nothing more. It is a declaration form rather than a set of names the compiler knows, which is why the whole of this page is about declaring what is on the other side and almost nothing about what is there.

`extern` — a declaration with no body

extern abs(n: int) -> int
extern strlen(s: *u8) -> usize
extern memcpy(dst: *u8, src: *u8, n: usize) -> *u8

print(abs(-5), abs(7))

5 7

It is a function header, and the absence of a body is the whole difference. Everything downstream is the ordinary path: a call is checked against the declared signature, its arity is checked, and it lowers to an ordinary call. The result type is optional and absent means unit, exactly as for a function.

Four rules follow from having no body:

Externs live in the one function namespace, so an extern and a function cannot share a name.
An extern is never generic. There is no body to monomorphize.
The escape analysis assumes the worst of it — every argument may be kept, and the result may view any of them — because nothing can tell whether the foreign side held on to what it was handed.
A declaration nothing calls is not emitted at all, so declaring more of a C library than a program uses costs nothing.

The namespace rule is the one that surprises, because the name a program uses is ordinarily the symbol:

extern abs(n: int) -> int

abs(n: int) -> int = n

'abs' is already declared as an 'extern', which this would overload — what tells overloads of an 'extern' apart is the symbol each names, and a sysl function declares no symbol

Where a program wants that name for itself, the link name below is what separates the two.

extern f() -> never is how a program says the callee does not come back, which is what makes the exit path of a panic ordinary sysl rather than a compiler intrinsic.

An `extern` also declares a variable

Written name: type. What follows the name is what says which of the two a declaration is — a parameter list makes it a function, a type makes it storage:

extern optind: i32
extern environ: **u8

print(optind)

It is here because a C library’s interface is not only its calls. stdout, stderr and stdin are variables, and half of stdio.h is reached through them; so are environ, optarg, optind, tzname and sys_errlist. Where C also offers a getter there is a way round — errno is __error() on Darwin, and an ordinary extern reaches that — but stdout has none that is the same object, since fdopen(1, "w") is a different FILE with its own buffer and interleaves wrongly with anything already writing to the real one. environ has no way round at all.

The type is written and never inferred. There is no initializer to infer it from, and what the other side laid down is not something this compiler can see. Writing the wrong one is the same kind of promise a wrong parameter list is. The one type refused is one that occupies nothing, because a symbol is an address and a value with no representation has nothing to put one at:

extern nothing: unit

print(1)

'nothing' cannot be an 'extern' variable: a unit value occupies nothing, so there is no storage for the linker to resolve the name to

It is a place, and a writable one — the one respect in which it is unlike every other global the language has. A module-level val is read-only at every depth and counts nothing, because it owns what it names for the whole run and promises never to change it. An extern variable owns nothing and promises nothing: the storage is C’s, C writes it, and optind = 1 before a getopt loop is ordinary use of the interface being reached. The type rule does not carry over either — a val is refused a &T because nothing would ever release it, and an extern variable may name whatever the other side laid down, because releasing it was never this program’s job.

Naming the symbol separately

A string before the name is what the linker resolves; the identifier after it is what the program calls it by:

extern "abs" magnitude(n: int) -> int
extern "abs" absolute(n: int) -> int

print(magnitude(-3), absolute(-4))

3 4

Without one the two are the same, which is the common case and stays the default. The separation exists because a symbol’s spelling belongs to whoever exported it: it may be shaped nothing like sysl, it may be a name the program wants for something of its own, and — the case that forced it — a declaration in the library would otherwise spend that name out of every program’s namespace. The standard library renders integers and floats through snprintf, and a program that declares snprintf itself must not collide with it.

The case where nothing else would do at all is a header macro. What C calls stdout is a #define, and the symbol behind it is __stdoutp on Darwin and stdout elsewhere — so extern "__stdoutp" stdout: *u8 is the only declaration that reaches it, and a transcription of the header’s spelling would reach nothing.

The symbol must be one a linker could resolve — letters, digits, _, $, .:

extern "not a symbol!" weird(n: int) -> int

print(weird(1))

'not a symbol!' is not a symbol a linker can resolve

Two declarations may share one symbol under different sysl names, as above; a module declares each symbol once. A link name is an extern‘s alone — a sysl function is defined here, and what it is called is its name.

Note what this does not do: nothing here changes what a sysl function’s own symbol is. It is the name, unmangled, so a program that defines abs collides with libc’s whatever else it declares.

A link name in the `llvm.` namespace names an instruction

extern "llvm.sqrt" root(x: f64) -> f64
extern "llvm.sqrt" rootf(x: f32) -> f32

print(root(9.0), rootf(4.0))

3 2

The two kinds of extern differ only in who resolves them — the linker, or the back end — and that needs no keyword to say which, because LLVM owns that namespace: a module defining a symbol beginning llvm. is invalid IR, so no library can export one and a link name there cannot mean anything else.

The width is derived, not written. LLVM overloads an intrinsic on its operand type and spells the choice in the name — llvm.sqrt.f64, llvm.sqrt.f32 — so a declaration stating the whole thing would say the width twice and let the two disagree. What is written is the base; the suffix comes from the signature, which is why the pair above is one name at two widths.

The set is closed, and the reason is not caution about the feature. An intrinsic’s signature belongs to LLVM and moves between releases, and a declaration that disagrees is not a link error — it is a verifier failure at best and a miscompile at worst, reported against generated IR rather than against a line someone wrote. So the compiler holds the list it supports and checks each declaration against it:

extern "llvm.nosuchthing" bogus(x: f64) -> f64

print(bogus(1.0))

'llvm.nosuchthing' is not an intrinsic sysl supports — it has llvm.ceil, llvm.copysign, llvm.fabs, llvm.floor, llvm.round, llvm.sqrt, llvm.trunc

What it is for is not only speed. An intrinsic that lowers to an instruction leaves no symbol behind, so the operation needs no library at the link — which is what lets the standard module’s roots, magnitudes, sign transfers and roundings work on a freestanding target, where there is no libm to ask. Where the machine has no instruction there is nothing to gain: llvm.sin exists and lowers to a call to the same sin an ordinary extern names, so the transcendentals stay linked.

What crosses the boundary

A scalar or a *T matches C directly. A string or a &T is a sysl layout C has no notion of, and handing one over is the same kind of promise *T already is — what crosses is the programmer’s business. The usual move is to convert:

import sysl.text.cstring

extern strlen(s: *u8) -> usize

var cs = cstring("hello")

print(strlen(cs.ptr))

cstring copies the text into the NUL-terminated shape C reads and owns that copy, which is how a language with no manual free says who frees it.

What crosses by value is not the programmer’s business. A struct, a tuple, a view, an enum — every aggregate — is handed over in whichever registers the machine’s C convention names, which is not the same as the registers a sysl-to-sysl call would use and is not what LLVM does with an aggregate left to itself. So a foreign declaration is emitted in the coerced types that convention asks for, and the call converts each value into and out of them. The shape a program wrote is unchanged, nothing about it is visible in a program, and nothing about it applies to a struct handed over behind a *T.

A vector is the one shape that does not cross, in either direction. Which register a <4>f32 arrives in differs by target and by which instruction-set extensions the other side was compiled with — the same C source built with and without -mavx2 does not agree — so there is no convention to emit against and sysl declines to guess at one. Guessing would not fail to link: it would produce a call that resolves and corrupts its arguments, which is the failure a boundary check exists to prevent.

extern "process_lanes" process(v: <4>f32) -> unit

how a vector reaches a C function differs by target

Pass the lanes through memory instead — a *f32 and a count, which is what C’s own SIMD-taking functions take and what has one meaning on both sides.

A scalar narrower than a register is not quite free either. A u8 is a byte to both languages, so there is nothing to coerce — but it travels in a register a whole word wide, and most conventions require whoever hands it over to widen it to fill one first. Sysl writes that widening where the convention asks for it: on an argument at the call, and on the result of every function it defines, so that a bool answered to a C caller is a bool rather than one bit beside thirty-one undefined ones. Which values are widened, and whether by sign or by zero, is the target’s answer rather than the language’s — AArch64 outside Darwin widens nothing at all, Windows widens only bool, and RISC-V 64 widens a 32-bit value even when it is unsigned. As with the coercion above, none of it is visible in a program; it is worth stating because it is the part of the boundary a reader is likeliest to assume away.

extern implies C’s convention and says nothing about any other. The one case that needs something else is a function the processor enters rather than a caller, and that is a property of a definition rather than of a foreign declaration — see interrupt below.

Several `extern`s may share a name

Two externs of one name are two functions exactly when they name two symbols. A C library’s naming is not sysl’s, and a family C spells _solid/_shaded/_blended is one operation with an option — which a binding may say directly, rather than inventing a sysl name per C symbol:

extern "strlen" size(s: *u8) -> usize
extern "strnlen" size(s: *u8, cap: usize) -> usize

Which one a call means is decided by its arguments, exactly as for any other overloaded name. Two declarations naming the same symbol are refused: that is one C function claimed at two signatures, and the symbol is what gets emitted, so both calls would reach the same code with different arguments. Where that is genuinely wanted — a void * interface used at several types — it is written where a reader can see it, by taking the address and casting it.

An extern and a sysl function do not overload each other, in either order: what tells overloads of an extern apart is the symbol each names, and a sysl function declares none.

`@export` — a definition C can call

@export is extern read the other way. An extern names a symbol the linker has and states the signature the other side published; an @export publishes a symbol and states the signature C may call it at. They are spelled alike because they are one mechanism pointing in two directions:

extern exit(code: int) -> never

@export
add(a: i32, b: i32) -> i32 = a + b

A sysl definition ordinarily carries its module path into its symbol, so two modules may each declare an init without colliding. @export publishes a bare, unmangled name beside it — one a C declaration can spell and a C linker can resolve.

Naming the symbol

@export("mylib_add") publishes it under that name instead, which is the same rename extern offers on the importing side:

module mylib

@export("mylib_add")
add(a: i32, b: i32) -> i32 = a + b

This is the form a real C API wants rather than a convenience. A C library’s symbols share a prefix so that linking two of them is not a coin toss, and the sysl side has a module path doing that job already. add is the name to write inside sysl and mylib_add is the name to publish; requiring the function to be called mylib_add everywhere inside would be spelling the module path twice. A sysl caller is unaffected — it goes on naming mylib.add, and reaches the definition rather than the published symbol.

@export implies C’s convention and says nothing about any other, which is extern‘s rule read the other way.

The published symbol is an entry, not a renamed definition

A rename is not a convention, and the difference is the whole of what @export is for. The exported symbol is a function of its own: its signature is what the machine’s C convention says, and it reassembles each argument into the shape sysl’s own lowering expects before calling the definition. The definition keeps its mangled name and its own lowering.

None of that is anything to write, and it is worth knowing for three reasons:

an aggregate may cross, which is the type rule below;
&f on an exported function is that entry’s address, so a C library may be handed the callback it asks for — which is what A function’s address below turns on;
a sysl caller pays nothing for it, since the conversion is only on the path C takes.

It is the foreign call path read backwards: a call out to C classifies each argument by the convention and puts it in the registers named, and an entry in classifies the same way and reads it back. One classifier answers both directions, so what a binding calls and what it exports cannot disagree about the same struct.

What an exported function may be

The boundary is a facade: one file whose job is the export surface, where the signatures are written to be C-shaped on purpose. That is what makes the list below cost so little — every refusal fires inside a file somebody wrote for this, where the restriction is the point rather than a surprise.

refused	because
a generic	an exported symbol is one function at one signature, so there is no way to say which instantiation the linker holds
a member	C has no receiver to hand it. The grammar refuses this before any rule here is reached, and says so in as many words: a member takes no annotation at all (attributes), so `@test` and `@pure` are as unavailable on a method
a `private` definition	`private` gives the symbol internal linkage, which promises every caller is inside the module; an export promises the opposite
a `@ghost`	it is erased before there is a symbol at all
a `@test`	only `sysl test` builds one, and an export has to be in the artifact a C project links
a variadic	what a C caller promotes into the tail is decided by the prototype it compiled against, not by this declaration. Take a `va_list` parameter, which says the same thing and is what C’s own `v` variants do
a symbol that is not a C identifier	there would be nothing a C declaration could spell

The types are the interesting rule, and it asks what C can declare. A scalar, a *T and a function pointer cross as themselves. So does a struct built out of those, and a simple enum, which is its underlying integer and nothing else — the exported symbol is an entry lowered under the machine’s C convention, so an aggregate is handed over where C looks for it.

What is refused is what C has no declaration for whatever convention is applied: a slice or a string, which is two words with a length in the second; a &T or a weak, which is a counted box whose header C would have to know the layout of; a trait object, which is a value and a method table together; a data enum, which is a tag beside a union sysl laid out rather than the shape a C union has; and a bare array as a parameter or result, which C decays to a pointer and has no by-value prototype for.

module mylib

@export
sum(xs: []i32) -> i32 = 0

'xs' of the exported 'mylib.sum' is []int, which C has no way to spell — an exported function takes an integer, a float, a 'bool', a 'char', a pointer, a function pointer, a simple enum, or a struct built out of those. A slice is an address and a length, so C takes them as two parameters — a pointer and a 'usize' — which is the shape its own string and buffer functions already have

An aggregate is asked about its fields, which is what keeps those two lists apart: a struct of scalars is a struct C declares, and a struct with a &T in it is a counted box with a coat on. The refusal names the field, since the declaration being read does not mention it:

module mylib

struct Node
    x: i32

struct P
    x: i32
    n: &Node

@export
f(p: P) -> i32 = p.x

'n' of mylib.P is &mylib.Node, which is what C has no declaration for — the aggregate around it is fine

Recurring is also why nothing here says who owns what: every type reaching the boundary is plain data, so no count crosses it in either direction.

Every refusal names the shape to write instead, because there always is one — a slice becomes the pointer and length C’s own buffer functions already take, an array becomes a struct holding it. That is what makes the boundary writable rather than merely restricted.

Module storage a C caller cannot fill

Module storage is filled before a program’s own statements run, and a C project supplies its own main — so nothing sysl emitted runs before the C side calls in. An exported function that reached storage a computed initializer would have written would read whatever the loader left, so it is refused, and the walk is transitive:

module mylib

counter() -> i32 = 7

val start: i32 = counter()

@export
begin() -> i32 = start

'mylib.begin' is exported and reaches 'mylib.start', which is module storage an initializer fills before the program's own statements run. A C project linking this supplies its own 'main', so nothing fills it and the function would read whatever the loader left. A module 'val' whose initializer is constant data is laid straight into the object file and is fine here — it is a computed one that has nowhere to be computed

A val whose initializer is constant data is fine, because nothing runs to fill it — the constant is written straight into the object file. That is the rule C already has for a static-storage initializer, which is why this bites so rarely:

module mylib

val start: i32 = 7

@export
begin() -> i32 = start

A const has no storage at all and never arises.

What the compiler hands the C project

sysl build-c writes a static archive and a C header beside it:

$ sysl build-c mylib -o libmylib.a
wrote libmylib.a
wrote libmylib.a.h

The header is a translation of the exported signatures and holds no decisions of its own:

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

int32_t mylib_add(int32_t a, int32_t b);

#ifdef __cplusplus
}
#endif

It uses <stdint.h>‘s fixed-width names because sysl’s integers say what they are where C’s say what they are at least: an i32 is int32_t, and writing it int would be right on every machine anyone is likely to use and wrong as a claim. A char is a Unicode scalar value and becomes uint32_t, never C’s char, which would be wrong by a factor of four. The header assumes C99, or any C++, which is what those three includes already needed.

The one fact a type name cannot carry across is divergence, since never and unit both spell as void. A function returning never is therefore annotated:

#ifndef SYSL_NORETURN
#if defined(__cplusplus) && __cplusplus >= 201103L
#define SYSL_NORETURN [[noreturn]]
#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
#define SYSL_NORETURN _Noreturn
#else
#define SYSL_NORETURN
#endif
#endif

SYSL_NORETURN void mylib_spin(void);

A macro rather than the keyword, because the header serves both languages and _Noreturn is not valid C++; an older compiler gets the empty definition, which is a weaker declaration rather than one it refuses. The block appears only in a header that has something diverging in it. What it buys the caller is real: code after the call is dead, and a path ending in it needs no return value.

Naming a struct in the header

A struct an exported signature reaches is defined in the header as well as named, since a prototype mentioning an Id is useless to a consumer that has not been told what one is. Left alone its name is derived from the module path — mylib_Id here, and sh_sysl_box2d_c_Id in a package — which makes it the one name in the file nobody chose. @export above the struct chooses it, exactly as it names a function’s symbol:

module mylib

@export("mylib_vec2")
struct Vec2
    x: i32
    y: i32

@export("mylib_add_vec")
add(a: Vec2, b: Vec2) -> Vec2 = Vec2(a.x + b.x, a.y + b.y)

val v = add(Vec2(1, 2), Vec2(10, 20))

print(v.x, v.y)

11 22

A sysl caller is unaffected by either name, exactly as it is by a function’s symbol — it goes on writing Vec2 and add. What the two attributes decide is what the header says:

typedef struct {
    int32_t x;
    int32_t y;
} mylib_vec2;

mylib_vec2 mylib_add_vec(mylib_vec2 a, mylib_vec2 b);

Written bare, @export gives the typedef the declared name — Vec2 — which is the reading it already has on a function. It composes with @packed and @align(n), which are three facts about one struct, and it is what a binding mirroring a C library wants: that library’s own type names rather than tidier derived ones.

The derived name was buying uniqueness and a chosen one is a claim, so the claim is checked. Two things in one header answering to one name are refused — and a function’s symbol counts, because at file scope C puts a typedef name and a function name in one namespace where sysl has two:

module mylib

@export("handle")
struct H
    x: i32

@export("handle")
make(n: i32) -> H = H(n)

'handle' is the C name of the function 'mylib.make' and the type 'mylib.H' — a header declares both in one namespace

A generic struct is refused for the reason a generic function is, one step shorter: every instantiation is a struct of its own, so one written name would be claimed by all of them at once.

module mylib

@export("Box")
struct Box[T]
    v: T

a header names one type at one shape, so 'mylib.Box' cannot be generic

A private struct is refused too, and not for the reason a private definition is — a typedef has no linkage to contradict. The visibility rule gets there first: a public declaration may not name a type less visible than itself and an export is public, so a private struct appears in no signature a header carries and there is no name in one for it to take.

module mylib

@export("mylib_id")
private struct Id
    index1: i32

'mylib.Id' is private, so no exported function may name it — an export is public

The chosen name reaches the header and nothing else. The emitted aggregate keeps its mangled name, and C links nothing on a type name — which is what makes this a spelling an author may decide rather than a fact anything else depends on.

From there it is an ordinary C build:

$ clang main.c libmylib.a -o app

The archive is self-contained. Whatever of the standard library the module reaches is compiled into it, because a .syslib is not something a C link line can be handed — an archive referring to one would fail at that link naming a sysl$ symbol its author has no way to place. So --std-lib is refused here and --no-std-lib asks for what already happens. The cost, which is accepted: two build-c archives linked into one program each carry the part of the library they reach.

What the archive does not hold is what the sysl side’s own libraries supply — libm, and whatever @link named — and build-c says which those are rather than leaving them to be found at that link. Those are libraries the author chose and can hand to a linker, which is exactly the distinction the standard module fails.

sysl emit-header prints the same declarations without building anything, for a project that generates its headers as a build step.

What a dependency’s module contributes

A module a dependency supplied contributes to your build only where your program reaches that module. In your own tree the four attributes below mean what they say and nothing qualifies them: each is a root of the reachability walk, which is what lets a build-c compilation — with no entry point at all — keep anything.

A dependency is different because a package’s source root is compiled whole rather than by what you import, so every module of every --lib root and every fetched package is in the compilation whether or not you named it. For an ordinary declaration that costs nothing, since pruning drops what no body reaches. These four are the declarations no body reaches, so without this rule an unimported module’s contribution landed in your build anyway:

in a module you never reach	what it used to cost you
an `@export`	its symbol in your archive
an `interrupt` handler	a handler in your vector table
a `@section` definition	bytes in your image, marked so that nothing removes them
a destructor	a function nothing can call

The rule is about where the declaration came from rather than about which attribute it carries, and that is what makes it hold. A kind left unconditional would keep whatever else the same function carries — an export that is also placed, or that is also a handler, would survive for the second reason and land its symbol anyway.

What that cost was a package carrying its own program. A binding whose tests have to run on real hardware writes them as an application with an @export("main"), and inside the package that handed every consumer a second main:

$ nm -g probe.a
0000000000000008 T _main              <- yours
0000000000000000 T _main              <- the package's test application

Reaching is asked of the module graph, so an import counts as readily as a call, and it follows the graph out — a package you reach through another package is reached. It is deliberately coarser than the walk over function bodies: a module holding nothing but an exported C entry point has no function anything calls, and a rule asking whether you called something there would drop exactly the case an export exists for.

If a package wants a symbol, a handler or a placed definition published regardless, it puts it in a module its consumers import. Each is a claim about what your image contains, and an image that never reaches the module has not asked for it. That reading is at its strongest where the attributes matter most: a vector table slot and a RAM-resident .ramfunc region are the scarcest things on the parts they exist for, so gaining every unimported module’s silently is the worse way to be wrong.

`@link` — which library resolves the externs

@link("z") in a file’s header names a library the linker must be given, and it sits beside the externs it supports because that is the only place that knows. An extern states the symbol it wants and never where the symbol lives; a binding to libpng is written by whoever writes the module, and the driver cannot carry a list of libraries it has never heard of.

module image.png
@link("png")
@link("z")

extern "png_create_read_struct" create(ver: *u8, err: *u8, fn: *u8) -> *u8

A directive names a library, and never a flag. That is the whole of the design. Where a library lives is a property of the machine being built for: the mathematics is a file of its own on ELF, part of libSystem on Darwin, inside the CRT on Windows, and absent from a freestanding target that has no libc for it to be in. A directive spelling -lm would be right on one of those and wrong on the other three — and the author could not be told so by any compiler running on the machine that wrote it, because the link that fails is somewhere else. So the file names m, and the driver decides what that becomes:

the target	what a name becomes	why
has the library separately	`-lname`	the ordinary case, and what every unrecognized name gets
already links what holds it	nothing	Darwin’s `libSystem`, Windows’ CRT — the driver passes those unasked
does not have it at all	nothing	a freestanding build has no libc, so nothing can be passed for one

The last two both put nothing on the command line and are still written apart, because they are different facts and a target added to the registry has to answer them separately. A freestanding program that then calls sqrt fails at the link naming sqrt, which is the honest report: what is missing is the function, and no -l would have supplied it.

The set the compiler knows is deliberately small — the C runtime and the mathematics, the two whose placement actually differs. An unrecognized name is passed straight through rather than guessed about. Being wrong in that direction produces a link error naming the library; being wrong in the other produces one naming a function, on a platform the author does not have.

Four more rules:

The requirement travels in the artifact. The clauses are part of the tree a .syslib carries, so a program depending on a prebuilt library learns to pass -lz without reading that library’s source. Leaving them out would mean a binding that works from source and stops working the moment it ships — the worst available shape, since the build that breaks is one its author never ran.
A module’s requirement is the union of its files’, and its files are not held to agreeing. This is where the directive differs from a capability clause, which it is otherwise shaped like: a capability describes what the whole module may do, so files that disagreed would be describing different modules, where a link requirement describes what one file’s externs need.
Order is kept rather than sorted. A static archive is scanned once, left to right, and a member is pulled in only to resolve a symbol already undefined — so a library that calls into another has to come first: -lpng -lz, never the reverse. Sorting would decide it by spelling, which is right by accident for those two and wrong for the next pair.
@link is an annotation, not grammar — so link is an ordinary identifier and a program may still declare a function or a field called it. That is the general rule for everything the file header carries: an annotation’s name is read as an identifier, which is what keeps alloc, no, requires and link out of the reserved list. See attributes.

Where the library is, where its headers are, and what they are configured with

@link says which library. Where it lives on a particular machine is not the module’s to know, and neither is what the surrounding project builds its headers with, so those are three flags on the command line rather than three more directives:


`--include-path <dir>`	where to look for a header the C beside a module includes
`--include-path <name>=<dir>`	the same, and it answers the header requirement a package declared under that name
`-D NAME` or `-D NAME=value`	a macro that C is compiled with
`--link-path <dir>`	where to look for the library `@link` named

They fail in that order, and the first two fail before anything reaches a linker. A binding to a library a package manager put outside the toolchain’s prefix needs the paths; a module joining an existing C project — an SDK, a firmware build — needs the macros as well, because a header found is not a header that compiles. pico-sdk’s pico/cyw43_arch.h #errors on a build that has not said which architecture variant it means, which is the shape to expect rather than a curiosity.

Nothing is guessed at. sysl does not add /opt/homebrew/lib and does not invent a macro: a compiler ruling on where a platform keeps its libraries, or on how a project configures its headers, would be wrong on a machine its author cannot reach, and the cost of being wrong is a build that fails somewhere else. A build system that already knows these has them — from CMake, the target’s INCLUDE_DIRECTORIES and COMPILE_DEFINITIONS.

A package may say which headers it needs, though never where they are. A --include-path written as <name>=<dir> answers a requirement the package declared under that name, so a build missing one stops before clang runs and names the package rather than a header the reader has never heard of. The declaration goes in package.hocon — see packages.

A function’s address — `*extern(A, B) -> R`

Fn is sysl’s answer to “what is the type of a callable”, and it is the right one for sysl: a bound where the callable is passed down, a boxed object where it is kept, and in both cases something with an environment beside it. C has no notion of an environment. What a C interface means by a function pointer is one word holding the address of code.

That matters for more than a corner: qsort and bsearch take a comparison, signal and sigaction take a handler, atexit takes a hook, pthread_create takes a thread body, scandir takes a filter, and every library with a _set_callback in it takes one of these.

extern qsort(base: *u8, n: usize, size: usize, cmp: *extern(*u8, *u8) -> i32)

compare(a: *u8, b: *u8) -> i32
    var pa: *i32 = ptr_cast(a)
    var pb: *i32 = ptr_cast(b)

    *pa - *pb

var xs = [30, 10, 20]

qsort(ptr_cast(&xs[0]), 3, 4, &compare)

print(xs[0], xs[1], xs[2])

10 20 30

&f is the address, and the & is the same one the memory model gives every other address. A bare f keeps its ordinary meaning — the capture-free closure — because a spelling that meant a sysl callable in one slot and a C address in another would be choosing silently between two representations that share nothing.

The function may be named through its module, and &f[T] may be qualified too. Under import shapes, &shapes.less is the same address &less gives under import shapes.less — a name means the declaration rather than a spelling of it, which is the rule a constant follows as well. A local binding shadows a module name, so where the head of the path is bound to a value the chain is an ordinary field read and the & addresses that field.

It is its own type rather than a mode over the call trait. *Fn(A) -> R was already taken, and by the right thing: an unowned trait object over a callable, two words, a method table beside the value. Spelling both the same would put a fat pointer where C reads one word, and the mistake would be invisible. So the three are three:

written	what it is	width
`A -> R` at a parameter	a bound over `Fn`, monomorphized and inlined	nothing
`&Fn(A) -> R`	a heap-boxed callable, counted	two words
`*extern(A) -> R`	the address of code compiled to C’s convention	one word

It is also not *T of anything. A raw pointer addresses a value — one that can be read through, written through, and measured — and there is no value at the end of this one, so every operation *T carries would have needed an exception. What an address of code can do is the one thing it is for: be called, and be handed to whoever asked for it.

Three consequences:

A call through one goes out under C’s convention, because that is what the type said was at the other end. Nothing checks that the signature is the one the code at that address was compiled with; that is the promise the * announces, and it is the same promise every raw pointer makes.
ptr_cast reaches between an address of code and an address of bytes, which is how a *u8 from dlsym becomes callable and how one goes back to a C interface that stores callbacks as void *.
null is a *extern, since “there is no callback, use the default” is a state several C interfaces have, and two compare by address so a program can ask whether one is installed:

compare(a: *u8, b: *u8) -> i32 = 0

var installed: *extern(*u8, *u8) -> i32 = null

print(installed == null, &compare == null)

true false

A generic function’s address — the instantiation is read off the type

A generic function is a body per set of type arguments, so an address needs them settled. The expected type settles them, by the same unification a call site uses on its arguments:

extern qsort(base: *u8, n: usize, size: usize, cmp: *extern(*u8, *u8) -> i32)

ascending[T](a: *T, b: *T) -> i32
    var pa: *i32 = ptr_cast(a)
    var pb: *i32 = ptr_cast(b)
    *pa - *pb

var xs = [30, 10, 20]

qsort(ptr_cast(&xs[0]), 3, 4, &ascending)
print(xs[0], xs[1], xs[2])

10 20 30

A comparison written once over *T is now usable at every element type, where before a program needed a concrete copy of it per type.

The `void *userdata` pattern — the arguments are written

A C interface that calls back pairs the pointer with an untyped void *, so a trampoline for one has the signature C fixed — (*u8, Event) -> bool. The state type appears nowhere in it, so nothing in the expected type can settle it, and no annotation written anywhere else could supply it either. The arguments are written where the address is taken, and this is the one position in the language that takes them:

extern qsort(base: *u8, n: usize, size: usize, cmp: *extern(*u8, *u8) -> i32)

compare[T: Ord](a: *u8, b: *u8) -> i32
    var x: *T = ptr_cast(a)
    var y: *T = ptr_cast(b)

    if *x < *y then -1 else if *y < *x then 1 else 0

var xs: [3]i32 = [30, 10, 20]

qsort(ptr_cast(&xs[0]), 3, 4, &compare[i32])
print(xs[0], xs[1], xs[2])

10 20 30

Recovering the state is still a ptr_cast from *u8, which is a promise rather than a deduction — that is C’s shape and nothing here changes it. What is no longer needed is the shape the language was forcing: a trampoline written over *T because it could not be written over *u8, a second ptr_cast of the function pointer, and a val whose only job was to be somewhere to put the type. qsort is written the new way.

More than one argument is written the same way, &f[A, B], and a value parameter takes its place in the list like any other.

&f[T] and &xs[i] are the same shape, and the analyzer is what separates them: the name has to resolve to a function declaration with no local shadowing it. A local shadowing the name keeps the ordinary indexed reading, so a subscript is never re-read as a feature its author did not reach for.

What the brackets can hold is the expression grammar’s reading of a type — a name, a qualified name, a name applied to arguments, *T, &T, a tuple, and an integer for a value parameter. A slice, a weak, a volatile and a callable have no spelling there; the annotated val reaches every one of them, and the diagnostic says so.

What has no address, and why

Each of these is refused because the address would not be an address of what its type says, and nothing downstream could notice.

A generic function with nothing to say which copy — the arguments have to come from somewhere, and a bare var says nothing:

id[T](x: T) -> T = x

var a = &id

print(1)

nothing here says what they are

A type parameter the signature never mentions, left to be inferred — nothing in the expected type can settle it, and the message names the form that can:

tagged[T](n: i32) -> i32 = n

val f: *extern(i32) -> i32 = &tagged

print(1)

does not say what 'T' should be

Written out, &tagged[i32], it is an ordinary address — that is the case the written form exists for.

A variadic function — C reads a tail relative to the last named argument, and a *extern states the arguments a call passes:

varia(n: int, ...) -> int = n

var b = &varia

print(1)

'varia' is variadic, and a '*extern' fixes the arguments a call passes — a tail has no width a signature could state, so a variadic function is reached by calling it

A nested function — its environment is the frame it was declared in, and what would have to travel beside the address is that frame. A closure is the same reason with the name taken off. A @test function is dropped by every build but sysl test, so its address would be of a definition the program does not have:

outer() -> int
    inner(x: int) -> int = x + 1

    var q = &inner

    inner(1)

print(outer())

'inner' is a nested function, so it has no address to take — what would have to travel beside the address is the frame it reads, and a '*extern' is one word. A top-level function is what has an address

An intrinsic — there is no body for an address to name:

extern "llvm.sqrt" root(x: f64) -> f64

var p = &root

print(1)

'root' is an intrinsic, which the back end lowers to an instruction rather than a function anything calls — there is no body for an address to name. A sysl function that calls it is what has one

A plain sysl function whose signature carries an aggregate — a struct, a tuple, a data enum, a view, a string:

struct Pair
    a: int
    b: int

agg(p: Pair) -> int = p.a

var c = &agg

print(1)

the 1st parameter of 'agg' is Pair, an aggregate, and an aggregate crosses to C in whichever registers that machine's convention names rather than the ones a sysl call uses

The test is made by shape rather than by asking the target’s classification, so a program accepted for one machine is accepted for every machine.

Two kinds of function are past the aggregate question

They were once refused by it, and that cost a binding every callback a C library asks it to register — those signatures are written in aggregates almost without exception.

An extern is C. sysl neither compiled it nor chose its convention, and its type is what the declaration transcribed from the header, so there is no lowering here to be wrong about:

struct Pair
    a: int
    b: int

extern "c_sum" c_sum(p: Pair) -> int
extern "c_take" c_take(f: *extern(Pair) -> int) -> int

print(c_take(&c_sum))

A function carrying @export has a C-convention entry, and its address is that entry’s. So the answer to the refusal above is to mark the function rather than to hand-write a wrapper around it:

struct Pair
    a: int
    b: int

@export("c_sum")
sum(p: Pair) -> int = p.a + p.b

extern "c_take" c_take(f: *extern(Pair) -> int) -> int

print(c_take(&sum))

A plain sysl function is what is left, and there the refusal stands: it has no C-convention entry to point at, and an address that is quietly wrong is worse than no address.

What it costs today

A signature cannot be named once. Every declaration mentioning a callback spells the whole of it, and a real binding mentions one several times — signal takes a handler and returns the previous one, so its declaration says the same eight tokens twice. This is not the foreign interface’s restriction: type declares a constrained subtype, whose base must be a scalar, so a name for a pointer type is refused in the same words:

type Handle = *u8

print(1)

a constrained subtype's base must be an integer, a float, or 'char', not *byte

What would fix it is an alias that is not a subtype.

Variadic functions

C’s ellipsis is the one arity in the language a declaration does not fix, and it exists for one reason: printf, snprintf, execl, open — the calls every C library reserves for a variable tail — cannot be declared at all without it.

extern printf(fmt: *u8, ...) -> int
extern snprintf(buf: *u8, n: usize, fmt: *u8, ...) -> int

print(1)

A sysl function may have one too, and the rules for what may go in the tail are shared, so a caller need not know whether the callee it is reaching is foreign:

sum(n: int, ...) -> int
    var ap: va_list

    va_start(ap)

    var total = 0

    for i in 0..<n do total += va_arg(ap)

    va_end(ap)

    total

print(sum(3, 10, 20, 30))

Why it is here at all. C can do this, so sysl must: a capability C has and sysl lacks is a place sysl cannot be used, and sysl exists to be used where C is. The concrete cases are the ones every C codebase has — a logging or formatting function whose arity is the caller’s business, and a function that must be callable from C at a variadic signature, or hand a tail onward to one.

The calling side

The ellipsis follows the named parameters, and there must be at least one, because C reads a variadic call’s tail relative to the last named argument. f(...) is not a callable declaration in any C either:

extern nothing(...) -> int

print(1)

'nothing' needs at least one named parameter before '...'

A call is checked against the declared parameters exactly as any other call is — the ellipsis excuses nothing that comes before it, arity included, and the escape analysis still assumes the callee keeps every argument. What the ellipsis governs is only what follows:

Only what C varargs can carry may go in the tail — an integer, a float, a char, or a raw pointer. What is refused there and not at a declared parameter is a bool: C would promote it to int, and sysl has no conversion that says so, so there is nothing to promote it with:

extern printf(fmt: *u8, ...) -> int

print(printf(null, true))

a bool cannot be passed to '...' — a variadic argument must be an integer, a float, a char, or a raw pointer

A tail argument is passed already widened, by C’s default argument promotions: an integer narrower than 32 bits becomes i32 or u32 following its own signedness, and an f16 or f32 becomes f64. This is not something the ABI can be left to do — LLVM promotes nothing on its own, and a narrow value handed over as written is read back out of the wrong number of bytes. The widening is part of the call.

An aggregate is the one place a sysl tail is narrower than a foreign one. A struct, an enum, a tuple or a view crosses to a foreign callee under exactly the classification a declared parameter of that type gets, which is what C does with one as well. It does not cross to a sysl one, because there it is the callee’s own walk that reads the tail back, and the walk reads one register at a time:

struct Pair
    a: int
    b: int

take(n: int, ...) -> int = n

print(take(1, Pair(1, 2)))

a Pair cannot be passed to a sysl function's '...' — a walk over the tail reads back one register at a time and an aggregate is not one, where a foreign callee takes it because C says which registers it arrives in

The refusal says which callee it is about rather than calling the argument unsuitable, since the same argument is fine one call away.

The receiving side — C’s, spelled sysl’s way

form	is
`va_list`	a predeclared type, like `int` and `never` — not a struct a program could have written, because its layout is the target ABI’s
`va_start(ap)`	readies it. C also names the last fixed parameter here; sysl does not, because the function already knows which parameter that is and repeating it is a chance to get it wrong
`va_arg(ap)`	takes the next argument and advances
`va_end(ap)`	finishes with it
`va_copy(dst, src)`	starts `dst` where `src` has reached, so a tail can be walked twice

These five are language forms, not library functions, in the same category as sizeof: each is an ABI primitive that no sysl body could implement, so there is nothing to put in the library. That is the line the “no functions built into the compiler” rule actually draws — no program could write va_arg.

va_arg reads its type from context, or from the brackets. C writes the type as a second argument, which is not a thing a sysl expression can hold; here it comes from the place the value is read into — var v: int = va_arg(ap), total += va_arg(ap), take(va_arg(ap)) — the same place None and Ok(5) get theirs. Where a reader would rather say it at the form, va_arg[int](ap) is the written type-argument list at a special form, and it is what a bare print(va_arg[int](ap)) needs. Where neither says, the form is refused rather than guessed at:

walk(n: int, ...) -> int
    var ap: va_list

    va_start(ap)

    print(va_arg(ap))

    va_end(ap)

    n

print(walk(1, 2))

'va_arg' reads the next argument as some type, and nothing here says which — annotate the variable it is read into

Handing a walk on

C’s other half of this is vprintf: a function receives the tail, does not read it itself, and passes it to somebody who does. The parameter type is *va_list, and the call writes &ap:

report(n: int, ap: *va_list) -> int
    var total = 0

    for i in 0..<n do total += va_arg(ap)

    total

relay(n: int, ...) -> int
    var ap: va_list

    va_start(ap)

    var t = report(n, &ap)

    va_end(ap)

    t

print(relay(2, 4, 5))

A bare va_list parameter is refused, and the by-value parameter rule is why — a copy of a walk is not a walk:

borrow(ap: va_list) -> int = 0

print(borrow(1))

a va_list is a parameter as '*va_list', not as 'va_list' — a parameter is a by-value binding, and a copy of a walk advances nothing 'borrow''s caller can see, so the walk is handed over by address and the call writes '&ap'

Two things follow, and both are the point. The borrower advances the lender’s own list, so what it consumed is gone when the lender reads on — which is what va_copy is for, exactly as in C. And va_start still asks for a tail of the function’s own while va_arg asks only for a walk, so a borrower reads a tail without having one.

Returning a va_list is refused outright, foreign or not:

give() -> va_list
    var ap: va_list

    ap

print(1)

a va_list cannot be returned from 'give' — the type names the storage a walk lives in, and there is no value of it to hand back

A *va_list is an ordinary raw pointer and is refused nowhere — it may be returned, held in a field, or carried in a struct, under the memory model’s rules and nobody else’s.

An extern is written in C’s spellings and takes either. A foreign declaration transcribes a C header, so it says what the header says: va_list is C’s by-value parameter, the one vprintf takes, and *va_list is C’s va_list *. The refusal above is about a sysl body, which could do nothing with a copy of a walk; a foreign body is C’s, and C’s vprintf is precisely a body that reads one.

extern vprintf(fmt: *u8, ap: va_list) -> i32

log(fmt: *u8, ...) -> i32
    var ap: va_list

    va_start(ap)

    var n = vprintf(fmt, &ap)

    va_end(ap)

    n

print(1)

The call writes &ap for either spelling, because the address is the only thing sysl has and it is what both are formed from. What actually crosses for the by-value one is a target question: C’s va_list is a different type on every machine and is passed three different ways — the value in the storage on Darwin arm64, the storage’s own address on x86-64 System V, the address of a fresh copy on AAPCS64. All three pass one pointer, so the difference cannot be recovered from the emitted types; the compiler reads it off the target it was told to build for.

Where an ellipsis may go

A member is a function with a receiver in front, so a ... reaches one under exactly these rules. The receiver is a parameter once the member is lowered, and it is therefore what a tail anchors on — so only(self, ...) is a complete declaration, while a receiverless make(...) has nothing named before its ellipsis and is refused exactly as f(...) is. The same holds for an associated function, a member of a generic type, a member with type parameters of its own, and a nested function, whose environment holds the first parameter slot the way a receiver does.

A trait may declare one, and an implementation must agree about it: a ... is part of what a caller may write, so having one where the trait has none is a different promise rather than a wider one. What such a trait cannot be is a trait object. A call to a variadic names the callee’s whole function type — that is how it says where the declared parameters stop — and a slot in a method table is a word that names none. A bound still reaches the method, because that call knows which function it is reaching.

It is as unsafe as C’s

Nothing checks that the callee asks for the types the caller passed, or that it stops at the right count; va_arg past the end reads whatever is there. The tail carries no type information, so there is nothing to check against. This is the one place in sysl where getting it wrong is undiagnosed — which is why a safe variadic (a homogeneous ...T collected into a slice, or a heterogeneous ...&Show over trait objects) is worth adding beside it later, never instead of it.

`opaque` — withholding a layout

opaque struct Name is known by shape only inside the module that declares it. Everywhere else the type is incomplete — exactly what C’s struct foo; is — and the only thing that may be said about it is *Name.

module net

opaque struct Conn
    fd: int
    live: bool

open() -> *Conn
close(c: *Conn)

One rule, because two different wants meet in it. A library stabilizing its surface wants to add and reorder fields with nothing downstream recompiled. A binding wants *sqlite3 to be a type a *u8 cannot be mistaken for, where nobody in sysl knows the layout at all. Both are “the shape is not yours to know”.

So an opaque struct may declare no body at all, which is the C-handle case:

import sysl.text.cstring

opaque struct Dir

extern "opendir" c_opendir(path: *u8) -> *Dir
extern "closedir" c_closedir(d: *Dir) -> int

var d = c_opendir(cstring("/tmp").ptr)

print(c_closedir(d))

Nothing in sysl lays a Dir out; the storage is libc’s. An ordinary struct with no body stays an error, and says which word to add.

What is refused outside the declaring module is one list: a binding, a field of another type, an element, an array, a slice, a &, a type argument, a by-value parameter or result, construction, reading or writing a field, a pattern naming the fields, a dereference, sizeof, alignof, offsetof, and a by-value self method. Every one of them needs a size or an offset, which is the single fact being withheld, so they are one diagnostic rather than fifteen.

The by-value self method is the case worth stating outright, because it looks like a call and is not. The function was compiled by the library; what crosses the boundary is the caller’s copy, laid out to the fields as they stood when that caller was built. Adding a field would then break it silently — precisely the failure the modifier exists to prevent. *self and &self need no shape and stay reachable, which is what makes them the forms an opaque type’s methods take.

The reach is the declaring module exactly, not a subtree the way private[M] widens. What opaque buys is that a field may move with nothing downstream recompiled, and the set of files that must recompile together is the module — its files share one scope, so they are already one unit for this, and a submodule is already not.

It is not a visibility, and the two are independent. Visibility decides who may say the name; opaque decides who may know the shape. A public type may be opaque, which is the whole point of one; a private type may be opaque too, and simply has nobody left to be opaque to.

Codegen needs nothing for it — pointers lower to ptr, so a *Opaque downstream never asks for the aggregate, and the check is entirely a front-end rule.

`interrupt` — a definition the processor enters

interrupt before a definition says the processor enters it, not a caller. It is written where a visibility modifier is, on the declaration rather than folded into extern, because it is about a definition — the handler is code this program supplies.

interrupt timer()               // RISC-V: takes nothing
interrupt(supervisor) trap()    // ...at a named privilege level

interrupt fault(f: *Frame)      // x86-64: the ABI requires the frame

One concept, three answers, every one of them read off clang rather than out of a document:

processor	what `interrupt` is	the signature it demands
x86-64	an LLVM calling convention, `x86_intrcc`	a pointer to the frame the hardware pushed, optionally then an integer error code
RISC-V	a function attribute, `"interrupt"="machine"`	nothing at all
AArch64	it does not exist — a handler is assembly	—
Arm M-profile (`thumb`)	it does not exist — a handler is an ordinary function	—
CRAFT (`craft`)	it does not exist — one vector, and the kernel decodes `cause`	—

So the annotation names the concept and the back end decides what that becomes. A directive spelling x86_intrcc would put one machine’s answer in a source file and be wrong on the other two — the same shape as @link naming a library rather than a flag, and the same reason.

On a processor without it, the annotation is refused rather than ignored:

interrupt timer()
    print("tick")

'interrupt' is not something aarch64 has: its exception entry goes through a vector table of fixed-size instruction slots, so a handler is assembly and there is nothing here for a convention to describe

Clang answers __attribute__((interrupt)) on AArch64 with “unknown attribute ignored” and compiles an ordinary function. That is defensible for C, where an attribute is advisory by tradition. It is not defensible here: the handler would then return with ret where the machine needs eret, having saved none of the registers an asynchronous entry clobbers, so the failure is silent and arrives as corruption in whatever was interrupted.

AArch64’s absence is not an oversight to fill in later. Its exception entry goes through a vector table the processor indexes by cause, where each entry is a fixed-size slot of instructions — so the entry point is assembly by construction, and there is nothing for a convention on a sysl function to describe.

M-profile’s absence is a different absence, and the refusal says which one it is. Every thumb target is Armv6-M, Armv7-M or Armv8-M, and there an exception is entered with xPSR, PC, LR, R12 and R3–R0 already stacked by the hardware and EXC_RETURN in the link register — so a plain function returning normally is a correct handler, and the vector table holds its address rather than its code. Nothing is needed, which is why nothing is accepted:

interrupt systick()
    ()

'interrupt' is not something thumb has: a Cortex-M exception is entered with the caller-saved registers already stacked by the processor and 'EXC_RETURN' in the link register, so an ordinary function is already a correct handler and there is no prologue for a convention to arrange — write one, and give it the name the vector table holds with '@export("SysTick_Handler")'

So a Cortex-M handler is an ordinary function named for the vector table with @export, which is already a reachability root — the symbol survives pruning and carries the name the table was built against, which is the whole of what a handler needs there.

Three more rules:

A handler is an entry point, so it is a root of the reachability walk, and calling one is refused outright: it leaves through a return-from-interrupt that would unwind a frame the call never pushed. A walk starting from what the program runs therefore cannot reach it, and dropping it would leave the vector table pointing at nothing. Its address is still worth taking, which is what fills that table.
The rules are about the signature, so they are checked on the declaration rather than while a body is walked. A generic handler nothing instantiates has no body analyzed at all, and it is exactly as wrong as one that does.
interrupt is a soft keyword, and what keeps it one is that a name must follow it. Three things start with that word and only the first is a convention: interrupt timer() declares a handler, interrupt(n: int) -> int declares a function called interrupt, and interrupt(4) calls one.

Nothing about this is portable, and the design does not pretend otherwise. An interrupt handler is the least portable code there is — it is entered by a mechanism the processor defines, and even the number of arguments differs. What the compiler owes is that the source says which machine it is for, and that building it for another fails loudly.

A library may carry C

A .c file dropped in any module of a library’s tree is compiled with it and archived beside it. Nothing declares it and nothing lists it: the build already walks every directory, and a C file found in one that holds source is compiled for the same target and becomes one more member of the .syslib. The sysl side reaches it through the extern that was already the way to name a symbol the linker has — so the language gains nothing, and the whole of the feature is in the build.

A module, and not merely a directory. A project is not the only thing that writes into its own tree: cmake -B build puts a build directory inside it and fills that with generated C meant for another compiler. A directory holding no sysl was never a module, so its C was never the tree’s and the build passes it by — while still descending through it, because a module may sit any depth below a directory holding nothing itself. The tree’s own root is the exception, since the root is the tree rather than a directory in it: a package namespaced by reverse DNS has its modules at sh/sysl/foo/ and nothing at the top, so C belonging to no single module goes there.

What this costs is a vendored C library laid out in sub-directories of its own: the ones holding no sysl are skipped, and a link error naming the symbols is what says so. Put the .sysl that declares those externs in the directory and it is a module — which is where every binding written so far has put it anyway.

A shim can be per-operating-system, and that is a directory rather than a condition. A .c cannot carry a sysl attribute, so #if is no help to it; what selects it is where it sits. A directory named __<os>__ selects source for one operating system and names nothing (modules), so the file belongs to the module holding the folder and is absent everywhere else:

sysl/fs/path.sysl              module sysl.fs, on every target
sysl/fs/__macos__/dirent.c     compiled on macOS
sysl/fs/__linux__/dirent.c     compiled on Linux

The standard library is the worked example. sysl.fs.entries lists a directory, which means reading a struct dirent — a shape whose name field sits at an offset the platforms disagree about, and exactly the transcription the table below refuses. Four lines of C answer it. The folder is what keeps that file off a freestanding target, where <dirent.h> does not exist and sysl.fs is still compiled: the library is compiled whole for every target, so a shim it could not compile everywhere had nowhere to live until the folder existed.

It exists because a binding to a real C library cannot be written without it. Three things are reachable from C and from nothing else, and each blocks an ordinary POSIX interface:

what	why `extern` cannot reach it
a caller-allocated opaque type	`regcomp` wants a `regex_t` the caller supplies, and its size is 32 bytes on Darwin and 64 under glibc. A program can only allocate storage whose size it knows
a macro	`REG_EXTENDED`, `O_RDONLY`, `SIGKILL` are `#define`s. They have no symbol, so there is nothing for a linker to resolve and nothing for `extern` to name
a shape with no sysl spelling	an untagged union, an inline function, and a C bitfield struct — sysl lays an `iN` field out in exactly N bits inside `@packed` (attributes), but C leaves its allocation to the implementation, so the two need not agree on a size and a shim is what settles it

Each becomes an ordinary function in three lines of C:

size_t sysl_regex_t_size(void)  { return sizeof(regex_t); }
int    sysl_reg_extended(void)  { return REG_EXTENDED; }

Better still, a shim that allocates the opaque type hands back a pointer and the sysl side never learns the size at all.

The alternative is transcription, and transcription is silently wrong. A hand-written struct regex_t carrying one platform’s header fields compiles everywhere and is correct on one machine. Nothing checks it — sysl’s own sizeof would report what sysl laid out, not what C did, so even that comparison is a tautology. Getting it wrong writes past the end of the caller’s storage. The number has to come from the headers, and C is what reads headers.

Three build rules:

A member is named after the path it was found at, directories included — demo/util.c becomes demo.util.o. A basename alone would not do: ar r replaces by name, so two modules each holding a util.c would have the second evict the first, and the library would ship missing whatever only the first defined.
The C files are fingerprinted with the sysl ones. A library’s shims are as much its source as its modules are, and an artifact that did not change when one was edited is a stale artifact nothing would notice was stale.
Cross-compiling a library that includes headers needs that target’s headers. That is not a cost the design imposes — it is the requirement being honest: a binding to POSIX regex cannot be built for a platform whose regex_t nobody can see. C that includes nothing cross-compiles like any other object. A __<os>__ directory is how a library carries both: the standard library does include a header, in a folder no freestanding build ever looks in, so it goes on building for every target the toolchain can lower for — and the file that would not compile there is not skipped by a rule about headers, it is simply not part of that build.

`c const` — a value only the C compiler can work out

A shim answers for a function, and it does not answer for a value. A constant reached through a call is not a constant: it has no value until the program runs, so it cannot size an array, cannot stand in a match arm, cannot be folded into a bound and cannot be checked by @assert. The macro row above still holds for REG_EXTENDED as an argument, and stops holding the moment the number has to be known while compiling — which is where a statically allocated FreeRTOS task lives, being a [sizeof(StaticTask_t)]u8 the caller supplies.

A c const block is a constant whose value the C compiler works out, for the target being built for. The right-hand sides are C, in quotes:

@include("<limits.h>")

c const
    BITS: u32 = "CHAR_BIT"
    WIDEST: usize = "sizeof(long long)"

print(str(BITS) + " " + str(WIDEST))

8 8

@include is a header clause like @link, written the way C writes it — "<limits.h>" reaches a system header and "qcbor.h" one beside the module, which is the same choice a C file makes. Where the headers are and what they are configured with is --include-path and --define‘s answer, exactly as it is for a shim. No name from the header becomes visible in sysl: a type still arrives by opaque struct and a function by extern, and what the block buys is only that the expressions compile.

Which is what the motivating case looks like written out:

@include("FreeRTOS.h")

c const
    STATIC_TASK_SIZE: usize = "sizeof(StaticTask_t)"
    MAX_DELAY: u32          = "portMAX_DELAY"

var tcb: [STATIC_TASK_SIZE]u8 = [0; STATIC_TASK_SIZE]

The value is measured from a probe translation unit that is compiled and never linked or run — the file’s headers, one global per constant, lowered to IR for the target, and the number read back out of the IR. Nothing executes, so the answer is the target’s rather than the host’s: a pointer measures four bytes building for a Cortex-M and eight building for this machine, with no hardware involved either way.

The c is contextual and stays an ordinary name. Nothing else in the language follows a name with a keyword, so c const cannot be anything but this, and a program counting characters keeps its variable c. The C needs no literal prefix for the same kind of reason: inside the block a string can mean nothing else, so the header marks the language once.

Any C constant expression, and the C compiler is the judge of which those are — which is what makes that an honest claim rather than a subset somebody maintains. An expression it will not settle comes back in its own words:

c const
    N: usize = "atoi(\"3\")"

the C compiler refused this file's 'c const' block

Four more refusals go with it: a header that is not there, a value the declared type cannot hold (naming the value and both ends of the range), a type that is not a number, and a block written inside a body, which has no file’s headers to be compiled against.

A string from C is not written this way. A number is a number in the compiler’s output and reads straight off; a string constant is a block of storage and a different job, and it would have to be written "\"foo\"" — two quotings for one value, which is a form nobody would guess. The refusal says so rather than leaving it to be found.

A float is measured too, and it is the value hand-copying gets wrong

The declared type may be f32 or f64. That a float can be spelled by name is no answer here: a name gives you the width, and what nothing was checking is the value. The case that makes it worth a feature rather than a convenience is the macro written as an expression over other macros — a graphics or physics header is full of them — because copying one of those means doing the arithmetic by hand and writing the answer down.

@include("<float.h>")

c const
    pi:      f32 = "3.14159265359f"
    quarter: f32 = "0.25f * 3.14159265359f"
    eps:     f32 = "FLT_EPSILON"

var one: f32 = 1.0

print(quarter * 4.0 == pi, one + eps > one, one + eps / 2.0 == one)

true true true

FLT_EPSILON is the second reason: it is the definition of the width rather than a number about it, and a transcription with one digit wrong still looks plausible while being the wrong tolerance for every convergence loop that uses it.

Rounding is allowed and silent. Asking for f32 is asking for the nearest f32, which is what C does for float x = M_PI; — refusing it would leave the narrow width unable to read the double-typed macros that are most of them. What is refused is the value going missing: a measurement that is not finite, because the C overflowed while settling it or the macro names an infinity or a NaN, and a finite one the declared width turns into an infinity or into a zero it was not.

c const
    huge: f32 = "1e300"

which 'f32' cannot hold

The widths are f32 and f64, and f16 is refused by name. C writes a constant expression as a float, a double or a long double, so those two are the widths a measurement reads back at without anyone having to guess which was meant.

c const
    h: f16 = "0.5"

'f16' is not a width a 'c const' is measured at

c type below still refuses a float, and that is a different question. A typedef is measured because its width is the configuration’s to decide, and float and double are IEEE binary32 and binary64 on every machine sysl targets — so f32 and f64 by name really are the whole answer there. It is the value that varies, never the width.

The declared type may be a transparent subtype of a number, which is what makes this block and c type below a pair rather than two features. Without new such a type is its base, so a constant declared at one is a constant declared at that base — and a measured type is exactly that shape:

@include("<stdint.h>")

c type
    Tick = "uint32_t"

c const
    forever: Tick = "0xFFFFFFFFul"

wait(ticks: Tick) -> Tick
    ticks

print(str(wait(forever)))

4294967295

That is the case the two blocks exist for: a typedef whose width the configuration decides, and the constants that have to be that width. Spelling the constant usize beside a Tick parameter is a package that stops compiling on a port where the two disagree, which is the version of this mistake that used to ship.

The name is followed against the file’s own declarations — a c type measured beside it, or a type whose base reaches an integer — and a name from anywhere else is refused. A block is one question put to one file’s headers, and a type measured against another file’s is not an answer this one can use.

A within range is checked while compiling, against the number that came back:

type Small = u32 within 0..10

c const
    N: Small = "sizeof(long long) * 100"

does not admit

which is the @assert a program would otherwise write underneath. A where predicate is refused rather than checked — a predicate is a function, checked where a value is made, and a constant is folded into its uses rather than made anywhere — and so is a new type, since reaching one from its base is a written conversion and there is nowhere on the line to write it.

The value does not travel through the C type. C narrows, so (uint8_t)800 is 32; carrying it that way would let a constant that should have been refused arrive looking like one that fits, and the range check is the whole point of having written the type down.

A library ships the measured number, not the expression. The lowering happens before the artifact is written, so a program linking a package needs neither the package’s headers nor a C compiler of its own — and could not honestly be handed the expression anyway, since an artifact is built for one target and re-measuring it elsewhere would answer a different question under the same name.

A file that writes no block costs nothing and never causes a C compiler to be looked for.

A file that says what it needs is not probed where it could not be

A probe is a C compilation, so a file carrying one asks for headers — and a library is built for every target it might be used on. Without a rule here a library could hold no block at all: one module measuring sizeof(regex_t) would fail every freestanding build of every program, including programs that never name it, because there is no <regex.h> for a bare Cortex-M and no reason there should be.

So a file’s blocks are skipped when the file declares @requires on a capability the machine cannot have:

module sysl.posix.regex
@requires(posix)
@include("regex.h")

c const
    REGEX_SIZE: usize = "sizeof(regex_t)"

Built for a freestanding target, no C compiler is asked anything. The module’s header stays and its declarations go, so a program that does reach it is told what it needs rather than being answered with an undefined name:

this reaches 'sysl.posix.regex', which requires 'posix', and this module declared 'no posix'

What is asked is whether the machine can have the capability, not whether the project provides it. package.hocon treats a capability it does not mention as provided, so a freestanding target nominally offers posix — a gate reading that would gate nothing at all. The question here is physical and has one answer per target: an operating system, and POSIX. Whether there is a heap is not asked, because that is an engineering decision about a machine that could have one either way.

A file that requires nothing is measured wherever it is built. Such a file claims to build anywhere, so a header missing there is the file having mis-stated itself — the skip is a rule about files that said what they need, not about which machine is in front of you.

`c type` — a width only the C compiler can work out

A c const can measure sizeof(TickType_t) and cannot use the answer. Nothing turns a constant into the type of a parameter, so a typedef whose width the target or a #define decides could be measured and not spelled — and a binding had to pick one integer and be right by luck.

That is the version of the transcription problem with no symptom. TickType_t is eight bytes for FreeRTOS’s POSIX port, four on a Cortex-M and two under configUSE_16_BIT_TICKS, and every one of them appears in a signature. An extern declaring the wrong one is not a size mismatch anything can see: it links, and then passes garbage in the high half.

A c type block is the type the C compiler says a name is, for the target being built for:

@include("<stddef.h>")

c type
    Size = "size_t"

val n: Size = 41

print(str(n + 1))

A measured type is the integer it was measured as — a second name for it, interchangeable with it, checking nothing of its own — so arithmetic on one needs no cast and an extern written against one is an ordinary declaration:

@include("FreeRTOS.h")

c type
    Tick  = "TickType_t"
    Stack = "configSTACK_DEPTH_TYPE"

extern "vTaskDelay" c_task_delay(ticks: Tick)

Everything c const says holds here: the same contextual c, the same quoting, the same @include headers, the same probe compiled and never run, and the same rule that a library ships the answer rather than the C name. A file writing both blocks asks the C compiler once, since the two are one question rather than a price per line.

A line carries no sysl type, which is the whole difference from a c const line — the type is the answer rather than the question. A program that wants to state a width writes @assert over a c const holding the sizeof, which says the same thing where it can be checked.

A c const declared at a measured type is the other half of the pair, and is written out above. Two blocks in one file are one question, and a binding usually writes both.

A number your program worked out reaches one under the type’s own name

A measured type is a transparent subtype, so a value of the integer it turns out to be flows in and out with no cast at all. What a program has, though, is usually a usize — a sizeof, a slice’s len, or arithmetic over them — and that is a different type from whatever C measured. The conversion is the type’s own name:

@include("<stddef.h>")

c type
    Size = "size_t"

take(n: Size) -> Size = n

var xs: [3]u32 = [0, 0, 0]

print(take(Size(xs.len)) + Size(sizeof(u32)))

That spelling is the only portable one, which is the whole reason it exists: the width is the target’s, so writing u32(xs.len) would be one configuration’s answer copied into the source — the transcription a c type is for abolishing. It is the ordinary case in a binding rather than a corner of one: a queue’s item size and a task’s stack depth are both a number sysl worked out and C has a typedef for.

The conversion is written, and an unwritten one is refused even where the widths happen to agree on the machine in front of you:

@include("<stddef.h>")

c type
    Size = "size_t"

take(n: Size) -> Size = n

var n: usize = 3

print(take(n))

'n' of 'take' is Size, but usize was given

A silent narrowing is exactly what breaks on the target where the typedef is sixteen bits, so it is refused here where it can be seen. The contracts page has the general rule, of which this is one case.

What comes back is a width and a signedness. Three things follow, and each was measured against the C compiler rather than assumed:

an enum is measurable and carries the signedness the C compiler chose for it;
a qualifier needs no special case, so const unsigned short measures as unsigned short;
plain char is asked about rather than assumed, since C leaves its signedness to the implementation — it is signed on an Apple arm64 machine and unsigned on many others.

A _Bool arrives as bool, the one answer that is not an integer and is still given: C means by _Bool what sysl means by bool, and the two already cross as a single unsigned byte.

A type C does not describe as an integer is refused by name:

c type
    Handle = "void *"

is not an integer type

A float, a pointer, a struct and an array each already have an answer here — a float by name, an address as *T, a struct as an opaque struct — and each is better than a same-width integer standing in for it and losing what it was.

What is deliberately absent

absent	instead
an `fn(int) -> int` type for sysl’s own callables	the `Fn` trait; `*extern` exists only where the representation is somebody else’s to choose
a header parser or a binding generator	an `extern` per declaration, and a `.c` shim for what a header hides
a calling convention on an export	open — `@export` implies C’s, and `interrupt` already built the shape a second one would take
a capability gate on an extern	open — an extern reaching libc plausibly needs `os`, and does not yet say so
an alias for a pointer signature	open — what is missing is a type alias that is not a constrained subtype

Both directions now exist. extern calls out of sysl and @export calls into it, which is what an incremental replacement of a C codebase needs: the sysl side can sit underneath an existing C program as readily as on top of an existing C library.

Next: attributes and compile-time.

Expressions and operators

2026-08-16T01:26:07.924728867Z

Almost everything in sysl is an expression. Assignment yields the value assigned, ++ yields a value, and if, match and the loops all yield the branch they took. What is not an expression is a short list — a declaration, a multiple assignment, and defer — and each is named where it comes up rather than left to be discovered.

This page is about how expressions are built and what each operator means. Where an expression is a control-flow form, statements and control flow has the details of the form itself.

Precedence

Loosest at the top, tightest at the bottom. The set is closed: there are no user-defined operator symbols, and no facility to add one.

Prec	Operators	Role	Associativity
1	`=` `+=` `-=` `*=` `/=` `%=` `&=` `\\|=` `^=` `<<=` `>>=`	assignment	right
2	`\\|\\|`	logical or	left
3	`&&`	logical and	left
4	`is`, `is not`	pattern test	non-associative
5	`==` `!=` `<` `>` `<=` `>=`	comparison	chained
6	`..` `..<`	range	non-associative
7	`\\|`	bitwise or	left
8	`^`	bitwise xor	left
9	`&`	bitwise and	left
10	`+` `-`	add, subtract	left
11	`*` `/` `%` `<<` `>>`	multiply, divide, remainder, shift	left
12	`-` `!` `~` `*` `&` `++` `--`	prefix unary	right
13	`[]` `.` `()` `::` `?` `++` `--`	postfix	left

* and & appear at two levels each — prefix at 12 (dereference, address-of) and binary at 11 and 9 (multiply, bitwise and). Position tells them apart, and nothing else has to.

Two deliberate corrections to C

Every level above matches C except two, and both are cases C is now widely held to have gotten wrong.

Bitwise binds tighter than comparison. x & mask == 0 means (x & mask) == 0, which is what it looks like. In C it means x & (mask == 0), the single most-cited precedence bug in the language.

Shift binds like multiplication, at level 11 alongside * / %, rather than looser than addition. A shift is a multiply or divide by a power of two, so it belongs with them. This is Go’s fix, and a deliberate divergence from Rust and Zig toward it.

var x = 0b1100
var mask = 0b0100

print(x & mask == 4)
print(1 + 2 << 3)

true
17

Both of those need parentheses in C, Rust and Zig. The payoff in systems code is that base + index << shift and a << 8 + b group the way they read.

Operands

Both operands of a binary operator have the same type. There is no implicit promotion anywhere, so a mixed-width expression is a diagnostic asking for the conversion rather than a silent widening.

var a: int = 1
var b: long = 2

print(a + b)

'+' needs matching types, got int and long

This includes the shift amount: in x << 2 the literal 2 takes x‘s type by the literal rule, and shifting by a value of some other type is written x << u8(k).

What has arithmetic

Arithmetic is defined on the numeric types and nowhere else. char has equality and ordering and no arithmetic at all; bool has equality, no ordering, and no arithmetic.

Unary - needs a type with a sign, so it is the signed integers and the floats — negating an unsigned value is written as the subtraction it actually is. Unary ~ is defined on every integer type, signed or not.

Integer arithmetic wraps at the declared width; see types. Integer division by zero traps.

Equality reaches further than ordering

== and != are defined wherever < is, and additionally on bool and on the two pointer-shaped modes *T and &T, which compare by address. Ordering on an address is not defined — a bare address has no meaningful one.

The one arithmetic two pointers have is `-`

p - q, between two *Ts of the same pointee, is an isize counting the elements between them — C’s ptrdiff_t, and the inverse of &p[n]. It is the only operator whose result type is neither operand’s.

Nothing else is defined: p + q names no address, p - n is what &p[n] is for, and a counted &T has no arithmetic at all.

Comparison chains

a < b < c is one comparison node, not two comparisons and a bool. It means a < b && b < c, short-circuiting — and a middle operand is evaluated once and compared twice.

bump(n: int) -> int
    print("evaluated", n)
    n

print(0 < bump(5) < 10)
print(9 < bump(5) < bump(6))

evaluated 5
true
evaluated 5
false

The first line calls bump once although its value is compared twice. The second stops at the first comparison that fails, so the bump(6) on its right never runs at all.

A vector comparison is not a chain

Comparing two vectors yields a mask rather than a bool, and a chain of them is refused. The reason is the short-circuiting above: a < b < c joins its links with &&, and there is no such thing as short-circuiting one lane of a register and not another. Reading the chain as a lane-wise & would give the same spelling a different meaning, so the reader is asked to write the & and see it.

val a: <4>int = [1, 2, 3, 4]

f() -> unit
    val m = 1 < a < 4

compare two vectors at a time and combine the masks with '&'

Floats compare by IEEE 754, `NaN` and all

A NaN is equal to nothing, itself included. So ==, <, >, <= and >= are all false at one — and != is true, because IEEE makes it the negation of == rather than a sixth ordered comparison. Exactly one of the six answers true.

var zero = 0.0
var nan = zero / zero

print(nan == nan, nan != nan)
print(nan < 1.0, nan >= 1.0)

false true
false false

This is also why a float is not hashable: a table assumes a reflexive equality, and one NaN breaks it.

Logical operators

&& and || take bool and short-circuit; ! is prefix on a bool. Nothing coerces to bool, so there is no integer-as-condition rule and no if (p) idiom — write p != null.

Ranges

a..b is inclusive, a..<b is half-open. Either end may be omitted: a.., ..b, ..<b, and a bare .. meaning the whole thing.

Ranges are non-associative and sit below arithmetic and above comparison, which is Swift’s placement — so 0..<n + 1 is 0..<(n + 1) and needs no parentheses.

var lo = 1

for i in lo..lo + 2
    print(i)

1
2
3

The spelling deviates from Swift’s ... toward Kotlin’s .. / ..<, because the two forms are visually parallel and read as “through” and “up to, less than”. It lexes unambiguously: a float literal needs digits after the ., so 1..2 is three tokens and not two.

..= is not a spelling sysl has, and is refused by name wherever a range may be written — it is Rust’s inclusive range, and inclusive here is the bare ..:

val a = 1

for i in a..=3
    print(i)

'..=' is not a range — inclusive is 'a..b' and exclusive is 'a..<b'

`is` — a pattern where a condition is wanted

x is Pat tests a value against a pattern and yields a bool; x is not Pat negates it. The right side is a full pattern, alternatives (|) included — the same grammar a match arm’s left side uses, so it is not a second thing to learn.

enum Shape
    Circle(r: real)
    Rect(w: real, h: real)

var s = Rect(2.0, 3.0)

if s is Rect(_, _) && s is not Circle(_)
    print("rectangular")

rectangular

Its level — between && and the comparisons — is what makes a is P && b > 0 a chain of two terms rather than an is against a conjunction. Both is and not are soft words: neither is reserved, so both remain usable as ordinary names, and this is the only place either reads as a keyword.

Assignment

Assignment is an expression yielding the value assigned, lowest precedence and right-associative.

var a = 0
var b = 0
var c = 0

a = b = c = 7

print(a, b, c)

7 7 7

That is what makes the capture idioms available — while (c = next()) != 0, if (p = find(k)) != null. C’s classic if (x = 0) bug is not caused by this; it is caused by C additionally letting any integer serve as a truth value. sysl has a distinct bool with no such coercion, so the mistake is already a type error and needs no grammar ban:

var x = 1

if x = 0
    print("never")

condition must be bool, got int

The compound forms +=, -=, &= and the rest are not separate operators with their own traits: a += b is defined as a = a + b and requires exactly what + requires. There is no AddAssign.

Statement position discards a block’s value

A block’s value is its trailing expression — but where the block’s own value is unused, the block has none, and its type is unit whatever the last line yields. Without that rule an if whose branches merely each did something would be forced to make those somethings agree:

if c
    full = true          // bool
else
    len += 1             // usize

The rule is about the position, not the operator: it propagates into the branches of an if, the arms of a match, and a loop’s else. Statement position starts at a statement, at a loop body, and at the body of a function that returns nothing.

A block that does not arrive keeps never rather than collapsing to unit — that is reachability, not a value, and the code around it is entitled to know.

Several places at once

A comma-separated list of places takes a comma-separated list of values. The right side is evaluated in full, into temporaries, before any assignment happens — which is the entire content of the feature, and what makes the first line below a swap rather than two statements that leave both variables holding b.

var a = 1
var b = 2

a, b = b, a

var xs = [10, 20, 30]

xs[0], xs[2] = xs[2], xs[0]

print(a, b, xs[0], xs[2])

2 1 30 10

Compound forms multi-assign too, and need no rule of their own — only the one above, read carefully. Every place is located, then every place a compound form touches is read, then the whole right side is produced, and only then does anything land:

var a = 1
var b = 2

a, b += b, a

print(a, b)

3 3

Both arms saw the values the statement started with. Written as two statements it would not work: a += b followed by b += a folds the new a into b, and nothing on the page says so.

A place’s own subexpressions are evaluated exactly once, before the assignments — so in xs[f()], xs[g()] = xs[g()], xs[f()] each of f and g runs once.

A multiple assignment is a statement, not an expression, and that is what keeps it small. A single assignment yields the value assigned; a multiple one would have to yield several, and the only thing that could be is a tuple — allocating a product type for a form whose whole point is that several places change at once. So it does not nest, does not appear in a condition, and has no value to discard. A binding takes the same list: val a, b = 1, 2.

An element reached through a user type’s Index is the one place the accepted set is smaller than a single =‘s, because b[i] = v there is a call rather than a store, and there is nothing to split into the two halves the ordering rule is about.

`++` and `--`

Expressions, both prefix and postfix. Prefix yields the new value; postfix yields the old one. This is what the pointer-walking idioms need — *p++ only works if ++ is an expression.

var i = 5

print(i++, i, ++i, i)

5 6 7 7

C’s i = i++ + ++i is undefined because C leaves evaluation order unspecified while allowing unsequenced mutation of one object. sysl fixes the root cause rather than banning the operator: evaluation order is strictly left to right, everywhere — operands of a binary operator, function arguments, index expressions. With an order defined, the expression above has one meaning. It is merely hard to read, which makes it a lint candidate and not a footgun.

Postfix binds tighter than prefix, so *p++ is *(p++) and -a.b is -(a.b), exactly as in C.

The postfix tail

Six things attach to an expression on the right, and they compose left to right.

tail	what it does
`e[i]`	index — an element of an array, a slice, or a type implementing `Index`
`e.name`	select a field, or call a method
`e.0`	select a tuple’s part by position
`e(…)`	call
`T::Attr`	a type’s attribute rather than a value’s — a constrained type’s bounds live here
`e?`	try — unwrap or propagate
`e++`, `e--`	post-increment, post-decrement

A tuple index is a Field selection because it is one: a tuple’s fields are named for their positions. Note that t.0.1 does not work, because the lexer reads 0.1 as a float before it is two indices — write (t.0).1, which is what the diagnostic says.

`?`

Postfix on an Option or a Result, and sugar for the most common match: unwrap the success, or early-return the failure.

On a Result: Ok(v) evaluates to v; Err(e) returns Err(e) from the enclosing function immediately.
On an Option: Some(v) evaluates to v; None returns None immediately.

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2) else Err("odd")

quarter(n: int) -> Result[int, string]
    var h = half(n)?

    half(h)

show(r: Result[int, string])
    r match
        Ok(v)  -> print("ok", v)
        Err(e) -> print("err", e)

show(quarter(8))
show(quarter(6))

ok 2
err odd

Two rules make it well defined. The enclosing function’s return type must carry the failure — a ? on a Result is legal only inside a function returning Result, and on an Option only inside one returning Option. The early return has to have somewhere to go, and the two channels do not cross. And the error types must match exactly; there is no implicit widening, so a function with its own error type converts a callee’s explicitly.

? is an expression and composes as one, so its unwrapped value flows into whatever surrounds it.

Conversions are calls

Every conversion is written, with call syntax, and none is inferred — the visible-cost rule the memory model rests on applies to representation changes too.

from → to	written	behaviour
integer → integer	`u16(n)`, `byte(n)`	truncates or extends; sign-extends only when the source is signed
integer → float	`real(n)`, `f32(n)`	rounds to nearest; signed and unsigned sources differ
float → integer	`int(x)`	truncates toward zero
float → float	`f32(x)`, `real(x)`	rounds to nearest
`char` → integer	`u32(c)`	total — every `char` is an integer
integer → `char`	`char(u)`	partial — traps on a value that is not a Unicode scalar value
`char` → `string`	`string(c)`	total — the one character, UTF-8 encoded into a fresh string
`*T` → integer	`usize(p)`, `isize(p)`	total — an address is a number

var n = 300
var c = 'A'

print(byte(n), real(n), u32(c), int(3.9))

44 300 65 3

Everything else is rejected. There is no conversion to or from bool — int(true) is an error and so is bool(0) — and no number converts to or from a string: str(x) renders one and the strconv surface parses one, neither of them spelled as a conversion. The char → string row is the one exception, and a narrow one: a char is a single scalar value, so encoding it is total and has nothing to say about failure.

The pointer row goes only one way. An address is a number of usize‘s width, so reading it as one loses nothing and produces a value that cannot be dereferenced. The inverse is not a conversion at all — making a pointer out of an integer is ptr_cast, in the raw tier, spelled apart from this table because it is where the language’s guarantees stop.

Because these are calls, they parse as postfix at level 13 rather than as an operator of their own. The name in front may be a type parameter, and then the row is chosen at the instantiation.

`sizeof`, `alignof` and `offsetof`

The three forms whose first operand is a type rather than a value. All take parentheses, and all yield a usize.

struct Pair
    a: int
    b: byte

print(sizeof(int), alignof(int), sizeof(Pair), alignof(Pair))

4 4 8 4

They are read as their own grammar rather than left to look like calls, because a call’s arguments are expressions and sizeof(*Node) would otherwise parse as a dereference. There is no form that takes a value — a value’s type is what would be measured anyway.

offsetof takes a type and then a field name, and answers where that field starts in bytes. The name is a name and not an expression, for the same reason the type is not one: there is no value here for a p.x to select from.

struct Header
    tag: u8
    length: u32
    flags: u16

print(offsetof(Header, tag), offsetof(Header, length), offsetof(Header, flags), sizeof(Header))

0 4 8 12

The padding after tag is what puts length at 4 — @packed lays the same fields end to end and makes them 0, 1 and 5. Its use is checking a mirrored C struct, where a size alone cannot see two same-width fields transposed. A field the struct does not have is refused by name, and so is a bitfield — the answer is in bytes, and a field starting at bit twelve is not at byte one.

Closures

x -> x + 1 is a closure literal. It sits at the top of the expression grammar, so its body extends as far to the right as an expression can: that is a closure over the sum, not a closure over x added to 1.

Parameters are one bare name, or a parenthesized list — including the empty list, which is the one arity with nowhere else to be written. A type annotation goes inside the parentheses and nowhere else, so there is no second spelling to disagree with the first.

apply(f: () -> int) -> int = f() + f()

var n = 10
var twice = apply(() -> n)
var inc = (x: int) -> x + 1

print(twice, inc(41))

20 42

A closure’s parameter declares no default. A call reaches a closure through the Fn traits, which carry types and not names, so there would be nothing at the call to fill one from.

`_` — a parameter with the name left out

A bare _ in operand position is a closure parameter, and the closure it builds closes at the nearest of three boundaries: a parenthesized group, an argument, or a statement.

apply(f: int -> int, x: int) -> int = f(x)

print(apply(_ + 1, 41), apply(_ * 2, 21))

42 42

The group is what a program reaches for when the other two boundaries fall in the wrong place. But it cuts both ways, and this is the one thing to know about the form: the closure closes at the group, so anything outside the group applies to the closure itself, not to what it computes.

apply(f: int -> int, x: int) -> int = f(x)

print(apply((_ + 1) * 2, 20))

this '_' has no type here

(_ + 1) * 2 multiplies a closure by two rather than closing over the doubled sum — so nothing is left to say what the placeholder’s parameter is, and the diagnostic points at the _. When the boundary is not where you want it, write the arrow form: x -> (x + 1) * 2.

An interpolation hole is a boundary too, so a placeholder cannot reach out of a string to close over the whole of one.

String interpolation

s"…" renders each ${…} hole through str and concatenates: s"a${e}b" is "a" + str(e) + "b", with no runtime formatting machinery involved. f"…" allows a printf specifier after a hole, and routes that hole through format instead, where the analyzer checks the specifier against the value’s type.

var name = "world"
var n = 7

print(s"hello ${name}, ${n * 6}")
print(f"[${n}%4d]")

hello world, 42
[   7]

The embedded source is parsed as an ordinary expression — so a hole may itself interpolate — and it is parsed as its own little source, so a diagnostic inside a hole points into the hole rather than at an unrelated column of the line the string sits on.

Operator dispatch

An operator expression is a trait-method call, resolved by one rule in every context. For an operator ⊕ mapped to trait Op with method m, a ⊕ b means Op::m(a, b), and it type-checks exactly when a‘s type satisfies Op at b‘s type.

What differs between a scalar, a user type and a bounded type parameter is only where the impl comes from — never the rule:

A built-in scalar satisfies the operator traits by a compiler-provided impl, and codegen keeps emitting the native machine instruction. No call, no vtable. The membership exists so the type system agrees a scalar satisfies Add, which is what lets one be passed where [T: Add] is wanted.
A user type with impl Op for S lowers to the member the impl produced. Overloading an operator is implementing its trait; there is no separate operator-method syntax.
A bounded parameter [T: Op] resolves abstractly at the definition, and monomorphization binds it per instantiation.

trait	method	operator
`Add`	`add`	`+`
`Sub`	`sub`	`-` (binary)
`Mul`	`mul`	`*`
`Div`	`div`	`/`
`Rem`	`rem`	`%`
`BitAnd`	`bitand`	`&` (binary)
`BitOr`	`bitor`	`\\|`
`BitXor`	`bitxor`	`^`
`Shl`	`shl`	`<<`
`Shr`	`shr`	`>>`
`Neg`	`neg`	`-` (unary)
`Not`	`not`	`~`
`Eq`	`eq`	`==`, `!=`
`Ord`	`lt`	`<`, `>`, `<=`, `>=`
`Index`	`index`	`e[i]` read
`IndexSet`	`index_set`	`e[i] = v`

struct Vec2
    x: int
    y: int

impl Add for Vec2
    add(self, rhs: Vec2) -> Vec2 = Vec2(self.x + rhs.x, self.y + rhs.y)

var v = Vec2(1, 2) + Vec2(10, 20)

print(v.x, v.y)

11 22

A type becomes fully comparable by implementing one method, lt, and fully equatable by implementing one, eq — the compiler derives the rest: a != b is !eq(a, b), a > b is lt(b, a), a <= b is !lt(b, a), a >= b is !lt(a, b).

Two of those swap their operands, and the swap is of the two values, applied at the call — so a > b still evaluates a before b, and the derivation is invisible in evaluation order as well as in the answer.

Eq and Ord are independent traits, not a hierarchy. That is the scalar law lifted intact: bool and the pointer modes have == and no <. There is no four-way PartialEq/Eq/PartialOrd /Ord tower.

The scalars do not go through those derivations — the compiler-provided impls supply all six comparisons directly at IEEE semantics, which is what keeps NaN <= 1.0 and NaN >= 1.0 both false where negating lt would have made one true.

A simple enum is `Eq`, and nothing else

An enum whose variants all carry nothing is a simple enum, and its value is its discriminant. There is exactly one thing equality on it could mean, so the compiler supplies it — the same rule that makes every width of integer Eq without a block being written per width:

enum Colorspace
    Srgb
    Linear

same[T: Eq](a: T, b: T) -> bool = a == b

print(Srgb == Srgb, Srgb == Linear)
print(same(Linear, Linear))

true false
true

The membership satisfies an Eq bound, as the second line shows, and not merely the == token — so a simple enum goes into anything written over [T: Eq].

It is not Ord. Declaration order is an order and it is not a meaning: Srgb < Linear says nothing anybody wants a language to assert on their behalf, so an enum whose order means something writes the impl that says so. It is not Hash either, for the same reason — that is a promise about a distribution, and a program makes it deliberately.

An enum that carries data is not a member. Comparing two of those means comparing their payloads, which needs every payload type to be Eq itself; that is an impl a program writes, and the core module shows the shape.

Writing the block by hand for a simple one is refused rather than ignored, because the comparison is emitted whatever the block says:

enum Colorspace
    Srgb
    Linear

impl Eq for Colorspace
    eq(self, rhs: Colorspace) -> bool = int(self) == int(rhs)

print(Srgb == Srgb)

'Colorspace' already implements 'sysl.Eq' — no variant of it carries anything, so its value is its discriminant and '==' is that comparison. Delete the block; a variant that needs an equality of its own has to carry something for it to be about

Why the token set is closed

Overloading the fixed set is the bare-metal consensus: Rust, C++, D and Ada all allow it, Zig and C allow no overloading at all, and none permits a new operator token. Low-level code is read while reasoning about hardware, and a mystery operator that is secretly a user function fights that — the same visible-cost value the memory model rests on. A closed set also lexes by longest match against a fixed list, with no operator “muncher” and no parser-vocabulary registration to keep in step.

Next: statements and control flow.

Error handling

2026-08-16T01:26:07.924728867Z

Failure travels on two separate channels in sysl, and choosing between them is a real decision at every API rather than a coin toss:

A recoverable failure is a value. Result[T, E] or Option[T] in the return type, propagated with ?. The caller has to engage with it, because it is part of the signature.
A bug is a trap. An index past the end, an invalid cast, a broken contract. Not a value, not catchable, and it stops the program.

Keeping them apart is what makes a signature honest. A function returning Result[T, E] is telling you it can fail in a way you handle; one returning plain T is telling you the only way it “fails” is if the program is already wrong.

The line between them is one question: could correct calling code ever hit this? If yes — the input came from a file, a socket, or a person, or the operation legitimately may not succeed — it is a Result. If only a bug reaches it, it traps.

`Result` and `Option`

Both are ordinary generic enums from the library, exactly as the previous chapter described. Option[T] is absence with no reason attached; Result[T, E] is failure with a reason:

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2)
    else Err("odd")

half(10) match
    Ok(v)  -> print("half:", v)
    Err(e) -> print("refused:", e)

half(7) match
    Ok(v)  -> print("half:", v)
    Err(e) -> print("refused:", e)

half: 5
refused: odd

E is whatever carries the reason — a string here, but usually an enum, so a caller can match on what went wrong instead of reading it.

Type arguments come from inference, including the cases with nothing to infer from at the call: a bare None takes its T from context, and Ok(n) inside a Result[int, string]-returning function takes its E from the return type.

`?`

Matching every call gets old fast, and ? is sugar for the match you would have written: unwrap the success, or early-return the failure.

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2)
    else Err("odd")

quarter(n: int) -> Result[int, string]
    var h = half(n)?

    half(h)

print(quarter(20).unwrap_or(-1), quarter(10).unwrap_or(-1), quarter(7).unwrap_or(-1))

5 -1 -1

On a Result, Ok(v) becomes v and Err(e) returns Err(e) from the enclosing function immediately. On an Option, Some(v) becomes v and None returns None:

struct Node
    label: string
    next: Option[&Node]

second_label(head: &Node) -> Option[string]
    var nx = head.next?

    Some(nx.label)

var tail: &Node = Node("b", None)
var head: &Node = Node("a", Some(tail))

print(second_label(head).unwrap_or("(none)"))
print(second_label(tail).unwrap_or("(none)"))

b
(none)

? is an expression, not a statement, so its unwrapped value flows straight into whatever surrounds it.

The two channels do not cross. An Option‘s ? cannot early-return from a Result-returning function, and the enclosing function’s return type has to be able to carry the failure at all — the early return needs somewhere to go:

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2)
    else Err("odd")

count(n: int) -> int
    half(n)?

'?' may only be used in a function returning sysl.Result, not int

The error types must match exactly, too. There is no implicit widening, so a function whose own error type differs from a callee’s converts at the call site:

struct IoError
    code: int
end IoError

struct AppError
    why: string
end AppError

read_it(n: int) -> Result[int, IoError]
    if n > 0 then Ok(n)
    else Err(IoError(5))

run(n: int) -> Result[int, AppError]
    var v = read_it(n)?

    Ok(v)

print(run(1).is_ok())

'?' propagates a IoError error, but this function returns AppError

That is a real ergonomic cost, and it is the shipping behaviour rather than the end state: the intended answer is a From-style conversion, where ? converts the callee’s error to the caller’s whenever a conversion trait connects the two, as Rust’s ? calls From::from. Writing that trait is possible today — impl From[IoError] for AppError and impl From[ParseError] for AppError are two different argument lists, and a type may implement a parameterized trait once at each of them (see the reference). What is left is teaching ? to look for one.

The combinators

The conveniences on both types are ordinary members in the library, not compiler knowledge. The total ones ask a question or supply a fallback:

find(xs: []const int, target: int) -> Option[usize]
    for i in 0..<xs.len
        if xs[i] == target then return Some(i)

    None

var data = [4, 5, 6]

print(find(data, 5).is_some(), find(data, 9).is_none())
print("fallback:", find(data, 9).unwrap_or(99))

true true
fallback: 99

Result has the matching pair is_ok() and is_err(), plus unwrap_err() for reaching the reason.

The forcing ones hand over the payload and stop the program when there is none — unwrap(), and expect(msg) which says why you thought there would be one:

var got: Option[int] = Some(7)

print(got.unwrap(), got.expect("a value was put here two lines ago"))

7 7

That these are written in sysl rather than built in is the part worth pausing on, because it is what keeps “a bug stops the program” from meaning “the compiler has to know the name of every way to stop”:

unwrap(self) -> T = self match
    Some(v) -> v
    None ->
        print("panic: unwrap of a None value")
        exit(1)

Two things make that ordinary code. A diverging arm has a type — never — so exit(1) sits beside Some(v) -> v and the match still has the payload’s type rather than a conflict. And the departure itself is an extern: the library declares exit(code: int) -> never, so stopping is a call.

`defer` — releasing what ARC does not

? has a consequence worth facing directly: it makes leaving early the normal way out of a function. That is fine for everything ARC owns — a &T, a string, a slice’s backing all go back on their own — and it is a problem for everything else. A file descriptor from open, a block from malloc, a lock taken from a mutex: those are released by hand, and a function with four exits has four places to remember.

defer <statement> runs that statement on the way out of the block containing it, so the release is written beside the call that took the resource, once:

acquire(n: int) -> Result[int, string]
    if n > 0 then Ok(n)
    else Err("cannot acquire")

step(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n * 10)
    else Err("odd step")

run(n: int) -> Result[int, string]
    var h = acquire(n)?

    defer print("released", h)

    var v = step(h)?

    print("finished with", v)

    Ok(v)

print(run(4).is_ok())
print(run(3).is_ok())

finished with 40
released 4
true
released 3
false

Both exits ran it. run(4) fell off the end and run(3) left through the ? in the middle, and neither one had to say so — which is the entire point, because the second exit is the one a program forgets.

Two rules make it predictable. Several in one block run last-registered-first, so they undo in the reverse of the order they were set up. And a defer runs only if control reached it: it is a statement, not a declaration, so one below an early return never registered at all. In the program above, a failure from acquire returns before the defer line, and nothing is released — correctly, since nothing was acquired.

The scope is the block, not the function, and a loop is where that shows:

for i in 0..<2
    defer print("close", i)

    print("open", i)

print("done")

open 0
close 0
open 1
close 1
done

Go runs its defer at function exit, so the same loop would hold two resources to the end and release both at once — which is how a loop over ten thousand files runs out of descriptors. Here each iteration is a block and each closes its own.

One thing defer is not: a finally. A trap runs nothing. A broken invariant means the program’s model of itself is already wrong, and cleanup run against that state is how a corrupt program writes its corruption out. defer releases a resource; it does not rescue a bug — which is the subject of the rest of this page.

Traps

The other channel. A trap is the runtime response to a broken invariant, and what it does is settled: it aborts. No unwinding, no stack cleanup, no catch, no exceptions.

var xs = [1, 2, 3]

print(xs[5])

That program compiles and then stops when it runs, because the bounds check fails. There is no handler that could have caught it and no defer that runs on the way down — defer is a scope-exit form, and a trap is not an exit. It is the program stopping because its model of itself is already wrong, and cleanup code run against that state is how a corrupt program writes its corruption out.

The trap sources are the runtime safety checks the safe subset rests on: an out-of-bounds index, an inverted or out-of-range slice range, a checked cast that fails, an integer divide by zero, and a violated require/ensure contract.

Integer overflow is not one of them, which is worth saying because Rust traps on it in a debug build. Arithmetic wraps at the declared width, as values showed — that is defined behaviour rather than a broken invariant, so there is nothing for a trap to report.

Two reasons abort is the only defensible choice here. A kernel and an embedded target have no unwinding runtime — landing pads, a personality routine and per-frame cleanup tables are exactly what a freestanding target does not have. And an abort is one code path, where unwinding is a second, invisible control-flow graph that every function in the program would have to be correct under.

What a trap does is an environment fact rather than a language one. A hosted program prints a diagnostic and exits non-zero; a kernel installs its own panic handler and enters that. The decision to stop is the language’s; the action on stopping is the environment’s.

Turning a trap back into a value

There is no panic you can recover from, so a program that wants to survive bad input must not do the trapping thing — check the bound, validate before dividing, and use the fallible constructor rather than the checked cast. That is the move to make wherever untrusted input enters:

enum Color: u8
    Red
    Green
    Blue

parse(b: u8) -> Result[Color, string]
    Color.try(b) match
        Some(c) -> Ok(c)
        None    -> Err("byte " + str(b) + " is not a Color")

parse(1) match
    Ok(c)  -> print("read:", Color::Image(c))
    Err(e) -> print(e)

parse(9) match
    Ok(c)  -> print("read:", Color::Image(c))
    Err(e) -> print(e)

read: Green
byte 9 is not a Color

Color(9) would have trapped. Color.try(9) hands back a None that this function turns into a reason, and the byte off the wire stops being a bug in the program and starts being a value it handles — which is the whole of the policy in one function.

What is deliberately absent

No exceptions. Recoverable failure is a returned value and a bug is an abort. There is no third, invisible control-flow channel.
No error return codes by convention. The failure is in the type and it is checked, not an int a caller might forget to inspect.
No panic that unwinds. A trap is terminal.

`?` and the memory model

? obeys ARC with no special rule, which matters most here because it is the operator most likely to carry a heap payload across a function boundary.

Unwrapping a &T success payload retains it past the wrapper, so the reference outlives the Result it came out of and is released exactly once. Propagating a &T error payload moves it through the early return with its count intact.

Neither is a rule about ?. Both fall out of retain-on-alias and release-at-scope-end — and they are worth naming because a hand-rolled C error return leaks or double-frees at exactly these two boundaries.

Next: traits and generics — one implementation over many types, and what a bound is really promising.

Errors, traps and contracts

2026-08-16T01:26:07.924728867Z

Failure travels on two separate channels, and which one a given failure uses is a design decision at every API rather than a coin toss:

A recoverable failure is a value. Result[T, E] or Option[T] in the return type, propagated with ?. It is part of the signature, so the caller has to engage with it.
A bug is a trap. An index past the end, an invalid cast, a broken contract. Not a value, not catchable, and the program stops.

This page covers both channels and then the three features that create the second one — constrained types, struct invariants, and function contracts — because a within range and a require clause are only interesting once you know what happens when they are false.

Which channel — the policy

One question decides it: could correct calling code ever hit this?

	answer	why
Yes — an expected outcome of valid use	`Result` / `Option`	The input came from outside the program — a file, a socket, a person — or the operation legitimately may not succeed. A correct caller still meets this case, so the type must force it to be handled.
No — only a bug reaches it	a trap	Indexing past the end, converting an out-of-range integer to a `char`, dividing by zero, violating a `require`. A correct program never does these; reaching one means the program is already wrong.

The payoff of the split is that signatures stay clean — no Result smeared across functions that cannot meaningfully fail — while the failures that are real are impossible to ignore, because they are in the type.

`Option[T]` and `Result[T, E]`

Both are ordinary generic enums declared in the standard library, with no compiler privileges:

enum Option[T]                 enum Result[T, E]
    Some(value: T)                 Ok(value: T)
    None                           Err(error: E)

Option[T] is absence — a value that may or may not be there, with no reason attached: a missing key, the next of a list tail, the result of a search. It is also what a weak reference degrades to, and what a fallible constructor like char.try answers with.
Result[T, E] is failure with a reason — parsing, I/O, validation. E is whatever carries the reason: a string, an error enum, a &Fail.

They are constructed and taken apart like any enum, and their type arguments come from inference — including the two cases with nothing to infer from at the call. A bare None takes its T from context, and an Ok(n) inside a Result[int, string]-returning function takes its E from the return type:

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2)
    else Err("odd")

first_even(xs: []const int) -> Option[int]
    for x in xs
        if x % 2 == 0 then return Some(x)

    None

var data = [3, 5, 8, 9]

half(10) match
    Ok(v)  -> print("half:", v)
    Err(e) -> print("refused:", e)

half(7) match
    Ok(v)  -> print("half:", v)
    Err(e) -> print("refused:", e)

print(first_even(data).unwrap_or(-1))

half: 5
refused: odd
8

E is usually an enum rather than a string, so a caller can match on what went wrong instead of reading a sentence about it.

The members

The total ones ask a question or supply a fallback. None of them can stop the program:

on `Option[T]`	on `Result[T, E]`	is
`is_some()`	`is_ok()`	`true` when the value is there
`is_none()`	`is_err()`	`true` when it is not
`unwrap_or(default)`	`unwrap_or(default)`	the payload, or `default`

The forcing ones hand over the payload and stop the program when there is none:

on `Option[T]`	on `Result[T, E]`	stops when
`unwrap()`	`unwrap()`	`None` / `Err`
`expect(msg)`	`expect(msg)`	`None` / `Err`, printing `msg`
—	`unwrap_err()`	`Ok`
—	`expect_err(msg)`	`Ok`

var got: Option[int] = Some(7)
var bad: Result[int, string] = Err("no")

print(got.is_some(), got.unwrap_or(0), got.expect("put here two lines ago"))
print(bad.is_err(), bad.unwrap_or(-1), bad.unwrap_err())

true 7 7
true -1 no

unwrap_err is Result‘s alone because Option‘s empty case carries nothing to hand back.

They are written in sysl, and that is the point

The forcing members stop the program without any compiler support of their own:

unwrap(self) -> T = self match
    Some(v) -> v
    None ->
        print("panic: unwrap of a None value")
        exit(1)

That is what keeps “a bug stops the program” from meaning “the compiler must know the name of every way to stop”. Two ordinary features make it work. A diverging arm has a type — never — so exit(1) sits beside Some(v) -> v and the match still has the payload’s type rather than a conflict between T and nothing. And the departure itself is an extern: the library declares exit(code: int) -> never, so stopping is a call.

Nothing here costs a program that does not use it. The enums are generic, so a member exists only where a call asks for one, and an extern nothing reaches is never declared in the output.

`?`

The expressions page gives ? its place in the grammar — postfix, at the tightest level, alongside . and (). Its rules in full:

On a Result, Ok(v) evaluates to v and Err(e) returns Err(e) from the enclosing function immediately. On an Option, Some(v) evaluates to v and None returns None immediately.

The enclosing function’s return type must be able to carry the failure. The early return has to have somewhere to go:

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2) else Err("odd")

count(n: int) -> int
    half(n)?

'?' may only be used in a function returning sysl.Result, not int

The two channels do not cross. An Option‘s ? cannot early-return from a Result-returning function, and the diagnostic names the type it wanted:

pick(n: int) -> Option[int]
    if n > 0 then Some(n) else None

cross(n: int) -> Result[int, string]
    var v = pick(n)?

    Ok(v)

'?' may only be used in a function returning sysl.Option, not sysl.Result[int, string]

The error types must match exactly. There is no implicit widening, so a function with an error type of its own converts a callee’s explicitly:

enum Fail
    Bad

half(n: int) -> Result[int, string]
    if n % 2 == 0 then Ok(n / 2) else Err("odd")

other(n: int) -> Result[int, Fail]
    var v = half(n)?

    Ok(v)

'?' propagates a string error, but this function returns Fail

That last rule is the shipping behaviour rather than the end state, and its ergonomic cost is real: a program with its own AppError cannot ?-propagate a library’s IoError without a manual step at each call. The eventual answer is a From-style conversion inserted by ?, which is designed and waiting on something else — a type implements a trait once, so an AppError cannot be From[IoError] and From[ParseError] both, and lifting that needs a way for a use to say which implementation it means. The conversion is additive: turning it on later invalidates no exact-match ? written before it.

? is an expression, so its unwrapped value flows straight into whatever surrounds it — Ok(mk()?) is ordinary, and a chain of hops is written as a sequence of ?-bound locals.

`?` and the memory model

? obeys ARC with no special rule, and this is where that discipline is load-bearing, because ? is the operator most likely to carry a heap payload across a function boundary.

Unwrapping a &T success payload retains it past the wrapper, so the reference outlives the Result it came out of and is released exactly once:

struct Point
    x: int
    y: int

mk(ok: bool) -> Result[&Point, string]
    if ok then Ok(Point(1, 2)) else Err("no")

use(ok: bool) -> Result[int, string]
    var p = mk(ok)?

    Ok(p.x + p.y)

print(use(true).unwrap_or(-1), use(false).unwrap_or(-1))

3 -1

Propagating a &T error payload moves it through the early return with its count intact, freed exactly once on whichever path consumes it.

Neither is a rule about ?. Both fall out of retain-on-alias and release-at-scope-end, and they are named here because a hand-rolled C error return leaks or double-frees at exactly these two boundaries.

Traps

The other channel. A trap is the runtime response to a broken invariant, and its semantics are settled:

A trap aborts. There is no unwinding, no stack cleanup, no catch, no exceptions. When a check fails the program stops; it does not run destructors up the stack, and it cannot be intercepted and resumed.

Two reasons this is the only defensible choice for the language’s targets. A kernel and an embedded target have no unwinding runtime — landing pads, a personality routine and per-frame cleanup tables are exactly the machinery a freestanding no alloc target does not have and does not want, and an abort needs none of it. And determinism: an abort is one code path, where unwinding is a second, invisible control-flow graph that every function in the program would have to be correct under. Removing it removes the whole “is this exception-safe?” class of reasoning, which is the same simplification the memory model makes by having no move semantics.

Nor does a trap run a deferred statement. defer is the language’s scope-exit form, and a trap is not an exit — it is the program stopping because its model of itself is already wrong. Cleanup code run against that state is how a corrupt program writes its corruption out on the way down. So defer is for releasing a resource, not for restoring an invariant.

What traps

source	example
an out-of-bounds array or slice index	`xs[5]` on a `[3]int`
an inverted or out-of-range slice range	`xs[3..1]`, `xs[0..9]`
a checked cast that fails	`char(u)` on an invalid scalar, `Color(n)` on an undeclared discriminant
an integer divide by zero	`n / 0`, `n % 0`
a violated `require` or `ensure`	below
a violated struct `invariant`	below
a violated `within` range or `where` predicate, at a produce site	below
`T::Succ` past `T::Last`, `T::Pred` below `T::First`	below
overflow of `+`, `-`, `*` where an operand came through a ranged type	below

Integer overflow is otherwise not a trap source, which is worth saying because Rust traps on it in a debug build. Plain arithmetic wraps at the declared width, so overflow is defined behaviour rather than a broken invariant and there is nothing for a trap to report. The last row of the table is the narrow exception, and it belongs to constrained types rather than to arithmetic.

No build option removes any of these. There is no --no-contracts, no bounds-check stripping, no NDEBUG. A check that is in the language is in every build, because a switch that removed one would make a program’s meaning depend on how it was compiled.

What stopping looks like

The decision to stop is the language’s; the action on stopping is the environment’s. Under the os capability a hosted program stops the process and exits non-zero; a kernel installs its own panic handler and enters that.

On a hosted target there are two observably different shapes, and the difference is worth knowing before you debug one:

stopped by	what you see	exit status
a compiler-inserted check — a bound, a cast, a range, a contract	nothing at all, and buffered output already written by the program is lost	the platform’s signal status for a trap instruction
a library forcing member — `unwrap`, `expect`	`panic: <message>` on stdout, after everything the program printed before it	1

The library’s route goes through exit, which flushes on its way out; a compiler check goes straight to the target’s trap instruction, which does not. So a program that printed diagnostics right up to the failing line will appear to have printed none of them if a bounds check is what stopped it. Reconciling the two so that every stop says why it stopped is an open question in the design.

Turning a trap back into a value

There is no panic you can recover from, so a program that must survive bad input has to not do the trapping thing: check the bound, validate before dividing, and use the fallible constructor rather than the checked cast. That is the move to make wherever untrusted input enters, and it is where a bug turns back into a value:

enum Color: u8
    Red
    Green
    Blue

parse(b: u8) -> Result[Color, string]
    Color.try(b) match
        Some(c) -> Ok(c)
        None    -> Err("byte " + str(b) + " is not a Color")

parse(1) match
    Ok(c)  -> print("read:", Color::Image(c))
    Err(e) -> print(e)

parse(9) match
    Ok(c)  -> print("read:", Color::Image(c))
    Err(e) -> print(e)

read: Green
byte 9 is not a Color

Color(9) would have trapped. Color.try(9) hands back a None this function turns into a reason, and the byte off the wire stops being a bug in the program and starts being a value it handles.

For a constrained type the equivalent is T::Valid, below.

Constrained types

One declaration form with three independent parts:

type Name = [new] Base [within lo..hi] [where predicate]

new, within and where are contextual keywords — ordinary identifiers everywhere else, so a field, a function or a variable may still be called where:

struct Cfg
    where: int
    invariant: int

where(n: int) -> int = n * 2

var c = Cfg(3, 4)

print(c.where, c.invariant, where(5))

3 4 10

Each of the three parts may be left out, with one exception:

written	means
`type Meters = new f64`	a distinct type over `f64`, no constraint
`type Age = int within 0..150`	`int` with a range, but the same type as `int`
`type Even = int where value % 2 == 0`	`int` with a predicate
`type Slot = new u8 within 0..<200`	distinct and constrained
`type Alias = int`	rejected

The last row is the exception. A transparent alias with no constraint declares nothing — it neither narrows the values nor makes a new type — so writing it can only be a mistake or an attempt at a typedef of one’s own, which is not a thing to write here:

type Alias = int

var n: Alias = 1

print(n)

'Alias' has no constraint — add a 'within' range or a 'where' predicate, or 'new' to make it a distinct type

Note that type Name = Existing is legal as a type alias for a name that has grown long; what is refused is calling that a constrained type by adding nothing to it. The diagnostic is what tells the two apart.

The base must be a scalar — an integer, a float, or a char:

struct Point
    x: int
    y: int

type Bad = new Point

var b = Bad(Point(1, 2))

print(b.x)

a constrained subtype's base must be an integer, a float, or 'char', not Point

A constraint here is a check on a value. The two ways to narrow an aggregate are the struct invariant below and, for an enum, having fewer variants.

Ranges

.. includes the upper bound and ..< excludes it, matching the range expressions. A bound is a constant expression — a literal, a const, or arithmetic over them, folded through the same path an array length and an enum discriminant go through, so the three positions accept the same expressions and cannot drift apart:

const max_tasks: int = 4

type Task = int within 0..<max_tasks
type Trimmed = int within 0..max_tasks - 2

var t: Task = 3
var u: Trimmed = 2

print(t, u)

3 2

That is one fact written once: within 0..<max_tasks beside [max_tasks]Task. What a bound may not be is non-constant — a module-level val is read-only storage with an address rather than a constant, and is refused here.

Two shapes are rejected at the declaration. A bound outside the base’s own range:

type Big = byte within 0..300

var b: Big = 1

print(b)

the bound 300 does not fit byte

And an inverted range:

type Inverted = int within 10..0

var i: Inverted = 5

print(i)

the lower bound of 'Inverted' is above its upper bound

Predicates

The predicate is an ordinary boolean expression, and the value it is about is named value, bound only inside the predicate:

type Even = int within 0..100 where value % 2 == 0
type HexDigit = char where value >= '0' && value <= '9'

var e: Even = 8
var h: HexDigit = '7'

print(e, h)

8 7

A predicate may read module constants, which is what lets a range and a table’s size be stated once. Where both a range and a predicate are written, the range is checked first, so a value the range rejects never reaches the predicate.

A non-boolean predicate is reported against the type, without leaking the name of the function the compiler synthesised to hold it:

type Odd = int where value + 1

var o: Odd = 3

print(o)

a 'where' predicate must be a 'bool', but this one is int

`new` is what makes it a type

Without new, a constrained type is its base with a checked range. Age and int are the same type, values flow between them in both directions with no cast, and what the declaration buys is the check:

type Age = int within 0..150

birthday(a: Age) -> Age = a + 1

var n: int = birthday(41)

print(n)

With new it is a distinct nominal type, and that is the whole of the difference. Two derived types over one base do not mix:

type Meters = new f64
type Feet = new f64

print(f64(Meters(1.0) + Feet(1.0)))

'+' needs matching types, got Meters and Feet

A derived type does not mix with its base either, and no position excuses it — an initializer, an argument and a returned value each refuse it:

type Meters = new f64

var q: Meters = 3.0

print(f64(q))

cannot initialize 'q': declared Meters but the value is real

Going in either direction is a written conversion: Meters(x) wraps, f64(m) unwraps, and the wrap is where the constraint is checked.

The payoff is a specific bug. A table-driven program has several small integers that index different things — a task number, a lock number, a priority level — and the mistake such a program actually makes is passing one where another was wanted. Three new u8s with three ranges make that a compile error rather than a plausible-looking wrong answer. It is an argument about types, not about checking.

A derivation inherits its base’s behaviour and may replace none of it

A new type over a scalar arrives with everything the scalar could do — the arithmetic operators, the remainder, the bitwise operators and the shifts, unary - and ~, the comparisons, the compound assignments, ++ and --, and str — working at itself and producing itself.

And no impl may replace or extend any of it:

type Stamp = new i64
type Span = new i64

impl Add[Span] for Stamp
    add(self, other: Span) -> Stamp = Stamp(i64(self) + i64(other))

'add' is how 'Add' is implemented for Stamp, and the compiler provides that — a member of this name would hide it

type Span = new i64

impl Display for Span
    str(self) -> string = "span"

'Span' already implements 'sysl.Display' — every 'sysl.Integer' does, through one block written over the family, and a subtype has its base's memberships

The two refusals arrive by different routes, which the messages say. Add is a membership the compiler provides, so a member of that name would hide something with no block behind it. Display is an ordinary impl the library writes — one blanket block covering every integer — and a derivation has its base’s memberships, so the block covers Span too.

Both halves are deliberate. Inheriting is right because a derivation does not change what the values are: a Slot is some of the u8s, not a different set of things that happens to be stored in a byte. A derivation that started with nothing would make every new u8 cost a dozen impl blocks, and nobody would use it.

Refusing to replace is the harder call, and it is a ruling. If Stamp could redefine <, then Stamp would be a set of i64s that do not order the way i64s order, and every fact the base guarantees would hold only until somebody looked. A derivation is a narrowing, and a narrowing that alters behaviour is not a narrowing.

So the answer to “I want my own +“ is that you do not want a derivation, you want a struct.

Except rendering, which a derivation may take back

The second refusal above is the unmarked one, and that is the whole of what it refuses. Say override and the block is yours:

type Stamp = new int

override impl Display for Stamp
    display(self, out: *Writer, fmt: FormatSpec) = display_str("#" + str(int(self)), out, fmt)

var s: Stamp = Stamp(7)

print(s)
print(7)

#7
7

The line is what the base guarantees about its values. Ordering is such a guarantee — that is the < argument above, and it still stands. How a value renders is not: a Stamp printing as #7 is the same i64 it always was, and nothing downstream reasons about it differently. So rendering is the one row a derivation may replace, and the operators are not.

	a `new` derivation	a one-field struct
distinct type	yes	yes
the base’s catalogue	free; only `Display` is replaceable	nothing, write it all
an operation the base does not have	impossible	ordinary
an operation the base has that is now nonsense	present anyway	absent
rendering as something other than the base	`override impl Display`	ordinary

Use a derivation for an identity — a slot number, a handle, a unit-tagged measurement, anything whose operations are its representation’s operations. Use a struct for a quantity with an algebra of its own: an instant plus a duration is an instant, an instant plus an instant is nonsense, and no derived scalar can be told the difference. The cost is real and was measured — a date-and-time library written this way needs one-field structs and five impl blocks per type.

What has no answer today is the case in the middle: a type that wants most of its base’s catalogue and one row of its own. impl Add[Duration] for Instant takes something the base could never have taken and touches no guarantee of i64‘s, but it is refused because the check is on the method name, and add is taken.

A subtype narrows which values a type has, never which operations it has — so what the base does not have, the subtype does not either, and the diagnostic names the subtype rather than the base:

type Slot = new u8 within 0..<8

neg(s: Slot) -> Slot = -s

unary '-' is not defined for the unsigned type Slot

type Ratio = new f64

flip(r: Ratio) -> Ratio = ~r

unary '~' is not defined for Ratio

The operations are the base’s; their overflow is not

Raw integer arithmetic wraps, and a wrapped result reaching a produce site is a wrong answer the range check can pass without noticing. On a Slot = u8 within 0..<200, Slot(150) + Slot(150) is 300, which wraps to 44 — which is in range.

So where an operand came through a within type and the operands’ declared ranges permit a result the base width cannot hold, +, - and * are overflow-detecting and trap. A range narrow enough that its results always fit stays on the plain instruction, so a counter, an index and an x + 1 cost exactly what they did before. A left shift is checked on its own terms — it has no overflow intrinsic, so a bit pushed out of the top is caught by shifting back, and a shift amount at or past the width traps rather than being undefined. Arithmetic on a type with no range still wraps.

For a transparent subtype the arithmetic happens at the base and yields a base value, so a literal beside one is an ordinary base value and what has to be in range is only what is stored:

type Small = int within 0..10

var s: Small = 2

print(s * 100)

The multiplier is not a Small and does not have to be. A derived subtype is its own representation, so it mixes with the base only through the cast above, and its results are its own and are checked where they are produced.

Where a constraint is checked

At every point a value of the constrained type is produced, and nowhere else. That is not a list of syntactic forms to memorize: a value comes to have the type wherever it flows into a slot the type is written on, plus wherever an operation of the type’s own yields one. The slots are enumerable:

a variable’s initializer, and every later assignment to it — including one arm of a multi-assignment, and a write through a pointer
an argument at a call, and a function’s returned value — a plain function’s, a method’s, a nested function’s, or a closure’s
an explicit cast, T(x)
a field written into a struct, at construction and at every later write, however the struct is reached
an element of an array, at a literal and at every later write, through the array or through a view of it
a part of a tuple, and the payload of an enum variant
an item entering a generic container instantiated at the type — the slot is written T there, so the check follows the type argument and not the spelling

type Age = int within 0..150

var a: Age = 8
var slot: Option[Age] = Some(a)
var p = &a

*p = 41

print(a, slot.unwrap_or(0))

41 8

And the two sites that are the type’s own doing rather than a slot’s:

an operation on a derived subtype, which gets the base’s catalogue producing itself — so Slot(199) + Slot(1) is a produce site and traps. A transparent subtype has no such site: its arithmetic happens at its base and yields a base value, checked by the store that gives it the subtype again.
a compound assignment and an increment, which compute and store in one step and so are checked between the two. a += e produces exactly what a = a + e produces: what the operator is applied to is a base value either way, so t += 120 on a Temp = int within -100..100 holding -50 is 70, and not a complaint that 120 is no temperature.

A value that already has the type is not re-checked when it is merely read, passed along, or copied — it could not have got there unchecked. Passing one to a different subtype over the same base is a produce site and is checked again, which is what keeps a wider type from leaking into a narrower one.

A constrained type has no zero value

The one site that is closed by not existing:

type Age = int within 0..150

var a: Age

print(a)

Age has no zero value, so 'a' needs an initial value

That holds whether or not the range contains zero. Making it the type’s rule rather than the range’s means widening a range never silently changes whether a declaration compiles somewhere else.

A violated check traps, and there is no `try`

It is not an error value and it is not catchable. A constrained type states something its values are, so a value that is not one of them is a bug in the code that made it rather than a condition to handle — which means the fallible constructor an enum has is deliberately absent here, and the diagnostic says so by name:

type Age = int within 0..150

print(Age.try(5))

'Age' is a constrained type and has no 'try': a value outside its range is a mistake in the code that produced it rather than a condition to handle, so 'Age(x)' checks it and traps, and 'Age::Valid(x)' asks the question without trapping

What the type’s own name offers: `::` attributes

A constrained type’s name is a type and not a value, so nothing is read from it. What it answers are attributes, written with :: rather than . so they stay out of the member namespace: Age::First cannot be confused with a field, a property or an associated function, and no impl can shadow one by declaring a member of that name.

The set is small and closed, and every member of it is a question about integer bounds:

written	is	notes
`T::First`	the lower bound	a `T`, a constant, no argument
`T::Last`	the upper bound	a `T`; one below the written bound where the range is exclusive
`T::Valid(x)`	whether `x` is in range	takes the base; a `bool`, and total — it never traps
`T::Succ(x)`	the next value	a `T` from a `T`; traps at `T::Last`
`T::Pred(x)`	the previous value	a `T` from a `T`; traps at `T::First`
`T::Range`	the range itself	only as a `for` loop’s iterable, `First..Last` inclusive, the variable a `T`
`T::Min` / `T::Max`	the same two numbers	the magnitude question, which agrees with the ordinal one here — see below

Min/Max are not aliases of First/Last, and the reason matters where the two come apart. First and Last name the ends of a declared sequence; Min and Max the extremes a type can hold. A within range is written in order, so both questions have the same answer here and both are offered — refusing Min on the one kind of type whose whole purpose is bounds would be the odd outcome, and a reader who met Min on u32 should not find it renamed on a subtype of u32. A simple enum answers only First/Last, because that is where they diverge: discriminants may be explicit and non-contiguous, so the first-declared variant need not carry the smallest one. An integer type answers only Min/Max, on the attributes page.

type Slot = new u8 within 0..<8

print(u8(Slot::First), u8(Slot::Last), Slot::Valid(3), Slot::Valid(9))
print(u8(Slot::Succ(Slot(3))), u8(Slot::Pred(Slot(3))))

var total = 0

for k in Slot::Range do total += int(u8(k))

print("sum of every slot:", total)

0 7 true false
4 2
sum of every slot: 28

Every attribute but Valid speaks the subtype. A bound of T is a value of T, the step from one T is another, and the values Range walks are Ts. That is invisible on a transparent subtype, where T and its base agree anyway — it is what makes the set usable on a derived one, which would otherwise be the only kind of type whose own attributes had to be cast back into it. A new subtype exists to stay out of its base’s traffic, and an attribute surface that handed back the base would make its own declaration the thing you had to undo to use it.

Valid is the exception, and the asymmetry is its job. It takes the base, because asking whether a value is a T is only a question about something that is not one yet. Handed a T it is refused, since the answer could only be yes:

type Slot = new u8 within 0..<8

print(Slot::Valid(Slot(3)))

'Slot::Valid' takes a byte, not Slot

The numbers it can be asked about are therefore the ones the base can hold, so a subtype over a u8 cannot be asked about -1. That is not a narrowing of the question; it is the base’s range being what a base is.

Valid is the answer to “how do I ask instead of trapping”. A produce site traps because a value outside the range is a mistake and not a condition; Valid is how a program holding a number it has not vetted puts the question, and a cast after a Valid that answered true is the ordinary way in.

Succ and Pred trap rather than saturating or wrapping, on the same argument: a step past the end is not a value of the type, so making one is the mistake, and no single answer would be right for every caller.

Two shapes are refused. Range is meaningful only where an iterable is — it names nothing a program can hold, because a range is not yet a type a program can name:

type Slot = new u8 within 0..<8

var r = Slot::Range

print(r)

'Slot::Range' is only meaningful as the iterable of a 'for' loop

And a subtype over a float or a char, or one written with no range, has no attributes at all — each of these is a question about integer bounds, and there are none to ask about. The diagnostic names the part that would have to change:

type Ratio = new f64 within 0.0..1.0

print(f64(Ratio::First))

'Ratio::First' needs an integer subtype, not real

type Plain = new int

print(Plain::Last)

'Plain::Last' needs a 'within' range

Struct invariants

A struct body may carry invariant <bool> clauses among its fields. The clause is an expression over the struct’s own fields, in scope by name, and several clauses all have to hold — each checked independently, so the diagnostic names the one that failed:

struct Window
    lo: int
    hi: int
    invariant lo <= hi
    invariant hi - lo < 4096

var w = Window(2, 10)

w.hi += 5

print(w.lo, w.hi, w.hi - w.lo)

2 15 13

An invariant may read a module constant. invariant is contextual here too, and the grammar disambiguates by shape: a member declaration has a parameter list or a ->, an invariant clause is the word followed by an expression, and anything else is a field — so a field may still be named invariant, as the Cfg example above showed, since invariant: int matches neither of the first two.

Checked at every write, not only at construction

That is the part worth stating, because the cheap implementation checks the constructor and calls it done. The obligation covers:

constructing the struct, including one built directly as an argument or as a returned value
assigning a whole struct over an existing one
assigning a single field, including a compound assignment (w.hi += 1) and an increment (w.hi++)
a field written through a pointer
a field written into an array element
a field written inside one of these — o.a.n = 9, or g.items[0].n = 9

That last one is owed for a reason a narrow reading misses. A clause may read through a field: invariant a.n <= b is legal, and a.n is then not a field of the struct at all, so the write that breaks it is a write the struct never sees. The obligation is therefore on every struct a place is written inside, not only on the one whose field is named last, and the checks nest innermost-first — so the smallest struct the write broke is the one that stops it. An index locates a place rather than owning one, so it contributes no check and is walked through.

The consequence is the intended one: a sequence of writes that ends in a valid state but passes through an invalid one traps at the step that broke it. There is no “I am mid-update” mode.

The multiple assignment is the exception that proves it — it lands both writes before either invariant is consulted, so a pair that ends legal is legal even where each half alone would not be:

struct Window
    lo: int
    hi: int
    invariant lo <= hi

var w = Window(2, 10)

w.lo, w.hi = 6, 8

print(w.lo, w.hi)

6 8

The pair that needs it is the one that crosses: w.lo = 12 followed by w.hi = 14 traps at the first write, because 12 is briefly above the 10 still in hi. w.lo, w.hi = 12, 14 does not, and the two writes land on a struct that was legal before and is legal after.

When a struct cannot be updated one field at a time

Three answers, and the order matters, because the last one is the expensive one and it is the one reached for first:

Look for an order in which no intermediate state is illegal, and often there is one. A count <= high watermark is updated by raising the ceiling before the floor, and needs nothing else; the same two writes in the other order are refused. That the same clause accepts one order and refuses the other is the whole of the answer here.
Ask whether the clause is pointing at a redundant field. An invariant relating two fields is a claim about the representation, and the trap is often the compiler observing that the struct carries one fact twice. A ring buffer keeping head, tail and count cannot move any two of them one at a time; one keeping head and count and computing the end has no clause to break, because nothing is left to disagree. Two of the three fields is the honest design either way.
Otherwise assign the whole struct, which is what whole-struct assignment is for — and know the price. *self = Ring(self.buf, …) restates the whole value to move two bytes, so an invariant across two fields makes a container’s own update cost the size of the container. For a buffer, that is its entire storage, per element.

What may be aliased

Everything above is discharged by walking outward through the place being written, so the whole obligation rests on the place still naming the struct. A pointer is where that runs out — inside a function taking a *Inner, there is no Outer to re-read and no way to learn there ever was one.

It is therefore a rule about what may be aliased, and it restricts alias creation, which is local and a question about types, rather than alias use, which would need the borrow checker sysl does not have. Four parts, and none of them applies to a program that declares no invariants — each is a question asked about a clause, and there is no clause to ask about.

A pointer that would be typed below a clause is refused where it is made:

struct Inner
    n: int

struct Outer
    a: Inner
    invariant a.n <= 10

var o = Outer(Inner(1))
var bad = &o.a

print(bad.n)

'&' here makes a '*Inner' pointing inside Outer, whose invariant reads 'a.n' — and a '*Inner' names no Outer, so a write through it would break the clause with nothing left to re-check it against. Take the address of the Outer itself, which keeps the invariant in its type, or make the change through a method

A writable view is the same licence to write by another spelling, and is refused the same way:

struct Inner
    n: int

struct Group
    items: [4]Inner
    invariant items[0].n <= 10

var g = Group([Inner(0), Inner(0), Inner(0), Inner(0)])
var view = g.items[0..<2]

print(view.len)

this view may be written, and it views storage inside Group, whose invariant reads 'items.n' — a '[]Inner' names no Group, so a write through it would break the clause with nothing left to re-check it against. Take it as a '[]const Inner', which may not write, or make the change through a method

A []const T is ordinary, since giving up the write is exactly what makes a view carry no promise it could break. So is &o itself, whose *Outer names the struct and is checked by the ordinary walk. And so is a pointer to a field no clause mentions — the refusal is about the clause, not about the struct:

struct Inner
    n: int

struct Outer
    a: Inner
    c: int
    invariant a.n <= 10

var o = Outer(Inner(1), 0)
var cp = &o.c

*cp = 9

print(o.a.n, o.c)

1 9

A mutating method call on such a field is allowed, and re-checks the clause when it returns. o.a.set(4) hands set the same severed *Inner — and it is allowed because the call site still knows the whole place: o is right there, so the clause is re-run the moment the call returns:

struct Inner
    n: int

    set(*self, v: int)
        self.n = v

struct Outer
    a: Inner
    invariant a.n <= 10

var o = Outer(Inner(1))

o.a.set(4)

print(o.a.n)

Since there are no parameter modes, a receiver is the only way a callee is handed somewhere to write without an & in the caller’s own source — which is why this one channel is worth keeping open, and why keeping it open costs a mutating method nothing.

A *self method may not let a pointer into its receiver outlive the call. That is what makes the paragraph above sound: a set that returned &self.n would hand out the severed alias by a route no & in the caller spells:

struct Cell
    n: int

    leak(*self) -> *int = &self.n

struct Holder
    c: Cell
    invariant c.n <= 10

a '*self' method may not let a pointer into the receiver's own storage outlive the call, and this one is returned — the receiver may be a field of a struct whose invariant reads it, and a pointer that gets out is somewhere to write that names no such struct. Hand back a copy of the value, or an index into it, and let the caller reach the storage through the receiver it already has

The check is local to the body, and it is asked only of methods whose struct can be a field of one carrying clauses — a struct that lies inside nothing can never have a severed receiver, so its methods are left alone. Storage on the far side of a reference or a view is not the receiver’s to lose either, so &self.bytes[0] where bytes is a []u8 field is ordinary.

A clause may only read storage the struct owns. All of the above is a rule about aliases of the struct’s own bytes, so a clause reading through a pointer, a reference, or a view’s elements is refused where it is written:

struct Inner
    n: int

struct Ptr
    p: *Inner
    invariant p.n <= 10

an invariant may only read storage the struct owns, and 'n' is read through *Inner — what is on the far side has an identity of its own, so another alias of it could break the clause with nothing left to re-check it against. Hold the value in a field of the struct, and state the invariant over that

A view’s len is on the near side — the three words are stored in the struct — and may be read.

What none of this does is make a *T safe, and it does not try to. A pointer handed to a third function that stores it is out of reach of a local check, exactly as the memory model says every guarantee about a raw pointer is. What the rule buys is that the silent severing — the one that looks like ordinary code, reads like ordinary code, and leaves a clause quietly false — is refused.

Generic structs

Invariants on a generic struct are not supported, and say so:

struct Gen[T]
    v: T
    invariant true

invariants on generic structs are not supported yet — 'Gen'

The open question is what a clause over a field of type T could even mean when nothing about T is known. Most useful invariants compare, which needs a bound — and a bound the struct carries is inherited by every member, so the machinery is there.

Contracts on a function

half(x: int) -> int
    require x >= 0, "a half of a negative is not what this means"
    ensure result >= 0

    x / 2

print(half(10), half(7))

5 3

require is checked on entry. ensure is checked before every return, including early ones — an early return that violates the postcondition traps exactly as the fall-through path would. Both take an optional message after a comma.

Both kinds form one block at the top of the body. A clause of either kind after an ordinary statement is rejected — a precondition that runs after some of the work is not a precondition, and a postcondition is written with them because that is where a reader looks for what the function promises, not because that is when it runs. Clauses may not be nested inside an inner block either:

f(x: int) -> int
    var y = x + 1

    require y >= 0

    y

'require'/'ensure' clauses must come before any other statement in a function body

`result` and `old`

Two names exist only inside a contract.

result is the value being returned, available in an ensure only. It is rejected in a require — there is no value yet — in an ordinary statement, and in the ensure of a function that returns nothing:

h(x: int) -> int
    require result >= 0

    x

'result' is only meaningful inside an 'ensure' of a value-returning function

A local actually named result shadows it, which is the ordinary scoping rule rather than a special case:

triple(n: int) -> int
    ensure result >= 0

    var result = n * 3

    result

print(triple(4))

old(expr) is expr evaluated on entry, available in an ensure only. It takes exactly one argument, and several old snapshots in one function are independent of each other. This is what lets a postcondition talk about what a mutating function changed rather than only about what it left behind:

struct Counter
    n: int
    m: int

    both(*self)
        ensure self.n > old(self.n) && self.m > old(self.m)

        self.n += 1
        self.m += 2

var c = Counter(0, 0)

c.both()
c.both()

print(c.n, c.m)

2 4

Contracts work the same on a method, including one with a *self receiver, where they are at their most useful: ensure result > old(self.n) on a mutating method says the thing the method is for.

Like a constraint, a violated contract traps, and contracts are checked in every build. There is no release mode that drops them, and adding one would make a program’s meaning depend on how it was compiled.

The third shape: a latch

Result and a trap are the two channels for an operation that failed. A stream is the case neither fits well, and the library answers it with a third shape — a trait whose one member reports whether the stream has gone wrong:

struct Meter
    written: int
    bad: bool

    put(*self, n: int)
        if n < 0 then self.bad = true
        else self.written += n

impl Fallible for Meter
    override failed(*self) -> bool = self.bad

var m = Meter(0, false)

m.put(3)

print(m.failed(), m.written)

m.put(-1)

print(m.failed(), m.written)

false 3
true 3

Fallible is required by both Writer and Reader, which is what lets one open file be both — two traits each declaring a failed for one type could not be told apart at a call, because failed takes no arguments and so nothing about the call could say which was meant.

It latches rather than returning, and that is the shape everything above it is built on: an implementation stays straight-line, print(x) stays a statement, and a caller asks once after a run of operations rather than after each. Whether a stream ended is a separate question from whether it ended badly, which is why reading answers the first with an empty result and leaves this to answer the second.

The default is false — most streams cannot fail, and one that cannot should not have to write down that it cannot, so an impl with an empty body is a complete one.

What is deliberately absent

absent	instead
exceptions, `throw`, `try`/`catch`	a returned value, or an abort. There is no third, invisible control-flow channel
error return codes by convention	`Result`, in the type, checked — not an `int` a caller might forget to inspect
a `panic` that unwinds	a trap is terminal
a `try` on a constrained type	`T::Valid(x)`, then the ordinary cast
a build flag that strips checks	every check is in every build
a contract discharged instead of checked	it is a branch and a trap wherever the value is produced, whether or not a prover has been over it

Nothing on this page is proved while compiling: a require is a branch and a trap, an invariant is a call to a synthesised predicate, a within is two comparisons. What that buys is that the failure lands where the mistake is — plus, for new types, a compile-time guarantee that has nothing to do with the checking at all.

Proving is a separate tool and it removes nothing. Verification adds the specification vocabulary — quantifiers, loop invariants, termination measures, @pure and @ghost — and sysl prove, which discharges the obligations with Why3. A clause proved redundant is still compiled, because a program whose emitted code depended on whether a prover had been available is one nobody could reason about. That is why the row above says instead of: the two are additive.

Next: the foreign interface.

Enums and patterns

2026-08-16T01:26:07.924728867Z

One keyword covers two things a lot of languages spell separately: a named-constant set, and a sum type whose variants carry data. Which one you get is decided by whether any variant has a payload, so there is no second keyword to learn and no way for two declarations to disagree about which kind this is.

A named set of constants

enum Color
    Red
    Green
    Blue = 10
    Yellow

name(c: Color) -> string
    c match
        Red    -> "red"
        Green  -> "green"
        Blue   -> "blue"
        Yellow -> "yellow"

print(name(Blue), int(Blue), int(Yellow))

blue 10 11

The discriminant rule is C’s: a bare variant is the previous one plus one, starting at zero, and an explicit = 10 is a value the counting continues from. What is not C’s is that Color is its own type — a Color and an int do not mix without the conversion being written, which is what makes this a type-safe constant set rather than a bag of integers.

Two variants may not stand for one value, however the collision arises. A simple enum’s value is its identity, so two names for one number would be one value with two spellings, and the second one’s match arm could never run. Deliberately naming a value twice is what a const is for.

Pinning the width

C leaves an enum’s underlying integer type implementation-defined, which makes it useless for the two things a systems programmer most wants it for: a struct field of known width, and a value read off a wire. sysl lets you say:

enum Pin: u8
    A0
    A1
    A2

print(Pin::Image(A1), Pin::Pos(A2), int(Pin::Last))

A1 2 2

The type after the : may be any integer type, including an arbitrary-width one like u4 — which turns a simple enum into a usable tool for packed hardware-register fields. Unspecified, it is int.

Those :: names are a fixed set of questions the enum’s own name answers, kept out of the member namespace so they can never collide with a variant. Image gives a variant’s name as a string, Pos gives its 0-based position in the declaration, Val goes back the other way, First/Last are the ends and Succ/Pred the neighbours.

Position is not the discriminant, and that is why both exist: discriminants may be explicit, non-contiguous and not zero-based, so an ordinal has to be looked up rather than computed. A value’s discriminant is int(c); its position is Pos.

Coming from an integer

Going to the underlying integer is total — every enum value is a valid integer. Coming from one has two spellings, chosen by how much you trust the value:

enum Color: u8
    Red
    Green
    Blue

print(Color::Image(Color(1)))

Color.try(7) match
    Some(c) -> print("got", Color::Image(c))
    None    -> print("7 is not a Color")

Green
7 is not a Color

Color(n) is a checked cast that traps on an integer no variant declares — the fast path for a value already known good. Color.try(n) returns an Option, and it is the required path for bytes off a wire. That closes C’s other enum hole, where every int is silently a valid enum value, the same way the char rules close it for codepoints.

Variants that carry data

Give a variant a payload and the same keyword builds a sum type:

enum Shape
    Circle(radius: int)
    Rect(w: int, h: int)
    Empty

area(s: Shape) -> int
    s match
        Circle(r)  -> 3 * r * r
        Rect(w, h) -> w * h
        Empty      -> 0

print(area(Circle(2)), area(Rect(3, 4)), area(Empty))

12 12 0

Constructing is calling the variant — Circle(3), with no Shape. to write, because a variant name is in scope as a constructor of its own enum. A nullary variant like Empty is legal in either kind of enum and reads the same in both.

Which memory mode the result takes follows the ordinary rule from the memory chapter: a data enum is a value, sized for its widest variant plus a tag, and it lands on the heap only where a &Shape is expected. Being a sum type changes nothing about the three modes — an enum is a struct-shaped value with a tag on it.

The payload really is one region, not one field per variant. A four-variant enum carrying one integer each is one integer wide, so a table of two hundred of them costs what you would expect rather than four times that.

The check that makes it worth having

A match on a data enum must cover every value, and the diagnostic names what is missing:

enum Shape
    Circle(radius: int)
    Rect(w: int, h: int)

area(s: Shape) -> int
    s match
        Circle(r) -> 3 * r * r

match on 'Shape' is not exhaustive; missing Rect (add an 'else' arm)

That is the central payoff of a closed set of variants: adding one turns every match on the enum into a checked to-do list rather than a bug that shows up at run time.

Coverage is about which values are guaranteed handled, not which tags appear, and the arms answer that question together. Some(Circle(r)), Some(Rect(w, h)) and None cover an Option[Shape] between them though no single arm covers a variant on its own — while Some(0) alone does not cover Some, because a Some holding anything else slips through.

A guarded arm never discharges a variant’s obligation, since the compiler cannot prove a guard holds. That is what keeps exhaustiveness a real guarantee instead of a formality.

`Option` and `Result` are just enums

Nothing above is special-cased for them. They are ordinary generic declarations in the library:

first_even(xs: []const int) -> Option[int]
    for x in xs
        if x % 2 == 0 then return Some(x)

    None

var data = [1, 3, 6, 7]

first_even(data) match
    Some(n) -> print("found:", n)
    None    -> print("none")

found: 6

That is worth knowing early, because it means everything this chapter says about matching, binding and exhaustiveness is what you already know about Option — and everything you learn about Option transfers to an enum you write yourself.

What a pattern can be

Literals, ranges, alternatives, bindings and guards, in the order the arms are tried:

classify(n: int) -> string
    n match
        0                    -> "zero"
        1 | 2 | 3            -> "small"
        4..10 if n % 2 == 0  -> "medium even"
        4..10                -> "medium odd"
        else                    "large"

print(classify(0), classify(2), classify(6), classify(7), classify(99))

zero small medium even medium odd large

Arms are tried top to bottom and the first whose pattern matches wins, so a failed guard falls through to a later overlapping arm — which is why the two 4..10 arms read as “even, otherwise odd” rather than as a contradiction. The scrutinee is evaluated exactly once, whatever the arms do.

The else arm carries no ->. The arrow separates a pattern from what to do when it matches, and else is not a pattern — it is the fallback, and it takes its body the way an if‘s else does.

Ranges are limited to the numeric types and char, where a contiguous interval means something. Literals work on anything == can test, including string and bool — so matching a boolean with true -> and false -> arms is exhaustive with no catch-all needed.

Destructuring a struct

Two forms, and they are a division of labour rather than two spellings of one thing:

struct Point
    x: int
    y: int

locate(p: Point) -> string
    p match
        Point(0, 0) -> "origin"
        Point{x: 0} -> "on the y axis"
        Point{y: 0} -> "on the x axis"
        else           "somewhere"

print(locate(Point(0, 0)), locate(Point(0, 5)), locate(Point(5, 0)), locate(Point(1, 1)))

origin on the y axis on the x axis somewhere

Positional is total. It mirrors construction, and it must name every field — so adding a field to the struct turns each positional pattern into a checked arity error, exactly as a new enum variant does. This is the handle-everything tool.

Named-field is partial. It binds by name, so it survives a field reorder, it can rename ({x: a}), and any field left out is simply unconstrained. Adding a field never breaks one. This is the grab-what-I-need tool.

Both nest inside each other and inside variant patterns — Some(Point{x}), Wrap(Point(a, b)) — and every sub-pattern is itself any pattern in this section.

The bare-name trap, closed

A bare identifier in a pattern is a nullary-variant pattern when it names one, and a binding otherwise. The dangerous middle case is a name that is a variant but carries data, and it is a hard error rather than a silent catch-all:

enum Shape
    Circle(radius: int)
    Empty

describe(s: Shape) -> string
    s match
        Circle -> "circle"
        Empty  -> "empty"

variant 'Circle' carries data — match it as 'Circle(…)'

Without that rule, Circle would have quietly become a binding that matched everything, and the Empty arm below it would have been dead code the compiler was happy with.

Matching through a reference

Field selection dereferences one level on its own, but match does not. Matching a &Enum is written match *e, which keeps “am I matching the reference or the thing” a visible question:

enum Tree
    Leaf(value: int)
    Node(left: &Tree, right: &Tree)

total(t: &Tree) -> int
    *t match
        Leaf(v)    -> v
        Node(l, r) -> total(l) + total(r)

var t: &Tree = Node(Leaf(1), Node(Leaf(2), Leaf(3)))

print("sum:", total(t))

sum: 6

That is also the shape a recursive enum takes: a variant holding its own enum by value would be infinitely sized, so recursion goes through a &T or a *T — the same indirection rule the memory chapter gives for structs.

Binding a &T payload out of an enum retains it, so the extracted reference outlives the enum it came from and the count stays exact. That is not a rule about patterns; it is ARC’s retain-on-alias applied to the temporary a binding introduces.

One shape, and nothing to say about the rest

match asks a value to choose between several shapes. Very often a program cares about one, and exhaustiveness then makes it pay for the arms it did not want — a one-arm match on an Option is forced to write a do-nothing catch-all.

expr is Pat tests a pattern and yields a bool, binding whatever the pattern names:

find(xs: []const int, target: int) -> Option[usize]
    for i in 0..<xs.len
        if xs[i] == target then return Some(i)

    None

var data = [4, 5, 6]

if find(data, 5) is Some(i) then print("at index:", i)

if find(data, 9) is not Some(_) then print("nine is not there")

at index: 1
nine is not there

The right side is a match arm’s left side, entire — a literal, a range, a variant, a struct, nested to any depth, and | alternatives. Terms chain with &&, which is what keeps the form from evaporating the moment a condition appears:

struct Row
    active: bool
    age: int

lookup(id: int) -> Option[Row]
    if id == 1 then Some(Row(true, 30))
    else None

if lookup(1) is Some(row) && row.active && row.age is 18..65 then
    print("admitted at", row.age)

admitted at 30

An is is a term of an if‘s or a while‘s condition and is legal nowhere else — not under ||, not under !, not on the right of an =. The restriction is about the binding, not the boolean: everywhere else in sysl a name is introduced by a declaration whose scope you can see from the indentation, and confining is to a condition is what keeps the answer to “where does this name hold something?” to one sentence.

A binding is live from its own is rightward through the rest of the condition, and through the branch that condition guards.

|| is excluded by that sentence rather than by a separate rule: there is no path through a is P(x) || b on which x was bound. A while‘s bindings are per-iteration — made by the test, released at the bottom of the body — which is what makes the drain loop the natural spelling and keeps a loop over a million elements holding one round’s refcounts rather than a million.

Two things is will not do. A pattern under is not may not bind, since it would name something on the one path where nothing matched it — x is not Some(_) is the form that was wanted. And a pattern that cannot fail is refused rather than folded away to true: x is n is a declaration wearing a test’s clothes.

Next: error handling — Result, the ? operator, and the line between an error and a trap.

The encoding module

2026-08-16T01:26:07.924728867Z

sysl.encoding turns bytes into text and back, and integers into bytes and back. Three files, one error type, and no allocator required for any of the core surface.

import sysl.encoding.{hex_string, base64_string, Standard}

print(hex_string("foobar".bytes))
print(base64_string("foobar".bytes, Standard, true))

666f6f626172
Zm9vYmFy

The two directions are shaped differently, on purpose

Encoding writes to a Writer. That means hex straight to a file or to standard output with no intermediate string — which is the case that actually matters for a codec.

import sysl.encoding.hex_encode

hex_encode("hi".bytes, stdout())
print("")

Decoding writes into a slice the caller supplies, and answers how many bytes it wrote. The output length is computable before anything is read — half the text for hex, three quarters for base64 — so there is nothing to discover by allocating, and the module stays usable where there is no allocator. hex_decoded_len and base64_decoded_len are exported so a caller can size the slice.

import sysl.encoding.{hex_decode, hex_decoded_len}
import sysl.text.from_utf8

val text = "666f6f".bytes
var out: []u8 = [0; 8]

print(hex_decoded_len(text))
print(hex_decode(text, out).unwrap())
print(from_utf8(out[0..<3]).unwrap())

3
3
foo

The _string conveniences beside each encoder are the only things in the module that allocate, and they exist because assembling a sink for the common case would be the library refusing to do the easy half.

base64 has two axes, and they are parameters

The alphabet and the padding are independent, so naming every combination ends at base64_encode_urlsafe_nopad. An enum and a bool say the same thing and compose.

import sysl.encoding.{base64_string, Standard, UrlSafe}

var bytes: []u8 = [0xfb, 0xff, 0xbf]

print(base64_string(bytes, Standard, true))
print(base64_string(bytes, UrlSafe, true))
print(base64_string("fo".bytes, Standard, false))

+/+/
-_-_
Zm8

Decoding accepts either alphabet without being told, which costs nothing: +/ and -_ do not overlap, so there is no input the two readings disagree about. Padding is optional on input and checked when present. That asymmetry is deliberate — a writer should be exact and a reader should be forgiving about what cannot be ambiguous.

What a refusal says

DecodeError has four cases, separated by what a caller would do about each rather than by taxonomy.


`BadByte(at)`	a byte outside the alphabet, and where
`BadLength`	not a whole number of encoded units
`BadPadding(at)`	`=` somewhere it cannot be
`Short(needed)`	the output slice is too small, and by how much

Short carries the length that would have been enough, so a caller resizes once rather than discovering the requirement a byte at a time.

import sysl.encoding.{hex_decode, BadByte, Short}

var out: []u8 = [0; 8]
var tiny: []u8 = [0; 1]

val bad = hex_decode("66zz".bytes, out) match
    Err(BadByte(at)) -> s"bad byte at $at"
    _ -> "something else"

val short = hex_decode("666f6f".bytes, tiny) match
    Err(Short(n)) -> s"needs $n bytes"
    _ -> "something else"

print(bad)
print(short)

bad byte at 2
needs 3 bytes

It is a type of its own rather than sysl.text‘s ParseError, which is about reading a number out of text: two of that type’s four cases could never occur here, and a caller matching on it would be told cases exist that cannot.

Fixed-width integers, at either byte order

import sysl.encoding.{get_u32_be, get_u32_le, put_u16_be, get_u16_be}

var b: []u8 = [0x11, 0x22, 0x33, 0x44]

print(get_u32_be(b).unwrap())
print(get_u32_le(b).unwrap())

var w: []u8 = [0; 2]

print(put_u16_be(w, 0xbeef))
print(get_u16_be(w).unwrap())

Reading answers an Option and writing a bool, rather than trapping: walking a buffer whose length came from somewhere else is the ordinary use, and running off the end of one is an expected condition there rather than a program’s mistake.

These are free functions at concrete widths, and that is exactly why they can exist. sysl.math‘s Bits trait deliberately has no swap_bytes, because every member of that trait must be total over every integer type and a u24 has no byte order at all. Nothing here is a trait member, so nothing here reopens that — get_u32_le names its width, and the widths written are the ones with a whole number of bytes.

Unsigned only: the signed read of the same bytes is a cast at the call site, and doubling a twelve-function surface to spare one cast is not a trade worth making.

Declarations

2026-08-16T01:26:07.924728867Z

A declaration is a statement, so anything that can be declared at the top of a file can also be declared inside a function body. A helper function used by one function belongs inside it, and needs no separate rule to allow it.

Bindings

Three forms, and the differences between them are about when the value is fixed rather than about where it lives.

form	mutable	value	type
`var name = v`	yes	optional — a `var` may be declared and assigned later	optional
`val name = v`	no, written once	required	optional
`const Name: T = v`	no, and known while compiling	required	required

The type is mandatory on a const and optional on a val, and that arrangement is deliberate in both directions. A const states an interface — its value is substituted where it is used, so what that value is matters less than what it is a value of. A val has its type readable off the value it was given, and a val with no value is not a declaration of anything.

The value may be an indented block

A binding’s = takes one expression, or an indented block whose trailing expression is the value — the same arrangement a function body has, and the same one an if branch has. What the block binds is the block’s own, and goes out of scope with it:

val limits =
    val raw = 7
    val capped = raw * 2

    capped

print(limits)

Reach for it when the value takes more than one step to work out. The alternative is a name in the enclosing scope that exists only to be read once on the next line, which says the value is available to everything below when it is not.

It composes with the branching forms rather than competing with them — an if too long for its line goes on the line under the =, which is the shape the form was built for:

pick(c: bool) -> int
    val n =
        if c then
            val a = 3

            a + 1
        else
            0

    n * 10

print(pick(true), pick(false))

40 0

A block of one expression is that expression. Moving a value to the next line to fit the margin changes nothing else about the declaration: a module val written that way is still laid into the object file, rather than becoming something the program computes before it starts.

A block that ends in something other than an expression yields unit, exactly as an if with no else does, and the complaint arrives where the value is used rather than where it was bound.

A const does not take one. A constant is folded into every use of it rather than run, so there is nowhere for the statements to happen. Its value may still sit on the next line — that is one expression rather than a block, by the rule above — and what is refused is a block that binds something:

const Limit: int =
    val base = 3

    base * 2

print(Limit)

'Limit' is a 'const', so its value is folded into every use of it

A module member states its type

Where a binding is a member of a module rather than a local, the annotation stops being optional even on a val. That is a rule about where the binding was written, so the grammar accepts either form and the analyzer applies the rule.

It is worth reading as one rule rather than two, because it is one: anything visible outside its file states its types, and a module member always could be, while a local states nothing to anyone and so infers exactly as a var does. Most of it the syntax already enforced — a parameter type and a field type are mandatory, and an absent return type means unit rather than being inferred — so a module-level binding is simply the last declaration the rule had left to reach.

The payoff is that interface extraction is parse-only. A file’s exported surface can be read off its syntax tree without resolving a name, checking a body, or having compiled anything the file imports, which is what lets the collect pass depend on nothing but parsing — and that is what a fast, parallel, eventually incremental build rests on. Scala infers types for public members and pays for it with a far heavier extraction step; this is a deliberate divergence, and a cheap one here because sysl’s signatures were already explicit for other reasons.

const Limit: int = 3
static val Scale: int = 2

show()
    var count = 0
    val doubled = Limit * Scale
    val name = "sysl"

    count += 1

    print(count, doubled, name, Limit)

show()

1 6 sysl 3

The two vals in that program are one keyword doing one thing: the module member says : int because it is visible outside its file, and the one inside show is visible to nobody and does not have to. The static is what asks for the member — this is the file the program starts in, so a plain val there would be a local of its body, and a local infers exactly as a var does.

A module-level val may hold a counted value, and never releases it. Storage that exists for the whole run is never let go of, so the one release with nowhere to go is the one at exit — and not taking it is what a static is. A &T, a weak T, a slice and a string the program builds are all admissible:

static val name: string = str(2026)

print(name)

That was refused until the reason was read again, and what it cost was every shape that needs a value to outlive every frame. What the initializer is still decides where the storage gets filled — a literal‘s bytes are a constant in the object file and its owner word is null, so nothing is allocated and the storage is complete before the program starts, while a built value is stored by a prologue. That difference is why a module with no alloc may still hold a table of literals:

val greeting: string = "hello"
val names: [3]string = ["alpha", "beta", "gamma"]

var i = 1

print(greeting, names[i])

hello beta

This is what a module with no allocator uses for its messages. A const could not serve it: a constant is folded into its uses and has no address, so it cannot be indexed at a position computed while running. Anything the program had to build is a local instead, which is ordinary — that is what the first program above does with its val name.

A raw pointer may be held, because it counts nothing and so there is no release to write. What a val promises is that its own storage is written once and never again, and holding an address keeps that promise exactly as holding a number does. This is the shape that has no substitute — a device register block named at file scope, reached by every function in the driver rather than re-materialised in each:

const UART: usize = 0x1000_0000
val regs: *Uart = ptr_cast(UART)

An address that is a constant is laid into the object file rather than stored by a prologue, so a val at pointer type needs nothing ordered and is readable before the first initializer runs — which is what a freestanding program starting at a reset vector requires.

Writing to a val twice is refused:

show()
    val name = "sysl"

    name = "other"

    print(name)

show()

a 'val' is written once, so assignment has nothing to write through

Read-only means read-only at every depth. k = …, k[0] = …, k[0] += 1 and k[0]++ are all refused on a module-level val, and so is &k[0] — a *T is a licence to write, and handing one out would move the mistake one step away from where it could still be reported.

Slicing is allowed, and yields a []const T. That is what lets a table be read and passed rather than only read: the read-only property travels with the view, through a name, through a call, and through a second subscript, so every write above is refused through it too. &v[0] on such a view is a *T, the tier the memory model excludes on purpose, and is how the view reaches C.

The one module-level storage none of this reaches is an extern variable. Every rule above is a promise this program makes about storage it laid down; an extern variable is storage the linker supplies — stdout, environ, optind — so there is no such promise to keep. It is a place, it may be written, and it holds whatever the other side put there.

Several at once

var and val both take a comma list, binding several names to several values. Each part’s type is inferred from its own value.

show()
    val a, b = 1, 2
    var lo, hi = 0, 10

    print(a, b, lo, hi)

show()

1 2 0 10

Two or more names and an initializer are both required: one name is the ordinary form, and a multiple binding with nothing to take apart names nothing. The right side is produced before any name is bound, so a value there still means whatever the enclosing scope calls it — the binding does not shadow itself half way through its own right-hand side.

It is a local form. The parts carry no type annotation and there is nowhere to write one, so a multiple val at the top of a file collides with the rule above and is refused rather than becoming a quiet local of the entry point. A module member that wants the form declares its names separately.

The same spelling also takes a result list and a tuple apart, which is why a function with several results needs no special form at the call.

By pattern, when the shape matters

A comma list says how many things to bind. A pattern says the shape, and so reaches inside a tuple that holds another one — which is the whole of the difference between the two forms.

show()
    val (a, b) = (1, 2)
    val ((x, y), z) = ((3, 4), 5)
    val (first, _) = (6, 7)

    var (lo, hi) = (0, 10)

    hi = hi + 1

    print(a, b, x, y, z, first, lo, hi)

show()

1 2 3 4 5 6 0 11

A _ binds nothing and skips its part. A var pattern makes every name it binds assignable, and a val pattern makes each of them write-once, exactly as the single-name forms do.

A struct pattern stands here on the same terms, naming fields rather than positions. It may name them in any order, may leave fields out, and may rename one to a sub-pattern:

struct Point
    x: int
    y: int

struct Line
    a: Point
    b: Point

show()
    val Point{x, y} = Point(3, 4)
    val Line{a: Point{x: ax}, b} = Line(Point(1, 2), Point(5, 6))

    print(x, y, ax, b.x, b.y)

show()

3 4 1 5 6

A field the pattern does not name simply binds nothing — unlike a match arm, a binding has no exhaustiveness to discharge.

The positional spelling Point(a, b) stands here too, and takes the fields in declaration order. It differs in the one way it differs in a match: it names every field, so a struct that grows one turns each positional binding into a checked to-do rather than one that goes on binding the same names. See Patterns.

Only a pattern that cannot fail may stand at a binding — a tuple pattern, a struct pattern, a name, a wildcard, and those nested inside one another. A struct qualifies because it has exactly one shape, which is the same property that makes a tuple pattern irrefutable.

A literal, a range, or a variant is a test, and a binding has no other arm to take when the test does not match, so each is refused with that as the reason. Those belong in a match (see Patterns).

Like the comma form, this is a local form: the parts have nowhere to carry a type, so one at the top of a file is refused rather than becoming a quiet local of the entry point.

Functions

A name, a parameter list, an optional -> result, and a body. There is no keyword: the shape is what identifies it. An absent result type means unit.

The body is either = expr — whose value is the result — or an indented block, whose trailing expression is the result.

double(n: int) -> int = n * 2

sum(a: int, b: int) -> int
    var t = a + b

    t

greet(name: string)
    print("hi", name)

print(double(21), sum(40, 2))
greet("you")

42 42
hi you

= may also open an indented block, so a body does not have to change shape when it outgrows a line.

Tail calls

A function whose last act is a call to itself does not open a second frame. The call becomes a branch back to the function’s own entry, so the recursion is bounded by the arithmetic rather than by the stack:

count(n: int, acc: int) -> int =
    if n == 0 then acc else count(n - 1, acc + 1)

print(count(1000000, 0))

A million frames is not a stack any machine has. Nothing is written to ask for this — it applies wherever it applies.

In tail position is the last thing the function does: the body’s trailing expression, the operand of a return, and the arms of the if and match those reach through. Nothing may wait on the result — n + count(n - 1) is an ordinary call, because the addition happens after it comes back.

A tail call is a call, so the jump lands where a call would: every require is checked again on the arguments the jump wrote, and every old(e) is snapshotted again. A recursion that violates its own precondition at depth four stops at depth four.

Two things end a tail position instead of being optimized around:

a defer in scope, which runs on the way out of a scope — after the callee returns for an ordinary call, and before it is entered for a jump;
an ensures on the function, which is checked when a call returns, and a tail call never returns.

Either one leaves the function compiled exactly as written.

It is self-recursion only. Mutual recursion and calls through a Fn or a *extern are ordinary calls, however they are written.

`@tailrec`

The jump is silent, which is what you want until an edit takes it away. @tailrec asserts it is there and is refused when it is not:

@tailrec
sum(n: int) -> int =
    if n == 0 then 0 else n + sum(n - 1)

print(sum(5))

calls itself nowhere the jump can replace

It changes nothing about what is emitted — write it on the functions where losing the jump silently would be a bug, and leave it off the rest.

Several results

A signature may declare more than one result, and the trailing expression or return supplies them as a comma list.

minmax(a: int, b: int) -> int, int
    if a < b
        a, b
    else
        b, a

show()
    var lo, hi = minmax(9, 4)

    print(lo, hi)

show()

4 9

This is not a tuple. A tuple is a value with a type of its own; a result list is several values handed back at once, and the multiple binding above is what receives them.

A result list is a whole line by construction, so it cannot be the body of an inline branch: if a < b then a, b else b, a does not parse, because the comma there would have to belong to the branch rather than to whatever expression the branch is part of. The block form above is how a conditional supplies several results.

Default parameters and named arguments

A parameter may say what a call that leaves it out gets instead. The default is a full expression, so a call or a conditional may stand there — it is evaluated at the call site that omitted it, and it may not name anything local to the declaration.

An argument may be written name = value, which stands at the parameter it names rather than at the one its position would have given it.

box(w: int, h: int = 1, fill: string = "*") -> string
    var s = ""

    for i in 0..<w * h
        s += fill

    s

print(box(3), box(2, 2), box(2, fill = "#"))

*** **** ##

name = value is also a legal expression — assignment yields the value stored — so the two readings collide, and the named argument is the one taken. It applies only where the name is a bare identifier: p.x = 1 and b[i] = v are stores as they always were, since neither is a name a parameter list could have written. A store to a plain variable is still reachable in an argument by parenthesizing it.

A closure’s parameter declares no default. A call reaches a closure through the Fn traits, which carry the types and not the names, so there would be nothing at the call to fill one from.

Overloading

A name may be declared more than once, and every use of it still means exactly one declaration. Which one is decided by the arguments a use passes: how many, and what type each is.

show(x: int) -> string = s"int $x"
show(x: string) -> string = s"str $x"
show(x: int, y: int) -> string = s"pair $x $y"

print(show(1))
print(show("a"))
print(show(1, 2))

int 1
str a
pair 1 2

The result is never part of it. A pair differing only in what they return is refused where the second is written. sysl reads an expected type inwards, from the context to the expression, so a call whose meaning depended on its own result would need its context typed before it could be resolved and would need resolving before its context could be typed.

h(x: int) -> string = "s"
h(x: int) -> int = 1

function 'h' is already declared — which declaration a call means is decided by its arguments and never by what it returns, so two that differ only in the result have no call that tells them apart

That is the plain duplicate message with its sentence finished, and the wording is deliberate: the two parameter lists are the same, so this is one declaration written twice. Somebody who wrote that by accident is told so plainly; the clause is added only where the results differ, because that is the pair a reader wrote on purpose and expected to work.

The rule behind it is wider than the identical case. Each declaration takes a range of argument counts — from its parameters that have no default up to all of them — and two collide when their ranges overlap at some count and their first that-many parameters agree in type. So a difference hidden behind a default is refused too, and there the point is sharper: the default is unreachable, because no call could ever supply one argument to the longer declaration.

g(x: int) -> string = "one"
g(x: int, y: int = 0) -> string = "two"

'g' is already declared with parameters this one could not be told from — a call passing 1 argument would fit both, and which declaration a call means is decided by its arguments and never by what it returns. Two declarations of one name have to differ in a way a call site can show

Reporting that at the declaration rather than at the call is the point. The mistake is in the pair; reporting it where the name is used would report one mistake once per call site, in files whose authors did not write it.

A use that fits none of them, or several, is refused where the use is, and the message carries the roster — the reader’s question at that point is which declarations exist:

k(x: int) -> string = "a"
k(x: string) -> string = "b"

print(k(1.5))

no 'k' takes these arguments — the declarations of that name are:
    k(x: int)
    k(x: string)

Three tie-breaks decide a use that fits more than one. A candidate that needed no default fitted the call as written and beats one that did; and a candidate whose parameters are exactly the arguments’ own types beats one reached by a conversion — which is what lets a literal’s natural type choose between two widths:

width(x: int) -> string = "int"
width(x: i64) -> string = "i64"

print(width(1))
print(width(1i64))

int
i64

What is deliberately absent is any ranking between conversions. Two candidates each reached by a different one are ambiguous, and saying so beats a ladder of precedences nobody could predict from the source.

Exactness is asked of the types a candidate was fitted at, which for a generic one is what the call solved it to. g[T] below takes the []int at T = []int, as it was written; the other takes it only by giving up the ability to write. So the generic declaration is the exact one:

g(s: []const int) -> string = "const"
g[T](x: T) -> string = "generic"

var a = [1, 2, 3]
val v: []int = a[..]

print(g(v))

generic

The third tie-break is that a candidate that named its parameters beats one that was solved for them, where both are exact. f(x: int) and f[T](x: T) both fit f(0) at int, and the ordinary declaration is the one that said what it takes:

f(x: int) -> string = "plain"
f[T](x: T) -> string = "generic"

print(f(0))

plain

That ranks a declaration against a declaration, which is a different question from ranking the routes the arguments took — the thing the paragraph above refuses.

An address chooses by the type the context wants, which is the mechanism a generic function’s address already uses. With no expected type there is nothing to read, and the address is refused rather than guessed at.

add(a: int) -> int = a + 1
add(a: int, b: int) -> int = a + b

val one: *extern(int) -> int = &add
val two: *extern(int, int) -> int = &add

print(one(41), two(6, 7))

42 13

Overloading an `extern`

Two externs of one name are two functions exactly when they name two symbols. A C library’s naming is not sysl’s, and a family C spells _solid/_shaded/_blended is one operation with an option — which a binding may now say, without inventing a sysl name per C symbol.

extern "strlen" size(s: *u8) -> usize
extern "strnlen" size(s: *u8, cap: usize) -> usize

Two naming the same symbol are refused. That is one C function claimed at two signatures, and the symbol is what gets emitted — both calls would reach the same code with different arguments, and nothing downstream could tell which had been meant.

extern "strlen" size(s: *u8) -> usize
extern "strlen" size(s: *u8, cap: usize) -> usize

'size' is already declared as an 'extern' for the symbol 'strlen' — two declarations of one name are two functions, and one C function cannot be two. Overloads of an 'extern' are told apart by the symbol each names, so give this one a symbol of its own or take its address and 'ptr_cast' it where the other signature is wanted

An extern and a sysl function do not overload each other, in either order, for the same reason: what tells overloads of an extern apart is the symbol, and a sysl function declares none.

Type parameters

A bracketed list directly after the name declares type parameters, with optional bounds. See generics and traits.

Structs

A named product type. Fields are declared one per line; methods, properties and an invariant may follow among them, in any order.

struct Rect
    w: int
    h: int

    invariant w > 0 && h > 0

    area(self) -> int = self.w * self.h

    perimeter -> int = 2 * (self.w + self.h)

    scale(*self, k: int)
        self.w *= k
        self.h *= k
end Rect

var r = Rect(3, 4)

print(r.area(), r.perimeter)

r.scale(2)

print(r.area(), r.w, r.h)

12 14
48 6 8

Four things are on display there.

A constructor is the struct’s name applied to its fields, in declaration order. There is no separate constructor declaration to write or to keep in step.

A field declares no default. What an unwritten field gets is decided by the constructor that builds the value, not by the field — and the compiler says so rather than leaving a = v after a field to fail as whatever the grammar happened to want there.

A property is a method with the parameter list left off — perimeter -> int, called as r.perimeter with no parentheses. It takes the same body forms a method does.

The receiver says how the method reaches its value, and is written as the first thing in the parameter list:

receiver	meaning
`self`	by value — the method gets a copy
`*self`	by pointer — the method may write through it
`&self`	by reference, counted
`&sync self`	by reference, and safe to share across threads
(none)	an associated function — no receiver, called on the type

struct Point
    x: int
    y: int

    origin() -> Point = Point(0, 0)

var p = Point.origin()

print(p.x, p.y)

0 0

`invariant`

A condition every value of the struct must satisfy, re-checked whenever the struct is built or one of its fields is written. Bare field names are in scope inside it. A multiple assignment re-checks it once, after every write has landed, which is what lets two fields that relate to each other be changed together.

invariant is a contextual word — an ordinary identifier everywhere else. See errors and contracts for what happens when one is broken.

A struct with no fields

A struct may declare no fields at all. Its emptiness has to be written — the end marker, optional everywhere else, is what says so — because a struct whose body the author forgot to indent looks exactly like one that has no body, and that is much the likelier mistake.

struct Stdout
end Stdout

impl Fallible for Stdout

impl Writer for Stdout
    write(*self, bytes: []const u8) = putbytes(bytes)
end Stdout

show[T: Display](x: T)
    var out = Stdout()

    x.display(&out, FormatSpec(0, -1, false))
    printc('\n')
end show

show(42)
show("through a sink of one's own")

print(sizeof(Stdout))

42
through a sink of one's own
0

What wants one is a sink: a value standing for a destination fixed at compile time — the console, a serial port — which has nothing to keep and so has no field to keep it in. Being a value rather than a global is what lets it be passed to a function, held in a struct, and chosen by a caller.

Such a type occupies no bytes, so embedding one costs the struct holding it nothing. The cost of that is that two of them have nothing to tell their storage apart, and &a == &b on two such locals may well be true. There is no state behind either address for the answer to be about.

`opaque`

opaque struct Name withholds the layout from every module but the one declaring it. Outside, the type is incomplete: only *Name may be said, so a value cannot be built, copied, or have a field read. This is a different axis from visibility — private decides who may say the name, opaque decides who may know the shape. See modules.

An opaque struct with no body at all is C’s incomplete type, struct sqlite3; — nothing in sysl lays one out, and the declaration exists so that *Session is a type a *u8 cannot be mistaken for.

Enums

Two shapes under one keyword. A simple enum is a set of named discriminants over an underlying integer type; a data enum gives its variants payloads, which makes it a sum type. Both may carry members.

enum Status: u8
    Ok = 0
    Warn = 10
    Fail = 20

    severe(self) -> bool = u8(self) >= 10

print(u8(Warn), Ok.severe(), Fail.severe())

10 false true

The : u8 pins the storage; without it the compiler picks. A variant is a bare name, a name with an explicit integer value, or a name with a payload:

enum Shape
    Circle(r: real)
    Rect(w: real, h: real)

    area(self) -> real = self match
        Circle(r)  -> 3.14159 * r * r
        Rect(w, h) -> w * h

print(Circle(1.0).area(), Rect(2.0, 3.0).area())

3.14159 6

A member is told from a variant by what follows it: a member needs a body after its header, so Circle(r: real) — a header with nothing after it — is a variant.

Option[T] and Result[T, E] are ordinary data enums declared in the standard library, with no compiler privileges.

Type declarations

type Name = Existing introduces a second spelling, interchangeable with the first. It creates no new type and no checking — an alias is for shortening a name that has grown long.

Adding new makes it a genuinely distinct type, and within and where add checked bounds:

type Meters = new f64
type Slot = new u8 within 0..<8

var d = Meters(1.5)
var s = Slot(3)

print(f64(d) * 2.0, u8(s))

3 3

new, within and where are contextual words, so a function or field may still be named where. See errors and contracts for what a bound costs and when it is checked.

Traits, impls, and externs

trait Name declares a set of requirements; impl Trait for Type supplies them. Both are covered on traits.

extern declares a function or a variable the other side of the link owns, and is covered on the foreign interface.

Visibility

A declaration is public unless it says otherwise — the unmarked case is the one that writes nothing, because it is the common one.

written	reach
(nothing)	public — anything that can see the module can see it
`private`	this file only
`private[mod]`	the named enclosing module and everything under it

A struct’s and an enum’s members and fields each take their own modifier, so a type may be public while part of its shape is not. A trait’s members and an impl block’s take none: a trait’s member is as visible as the trait, and an implementation supplies what the trait asked for.

The details — what a module is, how the reach is computed, and how visibility interacts with opaque — are on modules.

`end` markers

Every block-shaped declaration may be closed with end Name, naming what it closes. It is optional everywhere and checked when written, so it cannot drift from the thing it claims to close.

The one place it is required is a struct with no fields, where it is the only thing distinguishing a body that is deliberately empty from one that was meant to be there.

end is a soft word: it is an ordinary identifier everywhere except immediately before a name or a construct keyword, so end stays usable as a variable.

Next: patterns and matching.

datetime

2026-08-16T01:26:07.924728867Z

Instants, durations, a calendar, and zones with daylight-saving rules — the whole point being the conversion between a wall clock and a timeline, which can fail and can succeed twice.

The axis: a conversion with three answers. A local date-time is a reading on a wall clock. It is not a point on the timeline and does not become one until somebody says where the wall is. On the night a clock goes back, one reading names two instants; on the night it goes forward, one reading names none. A library that returns a single answer there is wrong twice a year.

The reference values were computed against the real tz database with Python’s zoneinfo, and that was worth doing for its own sake: Python subtracts two aware date-times in one zone by wall clock, so the first attempt at the reference values reported the week across the spring change as 168 hours. The confusion this program is about is not a hypothetical one.

What it found

The difference of two moments could not be spelled - — answered. Every operator row was op(self, rhs: Rhs) -> Self, so an implementation said what it took and never what it produced. Instant + Duration, Instant - Duration and Duration ± Duration all wrote themselves; Instant - Instant -> Duration was refused, because Sub‘s result was fixed to the type on the left. Three quarters of an algebra was spellable, and the quarter that was not was the operation the library exists to provide.

An operator trait carries its result as Out now, as well as its operand as Rhs — the same change matrix was written for. A vector space needs Vector * Vector -> real and a timeline needs Instant - Instant -> Duration; they are one feature asked for by two problems. sysl.time writes both rows of Sub on Instant, told apart by the type of the right operand and nothing else — the library page runs both. since stays as the named spelling, because later - earlier is right and earlier - later is just as easy to write.

The finding moved into the library with the types and was answered there, which is the part worth keeping: a gap that becomes a shipped module’s gap is fixed once for everybody instead of worked around once per program that wants a date.

A derived scalar and a one-field struct are exactly complementary, and neither is what a quantity wants. type Instant = new i64 inherits its base’s whole catalogue for free — ==, <, +, str — and may replace none of it, so it arrives with Instant + Instant, which is nonsense, and cannot be given Instant + Duration, which is not. A struct of one field gets the algebra exactly right and arrives with nothing: five impl blocks per type before anything can be compared or printed. So a quantity type chooses between the catalogue and the meaning, and this program pays the struct’s price on every one of its six types.

The three-way answer needed nothing new, and that is a result rather than an absence. A data enum already spells “one answer, or none, or two, and here they are”; the resolution type is an ordinary enum and coverage checking is what makes a caller handle all three. The axis the problem was chosen for turns out to be covered by machinery that was already there — which is the useful thing to know before designing a library around it.

An enum cannot render its own variant names — and the three tables here turn out to be three different asks. A simple enum’s name answers T::Image(v) with the word the variant is spelled with, so the name-only case never needed a table: the library’s weekday_name is that case, and is one attribute read.

Neither of this program’s own two is that case, and saying why is worth more than the original complaint. The zone enum maps NewYork to "America/New_York" — a tz identifier, which is a fact about the database and not about the declaration, so nothing but a table can hold it. The resolution type is a data enum, where Image is refused in as many words, because a value there is a variant plus a payload and a name answers for half of it — and its renderer builds a sentence out of that payload anyway.

What is left of the finding is the narrow thing: str on an enum is still refused, so a value that is nothing but its name is printed by asking for the name rather than by rendering the value.

A val could not be sliced, third program to report that, and the report was acted on: a view of read-only storage is a []const T, which carries the property rather than losing it.

A built-in is on nobody’s left. Duration * 2 is writable and 2 * Duration is not, so the scaling in a date-time library only ever reads one way round.

Worth noticing

Both quantities are counts of microseconds, and the representation argument is written out in the source rather than assumed. Packing civil fields to the nanosecond needs 30 bits for the nanosecond, 17 for the time of day and 9 for day and month — 56, leaving 8 bits of year, which is a range of ±128 years and not a calendar. A count fits more comfortably at the same width and costs nothing to compute with, because comparing, subtracting and adding a length are one instruction each on a count and an unpack-recompute-repack on packed fields.

Source · Next: matrix — an operator whose result is neither operand’s type.

The core module

2026-08-16T01:26:07.924728867Z

sysl is the one module a program does not import. Every other module in this section — sysl.buf, sysl.text, sysl.io and the rest — is an offer, reached by name or by an import. The core is what arrives unasked-for, and the reason it does is narrow: a program cannot avoid needing what the language desugars onto. print(x) is a call to a library function. ? unwraps a library enum. a + b is a library trait’s method. A language whose own forms reach names a program had to import first would be a language with a required import, which is a worse thing than an auto-imported module.

So the rule for what belongs here is not “useful” — a growable sequence is useful and lives in sysl.buf. It is reached by the language itself, or so close to that as to make no difference.

var maybe: Option[int] = Some(3)

print(maybe.unwrap_or(0), "— and not one import above this line")

3 — and not one import above this line

What is in it

area	names	where it is written up
absence and failure	`Option`, `Result`, `Fallible`	errors and contracts
stopping	`panic`, `assert`, `exit`	below, and attributes for `@test`
rendering to standard output	`print`-family: `prints`, `printi`, `printu`, `printr`, `printb`, `printc`, `putbytes`, `encode_utf8`; the sink itself, `Stdout` and `stdout`	below
rendering to standard error	`eprints`, `eputbytes`; the sink itself, `Stderr` and `stderr`	below
rendering to a sink	`Display`, `FormatSpec`, `Writer`, the `display_*` family	below
hashing	`Hash`, `hash_u64`, `hash_u128`, `hash_bool`, `hash_str`	below
destruction	`Drop`	the memory model
operators	`Add`, `Sub`, `Mul`, `Div`, `Rem`, `BitAnd`, `BitOr`, `BitXor`, `Shl`, `Shr`, `Neg`, `Not`, `Eq`, `Ord`	expressions
subscripting and walking	`Index`, `IndexSet`, `Iterate`	below
calling	`Fn0` … `Fn4`	below

None of it is a language feature. Option is a generic enum, Display is a trait, panic is a function that prints and exits. What the compiler knows is a short list of names — it asks Option for its variants when it lowers a ?, and it asks the print family which function renders an int — and it implements none of the behaviour behind them. Rewriting printi is something a program can do; rewriting ? is not.

Stopping the program

Two functions stop a program on purpose, and both are ordinary sysl:

panic(msg: string, file: string = __FILE__, line: long = __LINE__) -> never
    prints("panic: ")
    prints(msg)
    prints(" (")
    prints(file)
    prints(":")
    printi(line)
    prints(")\n")
    exit(1)

assert(cond: bool, msg: string = "", file: string = __FILE__, line: long = __LINE__)
    if !cond then
        if msg.len == 0 then panic("assertion failed", file, line)
        else panic(msg, file, line)

panic returns never, so a call to it is an expression of any type — which is what lets it sit in one arm of a match whose other arms produce values, exactly as unwrap does.

The message is optional, because a failure names the line it happened on. __FILE__ and __LINE__ are reserved identifiers, and a default is evaluated at the call — so a parameter defaulted to one reports the caller’s position rather than the library’s. Write a message where it says something the condition does not; leave it out where the condition speaks for itself.

Two details of that are worth copying if you write a checking function of your own. assert passes file and line on to panic rather than letting panic fill its own defaults — otherwise every assertion in every program would report the line inside the library that calls panic. And the location is composed with prints and printi instead of an interpolated string, because building a string makes heap storage, which would put assert out of reach of a module that declared @no_alloc — the module that wants an assertion most.

divide(a: int, b: int) -> int
    assert(b != 0)
    a / b

print(divide(84, 2))

`assert_eq` — the assertion that says what the values were

assert(a == b) names the line, so you know which check broke. You then run the program again to find out what the two values actually were — and running it again is exactly what the report could have saved you.

assert_eq[T: Eq + Display](got: T, want: T, msg: string = "", …)
assert_slice_eq[T: Eq + Display](got: []const T, want: []const T, msg: string = "", …)

sum(xs: []const int) -> int
    var total = 0

    for x in xs
        total = total + x

    total

assert_eq(sum([1, 2, 3]), 6)
assert_eq(sum([1, 2, 3]), 6, "the running total")
print("both held")

both held

A failure prints the pair, in the order it is read in — what happened, then what was meant to:

panic: got 5, want 6 (main.sysl:9)
panic: the running total: got 5, want 6 (main.sysl:10)

Why this is a function and not advice to write the message yourself. The hand-written form is assert(a == b, s"got $a, want $b"), and it has two costs: it evaluates each side twice, and it builds a string. Building one makes heap storage, which puts it out of reach of a module that declared @no_alloc — the module that wants an assertion most. Rendering through Display into the output costs neither.

One function rather than one per type. Eq says the comparison means something and Display says the value can be shown, which together are the whole of what a report needs.

assert_slice_eq earns a name of its own because a report saying two slices differ sends you to find out where. It checks the lengths first — a length mismatch explains every index after the shorter one — and otherwise names the first index the two disagree at, with both elements at it:

panic: got 2 elements, want 3 (main.sysl:4)
panic: got 2, want 5 at index 1 (main.sysl:9)

Floats use a different pair, in sysl.math. == is the wrong question to ask about a float, so assert_approx_eq and assert_approx_eq_rel take a tolerance and are built on approx_eq / approx_eq_rel, which is where the right question already lives.

These are the runtime half of the language’s checking, and they are not the same half as contracts. A require clause is a promise about a call, checked where the call arrives. assert is a promise about a moment, checked where the moment is. A function whose fifth statement has just computed something it can verify has no contract to hang that on — the contract was about the arguments, four statements ago.

They also stop the program differently from the checks the compiler inserts, and the difference is visible:

stopped by	what you see	exit status
a compiler-inserted check (a bounds test, a broken contract)	nothing at all — a trap instruction, and buffered output is lost	the platform’s signal status
`panic`, `assert`, `unwrap`, `expect`	`panic: <message>` on stdout, after everything printed before it	1

That is not an inconsistency. A trap is for a check the language makes, where the source line already says everything a message could; panic is for a check a program makes, about something it knows and the compiler does not, where the message is the entire point. The full account is on errors and contracts.

exit is the third name here and the only extern the core offers rather than keeps:

extern exit(code: int) -> never

It takes no link name where the four platform externs in sysl.sys all take one, because it is not a platform detail — it is the hosted exit, the thing panic and unwrap stop with, and a program stopping itself writes exactly the same call.

Rendering to standard output

print(a, b, c) is a desugaring, not a variadic function. Each argument is looked at individually, its static type chooses a one-argument renderer, and the call becomes that sequence of calls with a space between and a newline at the end.

static type	renderer	what it does
`string`	`prints`	the bytes, as they are
any signed integer	`printi`	through `snprintf`‘s `%lld`
any unsigned integer	`printu`	through `snprintf`‘s `%llu`
`real`, `f32`	`printr`	through `snprintf`‘s `%g`
`bool`	`printb`	`true` or `false`
`char`	`printc`	UTF-8 encoded in sysl, not by C
anything else	its `Display`	via `str`, which renders into a buffer

print(42, 3.5, true, 'é', "text", 7)
print(1.0 / 3.0)

42 3.5 true é text 7
0.333333

0.333333 rather than 0.3333333333333333 because %g is six significant digits by default — which is C’s default and stays C’s, since the whole of printr is one snprintf call.

The renderers are ordinary functions and a program may call them directly. Nothing separates them, so this is where the space between print‘s arguments visibly comes from — there isn’t one:

printi(-7)
prints("|")
printr(2.5)
prints("|")
printb(false)
prints("|")
printc('é')
prints("|")
printu(9)
putbytes("|end\n".bytes)

-7|2.5|false|é|9|end

Everything goes through one sink, and that is not incidental

putbytes is the bottom of the whole surface. Every function above writes through it, including the ones that went to snprintf for their digits — they format into a stack buffer and then hand the bytes here.

Two mechanisms would mean two buffers, and output emerging in an order the program did not write. That is the entire reason for the shape.

It also writes a byte at a time, which looks like a mistake and is not. A sysl string may hold an interior NUL, and every shortcut through C stops at one: puts, %s, even %.*s. A string that printed correctly right up until it contained a zero byte is a worse bug than a loop that costs a call per byte, and the loop is what a target with a real write replaces anyway.

putbytes(b: []const u8)
    var i = 0
    while i < b.len
        sysl_putchar(int(b[i]))
        i += 1
end putbytes

putbytes is one of exactly two functions a freestanding target has to replace. Swap its body for a write syscall and FdReader.read‘s for a read one, and the entire surface above both is unchanged — every renderer, every Display, every f"…" in the program.

`encode_utf8` — a character’s bytes, without printing them

encode_utf8(ch: char, into: []u8) -> usize

printc encodes rather than handing the character to snprintf, which has no conversion that takes a code point — and what it uses is this, which any program may call. It writes into storage the caller owns and answers how many bytes it wrote. No character needs more than four, so a [4]u8 is always enough and always on the stack, which is what keeps it usable where there is no allocator.

var b: [4]u8

print(encode_utf8('A', b[0..<4]), encode_utf8('é', b[0..<4]), encode_utf8('☃', b[0..<4]))

var n = encode_utf8('é', b[0..<4])

print(b[0], b[1], n)

1 2 3
195 169 2

It is here in sysl rather than beside from_utf8 in sysl.text, and that placement is forced. A submodule may name the standard module freely and the standard module may not name back, so an encoder over there would be one printc could not call — and the second encoder that would then be written for it is exactly the hand-rolled copy this function exists to prevent. The library carried four of them before it had this one.

A slice shorter than four bytes is a mistake in the program rather than a truncation, and the bounds check says so: how many bytes are needed is not known until the character has been looked at, so there is no honest answer to “it did not fit” that is cheaper than having room.

The other stream

A program’s answer and its complaints go to different places, so that a run whose output is being captured does not have the complaint land in the middle of the answer, and a redirect that keeps the answer still lets a person see what went wrong. eprints writes a string to standard error, and stderr() is the same destination as a Writer, for a value rendering itself through its own Display:

prints("the answer\n")
eprints("something to say about it\n")

the answer

The page shows only the first line because only the first line went to standard output — which is the whole point of the distinction, and is what sysl.args relies on when it puts a usage error on one stream and its --help on the other.

This half goes through write directly rather than a byte at a time, because there is no buffer between it and the descriptor: a diagnostic written just before a program stops has to have left before it does, which is the same reason C leaves standard error unbuffered. A short write is looped over, since a signal may cut one anywhere.

Rendering to a sink

Standard output is one destination. A value that knows how to render itself renders into a Writer instead, and that is what Display is:

struct FormatSpec
    width: int
    prec: int
    left: bool

trait Display
    display(self, out: *Writer, fmt: FormatSpec)

trait Writer: Fallible
    write(*self, bytes: []const u8)

Three decisions are packed into those six lines.

A value writes rather than returns. display produces no string, so rendering costs no allocation and a module under no alloc can still log. str(x) is then not a separate mechanism — it is this same rendering aimed at a buffer.

The sink is *Writer, a trait object. So a rendering is written once against any sink, and a kernel that has a UART and no standard output supplies one with an ordinary impl.

Standard output itself is one of those ordinary impls, and the library declares it — Stdout, a struct with no fields, because a destination fixed at compile time keeps nothing. stdout() hands one out, and it is what print writes a value’s own rendering into:

struct Marked
    n: int

impl Display for Marked
    display(self, out: *Writer, fmt: FormatSpec)
        display_str("<", out, fmt)
        display_int(long(self.n), out, fmt)
        display_str(">", out, fmt)

show(where: *Writer, m: Marked)
    m.display(where, FormatSpec(0, -1, false))
    where.write("\n".bytes)

var mine = Stdout()

show(stdout(), Marked(1))
show(&mine, Marked(2))

print(Marked(3))

<1>
<2>
<3>

That the destination is a value rather than a fixed global is what lets show take it as a parameter. Nothing above is privileged: a program pointing show at a UART writes another impl Writer and passes that instead.

Writer requires Fallible rather than declaring a failed of its own, because Reader needs the same question answered and an open file is both. Two traits may each declare a member of one name — a call says which by naming the trait — but failed takes no arguments, so at a call on a file there would be nothing to say which was meant. One required trait makes the question go away rather than move it. Fallible is on errors and contracts, with the reason a stream latches instead of returning.

The `display_*` family

Every rendering the language does ends up in this family, one function per shape:

function	renders
`display_str`	a `string`; precision truncates
`display_int`, `display_uint`	an integer a caller already holds at 64 bits; precision is a minimum digit count, zero-filled
`display_real`	a float; precision is significant digits, defaulting to 6 and capped at 40
`display_bool`, `display_char`	`true`/`false`, and a code point encoded to UTF-8
`display_digits`	where a number ends up — reads a sign off the front, zero-fills to the precision, then pads
`display_pad`	where the rest end up — puts finished bytes in the field the spec asked for
`display_fill`	writes one byte n times, in 16-byte runs off a stack buffer

Every built-in reaches its own through an impl, and the two halves get there differently. bool, char, string, real and f32 are five types, so each has an ordinary impl Display in the library forwarding to the function above. The iN/uN families are open — i5 and u24 are types you may write — so no finite list of blocks reaches them; what reaches them is a single blanket block, impl[T: Integer] Display for T, whose buffer is measured from the width it is instantiated at.

Either way they are Display exactly the way your own struct is, and a *Display can carry any of them. That is what the blanket bought: a []*Display holding an int, a u8, a string and a float is ordinary code, where an integer used to be the one thing a method table could not hold.

Integer is a trait you can write a bound over — f[T: Integer](x: T) accepts every width and nothing else — but not one you can implement. It names which types the compiler settles a family as, so there is nothing for a block to supply.

display_int and display_uint remain for a caller who already has a long in hand. Nothing in the library routes through them any more.

A scalar reaches its own through a method call, so a Display written for a struct can render its fields without leaving the allocation-free path:

import sysl.buf.byte_sink

var sink = byte_sink()
var out: *Writer = &sink

42.display(out, FormatSpec(6, -1, false))
"x".display(out, FormatSpec(0, -1, false))

putbytes(sink.text())
prints("\n")

42x

FormatSpec(6, -1, false) is a width of six, no precision — which is what -1 means throughout the family — and padding on the left. The neutral spec, which is what a plain print passes, is FormatSpec(0, -1, false).

The allocation-free path reaches every width. A rendering works its digits out against a frame-local buffer and hands the sink a slice of it, which is safe because a Writer borrows the bytes it is given rather than keeping them — so a module declaring @no_alloc can render anything, a u256 included.

It did not always. The buffer has to be sized for the width, and until an array’s length could be written in terms of a type parameter — [sizeof(T) * 3 + 2]u8, three decimal digits per byte being the bound at every width — the widest values fell back through str, which is heap storage. So the values needing the most care were the ones a module without an allocator could not print.

One padder, and why

Every renderer finishes by handing its bytes to display_pad. Six renderers each growing their own padding would be six chances for %8s to mean something slightly different, and the drift would be invisible until someone lined two columns up.

import sysl.buf.byte_sink

var sink = byte_sink()
var out: *Writer = &sink

display_int(42, out, FormatSpec(8, -1, false))
out.write("|".bytes)
display_int(-42, out, FormatSpec(0, 5, false))
out.write("|".bytes)
display_str("héllo", out, FormatSpec(0, 2, false))
out.write("|".bytes)
display_real(1.0 / 3.0, out, FormatSpec(0, 3, false))
out.write("|".bytes)
display_bool(true, out, FormatSpec(8, -1, true))
out.write("|".bytes)
display_char('é', out, FormatSpec(4, -1, false))
out.write("|".bytes)
display_uint(7, out, FormatSpec(0, 3, false))

putbytes(sink.text())
prints("\n")

      42|-00042|h|0.333|true    |  é|007

Read that line slowly, because four rules are visible in it.

Precision means a different thing per renderer, and matches printf’s meaning under the corresponding conversion. -00042 is %.5d: five digits minimum, zero-filled, and the sign is written before the zeros rather than being counted among them. 0.333 is %.3g: three significant digits. 007 is the unsigned form of the first. h is %.2s: truncation.

Width and precision count bytes, exactly as C’s do. display_str("héllo", …) with a precision of 2 was asked for two bytes, and é is two bytes of which only the first fits — so the answer is h. It backs off to a character boundary rather than handing the sink half of a code point, which is the one place this family refines C rather than copying it: %.2s in C would emit the lone lead byte.

The same byte-counting is why é in a field of four came out with two spaces and not three. A column-aligned table of non-ASCII text is therefore not something width gives you for free — counting display columns is a different problem (combining marks, wide CJK cells) and the library does not pretend to solve it.

left is the whole of justification. There is no centring, and no fill character other than a space for the field or a zero for the digits.

Writing `Display` for your own type

struct Point
    x: int
    y: int

impl Display for Point
    display(self, out: *Writer, fmt: FormatSpec) =
        display_pad(("(" + str(self.x) + ", " + str(self.y) + ")").bytes, out, fmt)

var p = Point(3, 4)

print(p)
print(f"[${p}%10s]")
print(f"[${p}%-10s]")

(3, 4)
[    (3, 4)]
[(3, 4)    ]

The parts are gathered before anything is padded, and that is the rule rather than the style. A specifier describes the field the whole value occupies — so %10s on a point pads the point, not its first number. An implementation that rendered parts and forwarded fmt down to each of them would pad the 3 to ten columns and then the 4, which is not what anybody asking for %10s meant.

Forwarding fmt straight down is right in exactly one case: when the part being rendered is the whole rendering, as for a wrapper around a single field.

A type with no Display cannot be printed, and the diagnostic says what to write:

struct Scale
    k: int

print(Scale(3))

cannot print a Scale value — write an 'impl sysl.Display for Scale' to say how it renders

A slice or an array of anything printable

One impl[T: Display] Display for []T covers every slice, so the element type only has to render itself. A slice of a type you wrote works the moment that type does:

struct Rect
    w: int
    h: int

impl Display for Rect
    display(self, out: *Writer, fmt: FormatSpec) = display_str("a rect", out, fmt)

var ns = [1, 2, 3]
var rs = [Rect(3, 4), Rect(1, 2)]

print(ns)
print(rs[..])
print(f"[${ns[..]}%14s]")

[1, 2, 3]
[a rect, a rect]
[     [1, 2, 3]]

A fixed-size array renders too, and by one block rather than one per length: impl[const N: usize, T: Display] Display for [N]T. A length is a value parameter, so it is an argument to the array shape rather than part of it, and one implementation covers every array there is. It delegates to the block above, so an array and its [..] view render identically — which is why print(ns) and print(ns[..]) are the same line of output.

Before value generics a length was part of a type’s shape: [2]T and [3]T were two shapes with no way to be generic over the difference, so printing a fixed array meant taking the view by hand.

The elements are written as they are met, never gathered. Gathering would need a growable buffer, sysl.buf is built on this module rather than under it, and an allocation on the printing path is the one thing printing does not have — so a slice prints under @no_alloc exactly as a number does.

That leaves the width, which has to be known before the first byte goes out. It is learned by rendering once into a sink that adds up what it is given and keeps none of it, so the cost of a padded slice is a second pass rather than a buffer, and an unpadded one is a single pass.

Saying how a slice of your type renders

The block above covers every slice, which would ordinarily be the end of the matter: two implementations for one type are refused, and a program writing impl Display for []Rect would be told the library got there first. Say override and it is yours:

struct Rect
    w: int
    h: int

impl Display for Rect
    display(self, out: *Writer, fmt: FormatSpec) = display_str("a rect", out, fmt)

override impl Display for []Rect
    display(self, out: *Writer, fmt: FormatSpec) =
        display_str(str(self.len) + " rects", out, fmt)

var rs = [Rect(3, 4), Rect(1, 2)]

print(rs[..])
print(rs[0])

2 rects
a rect

The keyword goes on the overriding side, and that is the whole of it — nothing in the library had to permit this in advance. A more specific implementation is found first, so []Rect reaches yours and every other slice still reaches the library’s.

Two things it deliberately does not do. It does not let you replace an implementation for a type that is not yours — override impl Display for []int is refused, because []int names nothing of your program’s and coherence puts that block in the library or nowhere. And it does not silence the ordinary duplicate: leave the keyword off and the second implementation is refused exactly as it always was, which is how a block written twice by accident still gets found.

Hashing

trait Hash
    hash(self) -> u64

A u64 rather than a usize, so a hash means the same thing on every target — a table moved between a 32-bit and a 64-bit machine does not rebucket because the word size changed.

As with rendering, the built-ins reach a named mixer — through written impls, one per closed type and a single blanket over the integers, which is what makes a built-in erasable to a &Hash rather than merely usable under a Hash bound. Those mixers are public, which is what lets a Hash written for a struct mix its own fields:

mixer	for	what it is
`hash_u64`	every integer up to 64 bits	splitmix64’s finalizer
`hash_u128`	every integer above 64 bits	the two halves mixed separately, then combined
`hash_bool`	`bool`	`hash_u64` of 1 or 0
`hash_str`	`string`	FNV-1a over the bytes

A value wider than 128 bits is truncated to 128 before it reaches hash_u128. That keeps the law a hash owes — equal values hash equal — and gives up only collision resistance among values that agree in their low 128 bits. If something ever keys a table on values that wide, mixing in 128-bit chunks is the fix.

hash_u64 is a finalizer and not the identity for a reason. Consecutive integers are the input a hash table actually meets — loop counters, row ids, sizes — and an identity hash makes them collide in a row rather than spreading them. A mixer costs three multiplies and turns a counter into something a table can bucket on.

A bool gets its own mixer because one bit does not widen to a number in this language; a string gets FNV-1a over its bytes because a string is a validated []u8, so there is nothing to decode and every byte counts once.

struct Key
    name: string
    n: int

impl Hash for Key
    hash(self) -> u64 = hash_u64(hash_str(self.name) * 0x100000001b3 ^ hash_u64(u64(self.n)))

print(Key("a", 1).hash() != Key("a", 2).hash())

true

The multiply-then-xor is the shape to copy: 0x100000001b3 is FNV’s prime, and mixing with it before the xor is what makes order matter. A plain xor of the field hashes would give Key("a", 1) and a hypothetical Key with the fields swapped the same bucket.

Because the memberships are impls, a built-in can be erased to a trait object — a method table holds function pointers, and an impl is what supplies one:

val xs: [3]&Hash = [7, "abc", true]

for h in xs do print(h.hash() != 0)

true
true
true

The widening is the law rather than an implementation detail: 1 and 1 are the same number, they compare equal across widths, and so they hash equal — each becomes the same u64 before it reaches the mixer.

Subscripting a type of your own

A built-in array or slice is indexed by walking to an address, and that is the compiler’s business. These two traits are what b[i] means when the receiver is a type somebody wrote:

trait Index[I, E]
    index(self, i: I) -> E

trait IndexSet[I, E]
    index_set(*self, i: I, v: E)

Reading and writing are separate traits because a type may offer one without the other — a view that computes its elements has an Index and no IndexSet to give.

struct Grid
    cells: [9]int

impl Index[int, int] for Grid
    index(self, i: int) -> int = self.cells[i]

impl IndexSet[int, int] for Grid
    index_set(*self, i: int, v: int)
        self.cells[i] = v

var g: Grid

g[3] = 7

print(g[3], g[0])

7 0

The difference from a built-in subscript is not cosmetic: reading through Index is a call, so it yields a value rather than a place. That is why compound assignment through one is refused rather than quietly expanding:

struct Grid
    cells: [9]int

impl Index[int, int] for Grid
    index(self, i: int) -> int = self.cells[i]

impl IndexSet[int, int] for Grid
    index_set(*self, i: int, v: int)
        self.cells[i] = v

var g: Grid

g[0] += 1

'+=' on an element read through 'sysl.Index' would evaluate the receiver and the index twice — write it out as 'b[i] = b[i] + …'

The expansion would be g.index_set(0, g.index(0) + 1), which evaluates g twice and the index expression twice. For a Grid that is merely wasteful; for a receiver that is a function call, or an index that advances a cursor, it is wrong. The refusal makes you write the version whose cost you can see.

This is the sysl.buf Buf[T] arrangement too, and there it earns something specific: subscripting reaches the bounds-checked members rather than the storage, so b[i] cannot read a slot past the count that the backing slice still has.

Walking a type of your own

trait Iterate[E]
    next(*self) -> Option[E]

This is what a for asks of what it walks, when what it walks is not a range, an array or a slice.

next answers with an Option, so ending and yielding are one question with one answer. A separate has_next would be two, and two questions can disagree — the classic iterator bug is a has_next that says yes and a next that then has nothing.

struct Countdown
    n: int

impl Iterate[int] for Countdown
    next(*self) -> Option[int]
        if self.n <= 0 then return None
        self.n -= 1
        Some(self.n + 1)

var c = Countdown(3)

for x in c do print(x)

3
2
1

The cursor is advanced through *self, and a loop iterates a copy of what it was given. c above is untouched by the walk. That matters for a cursor meaning to report something after the walk — a reader’s failure latch, say — which is why such a cursor has to borrow what it reports on rather than own it. sysl.io‘s lines() is built that way for exactly this reason.

A for also walks an erased cursor, since next takes *self and mentions no Self elsewhere — so Iterate has an object, and the loop calls its member through the table. The element type is whatever the object was erased to, which is why there is nothing to annotate:

struct Countdown
    n: int

impl Iterate[int] for Countdown
    next(*self) -> Option[int]
        if self.n <= 0 then return None
        self.n -= 1
        Some(self.n + 1)

var it: &Iterate[int] = Countdown(3)

for x in it do print(x)

3
2
1

That is the same rule that lets a trait object satisfy a bound — a for asks what may be called on the value, and a table is an answer to that. It means a function may hand back a cursor without saying which one it built.

Calling a value

trait Fn0[R]
    call(*self) -> R

trait Fn1[A, R]
    call(*self, a: A) -> R

trait Fn2[A, B, R]
    call(*self, a: A, b: B) -> R

…and Fn3, Fn4. One trait per arity, because a call’s argument types are part of what it promises and there is no way to write that variadically.

call takes *self so a callable may carry mutable state, which is what makes a counter writable:

struct Counter
    n: int

impl Fn0[int] for Counter
    call(*self) -> int
        self.n += 1
        self.n

var c = Counter(0)

print(c.call(), c.call(), c.call())

1 2 3

A function type A -> R is Fn1[A, R] at the use, so a hand-written callable goes wherever a closure goes — the parameter does not know or care which it got:

struct Scale
    k: int

impl Fn1[int, int] for Scale
    call(*self, a: int) -> int = a * self.k

apply(f: int -> int, x: int) -> int = f(x)

var s = Scale(3)

print(apply(s, 5), apply(n -> n + 1, 5))

15 6

That is worth knowing when a closure is not enough: a struct can have several members, be printed, be compared, and still be passed as the function.

Tuples

A tuple is comparable, hashable and printable exactly when its parts are. The memberships are structural, so nothing has to be written per tuple type:

print((1, 2), (1, 2, 3))
print((1, 2) < (1, 3), (1, 2) == (1, 2), (1, 2).hash() != (2, 1).hash())
print(f"[${(3, 4)}%10s]")

(1, 2) (1, 2, 3)
true true true
[    (3, 4)]

Every arity, not a list of them. The four rows are written over a type pack, so one block each covers a tuple of any width:

impl[..A: Eq] Eq for (..A)
    eq(self, rhs: Self) -> bool
        for const i in 0..<A.len
            if self.i != rhs.i then return false

        true
    end eq

That is the library’s own source, quoted for its shape, and it is worth reading as what a pack is for: ..A stands for the parts, the bound on it is asked of every one of them, and for const is unrolled so self.i is an ordinary field selection at whatever type that part has.

print((1, "a", true, 2.5, 'z'))
print((1, 2, 3, 4) == (1, 2, 3, 4), (1, 1, 1, 2) < (1, 1, 1, 3))

(1, a, true, 2.5, z)
true true

Ord on a tuple is lexicographic, and each position runs a ladder rather than a single <, because deciding a position takes two comparisons: this one is less, or it is greater, or the two agree and the next position decides. Every position agreeing is not-less, which is where the loop ends.

A wide tuple is still usually worse code than a struct with field names — .3 says nothing and .hue says everything. What has changed is that the language is no longer the thing telling you so.

Operators are here, and are documented elsewhere

The fourteen operator traits — Add through Ord — are declared in this module and are covered in full under operator dispatch, because which trait a + reaches is a rule about the operator rather than about the trait.

Two things about them belong here, where the declarations are:

Each trait requires exactly one method. Implementing comparison means writing lt and nothing else — a > b is lt(b, a), a <= b is !lt(b, a) — so there is no way for four functions to disagree with each other.

Eq and Ord are independent, not a hierarchy. That is the scalar law lifted intact: bool and the pointer modes have == and no <. Implementing one does not give you the other:

struct M
    v: int

impl Ord for M
    lt(self, rhs: M) -> bool = self.v < rhs.v

print(M(1) < M(2))
print(M(1) == M(2))

'==' is not defined for M

Everything else is an import away

A name that is not in the core is not in scope, and the diagnostic is the ordinary one for an undefined function rather than anything that hints at a module:

var b = byte_sink()

undefined function 'byte_sink'

That is the auto-import rule doing its job in the direction that matters. Only the standard module arrives unasked-for; a submodule is an offer, and taking it up is written down where a reader can see it.

Next: sysl.text — bytes to text, and back.

Control flow

2026-08-16T01:26:07.924728867Z

`if` yields a value

There is no ternary operator, because there is no need for one:

var n = 55

var label = if n % 2 == 0 then "even" else "odd"
print(n, "is", label)

55 is odd

Written across several lines it uses elif and reads as ordinary control flow. It is the same expression either way — the value is simply unused when nothing wants it:

grade(score: int) -> string
    if score >= 90 then "excellent"
    elif score >= 70 then "fine"
    elif score >= 50 then "scraped it"
    else "no"

print(grade(91), grade(72), grade(50), grade(12))

excellent fine scraped it no

An if being used for its value needs an else. Without one the open branch has no value to give, and the compiler says so rather than inventing a zero.

`match` picks an arm

Arms match a literal, a |-separated set of alternatives, a range, or fall through to else:

size(n: int) -> string
    n match
        0 -> "empty"
        1 | 2 | 3 -> "small"
        4..99 -> "medium"
        else "large"

print(size(0), size(2), size(55), size(1000))

empty small medium large

A match used for a value has to be exhaustive. That is what the else is doing above: int has more values than the arms name, so without it there would be inputs with no answer. Where the arms genuinely cover everything — the variants of an enum, say — no else is needed and adding one is a mistake, because it is the thing that would stop the compiler telling you about a variant you forgot when you add it later.

Loops

while and for are the ordinary ones. A range is written a..b for inclusive and a..<b for exclusive, which are the same two operators used everywhere else in the language:

var sum = 0
for i in 1..10 do sum = sum + i

var doubled = 0
for i in 0..<5 do doubled += i * 2

print("sum:", sum, "doubled:", doubled)

sum: 55 doubled: 20

do puts the body on the same line. Indent it instead and the do goes away:

var countdown = 3

while countdown > 0
    print("t minus", countdown)
    countdown -= 1

print("go")

t minus 3
t minus 2
t minus 1
go

When the body has to run before anything is asked, put the test at the foot with do … while:

digits(n: int) -> string
    var rest = n
    var s = ""

    do
        s = str(rest % 10) + s
        rest /= 10
    while rest > 0

    s

print(digits(0), digits(4071))

0 4071

Written as a while, that prints nothing at all for 0, and the usual patch is a special case above the loop. The test at the foot is the fix. The one-line form is do rest /= 10 while rest > 0.

continue in a do … while runs the test, which is why the loop is worth having rather than writing loop with if !cond then break at the bottom: that shape has no test for a continue to reach, so the first one added to it skips the exit and the loop never finishes.

A loop with nothing to test is written loop, which is what while true was always being used to say:

var n = 0

loop
    n += 1
    if n >= 4 then break

print("stopped at", n)

stopped at 4

Loops yield values too

This is the part worth slowing down for, because it replaces a pattern that is otherwise written with a flag variable. break carries a value out, and an else block — after the body, as in Python — supplies the value when the loop finishes without breaking:

first_multiple(of: int, upto: int) -> int
    for i in 1..upto
        if i % of == 0 then break i
    else -1

print(first_multiple(7, 20), first_multiple(23, 20))

7 -1

Read the else as “and if it ran out”. Every break value and the else value share one type, which becomes the loop’s type. Without an else, finishing normally yields nothing — so a value-carrying break needs one, and the compiler will tell you if it is missing.

A loop takes no else, because it has no normal completion to have one for. That has a consequence worth knowing: a loop that nothing breaks out of never finishes, so it can stand as the last thing a function owing a value does, with nothing after it to supply that value. while true cannot say this — a condition is an expression the compiler does not evaluate, so a loop written that way looks like one that might finish and the code after it looks reachable.

Iterating over things

A for walks a collection directly:

var primes = [2, 3, 5, 7, 11]
var total = 0

for p in primes do total += p

print("count:", primes.len, "total:", total)

count: 5 total: 28

And when the stepping is something a range cannot describe, the three-clause form is there:

var n = 0

for var i = 1; i < 100; i *= 2
    n += 1

print("doublings under 100:", n)

doublings under 100: 7

The ; in that header is the only place in the language it appears. It is deliberately not a statement terminator — a line ends a statement, and a token that could also end one would give the language two answers to the same question.

Next: functions, which have been quietly appearing in every example so far.

Contracts and constrained types

2026-08-16T01:26:07.924728867Z

Two features that are really one idea: write the rule down where the thing is declared, and let the compiler put the check in. A constrained type narrows what values a scalar may hold; a struct invariant says what has to stay true of a value’s fields; a contract says what a function requires and what it promises.

One declaration form, three independent parts

type Name = [new] Base [within lo..hi] [where predicate]

new, within and where are contextual keywords — ordinary identifiers everywhere else, so a field may still be called where. Each of the three parts may be left out:

type Meters   = new f64
type Age      = int within 0..150
type Even     = int where value % 2 == 0
type Slot     = new u8 within 0..<8

var a: Age = 42
var e: Even = 8
var m = Meters(5.5)

print(a, e, f64(m))

42 8 5.5

The value the predicate is about is named value, and it is bound only inside the predicate.

The base is a scalar — an integer, a float or a char. A constraint here is a check on a value, and the two ways to narrow an aggregate are the struct invariant below and, for an enum, having fewer variants.

One combination is rejected: type Alias = int, with no new and no constraint. It neither narrows the values nor makes a new type, so it declares nothing at all — there is no typedef to write by hand, and the diagnostic says so at the declaration. The one declaration of that shape is the one the compiler writes for you, when a c type asks the C compiler what a typedef in a header actually is.

`new` is what makes it a type

Without new, a constrained type is its base with a checked range. Age and int are the same type, values flow between them freely, and what the declaration buys is the check:

type Age = int within 0..150

birthday(a: Age) -> Age = a + 1

var n: int = birthday(41)

print(n)

Being its base means its name converts what the base’s name converts. Age(n) on a usize is the int(n) you would otherwise write, and the range is checked on the value that arrives — so the conversion is a conversion rather than a way past the constraint:

type Age = int within 0..150

var n: usize = 42
var f: f64 = 7.9

print(Age(n), Age(f))

42 7

That matters most where the base cannot be named. A c type is a transparent subtype of a width the C compiler measured for the target being built for, so u32(n) would be one machine’s answer written into the source, and the type’s own name is the only portable way in.

With new it is a distinct nominal type, and that is a large difference. Two derived types over one base do not mix:

type Meters = new f64
type Feet = new f64

var m = Meters(3.0)
var f = Feet(3.0)

print(f64(m + f))

'+' needs matching types, got Meters and Feet

A derived type does not mix with its base either, and going in either direction is a written conversion: Meters(x) wraps and f64(m) unwraps, and the wrap is where the constraint is checked. The wrap takes a value that is already at the base — Meters(3.0) and not Meters(3) — which is the one place the two kinds differ in call position, and it follows from new making the type distinct.

The payoff is a specific bug. A table-driven program has several small integers that index different things — a task number, a lock number, a priority level — and the mistake such a program actually makes is passing one where another was wanted. Three new u8s with three ranges make that a compile error instead of a plausible-looking wrong answer. It is an argument about types, not about checking.

A derivation inherits its base’s behaviour and may replace none of it

A new type over a scalar arrives with everything the scalar could do — ==, <, +, str and the rest — working at itself and producing itself. And almost no impl may replace or extend any of it.

Inheriting is right because a derivation does not change what the values are: a Slot is some of the u8s, not a different set of things stored in a byte. Refusing to replace is the harder call. If Stamp could redefine <, then Stamp would be a set of i64s that do not order the way i64s order, and every fact the base guarantees would hold only until somebody looked.

Rendering is the exception, and the reason says where the line is. How a value prints is not a fact the base guarantees about the value — a Stamp printing as #7 is the same i64 it was — so a derivation may take that one row back with an override impl Display. Ordering and arithmetic it may not.

So the answer to “I want my own +“ is that you do not want a derivation, you want a struct:

	a `new` derivation	a one-field struct
distinct type	yes	yes
the base’s catalogue	free; only `Display` is replaceable	nothing, write it all
an operation the base does not have	impossible	ordinary
an operation the base has that is now nonsense	present anyway	absent
rendering as something other than the base	`override impl Display`	ordinary

Use a derivation for an identity — a slot number, a handle, a unit-tagged measurement. Use a struct for a quantity with an algebra of its own: an instant plus a duration is an instant, an instant plus an instant is nonsense, and no derived scalar can be told the difference.

Where a constraint is checked

At every point a value of the type is produced, and nowhere else. That is not a list of syntactic forms to memorize — a value comes to have the type wherever it flows into a slot the type is written on: an initializer, an assignment, an argument, a returned value, a cast, a struct field, an array element, an enum payload, an item entering a generic container instantiated at the type.

A value that already has the type is not re-checked when it is merely read, passed along or copied. It could not have got there unchecked.

One site is closed by not existing. A constrained subtype has no zero value, whether or not its range contains zero:

type Age = int within 0..150

var a: Age

print(a)

Age has no zero value, so 'a' needs an initial value

Making that the type’s rule rather than the range’s means widening a range never silently changes whether a declaration compiles somewhere else.

A violated check traps. It is not an error value and it is not catchable, and there is deliberately no try form returning an Option: a constrained type states something its values are, so a value that is not one of them is a bug in the code that made it rather than a condition to handle.

Asking instead of trapping

Which is what the type’s own name is for. A constrained type answers a small closed set of attributes, written with :: so they stay out of the member namespace and no impl can shadow one:

type Slot = new u8 within 0..<8

print(u8(Slot::First), u8(Slot::Last), Slot::Valid(3), Slot::Valid(200))

var total = 0

for s in Slot::Range do total += int(u8(s))

print("sum of every slot:", total)

0 7 true false
sum of every slot: 28

First and Last are the bounds — note Last is 7, one below the written exclusive bound. Succ and Pred step, and trap at the ends rather than saturating or wrapping, on the same argument as the produce sites. Range is the whole range as a for loop’s iterable.

Every attribute but one speaks the subtype: a bound of T is a value of T, and the values Range walks are Ts. That is invisible on a transparent subtype and it is the point on a derived one, which would otherwise be the only kind of type whose own attributes had to be cast back into it.

Valid is the exception, and the asymmetry is its job: it takes the base, because asking whether a value is a T is only a question about something that is not one yet. It is total — it never traps — which is what makes it the question form, and a cast after a Valid that answered true is the ordinary way in.

Struct invariants

A struct body may carry invariant clauses among its fields, each an expression over the struct’s own fields, in scope by name:

struct Window
    lo: int
    hi: int
    invariant lo <= hi
    invariant hi - lo < 4096

var w = Window(2, 10)

w.hi += 5

print(w.lo, w.hi, w.hi - w.lo)

2 15 13

Several clauses all have to hold, and each is checked independently so the diagnostic names the one that failed.

Checked at every write, not only at construction — that is the part worth stating, because the cheap implementation checks the constructor and calls it done. Assigning a single field counts, including a compound assignment and an increment. So does a field written through a pointer, a field written into an array element, and a field written inside one of those.

The consequence is the intended one: a sequence of writes that ends in a valid state but passes through an invalid one traps at the step that broke it. There is no “I am mid-update” mode.

When a struct cannot be updated one field at a time, there are three answers and the order matters:

Look for an order in which no intermediate state is illegal, and often there is one. A count <= high watermark is updated by raising the ceiling before the floor. That the same clause accepts one order and refuses the other is the whole of the answer here.
Ask whether the clause is pointing at a redundant field. An invariant relating two fields is a claim about the representation, and the trap is often the compiler observing that the struct carries one fact twice. A ring buffer keeping head, tail and count cannot move any two of them one at a time; one keeping head and count and computing the end has no clause to break.
Otherwise assign the whole struct, and know the price — restating the whole value to move two bytes makes a container’s own update cost the size of the container.

Contracts on a function

half(x: int) -> int
    require x >= 0, "a half of a negative is not what this means"
    ensure result >= 0

    x / 2

print(half(10), half(7))

5 3

Both kinds form one block at the top of the body. A clause after an ordinary statement is rejected: a precondition that runs after some of the work is not a precondition, and a postcondition is written up there because that is where a reader looks for what the function promises — not because that is when it runs.

require is checked on entry. ensure is checked before every return, including early ones. Both take an optional message.

Two names exist only inside a contract. result is the value being returned, available in an ensure only. old(expr) is expr evaluated on entry — which is what lets a postcondition talk about what a mutating function changed rather than only about what it left behind:

struct Counter
    n: int

    bump(*self)
        ensure self.n > old(self.n)

        self.n += 1

var c = Counter(0)

c.bump()
c.bump()

print("n:", c.n)

n: 2

That is contracts at their most useful — on a mutating method, saying the thing the method is for.

Contracts are checked in every build. There is no release mode that drops them, and adding one would make a program’s meaning depend on how it was compiled.

What this is, and where the rest of it is

Nothing on this page is proved while compiling: a require is a branch and a trap, an invariant is a call to a synthesized predicate, a within is two comparisons. What the feature buys is that the rule is written once, where the thing is declared, instead of being re-checked by hand at every call — and that when it is broken, the program stops at the write that broke it rather than somewhere downstream where the wrong value finally mattered.

The proving is a page of its own. Verification adds the vocabulary a specification needs — quantifiers, loop invariants, termination measures, @pure and @ghost — and sysl prove, which discharges the obligations with Why3. The two fit together the way they do because a clause means one thing: the prover and the running program read the same sentence, and a check the prover proves redundant is still compiled. So nothing above changes when you start proving, which is the point.

Tests live beside the code

The third checking tool, and the one that runs on examples rather than on rules. A @test annotation on an ordinary function marks it as a test, and assert is what a test uses to state what it expects:

clamp(n: int, lo: int, hi: int) -> int
    if n < lo then lo
    elif n > hi then hi
    else n

@test
clamps_both_ends()
    assert(clamp(5, 0, 3) == 3, "above the ceiling")
    assert(clamp(-2, 0, 3) == 0, "below the floor")

@test("a value already inside is left alone")
leaves_the_middle()
    assert(clamp(2, 0, 3) == 2, "untouched")

print(clamp(9, 0, 3), clamp(1, 0, 3))

3 1

That program prints 3 1 and runs neither test, which is the whole arrangement: sysl run builds the program and the tests are not part of it. They have a caller nothing else has:

$ sysl test clamp.sysl
running 2 tests

clamp.sysl
  ok    clamps_both_ends                      2561ms
  ok    a value already inside is left alone  3ms

2 passed, 0 failed — 2564ms

A test is an ordinary function with no parameters, no result, and no type parameters — all three being the same requirement seen from different sides, since the runner calls it with nothing and reads the answer off whether it returned. Each is checked at the annotation rather than at the function, because the function is a perfectly good function and it is @test that made a promise about it.

The annotation has four forms. Bare @test names the test after the function; @test("a sentence") names it by the sentence, which is what the second one above does and why the runner prints prose for it. The other two are for the channel this chapter has been about: @test(should_trap) passes by stopping the program, and @test(should_trap: "past the end") additionally requires that text in what the run printed. That is how a trap gets tested at all — there is no catching it, so the runner is the thing that survives it.

assert(cond) traps when the condition is false, and names the file and line it failed on: its file and line parameters default to the reserved identifiers __FILE__ and __LINE__, and a default is evaluated at the call, so they report your line rather than the library’s.

The message is optional, and worth writing where it says something the condition does not — as "above the ceiling" does above, naming the case rather than restating the comparison. There is still no stringizer, so nothing reconstructs the expression that failed; what changed is that a failure carrying no message is now a location instead of the bare words “assertion failed”.

Next: a program that reads its input — putting the whole tour to work.

The complex module

2026-08-16T01:26:07.924728867Z

sysl.math.complex is one type. It is a submodule rather than part of sysl.math because Complex is not a name every numeric program wants in scope, and because sysl.math is mathematics on the floating-point types — which is not a sentence a type belongs in.

It requires no capability, so a freestanding target has it. The arithmetic is reachable under no alloc; rendering one is not — a specifier describes the field the whole value lands in, so the three pieces have to be gathered before the padding is applied, and gathering means a string. An allocator-free program computes with a Complex and prints its parts.

import sysl.math.complex.Complex

var a = Complex(3.0, 4.0)
var b = Complex(1.0, -2.0)

print(a, a.conj(), -a)
print(a.abs(), a.norm_sqr(), a.arg())
print(a + b, a - b, a * b, a / b)
print(a * 2.0, a / 2.0, a + 1.0)

3+4i 3-4i -3-4i
5 25 0.927295
4+2i 2+6i 11-2i -1+2i
6+8i 1.5+2i 4+4i

Importing the type is the whole of what a program does. Every operator above is a conditional conformance whose condition names Float — the library’s import, not yours.

Generic over the width, and why that is not a flourish

import sysl.math.complex.Complex
import sysl.math.Float

// A rotation, written once for both widths.
rotate[F: Float](z: Complex[F], theta: F) -> Complex[F] = z * Complex.expi(theta)

var wide = Complex(1.0, 0.0)
var narrow = Complex(1.0f32, 0.0f32)

print(rotate(wide, real.pi() / 2.0))
print(rotate(narrow, f32.pi() / 2.0f32))

6.12323e-17+1i
-4.37114e-08+1i

Complex[F: Float] is generic over the Float trait, so it is a Complex[real] or a Complex[f32] and never a widening of one into the other. The two are ordinary structs of two fields laid out at their own widths, with no dispatch between them — the parameter costs nothing at run time.

The library had already paid for this: sysl.math made the one-trait-two-widths investment so that x.sqrt() is the same three words whichever width x is. A complex type fixed at real would have been the first thing in the library to ignore it, and anyone working in binary32 would have had to write their own.

The two answers above differ in their real part because a quarter turn is not exactly representable in binary and f32 has seven digits where real has sixteen. That is the ordinary floating-point fact, and the page shows it rather than choosing an example that hides it.

The surface

struct Complex[F: Float]
    re: F
    im: F

    // Values that need no receiver.
    zero() -> Complex[F]
    one() -> Complex[F]
    i() -> Complex[F]
    from_real(x: F) -> Complex[F]
    from_polar(r: F, theta: F) -> Complex[F]
    expi(theta: F) -> Complex[F]

    // What a value is.
    conj(self) -> Complex[F]
    abs(self) -> F
    norm_sqr(self) -> F
    arg(self) -> F
    to_polar(self) -> (F, F)
    unit(self) -> Complex[F]
    recip(self) -> Complex[F]

    // Questions with a yes or a no.
    is_zero(self) -> bool
    is_real(self) -> bool
    is_imaginary(self) -> bool
    is_nan(self) -> bool
    is_infinite(self) -> bool
    is_finite(self) -> bool
    near(self, rhs: Complex[F], eps: F) -> bool

    // Exponentials, logarithms and roots.
    exp(self) -> Complex[F]
    ln(self) -> Complex[F]
    log(self, base: F) -> Complex[F]
    log2(self) -> Complex[F]
    log10(self) -> Complex[F]
    sqrt(self) -> Complex[F]
    powc(self, w: Complex[F]) -> Complex[F]
    powf(self, x: F) -> Complex[F]
    powi(self, n: int) -> Complex[F]

    // Trigonometry, circular and hyperbolic, each with its inverse.
    sin(self) -> Complex[F]
    cos(self) -> Complex[F]
    tan(self) -> Complex[F]
    asin(self) -> Complex[F]
    acos(self) -> Complex[F]
    atan(self) -> Complex[F]
    sinh(self) -> Complex[F]
    cosh(self) -> Complex[F]
    tanh(self) -> Complex[F]
    asinh(self) -> Complex[F]
    acosh(self) -> Complex[F]
    atanh(self) -> Complex[F]
end Complex

Plus Add, Sub, Mul, Div, Neg, Eq and Display — with Add, Sub, Mul and Div written twice each, once for another complex number and once for a real on the right.

Scaling is Mul at a second argument list rather than a second trait. The complex numbers are a vector space over the reals, and scaling is the operation a transform performs most often: every sample of an inverse, every window function, every spectrum read in decibels. z * k is the same answer as z * Complex(k, 0) and costs a quarter as much, and which of the two a * means is settled by the type of its right operand.

There is no Ord, because the complex numbers are not ordered — no order on them is compatible with the arithmetic:

import sysl.math.complex.Complex

print(Complex(1.0, 0.0) < Complex(2.0, 0.0))

'<' is not defined for sysl.math.complex.Complex[real]

sysl keeps Eq and Ord independent traits precisely so a type can have the one without the other. There is nothing to opt out of.

There is no scalar on the left. 2.0 * z would need an impl Mul[Complex[F]] for F, which is an implementation of a library trait for a built-in written by a module that owns neither — and it could not be one generic block, since F is a parameter rather than a type an impl can be written for. z * 2.0 is the same product.

Constructing one

import sysl.math.complex.Complex

var i: Complex[real] = Complex.i()

print(i, i * i)
print(Complex.from_real(2.0), Complex.from_polar(2.0, 0.0), Complex.expi(0.0))

var a = Complex(3.0, 4.0)
var p = a.to_polar()

print(p.0, p.1, a.unit().abs(), a.recip() * a)

0+1i -1+0i
2+0i 2+0i 1+0i
5 0.927295 1 1+0i

zero(), one() and i() take an annotation, and the ones beside them do not. They are associated functions of a generic type, so their width comes from what the context expects — and there is nothing to read it off in the middle of an expression. Everything else here is inferred from an argument: Complex.from_real(2.0) is a Complex[real] because 2.0 is a real.

expi(theta) is from_polar at radius one, and it has a name because that is how it is reached — a Fourier transform’s twiddle factor, a rotation, a phasor.

Exponentials, logarithms and trigonometry

import sysl.math.complex.Complex
import sysl.math.Float

var a = Complex(3.0, 4.0)

print(a.exp(), a.ln(), a.sqrt())
print(a.log2(), a.log10(), a.log(2.0))
print(a.powi(2), a.powf(0.5), a.powc(Complex(0.0, 1.0)))
print(a.sin(), a.cos(), a.tan())
print(a.sinh(), a.cosh(), a.tanh())
print(a.asin(), a.acos(), a.atan())
print(a.asinh(), a.acosh(), a.atanh())

-13.1288-15.2008i 1.60944+0.927295i 2+1i
2.32193+1.3378i 0.69897+0.402719i 2.32193+1.3378i
-7+24i 2+1i -0.0152837+0.395327i
3.85374-27.0168i -27.0349-3.85115i -0.000187346+0.999356i
-6.54812-7.61923i -6.58066-7.58155i 1.00071+0.00490826i
0.633984+2.30551i 0.936812-2.30551i 1.44831+0.158997i
2.29991+0.917617i 2.30551+0.936812i 0.117501+1.40992i

Three powers, because they are not the same function. powi is repeated squaring and is the only one that is exact — powi(2) of 3+4i is -7+24i and not something an ulp away from it. powf raises the magnitude and multiplies the angle. powc goes through the logarithm, and so carries its branch cut.

ln is the natural logarithm and is spelled for what it is, rather than as C’s bare log — which reads as though it were the general one and is the single most common way to get a base wrong. log(base) is the general one, and it takes a real base.

The operands a textbook formula does not survive

import sysl.math.complex.Complex

var huge = Complex(1.0e200, 1.0e200)
var tiny = Complex(1.0e-200, 1.0e-200)

print(huge.abs(), huge.norm_sqr())
print(huge / huge, tiny / tiny)

1.41421e+200 inf
1+0i 1+0i

This is why the module exists rather than the four-line struct a program would write for itself. Both lines are ordinary operands whose obvious formula answers nonsense.

abs goes through hypot, never norm_sqr().sqrt(). The magnitude of 1e200 + 1e200i is about 1.4e200 and is perfectly representable; its squared magnitude is not, and squaring first would have thrown the answer away before taking the root. norm_sqr overflowing is not a defect — that number really is out of range, and it is printed above so the contrast is on the page.

Division uses Smith’s algorithm, not (ac + bd) / (c² + d²). The textbook quotient forms the divisor’s squared magnitude, so both divisions above would be a NaN: an infinity over an infinity at the top of the range and a zero over a zero at the bottom. Dividing the smaller part of the divisor by the larger first keeps every intermediate within a factor of two of the answer’s own scale, which is the whole of the trick and costs one comparison.

A zero divisor is a NaN and not an infinity. It is the one place the complex quotient does not follow the real one: among the reals 1/0 runs off in the only direction there is, while a complex quotient has an argument as well as a magnitude and a zero divisor fixes neither. is_zero is the test a caller with a direction in mind writes.

norm_sqr is never spelled norm. C++’s std::norm(z) is the squared magnitude and Rust’s num-complex .norm() is the magnitude — the two precedents disagree, so the bare word would read as the wrong one to half of its readers and neither meaning is given it.

The branch cuts

import sysl.math.complex.Complex
import sysl.math.Float

var above = Complex(-1.0, 0.0)
var below = Complex(-1.0, -0.0)

print(above.ln(), below.ln())
print(Complex(-4.0, 0.0).sqrt(), Complex(-4.0, -0.0).sqrt())
print(Complex(2.0, 0.0).asin(), Complex(0.5, 0.0).asin().re)
print(Complex(1.0, 0.0).atanh().re, Complex(-1.0, 0.0).atanh().re)

0+3.14159i 0-3.14159i
0+2i 0-2i
1.5708-1.31696i 0.523599
inf -inf

The third line’s second value is printed as its real part alone, and deliberately. asin of a point inside [-1, 1] is real, so the imaginary part is zero — but it is zero by cancellation, and which zero a platform’s libm lands on is its own business: this machine answers 1.11022e-16 and glibc answers -0. Both are zero to within an ulp and neither is wrong. Pinning the digits would make the page a record of one C library rather than of sysl.

A function that is many-valued over the complex numbers is made single-valued by choosing where to cut, and which cut a library chose is the one thing a caller cannot work out from a signature. So they are written down here, and each is pinned by a test at the boundary itself rather than near it.

function	cut	principal value
`ln`, `log`, `log2`, `log10`	the negative real axis	`arg` in `(-pi, pi]`
`sqrt`	the negative real axis	non-negative real part
`powc`	inherits `ln`‘s	—
`asin`, `acos`	the real axis outside `[-1, 1]`	—
`atan`	the imaginary axis outside `[-i, i]`	—
`asinh`	the imaginary axis outside `[-i, i]`	—
`acosh`	the real axis to the left of `1`	non-negative real part
`atanh`	the real axis outside `[-1, 1]`	—

A negative zero says which side of a cut a value is on. arg puts pi itself on the cut, so -1 + 0i reads pi and -1 - 0i reads -pi — which is how a value that arrived at the axis from below keeps its side of it. The first two lines above are that, twice.

atanh has a pole at each end of its cut and runs off to an infinity of the right sign at both. It is written as a difference of two logarithms rather than one logarithm of a quotient for exactly that reason: the quotient form divides by zero at one pole and reaches ln(0) at the other, and would report the same singularity two different ways.

The command line

2026-08-16T01:26:07.924728867Z

Every subcommand takes a path, and a path is either a project root or a single file. That is not two modes bolted together — a module is a directory and its name is that directory’s path relative to the root, so naming a directory compiles the whole tree under it, one module per directory, and naming a file compiles that file alone. The modules reference has the rule the path is standing on.

The subcommands

	what it does
`sysl run <path>`	compile and execute
`sysl build <path> -o <exe>`	compile to a native executable
`sysl build-lib <path> -o <artifact>`	compile a library to a linkable artifact
`sysl build-c <path> -o <archive>`	compile to a static archive and a C header, for a C project
`sysl test <path>`	run the `@test` functions
`sysl emit-llvm <path>`	print the generated LLVM IR
`sysl emit-header <path>`	print the C header for what a module exports
`sysl weave <path>`	render a literate source as an HTML document
`sysl tangle <path>`	print the program a literate source holds
`sysl targets`	list the machines sysl can build for

sysl prove is an eleventh, and it has a page of its own — see verification.

A subcommand is required; sysl with none exits 2 and prints its usage.

`run`

sysl run hello.sysl

Four things in a row: the source is parsed and checked, textual LLVM IR is emitted, clang assembles and links it, and the binary runs. The executable goes to a temporary file and is removed afterwards — run leaves nothing behind.

Everything after a bare -- belongs to the program, not to sysl:

sysl run report.sysl -- --verbose report.txt

The split is made before sysl’s own options are parsed, which is the point: --verbose really is one of sysl’s own options, so without the -- sysl would have taken it — after it, it belongs to the program, and neither side has to know what the other’s flags are called. What arrives at main(args: []string) is the executable’s own path followed by those two words, so args.len is 3 — args[0] is the program, exactly as C’s argv[0] is.

run exits with the status the program exited with. It is running your program, so its status is your program’s — a compilation that failed is what exits 1 on sysl’s own behalf.

The program’s input is sysl’s input, so a program that reads works under run exactly as the built binary does:

printf 'one\ntwo\n' | sysl run count.sysl

What the program writes comes out as it writes it rather than all at once when it finishes, which is what makes a program that prompts usable here at all.

`build`

sysl build hello.sysl -o hello

The same compilation, stopping at the executable instead of running it. wrote hello goes to stderr so that stdout stays whatever the build was for.

-o is optional, and where it writes depends on what you named. Given a file, the name is that file’s, with its extension dropped, in the current directory: src/tools/fmt.sysl becomes fmt beside you.

Given a directory, the executable goes inside it, named after it. sysl build ., sysl build fmt and sysl build ../fmt are three ways of naming one project, and all three write fmt/fmt — so the answer does not depend on where you were standing when you asked. build-lib follows the same rule, writing fmt/fmt.syslib into the root it was built from.

A project whose package.hocon names dependencies gets them fetched here, if this machine has not got them already — see packages. run and test do the same; there is no separate step to remember, and a project with no dependencies does none of it.

`build-lib`

sysl build-lib mylib -o mylib.syslib
sysl run prog.sysl --lib mylib.syslib

A library compiled once into the two halves a program links against. See modules for what an artifact holds and why the generic half of it travels as trees rather than as object code.

A library may itself be built on another one, and --lib is what says so — it takes an artifact or a source root here exactly as it does for a compilation:

sysl build-lib sdl3 -o sdl3.syslib
sysl build-lib sdl3-ttf --lib sdl3.syslib -o sdl3-ttf.syslib

Unlike build, run and test, this does not fetch. A package with a dependencies block is refused rather than resolved over the network, and the message names the dependency and points at --lib. A command whose whole job is to compile one tree into an artifact for one machine should not be the thing that goes looking; the cost is that such a package writes its dependency down twice.

Building one needs an llvm-ar as well as a clang, because a .syslib is an ar archive — installation has the note about which ar and why the platform one will not do.

It compiles the package’s C, so it asks what that C needs. A package that declares its header requirements is refused here without --include-path <name>=<dir>, exactly as it is for a build — this being the command a package is published by rather than merely built by. It is asked for the package’s own manifest and nothing else: the C of a --lib source root is not compiled here, so that root’s declaration is not charged to a library built against it.

`build-c`

sysl build-c mylib -o libmylib.a
sysl build-c mylib -o libmylib.a --header include/mylib.h

build-lib‘s shape with a different destination: a static archive an existing C project links, and a C header declaring whatever the module marked @export. The compilation is the ordinary one rather than a library build — what is wanted is a module lowered for this target with its calls resolved — and what differs from build is that no entry point is emitted, since the C side supplies its own main.

The header goes beside the archive with .h appended unless --header names somewhere else. Both paths are announced on stderr, along with the archives the C project’s own link line will still need — an unresolved sysl symbol over there reads as a missing definition rather than as a missing archive, so it is worth being told before you meet it. --no-std-lib folds the standard library into the object and the archive then stands alone.

Like build-lib, this needs an llvm-ar as well as a clang. FFI has @export itself — what may be exported, what a symbol is named, and why a computed module val cannot be reached from one.

`emit-header`

sysl emit-header mylib

The same header build-c writes, on stdout and with nothing built, for a project that generates its headers as a build step.

`test`

sysl test <path>
sysl test <path> --filter <text>
sysl test <path> --fail-fast
sysl test <path> --std

The tree is compiled once, into a binary that runs one named test per process, and the runner starts it once per test. Attributes has @test itself — what a test may be, what every other build does with one, and why the process per test is the mechanism rather than a cost.

It takes the search-path flags too — --link-path, --include-path and -D, exactly as build does, and it needs them for the same reasons. A tree whose C includes a header the toolchain does not already know about, or whose constants come from a c const block over one, is a tree whose tests have to compile that C as much as its programs do. A package binding a system library is the ordinary case rather than a corner of one, so a test that could not be given those directories would be a test most packages could not run.

--std says the tree is the standard module, which is how sysl’s own library is tested. The compiler supplies sysl to every compilation, so without it the library arrives twice — once as the tree being compiled and once as the copy handed over — and every declaration is already declared. Nothing infers it: a program with a sysl directory of its own is nearly always a mistake, and a build that guessed would turn that refusal into a collision at the link.

The report groups by the file each test was written in, keeps source order inside a file, and shows a test’s output only where it failed:

running 4 tests

clamp.sysl
  ok    clamps below the low bound   6ms
  ok    clamps above the high bound  5ms
  FAIL  leaves a value in range      5ms
        did not return — exit status 1
        at clamp.sysl:31
        > panic: clamp(4, 1, 3) should be 3
  ok    is idempotent                5ms

3 passed, 1 failed — 21ms

A failure’s own line is one of three sentences and never more: did not return — exit status n, which is what a failed assert looks like since assert prints and exits; returned, and was expected to trap; and trapped, but printed nothing holding "…", for a @test(should_trap: "…") whose run trapped without saying it. Everything the run printed follows underneath, prefixed >.

--filter keeps the tests whose name or module holds the text, and the header says how many of how many are running. --fail-fast stops the loop rather than the report: what ran is still reported and what never ran is simply absent, because “skipped” would be a third verdict for something that is not a verdict.

Exit status is 0 if and only if every test that ran passed. A tree with no tests at all, and a filter that matched none of the tests there are, both exit 0 — neither is a failure, and each says which of the two happened rather than leaving one empty report to mean both.

None of that mechanism exists on a microcontroller. A process per test, a name in argv, a verdict in an exit status: a board has none of the three, so sysl test cannot follow the code onto one. sysl.harness is the other half — a framework linked into the image, which names its tests, locates a failure and prints a tally through a writer you hand it. Use this command for everything that runs on the machine you are typing on, and that for the checks that only exist on the target.

`emit-llvm`

sysl emit-llvm hello.sysl

The IR to stdout, the same text run and build hand to clang. Nothing is assembled and no toolchain is needed for it.

`weave`

sysl weave guide/lisp/lisp.lsysl -o lisp.html
sysl weave library/sysl/regex -o documents/

A literate source rendered as an HTML document. A .lsysl file is a Markdown document whose four-column-indented part is the program, which is what makes one readable with nothing rendering it — and an indented code block carries no language, so nothing can highlight it. weave tells the renderer that an indented block is sysl, which is the whole of the transformation: the source reaches the renderer exactly as written, and prose, tables, illustrations and heading levels are its own business.

What comes out is one file that opens by itself. It carries its own styling, in a light and a dark palette; its code is coloured by the same grammar this site highlights with; and its mathematics is set by KaTeX, which the page links. That last is the one thing a woven document needs the network for — the prose and the code are markup in the file, so a document read offline loses its equations to TeX source and nothing else.

The output goes to standard output, or to what -o names. A path holding several literate sources writes one document each, and -o then names a directory: a woven document is something somebody opens, so the unit is the file that was written rather than the tree. The ordinary .sysl files alongside are passed over, and a tree with no literate source at all is refused rather than producing an empty page.

It is a source-level command: no target, no standard module, no libraries. A package’s prose is worth reading on a machine that could not build it. What it does share with a compilation is the reading, so a file the compiler would refuse — a tab in an indent, a fence that is never closed — is refused here too, with the same message.

This is not an API reference generated from declarations. sysl has no documentation comment yet, so there is nothing for such a thing to read, and doc is left unclaimed for the day there is.

`tangle`

sysl tangle guide/lisp/lisp.lsysl
sysl tangle guide/lisp/lisp.lsysl -o lisp.sysl

The other half of a literate system: the program, with the prose stripped. A build tangles anyway — that is how a .lsysl file compiles at all — so what this adds is a way to see it.

That is worth having when a literate file misbehaves. A block indented that should not have been, a fence that swallowed a function: the question is always what the compiler actually read, and this is how to ask. It also hands the program to anything that does not know the format — a tool, a paste, a bug report.

The prose is replaced by blank lines rather than removed, so line 100 of the output is line 100 of the source. That is what lets a diagnostic about the program point into the document it was written in, and it is why the output is not as short as the program looks.

`targets`

The registry, one line per machine — the name to write after --target, the LLVM triple it stands for, and, for a target sysl knows and cannot build for, why not:

aarch64-macos                arm64-apple-macosx
x86_64-macos                 x86_64-apple-macosx
aarch64-linux                aarch64-unknown-linux-gnu
x86_64-linux                 x86_64-unknown-linux-gnu
riscv64-linux                riscv64-unknown-linux-gnu
x86_64-windows               x86_64-pc-windows-msvc
aarch64-freestanding         aarch64-none-elf
x86_64-freestanding          x86_64-unknown-none-elf
riscv64-freestanding         riscv64-unknown-elf
thumb-freestanding           thumbv8m.main-none-eabihf
thumb-freestanding-softfp    thumbv8m.main-none-eabi
thumb-freestanding-soft      thumbv8m.main-none-eabi
thumbv6m-freestanding        thumbv6m-none-eabi
thumbv7m-freestanding        thumbv7m-none-eabi
thumbv7em-freestanding       thumbv7em-none-eabihf
thumbv7em-freestanding-soft  thumbv7em-none-eabi
riscv32-freestanding         riscv32-unknown-elf
wasm32-freestanding          wasm32-unknown-unknown
craft-freestanding           craft
x86-linux                    i386-unknown-linux-gnu  (no C calling convention has been measured for x86)

The line for the machine you are on is marked (this machine), and a last line repeats what that machine’s own runtime called itself. That last line is there for the case the rest of the list cannot help with: on a machine sysl has no entry for, it is the only place to read what the machine actually said.

Eight of the freestanding rows are 32-bit microcontrollers. The RP2350 — the Pico 2 — boots either a pair of Cortex-M33s or a pair of RV32IMAC cores; the RP2040, the original Pico, has a pair of Cortex-M0+; the Armv7E-M rows are ST’s parts; and Armv7-M is the Cortex-M3. All are here because a microcontroller is what freestanding is mostly for: the three 64-bit freestanding rows reach kernels and hypervisors, which is a different audience. thumb rather than arm names the Arm ones because a Cortex-M executes Thumb only, so an arm written for A32 would assemble for a machine that cannot run it.

The Cortex-M33 has three rows, because neither the float ABI nor the FPU’s presence is sysl’s to pick. thumb-freestanding passes floating-point arguments in VFP registers, which is what eabihf selects; thumb-freestanding-softfp passes them in core registers, which is what -mfloat-abi=softfp means and what pico-sdk builds by default. The two cannot be mixed — GNU ld refuses the link outright, saying one object “uses VFP register arguments” and the other “does not” — so a sysl archive joining a C build has to agree with that build, and offering only the first row meant the C had to be rebuilt to follow sysl. Pick the one your project already uses; if you do not know, softfp is the pico-sdk default.

Both of those rows use the M33’s own unit, which is single precision. f32 arithmetic is instructions and f64 arithmetic is a call into the board’s runtime — __aeabi_dmul and its family — because an fpv5-sp-d16 has no double-precision instructions to select. That is the part rather than a setting, and it is worth knowing before a f64 goes into an inner loop.

thumb-freestanding-soft is the third, and it is for a board with no unit at all. softfp is not soft: -mfloat-abi=soft means no FPU instructions whatever, while softfp uses the fpv5-sp-d16 this core has and changes only the calling convention. That distinction is not something a triple can carry — both rows are thumbv8m.main-none-eabi — so sysl says which it is on every clang command line, with the convention beside it: -mfloat-abi=soft -mfpu=none for the soft row, -mfloat-abi=softfp -mfpu=fpv5-sp-d16 for softfp, and -mfloat-abi=hard -mfpu=fpv5-sp-d16 for the first. None of that is left to the compiler’s default, because the default is not the same one twice: the same triple reports a floating-point unit under some clangs and none under others, so a row that said nothing would mean a different machine depending on which was installed. Reach for it when your board’s headers say the FPU is off, which is where the difference announces itself: CMSIS refuses the build with “Compiler generates FPU instructions for a device without an FPU (check __FPU_PRESENT)”, and every Zephyr MPS2 board is configured that way. Getting it wrong the other way is worse than a refusal — the image links, boots, and takes a fault at whatever arithmetic reached a VFP instruction first.

thumbv7em-freestanding and thumbv7em-freestanding-soft are that same pair for Armv7E-M — an STM32 F4 or H7 with the FPU on, and one with it off.

thumbv6m-freestanding and thumbv7m-freestanding are different architectures, not further conventions. The first is the RP2040’s Cortex-M0+ — Armv6-M, which came before Armv8-M rather than being a subset of its options — and the second is the Cortex-M3. Build an original Pico’s program for thumbv6m; building it for a thumb- row produces instructions the core cannot execute, and the failure is a fault at whatever ran first rather than a refusal at the link. Neither core has a floating-point unit in the architecture, so neither needs a -soft sibling: there was never a second answer to give.

Build a Cortex-M3’s program for thumbv7m rather than for thumbv6m, even though Armv6-M code runs on an M3. What does not survive the substitution is the headers: a real project reads its own configuration, so it takes CONFIG_CPU_CORTEX_M3 to mean Armv7-M and reaches for BASEPRI, while CMSIS reading an Armv6-M triple hands it an intrinsic set that has none.

One thing needs the board’s help on that target, and only one. Armv6-M has no atomic instructions, so a program using &sync — the shared counted reference — compiles to calls the toolchain does not supply, and the link fails naming __atomic_fetch_add_4. Every other program is unaffected, because those calls are emitted only for a program that holds a &sync. The pico package supplies them over one of the chip’s hardware spinlocks, which is what a dual-core part needs — masking interrupts is per-core and would leave the other core free to lose the update.

wasm32-freestanding is the odd row: 32-bit, freestanding, and not a board at all. It is WebAssembly — a browser, wasmtime, or whatever else embeds a module — and unknown-unknown in the triple is the literal truth, so it comes with no libc, no loader and nothing that runs before an exported function is called. Sysl links it with -nostdlib and names main as the module’s entry, which is what makes main reachable and exports it under that name; a program that does not print comes out as a couple of hundred bytes of .wasm that wasmtime will run, and a program that does print fails at the link naming putchar, exactly as on any other bare target.

It needs a clang with the WebAssembly back end. Apple’s has eleven back ends and this is not among them, so on a Mac sysl reaches for Homebrew’s LLVM by itself — the same fallback it already makes for the RISC-V rows — and says so if it cannot find one.

craft-freestanding is 16-bit, and it is the one row sysl will not drive a build for. It is CRAFT — a teaching ISA with eight registers, a 64 KiB virtual address space and a software-managed TLB — whose LLVM back end lives out of tree, so what exists is an llc rather than a compiler driver. The machine has no libc, no object format and no linker: its assembler reads one file and resolves every label inside it. So sysl writes the LLVM and stops, and the rest is two commands of your own:

sysl emit-llvm hello.sysl --target craft-freestanding > hello.ll
llc -march=craft hello.ll -o hello.s
craft as hello.s

Every other subcommand refuses this target and says that. It is not a target sysl cannot lower for — emit-llvm produces an ordinary module — it is one with nothing for a driver to call.

Sixteen bits is the part that shows up in your code. usize is pointer-width by definition, so a slice’s length is a u16 and the address space is the bound on everything. An int is still 32 bits and a long still 64, because a width is the language’s answer rather than the machine’s — so ordinary arithmetic here is multi-word, and the back end expands it, exactly as every 32-bit target already expands a long. Indexing with an int needs no conversion for it: an index wider than an address is checked against what an address can name and then narrowed, so for i in 0..<4 do b[i] … means what it means everywhere else.

x86-linux is listed because it cannot be built for. The limit is the compiler’s rather than the machine’s, and it is no longer the width — this page said so until the 32-bit rows above arrived. What is missing is a C calling convention measured against clang, which is the only way a target’s answers are allowed to be arrived at. A reader who names it is better told that than told the name is unknown.

Freestanding does not mean self-contained. A program built for a bare board still names C symbols its runtime has to define — putchar wherever anything prints, free wherever a reference count can reach zero, memcpy and memset for a structure assignment you never wrote — and on a 32-bit machine it names a 64-bit division helper as well, because a long is sixty-four bits everywhere and neither RP2350 core has the instruction. None of that is a sysl dependency the compiler could warn about: it is what any C compiler emits for the same code, and a real project never meets it because its SDK has linked libgcc or compiler-rt already. Meeting it looks like undefined symbol: __aeabi_ldivmod at the link, which is the one place anybody will come looking for this paragraph.

Flags every subcommand takes


`--target <name>`	the machine to build for; defaults to this one
`--lib <path>`	a library to compile against; may be given more than once
`--std-lib <path>`	a prebuilt standard module
`--no-std-lib`	compile the standard module from source rather than linking a prebuilt one
`--ar <path>`	the `llvm-ar` to build a library with
`--link-path <dir>`	where to look for a library a `link` directive named; may be given more than once
`--include-path <dir>`	where to look for a header the C beside a module includes; may be given more than once
`--include-path <name>=<dir>`	the same, and it answers the header requirement a package declared under that name
`-D NAME` or `-D NAME=value`	a macro the C beside a module is compiled with; may be given more than once
`-O <level>`	the optimization level handed to clang
`-v`, `--verbose`	report what the build decided — the standard module, the files read, the command lines, and where `build-lib` staged
`--explain-escapes`	report every local array promoted to the heap

The standard-module flags and -O are covered in installation, including why the default is -O1 and not off.

`--link-path`, `--include-path` and `-D` are three steps of one thing

A module that binds a C library carries C of its own, and that C has to be found, compiled and linked. The three flags answer the three ways it fails, in the order it fails them:

--include-path — the shim #includes the library’s header and cannot find it. This is the first failure and the one that surprises, because it happens before anything reaches a linker.
-D — the header is found and refuses, because a C project of any size configures its own headers with macros and has not been asked. pico-sdk’s pico/cyw43_arch.h #errors rather than guessing which architecture variant is meant, which is the shape to expect.
--link-path — everything compiled and the archive is not where the linker looks.

Nothing is guessed at and nothing is defaulted. sysl does not add /opt/homebrew/lib, and it does not invent a macro: a compiler that ruled on where a platform keeps its libraries, or on how a project configures its headers, would be wrong on a machine nobody here has — and being wrong there costs a build that fails somewhere its author cannot reach. What a project defines is the project’s.

A build system that already knows these will have them: reading them out of CMake is a matter of asking the target for its INCLUDE_DIRECTORIES and COMPILE_DEFINITIONS and handing each along.

A package whose C includes headers it does not carry can say so, and then the first failure above stops being a surprise: written --include-path <name>=<dir>, the flag answers a requirement the package declared, and a build that is missing one is refused by name before clang runs. See packages.

`--lib` takes either a source tree or an artifact

Which one a path names is read off the name: a .syslib is decoded, anything else is walked as source. That is deliberate — how a library was shipped is the shipper’s business, and a program depending on one should not have to write down which it got. build-lib is what turns the first into the second, and the only difference downstream is what the compilation cost: an artifact is a linear decode where source is a parse.

`--target`, and the one thing `run` will not do

Given no --target, a build is for the machine it is running on. If that is a machine sysl has no entry for, it says so and stops rather than guessing, because a wrong guess produces a module that looks right and is not.

run executes what it builds, and only this machine can do that, so a cross target is refused before the build rather than after it:

sysl: error: 'run' executes what it builds, and 'x86_64-linux' is not this machine — use 'sysl build --target x86_64-linux'

A name the registry does not have is answered with the names it does:

sysl: error: unknown target 'arm-linux' — sysl knows aarch64-macos, x86_64-macos, aarch64-linux, x86_64-linux, riscv64-linux, x86_64-windows, aarch64-freestanding, x86_64-freestanding, riscv64-freestanding, thumb-freestanding, thumb-freestanding-softfp, thumb-freestanding-soft, thumbv6m-freestanding, thumbv7m-freestanding, thumbv7em-freestanding, thumbv7em-freestanding-soft, riscv32-freestanding, wasm32-freestanding, craft-freestanding, x86-linux

`-v`, `--verbose`

What the build decided, on stderr — which is where wrote <exe> goes, so stdout stays whatever the build was for:

sysl: 1 source file(s) under hello
sysl:   read hello/hello.sysl
sysl: standard module linked from ~/Library/Caches/sysl/<version>-…/std.syslib
sysl: link: clang --target=arm64-apple-macosx -Wno-override-module -O1 …

Three things, and they are the three that have actually been the answer to a question: which standard module the compilation got and whether it was linked or compiled from source, the files it read, and the command lines handed to clang together with the --lib, --link-path and --include-path searches behind them. There are no phase timings: a build that is slow is diagnosed by asking what it did.

build-lib adds a fourth, because it is the one command that writes anywhere but the artifact it was asked for:

sysl: members staged in /var/folders/…/sysl-lib-1729384756

The members are archived under names of their own rather than under whatever a temporary file was called, which is what the directory is for, and it is removed whether the build succeeded or gave up partway. The line is there for the run that is interrupted in between: what is left behind is a directory nothing else would have named.

`--explain-escapes`

On stderr, one line per local array the compiler moved to the heap, and the view that forced the move:

$ sysl build --explain-escapes tty.sysl
tty.sysl:31:12: 'buf' is promoted to the heap, because this view of it is returned

The position is the view, not the declaration, because that is the half a reader cannot work out for themselves. Where nothing was promoted it says so, in as many words, rather than printing nothing and leaving you to wonder whether the flag took. Memory has what promotion is and when it happens instead.

`-O2` is written the way clang writes it

A short option normally takes its value as the next argument, and clang’s optimization flag has been written joined since cc. So -O2 is rewritten into -O 2 before the options are parsed — only that letter, and only where something follows it, so a bare -O still takes the next argument and --optimize is untouched. Nothing in that rewrite can reach the program’s own arguments, which were already split off at the --.

Two combinations that are refused

Neither is resolved by precedence, because whichever precedence were chosen would silently discard half of what was asked for:

sysl: error: --core-lib compiles against the standard module, and 'build-lib --core' is what builds it
sysl: error: --no-core-lib and --core-lib ask for different standard modules

The first is build-lib --core --core-lib x, which cannot mean anything: the declarations being compiled are the ones the artifact holds. The second is the pair of near-identical spellings that a typo produces.

Exit statuses


0	it worked — and for `test`, every test that ran passed
1	a compiler diagnostic, a driver error, or a failing test
2	the command line did not parse
the program’s	`run` only, once the program has started

A compiler diagnostic is printed exactly as the compiler wrote it, with its location and a caret under the offending column. A driver error — something that went wrong around the compilation rather than inside it — is prefixed sysl: error:, which is why every message quoted on this page carries it and none of the ones on the language pages do.

Next: the tour, which uses run throughout.

A program that reads its input

2026-08-16T01:26:07.924728867Z

Here is everything the tour has covered, doing one job: count the lines, words and bytes of some text, and report the longest line.

import sysl.io.{Reader, lines}

// A source of bytes over storage the program already has.
struct SliceReader
    src: []const u8
    at: usize

// `Reader` requires `Fallible`, whose one member has a default — so this line
// is the whole of the implementation, and it says "reading this cannot fail".
impl Fallible for SliceReader

impl Reader for SliceReader
    read(*self, into: []u8) -> []const u8
        var left = self.src.len - self.at
        var n = if left < into.len then left else into.len

        for i in 0..<n do into[i] = self.src[self.at + i]

        self.at += n
        into[0..<n]

struct Stats
    lines: int
    words: int
    bytes: int
    longest: string
    invariant lines >= 0

words_in(s: string) -> int
    var n = 0
    var inside = false

    for b in s.bytes
        if b == 32 then inside = false
        elif !inside
            n += 1
            inside = true

    n

tally(src: *Reader) -> Stats
    var st = Stats(0, 0, 0, "")

    for line in lines(src)
        st.lines += 1
        st.words += words_in(line)
        st.bytes += int(line.len) + 1

        if line.len > st.longest.len then st.longest = line

    st
end tally

var sample = """
    the quick brown fox
    jumps over
    the lazy dog
    """

var r = SliceReader(sample.bytes, 0)
var st = tally(&r)

print("lines:", st.lines, "words:", st.words, "bytes:", st.bytes)
print("longest:", st.longest)

lines: 3 words: 9 bytes: 44
longest: the quick brown fox

Sixty lines, and almost every chapter of the tour is in there. Worth walking through what each part is leaning on.

The reader is a trait implementation

Reader asks for one method — hand me a buffer, tell me what you put in it — and SliceReader answers it over bytes the program already has. Nothing about the rest of the program knows which kind of source it got.

Notice the return type. read hands back a view of the caller’s own buffer, not a count, and that is the shape rather than an accident: a []const u8 already is a count and a pointer, so there is no way to be handed one and forget to apply it to the other. An empty result means the input ended.

into[0..<n] is a []u8 flowing into a []const u8 return type, which is the widening the arrays chapter described — giving up the ability to write is a promise the callee can always make.

The bare impl Fallible for SliceReader line is a required trait at work. Reader requires Fallible, so implementing one obliges the other; and because Fallible‘s single member has a default, there is nothing left to write and the block is empty. Whether a stream ended and whether it ended badly are separate questions — the first is answered by an empty result, the second by failed, and a source that cannot go wrong should not have to write down that it cannot.

The tally takes a trait object

tally(src: *Reader) is the dynamic side of the trait: one copy of the code, dispatching through the table, so it works over any source at all. &r at the call site erases the SliceReader into a *Reader, which is a two-word fat pointer and costs no allocation — which is why a kernel can use this shape.

A bound would have worked too. tally[R: Reader](src: *R) would monomorphize, giving a direct call per source type. The trait object is the right choice here because the point of the program is that the source is interchangeable.

The loop walks a cursor

lines(src) hands back a cursor implementing Iterate[string], and for walks anything that does. That means the loop reads a line at a time out of a 4 KiB chunk, rather than pulling the whole input into memory — and it looks exactly like the for x in xs that walks an array.

Each line is a string, so it is guaranteed well-formed UTF-8 and line.len is its byte length. st.longest = line costs no copy: a string is three words sharing its bytes, so keeping the longest line means retaining the chunk it came out of and nothing more.

The struct keeps a rule

invariant lines >= 0 is checked at construction and at every field write — including st.lines += 1, which is a compound assignment and owed the same re-check. If some later edit made the count go backwards, the program would stop at the write that broke it rather than somewhere downstream where a negative line count finally mattered.

words_in is the only piece doing real byte work, and it does it over s.bytes — the string’s storage as a read-only view. No allocation, no decoding, no copy.

Swapping the source

The point of writing it against a trait is this diff, which is the entire change needed to read the program’s actual input:

import sysl.io.{stdin, lines}

var src = stdin()
var st = tally(&src)

print("lines:", st.lines, "words:", st.words, "bytes:", st.bytes)

stdin() gives an FdReader, which implements the same Reader over a file descriptor. tally is untouched, and so is everything under it. A freestanding target that has no file descriptors substitutes one body — a read syscall — and the whole surface above it is unchanged.

That is the shape the standard library is built in, and it is worth taking away from the tour more than any single feature: the seam is a trait with one method, the thing on either side of it is ordinary sysl, and nothing in the middle had to be told which.

Where to go from here

You have seen the whole language. What is left is depth:

The reference is this same material in the other shape: every construct written down once, in its own place, with the rules complete rather than the beginner’s subset. The tour teaches in the order things make sense to learn; the reference answers a lookup — what may follow for, what ? does to a &T payload, which slice forms exist.
The library documents each module the table in modules named, one page each, down to what a no alloc program may reach.
The design chapters in the compiler’s design/ are the specification — every rule in this tour is stated there with the argument for it, including the alternatives that were rejected and why.
The guide programs are fourteen complete programs at the size where the choices start to matter — a JSON parser, a scheduler, SHA-2, a slab allocator, a ring buffer, a datetime library, a Lisp — each written to force a language decision rather than to demonstrate a finished one. The pages say what each found, which is most of the reason the language is shaped the way it is.
The standard library’s own source is the best worked example there is. Buf, StrBuilder and the Reader above are ordinary sysl over the same features this tour covered — there is no privileged layer underneath them.

bytecode

2026-08-16T01:26:07.924728867Z

A compiler for a small language and a machine that runs what it emits, over one shared instruction set.

The axis: the module system, and this is the only program in the set with an end-to-end assertion. Source text goes in, the compiler emits bytecode, the machine runs it, and what it printed is compared against what the program should print. No golden file stands in the middle, and the one place an intermediate form is inspected is the section that is about the intermediate form.

Three modules, and their shape is the point. isa is what the other two agree on — the opcodes, the buffer a program is emitted into, and how to read one back. compiler and vm each depend on it and neither depends on the other, which is a DAG rather than a rule anybody had to remember. compiler is two files because it grew to two, and nothing about either says so: they name each other’s declarations with no ordering and no forward declaration, which is what a module being a directory buys.

It is also the program that carries a capability clause — no alloc on the VM half — which is the declaration guide/slab and guide/kernel both wanted and neither could use, because a capability is a property of the whole directory.

What it found

A simple enum narrower than int could not be matched at all. enum Op: u8 is the natural way to write an instruction set — the opcode is a byte — and every match on one emitted a comparison at the wrong width, which the assembler refused. A compiler bug rather than a language one, found by the first program that wanted a narrow enum for the reason narrow enums exist, fixed at the source, and now covered by tests at i8, u8 and u16.

Result[unit, E] could not be written, and a compiler front end is all valueless fallible steps. Every parse step here emits code and yields nothing, so every one used to say Result[bool, Fault] with a bool that meant nothing — a placeholder payload keeping ? working.

Answered by making unit a zero-sized type: it has a layout, the empty one, so a field or a parameter of it is skipped rather than refused. Every one of those signatures now says what it means, and Ok(()) costs a getelementptr fewer than Ok(true) did. The finding earned its own entry because two unrelated programs paid for it — see png, which has nothing in common with a parser.

An assignment is an expression, so a two-branch if whose branches each end in one was checked as though those were its result. The unit-branch rule saved the case where one side was a statement and saved nothing where both sides assigned: full = true against len += 1 is a bool against a usize. That sharpened what hashmap had found about match — the trouble was never that match lacked a rule if had, it was that assignment is an expression and any two-armed form inherited it. Answered by taking the position instead: a block whose own value is unused has none.

A line could not be continued. There was no trailing-operator continuation, so a condition that outgrew its line had to become a sequence of early returns. Answered — and the rule that landed carries four exclusions, because an operator at the end of a line is not always a promise that the expression goes on.

Source · Next: png — somebody else’s format, byte by byte.

The buf module

2026-08-16T01:26:07.924728867Z

sysl.buf holds two types and three functions, and the interesting thing about the larger of them is what it is not: Buf[T] is not a type the compiler knows. It is a []T field for the storage, a usize for how much of it is live, and a dozen members — ordinary sysl, in a file a program could have written.

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push(1)
b.push(2)
b.push(3)

print(b.len(), b.cap(), b.is_empty())
print(b[0], b.at(2))

b[1] = 20

print(b.view().len, b.view()[1])

3 8 false
1 3
3 20

Nothing in the language reaches it. An array literal makes a []T, a for walks whatever implements Iterate, and neither of those is a growable sequence — so a program that wants one asks, and the import is where it asked. That is the core module’s rule applied from the other side: what a program cannot avoid needing arrives free, and what it has to ask for it asks for.

Why it can be written at all

A container that sizes its own storage needs three things, and sysl’s design notes once recorded all three as reasons this could not be a library type: sizeof over a type parameter, a cast to reach the elements through it, and above all a destructor, since the language had exactly one and no way to write another.

All three were the wrong answer, and none of the three is an absence now — a destructor is writable. A container does not need one if its storage is a value that already has one — the []T field is an ARC-owned buffer, so when a Buf goes, its storage goes with it, and nothing in the container has to say so. The one thing genuinely missing was the ability to ask for storage at a length worked out while running, and once a []T could be sized that way, Buf[T] was a hundred lines with no unsafe primitive in them.

A second apparent blocker dissolved the same way. A generic container cannot make its own storage, because an array is built by repeating a value and no bound promises that T has one. But a push arrives holding one — the value being pushed seeds the new storage, and the question never comes up.

struct Buf[T]
    elems: []T
    count: usize

    len(self) -> usize
    cap(self) -> usize
    is_empty(self) -> bool

    at(self, i: usize) -> T
    set(*self, i: usize, v: T)

    push(*self, v: T)
    extend(*self, xs: []const T)
    pop(*self) -> Option[T]

    insert(*self, i: usize, v: T)
    remove(*self, i: usize) -> T
    truncate(*self, n: usize)
    clear(*self)

    view(self) -> []T

It is generic over anything, including counted types — a Buf[string] retains and releases its elements like any other slice of them:

import sysl.buf.{Buf, buf}

var names: Buf[string] = buf()

names.push("ada")
names.push("grace")

print(names.len(), names[1])

2 grace

Bounds: a panic here, an `Option` there

at and set panic on an index past the end. pop returns an Option. That looks like two minds about the same question and is not:

An index past the end is a mistake in the program, not a value it meant to handle. Taking from an empty sequence is a question a caller asks on purpose.

It is the same bargain unwrap makes. A pop that returned T and panicked would make every drain loop write a length test it could have got from the answer.

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push(1)
b.push(2)
b.push(3)

print(b.pop().unwrap())
print(b.remove(0))
print(b.view()[0], b.len())

b.truncate(0)

print(b.len(), b.cap(), b.is_empty())

var e: Buf[int] = buf()

print(e.pop().is_none())

3
1
2 1
0 8 true
true

truncate, clear and remove are one operation seen three ways. truncate(n) lowers the count, and does nothing where n is a length the buffer does not have — a length past the end names no element, so unlike an index there is nothing for it to read and nothing to stop the program about. clear() is truncate(0). remove(i) shifts the survivors down over element i, hands that element back, and ends at truncate; an i that names no element is at‘s panic, for at‘s reason.

insert(i, v) is remove‘s other half, putting an element at i and moving everything from there on up one. Inserting at len is a push and is allowed for that reason — a loop inserting at a cursor reaches the end on its last step, and refusing there would make every caller write the case this one already handles. Anything past len is a gap, which a sequence cannot represent, and panics the way any other index past the end does.

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.extend([1, 3, 4])
b.insert(1, 2)
b.insert(4, 5)

print(b.view()[1], b.len())

2 5

Hand-rolling it is a shift written backwards — a loop walking up overwrites the element it is about to read — and that is where the off-by-one lives.

What none of truncate, clear and remove does is give storage back. The cap() of 8 survives the truncate above. The elements above the count are still values in a []T that ARC owns — which is also why a copy of a Buf taken before a removal reads the shifted elements at the length it was copied at.

Subscripting goes through the checked members

impl[T] Index[usize, T] for Buf[T]
    index(self, i: usize) -> T = self.at(i)

impl[T] IndexSet[usize, T] for Buf[T]
    index_set(*self, i: usize, v: T) = self.set(i, v)

b[i] on a Buf means b.at(i), and that is worth more than the syntax. The backing slice is longer than the count — subscripting the storage would happily read a slot the buffer does not consider live, and every bounds check in the language would pass. Routing [] through at is what makes b[i] unable to see spare capacity.

The cost is that reading through Index is a call, so it yields a value rather than a place:

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push(1)
b[0] += 1

'+=' on an element read through 'sysl.Index' would evaluate the receiver and the index twice

b[0] = b[0] + 1 is the spelling, and writing it out is the point: the expansion the compiler declines to make would evaluate b twice and the index twice, which for a receiver that is a call, or an index that advances a cursor, is wrong rather than merely wasteful.

Two other shapes a first program tries. len is a method, unlike StrBuilder‘s property:

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

print(b.len)

'len' is a method of 'sysl.buf.Buf[int]' — call it with 'len(…)'

And a Buf is not itself iterable — it implements Index, not Iterate:

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push(1)

for x in b
    print(x)

'for' iterates an integer range, an array, a slice, or a type that implements 'sysl.Iterate', and sysl.buf.Buf[int] is none of those

for x in b.view() is how it is walked, and that is not a workaround — it names the thing being iterated, which is the live prefix at the moment the loop started.

`view` is the bulk read, and it is a view

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push(1)
b.push(2)

var v = b.view()

print(v.len, b.cap())

b.push(3)
b.push(4)
b.push(5)
b.push(6)
b.push(7)
b.push(8)
b.push(9)

print(v.len, v[0], v[1])
print(b.len(), b.cap())

2 8
2 1 2
9 16

The seventh push overflowed a capacity of 8, so the elements moved to a new buffer of 16. v is unchanged and still valid — that is the whole of what this shows.

It does not dangle, because the storage it was made from is an ARC buffer like any other and the view keeps it alive. Go’s version of this is the famous confusion: two slices that agree until one of them grows, and afterwards agree about nothing. Here the guarantee is stronger and simpler — a program with no *T in it cannot fault, so the old storage stays until the last view of it goes.

What v does not do is grow with the buffer. It is a view of some elements and it has the length it was made with. Take it again to see more.

How a push is seen follows from how the `Buf` is held

sysl does not have to choose here, and that is the point:

import sysl.buf.{Buf, buf}

var p: &Buf[int] = buf()
var q = p
var c = *p

p.push(1)

print(q.len(), c.len())

1 0

q is a second name for one buffer, so it sees the push. c is a copy, because copying a struct is what *p means. Neither is a rule about growable sequences — both are the memory modes doing exactly what they do for any struct, and the author wrote which one they wanted.

Capacity, and what it costs

import sysl.buf.{Buf, buf_with_capacity}

var w: Buf[int] = buf_with_capacity(100, 0)

print(w.len(), w.cap())

w.push(7)

print(w.len(), w.cap(), w[0])

0 100
1 100 7

Growth is geometric — a full buffer doubles — and buf_with_capacity skips the reallocate-and-copy at each doubling on the way up to n. It is a guess and nothing depends on it: too small and the buffer grows the way it always does, too large and the slack goes with the rest. extend sizes the same way rather than fitting exactly, so a loop of extend calls stays amortized constant per element instead of turning quadratic the way += on a string does.

The fill is a parameter, and that is T having no zero. An array is made by repeating a value, and nothing about a type parameter says what an unused slot should hold. Leaving it out is an ordinary arity error:

import sysl.buf.{Buf, buf_with_capacity}

var c: Buf[int] = buf_with_capacity(8)

function 'sysl.buf.buf_with_capacity' takes 2 arguments, but 1 argument was given

None of those slots is ever read — count starts at zero, so every one of them is written before anything can see it. But they are real values, and that is the honest cost of a growable sequence in this language: there is no way to have storage that is merely reserved. A Buf[&T] grown to a capacity of 1024 while holding one element is holding 1024 references to whatever seeded the growth, and that object stays alive until the slots are overwritten. Capacity that is not yet values is a known gap, not a solved problem.

It needs an allocator, and says so

@no_alloc

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push(1)

print(b.len())

this reaches 'sysl.buf.buf.int', which makes heap storage, and this module declared '@no_alloc'

Both buf() and the push are named, because alloc is checked on what a module calls. There is no allocator-free Buf and there cannot be one: growing is the whole of what it does.

`ByteSink`

struct ByteSink
    bytes: &Buf[u8]

    text(self) -> []u8

impl Fallible for ByteSink

impl Writer for ByteSink
    write(*self, bytes: []const u8) = self.bytes.extend(bytes)

That is the entire type. It is one of the two Writers the library supplies — the other is Stdout, which stands for standard output, holds no state at all, and is therefore a struct with no fields. The buffer str and an f"…" hole render into is still the compiler’s, since a growable byte array is not something it can name at the layer it needs one.

impl Fallible for ByteSink has no block, and does not need one: every member of Fallible has a default, so implementing the latch on a buffer that has nothing to fail at is entirely a matter of opting in.

import sysl.buf.byte_sink

var sink = byte_sink()
var out: *Writer = &sink

display_int(42, out, FormatSpec(6, -1, false))
out.write("|".bytes)
display_str("ok", out, FormatSpec(0, -1, false))

putbytes(sink.text())
prints("\n")
print(sink.failed(), sink.text().len)

    42|ok
false 9

Why it is in the library rather than in each program

Because an implementation that renders more than one part cannot honour its specifier without one. A format specifier describes the field the whole value occupies, so a rendering of 1, +, 2, i has to pad what those four came to rather than each of them; padding needs the finished bytes; and the finished bytes need somewhere to land.

import sysl.buf.byte_sink

struct Complex
    re: int
    im: int

impl Display for Complex
    display(self, out: *Writer, fmt: FormatSpec)
        var sink = byte_sink()
        var gather: *Writer = &sink

        display_int(long(self.re), gather, FormatSpec(0, -1, false))
        gather.write("+".bytes)
        display_int(long(self.im), gather, FormatSpec(0, -1, false))
        gather.write("i".bytes)

        display_pad(sink.text(), out, fmt)
    end display

print(Complex(1, 2))
print(f"[${Complex(1, 2)}%8s]")
print(f"[${Complex(1, 2)}%-8s]")

1+2i
[    1+2i]
[1+2i    ]

Note the two specs. The inner FormatSpec(0, -1, false) is neutral — the parts are rendered plainly — and only display_pad at the end sees fmt. An implementation that forwarded fmt down to each part would pad the 1 to eight columns and then the 2, which is not what %8s on a complex number meant.

Every such implementation would write the same dozen lines, which is the definition of something that belongs in the library. What a program still writes for itself is an ordinary impl Writer for MyThing — a counter, a device, a bounded buffer that latches — and that remains the case the trait exists for.

A `Writer` may not keep what it is written

write takes a []const u8 that may be a view of the caller’s stack — that is exactly what the display_* renderers hand it, and it is why they cost no allocation. Nothing in the type says the bytes are borrowed, so it is checked: escape analysis rejects an implementation whose write lets its parameter outlive the call. ByteSink copies them into its Buf, which is what extend is.

That check is what licenses a renderer to pass a stack-backed slice through a trait object at all.

Type errors read as they should

The generic is monomorphized, so a mismatch names the instantiation rather than the parameter:

import sysl.buf.{Buf, buf}

var b: Buf[int] = buf()

b.push("x")

'v' of 'sysl.buf$Buf.push.int' is int, but string was given

sysl.buf$Buf.push.int is the push of a Buf[int] — one function, emitted for that instantiation. Generics has the rest of that story.

Next: sysl.io — reading, and the Lines cursor.

Attributes, annotations, and compile time

2026-08-16T01:26:07.924728867Z

Three kinds of form in sysl reach into the compilation rather than into the running program. Each has a name and a spelling of its own:

written	is	read by
`T::Attr`	an attribute — a question a type’s own name answers	the analyzer, at the use
`@test`, `@tailrec`, `@pure`, `@ghost`, `@export`, `@reads`, `@writes`, `@crossing`	an annotation — a fact about the free function under it	the grammar
`@packed`, `@align(n)`, `@section("...")`	an annotation — where the declaration under it is laid out, or where it lands	the grammar
`@export("...")` on a `struct`	an annotation — the name the type carries in a generated C header	the grammar
`@no_alloc`, `@requires`, `@link`, `@include`, `@tests`	an annotation — a fact about the whole file, in its header	the grammar
`@assert`	an annotation that describes nothing but itself — a condition settled while compiling	the analyzer, once
`#if`	a directive — a gate on lines	a pass before the lexer

The last two are told apart by the sigil, and that is the whole rule. An annotation is @ and belongs to what it is written above — a declaration, or the file itself; a directive is # and gates lines. Nothing about indentation is involved, which matters because a declaration at the margin — a module header — has its annotation at the margin too, so a rule about columns would have had the two forms competing for one position.

A directive is still written at column 1, and for its own reason: it is gone before anything counts a column, so an indented one would look like it takes part in a block structure it has nothing to do with. That is a rule about directives, not the thing that distinguishes them.

Annotations come in groups, by what they attach to — and the last of them is the empty one, which is as much a rule as the others.

On a function there are eight, each written on its own line above the declaration. More than one may be stacked, and writing the same one twice is refused. @test and @tailrec are below; @pure, @ghost, @reads and @writes belong to the specification vocabulary and are on the verification page; @export makes the definition C-callable and is on the FFI page, beside the extern it is the mirror image of; @crossing(...) says a parameter hands a value to another concurrency domain and is on the memory page, beside the crossing rule it asks.

On a type, or on storage there are four, and three of them are about where rather than about what the declaration does. @packed and @align(n) lay out a struct — no interior padding, and the boundary the aggregate begins on — and @align(n) marks one binding’s storage as well. @section("...") marks a binding or a function, and says which linker section it lands in. All three are below. The fourth is @export, which on a struct names the type in a generated C header rather than placing it, and is on the FFI page with the other half of itself.

On the file there are five, in its header directly below module and before everything else: @no_alloc and its siblings, @requires(...), @link("..."), @include("..."), and @tests. The first two say what the whole module may do; @link says what its externs need at the linker and @include what its c const and c type blocks need at the C compiler; the last says it is scaffolding for the module’s tests. All five attach to the file rather than to any declaration in it — and writing one further down is refused with a message saying where it belongs. The first four are covered under modules and FFI, where what they mean is; @tests is below.

On nothing at all there is one: @assert, which stands where a declaration stands and describes only itself. It attaches to nothing, declares no name, and nothing can refer to one — two saying the same thing are two checks rather than a duplicate. It is below.

On a member, none of them. “A function” above means a free function: a method, a property, an associated function, a field and a variant take no annotation at all, and the refusal says so rather than complaining about the indentation of the line:

struct Counter
    n: int

    @test
    is_zero(self) -> bool = self.n == 0

an annotation marks a function, and a member is not one

So what sysl test runs is a free function that calls the member, and @crossing(...) is written on the wrapper a caller already goes through rather than on the method behind it — which is where the call a program makes goes, and so where the complaint belongs. @packed and @align(n) are not the exception they look like: they mark the struct, written above struct and not above a field. @assert inside a type’s body is refused too, and gets its own sentence, because it is not a claim about the member under it — it goes beside the type, where sizeof and offsetof still name what it is about.

#test above a member is answered by the same sentence, with the sigil named at the end of it. A directive is gone before the lexer counts a column, so an indented # never reaches the directive pass at all and arrives at the member grammar instead — and being told only that an annotation is written @ would send a reader to write @test, which a member is refused just the same.

An annotation’s name is an ordinary identifier, which is the point of writing these as annotations at all: nothing here is reserved, so a program may still call something test, link, alloc, no or requires. guide/slab‘s allocator calls its central function alloc and threads its free list through a field called link.

The @ is also read inside a pattern, where it binds a name to what a sub-pattern matched (patterns). The two never compete: an annotation’s @ is a prefix at the start of a line above a declaration, and a pattern’s is infix between a name and a pattern, in a position no declaration may stand.

`::` — what a type’s own name answers

A type’s name is a type and not a value, so nothing is read from it. What it answers are attributes, written with :: rather than . so they stay out of the member namespace: Color::First cannot be confused with a variant, an associated function, or a member an impl added, and no impl can shadow one by declaring a member of that name.

Three kinds of type answer them, and each set is fixed and closed.

A simple enum

enum Color: u8
    Red = 2
    Green = 5
    Blue = 9

print(Color::Image(Color::First), Color::Image(Color::Last))
print(Color::Pos(Green), Color::Image(Color::Val(2)))
print(Color::Image(Color::Succ(Red)), Color::Image(Color::Pred(Blue)))
print(Color::Image(Color::Value("Blue")), int(Color::Value("Blue")))

Red Blue
1 Blue
Green Green
Blue 9

written	is	traps
`T::First` / `T::Last`	the first and last variant	no
`T::Pos(v)`	a value’s 0-based position in the declaration	no
`T::Val(i)`	the value at position `i`	on a position past the last, or below zero
`T::Succ(v)` / `T::Pred(v)`	the neighbouring value	at the last / at the first
`T::Image(v)`	the variant’s name, as a `string`	no
`T::Value(s)`	the value a name stands for	on a name no variant has

Position is not the discriminant, and that distinction is why Pos and Val exist. Discriminants may be explicit, non-contiguous and not zero-based — Green above is position 1 and discriminant 5 — so an ordinal has to be looked up rather than computed. Pos and Val are the two directions of that lookup, and Succ/Pred walk the declaration order rather than adding one. Going the other way, to a value’s discriminant, is the ordinary conversion int(c).

Image and Value are the printed-name pair, and they are what makes a simple enum observable. The type carries no == and no Display of its own, which is why every line above turns a value into a position or a name to look at it. A comparison is written on the discriminants, int(a) == int(b).

A constrained subtype

The other set — First, Last, Valid, Succ, Pred, Range — belongs to a within-ranged integer subtype, and is on the errors and contracts page beside the checking it is the question form of.

The two sets are spelled the same way for the same reason and overlap where the questions overlap, but they are not one set: an enum has Pos, Val, Image and Value because its values are named and unevenly spaced, and a subtype has Valid and Range because its values are a contiguous run of integers.

An integer type

The third set is two attributes wide — Min and Max, the extremes the type can hold. They belong to every member of the iN/uN family, and to the named types that are members of it.

print(u8::Min, u8::Max)
print(i8::Min, i8::Max)
print(int::Min, int::Max)
print(byte::Min, byte::Max)

0 255
-128 127
-2147483648 2147483647
0 255

The open family is why these exist rather than being written out. A program can spell 4294967295 for a u32 and lose nothing; the largest u10000 is 3,011 digits and cannot practically be written at all, so for a wide member the attribute is the only way to name a value the type obviously has. It is also why they cannot be a library table the way C’s UINT8_MAX is — there is no finite set of integer types to tabulate.

print(u3::Min, u3::Max)
print(i5::Min, i5::Max)
print(u64::Max)

0 7
-16 15
18446744073709551615

They are constants taking no argument, so they fold. That is what puts them where no call is admitted — a const initializer, an @assert condition, an array bound:

const LIMIT: u16 = u16::Max
const HALF: u32 = u32::Max / 2

print(LIMIT, HALF)

65535 2147483647

usize answers only a floor across targets. Its width is the pointer’s, so usize::Min is 0 everywhere and usize::Max is whatever the target makes it — a program that prints the latter is reading a fact about the machine rather than about the language.

Min/Max are not First/Last renamed, and asking for the wrong pair is answered by name rather than by a general refusal:

print(u8::First)

'u8' is an integer, not a declared sequence — its extremes are 'u8::Min' and 'u8::Max'. 'First' and 'Last' name the ends of an enum's variants or of a 'within' range, which is a different question

First and Last name the ends of a declared sequence — an enum’s variants, a written range — and an enum’s discriminants may be explicit and non-contiguous, so its first-declared variant need not carry the smallest value. The two questions coincide on an integer and only there. A within-ranged subtype answers both, since there they genuinely agree, and a reader who learned Min on u32 should not find it renamed on a subtype of u32.

And a subtype that narrows nothing has its base’s, because that is what it can hold. First and Last still need a range, which is the same distinction one paragraph up — a declared sequence against what the type can hold:

type Handle = new u16

print(u16(Handle::Max))

That is the case a c type is always in: a measured typedef carries no range, so asking a size_t for its maximum is asking about the integer C said it is. A where predicate is the exception and is refused — it narrows the type without saying to what, so there is no extreme to read off the declaration.

Only integers have them: f64::Max and bool::Max are refused, the float because its extremes are sysl.math‘s business and the boolean because it is not that kind of type.

A type parameter answers them too, from whatever the instantiation bound it to — which is what makes the bounds usable by a library rather than only by a program. Bounded narrowing, integer parsing, saturating arithmetic and a min/max reduction’s identity all want T‘s extreme, and none of them can name it any other way:

widest[T]() -> T = T::Max

val a: u8 = widest()
val b: u16 = widest()

print(a, b)
print(widest[i8]())

255 65535
127

One body serves every width it is instantiated at, and the argument may be written at the call or inferred from what the result is used as.

The parameter carries the type that was written, so a within-ranged subtype answers its own bound rather than its base’s:

type Age = int within 0..150

widest[T]() -> T = T::Max

val a: Age = widest()

print(int(a))

This is the one place a transparent subtype and its base give different answers, which is why generics states the rule: everywhere a value flows the two are interchangeable, and a bound is the one thing either can produce that the other cannot hold.

Min and Max are the only two a parameter answers. The rest stay on a written type name:

first[T]() -> T = T::First

val a: u8 = first()

print(a)

'T' is a type parameter, and the only attributes one answers are 'T::Min' and 'T::Max'

The reason is the walk that checks a generic body once, with T standing for itself rather than for any particular type. That walk has to hand back a typed value, and Min and Max both answer in T — so one stand-in is right for both. Valid answers a bool, Pos a usize and Image a string, so admitting those would mean restating each attribute’s result type a second time, in a second place, where the two copies could drift apart.

Nothing is asked of T in the signature. A parameter given a type with no extremes is reported at the instantiation that gave it one, and the message names both:

struct P
    x: int

widest[T]() -> T = T::Max

val a: P = widest()

print(1)

'T::Max' needs an integer type, and 'T' is P here

That is the same deferral sizeof(T) takes, and it is what keeps a bound from being something a generic has to declare in order to measure.

What has no attributes

A data enum, because its value is a variant plus a payload, so a position, a name and a neighbour are each questions about only half of it:

enum Shape
    Circle(r: int)
    Rect(w: int, h: int)

print(Shape::First)

'Shape::First' needs a simple enum, and 'Shape' carries data

A generic enum, because its name stands for no one value set until it is applied:

enum Box[T]
    Full(v: T)
    Empty

print(Box::First)

'Box' is generic, so 'Box::First' has no single enum to read

And an attribute outside the set is answered by name, since the set is closed:

enum Color: u8
    Red
    Green

print(Color::Nonesuch)

'Color' has no attribute 'Nonesuch'

`@test` — a function with a caller nothing else has

A word after @ that is neither test nor tailrec is answered by name rather than as grammar. The set is closed, which is what makes a misspelling an error instead of a marker that quietly does nothing — annotations are deliberately not a general mechanism yet.

The annotation goes on its own line above an ordinary function declaration, which may still be private:

add(a: int, b: int) -> int = a + b

@test
adds_two()
    assert(add(1, 1) == 2, "one and one")

@test("an empty slice has no first element")
private first_of_empty()
    assert(true, "nothing to see")

print(add(2, 3))

That program prints 5 and runs neither test, which is the whole of the arrangement: sysl run builds the program, and the tests are for sysl test.

Four forms of the annotation:

written	means
`@test`	an ordinary test, named after the function
`@test("a sentence")`	named by the sentence instead
`@test(should_trap)`	the test passes by stopping the program
`@test(should_trap: "past the end")`	…and the run must have printed that text

What a test may be

A test is an ordinary function with a caller nothing else has: no parameters, no result, not generic. All three are the same requirement from different sides, since the runner calls it with nothing and reads the answer off whether it returned. They are checked at the annotation, because the function is a perfectly good function and it is @test that made a promise about it:

@test
takes_one(n: int)
    assert(n > 0, "positive")

a '@test' function takes no parameters, and 'takes_one' takes one — 'sysl test' calls it with nothing, so there is nowhere for an argument to come from

@test
generic_one[T]()
    assert(true, "yes")

a '@test' function has no type parameters, and 'generic_one' declares 'T' — a generic is compiled for the arguments a caller fixes, and the runner supplies none

@test
gives_back() -> int = 1

a '@test' function returns nothing, and 'gives_back' returns 'int' — a test's result is whether it came back, so there is nothing to read a value with

A test passes by returning

That is the whole protocol, and it is what lets a test assert in the language it is testing rather than in a framework. A broken require, a bounds violation, an unwrap of a None — each ends the process, and none of them had to know it was running under a test.

should_trap inverts the reading, for a test whose subject is the check. With a string it additionally requires that the run printed it, which is what tells a trap from the right trap. A silent trap satisfies should_trap and can satisfy no string, because a compiler-inserted check raises a signal and says nothing — see what stopping looks like.

A test has one caller, and the program is not it

run_it()
    adds_two()

@test
adds_two()
    assert(true, "yes")

'adds_two' is a '@test' function, which 'sysl test' calls and nothing else does — every other build leaves it out, so this call would have no definition to reach. Work two tests share belongs in an ordinary function they both call

What is dropped, and when

sysl run, sysl build and sysl emit-llvm drop the tests — and drop them after analysis. So a @test that does not compile is an error in a build that would never have run it, and a module’s capability clause reaches its tests like any other member.

That ordering is what lets a test sit beside what it tests: a program’s tests do not run when it runs, and they do not stop being checked.

A helper only a test calls leaves with it, because it becomes unreachable and pruning notices; a helper the program also calls stays, because the program still calls it.

What a test build keeps regardless is the four definitions nothing in the program names: an interrupt handler, an @export, a @section definition (below), and a destructor. Each is entered from somewhere no walk over the program can see — the processor, a caller outside this compilation, a linker script gathering a named section, and the release hook generated from a payload type — so each is a root wherever the walk begins. A test build swaps the roots, putting the tests where the entry point was, and these four are roots there too. They have to be: leaving them out would not make them reachable from the tests instead, it would make them reachable from nothing.

That matters most to a package, whose only build is its own suite. A test build dropping a destructor could not link at all, the release hook being left to call a symbol nothing defined; one dropping an export would link, pass, and quietly go without the surface the package exists to provide.

sysl build-lib is the exception, and drops them before analysis. An artifact is the one output that outlives the compilation that made it, and analysis is not a passive reading: a test naming Buf[int] creates the whole of Buf at int, and that instantiation is an ordinary library function afterwards, with nothing in it recording which declaration asked for it. Dropping the test from the analyzed program would therefore drop the test and keep everything it caused — shipping instantiations no caller of the library ever asked for, and making the artifact’s contents a fact about its tests.

The line falls between parsing and analysis. Every source is parsed before the drop, so a syntax error in a @tests file still stops a build-lib. What such a file no longer gets is everything after the parse — name resolution, types, visibility, capabilities, the @test well-formedness rules above, generic instantiation, and the duplicate-@export check. So a library test that is well-formed text and wrong in every other way builds clean, and its real errors are reported by sysl test --std, which is where a library’s tests are run.

That last one is worth naming because it is the case where “everything after the parse” is easy to apply to only half of a build. An @export in a @tests file names a symbol this build is about to discard, so it can collide with nothing — and a check that read the tree before the drop would refuse a program over a name that was never going to be emitted.

Read the other way, sysl test is the build where such an export is a definition, and it is held to every rule on the FFI page accordingly — private, variadic, generic, a parameter C has no declaration for, two exports claiming one symbol, and an export reaching computed module storage. Each of those asks about the symbol table the build in hand emits, so which tree is read is the whole of the difference between the two commands.

`@tests` — a file of scaffolding

Pruning answers for a program. It does not answer for a library, which has no main to lower outwards from, so every public declaration is a potential entry and all of them are emitted. A helper only a test called would ride into the artifact and be advertised out of it, nameable by everything that links the library. Nothing about the declaration says it is scaffolding, and nothing could — it is an ordinary function, which is the point of it.

So the file says it, in its header, beside the capability clauses:

@tests

fixture() -> int = 6 * 7

@test("the fixture is the answer")
the_fixture_holds() =
    assert_eq(fixture(), 42)

It is @tests and not @test because the two say different things: @test names something the runner calls, and this names something no build but the runner’s keeps. One word for both would read as though the file were itself a test.

Two rules, and either alone would be unsound. Every build but sysl test drops everything such a file declares — and nothing outside a test may name any of it. Without the second, a program that called a helper would compile here and fail at the link, with a message about a missing symbol rather than about the line that named it.

The restriction is stated over the referring declaration, not over the file it sits in. So a @test function may name scaffolding wherever it was written — which is what keeps a test able to sit beside what it tests — and another @tests file may, and nothing else may:

@tests

fixture() -> int = 6 * 7

print(fixture())

error: 'fixture' is declared in a file that said '@tests', so it is there for the module's tests and no build but 'sysl test' keeps it — only another such file, or a '@test' function, may name it

A closure counts as the body it was written in. It is lowered to a function of its own under a name nobody wrote, so on its own terms it belongs to no file — but what decides is where it sits, not what it ends up called. A lambda inside a test may name the test file’s own scaffolding, and so may a bare function name, which is the same thing written shorter:

@tests

fixture() -> int = 6 * 7

apply(f: &Fn(int) -> int, n: int) -> int = f(n)

@test("the fixture is the answer, reached through a callback")
the_fixture_holds() =
    assert_eq(apply(v -> fixture() + v, 0), 42)

It goes when the file goes, too, which is the half that makes the naming safe: the program that ships carries no body for it.

An impl block may not sit in one. It declares no name; it fills a slot in a method table, which the rest of the program reads without naming anything. Kept in a test build and dropped everywhere else, it would mean a trait answering one way while the tests ran and another way in the program that ships. The impl belongs beside the type. A closure is the one exception the compiler makes for itself, and it is not a hole: the table it writes is dropped with the closure.

It stops at the package boundary. A package is compiled from source and a library arrives as an artifact whose test files were never encoded, so a rule that let the reference cross would compile against one and fail against the other. A test-support library meant to be imported is therefore ordinary code that ships, and is a different thing from a file of scaffolding inside a package.

The runner

sysl test <path>
sysl test <path> --filter <text>
sysl test <path> --fail-fast

One build, one process per test. The tree is compiled once, into a binary whose entry point takes a test’s name and runs that test alone — the program’s own statements and its main are not run, though its module-level vals are still filled, since a test reads a module’s storage like any other function. The runner then starts that binary once per test.

The process per test is not a cost being tolerated; it is the mechanism. A test that fails does so by ending its process, so a run that shared one would report the first failure and nothing after it. The compile is the slow half, and there is only ever one of it.

Exit status is 0 if and only if every test that ran passed. A tree with no tests, and a filter that matched none of the tests there are, both exit 0 and say which happened.

`assert` and `panic`

Both are ordinary functions in the standard module:

panic(msg: string) -> never
    print("panic:", msg)
    exit(1)

assert(cond: bool, msg: string)
    if !cond then panic(msg)

They exist because require is a promise about a call, checked on entry, and a test’s fifth statement has no contract to hang a claim on — the contract was about the arguments, four statements ago.

They stop the program the way unwrap does — a line naming what happened, then the hosted exit — rather than through the trap instruction, because a check a program makes is one the compiler cannot see, and the message is the whole point of it. The message is required rather than defaulted, because the condition’s source is not available to print and a failure saying only “assertion failed” sends its reader looking for which one.

`@assert` — a condition settled while compiling

const capacity: usize = 512

@assert(capacity == 512, "the protocol fixes this")

print(capacity)

The condition is a constant expression, folded by the machinery a const initializer already goes through — so it may name constants, sizeof, alignof, offsetof, and the arithmetic and comparisons over them, including a constant declared below it. A true one emits nothing at all. A false one stops the compilation, quoting the message:

@assert(1 == 2, "arithmetic broke")

print(1)

assertion failed: arithmetic broke

The message is optional and is the reader’s own, because they know what the number means — that a struct matches its C counterpart, that a table is the size a protocol fixes — where the expression alone says only that two numbers differ.

A failed comparison also says what each side came out as. The compiler folded both in order to decide the condition, so it has the numbers at the moment it reports that one of them is wrong, and withholding them would leave you editing the literal and rebuilding to find out. A side you wrote as a literal is not repeated back — it is on the line above the message — so sizeof(FRect) == 16 reports only the left; where both sides are computed, both are named. A condition that is not a comparison has nothing to add, since the thing that came out false is its only operand.

It is not require. A require is a runtime precondition: it is compiled, it branches, and it traps when the program reaches it. This is settled while compiling and reaches the binary as nothing. A condition it cannot settle is refused rather than deferred — and a call is the line, since a call in a constant expression would be a request for compile-time evaluation of arbitrary code:

f() -> int = 3

@assert(f() == 3)

print(1)

has to be a constant expression

Checking a C struct’s layout

This is what it was built for. sysl lays a struct out in declaration order and is C-compatible by construction, but from inside sysl that claim cannot be checked: sizeof reports what sysl laid out, not what the header says, so comparing the two is a tautology.

Where the C side is __attribute__((packed)) or was declared at a boundary, @packed and @align(n) further down this page are how the sysl side says the same thing — and the check below is what proves the two agree rather than merely look similar.

It stops being one when both sides name the same number. The C half goes in a .c beside the sysl, which is compiled with it and for the same target, so it reads the headers of the machine being built for:

#include <stddef.h>
_Static_assert(sizeof(struct pair) == 8, "struct pair size moved");
_Static_assert(offsetof(struct pair, b) == 4, "struct pair.b moved");

and the sysl half pins what sysl laid out:

struct Pair
    a: i32
    b: i32
end Pair

@assert(sizeof(Pair) == 8, "Pair must match struct pair")
@assert(offsetof(Pair, b) == 4, "struct pair.b moved")

print(sizeof(Pair), offsetof(Pair, b))

8 4

Neither half finds the other’s mistake, which is why both are written: the .c catches a header that moved, and the @assert catches a struct that was transcribed wrong.

Pin every field you read, not only the total. A size catches a field that changed width and one that was added. It says nothing about order — so two same-width fields transposed in the mirror leave the total unchanged, and the size assertion on both sides passes while every read is off by the distance between them:

struct Pair
    b: i32
    a: i32
end Pair

@assert(sizeof(Pair) == 8, "Pair must match struct pair")
@assert(offsetof(Pair, b) == 4, "struct pair.b moved")

print(1)

assertion failed: struct pair.b moved — the left side is 0

That is the failure the whole pairing exists to prevent, arriving through the half that was not checked. offsetof(T, field) closes it: it takes a type and a field name, and answers where the field starts in bytes. A field the struct does not have is refused by name rather than reported as a condition that would not fold.

Inside a generic, where it is settled once per instantiation

A generic’s interesting facts are not properties of its declaration — they are properties of each set of arguments it is compiled for. sizeof(T) has no width until something chooses a T, so an assertion about one is settled at every instantiation rather than once:

slab[T](x: T) -> usize
    @assert(sizeof(T) >= sizeof(*u8), "a free block has to hold the link through it")
    sizeof(T)

print(slab(1u64))

An argument the claim does not hold for stops the compilation, and the report names which one asked — the mistake is at the call that chose the type, while the sentence explaining why is at the declaration, so a message carrying only one of the two sends its reader to the wrong file:

slab[T](x: T) -> usize
    @assert(sizeof(T) >= sizeof(*u8), "a free block has to hold the link through it")
    sizeof(T)

print(slab(1u8))

assertion failed: a free block has to hold the link through it — the left side is 1 and the right side is 8 — where T = byte

This is the check require cannot make. A precondition over sizeof(T) written as a require is a runtime branch for a fact that was settled at the call: a container instantiated at a type too narrow compiles, ships, and traps the first time anybody uses it. guide/slab was written that way before this and is the worked example of the difference.

A value parameter is bound the same way and so is checked the same way, which is what lets a generic hold its caller to a bound on a length:

scratch[const N: usize](xs: [N]int) -> usize
    @assert(N <= 4, "the scratch buffer is a stack array")
    N

var small: [2]int = [1, 2]

print(scratch(small))

A generic nothing instantiates is not checked, and that is the same deferral an array bound already lives under: [sizeof(T)]u8 is a well-formed length nobody can name until a T is chosen, and the width is not wrong there — it is not being measured yet. The claim is settled at the first call, which is the first moment there is anything to settle. A condition that could never fold is still refused inside a generic, exactly as it is outside one.

`@tailrec` — an assertion that the frame is reused

A function whose last act is a call to itself compiles to a branch back to its own entry rather than a second frame, so the recursion is bounded by the arithmetic and not by the stack. That happens whether or not anything is written — see tail calls for what counts as the last act, and for the two things that end a tail position.

@tailrec asserts the jump is there:

@tailrec
count(n: int, acc: int) -> int =
    if n == 0 then acc else count(n - 1, acc + 1)

print(count(100000, 0))

What it buys is the refusal. The optimization is silent, so an edit that costs it is silent too — until the day the recursion is deep enough to matter:

@tailrec
count(n: int, acc: int) -> int =
    if n == 0 then acc else 1 + count(n - 1, acc)

print(count(5, 0))

calls itself nowhere the jump can replace

It changes nothing about what is emitted. Write it where losing the jump silently would be a bug, and leave it off everywhere else.

`@packed` and `@align(n)` — where a struct’s fields sit

By default a struct pads: each field begins on its own alignment, and the aggregate takes the widest of them. That is the layout a program wants unless something outside the program has an opinion.

struct Head
    tag: u8
    len: u32

print(sizeof(Head), alignof(Head))

8 4

Three bytes of that eight are a gap in front of len. Two attributes move a struct off the default, and they are separate axes — one removes the padding between fields, the other raises where the aggregate begins.

`@packed` — no interior padding

@packed
struct Head
    tag: u8
    len: u32

print(sizeof(Head), alignof(Head), sizeof([4]Head))

5 1 20

The fields are laid end to end, the aggregate needs no alignment of its own, and an array of them has no gap between elements either. A register block, and a C struct that has to match one, are what it is for.

The fields still read and write their own values — packing changes where they sit, not what they are:

@packed
struct Head
    tag: u8
    len: u32

var h = Head(7, 1000)

h.len += 1

print(h.tag, h.len)

7 1001

A packed field has no address. &s.f is refused, and so is any *T into one:

@packed
struct Head
    tag: u8
    len: u32

var h = Head(1, 2)
val p = &h.len

print(1)

'&' here makes a '*uint' into Head, which is '@packed' — its fields sit at their declared offsets, so this one need not be on a 'uint' boundary, and every use of a '*uint' is entitled to assume that it is. Read or write the field through the struct, which is where the offset is known, or take the address of the Head itself

The field sits at its declared offset, which is very often not a multiple of its own alignment — that is the point of the attribute — while a *u32 is a *u32 wherever it came from, and every use of one is entitled to assume the address is aligned. Only the escaped address loses that, and it would lose it arbitrarily far from the & that made it. The struct’s own address is untouched, being an ordinary pointer to an ordinary aggregate.

Bitfields — an `iN` field in exactly N bits

Inside @packed, an integer field occupies exactly its declared width. A packed struct whose fields all lower to an integer, at least one of them narrower than a byte, is one unsigned integer — and its fields are ranges of it:

@packed
struct Ctrl
    enable: u1
    mode: u3
    prescale: u4

val c = Ctrl(1, 5, 9)

print(sizeof(Ctrl), c.enable, c.mode, c.prescale)

1 1 5 9

No syntax was needed for this, which is why there is none: the open integer family already does the work C needs int x : 3 for, so a five-bit field is written u5 in a struct exactly as it is anywhere else.

Two things follow that C leaves to the implementation, and pinning them is the point of the feature rather than a detail of it — it is why portable embedded C avoids bitfields and writes the shifts out by hand. The bits fill from the least significant upward in declaration order, and a field straddles a byte boundary rather than moving off it. Both are visible in the storage:

@packed
struct Ctrl
    enable: u1
    mode: u3
    prescale: u4

var arena: [4]u8 = [0; 4]
var c: *Ctrl = ptr_cast(&arena[0])

c.enable = 1
c.mode = 5
c.prescale = 9

print(arena[0])

155 is 1 | 5 << 1 | 9 << 4: the first field declared is the low bits.

The rule is stated over the integer’s value and never over memory bytes. Written the other way — “the low bits of byte 0” — it would be a claim about endianness, which nothing in sysl is allowed to make. Written this way it costs nothing: the struct is an integer, so how it reaches memory is the target’s ordinary byte order for an integer of that width. A wire format’s byte order belongs to the protocol rather than to the CPU, and stays with sysl.encoding.binary‘s get_u16_le and the rest.

Every field has to be an integer. A bool is not one here — its storage is a byte and its representation a bit — and neither is a pointer, a float or an array:

@packed
struct Mixed
    p: *u8
    a: u3

val m = Mixed(null, 1)

print(m.a)

is one integer, and every field of it has to be one too

Nesting is the composition path, and it costs nothing: a bitfield struct is a leaf, and an ordinary @packed struct lays one out as a field of its size.

@packed
struct Ctrl
    enable: u1
    mode: u3
    prescale: u4

@packed
struct Block
    ctrl: Ctrl
    count: u32

var b = Block(Ctrl(1, 5, 9), 3)

b.ctrl.mode = 2

print(sizeof(Block), b.ctrl.enable, b.ctrl.mode, b.count)

5 1 2 3

A bitfield may be volatile, and it means a volatile access of the container. Reading a field is one volatile load of the whole container; writing one is a volatile load and a volatile store of it — what C does with volatile unsigned x : 3, and what lets a @packed struct describe a hardware register rather than only a data layout:

@packed
struct Reg
    enable: volatile u1
    mode: volatile u3
    prescale: volatile u4

var block: [4]u8 = [0u8; 4]
var r: *Reg = ptr_cast(&block[0])

r.enable = 1
r.prescale = 9
r.mode = 5

print(block[0], r.enable, r.mode, r.prescale)

155 1 5 9

The qualifier belongs to the container rather than to one range of it, so writing it on any field qualifies every access to the struct. Every field of a bitfield struct is bits of one word, so there is no shadow field here to stay ordinary — which is the thing per-field qualification buys in an ordinary register block. The struct itself still may not carry the qualifier, and does not need to:

@packed
struct Ctrl
    a: u3
    b: u5

var p: *volatile Ctrl = ptr_cast(4096usize)

print(p.a)

'volatile Ctrl' is not a type

A write is a read-modify-write, and nothing diagnoses what that costs. A device is entitled to one bus cycle, so writing a field of a register with clear-on-read or write-1-to-clear semantics corrupts the ranges beside it — the read that begins the sequence has already had its effect. Nothing in the language describes a register’s read semantics, so this is stated rather than refused, exactly as it is in C. A register of that kind keeps its volatile u32 and its shifts, where the single access is written out.

A field that is a set of named values is a simple enum, which is one integer and may be volatile like any other. A data enum may not — a tag beside a payload is more than the one access the qualifier promises.

A bitfield has no byte offset, so offsetof says so rather than rounding down to the byte the field begins in:

@packed
struct Ctrl
    enable: u1
    mode: u3
    prescale: u4

print(offsetof(Ctrl, mode))

is a bitfield — it starts at bit 1 of the struct and is 3 bits wide, so it has no byte offset

It has no address either, which is the packed rule above and needs no separate ruling.

Across a C boundary it travels as what it is — a packed struct of one integer — and not as a C bitfield struct. Those are different things on some machines, and it is C’s own doing: MSVC allocates unsigned a:1 into a four-byte unit where the Itanium ABI packs it into a byte, so a C bitfield struct of the same fields need not even be the same size everywhere. A sysl bitfield struct is one integer on every target.

`@align(n)` — where the aggregate begins

@align(64)
struct Head
    tag: u8
    len: u32

print(sizeof(Head), alignof(Head))

64 64

The size rounds up as well as the start, so an array keeps every element on the boundary. It may only raise: asking for less than the fields already need changes nothing, since lowering is what @packed is for and a type that under-promised would be unsound to pass around.

The bound is folded rather than lexed, so a program writes the name it already has for the number, and arithmetic over one works:

const CACHE_LINE: int = 64

@align(CACHE_LINE)
struct Head
    tag: u8
    len: u32

print(alignof(Head))

It must be a power of two — an address is aligned by having low bits clear, so a boundary of six is unsatisfiable rather than merely weak:

@align(6)
struct S
    a: int

'@align(6)' on 'S' is not an alignment — a boundary is a power of two, since an address is aligned by having low bits clear

They compose

The gaps between fields and the boundary the whole thing starts on are different questions, so a wire header that has to live in a DMA-capable buffer is both at once. The order they are written in does not matter.

@packed
@align(16)
struct Head
    tag: u8
    len: u32

print(sizeof(Head), alignof(Head))

16 16

Sub-byte fields are a separate axis and @align(n) does not touch them. Inside @packed an iN field occupies exactly N bits (bitfields above); the boundary the aggregate begins on is this attribute, and a bitfield struct takes one like any other.

`@align(n)` on a binding

The boundary may also be written on the storage itself — a var or a val, at the top of a module or inside a function, and on the static spelling of either.

@align(64)
var region: [128]u8

region[0] = 7u8
print(region[0], region.len)

7 128

It says nothing the struct form could not. A boundary put on a type travels with every value of it, and a named aligned type is reusable where a repeated attribute is not — so reach for the type when more than one thing needs the boundary. What this spelling saves is at the use site: a buffer wrapped in a struct is read as region.bytes[i] rather than region[i].

@packed has no meaning here, and says so, because it describes the arrangement of fields inside an aggregate and a binding has none:

@packed
var n: int = 1

print(n)

'@packed' describes how a struct's fields are laid out, so it can only mark a struct — a 'var' or a 'val' has no fields to pack, and '@align(n)' is the one of the two that may stand above one

A binding that names several things is refused for a related reason: there is no one object for a boundary to be about.

@align(16)
var a, b = 1, 2

print(a, b)

'@align(n)' is the boundary one object's storage begins on, and a binding that names several has no one object for it to be about — declare them on lines of their own

The bound is held to the same rule a struct’s is — a power of two, folded rather than lexed, so a const or arithmetic over one is what a program writes.

`@section("...")` — where a symbol lands

@align(n) says what boundary storage begins on. @section says where the storage is, and it is what a program reaches for when the address of a thing is part of what it is: a vector table at the address the processor fetches from, storage in .noinit that survives a warm reset, a DMA buffer in the RAM bank the engine can reach, a function copied into RAM so it can run while flash is being erased.

It marks whatever occupies an address — a module var, a module val, and a function.

@section(".noinit")
var crash_reason: u32

@section(".ramfunc")
erase_page(n: usize) -> bool = n < 64

Nothing on this page runs one of these. A section name belongs to the target’s object format — .noinit is ELF’s spelling, __DATA,__mine is Mach-O’s — so a program that places something is a program about one machine, and the machine this page’s examples run on is not the interesting one.

That is also why the compiler does not check what is in the string. A set of characters chosen by sysl would refuse a section some target requires, and the assembler that will not take one says so better than a rule here could. It is extern‘s link name and @export‘s symbol read a third time: a spelling belongs to whoever consumes it.

It composes with `@align(n)`

The two are different axes — one is the boundary an object begins on, the other is where it lives — and a statically placed stack is written with both. The order does not matter.

@align(4096)
@section(".noinit")
var page_table: [512]u64

A placed symbol is kept

Nothing inside the program reads a table that a linker script gathers — that is the whole point of writing one — so a placed definition is a root, exactly as an interrupt handler and an @exported function are, and a placed symbol is marked so that the optimizer does not delete an object with no reader.

Without that second half the attribute would compile, link, and place nothing. The failure would be the absence of a section, which is not a thing anybody looks for.

A placed definition a dependency supplied is kept only where your program reaches its module, which is the rule the FFI page states for every kind of root at once. It bites hardest here, because being marked is exactly what stops anything downstream undoing it: a placed definition kept for want of the rule is bytes in your image that no optimizer will remove, in the region the attribute exists to manage. A package whose placed definition you want is one you name — an import is enough.

What it may not mark

A const is folded into every use and has no storage; a type is not an object. Neither takes a section:

@section(".rodata")
const N: int = 4

print(N)

'@section("...")' places one object in a linker section, so it marks a 'var', a 'val' or a function

A local is refused for a different reason, and the message says which — its storage is the frame of whichever call is running, while a section is a region of the image, decided once at the link:

f() -> int
    @section(".noinit")
    var n: int = 1
    n

print(f())

'n' is a local, so it cannot be placed in section ".noinit"

A binding that names several things has no one object for a section to be about, which is the rule @align(n) above already follows:

@section(".data")
static var a, b = 1, 2

print(a, b)

'@section("...")' places one object, and a binding that names several has no one object for it to be about

`#if` — gating lines before the lexer

Everything a target decides is a fact the compiler reads about the machine. #if is the one place a program reads one, and it exists because machines genuinely differ in ways a library cannot paper over: a syscall number, a struct a header lays out two ways, a symbol one libc exports and the other does not.

#if posix
line_ending() -> string = "\n"
#else
line_ending() -> string = "\r\n"
#endif

print("a posix machine", line_ending().len)

a posix machine 1

What differs between the branches is the implementation, not the answer. That is the shape most uses of #if have: a syscall number, a struct a header lays out two ways, a symbol one libc exports and the other does not — chosen per machine so that everything above the choice can stop caring.

#elif chains, and #else catches what nothing named:

#if aarch64
machine() -> string = "aarch64"
#elif x86_64
machine() -> string = "x86_64"
#elif riscv64
machine() -> string = "riscv64"
#else
machine() -> string = "something else"
#endif

That one is quoted rather than run, because what it prints is supposed to depend on the machine — which is the whole point of the construct and exactly what a page cannot pin to one answer.

#if / #elif / #else / #endif, nesting freely, and the branches are exclusive — the first whose condition holds is the one that contributes, and a group inside a branch that was not taken contributes nothing however its own condition reads.

It gates lines, and it gates them before anything is parsed

A line in a branch this build is not for is replaced by an empty line, not removed, and so is every directive line. After the pass the file is an ordinary sysl file that happens to have some blank lines in it, and nothing downstream knows any of this happened.

Replaced rather than removed, because every line below a gate has to keep the number it was written at. Deleting them would leave the messages right and the carets somewhere else, with nothing to say so:

#if linux
say() -> string = "one"
extra() -> int = 1
another() -> int = 2
#endif

print(missing_name)

:7:7

The caret is on line 7, which is where print(missing_name) is written — not line 2, where it would be if the four gated lines had been dropped.

A directive sits at the margin, column 1. That is a rule and not a convention. sysl is indentation-sensitive, and indentation is how the language reads block structure — so a gate written in that channel would look like it takes part in a nesting it has nothing to do with, when in fact the line is gone before anything counts a column. At the margin it is visibly not part of the code’s shape, which is what it is. It is also how C is written. What keeps a declaration’s @test from ever being mistaken for one of these is the sigil, not the margin — an annotation on a module header sits at column 1 too.

Why lines and not a construct wrapping declarations. Rust spells this #[cfg], an attribute on an item, and can because Rust is brace-delimited: the attribute attaches without moving anything. Here the equivalent would have to take an indented block, so adding or removing a platform gate would reindent everything inside it — a one-line intent showing up as a whole-body diff. A flat marker disturbs nothing.

The symbols are derived from the target, and the set is closed

kind	symbols
operating system	`macos`, `linux`, `windows`, `freestanding`
processor	`aarch64`, `x86_64`, `riscv64`, `riscv32`, `thumb`, `x86`, `wasm32`, `craft`
derived	`hosted` (not `freestanding`), `posix` (`macos` or `linux`)

That is the whole vocabulary. There is no #define, nothing a project can add, and no dependence on a project config. A condition is a symbol, !, &&, ||, and parentheses; && binds tighter than ||.

posix is a name for the commonest disjunction rather than a replacement for writing it — #if linux || macos still says the same thing. Note that this posix is not the capability of the same name: this one asks is this a POSIX system, a fact about the machine settled by the target, where the capability asks may this module use POSIX, a permission a project grants and a no posix clause takes away. They agree today only because nothing denies anything yet.

A symbol nobody knows is an error, not false:

#if darwin
say() -> string = "one"
#else
say() -> string = "two"
#endif

print(say())

'darwin' is not something a target says about itself — sysl knows aarch64, craft, freestanding, hosted, linux, macos, posix, riscv32, riscv64, thumb, wasm32, windows, x86, x86_64

The set is closed, so a name outside it is a mistake rather than a fact this build happens not to have — and a misspelling that read as false would gate code out of the build with nothing said. Silently missing code is the one failure this feature cannot be allowed to have, and it is the one C has.

A target’s name is not a symbol — it has a - in it, which no identifier carries — and writing one is told what to write instead, because otherwise the reader is told that - is not an operator, which is true and no help:

#if aarch64-macos
say() -> string = "one"
#else
say() -> string = "two"
#endif

print(say())

'aarch64-macos' is a target's name rather than something a condition asks about — a condition asks about one fact of the machine at a time, so this is written 'aarch64 && macos'

Every condition is checked, in the branch being taken and the ones being skipped alike. So a misspelling in the Linux half is caught by a macOS build, which is where it would otherwise sit until somebody built for Linux:

#if linux
say() -> string = "one"
#elif nosuchmachine
say() -> string = "two"
#else
say() -> string = "three"
#endif

print(say())

'nosuchmachine' is not something a target says about itself

That refusal comes from a build whose #if linux was already false and whose #else is the branch being taken. The condition on the way past was still read.

What is given up, and what is not

The inactive branch is never syntax-checked. That is the price of gating text rather than trees, it is C’s price too, and a Linux branch can therefore rot while the macOS build stays green. What finds that is a build for each target — a thing to run, not a thing to design around. The conditions themselves are the part that is checked everywhere, and they are the part where a mistake would otherwise be silent.

The gate runs before anything knows what a string or a comment is, so a line that begins at the margin with a directive word is a directive even inside a text block or a block comment. Recognizing those would mean a second copy of the lexer’s rules about literals, in a place where the two could drift with nothing to notice — a worse defect than this one. The margin rule is what keeps it rare: a text block written anywhere but the top level is indented in the source, whatever its value turns out to be.

The library is subject to it too

library/sysl is sysl source, so it may gate on the machine like any other — which makes “the standard module” a question with a target in it, and the library’s source is parsed once per target accordingly.

The one thing held fixed is that a name the compiler spells for itself is declared on every target. A library that gated Option away for Windows would be a library nothing compiles against there, so that is refused in a registry-wide check rather than at the first ? somebody writes.

And an artifact records the target it was built for and is refused by a build for another, because the trees a library ships are now a per-target answer.

What is deliberately absent

absent	why
a general annotation mechanism	the set is closed: `@test`, `@tailrec`, `@pure`, `@ghost`, `@export`, `@reads(...)`, `@writes(...)` and `@crossing(...)` on a free function, `@packed`, `@align(n)` and `@export("...")` on a struct, `@section("...")` on a binding or a function, `@no_<capability>`, `@requires`, `@link`, `@include` and `@tests` on a file, and `@assert` on nothing at all. Each was designed and added on its own evidence; there is no way to write one the compiler does not already know
bitfield syntax	there is nothing to write: inside `@packed` an `iN` field already occupies exactly N bits, so a five-bit register field is `u5` and needs no `: 5` beside it. The open integer family does the work C’s declarator syntax was invented for
`#define`, or any project-supplied symbol	the `#if` vocabulary is derived from the target and closed, which is what makes an unknown symbol an error rather than a false
a `#if` that asks about a capability	a condition asks what the target says; what a project permits is a different question, left with the config that would define it
a test framework in the library	a test asserts in the language it is testing, and passes by returning
a release mode that drops a check	see errors and contracts — every check is in every build

That is the language. What ships beside it is the standard library, which is a section of its own — nothing in it is a language feature, and every type in it is one a program could have written.

sysl

Verification

for all and for some

invariant and variant on a loop

variant on a function

@pure

@reads and @writes — what a call may touch

@ghost — what costs nothing to say

sysl prove

Integer overflow is a proof obligation

Terms and programs

What is translated

Installing Why3

Vectors

Writing one down

What the operators do

Masks, and the lane-wise if

Reductions

Reaching memory

Where the width comes from

What the run promises

One kernel, every width

A kernel over an array

What a vector does not have yet

Lanes

Values and bindings

Naming a value

The scalar types

Every width is its own type

The family is open, and that is not a figure of speech

Characters are not small integers

Assignment is an expression

Types

Integers are an open family

Arithmetic wraps

Storage is not N / 8

Where the width stops

The narrowest widths

Floating point is a closed set

usize and isize

bool

char

unit and never

string

Fixed arrays and slices

Vectors

Structs

Enums

A variant belongs to its enum

Type aliases

Function types

A parameter passed by name

Traits and generics

A trait, and an implementation

Any type may carry an impl

Generics, and what an unbounded parameter may do

A bound is a trait

Operators are trait methods

Monomorphization

Trait objects

Object safety

A trait may require another

A trait may take type arguments

Implementing Display

Traits

Declaring a trait

A default may assume exactly what its own trait declares

Replacing a default says override

Conformance is explicit, always

The two dispatch strategies

Any type may carry an impl

Where an impl may live

An impl covers a generic type as a whole

Conditional conformance

A shape is covered the same way

override — when the overlap is deliberate

A trait may take type parameters

One implementation per argument list

A trait may require another trait

The table carries the required trait’s slots

`for all` and `for some`

`invariant` and `variant` on a loop

`variant` on a function

`@pure`

`@reads` and `@writes` — what a call may touch

`@ghost` — what costs nothing to say

`sysl prove`

Masks, and the lane-wise `if`

Storage is not `N / 8`

`usize` and `isize`

`bool`

`char`

`unit` and `never`

`string`

Any type may carry an `impl`

Implementing `Display`

Replacing a default says `override`

Any type may carry an `impl`

Where an `impl` may live

An `impl` covers a generic type as a whole

`override` — when the overlap is deliberate

Reading a clock — `sysl.posix.time`

`spawn` takes an address, not a callable

A body with nothing to read is passed `null`

`join` does not carry the result back

`Mutex[T]`

`lock` answers an address, and releasing is written

It is not built on `pthread_mutex_t`

`yield_now` and `current`

There is no `async`

When a refusal is the wrong answer: `from_utf8_lossy`

Classification: `Ascii`

Searching and trimming: `Search`

Gathering text: `StrBuilder`

A parse in a `Result` is not the value

How wide is it on screen: `columns`

Emphasis, and why `reset` is not enough

Whether to write escapes at all — `sysl.posix.tty`

Taking the terminal over — `sysl.posix.tty.raw`

Reading a line — `sysl.term.edit`