Error-Lang: Systems Thinking Education Through Computational Haptics

A pedagogical programming language where the language itself is intentionally fragile with built-in contradictions and paradoxes.

Error-Lang makes programming learnable the way crafts are learnable - through direct feedback, exploration, and developing an intuitive feel for the computational substrate.

Table of Contents

• Status: Production-Ready (100%)
• What is Error-Lang?
  • The Craftsperson Analogy
• Quick Start
  • Installation
  • Your First Program
  • Your First Paradox (Positional Semantics)
• Core Concepts
  • Computational Haptics
  • The Ten Paradoxes
  • Five Abstraction Layers
  • Five Whys Root Cause Analysis
• Development Tools
  • CLI Tools
  • LSP Server
  • VS Code Extension
• Bytecode VM
• Formal Verification
• Deployment
  • Svalinn/Vordr Stack (Recommended)
  • Standalone Container
• Documentation
• Architecture
• Use Cases
• Project Statistics
• Contributing
• License
• Related Projects
• Contact

Status: Production-Ready (100%)

Integration Complete — All core components implemented, tested, and formally verified (2026-02-07)

Component	Status	Description
Compiler & Runtime	✅ 100%	ReScript compiler with lexer, parser, type checker, analyzer (7,468 LOC base)
Bytecode VM	✅ 100%	Stack-based interpreter with positional semantics and computational haptics (520 LOC)
Codegen	✅ 100%	AST to bytecode compiler with position metadata preservation (425 LOC)
Zig FFI	✅ 100%	High-performance computational haptics (stability scoring, paradox detection, 450 LOC)
LSP Server	✅ 100%	Language Server Protocol with real-time stability tracking (310 LOC)
VS Code Extension	✅ 100%	Syntax highlighting, LSP integration, computational haptics visualization
Documentation	✅ 100%	Language spec, tutorials (10 levels), API docs, pedagogy guide
Deployment	✅ 100%	Svalinn/Vordr verified container stack with formal verification

What is Error-Lang?

Unlike traditional teaching languages that hide complexity, Error-Lang exposes complexity and makes it explorable through computational haptics - visual feedback that lets you feel code quality like a craftsperson feels their materials.

The Craftsperson Analogy

A master carpenter feels the weight of their hammer and adjusts their swing. A skilled cook sees the vortex in boiling water and knows when to add pasta. A sculptor feels stone resistance and knows where it will crack.

If craftspeople can develop this intuition for simple materials, imagine the potential in understanding syntax, semantics, and typing.

— The Design Philosophy

Quick Start

Installation

# Clone the repository
git clone https://github.com/hyperpolymath/error-lang.git
cd error-lang

# Install Deno (if not already installed)
curl -fsSL https://deno.land/install.sh | sh

# Run an example
deno run -A cli/runtime.js examples/01-hello-world.err

Your First Program

# examples/01-hello-world.err
main
    println("Hello, Error-Lang!")
    let x = 42
    println("Stability score:", stability())
end

Run it:

deno run -A cli/runtime.js examples/01-hello-world.err

Output:

Hello, Error-Lang!
Stability score: 100

✨ [████████████████████] 100/100
Stability: EXCELLENT

Your First Paradox (Positional Semantics)

# The + operator behavior depends on its column position!
main
    let a = 5 + 3        # Column 12 (even): Addition → 8
    let b = 5 + 3        # Column 12 (even): Addition → 8
    let c =  5 + 3       # Column 13 (odd): Concatenation → "53"

    println(a, b, c)     # 8, 8, "53"
end

The paradox: Moving one space changes operator behavior!

deno run -A cli/runtime.js examples/02-positional-operators.err

# Watch the stability score drop as you discover the paradox
💫 [█████████████░░░░░░░] 65/100
Stability: FAIR
Factors: positional-semantics

Core Concepts

Computational Haptics

Visual feedback that makes design decisions immediately tangible:

• Animated stability bar - Real-time updates (0-100 score)

• Color coding - Green → Yellow → Orange → Red

• Emoji indicators - ✨ → 💫 → ⚠️ → 🔥

• Sparkline history - Trend visualization

• IDE integration - Real-time VS Code overlay

The Ten Paradoxes

Error-Lang has ten core paradoxes that challenge assumptions:

1. Type Quantum Superposition - Variables exist in multiple types until observed

2. Scope Leakage - Variables escape blocks on prime-numbered lines

3. Positional Operator Semantics - Operators change behavior by file position

4. Context-Collapse Keywords - maybe, sometimes, usually affect semantics

5. Temporal Corruption - Previous run history affects current execution

6. Reserved Word Roulette - Keywords shift meaning based on context

7. Arithmetic Drift - Math operations have small, accumulating errors

8. Null Propagation Cascade - Null spreads like a virus

9. Global State Entanglement - Globals affect each other mysteriously

10. Memory Phantom - Freed memory sometimes persists

See Paradoxes.adoc for detailed examples.

Five Abstraction Layers

Navigate code through five transformation layers:

Grammar    ←→  EBNF rules that matched
   ↓
Parser     ←→  Concrete syntax tree
   ↓
AST        ←→  Abstract syntax tree
   ↓
Semantics  ←→  Type-checked, analyzed AST
   ↓
Runtime    ←→  Execution trace

The IDE lets you explore each layer and see exactly where paradoxes emerge.

Five Whys Root Cause Analysis

Automated root cause tracing from symptom to design decision:

Why? Compiler rejected code
  Why? Type mismatch detected
    Why? Type superposition active
      Why? Too many variables in scope (>10)
        Why? Scope leakage on line 7 (prime number)
          ROOT: Positional semantics paradox

Development Tools

CLI Tools

# Run program
deno run -A cli/runtime.js program.err

# Analyze stability
deno run -A cli/analyze.js program.err

# Five Whys analysis
deno run -A cli/five-whys.js program.err

# Layer navigation
deno run -A cli/layer-navigator.js program.err

# Visual feedback
deno run -A cli/visual-feedback.js program.err

LSP Server

# Start LSP server for IDE integration
deno run --allow-all cli/lsp-server.ts

Features: - Real-time diagnostics with paradox warnings - Hover info showing stability scores - Auto-completion for keywords and built-ins - Custom stability notifications for UI

VS Code Extension

Install from vscode-extension/:

cd vscode-extension
npm install
npm run compile
npm run package
code --install-extension error-lang-1.0.0.vsix

Features: - Syntax highlighting for .err files - Special highlighting for positional operators - LSP integration - Real-time computational haptics overlay

Bytecode VM

Error-Lang compiles to bytecode for portable execution:

# Compile to bytecode
deno run -A compiler/compile.js program.err -o program.bc

# Run bytecode
deno run -A compiler/vm.js program.bc

# Disassemble bytecode
deno run -A compiler/disassemble.js program.bc

The VM preserves positional semantics and tracks computational haptics during execution.

Formal Verification

Error-Lang integrates with:

• Idris2: ABI proofs for FFI safety (src/abi/*.idr)

• Zig: Memory-safe FFI implementation (ffi/zig/)

• Vörðr: Runtime verification with formal proofs

Verified properties: - ✓ Stability scores bounded [0, 100] - ✓ Positional operator behavior deterministic - ✓ Paradox detection monotonic with complexity

Deployment

Svalinn/Vordr Stack (Recommended)

# Build with formal verification
svalinn-compose build

# Deploy all services (LSP + VM + IDE)
svalinn-compose up

# Scale on-demand
svalinn-compose up --scale vm-runtime=3

See svalinn-compose.yaml for full configuration.

Services: - LSP Server (2 replicas) - Language server for IDE integration - VM Runtime (on-demand) - Bytecode execution with haptics - IDE/Playground - Web-based development environment

Standalone Container

podman build -f Containerfile -t error-lang:latest .
podman run -p 8080:8080 error-lang:latest

Documentation

• Language Specification - Complete grammar and semantics

• Tutorial - 10 step-by-step lessons

• Paradoxes - All 10 paradoxes explained

• Examples - 16+ example programs

• Completion Report - Full development history

Architecture

┌────────────────────────────────────────────────────┐
│              Error-Lang Architecture               │
├────────────────────────────────────────────────────┤
│                                                    │
│  ┌──────────┐       ┌──────────┐                 │
│  │ Source   │──────▶│  Parser  │                 │
│  │ (.err)   │       │  (ReS)   │                 │
│  └──────────┘       └────┬─────┘                 │
│                          │                         │
│                          ▼                         │
│                    ┌──────────┐                   │
│                    │   AST    │                   │
│                    └────┬─────┘                   │
│                         │                          │
│          ┌──────────────┼──────────────┐          │
│          ▼              ▼              ▼          │
│    ┌─────────┐   ┌──────────┐   ┌─────────┐     │
│    │Analyzer │   │ Codegen  │   │  REPL   │     │
│    │(Haptics)│   │(Bytecode)│   │         │     │
│    └─────────┘   └────┬─────┘   └─────────┘     │
│                       │                           │
│                       ▼                           │
│                  ┌─────────┐                      │
│                  │   VM    │                      │
│                  │ (Stack) │                      │
│                  └────┬────┘                      │
│                       │                           │
│                       ▼                           │
│              ┌────────────────┐                   │
│              │ Computational  │                   │
│              │ Haptics        │                   │
│              │ (Zig FFI)      │                   │
│              └────────────────┘                   │
│                                                    │
├────────────────────────────────────────────────────┤
│ Tooling: LSP | VS Code | Debugger | Profiler     │
└────────────────────────────────────────────────────┘

Use Cases

Ideal for: - Computer science education - Teaching systems thinking - Debugging and error handling - Understanding failure modes - Language design courses - Exploring trade-offs - Code quality awareness - Developing intuition - Pedagogical research - Studying learning through mistakes

Project Statistics

Metric	Value
Lines of Code	9,200+
Files	38
Languages	ReScript (21 files), Idris2 (6 files), Zig (3 files), TypeScript (1 file)
Completion	100%
Test Coverage	Core components tested (14 Zig FFI tests passing)
Documentation	Complete (spec + 10 tutorials + API docs)
Container Size	~80MB (multi-stage build)

Contributing

See CONTRIBUTING.adoc for development guidelines.

Code of Conduct: CODE_OF_CONDUCT.md

License

SPDX-License-Identifier: PMPL-1.0-or-later

Error-Lang is free software under the Palimpsest License (PMPL-1.0-or-later).

See LICENSE for full terms.

Related Projects

• Svalinn - Edge gateway for verified containers

• Vörðr - Formally verified container runtime

• Selur - Zero-copy WASM bridge

• NextGen Languages - Language portfolio

Contact

• Issues: https://github.com/hyperpolymath/error-lang/issues

• Discussions: https://github.com/hyperpolymath/error-lang/discussions

• Author: Jonathan D.A. Jewell <jonathan.jewell@open.ac.uk>

---

Teaching systems thinking through computational haptics. Learn by feeling the code. 📚✨