EmitPython.cpp

// Emits Python source from an MLIR ModuleOp whose ops have already been
// lowered to a small, closed set: func / arith / scf / cf / llvm.call /
// llvm.alloca / llvm.load / llvm.store / llvm.mlir.global /
// llvm.mlir.addressof plus outlined llvm.func bodies (parfor / anonymous
// functions).
//
// Companion to EmitC.cpp: structure mirrors that emitter closely but
// targets Python (no types, native strings, `and`/`or`, ternary `a if c
// else b`). The emitted file imports `matlab_runtime` (NumPy-backed
// shim) and runs on CPython 3.10+.

#include "matlab/MLIR/Passes/Passes.h"
#include <cmath>
#include "matlab/Basic/SourceManager.h"

#include "mlir/Dialect/Arith/IR/Arith.h"
#include "mlir/Dialect/ControlFlow/IR/ControlFlowOps.h"
#include "mlir/Dialect/Func/IR/FuncOps.h"
#include "mlir/Dialect/LLVMIR/LLVMDialect.h"
#include "mlir/Dialect/SCF/IR/SCF.h"
#include "mlir/IR/BuiltinOps.h"
#include "mlir/IR/BuiltinTypes.h"
#include "mlir/IR/Matchers.h"
#include "mlir/IR/Operation.h"
#include "mlir/IR/Value.h"
#include "mlir/IR/Verifier.h"
#include "mlir/Support/LLVM.h"
#include "llvm/ADT/DenseMap.h"
#include "llvm/ADT/DenseSet.h"
#include "llvm/ADT/SetVector.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/ADT/StringSet.h"

#include <cctype>
#include <cstdlib>
#include <functional>
#include <iostream>
#include <sstream>
#include <string>

namespace matlab {
namespace mlirgen {

namespace {

/// One class method (constructor / regular / get-property / operator)
/// captured during the pre-pass. The same struct doubles as the value
/// type of the call-site lookup table that drives method-call rewrites.
struct ClassMethodInfo {
  mlir::func::FuncOp Func;
  std::string ClassName;
  enum Kind { Ctor, Method, Get, Operator, Static } Kind = Method;
  std::string EmitName;   // Python `def` name (e.g. `__init__`, `deposit`,
                          // `Overdrawn`, `__eq__`).
  std::string OpSpelling; // Operator spelling for `Operator` kind only —
                          // e.g. `==` so call sites can render `a == b`.
};

/// Metadata for one MATLAB classdef: its (optional) superclass and
/// every method in the order Sema emitted them (mirrors source order).
struct ClassDef {
  std::string Super;
  llvm::SmallVector<ClassMethodInfo, 8> Methods;
};

/// Metadata for an scf.while op that matched the canonical for-loop shape
/// (one f64 iter-arg, condition `iv <= end` or `iv >= end`, body ends with
/// `iv += step ; yield`). Mirrors the C emitter's ForLoopInfo so the same
/// loops collapse to a clean `for iv in range(...)` / `for iv in
/// rt.frange(...)` in Python.
struct ForLoopInfo {
  mlir::Value Init;
  mlir::Value End;
  mlir::Value Step;
  bool IsDecreasing = false;
  // The arith.addf and scf.yield at the tail of the after-region; absorbed
  // into the for-head and never emitted as their own statements.
  mlir::Operation *AddOp = nullptr;
  mlir::Operation *YieldOp = nullptr;
  // The store-to-slot that copies the iter-arg into the user-visible
  // induction variable, plus the slot's alloca. Both are skipped when the
  // loop owns the slot exclusively (FuseSlot = true).
  mlir::Operation *BindStore = nullptr;
  mlir::Operation *SlotAlloca = nullptr;
  bool FuseSlot = false;
  // The Python identifier used for the induction variable in the emitted
  // `for iv in ...:` head.
  std::string IvName;
};

class Emitter {
public:
  Emitter(std::ostream &OS, bool NoLine, const matlab::SourceManager *SM)
      : OS(OS), NoLine(NoLine), SM(SM) {}

  bool run(mlir::ModuleOp M);

private:
  // --- Naming ------------------------------------------------------------
  std::string name(mlir::Value V);
  std::string freshName(const char *Prefix = "v");
  std::string uniqueName(llvm::StringRef Hint);
  std::string sanitizeIdent(llvm::StringRef In);

  // --- Region / block printing ------------------------------------------
  void emitRegion(mlir::Region &R, int Indent);
  void emitBlock(mlir::Block &B, int Indent);
  void emitOp(mlir::Operation &Op, int Indent);

  // --- Top-level --------------------------------------------------------
  void emitGlobal(mlir::LLVM::GlobalOp G);
  void emitFuncFunc(mlir::func::FuncOp F);
  void emitLLVMFunc(mlir::LLVM::LLVMFuncOp F);
  void emitProlog();
  void precomputeModuleProperties(mlir::ModuleOp M);

  // --- Helpers ----------------------------------------------------------
  void indent(int N) { for (int i = 0; i < N; ++i) OS << "    "; }
  std::string constStr(mlir::LLVM::GlobalOp G);
  void fail(llvm::StringRef Msg) {
    if (!Failed)
      std::cerr << "error: emit-python: " << Msg.str() << "\n";
    Failed = true;
  }
  // Advance the source-line tracker to match `L`, emitting any leading
  // `%` comments / preserved blank lines from the MATLAB source.
  void advanceTo(mlir::Location L, int Indent);
  bool emitLeadingComments(llvm::StringRef FullPath, int AfterLine,
                           int Line, int Indent, bool FunctionHeader = false);

  // --- Single-use inlining ----------------------------------------------
  std::string exprFor(mlir::Value V);
  std::string stmtExpr(mlir::Value V);
  void computeInlines(mlir::Region &R);
  bool canInline(mlir::Operation &Op);
  bool buildInlineExpr(mlir::Operation &Op, std::string &Expr);

  // --- Break/continue flag un-lowering ----------------------------------
  // Walk a region and tag every break / continue flag slot, the false
  // stores that initialise/reset them, and the scf.if ops that should
  // collapse into native `break` / `continue` one-liners.
  void scanBreakContinueFlags(mlir::Region &R);
  bool isFlagInversion(mlir::Value V);
  void gatherNonFlagConjuncts(mlir::Value V,
      llvm::SmallVectorImpl<mlir::Value> &Out);

  // --- For-loop pattern detection ---------------------------------------
  // Match an scf.while produced by LowerSeqLoops::lowerForOp. Populates
  // ForPatterns / SuppressedOps / FusedForSlots so the scf.while emitter
  // can print `for iv in range(...):` (or `rt.frange(...)`) instead of the
  // 4-line while-emulated shape.
  bool matchForPattern(mlir::scf::WhileOp W, ForLoopInfo &Info);
  void scanForLoopPatterns(mlir::Region &R);

  // Try to evaluate V as a compile-time integer-valued literal (covers
  // both arith.constant f64 / i64 and llvm.mlir.constant). Returns true
  // and writes Out when the value is exactly an integer.
  static bool tryEvalIntLiteral(mlir::Value V, long long &Out);
  // Compile-time triple-check: are all of init/end/step integer literals?
  static bool forBoundsAreIntLiterals(const ForLoopInfo &Info,
                                      long long &Init, long long &End,
                                      long long &Step);

  // --- Callee remap: llvm.call @matlab_foo -> rt.foo --------------------
  static std::string remapRuntimeCallee(llvm::StringRef Name);

  // True when the runtime helper named (without `matlab_` prefix) takes a
  // string-length operand we can drop in Python (where strings carry
  // their own length).
  static bool calleeHasDroppableLengthArg(llvm::StringRef Suffix,
                                          unsigned &LengthArgIdx);

  // True when V is a constant condition we can fold at emit time.
  // Returns 1 for static-true, 0 for static-false, -1 for "not foldable".
  static int evalConstCond(mlir::Value V);

  // Try to rewrite a `matlab_<suffix>` call as an inline numpy / Python
  // operator expression. Returns true on success and writes the
  // replacement into Out (with parens around binary forms so the result
  // composes cleanly inside other expressions).
  bool tryRewriteAsNumpy(mlir::LLVM::CallOp C, std::string &Out);

  // Try to rewrite obj_get_f64 / obj_set_f64 calls as Python attribute
  // access. obj_get_f64 produces a value expression; obj_set_f64 only
  // makes sense as a statement. The field-name operand must be a
  // string-global addressof matching a valid Python identifier.
  bool tryRewriteObjGet(mlir::LLVM::CallOp C, std::string &Out);
  bool tryRewriteObjSet(mlir::LLVM::CallOp C, std::string &Out);

  // Walk the module and group every classdef method by `matlab.class_name`
  // into Classes; populate CalleeIndex so call-site rewrites can look
  // up `BankAccount__deposit` and emit `acc.deposit(...)`. Expensive to
  // do per-call, hence the one-shot pre-pass.
  void collectClasses(mlir::ModuleOp M);

  // Emit one classdef as a Python `class` block (with `(Super)` when set).
  void emitClassBlock(llvm::StringRef ClassName, const ClassDef &CI);

  // Emit a single method inside an open class block. `Indent` is the
  // method-body indent (the `class` block uses Indent-1).
  void emitClassMethod(const ClassMethodInfo &CMI, int Indent);

  // Try to rewrite `<ClassName>__<method>(args...)` as one of:
  //   - constructor:  `ClassName(args)`
  //   - regular call: `args[0].method(args[1:])`
  //   - operator:     `args[0] OP args[1]`
  //   - get-property: `args[0].PropName`
  // Returns true on success and writes the replacement into Out.
  bool tryRewriteAsClassCall(llvm::StringRef Callee,
                              mlir::ValueRange Operands,
                              std::string &Out);

  std::ostream &OS;
  bool NoLine;
  const matlab::SourceManager *SM;
  bool Failed = false;

  llvm::DenseMap<mlir::Value, std::string> Names;
  llvm::DenseMap<mlir::Operation *, std::string> GlobalStrs;
  llvm::StringSet<> UsedNames;
  llvm::DenseMap<mlir::Value, std::string> InlineExprs;
  llvm::DenseSet<mlir::Operation *> InlinedOps;
  // Allocas whose entire use set is plain load/store. For these, the
  // pointer indirection collapses to a plain Python variable. Maps
  // alloca-op -> the Python identifier of the backing slot.
  llvm::DenseMap<mlir::Operation *, std::string> DirectSlots;
  // Per-function (persistent_name → wrap-spec) for scalar persistents.
  // Populated by the early walk below; consumed at every
  // matlab_global_set_f64 emit site so the wrap call uses a stable
  // (WL, signed) regardless of whether the local store carries the
  // fi attrs or even a typed operand.
  struct WrapSpec { int WL = 0; bool Signed = false; };
  llvm::StringMap<WrapSpec> PersistWrapSpec;
  // Alloca ops that hold arrays (from matrix-literal materialization);
  // they render as `name = [0.0] * N`, with stores/loads going via
  // indexing.
  llvm::DenseMap<mlir::Operation *, std::string> ArraySlots;
  // Subset of ArraySlots whose backing buffer was already emitted as a
  // collapsed Python list literal (`slot = [v0, v1, ...]`) — the
  // GEP/store ops that filled it have been absorbed and must not emit
  // their own statements. Keyed off SuppressedOps below.
  // Ops whose emission has been folded into a different op (e.g. the
  // GEP+store pairs that filled a matrix literal). Skip these in
  // emitOp().
  llvm::DenseSet<mlir::Operation *> SuppressedOps;
  // Break / continue flag slot allocas (matlab.name = "__did_break" /
  // "__did_continue"). The frontend lowers MATLAB `break`/`continue`
  // through these flags; the emitter un-lowers them back to native
  // Python keywords.
  llvm::DenseSet<mlir::Operation *> BreakFlagSlots;
  llvm::DenseSet<mlir::Operation *> ContinueFlagSlots;
  // scf.if ops whose entire body is a single flag-store; re-emit as
  // `if cond: break` (or continue). Value is the keyword to print.
  llvm::DenseMap<mlir::Operation *, const char *> FlagIfKind;
  // scf.if ops whose condition is purely a break/continue flag check
  // (`!did_break [& !did_continue]`) guarding a real body; emit the
  // then-region inline at the parent's indent.
  llvm::DenseSet<mlir::Operation *> InlinedIfs;
  // String globals (llvm.mlir.global with a StringAttr value), keyed off
  // the global's symbol name. When the AddressOf op for one of these is
  // inlined, return the Python literal directly so the emitted source
  // reads `rt.disp_str("Hello")` instead of `rt.disp_str(__matlab_str0)`.
  llvm::StringMap<std::string> StringGlobalLits;
  // Globals (any kind) that have already been inlined at every use site;
  // skip the top-of-file `name = "..."` declaration for them.
  llvm::StringSet<> SuppressedGlobals;
  // For-loop pattern matches (key: scf.while op).
  llvm::DenseMap<mlir::Operation *, ForLoopInfo> ForPatterns;
  // Slots whose alloca is owned by a for-loop's induction variable; the
  // alloca itself is suppressed and the slot name is the loop's IV name.
  llvm::DenseSet<mlir::Operation *> FusedForSlots;
  llvm::DenseMap<mlir::Operation *, std::string> FusedForSlotName;
  /* Per-function tracking for the persistent-snapshot prelude.
   * When the body has one or more `if isempty(p) || reset` arms
   * (shape 2 in the recognizer), the snap captures must run
   * AFTER every reset arm has executed — otherwise on a reset
   * cycle the snapshot would hold the pre-reset value while
   * the persistent's actual storage holds the reset value.
   * `ResetArmGuards` collects those scf.if ops; the scf.if emit
   * path checks the set after emitting and, when the set drains,
   * flushes `PendingSnapshotPrelude`. If no reset arm is present
   * (shape 1, the canonical isempty-only init that gets fully
   * suppressed), the prelude is emitted at function start
   * immediately, since there's no arm to wait for. */
  llvm::DenseSet<mlir::Operation *> ResetArmGuards;
  std::string PendingSnapshotPrelude;
  // Classdef registry. Classes maps the class name to its method list;
  // CalleeIndex maps every class-method symbol (`BankAccount__deposit`)
  // to its info so call-site rewriting can resolve it without scanning.
  llvm::StringMap<ClassDef> Classes;
  llvm::StringMap<ClassMethodInfo> CalleeIndex;
  int NextId = 0;

  // Most recent line emitted; used to suppress duplicate line markers
  // and to drive leading-comment emission on forward jumps.
  std::string LastLineFile;
  int LastLineNum = -1;
  bool AtBlockStart = true;
  // When non-empty, advanceTo's first-call branch (which would scan
  // back from the first op's line for leading comments) skips any
  // line ≤ this value in the matching file. We set it after hoisting
  // the script's top-of-file comment block to module-top so the same
  // lines aren't re-emitted at @main's first op.
  std::string PreEmittedCommentFile;
  int PreEmittedCommentLine = 0;

  // Top-level script body (the body of `@main`) is hoisted to module
  // scope. While emitting that body this flag is true so we don't add
  // a surrounding `def main()`.
  bool InMainHoist = false;
};

// ---------------------------------------------------------------------------
// Naming
// ---------------------------------------------------------------------------

std::string Emitter::freshName(const char *Prefix) {
  for (;;) {
    std::string S = Prefix;
    S += std::to_string(NextId++);
    if (UsedNames.insert(S).second) return S;
  }
}

std::string Emitter::sanitizeIdent(llvm::StringRef In) {
  std::string Out;
  Out.reserve(In.size() + 1);
  for (char C : In) {
    if ((C >= 'A' && C <= 'Z') || (C >= 'a' && C <= 'z') ||
        (C >= '0' && C <= '9') || C == '_') {
      Out += C;
    } else {
      Out += '_';
    }
  }
  if (Out.empty()) Out = "v";
  else if (Out[0] >= '0' && Out[0] <= '9') Out = "_" + Out;
  return Out;
}

std::string Emitter::uniqueName(llvm::StringRef Hint) {
  std::string Base = sanitizeIdent(Hint);
  if (UsedNames.insert(Base).second) return Base;
  for (int k = 2; ; ++k) {
    std::string Cand = Base + "_" + std::to_string(k);
    if (UsedNames.insert(Cand).second) return Cand;
  }
}

std::string Emitter::name(mlir::Value V) {
  auto It = Names.find(V);
  if (It != Names.end()) return It->second;
  // Prefer the user-source variable name carried through SlotPromotion +
  // LowerTensorOps (and any other pass that sets `matlab.name` on a
  // value's defining op). Falling back to a fresh `vN` only when no
  // hint is available keeps generated source readable for matrix
  // literals: `A = np.array(...)` instead of `v0 = np.array(...)`.
  if (auto *D = V.getDefiningOp()) {
    if (auto NA = D->getAttrOfType<mlir::StringAttr>("matlab.name")) {
      std::string N = uniqueName(NA.getValue());
      Names[V] = N;
      return N;
    }
  }
  std::string N = freshName();
  Names[V] = N;
  return N;
}

// ---------------------------------------------------------------------------
// Literal formatting
// ---------------------------------------------------------------------------

static std::string formatIntAttr(mlir::IntegerAttr IA, bool Unsigned = false) {
  auto T = mlir::dyn_cast<mlir::IntegerType>(IA.getType());
  if (T && T.getWidth() == 1) {
    return (IA.getValue().getZExtValue() & 1u) ? "True" : "False";
  }
  char Buf[64];
  if (Unsigned) {
    snprintf(Buf, sizeof(Buf), "%llu",
             (unsigned long long)IA.getValue().getZExtValue());
  } else {
    snprintf(Buf, sizeof(Buf), "%lld", (long long)IA.getInt());
  }
  return Buf;
}

static std::string formatFloatAttr(mlir::FloatAttr FA) {
  // Pick the shortest precision (1..17) whose `%g` text round-trips
  // exactly back to D — that's what Python's `repr(0.05)` does, and what
  // a user reading the generated source expects (`0.05`, not
  // `0.050000000000000003`). We also avoid scientific notation when a
  // longer decimal form is available — `10.0` reads better than `1e+01`.
  double D = FA.getValueAsDouble();
  // NaN / Inf have no Python literal — `%g` would emit bare `nan`/`inf`
  // (a NameError at runtime). Emit a valid float() constructor. (#197)
  if (std::isnan(D)) return "float(\"nan\")";
  if (std::isinf(D)) return D < 0 ? "float(\"-inf\")" : "float(\"inf\")";
  char Buf[64];
  // `%.17g` is the conservative reference: any value round-trips at 17.
  snprintf(Buf, sizeof(Buf), "%.17g", D);
  std::string Ref17 = Buf;
  bool Ref17HasE = (Ref17.find('e') != std::string::npos ||
                    Ref17.find('E') != std::string::npos);

  std::string S;
  for (int P = 1; P <= 17; ++P) {
    snprintf(Buf, sizeof(Buf), "%.*g", P, D);
    if (strtod(Buf, nullptr) != D) continue;
    bool ThisHasE = (strchr(Buf, 'e') || strchr(Buf, 'E'));
    // Reject a shorter form that switches to scientific notation when
    // the conservative reference renders cleanly in decimal.
    if (!Ref17HasE && ThisHasE) continue;
    S = Buf;
    break;
  }
  if (S.empty()) S = Ref17;
  bool HasDotOrExp = false;
  for (char C : S) {
    if (C == '.' || C == 'e' || C == 'E' || C == 'n') {
      HasDotOrExp = true;
      break;
    }
  }
  if (!HasDotOrExp) S += ".0";
  return S;
}

static std::string dropOuterParens(std::string E) {
  if (E.size() < 2 || E.front() != '(' || E.back() != ')') return E;
  int Depth = 0;
  for (size_t i = 0; i < E.size(); ++i) {
    if (E[i] == '(') ++Depth;
    else if (E[i] == ')') {
      --Depth;
      if (Depth == 0 && i + 1 < E.size()) return E;
    }
  }
  return E.substr(1, E.size() - 2);
}

// ---------------------------------------------------------------------------
// Runtime-symbol remap (`matlab_foo` -> `rt.foo`)
// ---------------------------------------------------------------------------
std::string Emitter::remapRuntimeCallee(llvm::StringRef Name) {
  // Every matlab_* runtime entry maps to `rt.<suffix>`. Keep non-matlab_
  // names verbatim so user-outlined helpers still resolve.
  if (Name.starts_with("matlab_")) {
    std::string Suf = Name.drop_front(strlen("matlab_")).str();
    // Suffixes that collide with Python keywords need an underscore so
    // `rt.assert(...)` parses. Kept in-sync with the runtime's
    // keyword-adjacent helpers.
    if (Suf == "assert" || Suf == "is" || Suf == "in" || Suf == "del" ||
        Suf == "if" || Suf == "else" || Suf == "elif" || Suf == "not" ||
        Suf == "and" || Suf == "or" || Suf == "lambda" || Suf == "pass" ||
        Suf == "class" || Suf == "def" || Suf == "return" ||
        Suf == "from" || Suf == "import" || Suf == "try" || Suf == "except"||
        Suf == "finally" || Suf == "raise" || Suf == "with" ||
        Suf == "while" || Suf == "for" || Suf == "yield" ||
        Suf == "global" || Suf == "nonlocal" ||
        Suf == "None" || Suf == "True" || Suf == "False")
      Suf += "_";
    return "rt." + Suf;
  }
  return Name.str();
}

// ---------------------------------------------------------------------------
// Single-use inlining
// ---------------------------------------------------------------------------

std::string Emitter::exprFor(mlir::Value V) {
  auto NI = Names.find(V);
  if (NI != Names.end()) return NI->second;
  auto II = InlineExprs.find(V);
  if (II != InlineExprs.end()) return II->second;
  if (mlir::Operation *Def = V.getDefiningOp()) {
    if (InlinedOps.count(Def)) {
      std::string Expr;
      if (buildInlineExpr(*Def, Expr)) {
        InlineExprs[V] = Expr;
        return Expr;
      }
    }
  }
  return name(V);
}

std::string Emitter::stmtExpr(mlir::Value V) {
  return dropOuterParens(exprFor(V));
}

bool Emitter::canInline(mlir::Operation &Op) {
  using namespace mlir;
  if (Op.getNumResults() != 1) return false;
  Value V = Op.getResult(0);

  // Always-inline: constants / zero / addressof.
  if (isa<LLVM::ConstantOp, arith::ConstantOp, LLVM::ZeroOp,
          LLVM::AddressOfOp>(Op))
    return true;

  if (!V.hasOneUse()) return false;
  Operation *User = V.getUses().begin()->getOwner();
  if (User->getBlock() != Op.getBlock()) return false;

  if (isa<arith::AddFOp, arith::SubFOp, arith::MulFOp, arith::DivFOp,
          arith::AddIOp, arith::SubIOp, arith::MulIOp,
          arith::AndIOp, arith::OrIOp,  arith::XOrIOp,
          arith::CmpFOp, arith::CmpIOp, arith::SelectOp,
          arith::SIToFPOp, arith::UIToFPOp,
          arith::FPToSIOp, arith::FPToUIOp,
          arith::ExtSIOp, arith::ExtUIOp, arith::TruncIOp,
          arith::TruncFOp, arith::ExtFOp,
          LLVM::GEPOp>(Op))
    return true;
  // Unregistered matlab.* binops on scalar primitives — same
  // shape and constraints as the registered arith.* ops above.
  {
    StringRef MN = Op.getName().getStringRef();
    if (Op.getNumOperands() == 2 && Op.getNumResults() == 1 &&
        (MN == "matlab.add" || MN == "matlab.sub" ||
         MN == "matlab.emul" || MN == "matlab.matmul" ||
         MN == "matlab.ediv" || MN == "matlab.matdiv" ||
         MN == "matlab.eq" || MN == "matlab.ne" ||
         MN == "matlab.lt" || MN == "matlab.le" ||
         MN == "matlab.gt" || MN == "matlab.ge" ||
         MN == "matlab.short_or" || MN == "matlab.short_and"))
      return true;
    // Unary `matlab.not` — bool NOT, common in HDL code (`~data_in`,
    // `if ~rst`, etc.) and emitted by the frontend with i1 result.
    if (MN == "matlab.not" && Op.getNumOperands() == 1 &&
        Op.getNumResults() == 1)
      return true;
    // matlab.load — slot triplet for HDL-targeted code that didn't
    // promote to llvm.alloca. Resolves through DirectSlots in
    // tryInlineExpr.
    if (MN == "matlab.load" && Op.getNumOperands() == 1 &&
        Op.getNumResults() == 1)
      return true;
  }

  // Is this LLVM call to a runtime helper that's known to be a pure
  // read with no side effects? Such calls don't block inlining of an
  // earlier value across them.
  auto isPureReadCall = [](Operation &Op2) -> bool {
    auto C = dyn_cast<LLVM::CallOp>(Op2);
    if (!C || !C.getCallee()) return false;
    StringRef N = *C.getCallee();
    if (!N.starts_with("matlab_")) return false;
    StringRef S = N.drop_front(strlen("matlab_"));
    // Conservative allowlist of known-pure runtime accessors. Adding
    // the wrong helper here would visibly reorder side effects in the
    // generated source, so we keep this list small and explicit.
    return S == "obj_get_f64" || S == "size" || S == "size_dim" ||
           S == "numel" || S == "numel3" || S == "length" ||
           S == "ndims" || S == "isempty" || S == "isnumeric" ||
           S == "isscalar" || S == "ismatrix" || S == "isvector" ||
           S == "isstruct" || S == "isfield" || S == "iscell" ||
           S == "isstring" || S == "string_len";
  };

  if (auto L = dyn_cast<LLVM::LoadOp>(Op)) {
    Value AddrV = L.getAddr();
    Block *BB = Op.getBlock();
    for (auto It = ++Block::iterator(&Op);
         It != BB->end() && &*It != User; ++It) {
      if (auto S = dyn_cast<LLVM::StoreOp>(&*It))
        if (S.getAddr() == AddrV) return false;
      if (isa<func::CallOp>(&*It)) return false;
      if (isa<LLVM::CallOp>(&*It)) {
        if (!isPureReadCall(*It)) return false;
      }
    }
    return true;
  }

  if (auto C = dyn_cast<func::CallOp>(Op)) {
    Block *BB = Op.getBlock();
    for (auto It = ++Block::iterator(&Op);
         It != BB->end() && &*It != User; ++It) {
      if (isa<LLVM::StoreOp>(*It)) return false;
      if (isa<func::CallOp>(*It)) return false;
      if (isa<LLVM::CallOp>(*It)) {
        if (!isPureReadCall(*It)) return false;
      }
    }
    (void)C;
    return true;
  }
  if (auto C = dyn_cast<LLVM::CallOp>(Op)) {
    if (!C.getCallee()) return false;
    Block *BB = Op.getBlock();
    for (auto It = ++Block::iterator(&Op);
         It != BB->end() && &*It != User; ++It) {
      if (isa<LLVM::StoreOp>(*It)) return false;
      if (isa<func::CallOp>(*It)) return false;
      if (isa<LLVM::CallOp>(*It)) {
        if (!isPureReadCall(*It)) return false;
      }
    }
    return true;
  }

  return false;
}

// Is the value's type `i1` (as opposed to a wider integer)?
static bool isI1(mlir::Type T) {
  auto IT = mlir::dyn_cast<mlir::IntegerType>(T);
  return IT && IT.getWidth() == 1;
}

bool Emitter::buildInlineExpr(mlir::Operation &Op, std::string &Expr) {
  using namespace mlir;
  if (auto C = dyn_cast<LLVM::ConstantOp>(Op)) {
    auto A = C.getValue();
    bool Unsigned = (bool)Op.getAttr("matlab.unsigned");
    if (auto IA = dyn_cast<IntegerAttr>(A)) {
      Expr = formatIntAttr(IA, Unsigned); return true;
    }
    if (auto FA = dyn_cast<FloatAttr>(A)) {
      Expr = formatFloatAttr(FA); return true;
    }
    return false;
  }
  if (auto C = dyn_cast<arith::ConstantOp>(Op)) {
    auto A = C.getValue();
    bool Unsigned = (bool)Op.getAttr("matlab.unsigned");
    if (auto FA = dyn_cast<FloatAttr>(A)) {
      Expr = formatFloatAttr(FA); return true;
    }
    if (auto IA = dyn_cast<IntegerAttr>(A)) {
      Expr = formatIntAttr(IA, Unsigned); return true;
    }
    return false;
  }
  if (isa<LLVM::ZeroOp>(Op)) { Expr = "0"; return true; }
  if (auto A = dyn_cast<LLVM::AddressOfOp>(Op)) {
    // String globals fold to a Python literal at the use site so the
    // emitted source reads `rt.disp_str("Hello")` instead of
    // `rt.disp_str(__matlab_str0)`. Function-symbol addressofs (function
    // handles) keep the bare name so they decay to the Python callable.
    auto It = StringGlobalLits.find(A.getGlobalName());
    if (It != StringGlobalLits.end()) {
      Expr = It->second;
      SuppressedGlobals.insert(A.getGlobalName());
      return true;
    }
    Expr = A.getGlobalName().str();
    return true;
  }
  auto bin = [&](const char *cc) {
    Expr = "(" + exprFor(Op.getOperand(0)) + " " + cc + " "
         + exprFor(Op.getOperand(1)) + ")";
    return true;
  };
  // Per-op wrap for integer overflow. Python's int has unbounded
  // precision, so chained arith on iN values diverges from the SV
  // DUT's mid-computation truncation: `(a + b) * c` in i16 wraps
  // twice in SV (after `+`, after `*`), but Python keeps the
  // intermediate at full precision and only the final wrap fires.
  // Wrap each addi / subi / muli / shli result here so the Python
  // ref matches SV's two's-complement semantics on every overflow-
  // capable op. Bitwise ops (and / or / xor) and right shifts
  // can't overflow and skip the wrap. i1 booleans skip too.
  auto wrapForResult = [&](std::string E) -> std::string {
    // For matlab.* unregistered binops the result type is often
    // `none`; fall back to the operand type so the wrap width
    // still matches the underlying datapath. Both arith.* and
    // matlab.* shapes go through this same path.
    mlir::IntegerType IT;
    if (auto T = mlir::dyn_cast<mlir::IntegerType>(
            Op.getResult(0).getType()))
      IT = T;
    else if (Op.getNumOperands() >= 1) {
      if (auto T = mlir::dyn_cast<mlir::IntegerType>(
              Op.getOperand(0).getType()))
        IT = T;
      else if (Op.getNumOperands() >= 2)
        if (auto T = mlir::dyn_cast<mlir::IntegerType>(
                Op.getOperand(1).getType()))
          IT = T;
    }
    if (!IT || IT.getWidth() < 2 || IT.getWidth() > 64) return E;
    // Signedness inference for the wrap helper. Walk one operand
    // back through transparent ops looking for a matlab.unsigned
    // marker — same heuristic as the func-return wrap. Default
    // signed (the SV emitter's default for multi-bit values).
    auto unsignedRoot = [&](mlir::Value V) -> bool {
      mlir::Value Cur = V;
      for (int Hops = 0; Hops < 4; ++Hops) {
        auto *Def = Cur.getDefiningOp();
        if (!Def) return false;
        if (Def->getAttr("matlab.unsigned")) return true;
        if (mlir::isa<mlir::arith::ExtUIOp, mlir::arith::ShRUIOp,
                      mlir::arith::AndIOp>(Def))
          return true;
        if (mlir::isa<mlir::arith::ExtSIOp, mlir::arith::ShRSIOp>(Def))
          return false;
        if (Def->getNumOperands() == 0) return false;
        Cur = Def->getOperand(0);
      }
      return false;
    };
    bool Sgn = !(unsignedRoot(Op.getOperand(0)) ||
                 unsignedRoot(Op.getOperand(1)));
    return std::string(Sgn ? "rt.fi_wrap_s(" : "rt.fi_wrap_u(") +
           dropOuterParens(std::move(E)) + ", " +
           std::to_string(IT.getWidth()) + ")";
  };
  auto binWrap = [&](const char *cc) {
    bin(cc);
    Expr = wrapForResult(std::move(Expr));
    return true;
  };
  if (isa<arith::AddFOp>(Op)) return bin("+");
  if (isa<arith::SubFOp>(Op)) return bin("-");
  if (isa<arith::MulFOp>(Op)) return bin("*");
  if (isa<arith::DivFOp>(Op)) return bin("/");
  if (isa<arith::AddIOp>(Op)) return binWrap("+");
  if (isa<arith::SubIOp>(Op)) return binWrap("-");
  if (isa<arith::MulIOp>(Op)) return binWrap("*");
  // arith.shli / shrsi / shrui from LowerFixedPoint. Python `>>` on int
  // is arithmetic (sign-preserving) and floors toward -inf — exactly what
  // matlab_fi_round_floor_s does on the C side. Left shift can lose
  // bits at the top; wrap the result to the declared width. Right
  // shifts can't overflow and skip the wrap.
  if (isa<arith::ShLIOp>(Op))  return binWrap("<<");
  if (isa<arith::ShRSIOp>(Op)) return bin(">>");
  // Logical right shift — Python's `>>` is arithmetic (sign-
  // preserving) but SV's `>>` is logical (zero-fill). Mask the
  // operand to its unsigned bit pattern first so the shifted
  // bits come back as zero rather than the sign extension.
  if (isa<arith::ShRUIOp>(Op)) {
    auto IT = mlir::dyn_cast<mlir::IntegerType>(
        Op.getOperand(0).getType());
    if (IT && IT.getWidth() >= 1 && IT.getWidth() <= 64) {
      uint64_t Mask = (IT.getWidth() == 64) ? ~uint64_t(0)
                                            : (uint64_t(1) << IT.getWidth()) - 1;
      Expr = "((" + exprFor(Op.getOperand(0)) + " & " +
             std::to_string(Mask) + ") >> " +
             exprFor(Op.getOperand(1)) + ")";
      return true;
    }
    return bin(">>");
  }
  // Bitwise vs logical split on i1. `and`/`or` on bools is shorter;
  // `^` doesn't have a short logical form, so emit `!=` (works because
  // `True != False`).
  if (auto A = dyn_cast<arith::AndIOp>(Op)) {
    if (isI1(A.getType())) return bin("and");
    return bin("&");
  }
  if (auto O = dyn_cast<arith::OrIOp>(Op)) {
    if (isI1(O.getType())) return bin("or");
    return bin("|");
  }
  if (auto X = dyn_cast<arith::XOrIOp>(Op)) {
    if (isI1(X.getType())) return bin("!=");
    return bin("^");
  }
  if (auto C = dyn_cast<arith::CmpFOp>(Op)) {
    const char *cc = "==";
    switch (C.getPredicate()) {
      case arith::CmpFPredicate::OEQ:
      case arith::CmpFPredicate::UEQ: cc = "=="; break;
      case arith::CmpFPredicate::ONE:
      case arith::CmpFPredicate::UNE: cc = "!="; break;
      case arith::CmpFPredicate::OLT:
      case arith::CmpFPredicate::ULT: cc = "<"; break;
      case arith::CmpFPredicate::OLE:
      case arith::CmpFPredicate::ULE: cc = "<="; break;
      case arith::CmpFPredicate::OGT:
      case arith::CmpFPredicate::UGT: cc = ">"; break;
      case arith::CmpFPredicate::OGE:
      case arith::CmpFPredicate::UGE: cc = ">="; break;
      default: return false;
    }
    Expr = "(" + exprFor(C.getLhs()) + " " + cc + " " + exprFor(C.getRhs()) + ")";
    return true;
  }
  if (auto C = dyn_cast<arith::CmpIOp>(Op)) {
    const char *cc = "==";
    switch (C.getPredicate()) {
      case arith::CmpIPredicate::eq:  cc = "=="; break;
      case arith::CmpIPredicate::ne:  cc = "!="; break;
      case arith::CmpIPredicate::slt:
      case arith::CmpIPredicate::ult: cc = "<"; break;
      case arith::CmpIPredicate::sle:
      case arith::CmpIPredicate::ule: cc = "<="; break;
      case arith::CmpIPredicate::sgt:
      case arith::CmpIPredicate::ugt: cc = ">"; break;
      case arith::CmpIPredicate::sge:
      case arith::CmpIPredicate::uge: cc = ">="; break;
    }
    Expr = "(" + exprFor(C.getLhs()) + " " + cc + " " + exprFor(C.getRhs()) + ")";
    return true;
  }
  // Unregistered matlab.* binops on scalar primitives — same set
  // and shape as the registered arith.* ops above. Renders as
  // single-expression so chains collapse to one Python line.
  {
    StringRef MN = Op.getName().getStringRef();
    if (Op.getNumOperands() == 2 && Op.getNumResults() == 1) {
      const char *cc = nullptr;
      bool Overflow = false;
      if (MN == "matlab.add") { cc = "+"; Overflow = true; }
      else if (MN == "matlab.sub") { cc = "-"; Overflow = true; }
      else if (MN == "matlab.emul" || MN == "matlab.matmul") {
        cc = "*"; Overflow = true;
      }
      else if (MN == "matlab.ediv" || MN == "matlab.matdiv") cc = "/";
      else if (MN == "matlab.eq") cc = "==";
      else if (MN == "matlab.ne") cc = "!=";
      else if (MN == "matlab.lt") cc = "<";
      else if (MN == "matlab.le") cc = "<=";
      else if (MN == "matlab.gt") cc = ">";
      else if (MN == "matlab.ge") cc = ">=";
      else if (MN == "matlab.short_or") cc = "or";
      else if (MN == "matlab.short_and") cc = "and";
      if (cc) {
        if (Overflow) return binWrap(cc);
        return bin(cc);
      }
    }
    // `matlab.not` — bool NOT. The op's i1 result coerces from any
    // integer / float operand the same way `if` would in MATLAB
    // (non-zero → true, zero → false). Render as `(not <operand>)`
    // so the Python operand precedence is unambiguous.
    if (MN == "matlab.not" && Op.getNumOperands() == 1 &&
        Op.getNumResults() == 1) {
      Expr = "(not " + dropOuterParens(exprFor(Op.getOperand(0))) + ")";
      return true;
    }
  }
  if (auto S = dyn_cast<arith::SelectOp>(Op)) {
    // Common shape from MATLAB's logical-to-double coercion: select(c,
    // 1.0, 0.0). Fold to `float(c)` instead of the ternary so the
    // emitted source reads like the MATLAB expression that produced it.
    auto isLit = [](Value V, double Want) -> bool {
      if (auto *D = V.getDefiningOp()) {
        FloatAttr FA;
        if (auto C = dyn_cast<arith::ConstantOp>(D))
          FA = dyn_cast<FloatAttr>(C.getValue());
        else if (auto C = dyn_cast<LLVM::ConstantOp>(D))
          FA = dyn_cast<FloatAttr>(C.getValue());
        return FA && FA.getValueAsDouble() == Want;
      }
      return false;
    };
    if (isLit(S.getTrueValue(), 1.0) && isLit(S.getFalseValue(), 0.0)) {
      Expr = "float(" + dropOuterParens(exprFor(S.getCondition())) + ")";
      return true;
    }
    // Python ternary: `a if c else b`.
    Expr = "(" + exprFor(S.getTrueValue()) + " if "
         + dropOuterParens(exprFor(S.getCondition())) + " else "
         + exprFor(S.getFalseValue()) + ")";
    return true;
  }
  if (isa<arith::SIToFPOp, arith::UIToFPOp>(Op)) {
    Expr = "float(" + dropOuterParens(exprFor(Op.getOperand(0))) + ")";
    return true;
  }
  if (isa<arith::FPToSIOp, arith::FPToUIOp>(Op)) {
    Expr = "int(" + dropOuterParens(exprFor(Op.getOperand(0))) + ")";
    return true;
  }
  // extsi/extui/trunci/extf/truncf are no-ops in Python.
  if (isa<arith::ExtSIOp, arith::ExtUIOp, arith::TruncIOp,
          arith::TruncFOp, arith::ExtFOp>(Op)) {
    Expr = exprFor(Op.getOperand(0));
    return true;
  }
  if (auto L = dyn_cast<LLVM::LoadOp>(Op)) {
    if (auto *D = L.getAddr().getDefiningOp()) {
      auto It = DirectSlots.find(D);
      if (It != DirectSlots.end()) { Expr = It->second; return true; }
    }
    // Non-direct slot: the address itself IS the value (typically a
    // GEP expression we materialised as an index). For GEPs, the load
    // resolves to `base[idx]` syntax; the GEP's inline expression
    // already carries that form.
    Expr = exprFor(L.getAddr());
    return true;
  }
  // matlab.load — symmetric with LLVM::LoadOp for slot triplets that
  // survived as unregistered ops (matlab.alloc → matlab.store /
  // matlab.load, all `none`-typed) on HDL-targeted code.
  if (Op.getName().getStringRef() == "matlab.load" &&
      Op.getNumOperands() == 1 && Op.getNumResults() == 1) {
    if (auto *D = Op.getOperand(0).getDefiningOp()) {
      auto It = DirectSlots.find(D);
      if (It != DirectSlots.end()) { Expr = It->second; return true; }
    }
    Expr = exprFor(Op.getOperand(0));
    return true;
  }
  if (auto G = dyn_cast<LLVM::GEPOp>(Op)) {
    // GEP into an array slot: produce `base[idx]` for a single-index
    // GEP. Multi-index GEPs are uncommon in our snapshot (only
    // matrix-literal buffers). Fall back to the first index, summed.
    std::string Base;
    if (auto *D = G.getBase().getDefiningOp()) {
      auto It = ArraySlots.find(D);
      if (It != ArraySlots.end()) Base = It->second;
    }
    if (Base.empty()) Base = exprFor(G.getBase());
    std::string Idx;
    bool First = true;
    for (auto I : G.getIndices()) {
      std::string Term;
      if (auto Vv = llvm::dyn_cast<mlir::Value>(I))
        Term = dropOuterParens(exprFor(Vv));
      else if (auto IA = llvm::dyn_cast<mlir::IntegerAttr>(I))
        Term = std::to_string(IA.getInt());
      else continue;
      if (First) { Idx = Term; First = false; }
      else       { Idx = "(" + Idx + " + " + Term + ")"; }
    }
    if (Idx.empty()) Idx = "0";
    Expr = Base + "[" + Idx + "]";
    return true;
  }
  if (auto C = dyn_cast<func::CallOp>(Op)) {
    // Class-method call: rewrite to `obj.method(args)` / `Class(args)` /
    // operator form when the callee resolves to a class method.
    if (tryRewriteAsClassCall(C.getCallee(), C.getOperands(), Expr))
      return true;
    std::string E = C.getCallee().str() + "(";
    for (unsigned i = 0; i < C.getNumOperands(); ++i) {
      if (i) E += ", ";
      E += dropOuterParens(exprFor(C.getOperand(i)));
    }
    E += ")";
    Expr = E;
    return true;
  }
  if (auto C = dyn_cast<LLVM::CallOp>(Op)) {
    if (!C.getCallee()) return false;
    // Class-field read: obj_get_f64(obj, "X") → obj.X.
    if (tryRewriteObjGet(C, Expr)) return true;
    // Class-method call: prefer `obj.method(...)` / `Class(...)` /
    // operator form when the callee is one of our classdef methods.
    if (tryRewriteAsClassCall(*C.getCallee(), C.getOperands(), Expr))
      return true;
    // Prefer the numpy / Python-operator rewrite for matrix builtins —
    // it reads as the natural translation instead of a runtime trampoline.
    if (tryRewriteAsNumpy(C, Expr)) return true;
    std::string Callee = remapRuntimeCallee(*C.getCallee());
    unsigned LengthIdx = ~0u;
    bool DropLen = false;
    if (C.getCallee()->starts_with("matlab_")) {
      unsigned Idx;
      if (calleeHasDroppableLengthArg(
              C.getCallee()->drop_front(strlen("matlab_")), Idx)) {
        LengthIdx = Idx;
        DropLen = true;
      }
    }
    std::string E = Callee + "(";
    bool First = true;
    for (unsigned i = 0; i < C.getNumOperands(); ++i) {
      if (DropLen && i == LengthIdx) continue;
      if (!First) E += ", ";
      First = false;
      E += dropOuterParens(exprFor(C.getOperand(i)));
    }
    E += ")";
    Expr = E;
    return true;
  }
  return false;
}

// Is V a constant integer with the given value?
static bool isConstInt(mlir::Value V, uint64_t Want) {
  auto *D = V.getDefiningOp();
  if (!D) return false;
  if (auto C = mlir::dyn_cast<mlir::arith::ConstantOp>(D))
    if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(C.getValue()))
      return IA.getValue().getZExtValue() == Want;
  if (auto C = mlir::dyn_cast<mlir::LLVM::ConstantOp>(D))
    if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(C.getValue()))
      return IA.getValue().getZExtValue() == Want;
  return false;
}

bool Emitter::isFlagInversion(mlir::Value V) {
  // True if V reduces to a static `True` once break/continue flags are
  // un-lowered: a constant true, the xor(load flag, true) idiom, or the
  // xor(const-false, const-true) Mem2RegLite leaves when a flag has no
  // store-of-true.
  if (!V.getType().isInteger(1)) return false;
  if (isConstInt(V, 1)) return true;
  auto Xor = V.getDefiningOp<mlir::arith::XOrIOp>();
  if (!Xor) return false;
  if (!Xor.getResult().getType().isInteger(1)) return false;
  mlir::Value Flag;
  if (isConstInt(Xor.getRhs(), 1)) Flag = Xor.getLhs();
  else if (isConstInt(Xor.getLhs(), 1)) Flag = Xor.getRhs();
  else return false;
  if (isConstInt(Flag, 0)) return true;
  auto Load = Flag.getDefiningOp<mlir::LLVM::LoadOp>();
  if (!Load) return false;
  auto *Addr = Load.getAddr().getDefiningOp();
  if (!Addr) return false;
  return BreakFlagSlots.count(Addr) || ContinueFlagSlots.count(Addr);
}

void Emitter::gatherNonFlagConjuncts(mlir::Value V,
    llvm::SmallVectorImpl<mlir::Value> &Out) {
  if (isFlagInversion(V)) return;
  if (auto And = V.getDefiningOp<mlir::arith::AndIOp>()) {
    if (And.getResult().getType().isInteger(1)) {
      gatherNonFlagConjuncts(And.getLhs(), Out);
      gatherNonFlagConjuncts(And.getRhs(), Out);
      return;
    }
  }
  Out.push_back(V);
}

// ---------------------------------------------------------------------------
// For-loop pattern detection (mirrors EmitC.cpp::matchForPattern)
// ---------------------------------------------------------------------------

bool Emitter::tryEvalIntLiteral(mlir::Value V, long long &Out) {
  auto *D = V.getDefiningOp();
  if (!D) return false;
  mlir::Attribute A;
  if (auto C = mlir::dyn_cast<mlir::arith::ConstantOp>(D)) A = C.getValue();
  else if (auto C = mlir::dyn_cast<mlir::LLVM::ConstantOp>(D)) A = C.getValue();
  else return false;
  if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(A)) {
    Out = IA.getInt();
    return true;
  }
  if (auto FA = mlir::dyn_cast<mlir::FloatAttr>(A)) {
    double D = FA.getValueAsDouble();
    long long I = (long long)D;
    if ((double)I == D) { Out = I; return true; }
    return false;
  }
  return false;
}

bool Emitter::forBoundsAreIntLiterals(const ForLoopInfo &Info, long long &Init,
                                       long long &End, long long &Step) {
  return tryEvalIntLiteral(Info.Init, Init) &&
         tryEvalIntLiteral(Info.End, End) &&
         tryEvalIntLiteral(Info.Step, Step);
}

bool Emitter::matchForPattern(mlir::scf::WhileOp W, ForLoopInfo &Info) {
  // Same shape as EmitC: one f64 iter-arg, before-region forwards it
  // unchanged through scf.condition, condition is a single cmpf OLE/OGE,
  // after-region ends with arith.addf iv, step + scf.yield %addf.
  if (W.getInits().size() != 1) return false;
  mlir::Block &Before = W.getBefore().front();
  mlir::Block &After = W.getAfter().front();
  if (Before.getNumArguments() != 1 || After.getNumArguments() != 1)
    return false;
  auto F64 = mlir::Float64Type::get(W.getContext());
  if (Before.getArgument(0).getType() != F64) return false;
  if (After.getArgument(0).getType() != F64) return false;

  for (auto &Inner : Before.getOperations()) {
    if (mlir::isa<mlir::scf::ConditionOp>(Inner)) continue;
    if (InlinedOps.count(&Inner)) continue;
    return false;
  }
  auto Cond = mlir::cast<mlir::scf::ConditionOp>(Before.getTerminator());
  if (Cond.getArgs().size() != 1) return false;
  if (Cond.getArgs()[0] != Before.getArgument(0)) return false;

  llvm::SmallVector<mlir::Value, 2> CondParts;
  gatherNonFlagConjuncts(Cond.getCondition(), CondParts);
  if (CondParts.size() != 1) return false;
  auto Cmp = CondParts[0].getDefiningOp<mlir::arith::CmpFOp>();
  if (!Cmp) return false;
  if (Cmp.getLhs() != Before.getArgument(0)) return false;
  auto Pred = Cmp.getPredicate();
  if (Pred != mlir::arith::CmpFPredicate::OLE &&
      Pred != mlir::arith::CmpFPredicate::OGE) return false;
  Info.End = Cmp.getRhs();
  Info.IsDecreasing = (Pred == mlir::arith::CmpFPredicate::OGE);

  if (After.getOperations().size() < 2) return false;
  auto Yld = mlir::dyn_cast<mlir::scf::YieldOp>(&After.back());
  if (!Yld || Yld.getResults().size() != 1) return false;
  auto *AddRaw = Yld.getResults()[0].getDefiningOp();
  auto Add = mlir::dyn_cast_or_null<mlir::arith::AddFOp>(AddRaw);
  if (!Add) return false;
  if (Add.getLhs() != After.getArgument(0)) return false;
  if (Add->getNextNode() != Yld.getOperation()) return false;

  Info.Init = W.getInits()[0];
  Info.Step = Add.getRhs();
  Info.AddOp = Add.getOperation();
  Info.YieldOp = Yld.getOperation();
  return true;
}

void Emitter::scanForLoopPatterns(mlir::Region &R) {
  // Mirrors EmitC: a slot is fusable when every use of the slot lives
  // inside one of its claimants' after-regions. Two consecutive loops
  // reusing the same `i` slot can both fuse when neither references `i`
  // outside its own body.
  llvm::DenseMap<mlir::Operation *, llvm::SmallVector<mlir::Operation *, 2>>
      SlotClaimants;

  R.walk([&](mlir::scf::WhileOp W) {
    ForLoopInfo Info;
    if (!matchForPattern(W, Info)) return;
    mlir::Block &After = W.getAfter().front();
    mlir::Value Iv = After.getArgument(0);
    for (auto &Op : After.getOperations()) {
      if (&Op == Info.AddOp || &Op == Info.YieldOp) break;
      auto Store = mlir::dyn_cast<mlir::LLVM::StoreOp>(Op);
      if (!Store) continue;
      if (Store.getValue() != Iv) continue;
      auto Alloca = Store.getAddr().getDefiningOp<mlir::LLVM::AllocaOp>();
      if (!Alloca) break;
      auto NA = Alloca->getAttrOfType<mlir::StringAttr>("matlab.name");
      if (!NA) break;
      Info.BindStore = Store.getOperation();
      Info.SlotAlloca = Alloca.getOperation();
      SlotClaimants[Info.SlotAlloca].push_back(W.getOperation());
      break;
    }
    ForPatterns[W.getOperation()] = std::move(Info);
  });

  llvm::DenseMap<mlir::Operation *, bool> SlotFusable;
  for (auto &Entry : SlotClaimants) {
    mlir::Operation *Slot = Entry.first;
    auto &Claimants = Entry.second;
    bool OK = true;
    for (auto &Use : Slot->getUses()) {
      mlir::Operation *User = Use.getOwner();
      bool InsideAny = false;
      for (mlir::Operation *W : Claimants) {
        mlir::Region *Loop = &W->getRegion(1);
        mlir::Region *P = User->getParentRegion();
        while (P) {
          if (P == Loop) { InsideAny = true; break; }
          P = P->getParentRegion();
        }
        if (InsideAny) break;
      }
      if (!InsideAny) { OK = false; break; }
    }
    SlotFusable[Slot] = OK;
  }

  for (auto &KV : ForPatterns) {
    ForLoopInfo &Info = KV.second;
    SuppressedOps.insert(Info.AddOp);
    SuppressedOps.insert(Info.YieldOp);

    bool Fuse = Info.SlotAlloca && SlotFusable.lookup(Info.SlotAlloca);
    if (Fuse) {
      Info.FuseSlot = true;
      auto It = FusedForSlotName.find(Info.SlotAlloca);
      if (It == FusedForSlotName.end()) {
        auto NA = Info.SlotAlloca->getAttrOfType<mlir::StringAttr>(
            "matlab.name");
        std::string N = uniqueName(NA.getValue());
        FusedForSlotName[Info.SlotAlloca] = N;
        Info.IvName = N;
      } else {
        Info.IvName = It->second;
      }
      FusedForSlots.insert(Info.SlotAlloca);
      SuppressedOps.insert(Info.BindStore);
    } else {
      Info.FuseSlot = false;
      Info.IvName = freshName();
    }
  }
}

// ---------------------------------------------------------------------------
// Constant condition folding
// ---------------------------------------------------------------------------

int Emitter::evalConstCond(mlir::Value V) {
  // Fold `arith.cmpi/cmpf C1, C2` and the boolean constants directly.
  // The polymorphic-dispatch layer bakes nargin into a constant comparison
  // (`if 2 == 2:`) which we want to drop entirely.
  if (auto *D = V.getDefiningOp()) {
    if (auto C = mlir::dyn_cast<mlir::arith::ConstantOp>(D)) {
      if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(C.getValue())) {
        auto T = mlir::dyn_cast<mlir::IntegerType>(IA.getType());
        if (T && T.getWidth() == 1) return (IA.getInt() & 1) ? 1 : 0;
      }
    }
    if (auto C = mlir::dyn_cast<mlir::LLVM::ConstantOp>(D)) {
      if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(C.getValue())) {
        auto T = mlir::dyn_cast<mlir::IntegerType>(IA.getType());
        if (T && T.getWidth() == 1) return (IA.getInt() & 1) ? 1 : 0;
      }
    }
    if (auto Ci = mlir::dyn_cast<mlir::arith::CmpIOp>(D)) {
      long long L, R;
      if (tryEvalIntLiteral(Ci.getLhs(), L) &&
          tryEvalIntLiteral(Ci.getRhs(), R)) {
        switch (Ci.getPredicate()) {
          case mlir::arith::CmpIPredicate::eq:  return L == R ? 1 : 0;
          case mlir::arith::CmpIPredicate::ne:  return L != R ? 1 : 0;
          case mlir::arith::CmpIPredicate::slt:
          case mlir::arith::CmpIPredicate::ult: return L <  R ? 1 : 0;
          case mlir::arith::CmpIPredicate::sle:
          case mlir::arith::CmpIPredicate::ule: return L <= R ? 1 : 0;
          case mlir::arith::CmpIPredicate::sgt:
          case mlir::arith::CmpIPredicate::ugt: return L >  R ? 1 : 0;
          case mlir::arith::CmpIPredicate::sge:
          case mlir::arith::CmpIPredicate::uge: return L >= R ? 1 : 0;
        }
      }
    }
    if (auto Cf = mlir::dyn_cast<mlir::arith::CmpFOp>(D)) {
      long long L, R;
      if (tryEvalIntLiteral(Cf.getLhs(), L) &&
          tryEvalIntLiteral(Cf.getRhs(), R)) {
        switch (Cf.getPredicate()) {
          case mlir::arith::CmpFPredicate::OEQ:
          case mlir::arith::CmpFPredicate::UEQ: return L == R ? 1 : 0;
          case mlir::arith::CmpFPredicate::ONE:
          case mlir::arith::CmpFPredicate::UNE: return L != R ? 1 : 0;
          case mlir::arith::CmpFPredicate::OLT:
          case mlir::arith::CmpFPredicate::ULT: return L <  R ? 1 : 0;
          case mlir::arith::CmpFPredicate::OLE:
          case mlir::arith::CmpFPredicate::ULE: return L <= R ? 1 : 0;
          case mlir::arith::CmpFPredicate::OGT:
          case mlir::arith::CmpFPredicate::UGT: return L >  R ? 1 : 0;
          case mlir::arith::CmpFPredicate::OGE:
          case mlir::arith::CmpFPredicate::UGE: return L >= R ? 1 : 0;
          default: return -1;
        }
      }
    }
  }
  return -1;
}

// ---------------------------------------------------------------------------
// Runtime call ABI: which helpers carry a droppable string-length operand?
// ---------------------------------------------------------------------------

bool Emitter::calleeHasDroppableLengthArg(llvm::StringRef Suffix,
                                          unsigned &LengthArgIdx) {
  // The C ABI passes (str_ptr, str_len) for any helper that takes a
  // user-string. Python strings carry their length, so the length operand
  // is dead weight — drop it. The runtime keeps an optional `n=None`
  // parameter for back-compat with hand-written callers.
  // Raw-string helpers carry an explicit (ptr, i64-length) tail. The
  // matlab_string variants used by file I/O wrap the buffer in a
  // descriptor and don't take a separate length, so they're absent
  // from this list.
  if (Suffix == "disp_str")      { LengthArgIdx = 1; return true; }
  if (Suffix == "fprintf_str")   { LengthArgIdx = 1; return true; }
  if (Suffix == "fprintf_f64")   { LengthArgIdx = 1; return true; }
  if (Suffix == "fprintf_f64_2") { LengthArgIdx = 1; return true; }
  if (Suffix == "fprintf_f64_3") { LengthArgIdx = 1; return true; }
  if (Suffix == "fprintf_f64_4") { LengthArgIdx = 1; return true; }
  if (Suffix == "input_num")     { LengthArgIdx = 1; return true; }
  // Object field accessors carry the (name_ptr, name_len) pair as their
  // 2nd / 3rd operands; the Python runtime ignores name_len.
  if (Suffix == "obj_get_f64")   { LengthArgIdx = 2; return true; }
  if (Suffix == "obj_set_f64")   { LengthArgIdx = 2; return true; }
  return false;
}

// ---------------------------------------------------------------------------
// Numpy rewrite — matrix calls collapse to inline numpy expressions
// ---------------------------------------------------------------------------
//
// The runtime shim wraps everything in `_m(...)` to coerce into ndarrays
// before falling through to numpy under the hood. For programs whose
// only matrix consumers are themselves rewritten (or `rt.disp_mat` /
// `rt.slice*` / etc., which all accept ndarrays directly), we can skip
// the round-trip and emit the numpy expression at the call site. The
// generated source then reads as the natural numpy translation:
//
//     A @ B            instead of  rt.matmul_mm(A, B)
//     A * B            instead of  rt.emul_mm(A, B)
//     A.T              instead of  rt.transpose(A)
//     np.linalg.inv(A) instead of  rt.inv(A)
//     np.zeros((3, 3)) instead of  rt.zeros(3.0, 3.0)
//
// We deliberately keep MATLAB-semantics helpers (slice2, sum / mean
// with column-major reductions, disp_mat formatting, etc.) on the
// runtime path — those don't have a one-line numpy equivalent.
bool Emitter::tryRewriteAsNumpy(mlir::LLVM::CallOp C, std::string &Out) {
  if (!C.getCallee()) return false;
  llvm::StringRef Full = *C.getCallee();
  if (!Full.starts_with("matlab_")) return false;
  llvm::StringRef Suf = Full.drop_front(strlen("matlab_"));

  auto opnd = [&](unsigned i) {
    return dropOuterParens(this->exprFor(C.getOperand(i)));
  };
  auto wrapped = [&](unsigned i) {
    return this->exprFor(C.getOperand(i));
  };
  // Format an integer-typed dimension argument: a constant integer
  // literal becomes a bare `3`; anything else is wrapped in `int(...)`
  // so it can index numpy shape tuples without a TypeError.
  auto fmtIntDim = [&](mlir::Value V) -> std::string {
    long long I;
    if (tryEvalIntLiteral(V, I)) return std::to_string(I);
    return "int(" + dropOuterParens(this->exprFor(V)) + ")";
  };
  auto bin = [&](const char *Op) {
    Out = "(" + wrapped(0) + " " + Op + " " + wrapped(1) + ")";
    return true;
  };

  // --- Element-wise / matrix arithmetic -----------------------------
  if (C.getNumOperands() == 2) {
    if (Suf == "matmul_mm") return bin("@");
    if (Suf == "add_mm" || Suf == "add_ms" || Suf == "add_sm") return bin("+");
    if (Suf == "sub_mm" || Suf == "sub_ms" || Suf == "sub_sm") return bin("-");
    if (Suf == "emul_mm" || Suf == "emul_ms" || Suf == "emul_sm") return bin("*");
    if (Suf == "ediv_mm" || Suf == "ediv_ms" || Suf == "ediv_sm") return bin("/");
  }

  // --- Construction --------------------------------------------------
  if (Suf == "mat_from_buf" && C.getNumOperands() == 3) {
    Out = "np.array(" + opnd(0) + ").reshape(" +
          fmtIntDim(C.getOperand(1)) + ", " +
          fmtIntDim(C.getOperand(2)) + ")";
    return true;
  }
  if (Suf == "mat_from_scalar" && C.getNumOperands() == 1) {
    Out = "np.array([[" + opnd(0) + "]])";
    return true;
  }
  if (Suf == "zeros") {
    if (C.getNumOperands() == 1) {
      std::string D = fmtIntDim(C.getOperand(0));
      Out = "np.zeros((" + D + ", " + D + "))";  // MATLAB zeros(n) is n×n.
      return true;
    }
    if (C.getNumOperands() == 2) {
      Out = "np.zeros((" + fmtIntDim(C.getOperand(0)) + ", " +
            fmtIntDim(C.getOperand(1)) + "))";
      return true;
    }
  }
  if (Suf == "ones") {
    if (C.getNumOperands() == 1) {
      std::string D = fmtIntDim(C.getOperand(0));
      Out = "np.ones((" + D + ", " + D + "))";
      return true;
    }
    if (C.getNumOperands() == 2) {
      Out = "np.ones((" + fmtIntDim(C.getOperand(0)) + ", " +
            fmtIntDim(C.getOperand(1)) + "))";
      return true;
    }
  }
  if (Suf == "eye") {
    if (C.getNumOperands() == 1) {
      Out = "np.eye(" + fmtIntDim(C.getOperand(0)) + ")";
      return true;
    }
    if (C.getNumOperands() == 2) {
      Out = "np.eye(" + fmtIntDim(C.getOperand(0)) + ", " +
            fmtIntDim(C.getOperand(1)) + ")";
      return true;
    }
  }

  // --- Linear algebra ------------------------------------------------
  if (C.getNumOperands() == 1) {
    if (Suf == "transpose") {
      Out = wrapped(0) + ".T";
      return true;
    }
    if (Suf == "inv")    { Out = "np.linalg.inv("  + opnd(0) + ")"; return true; }
    if (Suf == "det")    { Out = "np.linalg.det("  + opnd(0) + ")"; return true; }
    if (Suf == "norm")   { Out = "np.linalg.norm(" + opnd(0) + ")"; return true; }
    if (Suf == "trace")  { Out = "np.trace("       + opnd(0) + ")"; return true; }
  }
  if (Suf == "mldivide_mm" && C.getNumOperands() == 2) {
    Out = "np.linalg.solve(" + opnd(0) + ", " + opnd(1) + ")";
    return true;
  }

  // --- Element-wise math (matrix variants) --------------------------
  static constexpr struct { const char *Suf; const char *Np; } UnaryMatNp[] = {
    {"sqrt_m", "np.sqrt"},   {"exp_m", "np.exp"},     {"log_m", "np.log"},
    {"log2_m", "np.log2"},   {"log10_m", "np.log10"},
    {"sin_m",  "np.sin"},    {"cos_m", "np.cos"},     {"tan_m", "np.tan"},
    {"asin_m", "np.arcsin"}, {"acos_m", "np.arccos"}, {"atan_m", "np.arctan"},
    {"sinh_m", "np.sinh"},   {"cosh_m", "np.cosh"},   {"tanh_m", "np.tanh"},
    {"abs_m",  "np.abs"},    {"sign_m", "np.sign"},
    {"floor_m","np.floor"},  {"ceil_m", "np.ceil"},   {"round_m", "np.round"},
  };
  for (auto &E : UnaryMatNp) {
    if (Suf == E.Suf && C.getNumOperands() == 1) {
      Out = std::string(E.Np) + "(" + opnd(0) + ")";
      return true;
    }
  }
  return false;
}

// ---------------------------------------------------------------------------
// Class field access — `obj_get_f64(obj, "X")` → `obj.X`
// ---------------------------------------------------------------------------

// Recover the bare field name from the second operand of an obj_*_f64 call.
// Returns the identifier text on success (with surrounding quotes stripped),
// or std::nullopt when the operand isn't a string-literal addressof or the
// literal isn't a valid Python identifier.
static std::optional<std::string> getFieldNameLit(
    mlir::Value V, const llvm::StringMap<std::string> &StringGlobalLits) {
  auto *D = V.getDefiningOp();
  auto A = mlir::dyn_cast_or_null<mlir::LLVM::AddressOfOp>(D);
  if (!A) return std::nullopt;
  auto It = StringGlobalLits.find(A.getGlobalName());
  if (It == StringGlobalLits.end()) return std::nullopt;
  llvm::StringRef Lit = It->second;
  if (Lit.size() < 2 || Lit.front() != '"' || Lit.back() != '"')
    return std::nullopt;
  std::string Name = Lit.substr(1, Lit.size() - 2).str();
  if (Name.empty()) return std::nullopt;
  // Must be a plain Python identifier — anything fancy stays on the
  // runtime path so we don't emit broken `obj.123` or `obj.with-dash`.
  unsigned char C0 = (unsigned char)Name[0];
  if (!(std::isalpha(C0) || C0 == '_')) return std::nullopt;
  for (char C : Name)
    if (!std::isalnum((unsigned char)C) && C != '_') return std::nullopt;
  // Don't shadow a Python keyword.
  static constexpr const char *Keywords[] = {
    "False","None","True","and","as","assert","async","await","break",
    "class","continue","def","del","elif","else","except","finally","for",
    "from","global","if","import","in","is","lambda","nonlocal","not","or",
    "pass","raise","return","try","while","with","yield",
  };
  for (auto *KW : Keywords) if (Name == KW) return std::nullopt;
  return Name;
}

bool Emitter::tryRewriteObjGet(mlir::LLVM::CallOp C, std::string &Out) {
  if (!C.getCallee()) return false;
  if (*C.getCallee() != "matlab_obj_get_f64") return false;
  if (C.getNumOperands() < 2) return false;
  auto Field = getFieldNameLit(C.getOperand(1), StringGlobalLits);
  if (!Field) return false;
  Out = exprFor(C.getOperand(0)) + "." + *Field;
  return true;
}

// ---------------------------------------------------------------------------
// Classdef collection + call-site rewrite
// ---------------------------------------------------------------------------

// Map a MATLAB operator method name to the matching Python dunder + the
// in-source operator spelling (used at call sites). Returns true on
// success and writes the dunder name (e.g. `__eq__`) and the operator
// (`==`). Only a curated subset is mapped here — unmapped names stay as
// regular methods so the generated source remains valid even when the
// classdef defines a one-off.
static bool mapOperatorMethod(llvm::StringRef Name, std::string &Dunder,
                              std::string &Op) {
  if (Name == "eq")     { Dunder = "__eq__"; Op = "=="; return true; }
  if (Name == "ne")     { Dunder = "__ne__"; Op = "!="; return true; }
  if (Name == "lt")     { Dunder = "__lt__"; Op = "<";  return true; }
  if (Name == "le")     { Dunder = "__le__"; Op = "<="; return true; }
  if (Name == "gt")     { Dunder = "__gt__"; Op = ">";  return true; }
  if (Name == "ge")     { Dunder = "__ge__"; Op = ">="; return true; }
  if (Name == "plus")   { Dunder = "__add__"; Op = "+"; return true; }
  if (Name == "minus")  { Dunder = "__sub__"; Op = "-"; return true; }
  if (Name == "mtimes" ||
      Name == "times")  { Dunder = "__mul__"; Op = "*"; return true; }
  if (Name == "mrdivide" ||
      Name == "rdivide"){ Dunder = "__truediv__"; Op = "/"; return true; }
  if (Name == "uminus") { Dunder = "__neg__"; Op = "-"; return true; }
  return false;
}

void Emitter::collectClasses(mlir::ModuleOp M) {
  for (auto &Op : M.getBody()->getOperations()) {
    auto F = mlir::dyn_cast<mlir::func::FuncOp>(Op);
    if (!F) continue;
    if (F.getBody().empty()) continue;
    auto CN = F->getAttrOfType<mlir::StringAttr>("matlab.class_name");
    if (!CN) continue;

    ClassMethodInfo CMI;
    CMI.Func = F;
    CMI.ClassName = CN.getValue().str();

    auto Kind = F->getAttrOfType<mlir::StringAttr>("matlab.method_kind");
    auto MN   = F->getAttrOfType<mlir::StringAttr>("matlab.method_name");
    llvm::StringRef MName = MN ? MN.getValue() : llvm::StringRef();

    if (Kind && Kind.getValue() == "ctor") {
      CMI.Kind = ClassMethodInfo::Ctor;
      CMI.EmitName = "__init__";
    } else if (Kind && Kind.getValue() == "static") {
      CMI.Kind = ClassMethodInfo::Static;
      CMI.EmitName = MName.empty() ? "" : MName.str();
      if (CMI.EmitName.empty()) continue;
    } else if (MName.starts_with("get.")) {
      CMI.Kind = ClassMethodInfo::Get;
      CMI.EmitName = MName.drop_front(4).str();
    } else if (std::string D, O; mapOperatorMethod(MName, D, O)) {
      CMI.Kind = ClassMethodInfo::Operator;
      CMI.EmitName = D;
      CMI.OpSpelling = O;
    } else if (!MName.empty()) {
      CMI.Kind = ClassMethodInfo::Method;
      CMI.EmitName = MName.str();
    } else {
      // No method_name attribute — skip (we can't classify it).
      continue;
    }

    auto &CD = Classes[CMI.ClassName];
    if (auto Sup = F->getAttrOfType<mlir::StringAttr>("matlab.class_super"))
      if (CD.Super.empty()) CD.Super = Sup.getValue().str();
    CD.Methods.push_back(CMI);
    CalleeIndex[F.getSymName()] = CMI;
  }
}

bool Emitter::tryRewriteAsClassCall(llvm::StringRef Callee,
                                     mlir::ValueRange Operands,
                                     std::string &Out) {
  auto It = CalleeIndex.find(Callee);
  if (It == CalleeIndex.end()) return false;
  const ClassMethodInfo &CMI = It->second;
  switch (CMI.Kind) {
    case ClassMethodInfo::Ctor: {
      std::string E = CMI.ClassName + "(";
      for (unsigned i = 0; i < Operands.size(); ++i) {
        if (i) E += ", ";
        E += dropOuterParens(this->stmtExpr(Operands[i]));
      }
      E += ")";
      Out = E;
      return true;
    }
    case ClassMethodInfo::Get: {
      if (Operands.size() != 1) return false;
      Out = exprFor(Operands[0]) + "." + CMI.EmitName;
      return true;
    }
    case ClassMethodInfo::Operator: {
      if (Operands.size() != 2) return false;
      Out = "(" + exprFor(Operands[0]) + " " + CMI.OpSpelling + " "
          + exprFor(Operands[1]) + ")";
      return true;
    }
    case ClassMethodInfo::Method: {
      if (Operands.empty()) return false;
      std::string E = exprFor(Operands[0]) + "." + CMI.EmitName + "(";
      for (unsigned i = 1; i < Operands.size(); ++i) {
        if (i > 1) E += ", ";
        E += dropOuterParens(this->stmtExpr(Operands[i]));
      }
      E += ")";
      Out = E;
      return true;
    }
    case ClassMethodInfo::Static: {
      // No self — emit `ClassName.method(args)` per Python convention.
      std::string E = CMI.ClassName + "." + CMI.EmitName + "(";
      for (unsigned i = 0; i < Operands.size(); ++i) {
        if (i) E += ", ";
        E += dropOuterParens(this->stmtExpr(Operands[i]));
      }
      E += ")";
      Out = E;
      return true;
    }
  }
  return false;
}

bool Emitter::tryRewriteObjSet(mlir::LLVM::CallOp C, std::string &Out) {
  if (!C.getCallee()) return false;
  if (*C.getCallee() != "matlab_obj_set_f64") return false;
  // The C ABI is (obj, name_ptr, name_len, value); the length is
  // dropped at the emit layer for callees in calleeHasDroppableLengthArg,
  // so the value is always at operand index 3 here.
  if (C.getNumOperands() < 4) return false;
  auto Field = getFieldNameLit(C.getOperand(1), StringGlobalLits);
  if (!Field) return false;
  Out = dropOuterParens(exprFor(C.getOperand(0))) + "." + *Field +
        " = " + dropOuterParens(stmtExpr(C.getOperand(3)));
  return true;
}

void Emitter::scanBreakContinueFlags(mlir::Region &R) {
  // Phase 1: identify the break / continue flag slots.
  R.walk([&](mlir::LLVM::AllocaOp A) {
    auto NA = A->getAttrOfType<mlir::StringAttr>("matlab.name");
    if (!NA) return;
    if (NA.getValue() == "__did_break") {
      BreakFlagSlots.insert(A.getOperation());
      SuppressedOps.insert(A.getOperation());
    } else if (NA.getValue() == "__did_continue") {
      ContinueFlagSlots.insert(A.getOperation());
      SuppressedOps.insert(A.getOperation());
    }
  });

  if (BreakFlagSlots.empty() && ContinueFlagSlots.empty()) return;

  // Phase 2: any const-false store into a flag slot is the pre-loop
  // initialisation or end-of-iteration continue reset — elided.
  R.walk([&](mlir::LLVM::StoreOp S) {
    auto *Addr = S.getAddr().getDefiningOp();
    if (!Addr) return;
    bool IsFlag = BreakFlagSlots.count(Addr) || ContinueFlagSlots.count(Addr);
    if (!IsFlag) return;
    if (isConstInt(S.getValue(), 0)) {
      SuppressedOps.insert(S.getOperation());
    }
  });

  // Phase 3: classify scf.if ops.
  //  - `scf.if cond { flag := true }` → `if cond: break/continue`.
  //  - `scf.if (!flag [& !flag]) { ... }` → emit body inline.
  R.walk([&](mlir::scf::IfOp If) {
    if (!If.getElseRegion().empty()) {
      bool ElseTrivial = true;
      for (auto &Blk : If.getElseRegion().getBlocks()) {
        for (auto &Inner : Blk.getOperations()) {
          if (mlir::isa<mlir::scf::YieldOp>(Inner)) continue;
          ElseTrivial = false;
          break;
        }
        if (!ElseTrivial) break;
      }
      if (!ElseTrivial) return;
    }
    if (If.getNumResults() != 0) return;

    // Single store-of-true into a flag slot in the then-region.
    {
      mlir::LLVM::StoreOp FlagStore;
      bool OtherRealOps = false;
      for (auto &Blk : If.getThenRegion().getBlocks()) {
        for (auto &Inner : Blk.getOperations()) {
          if (mlir::isa<mlir::scf::YieldOp>(Inner)) continue;
          if (auto S = mlir::dyn_cast<mlir::LLVM::StoreOp>(Inner)) {
            auto *Addr = S.getAddr().getDefiningOp();
            bool Flag = Addr && (BreakFlagSlots.count(Addr) ||
                                 ContinueFlagSlots.count(Addr));
            if (Flag && isConstInt(S.getValue(), 1) && !FlagStore) {
              FlagStore = S;
              continue;
            }
          }
          if (mlir::isa<mlir::arith::ConstantOp, mlir::LLVM::ConstantOp>(Inner))
            continue;
          OtherRealOps = true;
        }
      }
      if (FlagStore && !OtherRealOps) {
        auto *Addr = FlagStore.getAddr().getDefiningOp();
        FlagIfKind[If.getOperation()] =
            BreakFlagSlots.count(Addr) ? "break" : "continue";
        SuppressedOps.insert(FlagStore.getOperation());
        return;
      }
    }

    // Pure flag-guard: every conjunct in the condition reduces to true.
    llvm::SmallVector<mlir::Value, 2> Kept;
    gatherNonFlagConjuncts(If.getCondition(), Kept);
    if (Kept.empty())
      InlinedIfs.insert(If.getOperation());
  });
}

void Emitter::computeInlines(mlir::Region &R) {
  for (auto &B : R.getBlocks()) {
    for (auto &Op : B.getOperations()) {
      if (canInline(Op)) InlinedOps.insert(&Op);
      for (auto &SubR : Op.getRegions()) computeInlines(SubR);
    }
  }
}

// ---------------------------------------------------------------------------
// Comment / blank-line propagation from the MATLAB source
// ---------------------------------------------------------------------------

namespace {
enum class LineKind { Blank, Comment, Code };
struct LineInfo { LineKind Kind; std::string_view Body; };
LineInfo classifyLine(std::string_view Text) {
  size_t I = 0;
  while (I < Text.size() && (Text[I] == ' ' || Text[I] == '\t')) ++I;
  if (I == Text.size()) return {LineKind::Blank, {}};
  if (Text[I] != '%')   return {LineKind::Code, {}};
  ++I;
  if (I < Text.size() && Text[I] == ' ') ++I;
  return {LineKind::Comment, Text.substr(I)};
}
} // namespace

bool Emitter::emitLeadingComments(llvm::StringRef FullPath, int AfterLine,
                                  int Line, int Indent, bool) {
  if (!SM || FullPath.empty() || Line <= 0) return false;
  matlab::FileID F = SM->findFileByName(std::string_view(FullPath));
  if (F == 0) return false;

  // If we pre-emitted the script's leading comment block at module-top,
  // skip those lines so they aren't re-emitted when @main's first op
  // triggers a leading-comment scan.
  std::string FileLeaf = FullPath.str();
  if (auto Slash = FileLeaf.find_last_of("/\\"); Slash != std::string::npos)
    FileLeaf = FileLeaf.substr(Slash + 1);
  if (PreEmittedCommentLine > 0 && FileLeaf == PreEmittedCommentFile)
    AfterLine = std::max(AfterLine, PreEmittedCommentLine);

  int Start = Line;
  for (int L = Line - 1; L > AfterLine; --L) {
    auto Info = classifyLine(SM->getLineText(F, (uint32_t)L));
    if (Info.Kind == LineKind::Code) break;
    Start = L;
  }
  if (Start == Line) return false;

  bool EmittedAny = false;
  bool CanEmitBlank = !AtBlockStart;
  bool LastWasBlank = false;
  for (int L = Start; L < Line; ++L) {
    auto Info = classifyLine(SM->getLineText(F, (uint32_t)L));
    if (Info.Kind == LineKind::Blank) {
      if (!CanEmitBlank || LastWasBlank) continue;
      OS << "\n";
      LastWasBlank = true;
      EmittedAny = true;
      continue;
    }
    indent(Indent);
    OS << "# " << Info.Body << "\n";
    CanEmitBlank = true;
    LastWasBlank = false;
    EmittedAny = true;
  }
  return EmittedAny;
}

void Emitter::advanceTo(mlir::Location L, int Indent) {
  mlir::FileLineColLoc FL;
  if ((FL = mlir::dyn_cast<mlir::FileLineColLoc>(L))) {
  } else if (auto NL = mlir::dyn_cast<mlir::NameLoc>(L)) {
    FL = mlir::dyn_cast<mlir::FileLineColLoc>(NL.getChildLoc());
  } else if (auto FuL = mlir::dyn_cast<mlir::FusedLoc>(L)) {
    for (auto Sub : FuL.getLocations())
      if ((FL = mlir::dyn_cast<mlir::FileLineColLoc>(Sub))) break;
  }
  if (!FL) return;
  std::string FullPath = FL.getFilename().str();
  int Line = static_cast<int>(FL.getLine());
  if (FullPath.empty() || Line <= 0) return;
  std::string File = FullPath;
  if (auto Slash = File.find_last_of("/\\"); Slash != std::string::npos)
    File = File.substr(Slash + 1);
  if (File == LastLineFile && Line == LastLineNum) return;

  bool SameFile = !LastLineFile.empty() && File == LastLineFile;
  bool ForwardJump = SameFile && Line > LastLineNum;

  bool ScanEmitted = false;
  if (ForwardJump) {
    ScanEmitted = emitLeadingComments(FullPath, LastLineNum, Line, Indent);
  } else if (LastLineFile.empty()) {
    ScanEmitted = emitLeadingComments(FullPath, Line - 64, Line, Indent,
                                      /*FunctionHeader=*/true);
  }
  if (!ScanEmitted && !AtBlockStart && ForwardJump &&
      Line > LastLineNum + 1) {
    OS << "\n";
  }
  AtBlockStart = false;
  LastLineFile = File;
  LastLineNum = Line;
  (void)NoLine;  // Reserved for future use; Python has no #line directive.
}

// ---------------------------------------------------------------------------
// Globals (string constants from LowerIO via llvm.mlir.global)
// ---------------------------------------------------------------------------

std::string Emitter::constStr(mlir::LLVM::GlobalOp G) {
  auto Val = G.getValueAttr();
  if (!Val) return "";
  if (auto S = mlir::dyn_cast<mlir::StringAttr>(Val))
    return S.getValue().str();
  return "";
}

// Build a Python double-quoted string literal for `Raw` (with escapes).
static std::string buildPyStringLit(llvm::StringRef Raw) {
  std::string Out;
  Out.reserve(Raw.size() + 2);
  Out += '"';
  for (unsigned char C : Raw) {
    switch (C) {
      case '\\': Out += "\\\\"; break;
      case '"':  Out += "\\\""; break;
      case '\n': Out += "\\n"; break;
      case '\t': Out += "\\t"; break;
      case '\r': Out += "\\r"; break;
      default:
        if (C >= 0x20 && C < 0x7F) Out += (char)C;
        else {
          char Buf[8];
          snprintf(Buf, sizeof(Buf), "\\x%02x", (unsigned)C);
          Out += Buf;
        }
        break;
    }
  }
  Out += '"';
  return Out;
}

void Emitter::emitGlobal(mlir::LLVM::GlobalOp G) {
  std::string N = G.getSymName().str();
  GlobalStrs[G.getOperation()] = N;
  std::string Raw = constStr(G);
  UsedNames.insert(N);
  OS << N << " = ";
  OS << '"';
  for (unsigned char C : Raw) {
    switch (C) {
      case '\\': OS << "\\\\"; break;
      case '"':  OS << "\\\""; break;
      case '\n': OS << "\\n"; break;
      case '\t': OS << "\\t"; break;
      case '\r': OS << "\\r"; break;
      default:
        if (C >= 0x20 && C < 0x7F) OS << (char)C;
        else {
          char Buf[8];
          snprintf(Buf, sizeof(Buf), "\\x%02x", (unsigned)C);
          OS << Buf;
        }
        break;
    }
  }
  OS << "\"\n";
}

// ---------------------------------------------------------------------------
// Prolog
// ---------------------------------------------------------------------------

void Emitter::emitProlog() {
  // The header line always goes here; the conditional `import` lines
  // are added in the standalone `emitPython()` after we know what the
  // body actually references. Nothing else should depend on the prolog
  // sitting at a fixed offset.
  OS << "# Generated by matlabc -emit-python. Do not edit.\n";
}

void Emitter::precomputeModuleProperties(mlir::ModuleOp) {
  // Python emitter has no per-module toggles today.
}

// ---------------------------------------------------------------------------
// Driver
// ---------------------------------------------------------------------------

bool Emitter::run(mlir::ModuleOp M) {
  if (mlir::failed(mlir::verify(M))) {
    fail("MLIR verification failed before Python emission");
    return false;
  }
  precomputeModuleProperties(M);
  emitProlog();

  // Multi-return: Python natively supports `return a, b` and `a, b = f(...)`,
  // no module-level prep needed. The check is removed; the return-op and
  // call-site emit handle N>1 results explicitly.

  // Pass 1: register every string global's Python literal so AddressOf
  // inlining can fold it directly. The top-of-file `__matlab_strN = "..."`
  // declarations the C/C++ backend emits are unnecessary in Python — the
  // literal lives at the use site instead, which reads more naturally.
  for (auto &Op : M.getBody()->getOperations()) {
    if (auto G = mlir::dyn_cast<mlir::LLVM::GlobalOp>(Op)) {
      auto Val = G.getValueAttr();
      if (mlir::dyn_cast_or_null<mlir::StringAttr>(Val)) {
        StringGlobalLits[G.getSymName()] = buildPyStringLit(constStr(G));
        UsedNames.insert(G.getSymName().str());
      }
    }
  }

  // Pass 2: collect MATLAB classdefs. Functions tagged with
  // `matlab.class_name` are routed into a class block (emitted in
  // pass 4) instead of being emitted as flat module-level defs.
  collectClasses(M);

  // Pass 3: reserve the symbol of every defined function so locals don't
  // shadow them, and emit bodies. `@main` is emitted last so top-level
  // script code references already-defined functions.
  mlir::func::FuncOp MainFn;
  for (auto &Op : M.getBody()->getOperations()) {
    if (auto F = mlir::dyn_cast<mlir::func::FuncOp>(Op)) {
      if (F.getBody().empty()) continue;
      UsedNames.insert(F.getSymName().str());
      if (F.getSymName() == "main") { MainFn = F; continue; }
    } else if (auto F = mlir::dyn_cast<mlir::LLVM::LLVMFuncOp>(Op)) {
      if (F.getBody().empty()) continue;
      UsedNames.insert(F.getSymName().str());
    }
  }
  // Reserve the bare class names too so a free-function's local can't
  // accidentally shadow a class type used at a constructor call site.
  for (auto &KV : Classes) UsedNames.insert(KV.first().str());

  // Hoist the script's top-of-file `% ...` comment block to module-top
  // so the file's documentation stays at the top of the generated
  // Python instead of being shoved between the function definitions
  // and the script body. We pre-emit it here and remember the highest
  // line number we covered so emitLeadingComments doesn't re-emit
  // those same lines when @main's first op fires advanceTo().
  if (MainFn && SM) {
    auto extract = [](mlir::Location L) -> mlir::FileLineColLoc {
      if (auto FL = mlir::dyn_cast<mlir::FileLineColLoc>(L)) return FL;
      if (auto NL = mlir::dyn_cast<mlir::NameLoc>(L))
        if (auto FL = mlir::dyn_cast<mlir::FileLineColLoc>(NL.getChildLoc()))
          return FL;
      if (auto FuL = mlir::dyn_cast<mlir::FusedLoc>(L)) {
        for (auto Sub : FuL.getLocations())
          if (auto FL = mlir::dyn_cast<mlir::FileLineColLoc>(Sub))
            return FL;
      }
      return {};
    };
    // Find the smallest line number among MainFn's body ops (any op
    // with a real location) to serve as "where the script body
    // starts." First-visited isn't reliable — constants and slot
    // allocas sometimes carry the location of their last use.
    std::string FullPath;
    int MinLine = 0;
    MainFn.getBody().walk([&](mlir::Operation *Op) {
      if (auto FL = extract(Op->getLoc())) {
        int L = (int)FL.getLine();
        if (L > 0 && (MinLine == 0 || L < MinLine)) {
          MinLine = L;
          FullPath = FL.getFilename().str();
        }
      }
    });
    if (MinLine > 0 && !FullPath.empty()) {
      int Line = MinLine;
      std::string FileLeaf = FullPath;
      if (auto Slash = FileLeaf.find_last_of("/\\");
          Slash != std::string::npos)
        FileLeaf = FileLeaf.substr(Slash + 1);
      matlab::FileID F = SM->findFileByName(std::string_view(FullPath));
      if (F != 0 && Line > 1) {
        // Walk back from `Line - 1` until we hit code or run out of
        // file. Any contiguous comment / blank-line block starting at
        // line 1 is the file-leading documentation.
        int Start = Line;
        for (int L = Line - 1; L >= 1; --L) {
          auto Info = classifyLine(SM->getLineText(F, (uint32_t)L));
          if (Info.Kind == LineKind::Code) { Start = L + 1; break; }
          Start = L;
        }
        if (Start <= 1) {
          bool LastWasBlank = false;
          bool EmittedAny = false;
          for (int L = Start; L < Line; ++L) {
            auto Info = classifyLine(SM->getLineText(F, (uint32_t)L));
            if (Info.Kind == LineKind::Blank) {
              if (LastWasBlank) continue;
              OS << "\n";
              LastWasBlank = true;
              continue;
            }
            if (Info.Kind == LineKind::Comment) {
              OS << "# " << Info.Body << "\n";
              LastWasBlank = false;
              EmittedAny = true;
            }
          }
          // Ensure exactly one blank line separates the hoisted block
          // from whatever class / def comes next, regardless of whether
          // the source ended with a blank.
          if (EmittedAny && !LastWasBlank) OS << "\n";
          PreEmittedCommentFile = FileLeaf;
          PreEmittedCommentLine = Line - 1;
        }
      }
    }
  }

  // Pass 4: emit class blocks. Order matters when a subclass references
  // its parent — emit classes whose Super is already declared first.
  llvm::SmallVector<llvm::StringRef, 8> ClassOrder;
  llvm::StringSet<> Emitted;
  bool Progress = true;
  while (Progress) {
    Progress = false;
    for (auto &KV : Classes) {
      if (Emitted.count(KV.first())) continue;
      if (!KV.second.Super.empty() && !Emitted.count(KV.second.Super))
        continue;
      ClassOrder.push_back(KV.first());
      Emitted.insert(KV.first());
      Progress = true;
    }
  }
  // Any remaining (cycle / forward-reference Super not in module) — emit
  // anyway so we don't silently drop them.
  for (auto &KV : Classes)
    if (!Emitted.count(KV.first())) ClassOrder.push_back(KV.first());

  for (llvm::StringRef Name : ClassOrder) {
    if (Failed) break;
    emitClassBlock(Name, Classes[Name]);
  }

  // Pass 5: emit free (non-class, non-main) functions.
  for (auto &Op : M.getBody()->getOperations()) {
    if (Failed) break;
    if (auto F = mlir::dyn_cast<mlir::func::FuncOp>(Op)) {
      if (F.getBody().empty()) continue;
      if (F == MainFn) continue;
      // Class methods are emitted inside their class block instead.
      if (F->hasAttr("matlab.class_name")) continue;
      emitFuncFunc(F);
    } else if (auto F = mlir::dyn_cast<mlir::LLVM::LLVMFuncOp>(Op)) {
      if (F.getBody().empty()) continue;
      emitLLVMFunc(F);
    }
  }
  if (!Failed && MainFn) emitFuncFunc(MainFn);

  return !Failed;
}

void Emitter::emitFuncFunc(mlir::func::FuncOp F) {
  NextId = 0;
  InlineExprs.clear();
  InlinedOps.clear();
  DirectSlots.clear();
  PersistWrapSpec.clear();
  ArraySlots.clear();
  SuppressedOps.clear();
  BreakFlagSlots.clear();
  ContinueFlagSlots.clear();
  FlagIfKind.clear();
  InlinedIfs.clear();
  ForPatterns.clear();
  FusedForSlots.clear();
  FusedForSlotName.clear();
  LastLineFile.clear();
  LastLineNum = -1;
  // Function-local UsedNames scope: every non-main function gets a fresh
  // namespace so its parameters & locals stay short (`x`, `i`) instead of
  // accumulating `_2`, `_3` suffixes from earlier functions. The
  // module-level reservations (other functions, non-suppressed globals)
  // are restored on exit so calls to peer functions still resolve.
  llvm::StringSet<> SavedUsed;
  bool IsMain = F.getSymName() == "main";
  if (!IsMain) {
    SavedUsed = UsedNames;
    UsedNames.clear();
    // Re-reserve the symbol of every defined function and string global.
    for (auto &Op : F->getParentOfType<mlir::ModuleOp>().getBody()
                     ->getOperations()) {
      if (auto Fn = mlir::dyn_cast<mlir::func::FuncOp>(Op))
        UsedNames.insert(Fn.getSymName().str());
      else if (auto Fn = mlir::dyn_cast<mlir::LLVM::LLVMFuncOp>(Op))
        UsedNames.insert(Fn.getSymName().str());
      else if (auto G = mlir::dyn_cast<mlir::LLVM::GlobalOp>(Op))
        UsedNames.insert(G.getSymName().str());
    }
  }

  computeInlines(F.getBody());
  scanBreakContinueFlags(F.getBody());
  scanForLoopPatterns(F.getBody());
  /* Per-function snapshot state — clear leftovers from prior
   * functions in the same module emit. Mandatory for correctness
   * since the class members are reused across functions. */
  ResetArmGuards.clear();
  PendingSnapshotPrelude.clear();
  auto FT = F.getFunctionType();

  // Hoist @main's body to module scope — mirrors the behaviour of
  // LowerIO renaming @script -> @main so scripts become top-level code
  // in the generated Python.
  if (IsMain) {
    InMainHoist = true;
    emitRegion(F.getBody(), 0);
    InMainHoist = false;
    return;
  }

  // User function.
  OS << "def " << F.getSymName().str() << "(";
  auto &Entry = F.getBody().front();
  for (unsigned i = 0; i < FT.getNumInputs(); ++i) {
    if (i) OS << ", ";
    auto Arg = Entry.getArgument(i);
    std::string N;
    if (auto NA = F.getArgAttrOfType<mlir::StringAttr>(i, "matlab.name"))
      N = uniqueName(NA.getValue());
    else
      N = freshName();
    Names[Arg] = N;
    OS << N;
  }
  OS << "):\n";
  if (F.getBody().front().empty() ||
      (F.getBody().front().getOperations().size() == 1 &&
       mlir::isa<mlir::func::ReturnOp>(&F.getBody().front().front()))) {
    // Empty-or-just-return body: emit a `pass`.
    indent(1);
    OS << "pass\n\n";
    if (!IsMain) UsedNames = std::move(SavedUsed);
    return;
  }
  /* Suppress the verbatim runtime calls for persistent accesses and
   * register the inline replacement: `<fn>.<name>` for reads, and a
   * statement-level `<fn>.<name> = <expr>` for writes (handled in the
   * call-emit path below). The initialiser line `<fn>.<name> = 0.0`
   * is emitted after the function body closes so the name is bound
   * the first time the function is called. */
  llvm::SetVector<llvm::StringRef> PersistentNames;
  llvm::DenseMap<llvm::StringRef, std::string> InitExprByName;
  /* Per-function mapping from persistent name → id used by the
   * runtime's `persistent_isempty(id)` check. Captured during the
   * body walk so the module-level init can mark the runtime's
   * "seen" flag — without it, `persistent_isempty` would always
   * return True for scalar persistents (which use Python function-
   * attribute storage instead of `_persistent_ptr`), causing the
   * `if isempty(p) || reset` reset arm to fire on every call and
   * resetting state every cycle. The bug is invisible under
   * random vectors (most uint8 inputs aren't `==1` so the FSM
   * stays in S0 either way) but obvious under tester-driven
   * stimulus that intentionally exercises state transitions. */
  llvm::DenseMap<llvm::StringRef, int64_t> PersistentIdByName;
  /* True when the persistent is scalar — accessed via
   * `matlab_global_{get,set}_f64` (function-attribute storage in
   * the emitted Python). False for fi-array persistents accessed via
   * `matlab_persistent_{get,set}_ptr` (runtime-managed pointer).
   * Only scalars need the module-level "seen" marker; fi-arrays
   * already get a real pointer stored on first call so
   * `persistent_isempty` flips correctly without our help. */
  llvm::DenseMap<llvm::StringRef, bool> IsScalarPersistent;
  std::string FnSym = F.getSymName().str();
  // Walk both LLVM::CallOp and matlab.call_builtin shapes — the
  // C/Python pipelines don't run LowerFixedPoint's matlab_persistent_*
  // → llvm.call sweep, so set calls survive as matlab.call_builtin.
  F.getBody().walk([&](mlir::Operation *Op) {
    auto PN = Op->getAttrOfType<mlir::StringAttr>("persistent_name");
    if (!PN) return;
    PersistentNames.insert(PN.getValue());
    llvm::StringRef Callee;
    if (auto C = mlir::dyn_cast<mlir::LLVM::CallOp>(Op)) {
      if (auto Sym = C.getCallee()) Callee = *Sym;
    } else if (Op->getName().getStringRef() == "matlab.call_builtin") {
      if (auto CA = Op->getAttrOfType<mlir::StringAttr>("callee"))
        Callee = CA.getValue();
    }
    /* Capture (name → id) from any persistent runtime call; the id
     * is always operand 0 (an i32 constant). */
    if (!Callee.empty() && Op->getNumOperands() >= 1) {
      mlir::APInt IdVal;
      if (mlir::matchPattern(Op->getOperand(0),
                              mlir::m_ConstantInt(&IdVal))) {
        PersistentIdByName[PN.getValue()] = IdVal.getSExtValue();
      }
    }
    /* Tag the persistent's kind (scalar vs fi-array) by which
     * runtime call shape touched it. Scalars use the f64-table
     * routes; fi-arrays use the ptr-table routes. */
    if (Callee == "matlab_global_get_f64" ||
        Callee == "matlab_global_set_f64") {
      IsScalarPersistent[PN.getValue()] = true;
    } else if (Callee == "matlab_persistent_get_ptr" ||
               Callee == "matlab_persistent_set_ptr") {
      IsScalarPersistent[PN.getValue()] = false;
    }
    /* Capture (name → wrap-spec) for every scalar persistent so
     * later set sites can use a consistent (WL, signed) regardless
     * of whether the local set has fi_wl attrs or even a typed
     * operand. The first reliably-typed set wins. Signedness is
     * recovered from (in order) the fi_signed attr, then the value
     * operand's `matlab.unsigned` marker (set on uintN constants),
     * and defaults to signed for plain iN integers. */
    if (Callee == "matlab_global_set_f64" && Op->getNumOperands() == 2) {
      auto WLA = Op->getAttrOfType<mlir::IntegerAttr>("fi_wl");
      auto SgnA = Op->getAttrOfType<mlir::IntegerAttr>("fi_signed");
      auto It = PersistWrapSpec.find(PN.getValue());
      if (It == PersistWrapSpec.end()) {
        if (WLA && SgnA) {
          PersistWrapSpec[PN.getValue()] = {(int)WLA.getInt(),
                                             SgnA.getInt() != 0};
        } else if (auto IT = mlir::dyn_cast<mlir::IntegerType>(
                       Op->getOperand(1).getType())) {
          bool Sgn = true;
          if (auto *Def = Op->getOperand(1).getDefiningOp())
            if (Def->getAttr("matlab.unsigned")) Sgn = false;
          PersistWrapSpec[PN.getValue()] = {(int)IT.getWidth(), Sgn};
        }
      }
    }
    if (Callee == "matlab_global_get_f64" && Op->getNumResults() == 1) {
      this->Names[Op->getResult(0)] = FnSym + "." + PN.getValue().str();
      SuppressedOps.insert(Op);
    }
  });
  /* SV-faithful persistent-read semantics: snapshot every
   * persistent at function entry, and route every persistent
   * read whose value flows ONLY into another persistent's write
   * (not into the function's outputs) through the snapshot. This
   * matches SV always_comb semantics where reads always see
   * pre-edge register values, regardless of how many writes have
   * happened earlier in the block. Reads that flow to outputs
   * (via func.return operands or stores into output-named
   * allocas) keep the post-edge view (`<fn>.<name>`), since
   * cocotb post-samples the output after the clock has latched.
   *
   * Closes the cic_decimator-style integrator-chain divergence:
   *
   *   int1 = int1 + x;       // SV: reads pre-edge int1
   *   int2 = int2 + int1;    // SV: reads pre-edge int1, NOT int1_next
   *
   * Without snapshots the Python ref blocking-assigns int1 then
   * uses the new int1 to compute int2, producing one extra
   * cycle of pipeline depth per chained stage relative to SV.
   *
   * Reachability: a load "reaches output" if its result, walked
   * forward through SSA def-use, eventually hits either a
   * `func.return` or a `matlab.store`/`llvm.store` value-source.
   * The latter covers MATLAB's output-named allocas (the front
   * end materialises `function [y, ...] = f(...)` outputs as
   * named allocas; assignments `y = expr` lower to stores into
   * those allocas, then a final load → return). */
  if (!PersistentNames.empty()) {
    /* Collect function output names from the result attributes;
     * MATLAB's `function [y, ...] = f(...)` stores each result
     * variable's source name as `matlab.name` on the function's
     * result attrs. The front end materialises these as
     * `matlab.alloc {name = <out>}` allocas inside the body —
     * stores into those allocas are the canonical "value flows
     * to output" markers, since the function's terminating
     * return loads from them. */
    llvm::DenseSet<llvm::StringRef> OutputNames;
    auto FT = F.getFunctionType();
    for (unsigned i = 0; i < FT.getNumResults(); ++i) {
      if (auto NA = F.getResultAttrOfType<mlir::StringAttr>(
              i, "matlab.name"))
        OutputNames.insert(NA.getValue());
    }
    llvm::DenseSet<mlir::Value> OutputAllocas;
    F.getBody().walk([&](mlir::Operation *Op) {
      auto Nm = Op->getName().getStringRef();
      if (Nm != "matlab.alloc" && Nm != "llvm.alloca") return;
      if (Op->getNumResults() != 1) return;
      auto NA = Op->getAttrOfType<mlir::StringAttr>("name");
      if (NA && OutputNames.contains(NA.getValue()))
        OutputAllocas.insert(Op->getResult(0));
    });
    /* Forward-propagated reachability set: a value V is in
     * ReachesOutput iff there's a def-use (or alloca-mediated)
     * path from V to either a func.return operand or a store
     * into an output-named alloca. Iterated to fixpoint to
     * follow through scf.if yields and intermediate-alloca
     * store/load chains (the latter common when MATLAB locals
     * survive Mem2Reg). */
    llvm::DenseSet<mlir::Value> ReachesOutput;
    auto isStoreOp = [](llvm::StringRef N) {
      return N == "matlab.store" || N == "llvm.store";
    };
    auto isLoadOp = [](llvm::StringRef N) {
      return N == "matlab.load" || N == "llvm.load";
    };
    /* Seeds */
    F.getBody().walk([&](mlir::Operation *Op) {
      if (auto Ret = mlir::dyn_cast<mlir::func::ReturnOp>(Op)) {
        for (auto V : Ret.getOperands()) ReachesOutput.insert(V);
        return;
      }
      auto Nm = Op->getName().getStringRef();
      if (isStoreOp(Nm) && Op->getNumOperands() >= 2 &&
          OutputAllocas.contains(Op->getOperand(1)))
        ReachesOutput.insert(Op->getOperand(0));
    });
    /* Fixed-point iteration */
    bool Changed = true;
    while (Changed) {
      Changed = false;
      F.getBody().walk([&](mlir::Operation *Op) {
        /* (a) any result in set → all operands enter set */
        bool AnyResultIn = false;
        for (auto R : Op->getResults())
          if (ReachesOutput.contains(R)) { AnyResultIn = true; break; }
        if (AnyResultIn) {
          for (auto Operand : Op->getOperands())
            if (ReachesOutput.insert(Operand).second) Changed = true;
        }
        /* (b) load(alloca) result in set → all values stored
         * into the same alloca enter set (alloca-mediated) */
        auto Nm = Op->getName().getStringRef();
        if (isLoadOp(Nm) && Op->getNumOperands() >= 1 &&
            Op->getNumResults() >= 1 &&
            ReachesOutput.contains(Op->getResult(0))) {
          mlir::Value Alloca = Op->getOperand(0);
          for (auto *AU : Alloca.getUsers()) {
            auto AUNm = AU->getName().getStringRef();
            if (isStoreOp(AUNm) && AU->getNumOperands() >= 2 &&
                AU->getOperand(1) == Alloca)
              if (ReachesOutput.insert(AU->getOperand(0)).second)
                Changed = true;
          }
        }
        /* (c) scf.if result in set → its yield operands enter
         * set (region-internal control-flow that produces the
         * if's value via scf.yield) */
        if (auto If = mlir::dyn_cast<mlir::scf::IfOp>(Op)) {
          bool Any = false;
          for (auto R : If.getResults())
            if (ReachesOutput.contains(R)) { Any = true; break; }
          if (Any) {
            for (auto *Region :
                 {&If.getThenRegion(), &If.getElseRegion()}) {
              for (auto &Blk : *Region) {
                if (auto Y = mlir::dyn_cast<mlir::scf::YieldOp>(
                        Blk.back()))
                  for (auto Operand : Y.getOperands())
                    if (ReachesOutput.insert(Operand).second)
                      Changed = true;
              }
            }
          }
        }
      });
    }
    /* Apply: any persistent load whose result is NOT in
     * ReachesOutput gets routed through the snapshot. */
    llvm::SetVector<llvm::StringRef> NeedSnap;
    F.getBody().walk([&](mlir::Operation *Op) {
      auto PN = Op->getAttrOfType<mlir::StringAttr>("persistent_name");
      if (!PN) return;
      llvm::StringRef Callee;
      if (auto C = mlir::dyn_cast<mlir::LLVM::CallOp>(Op)) {
        if (auto Sym = C.getCallee()) Callee = *Sym;
      } else if (Op->getName().getStringRef() == "matlab.call_builtin") {
        if (auto CA = Op->getAttrOfType<mlir::StringAttr>("callee"))
          Callee = CA.getValue();
      }
      if (Callee != "matlab_global_get_f64") return;
      if (Op->getNumResults() != 1) return;
      if (!ReachesOutput.contains(Op->getResult(0))) {
        this->Names[Op->getResult(0)] =
            "_" + PN.getValue().str() + "_snap";
        NeedSnap.insert(PN.getValue());
      }
    });
    /* Build the snapshot prelude text now (Names already point at
     * `_<name>_snap`), but defer the emit-or-defer decision to
     * after the Tier-1 recognizer below — that's where
     * ResetArmGuards gets populated for shape-2 isempty arms.
     * The decision must come after, otherwise we'd always emit
     * at function start regardless of whether a runtime reset
     * arm is present. */
    if (!NeedSnap.empty()) {
      llvm::SmallVector<llvm::StringRef, 4> Sorted(
          NeedSnap.begin(), NeedSnap.end());
      std::sort(Sorted.begin(), Sorted.end());
      PendingSnapshotPrelude.clear();
      PendingSnapshotPrelude +=
          "    # Persistent snapshots — match SV non-blocking "
          "semantics for reads that flow to next-state writes\n";
      for (llvm::StringRef PN : Sorted) {
        PendingSnapshotPrelude += "    _";
        PendingSnapshotPrelude += PN.str();
        PendingSnapshotPrelude += "_snap = ";
        PendingSnapshotPrelude += FnSym;
        PendingSnapshotPrelude += ".";
        PendingSnapshotPrelude += PN.str();
        PendingSnapshotPrelude += "\n";
      }
    }
  }
  // Tier 1: detect canonical `if isempty(p); p = init; end` first-
  // call init pattern and suppress the entire chain. The init value
  // becomes the initializer for the module-level persistent decl.
  // Walks both LLVM::CallOp and matlab.call_builtin shapes — modules
  // that exit the SV pipeline (or land here without LowerTensorOps's
  // matlab_persistent_* → llvm.call sweep) keep the matlab.call_builtin
  // form. Without this dual walk, a module like cic_decimator surfaces
  // its isempty as an unsupported op at emit time.
  F.getBody().walk([&](mlir::Operation *IECall) {
    llvm::StringRef IECallee;
    if (auto C = mlir::dyn_cast<mlir::LLVM::CallOp>(IECall)) {
      if (auto Sym = C.getCallee()) IECallee = *Sym;
    } else if (IECall->getName().getStringRef() == "matlab.call_builtin") {
      if (auto CA = IECall->getAttrOfType<mlir::StringAttr>("callee"))
        IECallee = CA.getValue();
    } else return;
    if (IECallee != "matlab_persistent_isempty") return;
    if (IECall->getNumResults() != 1) return;
    if (!IECall->getResult(0).hasOneUse()) return;
    auto *CmpUser = IECall->getResult(0).use_begin()->getOwner();
    /* Two recognised condition shapes feed the scf.if:
     *
     *   1. `isempty(p) → cmpf one, _, 0.0 → scf.if` — the canonical
     *      first-call init when the source is `if isempty(p)`.
     *   2. `isempty(p) → matlab.short_or(_, X) → scf.if` — the
     *      `if isempty(p) || reset` form. The C / Python pipeline
     *      doesn't run SplitIsEmptyOr (which would canonicalise it
     *      to shape 1), so we have to recognise the OR shape too;
     *      otherwise the InitExprByName capture misses, the
     *      module-level decl falls back to `0.0`, and downstream
     *      bitwise ops on the persistent see a float.
     *
     * In both cases the scf.if's then-region carries the init
     * `_global_set_f64` we want; the body-side guard stays put
     * (with shape 2 we can't suppress it, since the OR branch
     * still needs the runtime reset check).
     */
    auto Cmp = mlir::dyn_cast<mlir::arith::CmpFOp>(CmpUser);
    bool IsOrShape = false;
    mlir::Operation *Or = nullptr;
    // Recognised CmpUser shapes:
    //
    //   Shape 1 — `isempty(p) → cmpf one, _, 0.0 → scf.if` (the
    //   canonical `if isempty(p)` first-call init).
    //
    //   Shape 2 — `isempty(p) → matlab.short_or → scf.if` (the
    //   `if isempty(p) || reset` form, pre-LowerScalarsToArith).
    //
    //   Shape 3 — `isempty(p) → cmpf → arith.ori → scf.if` (the
    //   same shape-2 source, but LowerScalarsToArith has folded the
    //   short_or into `cmpf + arith.ori`; the cmpf result is the
    //   ori's first operand). This is what the production pipeline
    //   actually produces, so without recognising it the snapshot
    //   stays at function entry and reads the PRE-reset state on
    //   reset cycles.
    if (Cmp) {
      // Walk one hop past cmpf to see if it feeds an `arith.ori`
      // (shape 3). When it does, the ori becomes the Or.
      if (Cmp.getResult().hasOneUse()) {
        auto *Next = Cmp.getResult().use_begin()->getOwner();
        if (mlir::isa<mlir::arith::OrIOp>(Next) &&
            Next->getNumResults() == 1) {
          Or = Next;
          IsOrShape = true;
        }
      }
    } else {
      bool IsShortOr =
          CmpUser->getName().getStringRef() == "matlab.short_or";
      bool IsArithOr = mlir::isa<mlir::arith::OrIOp>(CmpUser);
      if ((IsShortOr || IsArithOr) && CmpUser->getNumResults() == 1) {
        Or = CmpUser;
        IsOrShape = true;
      } else {
        return;
      }
    }
    auto *IfUser = IsOrShape
        ? (Or->getResult(0).hasOneUse()
            ? Or->getResult(0).use_begin()->getOwner()
            : nullptr)
        : (Cmp.getResult().hasOneUse()
            ? Cmp.getResult().use_begin()->getOwner()
            : nullptr);
    if (!IfUser) return;
    auto Guard = mlir::dyn_cast<mlir::scf::IfOp>(IfUser);
    if (!Guard || !Guard.getThenRegion().hasOneBlock()) return;
    mlir::Operation *InitSet = nullptr;
    llvm::StringRef PNStr;
    for (mlir::Operation &Op : Guard.getThenRegion().front()) {
      llvm::StringRef Cl;
      if (auto LC = mlir::dyn_cast<mlir::LLVM::CallOp>(&Op)) {
        if (auto C = LC.getCallee()) Cl = *C;
      } else if (Op.getName().getStringRef() == "matlab.call_builtin") {
        if (auto CA = Op.getAttrOfType<mlir::StringAttr>("callee"))
          Cl = CA.getValue();
      } else continue;
      if (Cl != "matlab_global_set_f64") continue;
      auto PN = Op.getAttrOfType<mlir::StringAttr>("persistent_name");
      if (!PN) continue;
      InitSet = &Op;
      PNStr = PN.getValue();
      break;
    }
    if (!InitSet || InitSet->getNumOperands() < 2) return;
    InitExprByName[PNStr] =
        dropOuterParens(this->exprFor(InitSet->getOperand(1)));
    /* Suppress the whole isempty-cmpf-if chain only for shape 1 —
     * shape 2 (`isempty || reset`) needs the if's runtime reset
     * branch to still fire on body emit. The InitExprByName
     * capture is enough by itself to fix the module-level decl. */
    if (!IsOrShape) {
      SuppressedOps.insert(IECall);
      SuppressedOps.insert(Cmp.getOperation());
      SuppressedOps.insert(Guard.getOperation());
      SuppressedOps.insert(InitSet);
    } else {
      /* Shape 2 (`isempty(p) || reset`): the Guard scf.if emits
       * as a runtime reset arm. Track it so the snapshot prelude
       * is flushed AFTER all such arms have written to their
       * persistents — see ResetArmGuards definition. */
      ResetArmGuards.insert(Guard.getOperation());
    }
  });

  /* Snapshot prelude emit-or-defer decision: now that the Tier-1
   * recognizer has populated ResetArmGuards for shape-2 arms,
   * decide whether to flush the pending prelude at function start
   * (no reset arm to wait for) or leave it pending for the scf.if
   * emit path to flush after the last reset arm closes. */
  if (!PendingSnapshotPrelude.empty() && ResetArmGuards.empty()) {
    OS << PendingSnapshotPrelude;
    PendingSnapshotPrelude.clear();
  }

  emitRegion(F.getBody(), 1);
  OS << "\n";
  /* Module-level initialisers for every persistent referenced inside.
   * Sorted for deterministic output across runs. */
  if (!PersistentNames.empty()) {
    llvm::SmallVector<llvm::StringRef, 4> Sorted(
        PersistentNames.begin(), PersistentNames.end());
    std::sort(Sorted.begin(), Sorted.end());
    for (llvm::StringRef PN : Sorted) {
      auto It = InitExprByName.find(PN);
      if (It != InitExprByName.end() && !It->second.empty())
        OS << FnSym << "." << PN.str() << " = " << It->second << "\n";
      else
        OS << FnSym << "." << PN.str() << " = 0.0\n";
      /* Mark scalar persistents' ids as seen in the runtime's
       * `_persistent_ptr` table so `rt.persistent_isempty(id)`
       * returns False for them from now on. The Python emit uses
       * function-attribute storage for scalar persistents, which
       * the runtime can't see directly; this is the bridge. We
       * skip fi-array persistents — their first call sets the
       * real pointer, which would be clobbered by a sentinel
       * `True` (and `persistent_isempty` flips correctly there
       * without our help). */
      auto KindIt = IsScalarPersistent.find(PN);
      auto IdIt = PersistentIdByName.find(PN);
      bool IsScalar = (KindIt != IsScalarPersistent.end() && KindIt->second);
      if (IsScalar && IdIt != PersistentIdByName.end())
        OS << "rt.persistent_set_ptr(" << IdIt->second << ", True)\n";
    }
    OS << "\n";
  }
  if (!IsMain) UsedNames = std::move(SavedUsed);
}

void Emitter::emitClassBlock(llvm::StringRef ClassName, const ClassDef &CI) {
  OS << "class " << ClassName.str();
  if (!CI.Super.empty()) OS << "(" << CI.Super << ")";
  OS << ":\n";
  if (CI.Methods.empty()) {
    indent(1);
    OS << "pass\n\n";
    return;
  }
  for (const auto &CMI : CI.Methods)
    emitClassMethod(CMI, /*Indent=*/1);
  OS << "\n";
}

void Emitter::emitClassMethod(const ClassMethodInfo &CMI, int Indent) {
  mlir::func::FuncOp F = CMI.Func;
  NextId = 0;
  InlineExprs.clear();
  InlinedOps.clear();
  DirectSlots.clear();
  PersistWrapSpec.clear();
  ArraySlots.clear();
  SuppressedOps.clear();
  BreakFlagSlots.clear();
  ContinueFlagSlots.clear();
  FlagIfKind.clear();
  InlinedIfs.clear();
  ForPatterns.clear();
  FusedForSlots.clear();
  FusedForSlotName.clear();
  LastLineFile.clear();
  LastLineNum = -1;
  Names.clear();

  // Method-local name scope: snapshot module-level UsedNames so locals
  // and params don't accumulate `_2` suffixes from earlier emits.
  llvm::StringSet<> SavedUsed = UsedNames;
  UsedNames.clear();
  for (auto &Op : F->getParentOfType<mlir::ModuleOp>().getBody()
                   ->getOperations()) {
    if (auto Fn = mlir::dyn_cast<mlir::func::FuncOp>(Op))
      UsedNames.insert(Fn.getSymName().str());
    else if (auto Fn = mlir::dyn_cast<mlir::LLVM::LLVMFuncOp>(Op))
      UsedNames.insert(Fn.getSymName().str());
    else if (auto G = mlir::dyn_cast<mlir::LLVM::GlobalOp>(Op))
      UsedNames.insert(G.getSymName().str());
  }
  for (auto &KV : Classes) UsedNames.insert(KV.first().str());
  // Reserve `self` / `other` so other locals never collide.
  UsedNames.insert("self");

  computeInlines(F.getBody());
  scanBreakContinueFlags(F.getBody());
  scanForLoopPatterns(F.getBody());

  auto &Entry = F.getBody().front();
  auto FT = F.getFunctionType();
  bool IsCtor = CMI.Kind == ClassMethodInfo::Ctor;
  bool IsStatic = CMI.Kind == ClassMethodInfo::Static;
  bool IsBinaryOp = CMI.Kind == ClassMethodInfo::Operator &&
                    FT.getNumInputs() == 2;

  // Bind `self` (and `other` for binary operators). Static methods have
  // no implicit self — every parameter is a real argument.
  if (!IsCtor && !IsStatic && FT.getNumInputs() >= 1) {
    Names[Entry.getArgument(0)] = "self";
  }
  if (IsBinaryOp) {
    UsedNames.insert("other");
    Names[Entry.getArgument(1)] = "other";
  }
  // For a constructor, walk the body looking for the obj_new call. Bind
  // its result to `self` so all the field-store rewrites read as
  // `self.X = ...`. The obj_new itself is suppressed (Python's __init__
  // doesn't allocate the instance — Python does that for us).
  mlir::Operation *CtorObjNew = nullptr;
  if (IsCtor) {
    F.getBody().walk([&](mlir::LLVM::CallOp C) {
      if (CtorObjNew) return;
      if (C.getCallee() && *C.getCallee() == "matlab_obj_new" &&
          C.getNumResults() == 1) {
        CtorObjNew = C.getOperation();
        Names[C.getResult()] = "self";
        SuppressedOps.insert(C.getOperation());
      }
    });
    // The trailing `return obj_new_result` is implicit in __init__.
    if (CtorObjNew) {
      F.getBody().walk([&](mlir::Operation *Op) {
        if (auto R = mlir::dyn_cast<mlir::func::ReturnOp>(Op)) {
          if (R.getNumOperands() == 1 &&
              R.getOperand(0) == CtorObjNew->getResult(0))
            SuppressedOps.insert(Op);
        }
        if (auto R = mlir::dyn_cast<mlir::LLVM::ReturnOp>(Op)) {
          if (R.getNumOperands() == 1 &&
              R.getOperand(0) == CtorObjNew->getResult(0))
            SuppressedOps.insert(Op);
        }
      });
    }
  }

  // Decorators (one per line, before `def`).
  if (CMI.Kind == ClassMethodInfo::Get) {
    indent(Indent);
    OS << "@property\n";
  }
  if (IsStatic) {
    indent(Indent);
    OS << "@staticmethod\n";
  }
  // Header: `def name(self, p1, p2, ...):`. For ctors we synthesize the
  // `self` slot; for everything else the first param IS self. Static
  // methods omit `self` entirely.
  indent(Indent);
  OS << "def " << CMI.EmitName << "(";
  bool FirstParam = true;
  if (!IsStatic) { OS << "self"; FirstParam = false; }
  unsigned StartArg = (IsCtor || IsStatic) ? 0 : 1;
  for (unsigned i = StartArg; i < FT.getNumInputs(); ++i) {
    if (!FirstParam) OS << ", ";
    FirstParam = false;
    auto Arg = Entry.getArgument(i);
    std::string N;
    if (i == 1 && IsBinaryOp) {
      N = "other";
    } else if (auto NA =
                   F.getArgAttrOfType<mlir::StringAttr>(i, "matlab.name")) {
      N = uniqueName(NA.getValue());
    } else {
      N = freshName();
    }
    Names[Arg] = N;
    OS << N;
  }
  OS << "):\n";

  // Empty / trivial body: emit `pass` only when nothing observable
  // would be emitted. A non-suppressed return-with-value counts; a
  // void-or-suppressed return doesn't (its emit collapses to nothing).
  bool BodyIsTrivial = true;
  for (auto &Op : Entry.getOperations()) {
    if (SuppressedOps.count(&Op)) continue;
    if (InlinedOps.count(&Op)) continue;
    if (auto R = mlir::dyn_cast<mlir::func::ReturnOp>(Op)) {
      if (R.getNumOperands() == 0) continue;
      BodyIsTrivial = false; break;
    }
    if (auto R = mlir::dyn_cast<mlir::LLVM::ReturnOp>(Op)) {
      if (R.getNumOperands() == 0) continue;
      BodyIsTrivial = false; break;
    }
    if (mlir::isa<mlir::arith::ConstantOp, mlir::LLVM::ConstantOp,
                  mlir::LLVM::ZeroOp, mlir::LLVM::AddressOfOp>(Op))
      continue;
    BodyIsTrivial = false;
    break;
  }
  if (BodyIsTrivial) {
    indent(Indent + 1); OS << "pass\n";
    UsedNames = std::move(SavedUsed);
    return;
  }

  emitRegion(F.getBody(), Indent + 1);
  UsedNames = std::move(SavedUsed);
}

void Emitter::emitLLVMFunc(mlir::LLVM::LLVMFuncOp F) {
  NextId = 0;
  InlineExprs.clear();
  InlinedOps.clear();
  DirectSlots.clear();
  PersistWrapSpec.clear();
  ArraySlots.clear();
  SuppressedOps.clear();
  BreakFlagSlots.clear();
  ContinueFlagSlots.clear();
  FlagIfKind.clear();
  InlinedIfs.clear();
  ForPatterns.clear();
  FusedForSlots.clear();
  FusedForSlotName.clear();
  LastLineFile.clear();
  LastLineNum = -1;
  llvm::StringSet<> SavedUsed = UsedNames;
  UsedNames.clear();
  for (auto &Op : F->getParentOfType<mlir::ModuleOp>().getBody()
                   ->getOperations()) {
    if (auto Fn = mlir::dyn_cast<mlir::func::FuncOp>(Op))
      UsedNames.insert(Fn.getSymName().str());
    else if (auto Fn = mlir::dyn_cast<mlir::LLVM::LLVMFuncOp>(Op))
      UsedNames.insert(Fn.getSymName().str());
    else if (auto G = mlir::dyn_cast<mlir::LLVM::GlobalOp>(Op))
      UsedNames.insert(G.getSymName().str());
  }
  computeInlines(F.getBody());
  scanBreakContinueFlags(F.getBody());
  scanForLoopPatterns(F.getBody());
  /* Per-function snapshot state — clear leftovers from prior
   * functions in the same module emit. Mandatory for correctness
   * since the class members are reused across functions. */
  ResetArmGuards.clear();
  PendingSnapshotPrelude.clear();
  auto FT = F.getFunctionType();
  OS << "def " << F.getSymName().str() << "(";
  auto &Entry = F.getBody().front();
  for (unsigned i = 0; i < FT.getNumParams(); ++i) {
    if (i) OS << ", ";
    auto Arg = Entry.getArgument(i);
    // Prefer the user-source name carried as an arg-attr (set by
    // anonymous-function outlining for capture / param SSA values).
    std::string N;
    if (auto NA = F.getArgAttrOfType<mlir::StringAttr>(i, "matlab.name"))
      N = uniqueName(NA.getValue());
    else
      N = freshName();
    Names[Arg] = N;
    OS << N;
  }
  OS << "):\n";
  if (F.getBody().front().empty()) {
    indent(1); OS << "pass\n\n";
    UsedNames = std::move(SavedUsed);
    return;
  }
  emitRegion(F.getBody(), 1);
  OS << "\n";
  UsedNames = std::move(SavedUsed);
}

// ---------------------------------------------------------------------------
// Region / block / op dispatch
// ---------------------------------------------------------------------------

void Emitter::emitRegion(mlir::Region &R, int Indent) {
  for (auto &B : R.getBlocks())
    emitBlock(B, Indent);
}

void Emitter::emitBlock(mlir::Block &B, int Indent) {
  AtBlockStart = true;
  // Track whether this block emitted any real (non-comment) statement; if
  // not and the block is an inner region body, we need a `pass` placeholder
  // for Python's grammar. We don't know the parent here cheaply, so let
  // the parent emit `pass` when its region turned out empty — easier.
  for (auto &Op : B.getOperations())
    emitOp(Op, Indent);
}

// Count real (non-condition, non-inlined-no-op) statements a block will
// emit. scf.yield with one or more operands counts as that many
// statements, since each operand becomes one `result_var = expr` line in
// the parent's scope.
static int countEmittedStmts(mlir::Block &B,
                             const llvm::DenseSet<mlir::Operation *> &Inlined,
                             const llvm::DenseSet<mlir::Operation *> &Suppressed) {
  int N = 0;
  for (auto &Op : B.getOperations()) {
    if (mlir::isa<mlir::scf::ConditionOp>(&Op)) continue;
    if (auto Y = mlir::dyn_cast<mlir::scf::YieldOp>(&Op)) {
      N += (int)Y.getNumOperands();
      continue;
    }
    if (Inlined.count(&Op)) continue;
    if (Suppressed.count(&Op)) continue;
    ++N;
  }
  return N;
}

void Emitter::emitOp(mlir::Operation &Op, int Indent) {
  llvm::StringRef Name = Op.getName().getStringRef();

  if (InlinedOps.count(&Op)) return;
  if (SuppressedOps.count(&Op)) return;

  advanceTo(Op.getLoc(), Indent);

  // --- llvm.mlir.zero / llvm.mlir.null --------------------------------
  if (mlir::isa<mlir::LLVM::ZeroOp>(Op)) {
    std::string N = this->name(Op.getResult(0));
    indent(Indent);
    OS << N << " = 0\n";
    return;
  }

  // --- llvm.mlir.constant ---------------------------------------------
  if (auto C = mlir::dyn_cast<mlir::LLVM::ConstantOp>(Op)) {
    std::string N = this->name(C.getResult());
    indent(Indent);
    OS << N << " = ";
    auto V = C.getValue();
    if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(V))      OS << formatIntAttr(IA);
    else if (auto FA = mlir::dyn_cast<mlir::FloatAttr>(V))   OS << formatFloatAttr(FA);
    else OS << "0  # unknown const";
    OS << "\n";
    return;
  }

  // --- arith.constant --------------------------------------------------
  if (auto C = mlir::dyn_cast<mlir::arith::ConstantOp>(Op)) {
    std::string N = this->name(C.getResult());
    indent(Indent);
    OS << N << " = ";
    auto V = C.getValue();
    if (auto FA = mlir::dyn_cast<mlir::FloatAttr>(V))        OS << formatFloatAttr(FA);
    else if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(V)) OS << formatIntAttr(IA);
    else OS << "0  # unknown const";
    OS << "\n";
    return;
  }

  // --- func.return / llvm.return --------------------------------------
  if (auto R = mlir::dyn_cast<mlir::func::ReturnOp>(Op)) {
    if (InMainHoist) {
      // Top-level main body: drop the final `return` — Python module
      // scope has no `return`. The sentinel `0` the pipeline produces
      // as the script's exit status is dropped with it.
      return;
    }
    // Wrap each integer-typed return operand to the operand's
    // declared bit width so the Python ref matches the SV DUT's
    // two's-complement output truncation. HDL-targeted code expects
    // the SV emitter's `output logic [W-1:0]` to wrap-on-overflow;
    // without the wrap, mathematical results that exceed W bits
    // leak through to the harness and mismatch the DUT's truncated
    // sample. Default signed (the SV emitter's default for
    // multi-bit ports); the `matlab.unsigned` marker on a uintN
    // cast flips it to unsigned wrap.
    // Walk back through transparent ops (loads, casts, persistent
    // gets) looking for a `matlab.unsigned` marker. The marker
    // tracks back to a uintN literal / cast in source; absence
    // defaults to signed.
    auto isUnsignedRoot = [&](mlir::Value V) -> bool {
      mlir::Value Cur = V;
      for (int Hops = 0; Hops < 8; ++Hops) {
        auto *Def = Cur.getDefiningOp();
        if (!Def) return false;
        if (Def->getAttr("matlab.unsigned")) return true;
        if (auto LC = mlir::dyn_cast<mlir::LLVM::CallOp>(Def))
          if (auto S = LC.getCallee())
            if (*S == "matlab_global_get_f64") {
              auto It = PersistWrapSpec.find(
                  Def->getAttrOfType<mlir::StringAttr>("persistent_name")
                      .getValue());
              if (It != PersistWrapSpec.end()) return !It->second.Signed;
              return false;
            }
        if (mlir::isa<mlir::arith::ExtUIOp, mlir::arith::TruncIOp,
                      mlir::arith::ShRUIOp, mlir::arith::AndIOp>(Def))
          return true;
        if (mlir::isa<mlir::arith::ExtSIOp, mlir::arith::ShRSIOp>(Def))
          return false;
        if (Def->getNumOperands() == 0) return false;
        Cur = Def->getOperand(0);
      }
      return false;
    };
    auto wrapRet = [&](mlir::Value V) -> std::string {
      std::string Body = this->stmtExpr(V);
      auto IT = mlir::dyn_cast<mlir::IntegerType>(V.getType());
      // Skip i1 — booleans don't need wrap (and fi_wrap_s on
      // 1-bit converts 1 → -1 which the harness then mismatches).
      if (!IT || IT.getWidth() < 2 || IT.getWidth() > 64) return Body;
      bool Sgn = !isUnsignedRoot(V);
      return std::string(Sgn ? "rt.fi_wrap_s(" : "rt.fi_wrap_u(") +
             dropOuterParens(Body) + ", " +
             std::to_string(IT.getWidth()) + ")";
    };
    if (R.getNumOperands() == 0) {
      // Void return at the end of the body is the implicit Python
      // function exit; only emit `return` when it sits before more code.
      if (R->getNextNode() == nullptr &&
          R->getBlock() == &R->getParentRegion()->back())
        return;
      indent(Indent); OS << "return\n";
    } else if (R.getNumOperands() == 1) {
      indent(Indent);
      OS << "return " << wrapRet(R.getOperand(0)) << "\n";
    } else {
      // Multi-return: `return a, b, c` (Python tuple).
      indent(Indent);
      OS << "return ";
      for (unsigned i = 0; i < R.getNumOperands(); ++i) {
        if (i) OS << ", ";
        OS << wrapRet(R.getOperand(i));
      }
      OS << "\n";
    }
    return;
  }
  if (auto R = mlir::dyn_cast<mlir::LLVM::ReturnOp>(Op)) {
    if (InMainHoist) return;
    if (R.getNumOperands() == 0) {
      if (R->getNextNode() == nullptr &&
          R->getBlock() == &R->getParentRegion()->back())
        return;
      indent(Indent); OS << "return\n";
    } else {
      indent(Indent);
      OS << "return " << this->stmtExpr(R.getOperand(0)) << "\n";
    }
    return;
  }

  // --- llvm.call / func.call ------------------------------------------
  if (auto Call = mlir::dyn_cast<mlir::LLVM::CallOp>(Op)) {
    // Class-field write — `obj_set_f64(obj, "X", v)` becomes
    // `obj.X = v` and is always a void statement (no result to bind).
    if (Call.getCallee() && *Call.getCallee() == "matlab_obj_set_f64" &&
        Call.getNumResults() == 0) {
      std::string Rewrite;
      if (tryRewriteObjSet(Call, Rewrite)) {
        indent(Indent);
        OS << Rewrite << "\n";
        return;
      }
    }
    indent(Indent);
    if (Call.getNumResults() == 1) {
      std::string N = this->name(Call.getResult());
      OS << N << " = ";
    }
    if (auto Callee = Call.getCallee()) {
      // Class-field read with binding: `name = obj_get_f64(obj, "X")` →
      // `name = obj.X`. Inline-expression sites are handled by
      // buildInlineExpr; this path covers the rare non-inlined case.
      if (*Callee == "matlab_obj_get_f64" && Call.getNumResults() == 1) {
        std::string Rewrite;
        if (tryRewriteObjGet(Call, Rewrite)) {
          OS << dropOuterParens(Rewrite) << "\n";
          return;
        }
      }
      // Class-method call (constructor / regular / operator / get-prop).
      // Catches the case where the result is bound to a local rather
      // than inlined into another expression.
      {
        std::string Rewrite;
        if (tryRewriteAsClassCall(*Callee, Call.getOperands(), Rewrite)) {
          OS << dropOuterParens(Rewrite) << "\n";
          return;
        }
      }
      // For user-string runtime helpers, drop the (str_ptr, str_len) tail
      // length operand — Python strings carry their length, and the
      // matching runtime stub keeps `n` optional for back-compat.
      unsigned LengthIdx = ~0u;
      bool DropLen = false;
      if (Callee->starts_with("matlab_")) {
        unsigned Idx;
        if (calleeHasDroppableLengthArg(
                Callee->drop_front(strlen("matlab_")), Idx)) {
          LengthIdx = Idx;
          DropLen = true;
        }
      }
      // `rt.disp_str("literal")` is byte-identical to `print("literal")`,
      // so collapse it. Detect by callee + a single (post-length-drop)
      // operand that traces to a string-global addressof. We keep the
      // runtime call for `disp_str(<variable>)` since the runtime path
      // also handles non-`str` payloads.
      auto isStringLiteralOperand = [&](mlir::Value V) -> bool {
        if (auto *D = V.getDefiningOp())
          if (auto A = mlir::dyn_cast<mlir::LLVM::AddressOfOp>(D))
            return StringGlobalLits.count(A.getGlobalName()) > 0;
        return false;
      };
      if ((*Callee == "matlab_disp_str" ||
           *Callee == "matlab_string_disp") &&
          Call.getNumResults() == 0 && Call.getNumOperands() >= 1 &&
          isStringLiteralOperand(Call.getOperand(0))) {
        OS << "print(" << this->stmtExpr(Call.getOperand(0)) << ")\n";
        return;
      }
      // `rt.disp_f64(x)` prints a scalar using MATLAB's `%g` formatting.
      // Python's `f'{x:g}'` matches that for every finite value (NaN /
      // Inf print lower-case in Python vs MATLAB's "NaN" / "Inf" — none
      // of the in-tree goldens hit those, so we collapse the call to a
      // bare `print(f'{x:g}')` for readability). Outer single quotes
      // sidestep f-string quote-nesting limits in Python <3.12 — our
      // own string emission always uses double quotes, so any inlined
      // literal inside the expression won't collide.
      if (*Callee == "matlab_disp_f64" && Call.getNumResults() == 0 &&
          Call.getNumOperands() == 1) {
        OS << "print(f'{" << this->stmtExpr(Call.getOperand(0))
           << ":g}')\n";
        return;
      }
      // Matrix `disp` collapses to plain `print(M)`. The Python lane
      // accepts numpy's bracket-and-dotted-float matrix formatting via
      // a per-test `.stdout-python` override (see test/Run/
      // run_tests_emitpython.sh); the C/C++ goldens keep the MATLAB-
      // style `%7g` right-aligned columns they share.
      if (*Callee == "matlab_disp_mat" && Call.getNumResults() == 0 &&
          Call.getNumOperands() == 1) {
        OS << "print(" << this->stmtExpr(Call.getOperand(0)) << ")\n";
        return;
      }
      // Numpy / operator rewrite for matrix builtins — emit the inline
      // expression directly when the call binds a result.
      {
        std::string Rewrite;
        if (tryRewriteAsNumpy(Call, Rewrite)) {
          OS << dropOuterParens(Rewrite) << "\n";
          return;
        }
      }
      /* Persistent variable write: `matlab_global_set_f64(_, v)` with
       * persistent_name + persistent_fn lowers to `<fn>.<name> = <v>`.
       * The init line `<fn>.<name> = 0.0` is emitted below the
       * function body by emitFuncFunc. */
      if (*Callee == "matlab_global_set_f64" && Call.getNumResults() == 0 &&
          Call.getNumOperands() == 2) {
        auto PN = Call->getAttrOfType<mlir::StringAttr>("persistent_name");
        auto PF = Call->getAttrOfType<mlir::StringAttr>("persistent_fn");
        if (PN && PF) {
          OS << PF.getValue().str() << "." << PN.getValue().str()
             << " = " << this->stmtExpr(Call.getOperand(1)) << "\n";
          return;
        }
      }
      OS << remapRuntimeCallee(*Callee) << "(";
      bool First = true;
      for (unsigned i = 0; i < Call.getNumOperands(); ++i) {
        if (DropLen && i == LengthIdx) continue;
        if (!First) OS << ", ";
        First = false;
        OS << this->stmtExpr(Call.getOperand(i));
      }
      OS << ")\n";
    } else {
      // Indirect call: first operand is the callable.
      OS << this->exprFor(Call.getOperand(0)) << "(";
      for (unsigned i = 1; i < Call.getNumOperands(); ++i) {
        if (i > 1) OS << ", ";
        OS << this->stmtExpr(Call.getOperand(i));
      }
      OS << ")\n";
    }
    return;
  }
  if (auto Call = mlir::dyn_cast<mlir::func::CallOp>(Op)) {
    indent(Indent);
    if (Call.getNumResults() == 1) {
      std::string N = this->name(Call.getResult(0));
      OS << N << " = ";
    } else if (Call.getNumResults() > 1) {
      // Multi-return: `a, b = f(args)` Python tuple unpacking.
      for (unsigned i = 0; i < Call.getNumResults(); ++i) {
        if (i) OS << ", ";
        OS << this->name(Call.getResult(i));
      }
      OS << " = ";
    }
    {
      std::string Rewrite;
      if (tryRewriteAsClassCall(Call.getCallee(), Call.getOperands(),
                                 Rewrite)) {
        OS << dropOuterParens(Rewrite) << "\n";
        return;
      }
    }
    OS << Call.getCallee().str() << "(";
    for (unsigned i = 0; i < Call.getNumOperands(); ++i) {
      if (i) OS << ", ";
      OS << this->stmtExpr(Call.getOperand(i));
    }
    OS << ")\n";
    return;
  }

  // --- llvm.mlir.addressof --------------------------------------------
  if (auto A = mlir::dyn_cast<mlir::LLVM::AddressOfOp>(Op)) {
    std::string N = this->name(A.getResult());
    indent(Indent);
    auto It = StringGlobalLits.find(A.getGlobalName());
    if (It != StringGlobalLits.end()) {
      OS << N << " = " << It->second << "\n";
      SuppressedGlobals.insert(A.getGlobalName());
    } else {
      OS << N << " = " << A.getGlobalName().str() << "\n";
    }
    return;
  }

  // --- arith binary ops ------------------------------------------------
  // For overflow-capable integer ops (addi / subi / muli / shli) wrap
  // the result to its declared bit width so the Python ref matches
  // the SV DUT's two's-complement mid-computation truncation. See
  // the buildInlineExpr counterpart for the rationale; this is the
  // statement-emit shape (when the result needs a separate name
  // rather than being inlined into a single-line consumer).
  auto unsignedRoot = [&](mlir::Value V) -> bool {
    mlir::Value Cur = V;
    for (int Hops = 0; Hops < 4; ++Hops) {
      auto *Def = Cur.getDefiningOp();
      if (!Def) return false;
      if (Def->getAttr("matlab.unsigned")) return true;
      if (mlir::isa<mlir::arith::ExtUIOp, mlir::arith::ShRUIOp,
                    mlir::arith::AndIOp>(Def))
        return true;
      if (mlir::isa<mlir::arith::ExtSIOp, mlir::arith::ShRSIOp>(Def))
        return false;
      if (Def->getNumOperands() == 0) return false;
      Cur = Def->getOperand(0);
    }
    return false;
  };
  auto emitBin = [&](const char *CC) {
    indent(Indent);
    std::string N = this->name(Op.getResult(0));
    OS << N << " = " << this->exprFor(Op.getOperand(0)) << " " << CC << " "
       << this->exprFor(Op.getOperand(1)) << "\n";
  };
  auto emitBinWrapInt = [&](const char *CC) {
    mlir::IntegerType IT;
    if (auto T = mlir::dyn_cast<mlir::IntegerType>(
            Op.getResult(0).getType()))
      IT = T;
    else if (Op.getNumOperands() >= 1) {
      if (auto T = mlir::dyn_cast<mlir::IntegerType>(
              Op.getOperand(0).getType()))
        IT = T;
      else if (Op.getNumOperands() >= 2)
        if (auto T = mlir::dyn_cast<mlir::IntegerType>(
                Op.getOperand(1).getType()))
          IT = T;
    }
    if (!IT || IT.getWidth() < 2 || IT.getWidth() > 64) {
      emitBin(CC);
      return;
    }
    bool Sgn = !(unsignedRoot(Op.getOperand(0)) ||
                 unsignedRoot(Op.getOperand(1)));
    indent(Indent);
    std::string N = this->name(Op.getResult(0));
    OS << N << " = "
       << (Sgn ? "rt.fi_wrap_s(" : "rt.fi_wrap_u(")
       << this->exprFor(Op.getOperand(0)) << " " << CC << " "
       << this->exprFor(Op.getOperand(1)) << ", "
       << IT.getWidth() << ")\n";
  };
  if (mlir::isa<mlir::arith::AddFOp>(Op)) { emitBin("+"); return; }
  if (mlir::isa<mlir::arith::SubFOp>(Op)) { emitBin("-"); return; }
  if (mlir::isa<mlir::arith::MulFOp>(Op)) { emitBin("*"); return; }
  if (mlir::isa<mlir::arith::DivFOp>(Op)) { emitBin("/"); return; }
  if (mlir::isa<mlir::arith::AddIOp>(Op)) { emitBinWrapInt("+"); return; }
  if (mlir::isa<mlir::arith::SubIOp>(Op)) { emitBinWrapInt("-"); return; }
  if (mlir::isa<mlir::arith::MulIOp>(Op)) { emitBinWrapInt("*"); return; }
  if (mlir::isa<mlir::arith::ShLIOp>(Op))  { emitBinWrapInt("<<"); return; }
  if (mlir::isa<mlir::arith::ShRSIOp>(Op)) { emitBin(">>"); return; }
  if (mlir::isa<mlir::arith::ShRUIOp>(Op)) {
    // Logical right shift — Python `>>` is arithmetic; mask to
    // unsigned bit pattern first so the shifted bits come back as
    // zero. Mirrors the inline-expr path's handling.
    auto IT = mlir::dyn_cast<mlir::IntegerType>(Op.getOperand(0).getType());
    if (IT && IT.getWidth() >= 1 && IT.getWidth() <= 64) {
      uint64_t Mask = (IT.getWidth() == 64) ? ~uint64_t(0)
                                            : (uint64_t(1) << IT.getWidth()) - 1;
      indent(Indent);
      std::string N = this->name(Op.getResult(0));
      OS << N << " = ((" << this->exprFor(Op.getOperand(0)) << " & "
         << Mask << ") >> " << this->exprFor(Op.getOperand(1)) << ")\n";
      return;
    }
    emitBin(">>");
    return;
  }
  if (mlir::isa<mlir::arith::BitcastOp>(Op)) {
    indent(Indent);
    std::string N = this->name(Op.getResult(0));
    OS << N << " = " << this->exprFor(Op.getOperand(0)) << "\n";
    return;
  }

  if (auto A = mlir::dyn_cast<mlir::arith::AndIOp>(Op)) {
    if (isI1(A.getType())) { emitBin("and"); return; }
    emitBin("&"); return;
  }
  if (auto O = mlir::dyn_cast<mlir::arith::OrIOp>(Op)) {
    if (isI1(O.getType())) { emitBin("or"); return; }
    emitBin("|"); return;
  }
  if (auto X = mlir::dyn_cast<mlir::arith::XOrIOp>(Op)) {
    if (isI1(X.getType())) { emitBin("!="); return; }
    emitBin("^"); return;
  }

  // --- arith.cmpf / cmpi ----------------------------------------------
  if (auto C = mlir::dyn_cast<mlir::arith::CmpFOp>(Op)) {
    const char *CC = "==";
    switch (C.getPredicate()) {
      case mlir::arith::CmpFPredicate::OEQ:
      case mlir::arith::CmpFPredicate::UEQ: CC = "=="; break;
      case mlir::arith::CmpFPredicate::ONE:
      case mlir::arith::CmpFPredicate::UNE: CC = "!="; break;
      case mlir::arith::CmpFPredicate::OLT:
      case mlir::arith::CmpFPredicate::ULT: CC = "<"; break;
      case mlir::arith::CmpFPredicate::OLE:
      case mlir::arith::CmpFPredicate::ULE: CC = "<="; break;
      case mlir::arith::CmpFPredicate::OGT:
      case mlir::arith::CmpFPredicate::UGT: CC = ">"; break;
      case mlir::arith::CmpFPredicate::OGE:
      case mlir::arith::CmpFPredicate::UGE: CC = ">="; break;
      default: break;
    }
    indent(Indent);
    std::string N = this->name(C.getResult());
    OS << N << " = " << this->exprFor(C.getLhs()) << " " << CC
       << " " << this->exprFor(C.getRhs()) << "\n";
    return;
  }
  if (auto C = mlir::dyn_cast<mlir::arith::CmpIOp>(Op)) {
    const char *CC = "==";
    switch (C.getPredicate()) {
      case mlir::arith::CmpIPredicate::eq:  CC = "=="; break;
      case mlir::arith::CmpIPredicate::ne:  CC = "!="; break;
      case mlir::arith::CmpIPredicate::slt:
      case mlir::arith::CmpIPredicate::ult: CC = "<"; break;
      case mlir::arith::CmpIPredicate::sle:
      case mlir::arith::CmpIPredicate::ule: CC = "<="; break;
      case mlir::arith::CmpIPredicate::sgt:
      case mlir::arith::CmpIPredicate::ugt: CC = ">"; break;
      case mlir::arith::CmpIPredicate::sge:
      case mlir::arith::CmpIPredicate::uge: CC = ">="; break;
    }
    indent(Indent);
    std::string N = this->name(C.getResult());
    OS << N << " = " << this->exprFor(C.getLhs()) << " " << CC
       << " " << this->exprFor(C.getRhs()) << "\n";
    return;
  }

  // --- Unregistered matlab.* binops ----------------------------------
  // Frontend leaves these for non-numeric / non-fully-typed call sites
  // (mostly HDL-targeted code that the SV pipeline consumes
  // unchanged). The Python emitter should render them as the
  // equivalent Python operator so HDL-source files that don't depend
  // on persistent state can also compile here.
  {
    llvm::StringRef MN = Op.getName().getStringRef();
    if (Op.getNumOperands() == 2 && Op.getNumResults() == 1) {
      const char *CC = nullptr;
      bool Overflow = false;
      if (MN == "matlab.add") { CC = "+"; Overflow = true; }
      else if (MN == "matlab.sub") { CC = "-"; Overflow = true; }
      else if (MN == "matlab.emul" || MN == "matlab.matmul") {
        CC = "*"; Overflow = true;
      }
      else if (MN == "matlab.ediv" || MN == "matlab.matdiv") CC = "/";
      else if (MN == "matlab.eq") CC = "==";
      else if (MN == "matlab.ne") CC = "!=";
      else if (MN == "matlab.lt") CC = "<";
      else if (MN == "matlab.le") CC = "<=";
      else if (MN == "matlab.gt") CC = ">";
      else if (MN == "matlab.ge") CC = ">=";
      else if (MN == "matlab.short_or") CC = "or";
      else if (MN == "matlab.short_and") CC = "and";
      if (CC) {
        if (Overflow) emitBinWrapInt(CC);
        else emitBin(CC);
        return;
      }
    }
    // Unary `matlab.not` — bool NOT (HDL idiom: `~rst`, `~en`, etc.).
    // The op's i1 result coerces from any integer / float operand;
    // Python's `not` does the truthiness coercion automatically.
    if (MN == "matlab.not" && Op.getNumOperands() == 1 &&
        Op.getNumResults() == 1) {
      indent(Indent);
      std::string N = this->name(Op.getResult(0));
      OS << N << " = (not " << this->stmtExpr(Op.getOperand(0)) << ")\n";
      return;
    }
  }

  // --- arith casts ----------------------------------------------------
  if (mlir::isa<mlir::arith::SIToFPOp, mlir::arith::UIToFPOp>(Op)) {
    indent(Indent);
    std::string N = this->name(Op.getResult(0));
    OS << N << " = float(" << this->stmtExpr(Op.getOperand(0)) << ")\n";
    return;
  }
  if (mlir::isa<mlir::arith::FPToSIOp, mlir::arith::FPToUIOp>(Op)) {
    indent(Indent);
    std::string N = this->name(Op.getResult(0));
    OS << N << " = int(" << this->stmtExpr(Op.getOperand(0)) << ")\n";
    return;
  }
  // ext/trunc are no-ops in Python.
  if (mlir::isa<mlir::arith::ExtSIOp, mlir::arith::ExtUIOp,
                mlir::arith::TruncIOp, mlir::arith::TruncFOp,
                mlir::arith::ExtFOp>(Op)) {
    indent(Indent);
    std::string N = this->name(Op.getResult(0));
    OS << N << " = " << this->stmtExpr(Op.getOperand(0)) << "\n";
    return;
  }

  // --- arith.select ---------------------------------------------------
  if (auto S = mlir::dyn_cast<mlir::arith::SelectOp>(Op)) {
    indent(Indent);
    std::string N = this->name(S.getResult());
    OS << N << " = " << this->exprFor(S.getTrueValue()) << " if "
       << this->exprFor(S.getCondition()) << " else "
       << this->exprFor(S.getFalseValue()) << "\n";
    return;
  }

  // --- llvm.alloca / load / store -------------------------------------
  if (auto A = mlir::dyn_cast<mlir::LLVM::AllocaOp>(Op)) {
    std::string Hint;
    if (auto NA = A->getAttrOfType<mlir::StringAttr>("matlab.name"))
      Hint = NA.getValue().str();
    std::string SlotName;
    if (!Hint.empty()) {
      std::string Sane = sanitizeIdent(Hint);
      if (UsedNames.find(Sane) != UsedNames.end())
        SlotName = uniqueName(Sane + "_slot");
      else
        SlotName = uniqueName(Sane);
    } else {
      SlotName = uniqueName("slot");
    }
    mlir::Type ET = A.getElemType();
    bool IsArray = mlir::isa<mlir::LLVM::LLVMArrayType>(ET);

    if (IsArray) {
      auto AT = mlir::cast<mlir::LLVM::LLVMArrayType>(ET);
      uint64_t N0 = AT.getNumElements();
      Names[A.getResult()] = SlotName;
      ArraySlots[A.getOperation()] = SlotName;

      // Matrix-literal init pattern from LowerTensorOps::materializeMat:
      // every alloca user is a GEP-with-constant-index-then-store (or a
      // direct store at idx 0). When all N indices 0..N-1 are filled
      // exactly once with stmtExpr-able values, collapse into a single
      // `slot = [v0, v1, ...]` Python list literal and absorb the
      // GEP/store ops.
      auto getConstIdx = [](mlir::LLVM::GEPOp G, uint64_t &Out) -> bool {
        auto Idxs = G.getIndices();
        if (std::distance(Idxs.begin(), Idxs.end()) != 1) return false;
        auto Raw = *Idxs.begin();
        if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(Raw)) {
          Out = IA.getValue().getZExtValue();
          return true;
        }
        if (auto V = mlir::dyn_cast<mlir::Value>(Raw)) {
          if (auto C = V.getDefiningOp<mlir::LLVM::ConstantOp>())
            if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(C.getValue())) {
              Out = IA.getValue().getZExtValue();
              return true;
            }
          if (auto C = V.getDefiningOp<mlir::arith::ConstantOp>())
            if (auto IA = mlir::dyn_cast<mlir::IntegerAttr>(C.getValue())) {
              Out = IA.getValue().getZExtValue();
              return true;
            }
        }
        return false;
      };
      llvm::SmallVector<mlir::Value, 16> InitVals(N0);
      llvm::SmallVector<mlir::Operation *, 32> AbsorbedOps;
      bool InitOK = N0 > 0;
      uint64_t Filled = 0;
      for (mlir::OpOperand &Use : A->getUses()) {
        if (!InitOK) break;
        mlir::Operation *U = Use.getOwner();
        if (auto St = mlir::dyn_cast<mlir::LLVM::StoreOp>(U)) {
          if (St.getAddr() != A.getResult()) { InitOK = false; break; }
          if (InitVals[0]) { InitOK = false; break; }  // duplicate idx 0
          InitVals[0] = St.getValue();
          AbsorbedOps.push_back(St.getOperation());
          ++Filled;
          continue;
        }
        if (auto Gep = mlir::dyn_cast<mlir::LLVM::GEPOp>(U)) {
          if (Gep.getBase() != A.getResult()) { InitOK = false; break; }
          uint64_t Idx;
          if (!getConstIdx(Gep, Idx) || Idx >= N0 || InitVals[Idx]) {
            InitOK = false; break;
          }
          if (!Gep.getResult().hasOneUse()) { InitOK = false; break; }
          auto St = mlir::dyn_cast<mlir::LLVM::StoreOp>(
              *Gep.getResult().getUsers().begin());
          if (!St || St.getAddr() != Gep.getResult()) {
            InitOK = false; break;
          }
          InitVals[Idx] = St.getValue();
          AbsorbedOps.push_back(Gep.getOperation());
          AbsorbedOps.push_back(St.getOperation());
          ++Filled;
          continue;
        }
        // The legitimate post-init consumer (e.g. matlab_mat_from_buf).
        if (mlir::isa<mlir::LLVM::CallOp>(U)) continue;
        InitOK = false;
        break;
      }
      if (InitOK && Filled == N0)
        for (auto V : InitVals) if (!V) { InitOK = false; break; }
      if (InitOK && Filled == N0) {
        indent(Indent);
        OS << SlotName << " = [";
        for (uint64_t i = 0; i < N0; ++i) {
          if (i) OS << ", ";
          OS << this->stmtExpr(InitVals[i]);
        }
        OS << "]\n";
        for (auto *Op2 : AbsorbedOps) SuppressedOps.insert(Op2);
        return;
      }

      // Fallback: zero-filled list, individual stores follow.
      indent(Indent);
      OS << SlotName << " = [0.0] * " << N0 << "\n";
      return;
    }

    // For-loop fused slot: the surrounding `for iv in range(...):`
    // emitter declares the IV directly. Skip the alloca and any
    // pre-store; future loads/stores resolve to the IV name.
    if (FusedForSlots.count(A.getOperation())) {
      auto NIt = FusedForSlotName.find(A.getOperation());
      if (NIt != FusedForSlotName.end()) {
        Names[A.getResult()] = NIt->second;
        DirectSlots[A.getOperation()] = NIt->second;
      }
      return;
    }

    // Scalar slot: every use we've seen from Mem2RegLite is load/store.
    // Bind the alloca SSA value to the slot name; downstream load/store
    // treat it as a direct Python variable.
    Names[A.getResult()] = SlotName;
    DirectSlots[A.getOperation()] = SlotName;

    // Drop the pre-declaration `slot = 0` when the slot's first use is
    // an unconditional store. Python doesn't need pre-declaration —
    // assignment creates the binding — so the zero-init is dead weight
    // when overwritten before any read.
    //
    // Conservative dominance check: walk the parent block in program
    // order; at each op, look for any operand that is the slot. If the
    // op directly stores into the slot, the init is dead. If the op
    // directly loads, keep the init. If the op has a nested region
    // (scf.if / scf.while) that uses the slot, the use sits under a
    // conditional / loop and may be skipped at runtime — keep the init
    // so post-loop reads bind safely.
    // True when every dynamic execution of `B` performs at least one
    // unconditional Store into SlotV before reading from it (or before
    // returning). Recurses through scf.if when both branches store; that
    // covers MATLAB return-slot patterns like `if c; y = a; else y = b;
    // end` where the return slot is fully assigned regardless of branch.
    std::function<bool(mlir::Block &, mlir::Value)> blockAlwaysStores =
        [&](mlir::Block &B, mlir::Value SlotV) -> bool {
      for (auto &Op2 : B) {
        if (auto St = mlir::dyn_cast<mlir::LLVM::StoreOp>(Op2))
          if (St.getAddr() == SlotV) return true;
        if (auto If = mlir::dyn_cast<mlir::scf::IfOp>(Op2)) {
          if (If.getElseRegion().empty()) continue;
          if (blockAlwaysStores(If.getThenRegion().front(), SlotV) &&
              blockAlwaysStores(If.getElseRegion().front(), SlotV))
            return true;
        }
      }
      return false;
    };

    bool DropInit = false;
    {
      mlir::Block *ABlock = A->getBlock();
      mlir::Value SlotV = A.getResult();
      for (auto It = mlir::Block::iterator(A->getNextNode());
           It != ABlock->end(); ++It) {
        mlir::Operation *DirectUser = nullptr;
        for (mlir::OpOperand &U : SlotV.getUses()) {
          if (U.getOwner() == &*It) { DirectUser = U.getOwner(); break; }
        }
        if (DirectUser) {
          if (auto St = mlir::dyn_cast<mlir::LLVM::StoreOp>(DirectUser)) {
            if (St.getAddr() == SlotV) { DropInit = true; break; }
          }
          break;  // load (or other consumer) — keep the init.
        }
        bool NestedUse = false;
        for (auto &Reg : It->getRegions()) {
          Reg.walk([&](mlir::Operation *Inner) {
            for (mlir::Value Opnd : Inner->getOperands())
              if (Opnd == SlotV) NestedUse = true;
          });
          if (NestedUse) break;
        }
        if (NestedUse) {
          // Allow the nested-use case when the op is an scf.if whose
          // both branches unconditionally store into the slot — the
          // pre-init is then dead weight.
          if (auto If = mlir::dyn_cast<mlir::scf::IfOp>(&*It)) {
            if (!If.getElseRegion().empty() &&
                blockAlwaysStores(If.getThenRegion().front(), SlotV) &&
                blockAlwaysStores(If.getElseRegion().front(), SlotV)) {
              DropInit = true;
            }
          }
          break;
        }
      }
    }
    if (DropInit) return;

    indent(Indent);
    OS << SlotName << " = 0\n";
    return;
  }

  if (auto L = mlir::dyn_cast<mlir::LLVM::LoadOp>(Op)) {
    mlir::Operation *AddrDef = L.getAddr().getDefiningOp();
    std::string N;
    if (AddrDef) {
      if (auto A = mlir::dyn_cast<mlir::LLVM::AllocaOp>(AddrDef)) {
        if (auto NA = A->getAttrOfType<mlir::StringAttr>("matlab.name")) {
          N = uniqueName(NA.getValue().str() + "_v");
          Names[L.getResult()] = N;
        }
      }
    }
    if (N.empty()) N = this->name(L.getResult());
    indent(Indent);
    if (AddrDef && DirectSlots.count(AddrDef)) {
      OS << N << " = " << DirectSlots[AddrDef] << "\n";
    } else if (AddrDef && ArraySlots.count(AddrDef)) {
      // Array-slot load should always come through a GEP; the GEP
      // inlining handles the indexing. A raw load of the array pointer
      // doesn't make sense here — just bind to the slot name.
      OS << N << " = " << ArraySlots[AddrDef] << "\n";
    } else {
      // Non-direct (e.g. GEP address): the address expression IS the
      // place to load from — emit `N = <addr_expr>`. Works for
      // `arr[idx]` shaped GEPs.
      OS << N << " = " << this->stmtExpr(L.getAddr()) << "\n";
    }
    return;
  }
  if (auto S = mlir::dyn_cast<mlir::LLVM::StoreOp>(Op)) {
    mlir::Operation *AddrDef = S.getAddr().getDefiningOp();
    indent(Indent);
    if (AddrDef && DirectSlots.count(AddrDef)) {
      OS << DirectSlots[AddrDef] << " = " << this->stmtExpr(S.getValue())
         << "\n";
    } else if (AddrDef && ArraySlots.count(AddrDef)) {
      // Store straight to the array alloca's base pointer = element 0.
      // LLVM allows writing through an alloca address without a GEP; in
      // Python this needs explicit indexing.
      OS << ArraySlots[AddrDef] << "[0] = "
         << this->stmtExpr(S.getValue()) << "\n";
    } else {
      // Non-direct: address is a GEP-like expression (`arr[idx]`).
      OS << this->stmtExpr(S.getAddr()) << " = "
         << this->stmtExpr(S.getValue()) << "\n";
    }
    return;
  }

  // --- llvm.getelementptr ---------------------------------------------
  if (auto G = mlir::dyn_cast<mlir::LLVM::GEPOp>(Op)) {
    // If not inlined, materialise as an expression local (same text as
    // the inline form).
    std::string Base;
    if (auto *D = G.getBase().getDefiningOp()) {
      auto It = ArraySlots.find(D);
      if (It != ArraySlots.end()) Base = It->second;
    }
    if (Base.empty()) Base = this->exprFor(G.getBase());
    std::string Idx;
    bool First = true;
    for (auto I : G.getIndices()) {
      std::string Term;
      if (auto Vv = llvm::dyn_cast<mlir::Value>(I))
        Term = dropOuterParens(this->exprFor(Vv));
      else if (auto IA = llvm::dyn_cast<mlir::IntegerAttr>(I))
        Term = std::to_string(IA.getInt());
      else continue;
      if (First) { Idx = Term; First = false; }
      else       { Idx = "(" + Idx + " + " + Term + ")"; }
    }
    if (Idx.empty()) Idx = "0";
    std::string N = this->name(G.getResult());
    indent(Indent);
    OS << N << " = " << Base << "[" << Idx << "]\n";
    return;
  }

  // --- scf.if ---------------------------------------------------------
  if (auto If = mlir::dyn_cast<mlir::scf::IfOp>(Op)) {
    // Break/continue short-circuit: `scf.if cond { flag := true }` came
    // from a MATLAB `if cond; break; end`. Re-emit as a one-liner.
    auto FK = FlagIfKind.find(&Op);
    if (FK != FlagIfKind.end()) {
      indent(Indent);
      OS << "if " << this->stmtExpr(If.getCondition()) << ":\n";
      indent(Indent + 1);
      OS << FK->second << "\n";
      return;
    }
    // Pure flag-guard wrapping real body: skip the `if (...)` and emit
    // the then-region inline at the parent's indent.
    if (InlinedIfs.count(&Op)) {
      emitRegion(If.getThenRegion(), Indent);
      return;
    }
    // Static-condition folding. Polymorphic dispatch in the frontend
    // bakes nargin into a constant comparison (`if 2 == 2:`); detect
    // that here and emit only the live branch.
    int Folded = evalConstCond(If.getCondition());
    if (Folded == 1) {
      emitRegion(If.getThenRegion(), Indent);
      return;
    }
    if (Folded == 0) {
      if (!If.getElseRegion().empty())
        emitRegion(If.getElseRegion(), Indent);
      return;
    }

    // Detect an else-region whose only meaningful op is a single nested
    // scf.if (the shape MATLAB `elseif` lowers to). Walk the chain so
    // a cascade of elseifs collapses to one `elif <cond>:` per branch
    // instead of a deepening `else: if ...` ladder.
    auto findElseElif = [&](mlir::scf::IfOp Parent)
        -> mlir::scf::IfOp {
      if (Parent.getElseRegion().empty()) return {};
      auto &EBlock = Parent.getElseRegion().front();
      mlir::scf::IfOp Inner;
      for (auto &Inn : EBlock.getOperations()) {
        if (mlir::isa<mlir::scf::YieldOp>(&Inn)) {
          // Void if (no results): yield is a no-op. Result-bearing if:
          // the yield must forward exactly the inner if's results so
          // chaining is safe.
          if (auto Y = mlir::dyn_cast<mlir::scf::YieldOp>(Inn)) {
            if (Y.getNumOperands() == 0) continue;
            if (!Inner) return {};
            if (Y.getNumOperands() != Inner.getNumResults()) return {};
            for (unsigned i = 0; i < Y.getNumOperands(); ++i)
              if (Y.getOperand(i) != Inner.getResult(i)) return {};
            continue;
          }
        }
        if (InlinedOps.count(&Inn)) continue;
        if (SuppressedOps.count(&Inn)) continue;
        if (auto NestedIf = mlir::dyn_cast<mlir::scf::IfOp>(Inn)) {
          if (Inner) return {};  // multiple ifs — not a clean elif
          // Skip elif folding for the special break/continue forms;
          // those need their own scf.if emit path.
          if (FlagIfKind.count(NestedIf.getOperation())) return {};
          if (InlinedIfs.count(NestedIf.getOperation())) return {};
          Inner = NestedIf;
          continue;
        }
        return {};  // some other op rules out clean elif folding
      }
      return Inner;
    };

    indent(Indent);
    OS << "if " << this->stmtExpr(If.getCondition()) << ":\n";
    if (countEmittedStmts(If.getThenRegion().front(), InlinedOps,
                           SuppressedOps) == 0) {
      indent(Indent + 1); OS << "pass\n";
    } else {
      emitRegion(If.getThenRegion(), Indent + 1);
    }

    // Walk the else-chain, folding each cleanly-chainable nested scf.if
    // into an `elif`. The inner if's result SSA values are aliased to
    // the parent's result-locals so each branch's yield writes to the
    // shared variable.
    mlir::scf::IfOp Cur = If;
    while (true) {
      mlir::scf::IfOp Next = findElseElif(Cur);
      if (!Next) break;
      // Statically-folded inner condition: lift the live branch up to
      // the parent's indent and stop chaining.
      int InnerFold = evalConstCond(Next.getCondition());
      if (InnerFold == 1) {
        for (unsigned i = 0; i < Next.getNumResults(); ++i)
          Names[Next.getResult(i)] = this->name(Cur.getResult(i));
        emitRegion(Next.getThenRegion(), Indent);
        return;
      }
      if (InnerFold == 0) {
        for (unsigned i = 0; i < Next.getNumResults(); ++i)
          Names[Next.getResult(i)] = this->name(Cur.getResult(i));
        if (!Next.getElseRegion().empty())
          emitRegion(Next.getElseRegion(), Indent);
        return;
      }
      // Alias the inner if's result SSA values to the parent's result-
      // local names so the inner yield assigns to the shared variable.
      for (unsigned i = 0; i < Next.getNumResults(); ++i)
        Names[Next.getResult(i)] = this->name(Cur.getResult(i));
      indent(Indent);
      OS << "elif " << this->stmtExpr(Next.getCondition()) << ":\n";
      if (countEmittedStmts(Next.getThenRegion().front(), InlinedOps,
                             SuppressedOps) == 0) {
        indent(Indent + 1); OS << "pass\n";
      } else {
        emitRegion(Next.getThenRegion(), Indent + 1);
      }
      Cur = Next;
    }

    if (!Cur.getElseRegion().empty() &&
        countEmittedStmts(Cur.getElseRegion().front(), InlinedOps,
                           SuppressedOps) > 0) {
      indent(Indent);
      OS << "else:\n";
      emitRegion(Cur.getElseRegion(), Indent + 1);
    }
    /* Flush deferred snapshot prelude after the last reset arm
     * closes. ResetArmGuards is populated for shape-2 isempty/
     * reset arms (see persistent-read snapshot pass). On reset
     * cycles this guarantees the snapshot captures the
     * post-reset register value, matching SV's async-low reset
     * propagation through always_comb. */
    if (auto It = ResetArmGuards.find(&Op); It != ResetArmGuards.end()) {
      ResetArmGuards.erase(It);
      if (ResetArmGuards.empty() && !PendingSnapshotPrelude.empty()) {
        OS << PendingSnapshotPrelude;
        PendingSnapshotPrelude.clear();
      }
    }
    return;
  }

  // scf.yield inside scf.if / scf.while: assign to the parent's result
  // / iter-arg locals.
  if (auto Y = mlir::dyn_cast<mlir::scf::YieldOp>(Op)) {
    auto *Parent = Op.getParentOp();
    if (auto If = mlir::dyn_cast<mlir::scf::IfOp>(Parent)) {
      for (unsigned i = 0; i < Y.getNumOperands(); ++i) {
        indent(Indent);
        OS << this->name(If.getResult(i)) << " = "
           << this->stmtExpr(Y.getOperand(i)) << "\n";
      }
      return;
    }
    if (auto W = mlir::dyn_cast<mlir::scf::WhileOp>(Parent)) {
      for (unsigned i = 0; i < Y.getNumOperands(); ++i) {
        auto BA = W.getBefore().front().getArgument(i);
        indent(Indent);
        OS << this->name(BA) << " = " << this->stmtExpr(Y.getOperand(i))
           << "\n";
      }
      return;
    }
    return;
  }

  // --- scf.while ------------------------------------------------------
  if (auto W = mlir::dyn_cast<mlir::scf::WhileOp>(Op)) {
    auto &Before = W.getBefore().front();
    auto &After = W.getAfter().front();

    // Did the pre-scan flag this loop as a canonical MATLAB for-loop?
    auto FPIt = ForPatterns.find(W.getOperation());
    if (FPIt != ForPatterns.end()) {
      const ForLoopInfo &Info = FPIt->second;
      Names[Before.getArgument(0)] = Info.IvName;
      InlineExprs[After.getArgument(0)] = Info.IvName;
      if (W.getNumResults() == 1)
        InlineExprs[W.getResult(0)] = Info.IvName;

      // Prefer Python's int `range(...)` when init/end/step are integer
      // literals; otherwise fall back to a runtime helper so floating-
      // point steps and runtime-computed bounds still iterate correctly.
      long long IInit, IEnd, IStep;
      bool IntForm = forBoundsAreIntLiterals(Info, IInit, IEnd, IStep) &&
                     IStep != 0;
      indent(Indent);
      if (IntForm) {
        long long Stop = (IStep > 0) ? IEnd + 1 : IEnd - 1;
        OS << "for " << Info.IvName << " in range("
           << IInit << ", " << Stop;
        if (IStep != 1) OS << ", " << IStep;
        OS << "):\n";
      } else {
        OS << "for " << Info.IvName << " in rt.frange("
           << this->stmtExpr(Info.Init) << ", "
           << this->stmtExpr(Info.End) << ", "
           << this->stmtExpr(Info.Step) << "):\n";
      }
      // Body: emit every after-region op except the absorbed addf and
      // the trailing yield (already in SuppressedOps via scanForLoopPatterns).
      int EmittedStmts = 0;
      for (auto &Inner : After.getOperations()) {
        if (mlir::isa<mlir::scf::YieldOp>(&Inner)) continue;
        if (InlinedOps.count(&Inner)) continue;
        if (SuppressedOps.count(&Inner)) continue;
        ++EmittedStmts;
      }
      if (EmittedStmts == 0) {
        indent(Indent + 1); OS << "pass\n";
      } else {
        for (auto &Inner : After.getOperations())
          emitOp(Inner, Indent + 1);
      }
      return;
    }

    for (unsigned i = 0; i < W.getInits().size(); ++i) {
      auto BA = Before.getArgument(i);
      std::string N = freshName();
      Names[BA] = N;
      indent(Indent);
      OS << N << " = " << this->stmtExpr(W.getInits()[i]) << "\n";
    }
    for (unsigned i = 0; i < W.getNumResults(); ++i) {
      auto BA = Before.getArgument(i);
      Names[W.getResult(i)] = Names[BA];
    }

    bool BeforeIsCondOnly = true;
    for (auto &Inner : Before.getOperations()) {
      if (mlir::isa<mlir::scf::ConditionOp>(Inner)) continue;
      if (InlinedOps.count(&Inner)) continue;
      BeforeIsCondOnly = false;
      break;
    }

    // Render a loop condition with break/continue-flag inversions
    // stripped: `while cond & !did_break` → `while cond` once we're
    // emitting native `break` / `continue`. An entirely stripped
    // condition collapses to `True`.
    auto emitStrippedCond = [&](mlir::Value V) -> std::string {
      llvm::SmallVector<mlir::Value, 2> Parts;
      gatherNonFlagConjuncts(V, Parts);
      if (Parts.empty()) return "True";
      std::string Out;
      for (unsigned i = 0; i < Parts.size(); ++i) {
        if (i) Out += " and ";
        Out += this->stmtExpr(Parts[i]);
      }
      return Out;
    };

    if (BeforeIsCondOnly) {
      auto Cond = mlir::cast<mlir::scf::ConditionOp>(Before.getTerminator());
      for (unsigned i = 0; i < Cond.getArgs().size(); ++i) {
        auto AA = After.getArgument(i);
        InlineExprs[AA] = this->exprFor(Cond.getArgs()[i]);
      }
      indent(Indent);
      OS << "while " << emitStrippedCond(Cond.getCondition()) << ":\n";
      int EmittedStmts = 0;
      for (auto &Inner : After.getOperations()) {
        if (!InlinedOps.count(&Inner) &&
            !mlir::isa<mlir::scf::YieldOp, mlir::scf::ConditionOp>(&Inner))
          ++EmittedStmts;
      }
      if (EmittedStmts == 0 && After.getOperations().size() <= 1) {
        indent(Indent + 1); OS << "pass\n";
      } else {
        for (auto &Inner : After.getOperations())
          emitOp(Inner, Indent + 1);
      }
      return;
    }

    indent(Indent);
    OS << "while True:\n";
    for (auto &Inner : Before.getOperations()) {
      if (auto Cond = mlir::dyn_cast<mlir::scf::ConditionOp>(Inner)) {
        std::string CondStr = emitStrippedCond(Cond.getCondition());
        if (CondStr != "True") {
          indent(Indent + 1);
          OS << "if not (" << CondStr << "): break\n";
        }
        for (unsigned i = 0; i < Cond.getArgs().size(); ++i) {
          auto AA = After.getArgument(i);
          InlineExprs[AA] = this->exprFor(Cond.getArgs()[i]);
        }
        continue;
      }
      emitOp(Inner, Indent + 1);
    }
    for (auto &Inner : After.getOperations())
      emitOp(Inner, Indent + 1);
    return;
  }

  // --- Slot triplet (matlab.alloc / matlab.store / matlab.load) ----
  // Survive into Python emit on HDL-targeted code where the slot's
  // type stays `none` (RefineSlotTypes leaves conditionally-stored
  // slots unrefined; LowerScalarSlots doesn't promote them either).
  // For Python, an unrefined slot is harmless — bind the alloc's
  // SSA value to its source-level name and the load/store ops
  // collapse to plain Python variable reads / writes.
  if (Name == "matlab.alloc" && Op.getNumResults() == 1) {
    if (auto NA = Op.getAttrOfType<mlir::StringAttr>("name")) {
      std::string SlotName = sanitizeIdent(NA.getValue());
      Names[Op.getResult(0)] = SlotName;
      DirectSlots[&Op] = SlotName;
    }
    return;
  }
  if (Name == "matlab.store" && Op.getNumOperands() == 2) {
    auto *AddrDef = Op.getOperand(1).getDefiningOp();
    if (AddrDef && DirectSlots.count(AddrDef)) {
      indent(Indent);
      OS << DirectSlots[AddrDef] << " = "
         << this->stmtExpr(Op.getOperand(0)) << "\n";
      return;
    }
  }
  if (Name == "matlab.load" && Op.getNumOperands() == 1 &&
      Op.getNumResults() == 1) {
    // Loads inline at use site via exprFor (which resolves through
    // DirectSlots). No statement to emit.
    return;
  }

  // --- Unregistered matlab.call_builtin sites that survive to emit
  // time (Python pipeline doesn't run LowerFixedPoint). Render the
  // persistent-set form as `<fn>.<name> = <v>` to match the static
  // decl emitted alongside the function body. Other matlab.* op
  // shapes fall through to the unsupported diagnostic.
  if (Name == "matlab.call_builtin") {
    auto CA = Op.getAttrOfType<mlir::StringAttr>("callee");
    if (CA && CA.getValue() == "matlab_global_set_f64" &&
        Op.getNumOperands() == 2) {
      auto PN = Op.getAttrOfType<mlir::StringAttr>("persistent_name");
      auto PF = Op.getAttrOfType<mlir::StringAttr>("persistent_fn");
      if (PN && PF) {
        indent(Indent);
        // Wrap to the declared fi width when the call carries
        // fi_wl / fi_signed attrs so the Python ref matches the SV
        // DUT's two's-complement overflow behaviour. HDL-style
        // designs (CRC, FNV, LFSR, integrators) routinely depend on
        // wrap-on-overflow and would diverge under MATLAB's default
        // saturate semantics. Bare global_set_f64 (no fi attrs)
        // emits the value as-is.
        std::string V = this->stmtExpr(Op.getOperand(1));
        // Prefer the persistent's pre-computed wrap-spec captured
        // by the early walk. The early walk anchors on the FIRST
        // reliably-typed set (typically the init `<reg> = init_value`
        // pattern), which carries the source-level declared width.
        // Later body-side sets carry MATLAB's bit-growth tracking
        // attrs (e.g. `fi_wl=23` on `int1 + x` where int1 is i22) —
        // those are operation-natural widths, not the storage width.
        // The SV reg is sized to the source-declared width and the
        // implicit assignment truncates; the Python ref needs the
        // same truncation to match.
        auto WLA = Op.getAttrOfType<mlir::IntegerAttr>("fi_wl");
        auto SgnA = Op.getAttrOfType<mlir::IntegerAttr>("fi_signed");
        int WL = 0;
        bool Signed = false;
        bool HasSpec = false;
        auto It = PersistWrapSpec.find(PN.getValue());
        if (It != PersistWrapSpec.end()) {
          WL = It->second.WL;
          Signed = It->second.Signed;
          HasSpec = true;
        } else if (WLA && SgnA) {
          WL = (int)WLA.getInt();
          Signed = SgnA.getInt() != 0;
          HasSpec = true;
        } else if (auto IT = mlir::dyn_cast<mlir::IntegerType>(
                       Op.getOperand(1).getType())) {
          WL = (int)IT.getWidth();
          Signed = false;
          if (WL >= 1 && WL <= 64) HasSpec = true;
        }
        if (HasSpec) {
          V = std::string(Signed ? "rt.fi_wrap_s(" : "rt.fi_wrap_u(") +
              dropOuterParens(V) + ", " + std::to_string(WL) + ")";
        }
        OS << PF.getValue().str() << "." << PN.getValue().str()
           << " = " << V << "\n";
        return;
      }
    }
    // Bitwise builtins that stayed at the matlab.call_builtin level
    // because LowerScalarsToArith didn't lower them (typed-int
    // dispatch missed because some operand was none-typed). Render
    // as the equivalent Python expression and bind to the result
    // SSA name so consumers see a stable Python identifier.
    if (CA && Op.getNumResults() == 1) {
      llvm::StringRef Cn = CA.getValue();
      auto emitBin = [&](const char *Cc) {
        indent(Indent);
        std::string N = this->name(Op.getResult(0));
        OS << N << " = " << this->stmtExpr(Op.getOperand(0)) << " " << Cc
           << " " << this->stmtExpr(Op.getOperand(1)) << "\n";
      };
      if (Cn == "bitand" && Op.getNumOperands() == 2) { emitBin("&"); return; }
      if (Cn == "bitor"  && Op.getNumOperands() == 2) { emitBin("|"); return; }
      if (Cn == "bitxor" && Op.getNumOperands() == 2) { emitBin("^"); return; }
      if (Cn == "bitshift" && Op.getNumOperands() == 2) {
        // bitshift(a, k): k > 0 left-shift, k < 0 right-shift.
        // Python doesn't have a sign-driven bitshift, so render as
        // a conditional. The amount is almost always a folded
        // constant; we emit the chosen direction directly when so.
        indent(Indent);
        std::string N = this->name(Op.getResult(0));
        mlir::APInt KVal;
        if (mlir::matchPattern(Op.getOperand(1),
                                mlir::m_ConstantInt(&KVal))) {
          int64_t K = KVal.getSExtValue();
          if (K >= 0)
            OS << N << " = " << this->stmtExpr(Op.getOperand(0))
               << " << " << K << "\n";
          else
            OS << N << " = " << this->stmtExpr(Op.getOperand(0))
               << " >> " << -K << "\n";
        } else {
          // Variable shift: emit a runtime select on the sign.
          OS << N << " = (" << this->stmtExpr(Op.getOperand(0))
             << " << " << this->stmtExpr(Op.getOperand(1))
             << ") if " << this->stmtExpr(Op.getOperand(1))
             << " >= 0 else (" << this->stmtExpr(Op.getOperand(0))
             << " >> -(" << this->stmtExpr(Op.getOperand(1)) << "))\n";
        }
        return;
      }
      if (Cn == "bitcmp" && Op.getNumOperands() == 1) {
        indent(Indent);
        std::string N = this->name(Op.getResult(0));
        OS << N << " = ~" << this->stmtExpr(Op.getOperand(0)) << "\n";
        return;
      }
    }
  }

  // --- Fallback -------------------------------------------------------
  indent(Indent);
  OS << "# UNSUPPORTED: " << Name.str() << "\n";
  fail(("unsupported op in emitter: " + Name).str());
}

} // namespace

// Locate the rendered first newline so we can splice imports between
// the `# Generated ...` header line and the rest of the body.
static size_t firstNewlineAfterHeader(llvm::StringRef Body) {
  size_t Pos = Body.find('\n');
  return Pos == llvm::StringRef::npos ? Body.size() : Pos + 1;
}

// True iff the body actually references `<prefix>` as a symbol — checked
// via a small word-boundary scan so we don't match the substring inside
// a comment, identifier, or string literal that happens to contain it.
static bool bodyReferencesSymbol(llvm::StringRef Body,
                                 llvm::StringRef Prefix) {
  size_t I = 0;
  while ((I = Body.find(Prefix, I)) != llvm::StringRef::npos) {
    // Reject when the preceding character is part of an identifier — it
    // would mean we matched in the middle of a longer name like `art.x`.
    if (I > 0) {
      char C = Body[I - 1];
      if (std::isalnum((unsigned char)C) || C == '_') {
        I += Prefix.size();
        continue;
      }
    }
    // Reject matches inside a `# ...` comment line. Walk back to the
    // nearest newline; if we hit a `#` first, this match is in a comment.
    bool InComment = false;
    for (ssize_t J = (ssize_t)I - 1; J >= 0 && Body[J] != '\n'; --J) {
      if (Body[J] == '#') { InComment = true; break; }
    }
    if (InComment) { I += Prefix.size(); continue; }
    return true;
  }
  return false;
}

std::string emitPython(mlir::ModuleOp M, bool NoLine,
                       const matlab::SourceManager *SM) {
  /* Phase 6: the Python runtime ships no Symbolic Math Toolbox bridge
   * — it would route through SymPy but the emitter doesn't translate
   * the matlab_sym_* call shape to SymPy yet. Diagnose at the start
   * rather than silently emit code that fails at import. */
  bool HasSym = false;
  M.walk([&](mlir::Operation *Op) {
    if (HasSym) return;
    /* Pre-LLVM dialect: matlab.call_builtin carries the callee as a
     * StringAttr. Post-LLVM-conversion: llvm.func declarations carry
     * the runtime name as the symbol name. Check both so the
     * diagnostic fires regardless of where in the pipeline we run. */
    if (auto Cal = Op->getAttrOfType<mlir::StringAttr>("callee"))
      if (Cal.getValue().starts_with("matlab_sym_")) { HasSym = true; return; }
    if (auto F = mlir::dyn_cast<mlir::LLVM::LLVMFuncOp>(Op))
      if (F.getName().starts_with("matlab_sym_")) HasSym = true;
  });
  if (HasSym) {
    llvm::errs() << "error: -emit-python does not support the Symbolic "
                 << "Math Toolbox (matlab_sym_*) — use -emit-cpp / "
                 << "-emit-llvm or remove the symbolic operations\n";
    return {};
  }
  std::ostringstream OSS;
  Emitter E(OSS, NoLine, SM);
  if (!E.run(M)) return {};
  std::string Body = OSS.str();

  // Splice in only the imports the body actually references. Most
  // emitted programs use `rt.<helper>` for runtime calls; numpy is only
  // pulled in when a future emit path needs it (none today). Skipping
  // the unused imports keeps the generated source from claiming
  // dependencies it doesn't use.
  size_t SpliceAt = firstNewlineAfterHeader(Body);
  std::string Imports;
  if (bodyReferencesSymbol(Body, "rt."))
    Imports += "import matlab_runtime as rt\n";
  if (bodyReferencesSymbol(Body, "np."))
    Imports += "import numpy as np\n";
  // One blank line separates the header (and any imports) from the
  // body proper, keeping the file layout consistent regardless of
  // whether imports were added.
  Imports += "\n";

  return Body.substr(0, SpliceAt) + Imports + Body.substr(SpliceAt);
}

} // namespace mlirgen
} // namespace matlab