Error-Lang: Systems Thinking Education Through Computational Haptics

Table of Contents

• 1. What is Error-Lang?
  • 1.1. The Craftsperson Analogy
• 2. Quick Start
  • 2.1. Installation
  • 2.2. Your First Error-Lang Program
  • 2.3. Your First Paradox
• 3. Core Concepts
  • 3.1. Computational Haptics
  • 3.2. The Ten Paradoxes
  • 3.3. Five Abstraction Layers
  • 3.4. Five Whys Root Cause Analysis
• 4. Repository Structure
• 5. Technology Stack
  • 5.1. Core Languages
  • 5.2. IDE Architecture
• 6. Development
  • 6.1. Prerequisites
  • 6.2. Building the Compiler
  • 6.3. Building the IDE
  • 6.4. Running Tests
  • 6.5. Contributing
• 7. Educational Use
  • 7.1. Target Courses
  • 7.2. 12-Week Curriculum
• 8. The Error Ecosystem
• 9. Integration with Hyperpolymath Ecosystem
• 10. Status
• 11. License
• 12. Citation
• 13. Contact
• 14. Acknowledgments

1. What is Error-Lang?

Error-Lang is a pedagogical programming language where the language itself is intentionally fragile with built-in contradictions and paradoxes. Unlike traditional teaching languages that hide complexity, Error-Lang exposes complexity and makes it explorable.

Students learn systems thinking by experiencing how design decisions ripple through a codebase, making every choice have immediate, visible consequences through computational haptics - visual feedback that lets you feel code quality like a craftsperson feels their materials.

1.1. 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

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

2. Quick Start

2.1. 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

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

2.2. Your First Error-Lang 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

You’ll see:

Hello, Error-Lang!
Stability score: 100

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

2.3. Your First Paradox

# Positional operator semantics - operators change by location!
main
    let a = 5 + 3        # Column 12: Addition → 8
    let b = 5 + 3        # Column 12: Addition → 8
    let c =  5 + 3       # Column 13: Different! → "53" (concatenation)

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

The paradox: The + operator behavior depends on its column position in the file!

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

3. Core Concepts

3.1. 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

• Audio cues (future) - Sonic feedback for instability

3.2. The Ten Paradoxes

Error-Lang has ten core paradoxes that challenge assumptions about programming:

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

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

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.

3.3. 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.

3.4. Five Whys Root Cause Analysis

Automated root cause tracing from symptom to design decision:

SYMPTOM: Stability dropped to 45

WHY 1: Variable 'x' was mutated
  WHERE: line 12, mutable assignment
  LAYER: Runtime

WHY 2: Mutation affects 3 other locations
  WHERE: lines 15, 18, 22 read 'x'
  LAYER: Semantics

WHY 3: Shared state creates coupling
  WHERE: All readers depend on 'x' stability
  LAYER: Semantics

WHY 4: No encapsulation boundaries
  WHERE: Global scope, no modules
  LAYER: AST

WHY 5: DESIGN TRADEOFF - Mutability chosen over immutability
  ALTERNATIVES: Could use immutable data structures
  CONSEQUENCE: -55 stability points

4. Repository Structure

error-lang/
├── compiler/              # ReScript compiler
│   ├── src/
│   │   ├── Types.res      # Type definitions
│   │   ├── Stability.res  # Stability tracking
│   │   ├── TypeSuperposition.res
│   │   ├── LayerNavigator.res
│   │   └── FiveWhys.res
│   └── rescript.json
│
├── cli/                   # Deno runtime
│   ├── runtime.js         # Main executable
│   ├── stability-tracker.js
│   ├── visual-feedback.js
│   ├── layer-navigator.js
│   └── five-whys.js
│
├── ide/                   # Error-Lang Studio (ReScript-TEA)
│   ├── src/
│   │   ├── Model.res      # Application state
│   │   ├── Msg.res        # Event messages
│   │   ├── Update.res     # State transitions
│   │   ├── View.res       # UI rendering
│   │   └── Main.res       # Entry point
│   ├── deno.json          # Deno configuration
│   └── vite.config.js     # Build tool config
│
├── proven/                # Idris2 formal verification
│   └── src/
│       ├── Stability.idr  # Proven stability calculation
│       ├── Scope.idr      # Proven scope rules
│       └── TypeCollapse.idr
│
├── aspects/               # a2ml aspect definitions
│   ├── positional-operators.a2ml
│   ├── scope-leakage.a2ml
│   └── type-superposition.a2ml
│
├── examples/              # Example programs
│   ├── 01-hello-world.err
│   ├── 02-positional-operators.err
│   ├── 03-context-collapse.err
│   ├── 04-scope-leakage.err
│   └── 06-type-superposition.err
│
├── docs/                  # Documentation
│   ├── Design-Philosophy.adoc
│   ├── Educational-Framework.adoc
│   ├── Error-Ecosystem-Vision.adoc
│   └── Paradoxes.adoc
│
├── STATE.scm             # Project state
├── META.scm              # Architecture decisions
├── ECOSYSTEM.scm         # Ecosystem relationships
├── ROADMAP.adoc          # Development roadmap
└── README.adoc           # This file

5. Technology Stack

5.1. Core Languages

• ReScript - Compiler and IDE (type-safe, compiles to JS)

• Deno - Runtime and build tools (secure, modern JS runtime)

• Idris2 - Formal verification (dependent types, proofs)

• Guile Scheme - Metadata files (STATE.scm, META.scm, ECOSYSTEM.scm)

• a2ml - Aspect definitions (declarative paradoxes)

5.2. IDE Architecture

• ReScript-TEA - Reactive UI framework (The Elm Architecture)

• cadre-tea-router - Client-side routing

• draig-ssg - Static site generation

• Vite - Build tool and dev server

See ARCHITECTURE.adoc for complete IDE design.

6. Development

6.1. Prerequisites

• Deno 1.40+

• ReScript compiler (npm install -g rescript or via Deno)

• Idris2 (optional, for formal verification)

6.2. Building the Compiler

cd compiler
rescript build

6.3. Building the IDE

cd ide
deno task dev
# Opens http://localhost:3000 with hot reload

6.4. Running Tests

# Runtime tests
deno test cli/

# Compiler tests
cd compiler && rescript test

6.5. Contributing

See CONTRIBUTING.md for contribution guidelines.

Key points: - All code must have SPDX headers (PMPL-1.0-or-later) - Follow RSR (Rhodium Standard Repositories) structure - Use Deno, not Node.js/npm - Use ReScript, not TypeScript - Document paradoxes in both code and docs

7. Educational Use

7.1. Target Courses

• Programming Languages - Type systems, semantics, language design

• Database Systems - Query optimization, transaction isolation (Error-DB)

• Data Structures - Algorithm stability, complexity (Error-Struct)

• Systems Thinking - Consequence propagation, feedback loops

7.2. 12-Week Curriculum

See Educational-Framework.adoc for complete curriculum.

Week 1-2: Introduction to computational haptics Week 3-4: Type quantum superposition Week 5-6: Scope and temporal effects Week 7-8: Five Whys root cause analysis Week 9-10: Design tradeoff exploration Week 11-12: Final project - stabilize fragile code

8. The Error Ecosystem

Error-Lang is the first in a series of pedagogical tools:

• Error-Lang (this repo) - Fragile programming language

• Error-DB (planned) - Fragile database with paradoxes

• Error-Struct (planned) - Data structures with stability tracking

All share: - Computational haptics (visual feedback) - Stability scoring (0-100) - Five Whys analysis (root cause tracing) - Layer navigation (transformation visualization)

See Error-Ecosystem-Vision.adoc for the complete vision.

9. Integration with Hyperpolymath Ecosystem

Error-Lang integrates with the hyperpolymath infrastructure:

• rsr-template-repo - Standard repository structure

• Hypatia - Neurosymbolic CI/CD intelligence

• gitbot-fleet - Automated bot network (rhodibot, echidnabot, etc.)

• proven - Idris2 formal verification library

• cadre-tea-router - Client-side routing for TEA apps

• draig-ssg - Static site generator

See ECOSYSTEM.scm for detailed relationships.

10. Status

Current Phase: Alpha - Foundation Complete

• ✅ Stability tracking system

• ✅ Paradox detection (context-collapse, positional ops, scope leakage)

• ✅ Five Whys root cause analysis

• ✅ Layer navigation infrastructure

• ✅ Visual haptic feedback system

• ✅ Example programs (5 paradoxes)

• ✅ Complete documentation

• 🔄 IDE implementation (architecture complete, build in progress)

• 🔄 Formal verification (Idris2 proofs designed, not implemented)

• 🔄 Remaining paradoxes (5 more to implement)

See ROADMAP.adoc for complete development plan.

11. License

PMPL-1.0-or-later (Palimpsest License)

Copyright (c) 2026 Jonathan D.A. Jewell <jonathan.jewell@open.ac.uk>

See LICENSE for full text.

12. Citation

If you use Error-Lang in research or teaching:

@software{error_lang_2026,
  author = {Jewell, Jonathan D.A.},
  title = {Error-Lang: Systems Thinking Education Through Computational Haptics},
  year = {2026},
  url = {https://github.com/hyperpolymath/error-lang},
  license = {PMPL-1.0-or-later}
}

13. Contact

Jonathan D.A. Jewell

• Email: jonathan.jewell@open.ac.uk

• GitHub: https://github.com/hyperpolymath

• Repository: https://github.com/hyperpolymath/error-lang

14. Acknowledgments

Built with the hyperpolymath ecosystem: - ReScript-TEA, cadre-tea-router, draig-ssg - proven (Idris2 verification), a2ml (aspect modeling) - Hypatia (neurosymbolic CI/CD), gitbot-fleet (automation)

Inspired by: - The Elm Architecture (Evan Czaplicki) - Dependent types research (Idris, Agda, Coq) - Systems thinking pedagogy (Donella Meadows, Peter Senge) - Computational haptics research