execsql2 2.34.0__py3-none-any.whl → 2.37.0__py3-none-any.whl

execsql/script/executor.py

@@ -63,11 +63,13 @@ from execsql.script.ast import (
     Script,
     ScriptBlock,
     SqlBlock,
+    SourceSpan,
     SqlStatement,
 )
 from execsql import manifest as _manifest
+from execsql.script.parser import substitute_directive
 from execsql.script.engine import set_dynamic_system_vars, set_static_system_vars, substitute_vars
-from execsql.script.variables import SubVarSet
+from execsql.script.variables import ScriptArgSubVarSet, SubVarSet
 from execsql.state import ExecFrame, RuntimeContext, active_context, get_context, xcmd_test
 from execsql.utils.errors import exception_desc, exit_now, logged_error, stamp_errinfo
 
@@ -85,6 +87,14 @@ _DEFER_RX = re.compile(r"!\{([$@&~#+]?\w+)\}!")
 _VARLIKE = re.compile(r"!![$@&~#]?\w+!!", re.I)
 
 
+def _warn_unsubstituted(cmd: str) -> None:
+    """Log a command that still looks like it holds a variable; print it too if ``write_warnings`` is on."""
+    from execsql.utils.errors import write_warning
+    from execsql.utils.fileio import redact
+
+    write_warning(f"There is a potential un-substituted variable in the command\n     {redact(cmd)}")
+
+
 def _stack_localvars(ctx: RuntimeContext) -> SubVarSet | None:
     """Build the merged ``~`` local + ``#`` param overlay for the current scope.
 
@@ -169,39 +179,64 @@ def _convert_deferred_vars(text: str) -> str:
     return _DEFER_RX.sub(r"!!\1!!", text)
 
 
-def _eval_condition(
+def _condition_holds(
     ctx: RuntimeContext,
+    command: str,
+    span: SourceSpan,
     condition: str,
     modifiers: list[ConditionModifier] | None = None,
 ) -> bool:
-    """Evaluate a condition string with optional ANDIF/ORIF modifiers.
+    """Evaluate the condition of IF, ELSEIF, LOOP or EXECUTE SCRIPT … WHILE / UNTIL, with its ANDIF / ORIF modifiers.
 
     Short-circuits ANDIF (stops on first False) and ORIF (stops on first True)
     so that patterns like ``IF (sub_defined(x)) ANDIF (not sub_empty(x))``
     don't evaluate ``sub_empty`` when ``x`` is undefined.
+
+    *command* is the metacommand as written, on the line *span* starts; an
+    error is reported there, or on the ANDIF / ORIF that raised it.
     """
     effective_locals = _stack_localvars(ctx)
-    expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-    result = xcmd_test(expanded)
-
-    if modifiers:
-        for mod in modifiers:
-            # Short-circuit: AND with False can't become True,
-            # OR with True can't become False.
-            if mod.kind == "AND" and not result:
-                continue
-            if mod.kind == "OR" and result:
-                continue
-            mod_expanded = substitute_vars(mod.condition, effective_locals, ctx=ctx)
-            mod_result = xcmd_test(mod_expanded)
-            if mod.kind == "AND":
-                result = result and mod_result
-            else:  # OR
-                result = result or mod_result
-
+    result = _test(ctx, command, span, condition, effective_locals)
+    for mod in modifiers or []:
+        # Short-circuit: AND with False can't become True,
+        # OR with True can't become False.
+        if (mod.kind == "AND" and not result) or (mod.kind == "OR" and result):
+            continue
+        keyword = "ANDIF" if mod.kind == "AND" else "ORIF"
+        result = _test(ctx, f"{keyword} ({mod.condition})", mod.span, mod.condition, effective_locals)
     return result
 
 
+def _test(
+    ctx: RuntimeContext,
+    command: str,
+    span: SourceSpan,
+    condition: str,
+    localvars: SubVarSet | None,
+) -> bool:
+    """One condition of *command*: its value.
+
+    A condition that cannot be evaluated stops the run.  Its error is raised
+    with the line and text of *command*, which may be an ELSEIF, ANDIF or
+    ORIF rather than the statement on record, or a loop condition evaluated
+    after its body.
+    """
+    try:
+        return xcmd_test(substitute_vars(condition, localvars, ctx=ctx))
+    except Exception as exc:
+        e = _as_errinfo(exc)
+        if e.script_file is None:
+            e.script_file, e.script_line_no = span.file, span.start_line
+            e.cmd, e.cmdtype = command, "cmd"
+        # The run stops, except at a BREAKPOINT prompt, which carries on:
+        # a test that failed in the database (HASROWS) has rolled back the
+        # connection, so the batch must not commit.
+        _fail_open_batches(ctx, span.file, span.start_line)
+        if e is exc:
+            raise
+        raise e from exc
+
+
 def _set_command_vars(ctx: RuntimeContext, source: str, line_no: int) -> None:
     """Set per-command system variables (current script, line, time)."""
     assert ctx.subvars is not None
@@ -254,11 +289,7 @@ def _exec_sql(
     effective_locals = _stack_localvars(ctx) or localvars
     cmd = substitute_vars(text, effective_locals, ctx=ctx)
     if _VARLIKE.search(cmd):
-        from execsql.utils.fileio import redact
-
-        output.write(
-            f"Warning: There is a potential un-substituted variable in the command\n     {redact(cmd)}\n",
-        )
+        _warn_unsubstituted(cmd)
     e = None
     result = None
     try:
@@ -271,34 +302,97 @@ def _exec_sql(
             db.execute(cmd)
         if commit:
             db.commit()
-    except ErrInfo as errinfo:
-        e = errinfo
-    except SystemExit:
-        raise
     except Exception as exc:
-        e = ErrInfo(type="exception", exception_msg=exception_desc())
-        e.__cause__ = exc  # the driver's own message, which a prompt shows
+        e = _as_errinfo(exc)
     if e:
-        stamp_errinfo(e)
-        subvars.add_substitution("$LAST_ERROR", cmd)
-        subvars.add_substitution("$ERROR_MESSAGE", e.errmsg())
-        status.sql_error = True
-        if ctx.exec_log is not None:
-            ctx.exec_log.log_status_info(f"SQL error: {logged_error(e)}")
-        if status.halt_on_err:
-            exit_now(1, e)
-        status.error_history.append((source, line_no, cmd, e.errmsg()))
+        _sql_failed(ctx, e, cmd, source, line_no)
         return
     subvars.add_substitution("$LAST_SQL", cmd)
     if ctx.prompt_input is not None:
         ctx.prompt_input(result)
 
 
+def _sql_failed(ctx: RuntimeContext, e: ErrInfo, cmd: str, source: str, line_no: int) -> None:
+    """Report an SQL error: halt under ERROR_HALT ON, else record it and carry on.
+
+    Sets ``$LAST_ERROR`` to *cmd*, ``$ERROR_MESSAGE`` and ``SQL_ERROR()``.
+    """
+    assert ctx.status is not None
+    assert ctx.subvars is not None
+    stamp_errinfo(e)
+    ctx.subvars.add_substitution("$LAST_ERROR", cmd)
+    ctx.subvars.add_substitution("$ERROR_MESSAGE", e.errmsg())
+    ctx.status.sql_error = True
+    if ctx.exec_log is not None:
+        ctx.exec_log.log_status_info(f"SQL error: {logged_error(e)}")
+    _fail_open_batches(ctx, source, line_no)
+    if ctx.status.halt_on_err:
+        exit_now(1, e)
+    ctx.status.error_history.append((source, line_no, cmd, e.errmsg()))
+
+
 # ---------------------------------------------------------------------------
 # Metacommand execution
 # ---------------------------------------------------------------------------
 
 
+def _as_errinfo(exc: Exception) -> ErrInfo:
+    """*exc* as an :class:`ErrInfo`: itself if it is one, else an exception report.
+
+    The report keeps *exc* as its ``__cause__``: the driver's or parser's own
+    message, which a prompt shows.  Call it in the ``except`` clause, where
+    :func:`exception_desc` can still see the exception.
+    """
+    if isinstance(exc, ErrInfo):
+        return exc
+    e = ErrInfo(type="exception", exception_msg=exception_desc())
+    e.__cause__ = exc
+    return e
+
+
+def _fail_open_batches(ctx: RuntimeContext, source: str, line_no: int) -> None:
+    """Keep every open batch from committing after an error inside it.
+
+    Whatever failed (a statement, a metacommand, or SQL a metacommand ran),
+    the batch is not committed: a database error may already have rolled
+    back the batch's earlier work, and execsql cannot tell from here whether
+    it did.
+    """
+    assert ctx.status is not None
+    if ctx.status.batch.in_batch():
+        ctx.status.batch.fail_enclosing(f"an error on line {line_no} of {source}")
+
+
+def _metacommand_failed(
+    ctx: RuntimeContext,
+    cmd: str,
+    e: ErrInfo,
+    source: str,
+    line_no: int,
+    *,
+    always_halt: bool = False,
+) -> None:
+    """Record a failed metacommand; stop the run if METACOMMAND_ERROR_HALT is on, or *always_halt*.
+
+    With it off the script carries on, and ``METACOMMAND_ERROR()``,
+    ``$LAST_ERROR`` and ``$ERROR_MESSAGE`` say what failed.
+    """
+    status = ctx.status
+    subvars = ctx.subvars
+    assert status is not None
+    assert subvars is not None
+    stamp_errinfo(e)
+    status.metacommand_error = True
+    subvars.add_substitution("$LAST_ERROR", cmd)
+    subvars.add_substitution("$ERROR_MESSAGE", e.errmsg())
+    if ctx.exec_log is not None:
+        ctx.exec_log.log_status_info(f"Metacommand error: {logged_error(e)}")
+    _fail_open_batches(ctx, source, line_no)
+    if status.halt_on_metacommand_err or always_halt:
+        exit_now(1, e)
+    status.error_history.append((source, line_no, cmd, e.errmsg()))
+
+
 def _exec_metacommand(
     ctx: RuntimeContext,
     cmd: str,
@@ -323,11 +417,7 @@ def _exec_metacommand(
     assert subvars is not None
 
     if _VARLIKE.search(cmd):
-        from execsql.utils.fileio import redact
-
-        output.write(
-            f"Warning: There is a potential un-substituted variable in the command\n     {redact(cmd)}\n",
-        )
+        _warn_unsubstituted(cmd)
     e = None
     try:
         applies, result = metacommandlist.eval(cmd)
@@ -335,28 +425,16 @@ def _exec_metacommand(
             if (manifest := _manifest.current()) is not None:
                 manifest.record_metacommand(cmd, source, line_no, metacommandlist)
             return result
-    except ErrInfo as errinfo:
-        e = errinfo
-    except SystemExit:
-        raise
     except Exception as exc:
-        e = ErrInfo(type="exception", exception_msg=exception_desc())
-        e.__cause__ = exc
+        e = _as_errinfo(exc)
     if e:
-        stamp_errinfo(e)
-        status.metacommand_error = True
-        subvars.add_substitution("$LAST_ERROR", cmd)
-        subvars.add_substitution("$ERROR_MESSAGE", e.errmsg())
-        if ctx.exec_log is not None:
-            ctx.exec_log.log_status_info(f"Metacommand error: {logged_error(e)}")
-        if status.halt_on_metacommand_err:
-            exit_now(1, e)
+        _metacommand_failed(ctx, cmd, e, source, line_no)
         if (manifest := _manifest.current()) is not None:
             manifest.record_metacommand(cmd, source, line_no, metacommandlist)
-        status.error_history.append((source, line_no, cmd, e.errmsg()))
         return None
     # No handler matched — truly unknown metacommand
     status.metacommand_error = True
+    _fail_open_batches(ctx, source, line_no)
     raise ErrInfo(type="cmd", command_text=cmd, other_msg="Unknown metacommand")
 
 
@@ -443,10 +521,22 @@ def _execute_node(
         # !!$COUNTER_N!! and re-roll !!$RANDOM!!/!!$UUID!! references.
         effective_locals = _stack_localvars(ctx) or localvars
         expanded = substitute_vars(command, effective_locals, ctx=ctx)
-        if _BREAK_RX.match(expanded):
-            raise _BreakLoop
         ctx.last_command = ExecutingStatement(node)
-        _exec_metacommand(ctx, expanded, node.span.file, node.span.start_line)
+        if not _BREAK_RX.match(expanded):
+            _exec_metacommand(ctx, expanded, node.span.file, node.span.start_line)
+        elif _break_has_target(ctx):
+            raise _BreakLoop
+        else:
+            _metacommand_failed(
+                ctx,
+                expanded,
+                ErrInfo(
+                    type="cmd",
+                    other_msg="BREAK has nothing to leave: it is not inside a LOOP, SCRIPT or included file.",
+                ),
+                node.span.file,
+                node.span.start_line,
+            )
 
     elif isinstance(node, IfBlock):
         ctx.last_command = ExecutingStatement(node)
@@ -499,7 +589,7 @@ def _execute_if(
     """
     from execsql.state import ExecFrame
 
-    if _eval_condition(ctx, node.condition, node.condition_modifiers):
+    if _condition_holds(ctx, node.command, node.span, node.condition, node.condition_modifiers):
         _push_block_frame(
             ctx,
             ExecFrame(kind="if", label=node.condition, source=node.span.file, line=node.span.start_line),
@@ -512,7 +602,7 @@ def _execute_if(
 
     # Try ELSEIF clauses
     for clause in node.elseif_clauses:
-        if _eval_condition(ctx, clause.condition, clause.condition_modifiers):
+        if _condition_holds(ctx, clause.command, clause.span, clause.condition, clause.condition_modifiers):
             _push_block_frame(
                 ctx,
                 ExecFrame(kind="elseif", label=clause.condition, source=node.span.file, line=node.span.start_line),
@@ -552,9 +642,8 @@ def _execute_loop(
     try:
         if node.loop_type == "WHILE":
             while True:
-                effective_locals = _stack_localvars(ctx)
-                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-                if not xcmd_test(expanded):
+                ctx.last_command = ExecutingStatement(node)
+                if not _condition_holds(ctx, node.command, node.span, condition):
                     break
                 frame.iteration += 1
                 try:
@@ -568,9 +657,8 @@ def _execute_loop(
                     _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=True)
                 except _BreakLoop:
                     break
-                effective_locals = _stack_localvars(ctx)
-                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-                if xcmd_test(expanded):
+                ctx.last_command = ExecutingStatement(node)
+                if _condition_holds(ctx, node.command, node.span, condition):
                     break
     finally:
         ctx.ast_exec_stack.pop()
@@ -583,7 +671,19 @@ def _execute_batch(
     *,
     in_loop: bool = False,
 ) -> None:
-    """Execute a BEGIN BATCH / END BATCH block."""
+    """Execute a BEGIN BATCH / END BATCH block.
+
+    Reaching END BATCH commits the batch; a commit that fails is an SQL error
+    on the END BATCH line, after the batch's uncommitted databases are rolled
+    back, and every enclosing batch then rolls back at its own END BATCH
+    instead of committing. Leaving it any other way (BREAK,
+    an error, HALT) abandons it: see
+    :meth:`~execsql.script.control.BatchLevels.abandon_batch` for when that
+    rolls back and when an enclosing batch takes the statements over.  A
+    halt usually gets there first: :func:`~execsql.utils.errors.exit_now`
+    abandons every open batch before an ON ERROR_HALT script runs, so
+    nothing is left to do here.
+    """
     from execsql.state import ExecFrame
 
     status = ctx.status
@@ -593,12 +693,35 @@ def _execute_batch(
         ctx,
         ExecFrame(kind="batch", label="", source=node.span.file, line=node.span.start_line),
     )
+    completed = False
     try:
         _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=in_loop)
+        completed = True
     finally:
         ctx.ast_exec_stack.pop()
-        if status.batch.in_batch():
+        if status.batch.in_batch() and not completed:
+            status.batch.abandon_batch()
+    if status.batch.in_batch():
+        end_line = node.span.effective_end_line
+        ctx.last_command = ExecutingStatement(
+            MetaCommandStatement(span=SourceSpan(node.span.file, end_line), command="END BATCH"),
+        )
+        failure = status.batch.failure()
+        if failure is not None:
+            status.batch.abandon_batch()
+            e = ErrInfo(type="error", other_msg=f"The batch was not committed: {failure}.")
+            _sql_failed(ctx, e, "END BATCH", node.span.file, end_line)
+            return
+        # The commit is the batch's last SQL: SQL_ERROR() right after END
+        # BATCH says whether it failed, as after any statement.
+        status.sql_error = False
+        try:
             status.batch.end_batch()
+        except Exception as exc:
+            # end_batch has rolled back what it had not committed, which can
+            # include an enclosing batch's statements on a shared connection;
+            # _sql_failed keeps that batch from committing the rest.
+            _sql_failed(ctx, _as_errinfo(exc), "END BATCH", node.span.file, end_line)
 
 
 def _pre_register_scripts(ctx: RuntimeContext, nodes: list[Node]) -> None:
@@ -649,107 +772,123 @@ def _execute_include(
     node: IncludeDirective,
     localvars: SubVarSet | None = None,
 ) -> None:
-    """Execute an INCLUDE or EXECUTE SCRIPT directive.
-
-    **INCLUDE** is handled natively: the target file is parsed by the AST
-    parser and executed through the AST executor with circular-include
-    detection.
+    """Run an INCLUDE or EXECUTE SCRIPT written in the script.
 
-    **EXECUTE SCRIPT** is handled natively when the target is in
-    ``ctx.ast_scripts``: arguments are parsed, a local variable overlay
-    is created, and the body is executed through the AST executor.
-    WHILE/UNTIL loops are handled natively too.
+    Variables in its file, script name and arguments are substituted once,
+    as in any other metacommand, so ``!!$COUNTER_1!!`` counts once and
+    ``$LAST_ERROR`` holds the text that ran.  An EXECUTE SCRIPT ``WHILE`` /
+    ``UNTIL`` condition is substituted on each pass instead.
     """
-    if node.is_execute_script:
-        # Substitute variables in the target — the script name may be passed
-        # as a parameter (e.g., EXECUTE SCRIPT !!#script_name!!).
-        effective_locals = _stack_localvars(ctx) or localvars
-        target = substitute_vars(node.target, effective_locals, ctx=ctx).strip().lower()
-
-        # Native path: target is in our AST registry
-        if target in ctx.ast_scripts:
-            _execute_script_native(ctx, node, ctx.ast_scripts[target], localvars)
-            return
-
-        # Target not registered — IF EXISTS silently skips; otherwise error.
-        if node.if_exists:
-            return
-        raise ErrInfo(
-            "cmd",
-            other_msg=f"There is no SCRIPT named {node.target}.",
-        )
-
-    # --- INCLUDE (file inclusion) — parse and execute natively ---
-    _execute_include_native(ctx, node, localvars)
+    effective_locals = _stack_localvars(ctx) or localvars
+    directive = substitute_directive(node, lambda text: substitute_vars(text, effective_locals, ctx=ctx))
+    _run_directive(ctx, directive, localvars)
 
 
-def _execute_script_native(
+def _run_directive(
     ctx: RuntimeContext,
     node: IncludeDirective,
-    script_block: ScriptBlock,
     localvars: SubVarSet | None = None,
 ) -> None:
-    """Execute a SCRIPT block natively through the AST executor.
+    """Run an INCLUDE or EXECUTE SCRIPT whose variables have been substituted.
 
-    Pushes a SCRIPT-kind :class:`~execsql.state.ExecFrame` onto
-    ``ctx.ast_exec_stack`` so that metacommand handlers (``x_sub``,
-    ``x_rm_sub``, ``xf_sub_defined``, prompt handlers, etc.) can access
-    ``~`` local variables and ``#`` script arguments via
-    ``ctx.current_localvars()`` / ``ctx.current_paramvals()``. The frame
-    is popped on exit (including on error) via ``try/finally``.
+    **INCLUDE** parses the target file with the AST parser and executes it
+    with circular-include detection.  **EXECUTE SCRIPT** runs a SCRIPT
+    registered in ``ctx.ast_scripts`` with its arguments in a local variable
+    overlay, once or in a WHILE / UNTIL loop.
+
+    The INCLUDE or EXECUTE SCRIPT failing itself (no such file or script, a
+    missing argument) is a metacommand error; see :func:`_directive_failed`.
+    """
+    if (manifest := _manifest.current()) is not None:
+        assert ctx.metacommandlist is not None
+        manifest.record_metacommand(node.command, node.span.file, node.span.start_line, ctx.metacommandlist)
+
+    if not node.is_execute_script:
+        _execute_include_native(ctx, node, localvars)
+        return
+
+    target = node.target.strip().lower()
+    script_block = ctx.ast_scripts.get(target)
+    if script_block is None:
+        # IF EXISTS silently skips a SCRIPT that is not defined.
+        if not node.if_exists:
+            _directive_failed(ctx, node, ErrInfo("cmd", other_msg=f"There is no SCRIPT named {node.target.strip()}."))
+        return
+    try:
+        paramvals = _script_args(node, script_block)
+    except ErrInfo as e:
+        _directive_failed(ctx, node, e)
+        return
+    _execute_script_native(ctx, node, script_block, paramvals)
+
+
+def _directive_failed(ctx: RuntimeContext, node: IncludeDirective, e: ErrInfo) -> None:
+    """INCLUDE or EXECUTE SCRIPT itself failed (no such file or script, a missing argument): a metacommand error.
+
+    Errors raised by the statements an included file or script runs are
+    theirs, not the directive's, and are handled where they happen.
+    """
+    _metacommand_failed(ctx, node.command, e, node.span.file, node.span.start_line)
+
+
+def _script_args(node: IncludeDirective, script_block: ScriptBlock) -> ScriptArgSubVarSet | None:
+    """The arguments an EXECUTE SCRIPT passes to *script_block*, with defaults for those it leaves out.
+
+    ``node.arguments`` must already be substituted.  Raises :class:`ErrInfo`
+    when a required parameter has no argument.
     """
-    from execsql.script.variables import ScriptArgSubVarSet
     from execsql.utils.strings import wo_quotes
 
-    # Parse arguments (replicates ScriptExecSpec logic)
-    # Expand the argument string in the *caller's* scope so that references
-    # like val=!!#parent_param!! or val=!!~parent_local!! resolve correctly
-    # before we push a new scope for this script.
-    paramvals: ScriptArgSubVarSet | None = None
     if node.arguments is not None:
-        caller_locals = _stack_localvars(ctx)
-        expanded_args = substitute_vars(node.arguments, caller_locals, ctx=ctx)
         args_rx = re.compile(
             r'(?P<param>#?\w+)\s*=\s*(?P<arg>(?:(?:[^"\'\[][^,\)]*)|(?:"[^"]*")|(?:\'[^\']*\')|(?:\[[^\]]*\])))',
             re.I,
         )
-        all_args = re.findall(args_rx, expanded_args)
+        all_args = re.findall(args_rx, node.arguments)
         all_cleaned_args = [(ae[0], wo_quotes(ae[1])) for ae in all_args]
         all_prepared_args = [(ae[0] if ae[0][0] == "#" else "#" + ae[0], ae[1]) for ae in all_cleaned_args]
         paramvals = ScriptArgSubVarSet()
         for param, arg in all_prepared_args:
             paramvals.add_substitution(param, arg)
-
-        # Validate parameter names match — with default parameter support
-        if script_block.param_defs is not None:
-            passed_names = [p[0].lstrip("#") for p in all_prepared_args]
-            required = [p.name for p in script_block.param_defs if p.required]
-            missing = [p for p in required if p not in passed_names]
-            if missing:
-                raise ErrInfo(
-                    "error",
-                    other_msg=(f"Missing required parameter(s) ({', '.join(missing)}) in call to {script_block.name}."),
-                )
-            # Inject defaults for optional params not provided
-            for pdef in script_block.param_defs:
-                if pdef.default is not None and pdef.name not in passed_names:
-                    paramvals.add_substitution(f"#{pdef.name}", pdef.default)
+        passed_names = [p[0].lstrip("#") for p in all_prepared_args]
     else:
-        if script_block.param_defs is not None:
-            required = [p.name for p in script_block.param_defs if p.required]
-            if required:
-                raise ErrInfo(
-                    "error",
-                    other_msg=(
-                        f"Missing required parameter(s) ({', '.join(required)}) in call to {script_block.name}."
-                    ),
-                )
-            # No args provided but all params have defaults — inject them all
-            paramvals = ScriptArgSubVarSet()
-            for pdef in script_block.param_defs:
-                if pdef.default is not None:
-                    paramvals.add_substitution(f"#{pdef.name}", pdef.default)
+        if script_block.param_defs is None:
+            return None
+        paramvals = ScriptArgSubVarSet()
+        passed_names = []
+
+    # Validate parameter names match — with default parameter support
+    if script_block.param_defs is not None:
+        missing = [p.name for p in script_block.param_defs if p.required and p.name not in passed_names]
+        if missing:
+            raise ErrInfo(
+                "error",
+                other_msg=f"Missing required parameter(s) ({', '.join(missing)}) in call to {script_block.name}.",
+            )
+        # Inject defaults for optional params not provided
+        for pdef in script_block.param_defs:
+            if pdef.default is not None and pdef.name not in passed_names:
+                paramvals.add_substitution(f"#{pdef.name}", pdef.default)
+    return paramvals
+
 
+def _execute_script_native(
+    ctx: RuntimeContext,
+    node: IncludeDirective,
+    script_block: ScriptBlock,
+    paramvals: ScriptArgSubVarSet | None,
+) -> None:
+    """Execute a SCRIPT block natively through the AST executor.
+
+    *paramvals* are its arguments, from :func:`_script_args`.
+
+    Pushes a SCRIPT-kind :class:`~execsql.state.ExecFrame` onto
+    ``ctx.ast_exec_stack`` so that metacommand handlers (``x_sub``,
+    ``x_rm_sub``, ``xf_sub_defined``, prompt handlers, etc.) can access
+    ``~`` local variables and ``#`` script arguments via
+    ``ctx.current_localvars()`` / ``ctx.current_paramvals()``. The frame
+    is popped on exit (including on error) via ``try/finally``.
+    """
     # Push a SCRIPT-kind ExecFrame onto ast_exec_stack so that:
     #   - get_subvarset() can find ~local and +outer-scope variables
     #   - xf_sub_defined/xf_sub_empty can check ~local and #param variables
@@ -782,9 +921,8 @@ def _execute_script_native(
 
         if node.loop_type == "WHILE":
             while True:
-                effective_locals = _stack_localvars(ctx)
-                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-                if not xcmd_test(expanded):
+                ctx.last_command = ExecutingStatement(node)
+                if not _condition_holds(ctx, node.command, node.span, condition):
                     break
                 frame.iteration += 1
                 try:
@@ -798,18 +936,14 @@ def _execute_script_native(
                     _run_body()
                 except _BreakLoop:
                     break
-                effective_locals = _stack_localvars(ctx)
-                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-                if xcmd_test(expanded):
+                ctx.last_command = ExecutingStatement(node)
+                if _condition_holds(ctx, node.command, node.span, condition):
                     break
         else:
             try:
                 _run_body()
-            except _BreakLoop as exc:
-                raise ErrInfo(
-                    type="cmd",
-                    other_msg=f"BREAK metacommand inside SCRIPT '{script_block.name}' but not inside a LOOP.",
-                ) from exc
+            except _BreakLoop:
+                pass  # BREAK outside a LOOP in the script returns from it
     finally:
         _pop_frame(ctx)
 
@@ -824,24 +958,68 @@ def _execute_include_native(
     Handles tilde expansion, IF EXISTS, logging, and circular-include
     detection via ``ctx.include_chain``.
     """
-    from execsql.script.parser import parse_script
-    from execsql.utils.errors import file_size_date
+    try:
+        loaded = _load_include(ctx, node)
+    except _OutsideIncludeRoot as refused:
+        # A security boundary, not a script error to carry on from: the run
+        # stops whatever METACOMMAND_ERROR_HALT says.
+        _metacommand_failed(ctx, node.command, refused.errinfo, node.span.file, node.span.start_line, always_halt=True)
+        return
+    except Exception as exc:
+        _directive_failed(ctx, node, _as_errinfo(exc))
+        return
+    if loaded is None:
+        return
+    resolved, included_tree = loaded
 
-    # Substitute variables in the target path
-    effective_locals = _stack_localvars(ctx) or localvars
-    target = substitute_vars(node.target, effective_locals, ctx=ctx).strip()
+    # Pre-register SCRIPT blocks in the included file so forward references work.
+    _pre_register_scripts(ctx, included_tree.body)
+
+    # Execute with include-chain tracking
+    from execsql.state import ExecFrame
+
+    ctx.include_chain.append(resolved)
+    _push_block_frame(
+        ctx,
+        ExecFrame(kind="include", label=Path(resolved).name, source=resolved, line=1),
+    )
+    try:
+        _execute_nodes(ctx, included_tree.body, included_tree.source, localvars)
+    except _BreakLoop:
+        pass  # BREAK outside a LOOP in the file leaves it
+    finally:
+        ctx.ast_exec_stack.pop()
+        ctx.include_chain.pop()
+
+
+class _OutsideIncludeRoot(Exception):
+    """An INCLUDE's file is outside ``include_root``; *errinfo* says where it resolved."""
 
-    # Strip surrounding quotes — the AST parser captures the full target
-    # including any quotes, but the legacy dispatch regex stripped them.
-    if len(target) >= 2 and target[0] in ('"', "'") and target[-1] == target[0]:
-        target = target[1:-1]
+    def __init__(self, errinfo: ErrInfo) -> None:
+        super().__init__(str(errinfo))
+        self.errinfo = errinfo
 
-    # Tilde expansion (matches x_include legacy handler)
+
+def _load_include(
+    ctx: RuntimeContext,
+    node: IncludeDirective,
+) -> tuple[str, Any] | None:
+    """Find and parse the file an INCLUDE names: ``(resolved path, tree)``, or ``None`` to skip it (IF EXISTS).
+
+    Raises :class:`_OutsideIncludeRoot` for a file outside ``include_root``,
+    and :class:`ErrInfo` when the INCLUDE itself fails: no such file, a
+    circular include, or a file that does not parse.
+    """
+    from execsql.script.parser import parse_script
+    from execsql.utils.errors import file_size_date
+
+    target = node.target
+    # Tilde expansion (matches the monolith's x_include)
     if len(target) > 1 and target[0] == "~" and target[1] == os.sep:
         target = str(Path.home() / target[2:])
 
-    # Optional containment: when conf.include_root is set, the resolved
-    # INCLUDE / EXECUTE SCRIPT target must live under that root.
+    # Optional containment: when conf.include_root is set, the file must
+    # live under that root.
     include_root = getattr(ctx.conf, "include_root", None) if hasattr(ctx, "conf") else None
     if include_root is None:
         import execsql.state as _state
@@ -850,14 +1028,17 @@ def _execute_include_native(
     if include_root:
         from execsql.utils.fileio import safe_output_path
 
-        target = safe_output_path(target, include_root)
+        try:
+            target = safe_output_path(target, include_root)
+        except ErrInfo as e:
+            raise _OutsideIncludeRoot(e) from e
 
     target_path = Path(target)
 
     # IF EXISTS handling
     if node.if_exists:
         if not target_path.is_file():
-            return
+            return None
     else:
         if not target_path.is_file():
             raise ErrInfo(type="error", other_msg=f"File {target} does not exist.")
@@ -883,23 +1064,7 @@ def _execute_include_native(
     included_tree = parse_script(target, encoding=encoding)
     if (manifest := _manifest.current()) is not None:
         manifest.record_include(target, node.span.file, node.span.start_line)
-
-    # Pre-register SCRIPT blocks in the included file so forward references work.
-    _pre_register_scripts(ctx, included_tree.body)
-
-    # Execute with include-chain tracking
-    from execsql.state import ExecFrame
-
-    ctx.include_chain.append(resolved)
-    _push_block_frame(
-        ctx,
-        ExecFrame(kind="include", label=Path(resolved).name, source=resolved, line=1),
-    )
-    try:
-        _execute_nodes(ctx, included_tree.body, included_tree.source, localvars)
-    finally:
-        ctx.ast_exec_stack.pop()
-        ctx.include_chain.pop()
+    return resolved, included_tree
 
 
 # ---------------------------------------------------------------------------
@@ -908,7 +1073,7 @@ def _execute_include_native(
 
 
 class _BreakLoop(BaseException):
-    """Raised by BREAK metacommand to exit the innermost loop.
+    """Raised by BREAK to leave the innermost LOOP, SCRIPT or included file.
 
     A ``BaseException``, like ``KeyboardInterrupt``, so the ``except
     Exception`` handlers it may pass on its way to the loop leave it alone:
@@ -917,13 +1082,23 @@ class _BreakLoop(BaseException):
     """
 
 
-def _inside_loop(ctx: RuntimeContext) -> bool:
-    """Whether a BREAK at the current statement would leave a loop within its scope."""
+def _break_has_target(ctx: RuntimeContext) -> bool:
+    """Whether a BREAK at the current statement has something to leave.
+
+    BREAK leaves the innermost LOOP, SCRIPT or included file (a SCRIPT that
+    ``EXECUTE SCRIPT … WHILE`` / ``UNTIL`` repeats stops repeating); in the main
+    script outside all of them there is nothing to leave.
+
+    Each kind listed here must have a runner that catches ``_BreakLoop``:
+    ``_execute_loop``, ``_execute_script_native`` and
+    ``_execute_include_native``.  A ``_BreakLoop`` nobody catches would end
+    the run as an uncaught BaseException.
+    """
     for frame in reversed(ctx.ast_exec_stack):
-        if frame.kind in ("loop_while", "loop_until"):
+        if frame.kind in ("loop_while", "loop_until", "script", "include"):
             return True
-        if frame.kind in ("script", "main"):
-            return frame.kind == "script" and frame.iteration > 0
+        if frame.kind == "main":
+            return False
     return False
 
 
@@ -986,9 +1161,8 @@ class ExecutingStatement:
         node = self.node
         if isinstance(node, SqlStatement):
             return _StatementText(node.text)
-        if isinstance(node, MetaCommandStatement):
-            return _StatementText(node.command, "-- !x! ")
-        return _StatementText("")
+        command = getattr(node, "command", "")
+        return _StatementText(command, "-- !x! " if command else "")
 
     def __repr__(self) -> str:
         return f"ExecutingStatement({self.source}:{self.line_no}, {self.command_type})"
@@ -1006,23 +1180,7 @@ def _node_cmd_type(node: Node) -> str:
 
 
 def _node_cmd_text(node: Node) -> str:
-    if isinstance(node, SqlStatement):
-        return node.text
-    if isinstance(node, MetaCommandStatement):
-        return "-- !x! " + node.command
-    if isinstance(node, IfBlock):
-        return f"-- !x! IF ({node.condition})"
-    if isinstance(node, LoopBlock):
-        return f"-- !x! LOOP {node.loop_type} ({node.condition})"
-    if isinstance(node, BatchBlock):
-        return "-- !x! BEGIN BATCH"
-    if isinstance(node, ScriptBlock):
-        return f"-- !x! BEGIN SCRIPT {node.name}"
-    if isinstance(node, IncludeDirective):
-        if node.is_execute_script:
-            return f"-- !x! EXECUTE SCRIPT {node.target}"
-        return f"-- !x! INCLUDE {node.target}"
-    return repr(node)
+    return ExecutingStatement(node).command.commandline() or repr(node)
 
 
 # ---------------------------------------------------------------------------
@@ -1068,11 +1226,6 @@ def execute(script: Script, *, ctx: RuntimeContext | None = None) -> None:
         _push_frame(ctx, "<main>", script.source, line_no=1, kind="main")
         try:
             _execute_nodes(ctx, script.body, script.source)
-        except _BreakLoop as exc:
-            raise ErrInfo(
-                type="cmd",
-                other_msg="BREAK metacommand outside of a LOOP block.",
-            ) from exc
         finally:
             _pop_frame(ctx)
 
@@ -1091,7 +1244,8 @@ def execute_input(
     """Run input typed at a BREAKPOINT prompt as the next lines of the paused script.
 
     The input runs as if it were written where the script paused: in its
-    variable scope, its batch and its loop, so a BREAK leaves that loop.
+    variable scope, its batch and its loop, so a BREAK leaves that loop
+    (or the SCRIPT or included file it paused in).
     Unlike :func:`execute`, nothing is reset.
 
     *show* receives the result of each SQL statement run.  An error that
@@ -1107,10 +1261,6 @@ def execute_input(
         ctx.prompt_input = show
         try:
             _execute_nodes(ctx, script.body, script.source)
-        except _BreakLoop as exc:
-            if not _inside_loop(ctx):
-                raise ErrInfo(type="cmd", other_msg="BREAK metacommand outside of a LOOP block.") from exc
-            raise
         finally:
             ctx.prompt_input = prompt_input
             ctx.last_command = last_command