JANUS 🜏

"The last programming language you need to learn."

Status: Production-Ready — :core + :service Profiles Complete

License: Libertaria Suite (LCL-1.0 / LSL-1.0 / LUL-1.0)

Repository: https://git.maiwald.work/Janus/janus-lang

---

🔥 The Breakthrough: One Language. From Teaching to Production.

Janus is the last programming language you need to learn — combining teaching simplicity with production power through native Zig compilation.

❌ The Old Way:

• Teach in Python (easy but slow)
• Rewrite in C++ (fast but unsafe)
• Or teach C directly (students drown in complexity)

✅ The Janus Way:

• Learn with clean syntax — Teaching-friendly, AI-friendly
• Build with Zig's stdlib — Production tools from day one
• Deploy native binaries — Zero rewrites, zero interpreters
• Master systems programming — Understanding from fundamentals to metal

The Strategic Genius

Janus compiles natively through Zig, giving you the entire Zig standard library wrapped in teaching-friendly syntax:

// Week 1: Learn fundamentals with clean, honest syntax
func factorial(n: i32) -> i32 {
    if n <= 1 { return 1 }
    return n * factorial(n - 1)
}

// Week 2: Access production-grade Zig stdlib natively
use zig "std/ArrayList"
use zig "std/fs"

var list = zig.ArrayList(i32).init(allocator)
var file = zig.fs.cwd().openFile("data.txt", .{}) catch |_| {}

You get:

• ✅ Clean syntax for learning and teaching
• ✅ Zig's battle-tested stdlib for building real systems
• ✅ Native LLVM performance — No interpreter, no runtime overhead
• ✅ Zero FFI — It's all native compilation
• ✅ Production-ready from day one

This is not a toy. This is strategic systems programming education.

Start Learning: The Monastery →

---

⚒️ The Vision

Janus is a strategic weapon against software complexity and educational fragmentation.

Systems programming lost its way:

• Python — Easy but too slow for systems
• C/C++ — Fast but unsafe, complex, memory leaks
• Rust — Safe but steep learning curve, slow iteration
• Go — Simple & procedural but hides too much, not for systems

Janus gives you all four virtues:

• Easy — Clean teaching syntax, progressive disclosure
• Fast — Native LLVM compilation, zero-cost abstractions
• Safe — Explicit memory management, error handling, no GC
• Honest — All costs visible, no hidden complexity

---

⚡ Production Ready: What Works Today

Test Coverage: 477/478 tests passing (99.8%) Compiler Status: Production-ready for teaching and real systems

🔥 Complete Language Features

Core Language (✅ 100% Functional):

• Functions with parameters, return types, and error handling
• Variables (let/var) with type inference
• Control flow: if/else, while, for, match (with exhaustiveness)
• Error handling: fail/catch/try with error unions T ! E
• Complete type system: primitives, structs, arrays, slices, optionals
• All operators: arithmetic, logical, bitwise, comparison, compound assignment
• Pattern matching with exhaustiveness checking
• Module system with import and use zig

Native Zig Integration (✅ Zero-Cost):

• use zig "path" — Direct access to Zig's entire standard library
• ArrayList, HashMap, file I/O, JSON, crypto, networking — all available
• No FFI overhead — Janus syntax compiles through Zig natively
• Students get production-grade tools from day one
• Write Janus syntax, get Zig performance and stdlib

Compilation Pipeline (✅ Production-Grade):

• Source → Parser → ASTDB → Symbol Table → Type System → QTJIR → LLVM → Native Binary
• Full semantic validation with pedagogical error messages
• Profile enforcement (:core, :script, :service, :cluster, :compute, :sovereign)
• Complete end-to-end compilation tested

Error Handling (✅ Complete):

• Error unions: func divide(a: i32, b: i32) -> i32 ! DivisionError
• Fail statement: fail ErrorType.Variant
• Catch expression: divide(10, 0) catch err { handle_error() }
• Try operator: let result = divide(10, 0)? (propagate errors)
• Type-safe, explicit, no exceptions

🚀 Concurrency (:service Profile — NEW in v2026.1.7)

CBC-MN Scheduler: Capability-Budgeted Cooperative M:N Scheduling

// Structured concurrency with nurseries
func main() {
    nursery {
        spawn fetch_user(1)
        spawn fetch_user(2)
        spawn fetch_user(3)
    }
    // All tasks complete here - no leaked goroutines!
    println("All users fetched")
}

async func fetch_user(id: i32) -> User {
    let data = await http.get("/users/" + id)
    return User.from_json(data)
}

What you get:

• ✅ M:N Fibers — Lightweight stackful fibers with work-stealing
• ✅ Structured Concurrency — Nurseries guarantee all children complete
• ✅ async/await — Clean syntax for asynchronous operations
• ✅ spawn — Launch tasks in current nursery scope
• ✅ Channels — CSP-style message passing
• ✅ select — Multi-channel wait with timeout
• ✅ Budget-driven scheduling — DoS immunity at language level
• ✅ No GC — Deterministic performance, zero runtime overhead

Learn more: SPEC-021: M:N Scheduler | SPEC-019: :service Profile

📖 Start Learning: The Monastery

The :core profile is 100% complete and ready for teaching systems programming from fundamentals to production.

The :service profile is 100% complete for building concurrent, high-performance backend services.

---

🚀 Quick Start

You are an engineer. You know what to do.

# Clone and build
git clone https://git.maiwald.work/Janus/janus-lang.git
cd janus-lang
make build

# Run hello world
./zig-out/bin/janus run examples/hello.jan

Output:

Hello, Janus!

First Program with Error Handling

error DivisionError { DivisionByZero }

func divide(a: i32, b: i32) -> i32 ! DivisionError {
    if b == 0 {
        fail DivisionError.DivisionByZero
    }
    a / b
}

func main() {
    let result = divide(10, 2) catch err {
        println("Error caught!")
        return
    }
    println(result)  // Prints: 5
}

This compiles to native code. This is production-ready.

---

📚 Documentation

The repository is organized into Four Pillars:

1. User Manual: Guides, Operations, and Legal Policy
2. Specifications: Technical details for Compiler Developers
3. Doctrines: The Philosophy and Law of Janus
4. University: Education, Labs, and Courseware

Language Profiles

Janus is one language with multiple capability sets. See SPEC-002: Profiles System:

• :core (🜏 The Monastery) — COMPLETE — Teaching, fundamentals, systems programming
• :script (The Bazaar) — Dynamic surface, REPL, rapid prototyping
• :service (The Backend) — COMPLETE — M:N fibers, structured concurrency, async/await
• :cluster (The Swarm) — Actor model, distributed systems
• :compute (The Accelerator) — NPU/GPU kernels, data-parallel computation
• :sovereign (The King) — Complete language, raw pointers, ultimate control

Start with :core — Master systems programming fundamentals with native Zig stdlib. Begin your journey →

AI Integration

Janus is AI-friendly by design — clean syntax, explicit semantics, pedagogical error messages.

AI contributions are governed by the AI-Airlock Protocol — cryptographic enforcement, not policy. AI agents work in isolated branches and require human GPG-signed review.

🤖 AI Agents: See docs/meta/AGENTS.md for development guidelines.

---

🎯 Key Resources

For Students & Learners

• 🜏 Start Here: The Monastery — Complete :core profile curriculum
• Quick Start Guide — Your first Janus program
• Why Zig Integration Is Genius — Understanding the strategic brilliance
• Hello World → Production — 6-level progression guide
• 30 Days of :core — Structured learning path

For Developers

• SPEC-018: :core Profile — Complete technical specification
• SPEC-019: :service Profile — Concurrency & async specification
• SPEC-021: M:N Scheduler — CBC-MN scheduler architecture
• SPEC-002: Profiles System — Understanding the capability ladder
• Integration Tests — 130+ E2E tests passing
• Example Programs — Real code samples

For Contributors

• Contributing — How to contribute
• AI Policy — AI contribution governance
• AI Agents Guide — Development with AI assistance

---

🔄 Concurrency Model

Janus has something that Go, Rust, Erlang, and Zig do not have:

A first-class runtime root with explicit ownership of concurrency.

The Problem with Other Languages

// Go: Hidden runtime, implicit scheduler
go func() { ... }()  // Where does this run? Magic!

// Tokio: Global runtime, ambient authority
tokio::spawn(async { ... });  // Which executor? The invisible one!

The Janus Solution: Explicit Authority

// Janus: Explicit handles, visible authority
nursery do
    spawn task_a()  // Uses nursery's scheduler handle
    spawn task_b()  // Same scheduler, visible relationship
end

Why this matters:

Concern	Go/Rust/Erlang	Janus
Test isolation	❌ Hard	✅ Easy
Multiple runtimes	❌ Impossible	✅ Natural
Debugging	❌ Magic	✅ Explicit
Embedding	❌ Painful	✅ Clean

Key Principles

1. One Runtime Root — Single global Runtime, not a hidden scheduler
2. Explicit Handles — Nurseries store scheduler references, not callbacks
3. No Invisible Authority — Even the scheduler must be passed explicitly
4. Budget-Driven Yielding — Deterministic, not time-based

Learn more: Runtime Root Architecture | SPEC-021: M:N Scheduler

---

🏆 Why Janus Wins

The last programming language you need to learn because:

1. Teaching-friendly syntax — Easy to learn, easy to teach, AI-friendly
2. Production-ready stdlib — Zig's entire standard library via use zig
3. Native performance — Compiles to LLVM, zero runtime overhead
4. Systems programming — From fundamentals to production, one language
5. Zero rewrites — Code written in week 1 runs in production
6. Explicit everything — Memory, errors, costs — all visible
7. Profile system — Start simple (:core), grow to (:sovereign)
8. M:N Concurrency — Structured concurrency, work-stealing, no leaked tasks
9. DoS immunity — Budget-driven scheduling at the language level

From "Hello World" to distributed systems. One language. Zero compromises.

---

"We do not pray for easy lives. We pray to be stronger men." - JFK (Paraphrased by Voxis)

"The Monastery teaches fundamentals. The Bazaar deploys systems." - The Doctrine

---

Issues: https://git.maiwald.work/Janus/janus-lang/issues Community: https://janus-lang.org (coming soon) License: Libertaria Suite