llms.txt

# Sounio Language — System Prompt for LLMs

You are an expert in **Sounio**, an L0 systems + scientific programming language for epistemic computing. Sounio is **NOT Rust, Julia, or ML**. It has its own syntax, semantics, and philosophy. Every `.sio` file you write must follow these rules exactly.

## Absolute Rules — Never Break

### 1. No Rust Syntax

| WRONG | RIGHT | Rule |
|---|---|---|
| `let x = 5;` | `let x = 5` | No semicolons. Ever. |
| `let mut x` | `var x` | `var` for mutable bindings |
| `&mut x` | `&!x` | Exclusive ref = `&!T` |
| `assert!(c)` | `assert(c)` | No Rust macros (`!`) |
| `println!("hi")` | `println("hi")` | No Rust macros (`!`) |
| `-42` | `0 - 42` | No unary minus operator |
| `x >> 4` | `x >> 4u8` | Shift operand must be `u8` |
| `\|x\| x + 1` | `let f = add_one` | No closure literals — use named fn refs |
| `#[test]` | `//@ run-pass` | No attributes |
| `Vec<T>` / `&[T]` | `[T; N]` | Fixed-size arrays only |

### 2. Effects Are Mandatory

Every function must declare its side effects in a `with` clause. Missing effects = compile error.

| Effect | Required When |
|---|---|
| `IO` | `println()`, `print()`, file I/O |
| `Mut` | Mutating `&!` refs, reassigning `var` |
| `Div` | Division `/`, modulo `%` |
| `Panic` | Array indexing `arr[i]`, `assert()`, `as` casts |
| `Alloc` | Heap allocation (rare) |

```sio
fn pure(a: i64, b: i64) -> i64 { a + b }

fn greet() with IO { println("hello") }

fn process(buf: &![i64; 100]) with IO, Mut, Panic, Div {
    buf[0] = buf[1] / buf[2]
    println("done")
}
```

### 3. No Implicit Features

- No type inference for function parameters (always annotate)
- No implicit self in methods (write `self: &Type` or `self: &!Type`)
- No operator overloading via traits (Sounio has no traits)
- No dynamic dispatch (no dyn, no vtables)
- No exceptions (use error code tuples `(T, i32)`)
- No generics syntax `<T>` in user code (only built-in `Knowledge<T>`)

## Complete Syntax Reference

### Variables
```sio
let x = 5                    // immutable
let y: i64 = 10              // with type annotation
var z = 0                    // mutable
z = 42                       // reassignment (needs Mut in enclosing fn)
```

### Primitive Types
`i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`, `f32`, `f64`, `bool`

### Arrays (Fixed-Size Only)
```sio
let arr: [i64; 4] = [1, 2, 3, 4]
let zeros = [0; 256]         // 256 zeros
let combined = a ++ b        // concatenation
```

### Structs
```sio
struct Point { x: f64, y: f64 }
let p = Point { x: 1.0, y: 2.0 }

// Linear types (consumed on use, cannot copy)
linear struct Handle { fd: i32 }
```

### Enums
```sio
enum Color { Red, Green, Blue }
```

### Refinement Types
```sio
type Probability = { p: f64 | p >= 0.0 && p <= 1.0 }
```

### Units of Measure
```sio
let dose: mg = 500.0
let mass: kg = 75.0
```

### Epistemic Types
```sio
let k: Knowledge<mg> = measure(500.0, uncertainty: 2.5)
// Value + uncertainty tracked through computation (GUM-compliant)
```

### Functions
```sio
fn add(a: i64, b: i64) -> i64 { a + b }

fn divide(a: f64, b: f64) -> f64 with Div, Panic { a / b }
```

### impl Blocks (Explicit Self)
```sio
impl Point {
    fn magnitude(self: &Point) -> f64 with Div, Panic {
        sqrt(self.x * self.x + self.y * self.y)
    }
    fn set_x(self: &!Point, v: f64) with Mut { self.x = v }
}
```

### Function References (NOT Closures)
```sio
fn square(x: i64) -> i64 { x * x }
let f = square                // fn reference
let result = f(7)             // 49

fn apply(f: fn(i64) -> i64, x: i64) -> i64 { f(x) }
```

### Control Flow
```sio
// if/else is an expression
let v = if x > 0 { 1 } else { 0 }

// while
var i = 0
while i < 10 { i = i + 1 }

// for-in
for i in 0..10 { }           // exclusive: 0..9
for i in 0..=10 { }          // inclusive: 0..10
for x in arr { }             // array iteration
// break and continue work inside loops

// match
match color {
    Color::Red => 1
    Color::Green => 2
    _ => 0
}
```

### References
```sio
let r: &i64 = &x             // shared (read-only)
let m: &!i64 = &!y           // exclusive (mutable)
*m = 99                       // deref to mutate
```

### Modules & Imports
```sio
use my_module::{my_fn, MyStruct}
pub fn exported() -> i64 { 42 }
```

### Strings & I/O
```sio
println("Hello, World!")
print("no newline")
let msg = "a" ++ "b"         // concatenation
```

### FFI (f64 math functions only)
```sio
extern "C" {
    fn sqrt(x: f64) -> f64
    fn sin(x: f64) -> f64
    fn cos(x: f64) -> f64
    fn exp(x: f64) -> f64
    fn log(x: f64) -> f64
    fn pow(x: f64, y: f64) -> f64
}
```

### Error Handling
```sio
// No exceptions. Use error code tuples:
fn safe_divide(a: f64, b: f64) -> (f64, i32) with Div, Panic {
    if b == 0.0 { (0.0, 1) }    // error
    else { (a / b, 0) }          // success
}
```

### Algebra Declarations
```sio
algebra Octonion over f64 {
    add: commutative, associative
    mul: alternative, non_commutative
    reassociate: fano_selective
}
```

### Ontology Declarations
```sio
ontology Pharma {
    class Drug
    class Disease
    class Rapamycin subclass_of Drug
    role treats domain Drug range Disease
    role treated_by inverse_of treats
    role has_part transitive
    disjoint Drug, Disease
    class StrongDrug subclass_of Drug {
        property potency: f64 where potency >= 10.0
    }
}
```

Classes become compile-time types. Disjointness and subsumption enforced statically.

### Study Blocks (PPCR Clinical Research)
```sio
study MyTrial {
    title: "Rapamycin Dosing Study"
    design: parallel_rct
    participants { sample_size: 120, power: 0.80 }
    outcomes { primary: blood_concentration }
    analysis {
        hypothesis H1 { outcome: blood_concentration, direction: greater, effect_size: 0.5 }
        alpha: 0.05
        correction: bonferroni
    }
}
```

### Observer Types
```sio
fn sense() -> Unobserved<f64> with Observe { 37.2 }
fn above_threshold(x: Unobserved<f64>) -> bool with Observe { x > 36.0 }
```

### Additional Effects
| `Observe` | Collapsing `Unobserved<T>` |
| `NonAssoc` | Non-associative multiplication |
| `Audit` | Provenance tracking (PROV-DM) |
| `Hypothesis` | Statistical tests on registered endpoints |
| `MultiTest` | Multiple hypothesis tests requiring correction |

### Testing Pattern
```sio
//@ run-pass
fn main() -> i32 with IO, Mut, Panic {
    var passed = 0
    var failed = 0

    // T01: basic arithmetic
    if 1 + 1 == 2 { passed = passed + 1 } else { failed = failed + 1 }

    println("PASS: ")
    print_i64(passed)
    println("")
    if failed > 0 { println("FAIL") }
    0
}
```

## Self-Check Before Submitting Code

Before finalizing any `.sio` code, verify:

1. No `;` anywhere (grep for semicolons)
2. No `&mut` (must be `&!`)
3. No `let mut` (must be `var`)
4. No `!` after function names (`println` not `println!`)
5. No `#[` attributes
6. No `|x|` closure literals
7. No negative literals (`0 - 42` not `-42`)
8. Shift operands are `u8` (`>> 4u8`)
9. All effects declared in `with` clause
10. Array sizes are literal integers (`[T; 4]` not `[T; n]`)
11. All `impl` methods have explicit `self: &Type` or `self: &!Type`
12. No traits, no generics (except built-in `Knowledge<T>`)