interp: block return must not ride the invokeEx code0 fast path (#3572)

* interp: block return must not ride the invokeEx code0 fast path

Context::invokeEx hands enumerators (for_each_function et al.) the closure
body's single statement bare when code0 is set — skipping the
SimNode_ClosureBlock epilogue that clears stopForReturn. A firing bare
`return` inside such a block then killed the remaining iterations AND
leaked the stop flag into the calling function, silently skipping its
tail. Longest-lived visible casualty: rst.das documents() dropped every
Uncategorized function from the generated docs, and gate 3 passed
precisely because the loop was dead. JIT and AOT were always correct.

Fix: C0 additionally requires !expr->hasReturn, so return-bearing
single-statement closures take the full ClosureBlock path. Failing test
first: tests/ast/test_closure_block_return.das (red pre-fix, green now).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q8bZnWkVWeXy8jfrxSojso

* docs: group the functions the healed Uncategorized loop surfaced

The invokeEx block-return fix brings rst.das documents()'s Uncategorized
loop back to life, surfacing functions that had been silently dropped
from the generated docs. Groups + handmade entries for the new ones:
fio set_env_variable + long_fread/long_fwrite, logger_init_tee/
logger_set_tee, and the per-thread jobque dials (set/get_jobque_thread_
team_mode, set_current_thread_priority — hidden with the tuning-knob
family). Existing jobque handmade descriptions are untouched (an earlier
revision of this branch accidentally rewrote them; restored verbatim —
Copilot review caught the divergences).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q8bZnWkVWeXy8jfrxSojso

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: borisbat

doc/reflections/das2rst.das

@@ -214,12 +214,12 @@ def document_module_fio(_root : string) {
     var mod = [get_module("fio_core"), find_module("fio")]
     var groups <- array<DocGroup>(
         hide_group(group_by_regex("Internal builtin functions", mod, %regex~builtin%%)),
-        group_by_regex("File manipulation", mod, %regex~(f|stat$|getchar|remove|rename|copy_file|file_size|equivalent|is_symlink|set_mtime)%%),
+        group_by_regex("File manipulation", mod, %regex~(f|long_f|stat$|getchar|remove|rename|copy_file|file_size|equivalent|is_symlink|set_mtime)%%),
         group_by_regex("Path manipulation", mod, %regex~(base_name|dir_name|get_full_file_name|extension|stem|replace_extension|path_join|normalize|to_generic_path|is_absolute|relative|relative_result|parent)$%%),
         group_by_regex("Directory manipulation", mod, %regex~(dir|dir_rec|mkdir|mkdir_rec|mkdir_result|rmdir|rmdir_rec|rmdir_rec_result|rmdir_result|chdir|getcwd)$%%),
         group_by_regex("Glob and pattern matching", mod, %regex~(match_glob|glob|glob_filtered|is_glob_pattern|expand_glob|parse_file_list)$%%),
         group_by_regex("Filesystem queries", mod, %regex~(temp_directory|temp_directory_result|create_temp_file|create_temp_file_result|create_temp_directory|create_temp_directory_result|disk_space)$%%),
-        group_by_regex("OS specific routines", mod, %regex~(sleep|exit|system|popen|popen_binary|popen_timeout|spawn_argv|popen_argv|popen_argv_pipe|popen_timed_out|run_and_capture|get_env_variable|sanitize_command_line|has_env_variable)$%%),
+        group_by_regex("OS specific routines", mod, %regex~(sleep|exit|system|popen|popen_binary|popen_timeout|spawn_argv|popen_argv|popen_argv_pipe|popen_timed_out|run_and_capture|get_env_variable|set_env_variable|sanitize_command_line|has_env_variable)$%%),
         group_by_regex("Dynamic modules", mod, %regex~(register_dynamic_module|register_native_path)$%%)
     )
     documents("File input output library", mod, "fio.rst", groups)
@@ -598,7 +598,7 @@ def document_module_jobque(_root : string) {
         group_by_regex("Channel, JobStatus, Lockbox, Stream", mod, %regex~(append|notify|join|channel_create|channel_remove|stream_create|stream_remove|add_ref|release|notify_and_release|lock_box_create|lock_box_remove|job_status_create|job_status_remove)$%%),
         group_by_regex("Queries", mod, %regex~(get_total_hw_jobs|get_total_hw_threads|get_total_hw_cores|is_job_que_shutting_down|is_job_que_available|count_jobque_leaks)$%%),
         group_by_regex("Event tracing", mod, %regex~(jobque_trace_start|jobque_trace_stop|jobque_trace_save|jobque_trace_tag|jobque_trace_category|jobque_trace_marker_name|jobque_trace_marker)$%%),
-        group_by_regex("Internal invocations", mod, %regex~(new_job_invoke|new_thread_invoke|new_debugger_thread|set_jobque_fork_pool|set_jobque_fork_skip_heap_reset|set_jobque_worker_spin|set_jobque_batch_dispatch|set_jobque_join_spin|set_jobque_team_mode|get_jobque_team_mode|set_jobque_threads_cap|set_jobque_affinity|get_jobque_affinity|set_jobque_worker_limit|get_jobque_worker_limit|set_jobque_team_rank_gate|get_jobque_team_rank_gate|set_jobque_team_prof|reset_jobque_team_prof|get_jobque_team_prof|get_jobque_team_prof_counts|get_jobque_team_prof_react|team_parallel_for_invoke|team_parallel_for_indexed_invoke|team_parallel_stages_invoke|flush_jobque_batch|jobque_try_run_one)$%%),
+        group_by_regex("Internal invocations", mod, %regex~(new_job_invoke|new_thread_invoke|new_debugger_thread|set_jobque_fork_pool|set_jobque_fork_skip_heap_reset|set_jobque_worker_spin|set_jobque_batch_dispatch|set_jobque_join_spin|set_jobque_team_mode|get_jobque_team_mode|set_jobque_thread_team_mode|get_jobque_thread_team_mode|set_current_thread_priority|set_jobque_threads_cap|set_jobque_affinity|get_jobque_affinity|set_jobque_worker_limit|get_jobque_worker_limit|set_jobque_team_rank_gate|get_jobque_team_rank_gate|set_jobque_team_prof|reset_jobque_team_prof|get_jobque_team_prof|get_jobque_team_prof_counts|get_jobque_team_prof_react|team_parallel_for_invoke|team_parallel_for_indexed_invoke|team_parallel_stages_invoke|flush_jobque_batch|jobque_try_run_one)$%%),
         group_by_regex("Construction", mod, %regex~(with_channel|with_stream|with_job_status|with_job_que|with_lock_box|create_job_que|destroy_job_que)$%%),
         group_by_regex("Atomic", mod, %regex~(atomic32_create|atomic32_remove|with_atomic32|atomic64_create|atomic64_remove|with_atomic64|get|set|inc|dec)$%%)
     )
@@ -1316,9 +1316,9 @@ def document_module_toml(_root : string) {
 def document_module_logger(_root : string) {
     var mod = find_module("logger")
     var groups <- array<DocGroup>(
-        group_by_regex("Setup", mod, %regex~.*(logger_init|logger_set_name|logger_set_path|logger_get_path|logger_get_name)$%%),
+        group_by_regex("Setup", mod, %regex~.*(logger_init|logger_init_tee|logger_set_name|logger_set_path|logger_get_path|logger_get_name)$%%),
         group_by_regex("Level filters", mod, %regex~.*(logger_set_min_level|logger_get_min_level|logger_set_category_level|logger_clear_category_levels)$%%),
-        group_by_regex("Output control", mod, %regex~.*(logger_set_stderr_fallback|logger_flush|logger_close)$%%),
+        group_by_regex("Output control", mod, %regex~.*(logger_set_stderr_fallback|logger_set_tee|logger_flush|logger_close)$%%),
         group_by_regex("Log calls", mod, %regex~.*(logger_log|logger_trace|logger_debug|logger_info|logger_warning|logger_error|logger_critical)$%%),
         group_by_regex("Stdout hook", mod, %regex~.*(logger_install_hook)$%%)
     )

doc/source/stdlib/handmade/function-fio-set_env_variable-0xf7b1b4df69de309.rst

@@ -0,0 +1 @@
+Sets an environment variable in the current process (the `setenv`/`_putenv` family). The change is visible to subsequent `get_env_variable` calls and inherited by child processes spawned afterwards (`popen`, `spawn_argv`); it does not affect the parent shell.

doc/source/stdlib/handmade/function-jobque-get_jobque_thread_team_mode-0xadb77f2665209111.rst

@@ -0,0 +1 @@
+Reads the calling OS thread's team-mode override (see `set_jobque_thread_team_mode`).

doc/source/stdlib/handmade/function-jobque-set_current_thread_priority-0x30274d0f647e878a.rst

@@ -0,0 +1 @@
+Sets the OS priority of the calling thread on the jobque `JobPriority` scale, -2 (Minimum) .. 2 (Maximum), clamped. The dispatch caller is load-bearing in team mode — only it publishes chains, so a descheduled caller idles every lane; queue creation already runs it at High (+1), and this exposes the remaining notch (and the rest of the scale) to scripts.

doc/source/stdlib/handmade/function-jobque-set_jobque_thread_team_mode-0x3ea171573d71f2e0.rst

@@ -0,0 +1 @@
+Per-caller team-mode override: with team mode off for this OS thread, `team_parallel_*` calls run inline on the caller while other threads keep publishing to the shared worker team. New OS threads default to enabled.

src/ast/ast_simulate.cpp

@@ -2221,7 +2221,10 @@ namespace das
             SimNode_Block * block;
             if ( expr->isClosure ) {
                 bool needResult = expr->type!=nullptr && expr->type->baseType!=Type::tVoid;
-                bool C0 = !needResult && simlist.size()==1 && expr->finalList.size()==0;
+                // the invokeEx code0 fast path evals list[0] bare, skipping the ClosureBlock
+                // epilogue that clears stopForReturn — a block containing a return must take
+                // the full path or the flag leaks into the invoking enumeration and its caller
+                bool C0 = !needResult && simlist.size()==1 && expr->finalList.size()==0 && !expr->hasReturn;
 #if DAS_DEBUGGER
                 if ( context.debugger ) {
                     block = context.code->makeNode<SimNodeDebug_ClosureBlock>(at, needResult, C0, expr->annotationData);

tests/ast/test_closure_block_return.das

@@ -0,0 +1,63 @@
+options gen2
+options indenting = 4
+options rtti
+
+require dastest/testing_boost public
+require daslib/ast
+
+//! A bare `return` inside a block exits THE BLOCK only. The interpreter's invokeEx code0 fast
+//! path handed enumerators (for_each_function et al.) the closure body's single statement WITHOUT
+//! the SimNode_ClosureBlock epilogue that clears stopForReturn — so the first firing return
+//! killed the remaining iterations AND leaked the stop flag into the calling function, silently
+//! skipping its tail (rst.das documents() lost every Uncategorized function this way). The
+//! single-statement and multi-statement closures below are semantically identical; they must
+//! count the same. JIT and AOT were always correct — this is an interpreter-only regression rail.
+
+// single-statement closure body (one IfThenElse) — rides the code0 fast path
+def private count_single(mod : rtti::Module?) : int {
+    var n = 0
+    for_each_function(mod, "") $(func) {
+        if (func.flags.generated) {
+            return
+        } else {
+            n++
+        }
+    }
+    return n
+}
+
+// multi-statement closure body — never rode the fast path, always correct
+def private count_multi(mod : rtti::Module?; var fired : int&) : int {
+    var n = 0
+    for_each_function(mod, "") $(func) {
+        if (func.flags.generated) {
+            fired++
+            return
+        }
+        n++
+    }
+    return n
+}
+
+// tail sentinel: a leaked stop flag would skip everything after the enumeration
+def private tail_runs(mod : rtti::Module?) : bool {
+    for_each_function(mod, "") $(func) {
+        if (func.flags.generated) {
+            return
+        }
+    }
+    return true
+}
+
+[test]
+def test_closure_block_return(t : T?) {
+    ast_gc_guard() {
+        var mod = get_module("$")
+        var fired = 0
+        let multi = count_multi(mod, fired)
+        t |> success(fired > 0, "the early return must actually fire (module $ has generated fns)")
+        t |> success(multi > 0, "enumeration continues past a block return")
+        t |> equal(count_single(mod), multi)
+        t |> success(tail_runs(mod), "block return must not leak past the enumeration")
+    }
+}