mpl/road_map.md

MPL Implementation Audit & Vision-Aligned Roadmap

Part 1: Code Analysis - Grammar vs Examples

What Actually Exists

The ANTLR grammar (MPL.g4) successfully defines 70+ mathematical symbols and can parse all 10 example files. However, it's only a parser - no execution, no type system, no module system.

Specific Mismatches Found

1. Module System Claims vs Reality

   • Example 05: Mathematics‧sin(angle) implies qualified module access
   • Grammar: Just tokenizes ‧ (MIDDOT) with no semantic handling
   • Gap: 100% of module functionality missing

2. Type System Fiction

   • Examples: λn∈ℕ: suggests type constraints
   • Grammar: Parses IN as a token, no type checking exists
   • Example 10: age: ℕ | age>0 implies refinement types
   • Gap: 100% of type system missing

3. Effect System Illusion

   • Examples: ↴ {↯e ⇒ handler} implies exception handling
   • Grammar: Just parses symbols as operators
   • Examples: 〔〕 claims automatic resource cleanup
   • Gap: 100% of effect semantics missing

4. Parallel Execution Fantasy

   • Example 04: fetchData(url) ‖ processData(url) implies concurrency
   • Grammar: ‖ is just an infix operator
   • Gap: 100% of runtime missing

5. Pattern Matching

   • Spec promises it for M1
   • Grammar: No match construct at all
   • Gap: 0% implemented

Percentage Built vs Envisioned

• Parsing: 90% complete (missing pattern matching)
• Execution: 0% - can't run a single program
• Type System: 0% - no checking whatsoever
• Module System: 0% - no imports/exports work
• Effect System: 0% - symbols without semantics
• Standard Library: 0% - no built-in functions

Overall: ~15% of envisioned language exists

Part 2: Implementation Audit

What's Implemented

• 172 lines of ANTLR grammar
• Lexer recognizing Unicode + ASCII escapes
• Parser accepting expression/statement syntax
• Java test harness that parses files

What's Claimed But Missing

1. "Hello World" can't actually print - ✎ parsed but no runtime
2. Factorial can't compute - no function evaluation
3. File operations are fictional - 🖫 exists but does nothing
4. Modules don't resolve - 𝓜 just starts a block
5. No REPL - can't interactively try symbols
6. No error messages - parser fails with English Java exceptions

Critical Missing Pieces for Mission

• Symbol Input Methods: How does a child in Cairo type λ?
• Visual Output: Results shown as math, not text
• Symbolic Errors: ⚠ instead of "SyntaxError"
• Distribution: No installer, no website, no accessibility

Part 3: Vision-Aligned Roadmap

Phase 0: First Child (2 weeks)

Goal: ONE child writes factorial without seeing English

Code Changes:

// New: src/main/java/com/mpl/runtime/Interpreter.java
public class Interpreter {
    public Value eval(ParseTree tree) {
        // Minimal evaluator for arithmetic + functions
        // Support: numbers, +, ×, -, ÷, λ, application
    }
}

// New: src/main/java/com/mpl/ui/SymbolPad.java  
public class SymbolPad extends JPanel {
    // Visual symbol palette - click to insert
    // Groups: Greek, Math, Logic, Effects
    // Tooltips show symbol meaning with pictures
}

Deliverable: Video of child clicking symbols to compute λn: n×n applied to 5, seeing 25

Phase 1: Symbol Accessibility (1 month)

Goal: Anyone can input symbols without special knowledge

Code Changes:

// New: src/main/resources/symbol-input.json
{
  "α": ["alpha", "a.", "\\alpha"],  // Multiple input methods
  "λ": ["lambda", "fn", "\\", "\\lambda"],
  "∀": ["forall", "all", "\\forall"]
}

// New: src/main/java/com/mpl/input/SmartComplete.java
// As user types "lam" → suggests λ with visual preview

Platform Solutions:

• Web: Virtual keyboard overlay
• Mobile: Custom IME with math symbols
• Desktop: System-wide compose key mappings

Success Metric: 10 children from different countries input factorial

Phase 2: Mathematical Error Messages (1 month)

Goal: Errors shown as math notation, not English text

Code Changes:

// New: src/main/java/com/mpl/errors/SymbolicError.java
public class SymbolicError {
    // Instead of "Type mismatch: expected Int, got String"
    // Show: ⚠ ℕ ≠ String with visual type hierarchy
    
    public Diagram renderError() {
        // Graphical representation of what went wrong
        // Red highlighting on problematic symbols
        // Green showing what was expected
    }
}

Examples:

• Parse error: Highlights unmatched ( with blinking )
• Type error: Shows ℕ ← "text" with red ✗
• Missing definition: ? factorial with suggestion to define

Phase 3: Visual Execution (2 months)

Goal: See programs run as animated mathematics

Code Changes:

// New: src/main/java/com/mpl/viz/ExecutionAnimator.java
// Shows factorial(3) as:
// factorial(3) → 3 × factorial(2) → 3 × 2 × factorial(1) → 3 × 2 × 1 → 6
// Each step animated with mathematical transformations

Features:

• Step-through debugging with symbol highlighting
• Value visualization (sets as Venn diagrams, functions as mappings)
• Parallel execution shown as split timelines

Phase 4: Community Seed (2 months)

Goal: First 100 non-English speakers using MPL

Code Changes:

// New: src/main/java/com/mpl/share/SymbolProgram.java
// Export programs as mathematical documents (PDF/SVG)
// QR codes for mobile symbol input

// New: src/main/resources/lessons/
// Visual tutorials - no text, only symbols and animations
// Start with arithmetic, build to algorithms

Distribution:

• mpl.math domain (not .com - emphasize mathematics)
• PWA for instant access on any device
• Offline-first for areas with limited internet
• Partner with one school in Egypt, one in Japan

Phase 5: Mathematical Standard Library (3 months)

Goal: Rich set of mathematical functions without English names

Code Changes:

-- Instead of "sort", "map", "filter":
↑: List α → List α  -- ascending order (up arrow)
∀→: (α → β) → List α → List β  -- universal transformation
∃?: (α → 𝔹) → List α → List α  -- exists predicate filter

-- File operations use pictograms:
📖: 🖫Path → String  -- read (open book)
✍: String → 🖫Path → ⊤  -- write (writing hand)

Success Metrics by Phase

• Phase 0: 1 child computes without English
• Phase 1: 10 children from different languages input symbols
• Phase 2: 50 users understand errors without translation
• Phase 3: 100 users debug programs visually
• Phase 4: 500 non-English speakers share programs
• Phase 5: 1000 users building real applications

What We're NOT Prioritizing

• Compiler optimizations
• Corporate adoption
• Performance benchmarks
• English documentation
• Traditional CS curriculum compatibility

The Revolution Metric

Each phase asks: "Could a child who speaks no English use this?"

If the answer is no, we've failed the mission. The moonshot isn't building a language - it's proving programming belongs to all humanity, not just English speakers.