Introduction & Philosophy

Wysna is a statically-typed programming language engineered for high predictability, zero-friction memory safety, and seamless native execution. It is designed to be easily reasoned about by both human engineers and AI coding agents.

Why Wysna?

In modern software development, teams often face a dilemma:

• High-level interpreted or runtime-managed languages (Python, JavaScript) offer friendly ergonomics and fast prototyping, but struggle with runtime crashes, untyped errors, dynamic mutation traps, and garbage collection latency.
• Low-level systems languages (C, C++, Rust) provide bare-metal performance and deterministic memory layouts, but carry significant cognitive overhead regarding pointers, manual memory allocation, complex borrow checkers, or verbose lifetime annotations.

Wysna occupies a distinct sweet spot:

1. Familiar, Clean Syntax: An expressive grammar that avoids unnecessary boilerplate while enforcing explicit types at module boundaries.
2. Pure Value Semantics: Types behave like independent values. Modifying a list or struct passed into a function does not secretly mutate the caller’s copy.
3. Automatic Reference Counting (ARC) + Copy-on-Write (CoW): Memory is freed the instant its reference count hits zero. Mutations only duplicate buffers if they are shared.
4. Compile-time Error Modeling: No unchecked runtime exceptions. Optionality (T?) and fallible operations (T ! E) are part of the type signature.
5. Direct C99 & WASI Target: Compiles into standardized, readable C99 source code, allowing it to leverage mature optimizing C compilers (Clang, GCC) and run anywhere from microcontrollers to WebAssembly sandboxes.

Meet Wawi: The Official Mascot

Wysna is personified by Wawi, inspired by the Ecuadorian Ninacuro (Pyrophorus noctilucus), a click beetle renowned for producing 100% efficient bioluminescent “cold light” without thermal dissipation. In compiler engineering, this mirrors Wysna’s deterministic zero-GC value semantics: maximum computational light with zero runtime waste.

---

Core Mental Model

                    ┌─────────────────────────┐
                    │     Wysna Source        │
                    │      (*.wysna)          │
                    └────────────┬────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │    High-Level IR (HIR)  │  ◄── Type checking, Scope &
                    │   Semantic Validation   │      Exhaustive Match checks
                    └────────────┬────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │    Mid-Level IR (MIR)   │  ◄── Flow graph, Lifetime facts,
                    │   ARC / CoW Lowering    │      Deterministic Drops
                    └────────────┬────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │     C99 / WASI Code     │  ◄── Native executable via
                    │   Clang / GCC Toolchain │      system C compiler
                    └─────────────────────────┘

Determinism by Default

Every statement, assignment, and function call in Wysna has deterministic behavior. There are no mysterious background runtime threads or garbage collection pauses. When a scope finishes, all allocated resources owned by that scope are released immediately.

AI-Agent Friendliness

Wysna’s grammar and compiler diagnostics are intentionally structured to avoid ambiguous syntactic constructs. Because types and error states are explicit, AI agents can generate, inspect, and repair Wysna code with minimal semantic drift.