{ "markdown": "\n\n

\n \"Sounio\"\n

\n\n

SOUNIO

\n

A self-hosted systems + scientific programming language for epistemic computing, uncertainty propagation, and algebraic effects

\n\n

\n \"Sounio\n \"Playground\"/\n \"Version\n \"Apache-2.0\n \"~6.1k\n

\n\n

\n Website ·\n Playground ·\n Documentation ·\n Manifesto ·\n Examples ·\n Status ·\n Contributing\n

\n\n---\n\n**Sounio** is a systems programming language for epistemic computing — its type system tracks not just what your data *is*, but how much you should *trust* it. Uncertainty propagation, provenance tracking, and confidence-gated execution are built into the type system, not bolted on as libraries.\n\n**Keywords:** systems programming language, scientific computing language, epistemic types, uncertainty propagation, algebraic effects, self-hosted compiler, formal verification, non-associative algebra, octonions, e-graphs.\n\n### Technical Pillars & Core Keywords\n\n| Pillar | Description | Key Search Terms |\n| :--- | :--- | :--- |\n| **Epistemic Computing** | Built-in confidence-gated execution tracking and provenance tracking. | `epistemic-computing`, `Knowledge[T]`, `confidence-threshold` |\n| **Uncertainty Propagation** | GUM-compliant (Guide to the Expression of Uncertainty in Measurement) error propagation. | `uncertainty-propagation`, `GUM-compliance`, `error-propagation` |\n| **Systems & Science** | Native x86_64 ELF compilation, self-hosted compiler loop, PTX/GPU acceleration. | `systems-programming`, `scientific-computing`, `ptx-codegen` |\n| **Algebraic Effects** | Explicit side-effects declarations (`IO`, `Mut`, `Div`, `Panic`, `Alloc`). | `algebraic-effects`, `effect-system`, `effects-with` |\n| **Mathematical Rigor** | Non-associative octonion basis associators, formalized Lean 4 proofs of invariants. | `non-associative-algebra`, `octonions`, `lean4-proofs` |\n| **Dimensional Analysis** | Compile-time unit checking (`VAR_UNIT_DIM`) to prevent physical dimension errors. | `dimensional-analysis`, `unit-types`, `compile-time-units` |\n\nThe compiler is **self-hosted**: Sounio compiles itself, bootstrapped from a [2000-line C compiler](bootstrap/stage0.c) through a multi-stage chain to a true fixed-point where stage N and stage N+1 produce bit-identical binaries. It was used to computationally verify a new result in algebra — that the count of nonzero octonion basis associators equals |PSL(2,7)| = 168 — now [submitted for publication](#the-168-theorem).\n\nThis is an active **research project**, not a production release. Read the [honest status](#honest-status) before using it for anything serious.\n\n### Cross-Repo Example: Cognitive O-SSM on SWOW-EN\n\nThe canonical Sounio checkout now includes a bounded cross-repo example under:\n\n- `examples/cognitive_ossm/`\n\nThis lane is paired with the repository:\n\n- `github.com/agourakis82/hyperbolic-semantic-networks`\n\nWorkflow split and current boundary:\n\n- Sounio provides checkable `.sio` implementation scaffolding and separately executable epistemic receipts.\n- The hyperbolic repo exports the compact SWOW bundle in `data/cpc2026/sounio_input/`.\n- The hyperbolic repo's Python mirror currently generates the full paper-scale O-SSM artifacts.\n- The repaired native reference passes Madaros `check`, but current native-v2 compilation is blocked. Historical native n=100/n=1000 JSON files are excluded from parity claims.\n\nFrom the Sounio repo root:\n\n```bash\n./bin/souc check examples/cognitive_ossm/run_ossm_native_reference.sio\nCPC2026_SCIENTIFIC_REPO=/workspace/hyperbolic-semantic-networks \\\n bash scripts/ci/cpc2026_yale_evidence_gate.sh\nuv run --with numpy python scripts/research/cpc2026_ossm_subset_audit.py\n```\n\n---\n\n## For LLMs and Code Tools\n\n- Session bootstrap:\n 1. Run `./sounio-whereami --quick`\n 2. Read [ONBOARDING.md](ONBOARDING.md)\n 3. Read [CLAUDE_HANDOFF.md](CLAUDE_HANDOFF.md)\n 4. Read [CLAUDE.md](CLAUDE.md)\n 5. Read [AGENTS.md](AGENTS.md)\n 6. Verify the current branch before editing\n 7. Treat `/workspace/sounio` as the active remote-first workspace path\n 8. Do not propose destructive reset/clean/rebase flows to \"simplify\" recovery state\n- Prompt surface: [llms.txt](llms.txt)\n- **Repository scale (read before estimating size):** [SCALE.md](SCALE.md) · [docs/audit/README.md](docs/audit/README.md)\n- Regenerate numbers: `bash scripts/dev/measure_repo_scale.sh`\n- Repository guide: [CLAUDE.md](CLAUDE.md)\n- Syntax and workflow guide: [docs/guide/LLM_PROGRAMMING_GUIDE.md](docs/guide/LLM_PROGRAMMING_GUIDE.md)\n- Live Hugging Face dataset: \n- Training dataset export: [datasets/sounio-code-examples/README.md](datasets/sounio-code-examples/README.md)\n- Dataset builder: [scripts/dev/export_hf_dataset.py](scripts/dev/export_hf_dataset.py)\n\nThis repo now ships a root `llms.txt` for model-aware tools and a reproducible Hugging Face-style dataset export built from the Sounio test suite.\nThe current published dataset lives in the maintainer namespace as a public mirror until the `sounio-lang` Hugging Face org namespace is ready.\n\n---\n\n## What makes Sounio different\n\n**Epistemic types as first-class citizens.** Every scientific measurement has uncertainty. Most languages ignore this. Sounio's type system includes `Knowledge[T]` with built-in confidence, provenance tracking, and automatic GUM-compliant uncertainty propagation. The compiler can enforce confidence thresholds at compile time — a function requiring `ε >= 0.82` rejects under-confident data before any code runs. No equivalent system exists in any production language.\n\n**Self-hosted compiler.** The compiler bootstrapped from C through a multi-stage chain (`stage0.c` → `boot2g.sio` → self-hosted) to a true fixed-point. The default workflow is now native-only: `bin/souc` compiles `.sio` sources to temporary or named ELFs via the Madaros self-hosted engine and executes those binaries directly.\n\n**Not a Rust/Julia dialect.** Own syntax (`&!` not `&mut`, `var` not `let mut`), own semantics (algebraic effects, linear types, dimensional analysis), own philosophy (epistemic computing for science).\n\n---\n\n## Quick taste\n\n### Uncertainty propagation with provenance\n\n```\nfn main() with IO {\n // A drug dose with tracked confidence and evidence source\n let base_dose: Knowledge[f64] = Knowledge(15.0, ε=0.92, prov=\"ASHP_2020_Level1A_RCT\")\n\n // Hospital scale measurement: high-confidence device\n let weight: Knowledge[f64] = Knowledge(78.5, ε=0.98, prov=\"hospital_scale_calibrated\")\n let ref_wt: Knowledge[f64] = Knowledge(70.0, ε=1.0)\n\n // GUM propagation is automatic: ε(a*b) = ε(a) * ε(b)\n let adjusted_dose: Knowledge[f64] = base_dose * (weight / ref_wt)\n\n // Extract propagated confidence\n let conf = adjusted_dose.ε // ~0.90\n println(conf)\n}\n```\n\n> Full pipeline: [tests/run-pass/vancomycin_propagation.sio](tests/run-pass/vancomycin_propagation.sio) — real ASHP 2020 vancomycin dosing with 5-step GUM propagation.\n\n### Compile-time confidence gate\n\n```\n// ASHP 2020 §8.3: AUC-guided dosing requires ε >= 0.82\nfn prescribe_vancomycin(dose: Knowledge[f64, ε >= 0.82]) with IO {\n println(\"Vancomycin prescribed\")\n}\n\nfn main() with IO {\n let risky_dose: Knowledge[f64, ε=0.40] = Knowledge { value: 500.0, epsilon: 0.40 }\n\n prescribe_vancomycin(risky_dose) // COMPILE ERROR: ε=0.40 < required 0.82\n}\n```\n\n> The compiler rejects this *before any code runs* — a hard patient-safety guarantee. See: [tests/compile-fail/vancomycin_low_conf.sio](tests/compile-fail/vancomycin_low_conf.sio)\n\n### Effects and linear types\n\n```\nfn sqrt_approx(x: f64) -> f64 with Mut, Div, Panic {\n if x <= 0.0 { return 0.0 }\n var g = x / 2.0\n var i = 0\n while i < 50 {\n g = (g + x / g) / 2.0\n i = i + 1\n }\n return g\n}\n\nlinear struct FileHandle { fd: i32 } // must be consumed exactly once\n```\n\n> More examples: [examples/epistemic_bmi.sio](examples/epistemic_bmi.sio), [docs/guide/SOUNIO_QUICK_START.md](docs/guide/SOUNIO_QUICK_START.md)\n\n---\n\n## Honest Status\n\nThis is an active research repository. Public claims are registry-backed; see [`docs/serious-language/public-claim-registry.v1.tsv`](docs/serious-language/public-claim-registry.v1.tsv) (authoritative for every feature's maturity tier).\n\n**PL adoption audit (2026-05-27):** [`docs/audit/PL_ADOPTION_AUDIT_2026-05-27.md`](docs/audit/PL_ADOPTION_AUDIT_2026-05-27.md) — bone-honest stocktake of what a stranger cloning this repo will find, with live probes. The two biggest adopter-unlock gaps are (G1) closing the multi-module bundle compile and (G2) the CLI exit-code contract (G2 fixed 2026-05-27 in this commit).\n\n**Registry rows you should read before drawing conclusions:**\n`stdlib.surface = validated_research` (bounded support contract only; not broad all-file callability) · `tooling.editor = validated_research` (checked formatter, REPL, preview LSP, and editor wiring; not mature IDE support) · `tooling.package = validated_research` (local packages only; no public registry) · `closures.lambdas = stale_conflicting` (spec §4.7.2 non-normative) · `generics.{structs,functions,traits} = prototype` · `binary.source = validated_research` (checked Madaros prebuilt is built from the modular tree; `lean_single.sio` remains the bootstrap seed) · `platform.windows = prototype`.\n\n**Scale (measured 2026-07-11):** **6,130** tracked `.sio` files, **~2.21M** lines (`bash scripts/dev/measure_repo_scale.sh`). The self-hosted compiler alone is **~555k** lines — not a small experiment. Full audit: [docs/audit/README.md](docs/audit/README.md) · [SCALE.md](SCALE.md).\n\n### What WORKS (evidence-backed lanes)\n\n| Component | Status | Evidence |\n|---|---|---|\n| **Epistemic core** | `Knowledge[T]` + GUM + provenance | Named package / conformance gates |\n| **Self-hosted compiler** | Lexer → codegen; fixed-point bootstrap | `lean_single` fixed-point + native-v2 spine gates |\n| **Ontology** | Generated bundles + validation harness | `run_ontology_validation.sh` + compile gates |\n| **Native codegen** | Linux ELF; Mach-O artifact lane | Self-host + native-v2 gates |\n| **Core stdlib slices** | Stats, linalg, ODE, etc. | `stdlib_science_pipeline_gate`, reliability inventory |\n| **Language server** | LSP 3.17 subset | Release binary + protocol tests (prototype per registry) |\n\n### What's SCAFFOLDING or PARTIAL\n\n| Component | Reality |\n|---|---|\n| **~46% of stdlib modules** | Classified scaffold in [audit A.2](docs/audit/README.md) — code without executable proof |\n| **32 stdlib smoke tests** | Print `FOO_OK` only; do not exercise module logic |\n| **129 CI gate scripts** | Most are **not** on `make check` / GitHub CI (audit A.4) |\n| **GPU CLI path** | PTX/kaxi code exists; end-to-end CLI path incomplete |\n| **Theorem prover / async / geometry** | Large or stub surfaces — see module audit JSON |\n\n### Stdlib module audit (A.2, not file-count folklore)\n\n| Tier | Modules | Meaning |\n|---|---:|---|\n| **works** | 66 | Tests, gates, or mass with executable evidence |\n| **scaffold** | 59 | Code present; no direct executable proof in tree |\n| **doc-only roots** | 3 | Non-module files at `stdlib/` root |\n\nDo **not** cite **814/910 (89%)** as \"stdlib completeness\" — that is harness inventory, mixes real tests with smoke placeholders, and differs from the reliability gate inventory. See audit artifacts under `artifacts/audit/`.\n\n---\n\n## The 168 Theorem\n\nWhile developing Sounio's octonion multiplication backend, we discovered and proved a combinatorial fact that appears not to have been explicitly stated in the literature:\n\n> *The number of ordered triples (i, j, k) in {1,...,7}^3 for which the octonion basis associator [e_i, e_j, e_k] is nonzero is exactly 168 = |PSL(2,7)|.*\n\nThe decomposition is 343 = 133 (repeated indices) + 42 (Fano-line triples) + **168** (non-collinear triples). We also report that sedenion nonzero associator counts are multiples of 168, and that the primitive zero-divisor pair count 336 = 2 x 168.\n\nThe result was verified computationally in Sounio and independently reproduced in Python/NumPy.\n\n**Paper:** \"The 168 Theorem: PSL(2,7) Governs Non-Associativity and Zero-Divisor Structure in the Cayley-Dickson Tower\" — Agourakis & Gerenutti (2026). Submitted to *Advances in Applied Clifford Algebras*.\n\n---\n\n## Get started\n\nThis checkout ships checked self-hosted compiler artifacts for Linux `x86_64` behind the host-aware `bin/souc` launcher, which is the official compiler entrypoint and routes to Madaros by default. The checked `bin/souc-*` binaries are Linux ELF artifacts; macOS is a cross-compile target rather than a host-native binary lane. No Rust build step is required for the default workflow.\n\n```bash\ngit clone https://github.com/sounio-lang/sounio.git\ncd sounio\n\nexport SOUC=\"$(pwd)/bin/souc\"\nexport SOUNIO_STDLIB_PATH=\"$(pwd)/stdlib\"\n\n$SOUC --version # souc 2.1.0\n$SOUC info # selected host artifact + wrapper contract\n$SOUC check examples/hello.sio # type-check via checked self-hosted lane\n$SOUC init hello_pkg && cd hello_pkg # create a minimal sounio.toml project\n$SOUC check && $SOUC run && $SOUC build # project entrypoint -> ELF\n$SOUC run examples/native/hello.sio # compile to a temp ELF and execute it\n$SOUC compile examples/hello.sio -o /tmp/souc-next\n$SOUC compile examples/hello.sio -o /tmp/hello-macos --target aarch64-macos\n```\n\nIf you need the legacy bootstrap path explicitly:\n\n```bash\nSOUNIO_SOUC_ENGINE=lean_single \\\n $SOUC compile self-hosted/compiler/lean_single.sio -o /tmp/souc-next\n```\n\nFor detailed setup: [INSTALL.md](INSTALL.md) · [docs/guide/MINIMUM_VIABLE_SOUNIO.md](docs/guide/MINIMUM_VIABLE_SOUNIO.md)\n\n### Editor integration\n\nThe Sounio language server (`bin/sounio-lsp`) ships with the checkout and is the same binary published at\n[`sounio-lsp-v0.3.0-r1`](https://github.com/Sounio-lang/sounio/releases/tag/sounio-lsp-v0.3.0-r1). Point any LSP-aware editor (VS Code, Neovim, Helix, Zed, etc.) at the binary with file-type `.sio`. Capabilities and the change log live in [`tools/lsp/CHANGELOG.md`](tools/lsp/CHANGELOG.md); Sprint-2 backlog in [`tools/lsp/SPRINT2_TODO.md`](tools/lsp/SPRINT2_TODO.md).\n\n---\n\n## Architecture\n\n**Pipeline:** Source → Lexer → Parser → AST → Check → HIR → SIR → HLIR (SSA) → Codegen\n\n| Directory | Purpose |\n|---|---|\n| `self-hosted/lexer/`, `parser/` | Frontend (tokenizer, recursive descent) |\n| `self-hosted/check/`, `types/` | Bidirectional type inference + algebraic effects |\n| `self-hosted/ir/` | IR lowering, optimization, e-graph equality saturation |\n| `self-hosted/native/` | Native ELF and Mach-O emission in the current self-hosted lane |\n| `self-hosted/compiler/` | Codegen drivers (lean, IR) |\n| `stdlib/epistemic/` | `Knowledge[T]`, uncertainty (GUM), provenance |\n| `stdlib/units/` | Dimensional analysis |\n| `bootstrap/` | stage0 (C) → boot2g → self-hosted chain |\n| `formal/` | Lean 4 proofs (epistemic type invariants) |\n| `tests/` | `run-pass/`, `compile-fail/`, `ui/`, `stdlib/` |\n\n---\n\n## Design Principles\n\n1. **Uncertainty is not optional** — Every scientific value has uncertainty. Ignoring it is a bug, not a simplification.\n2. **Provenance matters** — Data without origin is data without trust.\n3. **Propagation is automatic** — Manual uncertainty calculation is error-prone. The compiler handles it (GUM/ISO 17025).\n4. **Confidence gates execution** — Low-confidence code paths require explicit acknowledgment.\n5. **One type definition, compiler guarantees everything** — Define your epistemic constraints once; the compiler enforces them across all operations.\n\nSee [docs/MANIFESTO.md](docs/MANIFESTO.md) for the full philosophy.\n\n---\n\n## Known Limitations\n\n**Platform.** This checkout ships checked self-hosted compiler artifacts for Linux `x86_64`, macOS `arm64`, and macOS `x86_64` behind the `bin/souc` launcher. Linux `x86_64` and macOS `arm64` are the active first-class host lanes. The newer native-v2 `aarch64` backend is still preview-grade, so Apple Silicon support in this checkout is via the self-hosted Mach-O artifact lane rather than the new preview emitter.\n\n**Native startup cost.** Native execution still requires producing a host binary before launch, so there is a small startup cost compared with an in-process executor.\n\n**Launcher contract.** `bin/souc` now provides compatibility commands for `check`, `run`, `compile`, `build`, and `init`. When invoked inside a directory with `sounio.toml`, `check`, `run`, and `build` resolve the project entrypoint from `[[bin]].path`, `[project].entry`, or `src/main.sio`. Broader omega workflows and JIT-oriented tooling still live outside the checked self-hosted launcher lane.\n\n**Windows cross-compile.** The PE/COFF backend (3,508 lines) is production-grade. Use `--target x86_64-windows` to emit Windows binaries. No pre-built .exe is shipped in this checkout.\n\n**REPL.** The checked self-hosted launcher supports `souc repl` for a file-backed interactive loop.\n\n**Debug flags.** `--show-ast` and `--show-types` are supported as pass-through flags on the checked self-hosted launcher for `check`, `run`, `compile`, and `build`.\n\n**FFI.** `extern \"C\"` remains limited in scope, but the old JIT-only integer FFI failure mode is gone on the native path.\n\n**GPU.** PTX codegen exists in `self-hosted/gpu/` but there is no end-to-end compilation path from the CLI. SPIR-V/Metal/WGSL files exist as stubs.\n\nFull list: [docs/compiler/KNOWN_LIMITATIONS.md](docs/compiler/KNOWN_LIMITATIONS.md)\n\n---\n\n## Citation\n\nIf you use Sounio in academic work:\n\n```bibtex\n@software{sounio2026,\n title = {Sounio: A Systems Programming Language for Epistemic Computing},\n author = {Agourakis, Demetrios Chiuratto and Gerenutti, Marli},\n year = {2026},\n version = {2.1.0},\n doi = {10.5281/zenodo.18726647},\n url = {https://github.com/sounio-lang/sounio},\n note = {Self-hosted compiler with epistemic types and Lean 4 verification}\n}\n```\n\n---\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n\n---\n\n

At the horizon of certainty, where ancient columns meet the endless sea.

\n

SOUNIO

\n", "bytes": 19408, "sha": "3f11b7f7f003f3faf6612b7832119cf761bc726e7110bb4a7a0f0b5826ec3ea6", "repo_slug": "sounio-lang/sounio", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_agourakis82_sounio_mcp_server_d2711025/readme" }