Real exceptions: throw + finally on top of the existing try/catch

First step of the Python-ergonomics catch-up goal. The existing
Statement::Try only supported `try { ... } catch err { ... }` where
the caught value was an error string produced by builtin failures.
This commit adds:

  - `throw expr` — explicit exception raise. Expression is evaluated
    and its display-string becomes the error the surrounding catch
    receives. New Statement::Throw(Expression).

  - `finally { ... }` clause on try blocks. Optional, runs after
    both the body AND any handler — including when the handler
    itself raises (matches Python's try/except/finally). Statement::Try
    extended with `finally: Option<Vec<Statement>>`.

Implementation surfaces touched:
  - ast.rs:        Try gains `finally: Option<Vec<Statement>>`;
                   Throw(Expression) added
  - parser.rs:     Token::Throw, Token::Finally lexed; parse_try_stmt
                   reads optional finally; throw is its own statement
  - interpreter.rs: execute_stmt handles Throw via eval+Err; Try now
                    runs finally regardless of outcome; rewrite_module_calls
                    + register_user_functions visit the new shape
  - formatter.rs:  Try formatter outputs the finally clause; Throw
                   formats as `throw expr;`
  - compiler.rs:   Throw falls back to Op::ExecStmt like Try (the
                   tree-walk path handles unwind; bytecode VM would
                   need a try-stack to compile these natively)

Test cases (examples/tests/test_exceptions.omc — 8 tests, all pass):
  1. Basic throw + catch with string
  2. Throw number; catch receives stringified form
  3. Catch does NOT run when try succeeds
  4. Finally runs after successful try
  5. Finally runs after catch
  6. Nested try — inner catch consumes, outer doesn't run
  7. Nested try with rethrow — outer catch sees rethrown value
  8. Throw propagates through fn call boundary

What's NOT yet shipped (future work toward "feel like a real
language"):
  - Typed-catch hierarchies. The caught value is currently always a
    Value::String. To support `catch e: SomeType { ... }` the
    Err(String) contract would need to be Err(Value), threading the
    thrown object through every Err propagation site in the
    interpreter. Single-session lift but ~40 sites to update.
  - Try-without-catch (`try { ... } finally { ... }`). Parser
    currently requires catch before finally; runtime semantics
    already handle the case.
  - Custom exception classes. Once classes/methods land, exception
    types will compose with them naturally.

Regression: 161 prior OMC tests + 8 new = 169 OMC tests pass.
77 codegen tests, cargo unit tests all green. No prior heal-pass /
substrate / harmonic_libs tests touched.

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

Author: RandomCoder-lab

examples/tests/test_exceptions.omc

@@ -0,0 +1,130 @@
+# Tests for OMC's exception handling: throw, try/catch, finally.
+# Currently the caught value is a Value::String (the thrown expression's
+# display-form). Typed-catch hierarchies (Err(Value) rather than
+# Err(String)) is future work — this test suite documents what's
+# supported today.
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_true(cond, msg) {
+    if !cond {
+        test_record_failure(msg);
+    }
+}
+
+# ---- throw + catch basics ----
+
+fn test_throw_string() {
+    h caught = "";
+    try {
+        throw "boom";
+    } catch e {
+        caught = e;
+    }
+    assert_eq(caught, "boom", "string throw caught");
+}
+
+fn test_throw_number_stringified() {
+    h caught = "";
+    try {
+        throw 42;
+    } catch e {
+        caught = e;
+    }
+    assert_eq(caught, "42", "number throw stringified at catch");
+}
+
+fn test_no_throw_no_catch_run() {
+    h ran = 0;
+    try {
+        ran = 1;
+    } catch e {
+        ran = 99;
+    }
+    assert_eq(ran, 1, "catch should not run when try succeeds");
+}
+
+# ---- finally semantics ----
+
+fn test_finally_runs_on_success() {
+    h ran = 0;
+    try {
+        # No throw
+    } catch e {
+        ran = 99;
+    } finally {
+        ran = 1;
+    }
+    assert_eq(ran, 1, "finally runs after successful try");
+}
+
+fn test_finally_runs_on_failure() {
+    h ran_catch = 0;
+    h ran_finally = 0;
+    try {
+        throw "x";
+    } catch e {
+        ran_catch = 1;
+    } finally {
+        ran_finally = 1;
+    }
+    assert_eq(ran_catch, 1, "catch ran on failure");
+    assert_eq(ran_finally, 1, "finally also ran after catch");
+}
+
+# ---- nested try ----
+
+fn test_nested_inner_catch() {
+    h outer = 0;
+    h inner = 0;
+    try {
+        try {
+            throw "inner";
+        } catch e {
+            inner = 1;
+        }
+    } catch e {
+        outer = 99;
+    }
+    assert_eq(inner, 1, "inner catch ran");
+    assert_eq(outer, 0, "outer catch did NOT run (inner consumed)");
+}
+
+fn test_nested_rethrow() {
+    h outer_msg = "";
+    try {
+        try {
+            throw "original";
+        } catch e {
+            throw "rethrown";
+        }
+    } catch e {
+        outer_msg = e;
+    }
+    assert_eq(outer_msg, "rethrown", "outer catch sees rethrown value");
+}
+
+# ---- throw inside a called function ----
+
+fn raises() {
+    throw "from raises";
+}
+
+fn test_throw_through_call() {
+    h caught = "";
+    try {
+        raises();
+    } catch e {
+        caught = e;
+    }
+    assert_eq(caught, "from raises", "throw propagates through call boundary");
+}
+
+# OMC's parser currently REQUIRES `catch` before `finally`, even when
+# the try block is not expected to throw. Try-without-catch (Python's
+# `try: ... finally: ...` without an except clause) is a future
+# parser-side relaxation — the runtime semantics already handle it.

omnimcode-core/src/ast.rs

@@ -86,16 +86,25 @@ pub enum Statement {
         /// `alias` — parser enforces this.
         selected: Option<Vec<String>>,
     },
-    /// `try { ... } catch err { ... }`. If the try block raises an
-    /// error (via `error("msg")` or any builtin failure), execution
-    /// jumps to the catch block with `err_var` bound to a Value::String
-    /// holding the error message. Without try/catch, builtin failures
-    /// crash the program.
+    /// `try { ... } catch err { ... }` with optional `finally { ... }`.
+    /// If the try block raises an error (via `throw expr`, `error("msg")`,
+    /// or any builtin failure), execution jumps to the catch block with
+    /// `err_var` bound to a Value::String holding the error message. The
+    /// `finally` block, if present, runs unconditionally after both the
+    /// try body AND any handler — even when the handler itself raises.
+    /// Matches Python's try/except/finally semantics.
     Try {
         body: Vec<Statement>,
         err_var: String,
         handler: Vec<Statement>,
+        finally: Option<Vec<Statement>>,
     },
+    /// `throw expr` — explicit exception raise. The expression is
+    /// evaluated and its display-string becomes the error message
+    /// that the surrounding catch (if any) receives in its err_var.
+    /// Future work: carry the thrown Value through Err(Value) instead
+    /// of stringifying, enabling typed-catch hierarchies.
+    Throw(Expression),
     /// `match expr { pat => stmts, ... }`. First arm whose pattern
     /// accepts the scrutinee runs; remaining arms are skipped.
     /// A wildcard or bare-identifier arm at the end is the default.

omnimcode-core/src/compiler.rs

@@ -990,11 +990,11 @@ impl Compiler {
             Statement::FunctionDef { .. } => {
                 // Function defs hoisted by compile_program(); skip here.
             }
-            Statement::Try { .. } => {
+            Statement::Try { .. } | Statement::Throw(_) => {
                 // Tree-walk fallback. See Op::ExecStmt comments — full
                 // exception unwind would require a side try-stack and
                 // a Result-aware op dispatch loop. Until that pays for
-                // itself, fall back to the AST walker for try/catch.
+                // itself, fall back to the AST walker for try/catch/throw.
                 self.emit(Op::ExecStmt(Box::new(s.clone())));
             }
             Statement::Match { .. } => {

omnimcode-core/src/formatter.rs

@@ -178,7 +178,7 @@ fn format_stmt(stmt: &Statement, level: usize, out: &mut String) {
                 out.push_str(";\n");
             }
         }
-        Statement::Try { body, err_var, handler } => {
+        Statement::Try { body, err_var, handler, finally } => {
             out.push_str("try {\n");
             for s in body { format_stmt(s, level + 1, out); }
             indent_to(level, out);
@@ -187,8 +187,18 @@ fn format_stmt(stmt: &Statement, level: usize, out: &mut String) {
             out.push_str(" {\n");
             for s in handler { format_stmt(s, level + 1, out); }
             indent_to(level, out);
+            if let Some(finally_body) = finally {
+                out.push_str("} finally {\n");
+                for s in finally_body { format_stmt(s, level + 1, out); }
+                indent_to(level, out);
+            }
             out.push_str("}\n");
         }
+        Statement::Throw(e) => {
+            out.push_str("throw ");
+            format_expr(e, out);
+            out.push_str(";\n");
+        }
         Statement::Match { scrutinee, arms } => {
             out.push_str("match ");
             format_expr(scrutinee, out);

omnimcode-core/src/interpreter.rs

@@ -644,7 +644,7 @@ impl Interpreter {
                     pragmas,
                 }
             }
-            Statement::Try { body, err_var, handler } => Statement::Try {
+            Statement::Try { body, err_var, handler, finally } => Statement::Try {
                 body: body
                     .into_iter()
                     .map(|s| Self::rewrite_module_calls(s, module_names, alias))
@@ -654,7 +654,13 @@ impl Interpreter {
                     .into_iter()
                     .map(|s| Self::rewrite_module_calls(s, module_names, alias))
                     .collect(),
+                finally: finally.map(|stmts| stmts.into_iter()
+                    .map(|s| Self::rewrite_module_calls(s, module_names, alias))
+                    .collect()),
             },
+            Statement::Throw(e) => Statement::Throw(
+                Self::rewrite_call_expr(e, module_names, alias),
+            ),
             Statement::Match { scrutinee, arms } => Statement::Match {
                 scrutinee: Self::rewrite_call_expr(scrutinee, module_names, alias),
                 arms: arms
@@ -1493,19 +1499,39 @@ impl Interpreter {
                 // No arm matched — silent no-op.
                 Ok(())
             }
-            Statement::Try { body, err_var, handler } => {
+            Statement::Try { body, err_var, handler, finally } => {
                 // Run the body; if anything inside returns Err, jump to
                 // the handler with err_var bound to the message string.
-                // The body and handler share the surrounding scope —
-                // no extra scope is pushed (matches Python try/except).
-                match self.execute_block(body) {
+                // After the body+handler complete (success OR failure),
+                // run finally unconditionally — including when the
+                // handler itself raises. Matches Python try/except/finally.
+                let body_result = self.execute_block(body);
+                let after_handler = match body_result {
                     Ok(()) => Ok(()),
                     Err(msg) => {
-                        // Install err_var in the current scope, run handler.
                         self.set_var(err_var.clone(), Value::String(msg));
                         self.execute_block(handler)
                     }
-                }
+                };
+                if let Some(finally_body) = finally {
+                    // Run finally regardless of after_handler's status.
+                    // If both finally and after_handler fail, finally's
+                    // error wins (Python's behavior — finally is the
+                    // "last word" that the surrounding scope sees).
+                    let finally_result = self.execute_block(finally_body);
+                    if finally_result.is_err() {
+                        return finally_result;
+                    }
+                }
+                after_handler
+            }
+            Statement::Throw(expr) => {
+                // Evaluate the expression, raise its display-string as
+                // the current frame's error. Surrounding catch (if any)
+                // binds the string to err_var; uncaught throws propagate
+                // up to the top-level error handler.
+                let v = self.eval_expr(expr)?;
+                Err(v.to_display_string())
             }
             _ => Ok(()),
         }
@@ -6908,9 +6934,10 @@ impl Interpreter {
                 Statement::While { body, .. } | Statement::For { body, .. } => {
                     for s in body { visit(s, fns); }
                 }
-                Statement::Try { body, handler, .. } => {
+                Statement::Try { body, handler, finally, .. } => {
                     for s in body { visit(s, fns); }
                     for s in handler { visit(s, fns); }
+                    if let Some(f) = finally { for s in f { visit(s, fns); } }
                 }
                 Statement::Match { arms, .. } => {
                     for arm in arms { for s in &arm.body { visit(s, fns); } }

omnimcode-core/src/parser.rs

@@ -28,6 +28,8 @@ pub enum Token {
     Safe,        // H.5 host-level support: `safe <expr>` prefix
     Try,
     Catch,
+    Finally,
+    Throw,
     Match,
     /// `..` for inclusive ranges in match patterns: `0..9`, `"a".."z"`.
     /// Lexed when not part of `..=` (which we don't use yet) or `...`.
@@ -365,6 +367,8 @@ impl Lexer {
                         "safe" => Token::Safe,
                         "try" => Token::Try,
                         "catch" => Token::Catch,
+                        "finally" => Token::Finally,
+                        "throw" => Token::Throw,
                         "match" => Token::Match,
                         "and" => Token::And,
                         "or" => Token::Or,
@@ -760,6 +764,16 @@ impl Parser {
             Token::For => self.parse_for_stmt(),
             Token::Fn => self.parse_function_def(),
             Token::Try => self.parse_try_stmt(),
+            Token::Throw => {
+                // `throw expr;` — evaluate expr, raise its display string
+                // as the current frame's error. Caught by surrounding
+                // try/catch; uncaught throws propagate to the top-level
+                // error handler (which prints + exits the program).
+                self.advance(); // consume `throw`
+                let expr = self.parse_expression()?;
+                self.expect(Token::Semicolon)?;
+                Ok(Statement::Throw(expr))
+            }
             Token::Match => self.parse_match_stmt(),
             // `import core;` or `import core as c;` or `load "path";`
             Token::Import | Token::Load => {
@@ -963,10 +977,11 @@ impl Parser {
         Ok(Statement::While { condition, body })
     }
 
-    /// `try { ... } catch err { ... }` — the simplest possible
-    /// exception form. No exception classes (yet); the caught value
-    /// is always a string holding the error message. Single catch
-    /// arm only — we may add multi-arm matching later.
+    /// `try { ... } catch err { ... }` with optional trailing
+    /// `finally { ... }`. The caught value is currently a Value::String
+    /// holding the error message; future work will carry the thrown
+    /// Value through unchanged for typed-catch hierarchies. Single
+    /// catch arm only — multi-arm typed matching is later work.
     fn parse_try_stmt(&mut self) -> Result<Statement, String> {
         self.expect(Token::Try)?;
         self.expect(Token::LBrace)?;
@@ -975,7 +990,17 @@ impl Parser {
         let err_var = self.parse_ident()?;
         self.expect(Token::LBrace)?;
         let handler = self.parse_block()?;
-        Ok(Statement::Try { body, err_var, handler })
+        // Optional `finally { ... }`. Runs unconditionally after both
+        // the try body and any handler (including when handler itself
+        // raises). Matches Python's try/except/finally semantics.
+        let finally = if self.current() == Token::Finally {
+            self.expect(Token::Finally)?;
+            self.expect(Token::LBrace)?;
+            Some(self.parse_block()?)
+        } else {
+            None
+        };
+        Ok(Statement::Try { body, err_var, handler, finally })
     }
 
     /// `match expr { pat => stmt, pat => { stmts }, ... }`