Stryx Programming Language

[Version 0.1-draft] [Build: In Progress] [Modes: Scripting | Systems] [Runtime: stryxvm + JIT]

Stryx is a gradually typed, hybrid systems/scripting language that bridges the gap between rapid developer iteration and low-level mechanical sympathy. By combining an explicit compile-time execution model with an isolated CPython runtime bridge, Stryx allows you to write quick, expressive scripts and scale them seamlessly into zero-overhead, JIT-accelerated systems software—all using a single, unified grammar.

---

Core Philosophy & Design Goals

Modern software development often forces an artificial choice: pick a dynamic scripting language (like Python or JavaScript) for fast iteration but sacrifice hardware predictability, or pick a systems language (like C++ or Rust) for performance but endure verbose ceremony for simple tasks.

Stryx treats this as a continuous spectrum, rather than a binary choice:

• One Unified Grammar: There is no distinct scripting dialect. The exact same syntax compiles under both paradigms; behavioral differences emerge purely from structural configuration, not syntax.
• Continuous Type Gradient: Move fluidly between explicit static types (int, float), compile-time inferred types (auto), and fully boxed dynamic wrappers (any). Type transitions are strictly controlled—no variable can silently downgrade into dynamic boxing without an explicit opt-in.
• Explicit Interoperability Boundaries: Interacting with foreign environments (such as embedded Python) is never transparent. Data entering or leaving an interpreted environment must be explicitly declared and asserted at the boundary. This eliminates hidden scope bleeding and visualizes performance costs directly in the source code.
• Portable-First, Native-on-Demand: Stryx code compiles to architecture-agnostic bytecode (.sbc) for maximum portability. When performance matters, localized hotpaths can be surgically promoted to native machine instructions at runtime using simple optimization directives.

---

The Ecosystem Toolchain

The Stryx toolchain is divided into discrete, specialized components designed for high-throughput build pipelines and modular package management:

Component	Binary	Primary Role
Compiler Frontend	stryc	Parses .strx source, executes constant folding, and emits optimized .sbc bytecode.
Virtual Machine	stryxvm	Interprets .sbc bytecode and hosts the native @optimize(hotpath) JIT compilation engine.
Package Manager	strpkg	Manages external module dependencies, project initialization, and reproducibility lockfiles.
Interactive REPL	stryx	Launches an interactive environment or executes localized scripts shorthand.

Compilation Pipeline Architecture

.strx Source File(s)
        │
        ▼
stryc (Lexer → Parser → AST)
        │
        ▼
Stryx IR (Intermediate Representation)
        │
        ├─────────────────────────┐
        │                         │
        ▼                         ▼
Bytecode Emitter      Constant Folding & Inlining Pass
        │                         │
        └─────────────┬───────────┘
                      │
                      ▼
                 .sbc Asset
                      │
                      ▼
      stryxvm (Bytecode Interpreter)
                      │
          ┌───────────┴───────────┐
          │                       │
          ▼                       ▼
   Standard VM          @optimize(hotpath)
                            JIT Pass
                                │
                                ▼
                 Native Machine Instructions

---

Project Setup & Tooling

Stryx projects are structured around an explicit workspace configuration file, Project.strxpkg, which defines entry points, compile-time optimizations, and foreign bridge requirements.

File Structure Conventions

• .strx: Human-readable source files.
• .sbc: Portably compiled Stryx bytecode binaries.
• .strxpkg: TOML-formatted package manifest.
• .strxlock: Generated dependency lock file.

Sample Manifest (Project.strxpkg)

[package]
name    = "orbital_sim"
version = "0.1.0"
entry   = "src/main.strx"

[dependencies]
stryx_math   = "1.2.0"
stryx_time   = "0.5.1"

[build]
optimize = ["src/simulation.strx"]   # Files explicitly targeted for hotpath analysis
python_bridge = true                  # Embeds the CPython sub-interpreter instance

Quick CLI Shorthands

# Compile a project file to bytecode
stryc main.strx -o main.sbc

# Compile with analytical JIT tracking reports
stryc main.strx --emit-ir --hotpath-report

# Direct interpretation of a script (implicit Scripting Mode)
stryx script.strx

# Pipeline compilation and immediate execution
stryc main.strx | stryxvm -

---

Execution Models: Dual-Mode Design

Stryx alters its execution runtime based on the presence of an explicit entry point.

1. Scripting Mode (Implicit Top-Level Frame)

If a source file contains no main() function, the compiler treats it as a script.

• Statements are executed sequentially at the file root.
• Variables default to heap-allocated closures when their structural types cannot be resolved statically at compile time.
• Perfect for configuration files, text manipulation pipelines, and prototyping.

2. Systems Mode (Hard-Stack Enforcement)

If a function named main() -> int or main() -> void is explicitly declared, the compiler switches into Systems Mode.

• Zero top-level statements are permitted outside of pure structural declarations, modules, and directive definitions.
• All variables within functions are strictly stack-local and guarantee a localized, predictable memory footprint.
• Compilation guarantees minimal overhead and enables optimal JIT compilation vectors.

---

Core Language Syntax Tour

1. The Continuous Type Gradient

Stryx adheres to one fundamental typing rule: If a type is explicitly specified, enforce it. If no type is specified, default to any.

int count = 100         // Explicit static: compiled to fixed-size stack primitive
auto ratio = 3.14       // Inferred static: type deduced at compile time; zero runtime cost
any payload = 12.5      // Boxed dynamic: explicit 128-bit runtime variant box on the heap

2. Keyword-less Functions & Tuples

Functions are distinguished purely by their structural arrow signature (->). They support default arguments, compile-time return inference (auto), and multiple return unpacking.

3. Value-Semantic Structs & Overloading

Structs in Stryx are laid out contiguously and passed by value (copied layout) unless explicitly requested by reference using the & modifier.

---

The Python Interoperability Boundary

Stryx features an embedded, isolated CPython sub-interpreter instance. This boundary does not blend execution scopes; instead, values are deeply copied across runtime layers, providing distinct encapsulation and strict fault isolation.

Operational Architecture

• Flattened Scopes: Struct parameters passed into a Python boundary are flattened into snake_case combinations (e.g., coord.x shifts to coord_x inside Python).
• Return Type Assertions: Return paths must explicitly match the target Stryx variable declaration. Returning an incompatible type triggers a catchable ConversionError.
• Exception Wrapping: Uncaught Python exceptions are trapped at the barrier, translated into a native PythonError, and thrown into the Stryx standard try-catch pipeline.

---

Optimization Directives & JIT Lifecycle

• @optimize(hotpath): Instructs stryxvm to monitor and runtime-compile a function or tight loop block into native machine instructions.
• @inline: Eliminates routine call-stack overhead by substituting function call sites directly.
• @noinline: Inhibits call elimination routines, keeping stack traces distinct for debugging.

---

License

Stryx is open-source software drafted under the specification guidelines of Version 0.1.