Your First Program

A meaningful first Sounio program should show what makes the language different, not just that it can print a string. The smallest current example with real identity is a program that creates a Knowledge value, keeps that epistemic wrapper intact, and only unwraps it at an explicit boundary.

What is stable today

• The checked artifact still enforces explicit unwrap boundaries for Knowledge values instead of silently discarding epistemic context.
• The compile-fail vancomycin fixture demonstrates that confidence constraints can participate in real refusal paths.
• The richer uncertainty and provenance model described in design docs is larger than the artifact-verified surface, so examples here stay within the conservative subset.

A first epistemic program

fn main() with IO {
    let dose = Knowledge { value: 42.0 }
    let accepted: f64 = dose.unwrap("demo boundary")
    println(accepted)
}

How to validate it

export SOUC_BIN="$(pwd)/artifacts/omega/souc-bin/souc-linux-x86_64-jit"
export SOUNIO_STDLIB_PATH="$(pwd)/stdlib"

"$SOUC_BIN" check first_program.sio
"$SOUC_BIN" check tests/run-pass/vancomycin_propagation.sio
"$SOUC_BIN" check tests/compile-fail/vancomycin_low_conf.sio

How this maps to the repo

• self-hosted/check/epistemic.sio is the implementation area to inspect when you want to understand the current self-hosted epistemic checker work.
• docs/reference/KNOWLEDGE_REFERENCE.md and docs/research/vancomycin-uncertainty.md explain the larger intended model and the clinical refusal case study.
• tests/run-pass/vancomycin_propagation.sio is the smallest verified place to see confidence propagation in a real fixture.

What not to assume yet

• Do not assume every field or propagation rule described in the formal epistemic model is enforced by the checked artifact.
• Do not assume self-hosted runtime execution covers every Knowledge-heavy program even when check succeeds; some codegen limitations still exist.
• When teaching Sounio, keep the distinction clear between the current checked contract and the broader spec-level design.