Class inheritance: extends Parent + chained method dispatch

Sixth piece of the Python-ergonomics catch-up. Extends the class
system from the previous commit with single inheritance via the
`extends` keyword. Method dispatch walks the parent chain when the
child class doesn't define the method.

Syntax:

    class Animal {
        name;
        fn greet(self) { return concat_many(\"hi from \", dict_get(self, \"name\")); }
        fn species(self) { return \"generic animal\"; }
    }

    class Dog extends Animal {
        name;
        breed;
        fn species(self) {                 # override
            return concat_many(\"dog (\", dict_get(self, \"breed\"), \")\");
        }
        fn bark(self) { return concat_many(dict_get(self, \"name\"), \" says woof\"); }
    }

    class Puppy extends Dog { ... }       # multi-level chains work

    h d = Dog(\"rex\", \"lab\");
    d.greet()    # inherited from Animal
    d.species()  # overridden in Dog → \"dog (lab)\"
    d.bark()     # Dog's own method

Implementation:

  AST:
    Statement::ClassDef gains `parent: Option<String>` field.

  Parser:
    Token::Extends keyword; parse_class_def reads optional
    `extends Parent` clause between name and the LBrace.

  Interpreter:
    - New `class_parents: HashMap<String, String>` table on the
      Interpreter, populated by execute_stmt when ClassDef runs.
    - Method dispatch in call_function walks the parent chain:
      try `<Child>__<method>`, then `<Parent>__<method>`, etc.,
      bounded to 64 hops as a cycle-safety net.
    - Chain walk happens BEFORE module-qualified dispatch so
      instance method lookup still wins over dotted module calls.

  Formatter:
    Prints `class Name extends Parent { ... }` when parent is set.

Tests (examples/tests/test_classes.omc — 4 new, all pass):
  - test_inherited_method: Dog inherits Animal.greet without redefining
  - test_override: Dog.species overrides Animal.species
  - test_own_method: Dog.bark not on Animal
  - test_multi_level_inheritance: Puppy chains 2 hops up to Animal.greet,
    1 hop up to Dog.bark, overrides both at species

What's NOT yet:
  - super() calls. Method overrides currently can't invoke the parent's
    implementation explicitly. Could be sugar for the mangled parent
    name lookup; deferred to a later session.
  - Multiple inheritance / mixins / MRO. Single-parent chain only.
  - Class methods / static methods. All methods are instance methods.
  - Construction calls parent's constructor automatically. Right now
    the child controls its own fields; no auto-init from parent.

Regression: 11 class tests (was 7 + 4 new) + 8 exception + 10 fstring
+ 10 regex + 17 JSON + 57 substrate + 70 builtins + 18 harmonic libs
+ 16 heal = 217 OMC tests, all pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

examples/tests/test_classes.omc

@@ -119,3 +119,62 @@ fn test_self_mutation() {
     c.increment();
     assert_eq(dict_get(c, "value"), 3, "increment chain");
 }
+
+# ---- Inheritance ----
+
+class Animal {
+    name;
+    fn greet(self) {
+        return concat_many("hi from ", dict_get(self, "name"));
+    }
+    fn species(self) {
+        return "generic animal";
+    }
+}
+
+class Dog extends Animal {
+    name;
+    breed;
+    fn species(self) {
+        return concat_many("dog (", dict_get(self, "breed"), ")");
+    }
+    fn bark(self) {
+        return concat_many(dict_get(self, "name"), " says woof");
+    }
+}
+
+class Puppy extends Dog {
+    name;
+    breed;
+    fn species(self) {
+        # Override even the Dog's override.
+        return concat_many("puppy (", dict_get(self, "breed"), ")");
+    }
+}
+
+fn test_inherited_method() {
+    h d = Dog("rex", "lab");
+    # greet is defined on Animal; Dog doesn't override it.
+    assert_eq(d.greet(), "hi from rex", "inherited greet");
+}
+
+fn test_override() {
+    h a = Animal("alice");
+    h d = Dog("rex", "lab");
+    assert_eq(a.species(), "generic animal", "Animal.species");
+    assert_eq(d.species(), "dog (lab)", "Dog.species override");
+}
+
+fn test_own_method() {
+    h d = Dog("rex", "lab");
+    assert_eq(d.bark(), "rex says woof", "Dog's own method");
+}
+
+fn test_multi_level_inheritance() {
+    h p = Puppy("buddy", "golden");
+    # bark is from Dog (1 hop up), greet is from Animal (2 hops up),
+    # species is Puppy's own (overrides both).
+    assert_eq(p.bark(), "buddy says woof", "bark from Dog");
+    assert_eq(p.greet(), "hi from buddy", "greet from Animal (2 hops)");
+    assert_eq(p.species(), "puppy (golden)", "Puppy's own species");
+}

omnimcode-core/src/ast.rs

@@ -106,17 +106,27 @@ pub enum Statement {
     /// of stringifying, enabling typed-catch hierarchies.
     Throw(Expression),
     /// `class Name { field1; field2; fn method1(self, ...) { ... } }`
-    /// Minimum-viable class system: each ClassDef desugars at
-    /// register_user_functions time into:
+    /// (optional `extends Parent` clause for inheritance).
+    ///
+    /// Each ClassDef desugars at register_user_functions time into:
     ///   - A constructor fn `Name(field1, field2, ...)` that builds a
     ///     dict with __class__="Name" plus each field as a key.
     ///   - One top-level fn per method, name-mangled as `Name__method`.
+    ///
     /// Method dispatch `obj.method(args)` works because the
     /// call-resolution path checks whether the receiver is a Dict
     /// carrying __class__ and routes to the mangled fn name with
     /// `obj` injected as the first argument (the `self` slot).
+    ///
+    /// Inheritance: when `parent` is `Some("Parent")`, the
+    /// instance's __class__ is still set to the child's name, but
+    /// method dispatch falls back to the parent's mangled namespace
+    /// (and recursively up the chain) if the child doesn't define
+    /// the method. The Interpreter maintains a class_parents table
+    /// for the lookup.
     ClassDef {
         name: String,
+        parent: Option<String>,
         fields: Vec<String>,
         methods: Vec<Statement>, // each is a FunctionDef
     },

omnimcode-core/src/formatter.rs

@@ -214,9 +214,13 @@ fn format_stmt(stmt: &Statement, level: usize, out: &mut String) {
             indent_to(level, out);
             out.push_str("}\n");
         }
-        Statement::ClassDef { name, fields, methods } => {
+        Statement::ClassDef { name, parent, fields, methods } => {
             out.push_str("class ");
             out.push_str(name);
+            if let Some(p) = parent {
+                out.push_str(" extends ");
+                out.push_str(p);
+            }
             out.push_str(" {\n");
             for f in fields {
                 indent_to(level + 1, out);

omnimcode-core/src/interpreter.rs

@@ -15,6 +15,11 @@ pub type JitDispatch =
 pub struct Interpreter {
     globals: HashMap<String, Value>,
     functions: HashMap<String, (Vec<String>, Vec<Statement>)>,
+    /// Class-parent table for `class Child extends Parent` inheritance.
+    /// Maps child class name → parent class name. The instance-method
+    /// dispatch path walks this chain when `<Child>__<method>` isn't
+    /// found, trying `<Parent>__<method>` and so on.
+    class_parents: HashMap<String, String>,
     /// Optional JIT dispatch hook. When set, `invoke_user_function_at`
     /// consults this BEFORE running the tree-walk body. If the hook
     /// returns `Some(result)`, that result wins; otherwise tree-walk
@@ -99,6 +104,7 @@ impl Interpreter {
             test_current_name: std::cell::RefCell::new(String::new()),
             call_stack: Vec::new(),
             host_builtins: HashMap::new(),
+            class_parents: HashMap::new(),
         }
     }
 
@@ -1452,11 +1458,14 @@ impl Interpreter {
                 self.functions.insert(name.clone(), (params.clone(), body.clone()));
                 Ok(())
             }
-            Statement::ClassDef { name, fields, methods } => {
+            Statement::ClassDef { name, parent, fields, methods } => {
                 // Desugar at execute time so the tree-walker doesn't
                 // need register_user_functions to have been called.
                 // Same logic as register_user_functions::visit:
                 // synthesize a constructor + mangled methods.
+                if let Some(p) = parent {
+                    self.class_parents.insert(name.clone(), p.clone());
+                }
                 let mut ctor_body: Vec<Statement> = Vec::new();
                 ctor_body.push(Statement::VarDecl {
                     name: "__obj".to_string(),
@@ -2146,6 +2155,10 @@ impl Interpreter {
         // the mangled `<ClassName>__<method>` fn registered at class-
         // definition time, with `obj` injected as the first arg.
         //
+        // Inheritance: when the child class doesn't define <method>,
+        // walk up the class_parents chain trying `<Parent>__<method>`,
+        // `<Grandparent>__<method>`, and so on. First hit wins.
+        //
         // This MUST be checked before module-qualified dispatch so
         // that instance dicts aren't accidentally looked up as
         // modules. Identified by: receiver-name is a local variable
@@ -2154,13 +2167,22 @@ impl Interpreter {
             if let Some(Value::Dict(d)) = self.get_var(recv_name) {
                 let class_key = d.borrow().get("__class__").cloned();
                 if let Some(Value::String(class_name)) = class_key {
-                    let mangled = format!("{}__{}", class_name, method_name);
-                    if let Some((params, body)) = self.functions.get(&mangled).cloned() {
-                        // Build the call arg list: receiver first
-                        // (binding to `self` if that's the first param
-                        // name), then the rest. We pass the receiver
-                        // as a variable expression — the existing
-                        // `recv_name` resolves to the same dict.
+                    // Walk class → parent chain, bounded to avoid
+                    // accidental cycles in a malformed class table.
+                    let mut current_class: Option<String> = Some(class_name);
+                    let mut hops = 0usize;
+                    let mut hit: Option<(String, Vec<String>, Vec<Statement>)> = None;
+                    while let Some(c) = current_class {
+                        if hops > 64 { break; } // sanity bound
+                        let mangled = format!("{}__{}", c, method_name);
+                        if let Some((params, body)) = self.functions.get(&mangled).cloned() {
+                            hit = Some((mangled, params, body));
+                            break;
+                        }
+                        current_class = self.class_parents.get(&c).cloned();
+                        hops += 1;
+                    }
+                    if let Some((mangled, params, body)) = hit {
                         let mut full_args: Vec<Expression> =
                             Vec::with_capacity(args.len() + 1);
                         full_args.push(Expression::Variable(recv_name.to_string()));
@@ -7122,7 +7144,14 @@ impl Interpreter {
                     fns.insert(name.clone(), (params.clone(), body.clone()));
                     for s in body { visit(s, fns); }
                 }
-                Statement::ClassDef { name, fields, methods } => {
+                Statement::ClassDef { name, parent: _parent, fields, methods } => {
+                    // NOTE: parent registration happens in execute_stmt
+                    // (which has access to &mut self). visit() only
+                    // sees &mut HashMap<...> so it can't reach the
+                    // class_parents table. For the VM-prep path, the
+                    // class_parents update is made during execute_stmt
+                    // when the statement actually executes.
+                    //
                     // Desugar: build a constructor fn and one method fn
                     // per declared method. The constructor is a body of
                     // dict_set calls that populates a fresh dict with

omnimcode-core/src/parser.rs

@@ -42,6 +42,7 @@ pub enum Token {
     Throw,
     Match,
     Class,
+    Extends,
     /// f-string template — alternating literal and expression segments.
     /// Parser turns this into `concat_many(parts...)` at expression
     /// position.
@@ -475,6 +476,7 @@ impl Lexer {
                         "finally" => Token::Finally,
                         "throw" => Token::Throw,
                         "class" => Token::Class,
+                        "extends" => Token::Extends,
                         "match" => Token::Match,
                         "and" => Token::And,
                         "or" => Token::Or,
@@ -1099,6 +1101,13 @@ impl Parser {
     fn parse_class_def(&mut self) -> Result<Statement, String> {
         self.expect(Token::Class)?;
         let name = self.parse_ident()?;
+        // Optional `extends Parent` clause.
+        let parent = if self.current() == Token::Extends {
+            self.advance();
+            Some(self.parse_ident()?)
+        } else {
+            None
+        };
         self.expect(Token::LBrace)?;
         let mut fields: Vec<String> = Vec::new();
         let mut methods: Vec<Statement> = Vec::new();
@@ -1117,7 +1126,7 @@ impl Parser {
             }
         }
         self.expect(Token::RBrace)?;
-        Ok(Statement::ClassDef { name, fields, methods })
+        Ok(Statement::ClassDef { name, parent, fields, methods })
     }
 
     /// `try { ... } catch err { ... }` with optional trailing