From 71e19efdca9a5759ee54afc4bae0d2b0c3ff0cc9 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Tue, 4 Aug 2026 12:39:34 -0700
Subject: [PATCH] Make stdlib initialization explicit (#222)

---
 CHANGELOG.md                            |   4 +
 README.md                               |   6 +
 bin/base-bash                           |  37 +--
 examples/cookbook-args-lists-strings.sh |   3 +
 examples/cookbook-cleanup-temp.sh       |   3 +
 examples/std-usage.sh                   |   3 +
 lib/bash/README.md                      |  11 +-
 lib/bash/arg/README.md                  |   2 +
 lib/bash/arg/tests/lib_arg.bats         |  13 +-
 lib/bash/file/README.md                 |   2 +
 lib/bash/file/tests/lib_file.bats       |  10 +
 lib/bash/gh/README.md                   |   2 +
 lib/bash/gh/tests/lib_gh.bats           |  22 ++
 lib/bash/git/README.md                  |   2 +
 lib/bash/git/tests/lib_git.bats         |  10 +
 lib/bash/list/README.md                 |   2 +
 lib/bash/list/tests/lib_list.bats       |  13 +-
 lib/bash/std/README.md                  |  57 +++-
 lib/bash/std/lib_std.sh                 | 401 ++++++++++++++++--------
 lib/bash/std/tests/lib_std.bats         | 109 ++++++-
 lib/bash/str/README.md                  |   2 +
 lib/bash/str/tests/lib_str.bats         |  15 +-
 tests/bash-42-logging-smoke.sh          |   5 +
 tests/bash-option-contract.sh           |   3 +
 24 files changed, 543 insertions(+), 194 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 381706a..b45321b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,6 +49,10 @@ and versions are tracked in the repo-root `VERSION` file.
 
 ### Changed
 
+- Made `lib_std.sh` sourcing passive and introduced the explicit, idempotent
+  `base_bash_libs_init` lifecycle API. Wrapper flags now return through a
+  caller-owned array without hidden positional-parameter mutation; launchers,
+  examples, and companion-library tests initialize explicitly.
 - Made timed foreground-TTY invocations fail closed with a safe diagnostic;
   callers must provide a pipe or explicit non-terminal stdin for the v2 hard
   descendant guarantee.
diff --git a/README.md b/README.md
index 3636793..9052daf 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,8 @@ Source the installed stdlib from the Homebrew prefix:
 ```bash
 base_bash_libs_prefix="$(brew --prefix basefoundry/base/base-bash-libs)"
 source "$base_bash_libs_prefix/libexec/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
 printf 'base-bash-libs version: %s\n' "$BASE_BASH_LIBS_VERSION"
 ```
 
@@ -115,6 +117,8 @@ Source the stdlib from that checkout:
 ```bash
 base_bash_libs_dir="$PWD/vendor/base-bash-libs"
 source "$base_bash_libs_dir/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
 printf 'base-bash-libs version: %s\n' "$BASE_BASH_LIBS_VERSION"
 ```
 
@@ -145,6 +149,8 @@ project_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
 base_bash_libs_dir="$project_root/vendor/base-bash-libs"
 
 source "$base_bash_libs_dir/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
 import "$base_bash_libs_dir/lib/bash/file/lib_file.sh"
 import "$base_bash_libs_dir/lib/bash/git/lib_git.sh"
 import "$base_bash_libs_dir/lib/bash/gh/lib_gh.sh"
diff --git a/bin/base-bash b/bin/base-bash
index 5ca16fc..c89fcb3 100755
--- a/bin/base-bash
+++ b/bin/base-bash
@@ -6,7 +6,7 @@
 #
 # Responsibilities:
 #     - run a Bash script with lib/bash/std/lib_std.sh preloaded
-#     - preserve stdlib wrapper-flag behavior for the target script
+#     - explicitly initialize stdlib runtime state and filter wrapper flags
 #     - provide package-relative imports without establishing Base runtime state
 #
 
@@ -127,36 +127,9 @@ base_bash_resolve_lib_dir() {
 }
 
 base_bash_source_stdlib() {
-    local script_path="$1"
     local stdlib_path="$BASE_BASH_LIBS_DIR/std/lib_std.sh"
-    shift
-
-    # Consumed by lib_std.sh while it is being sourced below.
-    # shellcheck disable=SC2034
-    BASE_BASH_BOOTSTRAP_SOURCE="$script_path"
     # shellcheck source=/dev/null
-    source "$stdlib_path" "$@" || exit $?
-    unset BASE_BASH_BOOTSTRAP_SOURCE
-}
-
-base_bash_filter_runtime_args() {
-    local parse_options=1
-
-    base_bash_runtime_args=()
-
-    while (($#)); do
-        if ((parse_options)) && [[ "$1" == "--" ]]; then
-            base_bash_runtime_args+=("$1")
-            parse_options=0
-        # Keep consuming the deprecated --verbose-wrapper compatibility flag
-        # during the 1.x window so it never leaks into command argv.
-        elif ((parse_options)) && [[ "$1" == --debug-wrapper || "$1" == --verbose-wrapper || "$1" == --utc-wrapper || "$1" == --color ]]; then
-            :
-        else
-            base_bash_runtime_args+=("$1")
-        fi
-        shift
-    done
+    source "$stdlib_path" || exit $?
 }
 
 import_base_bash_lib() {
@@ -183,7 +156,6 @@ base_bash_run_script() {
     local script_path="$1"
     local package_root="$2"
     local -a runtime_args=()
-    local -a base_bash_runtime_args=()
     shift 2
 
     [[ -f "$script_path" ]] || base_bash_die "Script '$script_path' was not found."
@@ -191,9 +163,8 @@ base_bash_run_script() {
     BASE_BASH_LIBS_DIR="$(base_bash_resolve_lib_dir "$package_root")" || exit $?
     export BASE_BASH_LIBS_DIR
 
-    base_bash_filter_runtime_args "$@"
-    base_bash_source_stdlib "$script_path" "$@"
-    runtime_args=("${base_bash_runtime_args[@]}")
+    base_bash_source_stdlib
+    base_bash_libs_init runtime_args --source "$script_path" -- "$@" || exit $?
 
     unset -f main
 
diff --git a/examples/cookbook-args-lists-strings.sh b/examples/cookbook-args-lists-strings.sh
index 6f6fc8d..d4c1cef 100755
--- a/examples/cookbook-args-lists-strings.sh
+++ b/examples/cookbook-args-lists-strings.sh
@@ -5,6 +5,9 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" || exit 1
 # shellcheck source=/dev/null
 source "$repo_root/lib/bash/std/lib_std.sh"
 
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
+
 import "$repo_root/lib/bash/arg/lib_arg.sh"
 import "$repo_root/lib/bash/list/lib_list.sh"
 import "$repo_root/lib/bash/str/lib_str.sh"
diff --git a/examples/cookbook-cleanup-temp.sh b/examples/cookbook-cleanup-temp.sh
index 2675fac..2d1b372 100755
--- a/examples/cookbook-cleanup-temp.sh
+++ b/examples/cookbook-cleanup-temp.sh
@@ -5,6 +5,9 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" || exit 1
 # shellcheck source=/dev/null
 source "$repo_root/lib/bash/std/lib_std.sh"
 
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
+
 base_bash_libs_require_version 1.0.0
 
 workspace_dir=""
diff --git a/examples/std-usage.sh b/examples/std-usage.sh
index 18a549c..f9f7643 100755
--- a/examples/std-usage.sh
+++ b/examples/std-usage.sh
@@ -5,6 +5,9 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" || exit 1
 # shellcheck source=/dev/null
 source "$repo_root/lib/bash/std/lib_std.sh"
 
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
+
 import "$repo_root/lib/bash/file/lib_file.sh"
 
 example_file="${TMPDIR:-/tmp}/base-bash-libs-example.$$"
diff --git a/lib/bash/README.md b/lib/bash/README.md
index ea3f072..4e1b92e 100644
--- a/lib/bash/README.md
+++ b/lib/bash/README.md
@@ -29,11 +29,12 @@ modules.
 ## Caller Runtime Contract
 
 All public modules support Bash 4.2 or newer with every combination of caller-
-selected `errexit`, `nounset`, and `pipefail`. Sourcing a module does not change
-those settings, any other `set` or `shopt` option, `IFS`, `OPTIND`, the working
-directory, the umask, traps, or ordinary positional arguments. The stdlib's
-documented wrapper flags are the exception: its initializer removes recognized
-wrapper flags and publishes the filtered positional arguments.
+selected `errexit`, `nounset`, and `pipefail`. Sourcing a module is passive: it
+does not change those settings, any other `set` or `shopt` option, `IFS`,
+`OPTIND`, the working directory, the umask, traps, exports, or ordinary
+positional arguments. After sourcing `lib_std.sh`, callers explicitly invoke
+`base_bash_libs_init` to initialize runtime state and receive wrapper-filtered
+arguments in a caller-owned array.
 
 Public API calls preserve the same process state unless their documented
 purpose is to change it. Examples of intentional mutation include PATH helpers,
diff --git a/lib/bash/arg/README.md b/lib/bash/arg/README.md
index 6f4fc0f..97e53ba 100644
--- a/lib/bash/arg/README.md
+++ b/lib/bash/arg/README.md
@@ -23,6 +23,8 @@ Aliasing is rejected before any caller-owned output is changed.
 
 ```bash
 source "/absolute/path/to/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" --
 source "/absolute/path/to/lib/bash/arg/lib_arg.sh"
 
 declare -A options=()
diff --git a/lib/bash/arg/tests/lib_arg.bats b/lib/bash/arg/tests/lib_arg.bats
index 0390cda..cfdb5f4 100644
--- a/lib/bash/arg/tests/lib_arg.bats
+++ b/lib/bash/arg/tests/lib_arg.bats
@@ -5,12 +5,21 @@ load ../../tests/test_helper.sh
 setup() {
     setup_test_tmpdir
     source "$BASE_BASH_DIR/std/lib_std.sh"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args --source "$BASE_BASH_DIR/arg/tests/lib_arg.bats" --
     source "$BASE_BASH_DIR/arg/lib_arg.sh"
 }
 
 create_script() {
     local script_path="$1"
-    cat > "$script_path"
+    local content source_line init_lines
+    content="$(cat)"
+    source_line="source \"$BASE_BASH_DIR/std/lib_std.sh\""
+    if [[ "$content" == *"$source_line"* ]]; then
+        init_lines=$'declare -a base_bash_libs_test_args=()\nbase_bash_libs_init base_bash_libs_test_args -- "$@"\nset -- "${base_bash_libs_test_args[@]}"'
+        content="${content/"$source_line"/"$source_line"$'\n'"$init_lines"}"
+    fi
+    printf '%s\n' "$content" > "$script_path"
     chmod +x "$script_path"
 }
 
@@ -47,6 +56,8 @@ create_script() {
             case "$mode" in *u*) set -u ;; esac
             case "$mode" in *p*) set -o pipefail ;; esac
             source "$2"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             source "$3"
             arg_parse
             exit $?
diff --git a/lib/bash/file/README.md b/lib/bash/file/README.md
index 365e51b..6bf3a8f 100644
--- a/lib/bash/file/README.md
+++ b/lib/bash/file/README.md
@@ -27,6 +27,8 @@ settings; they do not impose a strict-mode policy on the calling script.
 
 ```bash
 source "/absolute/path/to/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" --
 source "/absolute/path/to/lib/bash/file/lib_file.sh"
 
 update_file_section ~/.bash_profile "# BEGIN APP" "# END APP" \
diff --git a/lib/bash/file/tests/lib_file.bats b/lib/bash/file/tests/lib_file.bats
index 49a6e72..a143d00 100644
--- a/lib/bash/file/tests/lib_file.bats
+++ b/lib/bash/file/tests/lib_file.bats
@@ -5,6 +5,8 @@ load ../../tests/test_helper.sh
 setup() {
     setup_test_tmpdir
     source "$BASE_BASH_DIR/std/lib_std.sh"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args --source "$BASE_BASH_DIR/file/tests/lib_file.bats" --
     source "$BASE_BASH_DIR/file/lib_file.sh"
 }
 
@@ -39,6 +41,8 @@ file_mode() {
     cat > "$script" <<EOF
 #!/usr/bin/env bash
 source "$BASE_BASH_DIR/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "\${BASH_SOURCE[0]}" -- "\$@"
 source "$BASE_BASH_DIR/file/lib_file.sh"
 printf 'line-one' > "\$1"
 update_file_section "\$1" "# BEGIN" "# END" "first"
@@ -103,6 +107,8 @@ EOF
 #!/usr/bin/env bash
 set -euo pipefail
 source "$BASE_BASH_DIR/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "\${BASH_SOURCE[0]}" -- "\$@"
 source "$BASE_BASH_DIR/file/lib_file.sh"
 update_file_section
 printf 'after\n'
@@ -127,6 +133,8 @@ EOF
 #!/usr/bin/env bash
 set -euo pipefail
 source "$BASE_BASH_DIR/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "\${BASH_SOURCE[0]}" -- "\$@"
 source "$BASE_BASH_DIR/file/lib_file.sh"
 update_file_section "\$1" "# BEGIN" "# END"
 printf 'strict=preserved\n'
@@ -307,6 +315,8 @@ EOF
     cat > "$script" <<EOF
 #!/usr/bin/env bash
 source "$BASE_BASH_DIR/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "\${BASH_SOURCE[0]}" -- "\$@"
 source "$BASE_BASH_DIR/file/lib_file.sh"
 trap 'printf "caller\n" >> "$log_file"' EXIT
 before_trap="\$(trap -p EXIT)"
diff --git a/lib/bash/gh/README.md b/lib/bash/gh/README.md
index 2b547ff..c4f7107 100644
--- a/lib/bash/gh/README.md
+++ b/lib/bash/gh/README.md
@@ -8,6 +8,8 @@ Source the stdlib before this library:
 
 ```bash
 source "/path/to/base-bash-libs/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" --
 import "/path/to/base-bash-libs/lib/bash/gh/lib_gh.sh"
 ```
 
diff --git a/lib/bash/gh/tests/lib_gh.bats b/lib/bash/gh/tests/lib_gh.bats
index 10a2991..841ab50 100644
--- a/lib/bash/gh/tests/lib_gh.bats
+++ b/lib/bash/gh/tests/lib_gh.bats
@@ -8,6 +8,8 @@ setup() {
     mkdir -p "$TEST_TMPDIR/bin"
     PATH="$TEST_TMPDIR/bin:$BASE_TEST_ORIG_PATH"
     source "$BASE_BASH_DIR/std/lib_std.sh"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args --source "$BASE_BASH_DIR/gh/tests/lib_gh.bats" --
     source "$BASE_BASH_DIR/gh/lib_gh.sh"
 }
 
@@ -163,6 +165,8 @@ gh_api_retry_observed() {
                 case "$mode" in *u*) set -u ;; esac
                 case "$mode" in *p*) set -o pipefail ;; esac
                 source "$2"
+                declare -a app_args=()
+                base_bash_libs_init app_args --
                 source "$3"
                 "$4"
                 rc=$?
@@ -301,6 +305,8 @@ EOF
             case "$mode" in *u*) set -u ;; esac
             case "$mode" in *p*) set -o pipefail ;; esac
             source "$2"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             source "$3"
             PATH="$4:$PATH"
             gh_run issue list
@@ -318,6 +324,8 @@ EOF
             case "$mode" in *u*) set -u ;; esac
             case "$mode" in *p*) set -o pipefail ;; esac
             source "$2"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             source "$3"
             PATH="$4:$PATH"
             gh_run --sensitive --safe-display "strict protected operation" -- issue list
@@ -402,6 +410,8 @@ EOF
 
     bats_run "$BASH" -c '
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args --
         source "$2"
         PATH="$3"
         gh_require_cli "$4"
@@ -572,6 +582,8 @@ EOF
 #!/usr/bin/env bash
 set -euo pipefail
 source "$BASE_BASH_DIR/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "\${BASH_SOURCE[0]}" -- "\$@"
 source "$BASE_BASH_DIR/gh/lib_gh.sh"
 PATH="$TEST_TMPDIR/bin:$BASE_TEST_ORIG_PATH"
 gh_run issue create --title Example
@@ -610,6 +622,8 @@ EOF
 
     bats_run "$BASH" -c '
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args --
         source "$2"
         PATH="$3"
         gh_run issue list
@@ -1711,6 +1725,8 @@ EOF
     cat > "$script" <<'EOF'
 #!/usr/bin/env bash
 source "$1"
+declare -a app_args=()
+base_bash_libs_init app_args --
 source "$2"
 TMPDIR="$3"
 STATUS_FILE="$4"
@@ -1753,6 +1769,8 @@ EOF
 #!/usr/bin/env bash
 set -u
 source "$1"
+declare -a app_args=()
+base_bash_libs_init app_args --
 source "$2"
 TMPDIR="$3"
 TRAP_MARKER="$4"
@@ -1904,6 +1922,8 @@ EOF
 #!/usr/bin/env bash
 set -e
 source "$BASE_BASH_DIR/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "\${BASH_SOURCE[0]}" -- "\$@"
 source "$BASE_BASH_DIR/gh/lib_gh.sh"
 PATH="$TEST_TMPDIR/bin:$PATH"
 gh_api_with_retry repos/owner/missing
@@ -1931,6 +1951,8 @@ EOF
 
     bats_run "$BASH" -c '
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args --
         source "$2"
         set -C
         value="$(gh_api_with_retry --max-attempts 1 -- repos/owner/repo)" || exit $?
diff --git a/lib/bash/git/README.md b/lib/bash/git/README.md
index 4fbcc70..12c8188 100644
--- a/lib/bash/git/README.md
+++ b/lib/bash/git/README.md
@@ -39,6 +39,8 @@ helpers manage branch selection, retries, and cleanup.
 
 ```bash
 source "/absolute/path/to/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" --
 source "/absolute/path/to/lib/bash/git/lib_git.sh"
 
 branch=""
diff --git a/lib/bash/git/tests/lib_git.bats b/lib/bash/git/tests/lib_git.bats
index 860a8a9..1f7be6a 100644
--- a/lib/bash/git/tests/lib_git.bats
+++ b/lib/bash/git/tests/lib_git.bats
@@ -5,6 +5,8 @@ load ../../tests/test_helper.sh
 setup() {
     setup_test_tmpdir
     source "$BASE_BASH_DIR/std/lib_std.sh"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args --source "$BASE_BASH_DIR/git/tests/lib_git.bats" --
     source "$BASE_BASH_DIR/git/lib_git.sh"
 }
 
@@ -49,6 +51,8 @@ setup() {
                 case "$mode" in *u*) set -u ;; esac
                 case "$mode" in *p*) set -o pipefail ;; esac
                 source "$2"
+                declare -a app_args=()
+                base_bash_libs_init app_args --source "$0" --
                 source "$3"
                 "$4"
                 rc=$?
@@ -129,6 +133,8 @@ setup() {
             case "$mode" in *u*) set -u ;; esac
             case "$mode" in *p*) set -o pipefail ;; esac
             source "$2"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             source "$3"
             git_branch_merged_to_ref "$4" feature main
             rc=$?
@@ -206,6 +212,8 @@ EOF
     bats_run "$BASH" -c '
         set -u
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args --
         source "$2"
         git() {
             printf "%s\n" \
@@ -1301,6 +1309,8 @@ EOF
             case "$mode" in *u*) set -u ;; esac
             case "$mode" in *p*) set -o pipefail ;; esac
             source "$2"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             source "$3"
             check_script_up_to_date "$4"
         ' bash "$mode" "$BASE_BASH_DIR/std/lib_std.sh" "$BASE_BASH_DIR/git/lib_git.sh" "$script_path"
diff --git a/lib/bash/list/README.md b/lib/bash/list/README.md
index 3e9280a..bf554cf 100644
--- a/lib/bash/list/README.md
+++ b/lib/bash/list/README.md
@@ -26,6 +26,8 @@ helpers are available.
 
 ```bash
 source "/absolute/path/to/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" --
 source "/absolute/path/to/lib/bash/list/lib_list.sh"
 
 declare -a packages=("jq")
diff --git a/lib/bash/list/tests/lib_list.bats b/lib/bash/list/tests/lib_list.bats
index 5870ad1..2de8337 100644
--- a/lib/bash/list/tests/lib_list.bats
+++ b/lib/bash/list/tests/lib_list.bats
@@ -5,12 +5,21 @@ load ../../tests/test_helper.sh
 setup() {
     setup_test_tmpdir
     source "$BASE_BASH_DIR/std/lib_std.sh"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args --source "$BASE_BASH_DIR/list/tests/lib_list.bats" --
     source "$BASE_BASH_DIR/list/lib_list.sh"
 }
 
 create_script() {
     local script_path="$1"
-    cat > "$script_path"
+    local content source_line init_lines
+    content="$(cat)"
+    source_line="source \"$BASE_BASH_DIR/std/lib_std.sh\""
+    if [[ "$content" == *"$source_line"* ]]; then
+        init_lines=$'declare -a base_bash_libs_test_args=()\nbase_bash_libs_init base_bash_libs_test_args -- "$@"\nset -- "${base_bash_libs_test_args[@]}"'
+        content="${content/"$source_line"/"$source_line"$'\n'"$init_lines"}"
+    fi
+    printf '%s\n' "$content" > "$script_path"
     chmod +x "$script_path"
 }
 
@@ -54,6 +63,8 @@ create_script() {
                 case "$mode" in *u*) set -u ;; esac
                 case "$mode" in *p*) set -o pipefail ;; esac
                 source "$2"
+                declare -a app_args=()
+                base_bash_libs_init app_args --
                 source "$3"
                 "$4"
                 exit $?
diff --git a/lib/bash/std/README.md b/lib/bash/std/README.md
index 1efef51..6807798 100644
--- a/lib/bash/std/README.md
+++ b/lib/bash/std/README.md
@@ -62,6 +62,9 @@ such output names are rejected before caller state is changed.
 
 ### Runtime and Imports
 
+- `base_bash_libs_init <result_array> [--source <script>] -- [argv...]`:
+  explicitly initializes runtime state and returns wrapper-filtered application
+  arguments without mutating the caller's positional parameters.
 - `base_bash_libs_require_version <version>`: exits with a diagnostic when the
   loaded package version is older than the requested dotted numeric version.
 - `check_bash_version`: returns zero for Bash 4.2 or newer and reports the
@@ -198,29 +201,50 @@ re-exec the caller.
 
 ## Initialization Contract
 
-Sourcing `lib_std.sh` runs a small one-time initializer:
+Sourcing `lib_std.sh` is passive. It publishes function definitions, immutable
+package metadata, and a collision-safe load guard, but it does not consume or
+rewrite positional parameters, install traps, export runtime controls, change
+shell options, initialize logging, or create caller-owned generic state.
 
-- initializes the logging level map
-- records the original script arguments in `__SCRIPT_ARGS__`
-- derives the caller's source directory in `__SCRIPT_DIR__`
-- exposes the package version in `BASE_BASH_LIBS_VERSION`
-- exposes the successful stdlib load marker in `BASE_BASH_LIBS_STDLIB_LOADED`
-- consumes Base wrapper flags such as `--debug-wrapper`, `--utc-wrapper`, and
-  `--color`; the compatibility flag `--verbose-wrapper` is deprecated
-- resets the caller's positional parameters to the filtered argument list
+Call `base_bash_libs_init` exactly once for the application lifecycle:
 
-Caller-visible globals:
+```bash
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
+
+# The caller owns this explicit handoff; the library never changes "$@".
+main "${app_args[@]}"
+```
+
+The first argument is a caller-declared indexed array. Optional `--source`
+identifies the application script for relative imports and diagnostics. The
+arguments after the configuration separator `--` are copied into the result
+array after these wrapper controls are consumed:
+
+- `--debug-wrapper` enables DEBUG logging for the terminal and the stdlib
+  category.
+- `--verbose-wrapper` retains the deprecated VERBOSE compatibility level.
+- `--utc-wrapper` exports `LOG_UTC=1` for the initialized runtime.
+- `--color` enables terminal colors when stderr is a TTY and `NO_COLOR` is not
+  set.
+
+Initialization is idempotent for the same script context and argv. A repeated
+call with different context or argv fails with a diagnostic instead of silently
+changing a running application's configuration. Companion libraries should be
+imported after initialization.
+
+Caller-visible metadata:
 
 - `BASE_BASH_LIBS_VERSION`: readonly package version read from the root
   `VERSION` file
 - `BASE_BASH_LIBS_STDLIB_LOADED`: readonly marker set to `1` after
-  `lib_std.sh` has initialized successfully
+  `lib_std.sh` has loaded successfully; it does not imply runtime init
 - `__SCRIPT_ARGS__`: original arguments before wrapper flags were stripped
 - `__SCRIPT_DIR__`: absolute source directory for the script being bootstrapped
 
-When a Base wrapper preloads the stdlib for another command, it can set
-`BASE_BASH_BOOTSTRAP_SOURCE` so `__SCRIPT_DIR__` still points at the command
-script rather than the wrapper.
+`__SCRIPT_ARGS__` and `__SCRIPT_DIR__` are published only by the explicit
+initializer. A launcher may pass `--source` directly; `BASE_BASH_BOOTSTRAP_SOURCE`
+is only a fallback for callers that cannot provide that option.
 
 The library preserves caller-selected `errexit`, `nounset`, and `pipefail`
 settings and supports every combination on Bash 4.2 or newer. It does not
@@ -837,12 +861,15 @@ For standalone scripts that source the library directly:
 #!/usr/bin/env bash
 source "/path/to/base-bash-libs/lib/bash/std/lib_std.sh"
 
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" -- "$@"
+
 main() {
     set_log_level DEBUG
     std_run echo "hello"
 }
 
-main "$@"
+main "${app_args[@]}"
 ```
 
 ## What Belongs Here
diff --git a/lib/bash/std/lib_std.sh b/lib/bash/std/lib_std.sh
index 42b45eb..fb92c7c 100644
--- a/lib/bash/std/lib_std.sh
+++ b/lib/bash/std/lib_std.sh
@@ -19,13 +19,14 @@
 # Sourcing:
 #   source "<repo>/lib/bash/std/lib_std.sh"
 #
-# Caller-visible globals:
+# Caller-visible metadata:
 #   BASE_BASH_LIBS_VERSION
 #                    Package version read from the repository/package VERSION file.
 #   BASE_BASH_LIBS_STDLIB_LOADED
-#                    Set to 1 after lib_std.sh has initialized successfully.
-#   __SCRIPT_ARGS__   Original "$@" before lib_std consumed global flags.
-#   __SCRIPT_DIR__    Absolute path to the script that sourced the library.
+#                    Set to 1 after lib_std.sh has been loaded successfully.
+#
+# Runtime globals such as __SCRIPT_ARGS__ and __SCRIPT_DIR__ are published only
+# by base_bash_libs_init. Sourcing this file never consumes or rewrites "$@".
 #
 # Core helpers:
 #   std_run [opts] cmd ...
@@ -66,9 +67,12 @@
 #   add_to_path -p "/opt/tools"  # inject directories without duplicates.
 #
 # Notes:
-#   - Global options --debug-wrapper/--verbose-wrapper/--utc-wrapper/--color are stripped from "$@" automatically.
+#   - Call base_bash_libs_init <result_array> [--source <script>] [--] [argv...]
+#     before using stateful helpers. It strips --debug-wrapper,
+#     --verbose-wrapper, --utc-wrapper, and --color into the result array.
 #   - --verbose-wrapper is deprecated compatibility surface; prefer --debug-wrapper.
-#   - Wrappers may override the caller path seen by this library through BASE_BASH_BOOTSTRAP_SOURCE.
+#   - BASE_BASH_BOOTSTRAP_SOURCE is accepted as a source-path fallback by the
+#     explicit initializer, not consumed while this file is sourced.
 #
 
 ################################################# INITIALIZATION #######################################################
@@ -79,7 +83,6 @@ __lib_std_require_supported_bash__() {
         printf '%s\n' "Your shell is not Bash." >&2
         return 1
     fi
-
     if ((BASH_VERSINFO[0] < 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] < 2))); then
         printf '%s\n' "Error: This script requires Bash 4.2 or higher." >&2
         printf '%s\n' "Your version ($BASH_VERSION) is not compatible." >&2
@@ -87,53 +90,67 @@ __lib_std_require_supported_bash__() {
     fi
 }
 
+# Runtime state remains passive, but loading an unsupported interpreter is a
+# deterministic contract error rather than a partially-defined library.
 __lib_std_require_supported_bash__ || return 1 2>/dev/null || exit 1
 unset -f __lib_std_require_supported_bash__
 
-#
-# Make sure we do nothing in case the library is sourced more than once in the same shell.
-# This prevents functions from being redefined and initialization from running multiple times.
-#
-[[ -n "${__stdlib_sourced__-}" ]] && return
-__stdlib_sourced__=1
-readonly __LIB_STD_PATH__="${BASH_SOURCE[0]}"
-
-# lib_std.sh lives at lib/bash/std/lib_std.sh in the packaged repository.
-# Walking three levels up reaches the package root that owns VERSION.
-__BASE_BASH_LIBS_ROOT__="$(
-    cd -- "$(dirname -- "$__LIB_STD_PATH__")/../../.." &>/dev/null && pwd -P
-)" || {
-    printf '%s\n' "Error: Unable to resolve base-bash-libs root from '$__LIB_STD_PATH__'." >&2
-    return 1 2>/dev/null || exit 1
-}
-readonly __BASE_BASH_LIBS_ROOT__
-
-__lib_std_read_package_version__() {
-    local version_file="$1" version
+__base_bash_libs_read_package_version__() {
+    local source_path="${1-}" version_file version
 
-    if [[ ! -r "$version_file" ]]; then
+    [[ -n "$source_path" ]] || return 1
+    version_file="$(cd -- "$(dirname -- "$source_path")/../../.." &>/dev/null && pwd -P)/VERSION" || return 1
+    [[ -r "$version_file" ]] || {
         printf '%s\n' "Error: base-bash-libs VERSION file is not readable: $version_file" >&2
         return 1
-    fi
-
+    }
     IFS= read -r version < "$version_file" || [[ -n "$version" ]] || {
         printf '%s\n' "Error: Unable to read base-bash-libs version from: $version_file" >&2
         return 1
     }
-
-    if [[ -z "$version" ]]; then
+    [[ -n "$version" ]] || {
         printf '%s\n' "Error: base-bash-libs VERSION file is empty: $version_file" >&2
         return 1
-    fi
-
+    }
     printf '%s' "$version"
 }
 
-BASE_BASH_LIBS_VERSION="$(__lib_std_read_package_version__ "$__BASE_BASH_LIBS_ROOT__/VERSION")" || {
+# A source guard is deliberately package-prefixed and readonly. It is the only
+# source-time state other than immutable package metadata. Re-sourcing the same
+# version is a no-op; attempting to mix versions fails before definitions are
+# replaced.
+if [[ -n "${BASE_BASH_LIBS_STD_SOURCE_GUARD+x}" ]]; then
+    if [[ "${BASE_BASH_LIBS_STD_SOURCE_VERSION-}" != "$(__base_bash_libs_read_package_version__ "${BASH_SOURCE[0]}")" ||
+        "${BASE_BASH_LIBS_STD_SOURCE_PATH-}" != "${BASH_SOURCE[0]}" ]]; then
+        printf '%s\n' "Error: incompatible base-bash-libs stdlib versions or sources are already loaded (loaded ${BASE_BASH_LIBS_STD_SOURCE_VERSION:-unknown} from ${BASE_BASH_LIBS_STD_SOURCE_PATH:-unknown}, requested $(__base_bash_libs_read_package_version__ "${BASH_SOURCE[0]}" 2>/dev/null || printf 'unknown') from ${BASH_SOURCE[0]})." >&2
+        unset -f __base_bash_libs_read_package_version__
+        return 1 2>/dev/null || exit 1
+    fi
+    unset -f __base_bash_libs_read_package_version__
+    return 0
+fi
+
+if [[ -n "${BASE_BASH_LIBS_VERSION+x}" || -n "${BASE_BASH_LIBS_STDLIB_LOADED+x}" ]]; then
+    printf '%s\n' "Error: base-bash-libs metadata names are already owned by the caller; refusing to overwrite them." >&2
+    return 1 2>/dev/null || exit 1
+fi
+
+readonly BASE_BASH_LIBS_STD_SOURCE_PATH="${BASH_SOURCE[0]}"
+readonly BASE_BASH_LIBS_STD_ROOT="$(cd -- "$(dirname -- "$BASE_BASH_LIBS_STD_SOURCE_PATH")/../../.." &>/dev/null && pwd -P)" || {
+    printf '%s\n' "Error: Unable to resolve base-bash-libs root from '$BASE_BASH_LIBS_STD_SOURCE_PATH'." >&2
+    return 1 2>/dev/null || exit 1
+}
+BASE_BASH_LIBS_VERSION="$(__base_bash_libs_read_package_version__ "$BASE_BASH_LIBS_STD_SOURCE_PATH")" || {
     return 1 2>/dev/null || exit 1
 }
 readonly BASE_BASH_LIBS_VERSION
-unset -f __lib_std_read_package_version__
+readonly BASE_BASH_LIBS_STD_SOURCE_VERSION="$BASE_BASH_LIBS_VERSION"
+readonly BASE_BASH_LIBS_STD_SOURCE_GUARD=1
+# Used by companion libraries as a source-order guard. This marker means the
+# definitions and immutable metadata are loaded; it does not imply runtime init.
+# shellcheck disable=SC2034
+readonly BASE_BASH_LIBS_STDLIB_LOADED=1
+unset -f __base_bash_libs_read_package_version__
 
 __base_bash_libs_is_dotted_numeric_version__() {
     local version="${1-}" version_re='^[0-9]+([.][0-9]+)*$'
@@ -193,55 +210,6 @@ base_bash_libs_require_version() {
     return 0
 }
 
-#
-# Memorize the original script arguments at the very beginning.
-# This allows the library to parse global options before the main script does.
-# We retain the original arguments in __SCRIPT_ARGS__ and the script source directory in __SCRIPT_DIR__ as readonly
-# variables which could be used by the caller. When a wrapper preloads this library on behalf of another script, it can
-# provide BASE_BASH_BOOTSTRAP_SOURCE so __SCRIPT_DIR__ still resolves to the real command script.
-#
-readonly __SCRIPT_ARGS__=("$@")
-__new_args__=()
-__script_source__="${BASE_BASH_BOOTSTRAP_SOURCE:-${BASH_SOURCE[1]-}}"
-if [[ -n "$__script_source__" ]]; then
-    __SCRIPT_DIR__=$(
-        cd -- "$(dirname -- "$__script_source__")" &>/dev/null && pwd -P
-    ) || {
-        printf '%s\n' "Error: Unable to resolve caller directory from '$__script_source__'." >&2
-        return 1 2>/dev/null || exit 1
-    }
-else
-    # An interactive shell or a top-level `bash -c` source has no outer
-    # BASH_SOURCE frame. In that case relative imports are anchored to the
-    # directory in which the caller sourced the library.
-    __SCRIPT_DIR__="$(pwd -P)" || {
-        printf '%s\n' "Error: Unable to resolve the current caller directory." >&2
-        return 1 2>/dev/null || exit 1
-    }
-fi
-readonly __SCRIPT_DIR__
-declare -ga __std_cleanup_hooks=()
-declare -ga __std_cleanup_paths=()
-declare -ga __std_cleanup_entries=()
-declare -gA __std_cleanup_path_fingerprints=()
-declare -g __std_cleanup_dispatcher_installed=0
-declare -g __std_cleanup_dispatcher_running=0
-declare -g __std_cleanup_dispatcher_finished=0
-declare -g __std_cleanup_pending_signal_status=0
-declare -g __std_cleanup_debug_guard_running=0
-declare -g __std_original_exit_trap=""
-declare -g __std_original_exit_trap_spec=""
-declare -g __std_cleanup_dispatcher_trap_spec=""
-declare -g __std_original_int_trap=""
-declare -g __std_original_int_trap_spec=""
-declare -g __std_cleanup_int_trap_spec="__not-installed__"
-declare -g __std_original_term_trap=""
-declare -g __std_original_term_trap_spec=""
-declare -g __std_cleanup_term_trap_spec="__not-installed__"
-declare -g __std_original_debug_trap=""
-declare -g __std_original_debug_trap_spec=""
-declare -g __std_cleanup_debug_trap_spec="__not-installed__"
-
 ############################################ BASH VERSION CHECKER #######################################################
 
 #
@@ -295,60 +263,232 @@ check_bash_version() {
 
 ###################################################### INIT ############################################################
 
+__std_init_validate_result_array__() {
+    local result_name="${1-}" declaration attributes nocasematch_enabled=0 attributes_ok=0
+
+    [[ "$result_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || {
+        printf '%s\n' "base_bash_libs_init: result name must be a valid Bash variable name." >&2
+        return 1
+    }
+    [[ "$result_name" != __* ]] || {
+        printf '%s\n' "base_bash_libs_init: result name '$result_name' uses the reserved internal namespace." >&2
+        return 1
+    }
+    declaration="$(declare -p "$result_name" 2>/dev/null || true)"
+    [[ -n "$declaration" ]] || {
+        printf '%s\n' "base_bash_libs_init: result '$result_name' must be a caller-declared indexed array." >&2
+        return 1
+    }
+    attributes="${declaration#declare -}"
+    attributes="${attributes%% *}"
+    if shopt -q nocasematch; then
+        nocasematch_enabled=1
+        shopt -u nocasematch
+    fi
+    if [[ "$attributes" == *a* &&
+        "$attributes" != *A* &&
+        "$attributes" != *r* ]]; then
+        attributes_ok=1
+    fi
+    if ((nocasematch_enabled)); then
+        shopt -s nocasematch
+    fi
+    ((attributes_ok)) || {
+        printf '%s\n' "base_bash_libs_init: result '$result_name' must be a caller-declared indexed array." >&2
+        return 1
+    }
+}
+
+__std_init_publish_array__() {
+    local result_name="$1" value
+    shift
+    eval "$result_name=()"
+    for value; do
+        eval "$result_name+=(\"\$value\")"
+    done
+}
+
+__std_init_args_match__() {
+    local index=0
+    (($# == ${#__SCRIPT_ARGS__[@]})) || return 1
+    for index in "${!__SCRIPT_ARGS__[@]}"; do
+        [[ "${__SCRIPT_ARGS__[$index]}" == "$1" ]] || return 1
+        shift
+    done
+}
+
+__std_initialize_runtime_state__() {
+    local script_dir="$1"
+    shift
+
+    if [[ -n "${BASE_BASH_LIBS_STD_INITIALIZED+x}" ]]; then
+        [[ "${BASE_BASH_LIBS_STD_INITIALIZED}" == 1 ]] || {
+            printf '%s\n' "base_bash_libs_init: runtime state marker is owned by the caller." >&2
+            return 1
+        }
+        return 0
+    fi
+
+    if [[ -n "${BASE_BASH_LIBS_STD_INIT_SOURCE+x}" || -n "${__SCRIPT_ARGS__+x}" || -n "${__SCRIPT_DIR__+x}" ]]; then
+        printf '%s\n' "base_bash_libs_init: initialization names are already owned by the caller." >&2
+        return 1
+    fi
+
+    __log_init__
+    declare -g __color__=0
+    declare -ga __std_cleanup_hooks=()
+    declare -ga __std_cleanup_paths=()
+    declare -ga __std_cleanup_entries=()
+    declare -gA __std_cleanup_path_fingerprints=()
+    declare -g __std_cleanup_dispatcher_installed=0
+    declare -g __std_cleanup_dispatcher_running=0
+    declare -g __std_cleanup_dispatcher_finished=0
+    declare -g __std_cleanup_pending_signal_status=0
+    declare -g __std_cleanup_debug_guard_running=0
+    declare -g __std_original_exit_trap=""
+    declare -g __std_original_exit_trap_spec=""
+    declare -g __std_cleanup_dispatcher_trap_spec=""
+    declare -g __std_original_int_trap=""
+    declare -g __std_original_int_trap_spec=""
+    declare -g __std_cleanup_int_trap_spec="__not-installed__"
+    declare -g __std_original_term_trap=""
+    declare -g __std_original_term_trap_spec=""
+    declare -g __std_cleanup_term_trap_spec="__not-installed__"
+    declare -g __std_original_debug_trap=""
+    declare -g __std_original_debug_trap_spec=""
+    declare -g __std_cleanup_debug_trap_spec="__not-installed__"
+
+    readonly BASE_BASH_LIBS_STD_INIT_SOURCE="$script_dir"
+    declare -ga __SCRIPT_ARGS__=("$@")
+    readonly -a __SCRIPT_ARGS__
+    declare -g __SCRIPT_DIR__="$script_dir"
+    readonly __SCRIPT_DIR__
+    readonly BASE_BASH_LIBS_STD_INITIALIZED=1
+}
+
+#
+# base_bash_libs_init - Explicitly initializes runtime state and filters wrapper
+# flags into a caller-owned indexed array. Sourcing the library never invokes
+# this function and never mutates positional parameters.
 #
-# __stdlib_init__ - The main initialization function for this library.
-#
-# This is the only function that executes when the library is sourced.
-# It sets up the environment by:
-#   1. Initializing the logging system.
-#   2. Parsing global command-line options like --debug, --verbose, --color.
+# Usage:
+#   declare -a app_args=()
+#   base_bash_libs_init app_args --source "$script" -- "$@"
 #
-__stdlib_init__() {
-    __log_init__
-    set_log_category_level -l base_bash_libs INFO
-
-    #
-    # Handle global arguments and strip them from the list before passing control to the main script.
-    # The environment variables LOG_DEBUG and LOG_UTC are recognized by the Python logging framework:
-    #   - LOG_DEBUG=1 sets the log level to DEBUG (Bash logging has VERBOSE but Python has only DEBUG)
-    #   - LOG_UTC=1   forces timestamps to use UTC
-    #
-    local arg parse_options=1
-    __color__=0
-    for arg in "${__SCRIPT_ARGS__[@]+"${__SCRIPT_ARGS__[@]}"}"; do
-        if ((parse_options)) && [[ "$arg" == "--" ]]; then
-            __new_args__+=("$arg")
-            parse_options=0
+base_bash_libs_init() {
+    local result_name="${1-}" source_path="" script_dir="" arg
+    local parse_config=1 color_requested=0 configure_runtime=0
+    local -a input_args=() filtered_args=()
+
+    (($# >= 1)) || {
+        printf '%s\n' "base_bash_libs_init: expected a result array name." >&2
+        return 1
+    }
+    __std_init_validate_result_array__ "$result_name" || return 1
+    shift
+
+    while (($#)); do
+        if ((parse_config)) && [[ "$1" == "--source" ]]; then
+            (($# >= 2)) || {
+                printf '%s\n' "base_bash_libs_init: --source requires a script path." >&2
+                return 1
+            }
+            source_path="$2"
+            shift 2
             continue
         fi
-        if ((parse_options)); then
+        if ((parse_config)) && [[ "$1" == "--" ]]; then
+            parse_config=0
+            shift
+            input_args+=("$@")
+            break
+        fi
+        input_args+=("$1")
+        shift
+    done
+
+    source_path="${source_path:-${BASE_BASH_BOOTSTRAP_SOURCE:-${BASH_SOURCE[1]-}}}"
+    if [[ -n "$source_path" ]]; then
+        script_dir="$(cd -- "$(dirname -- "$source_path")" &>/dev/null && pwd -P)" || {
+            printf '%s\n' "base_bash_libs_init: unable to resolve source directory from '$source_path'." >&2
+            return 1
+        }
+    else
+        script_dir="$(pwd -P)" || {
+            printf '%s\n' "base_bash_libs_init: unable to resolve the current caller directory." >&2
+            return 1
+        }
+    fi
+
+    if [[ -n "${BASE_BASH_LIBS_STD_INITIALIZED+x}" ]]; then
+        [[ "${BASE_BASH_LIBS_STD_INIT_SOURCE:-}" == "$script_dir" ]] || {
+            printf '%s\n' "base_bash_libs_init: already initialized for '$BASE_BASH_LIBS_STD_INIT_SOURCE'; requested '$script_dir'." >&2
+            return 1
+        }
+        __std_init_args_match__ "${input_args[@]+${input_args[@]}}" || {
+            printf '%s\n' "base_bash_libs_init: repeated initialization received different argv; refusing to hide the mismatch." >&2
+            return 1
+        }
+    else
+        configure_runtime=1
+        __std_initialize_runtime_state__ "$script_dir" "${input_args[@]+${input_args[@]}}" || return 1
+    fi
+
+    parse_config=1
+    for arg in "${input_args[@]+${input_args[@]}}"; do
+        if ((parse_config)) && [[ "$arg" == "--" ]]; then
+            filtered_args+=("$arg")
+            parse_config=0
+            continue
+        fi
+        if ((parse_config)); then
             case "$arg" in
                 --debug-wrapper)
-                    set_log_level DEBUG
-                    set_log_category_level -l base_bash_libs DEBUG
-                    export LOG_DEBUG=1
+                    if ((configure_runtime)); then
+                        set_log_level DEBUG
+                        set_log_category_level -l base_bash_libs DEBUG
+                        export LOG_DEBUG=1
+                    fi
                     ;;
                 --verbose-wrapper)
-                    # Deprecated compatibility option; prefer --debug-wrapper.
-                    set_log_level VERBOSE
-                    set_log_category_level -l base_bash_libs VERBOSE
-                    export LOG_DEBUG=1
+                    if ((configure_runtime)); then
+                        set_log_level VERBOSE
+                        set_log_category_level -l base_bash_libs VERBOSE
+                        export LOG_DEBUG=1
+                    fi
                     ;;
                 --utc-wrapper)
-                    export LOG_UTC=1
+                    if ((configure_runtime)); then
+                        export LOG_UTC=1
+                    fi
                     ;;
                 --color)
-                    __color__=1
+                    color_requested=1
                     ;;
                 *)
-                    __new_args__+=("$arg")
+                    filtered_args+=("$arg")
                     ;;
             esac
         else
-            __new_args__+=("$arg")
+            filtered_args+=("$arg")
         fi
     done
-    __init_colors__
+
+    if ((configure_runtime)); then
+        __color__="$color_requested"
+        __init_colors__
+        set_log_category_level -l base_bash_libs INFO
+        # Re-apply explicit debug levels after the default category gate.
+        for arg in "${input_args[@]+${input_args[@]}}"; do
+            if [[ "$arg" == "--debug-wrapper" ]]; then
+                set_log_category_level -l base_bash_libs DEBUG
+            elif [[ "$arg" == "--verbose-wrapper" ]]; then
+                set_log_category_level -l base_bash_libs VERBOSE
+            fi
+        done
+    fi
+
+    __std_init_publish_array__ "$result_name" "${filtered_args[@]+${filtered_args[@]}}"
     return 0
 }
 
@@ -375,7 +515,7 @@ import() {
     for lib; do
         import_path="$lib"
         if [[ "$lib" != /* ]]; then
-           [[ $__SCRIPT_DIR__ ]] || { printf '%s\n' "ERROR: __SCRIPT_DIR__ not set; import functionality needs it" >&2; exit 1; }
+           [[ -n "${__SCRIPT_DIR__-}" ]] || { printf '%s\n' "ERROR: base_bash_libs_init must run before relative imports" >&2; exit 1; }
            import_path="$__SCRIPT_DIR__/$lib"
         fi
         if [[ -f "$import_path" ]]; then
@@ -489,7 +629,7 @@ print_path() {
 # __log_init__ - Initializes the logging system.
 #
 # Sets up colors for interactive terminals and defines the log level hierarchy.
-# This is called automatically by __stdlib_init__.
+# This is called by base_bash_libs_init.
 #
 __log_init__() {
     # Map log level strings (FATAL, ERROR, etc.) to numeric values.
@@ -549,7 +689,7 @@ __log_source_location__() {
         __std_log_source_caller_rest="${__std_log_source_caller_info#* }"
         __std_log_source_caller_file="${__std_log_source_caller_rest#* }"
         if [[ -n "$__std_log_source_caller_file" &&
-            "$__std_log_source_caller_file" != "$__LIB_STD_PATH__" ]]; then
+            "$__std_log_source_caller_file" != "$BASE_BASH_LIBS_STD_SOURCE_PATH" ]]; then
             __std_log_source_path="$__std_log_source_caller_file"
             __std_log_source_line="$__std_log_source_caller_line"
             break
@@ -690,7 +830,7 @@ __print_log_record__() {
 
 #
 # __init_colors__ - Initialize colors used for logging
-# This is called from __stdlib_init__
+# This is called from base_bash_libs_init.
 #
 __init_colors__() {
     # If --color was not passed, NO_COLOR is set, or the log stream is not a terminal, disable colors.
@@ -3654,16 +3794,3 @@ wait_for_enter() {
 }
 
 #################################################### END OF FUNCTIONS ##################################################
-
-#
-# The only function that would be called upon sourcing of the library
-#
-__stdlib_init__
-# Used by companion libraries as a source-order guard.
-# shellcheck disable=SC2034
-readonly BASE_BASH_LIBS_STDLIB_LOADED=1
-
-# This is the crucial step: it resets the positional parameters ($@, $1, etc.)
-# of the *calling script* to the new, filtered list of arguments.
-set -- "${__new_args__[@]+"${__new_args__[@]}"}"
-unset __new_args__ __script_source__ __stdlib_init__ __log_init__ __init_colors__
diff --git a/lib/bash/std/tests/lib_std.bats b/lib/bash/std/tests/lib_std.bats
index c560972..b3e2b0f 100644
--- a/lib/bash/std/tests/lib_std.bats
+++ b/lib/bash/std/tests/lib_std.bats
@@ -6,7 +6,16 @@ readonly STDLIB_PATH="$BASE_BASH_DIR/std/lib_std.sh"
 
 create_script() {
     local script_path="$1"
-    cat > "$script_path"
+    local source_line init_lines content
+    shift
+
+    content="$(cat)"
+    source_line="source \"$STDLIB_PATH\""
+    if [[ "$content" == *"$source_line"* && "$content" != *"base-bash-libs: passive-source"* ]]; then
+        init_lines=$'declare -a base_bash_libs_test_args=()\nbase_bash_libs_init base_bash_libs_test_args -- "$@"\nset -- "${base_bash_libs_test_args[@]}"'
+        content="${content/"$source_line"/"$source_line"$'\n'"$init_lines"}"
+    fi
+    printf '%s\n' "$content" > "$script_path"
     chmod +x "$script_path"
 }
 
@@ -271,12 +280,100 @@ setup() {
     PATH="$BASE_TEST_ORIG_PATH"
     unset DRY_RUN dry_run LOG_DEBUG LOG_UTC NO_COLOR BASE_BASH_BOOTSTRAP_SOURCE BASE_CLI_PRIMARY_LOG
     source "$STDLIB_PATH"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args -- "$@"
 }
 
 teardown() {
     PATH="$BASE_TEST_ORIG_PATH"
 }
 
+@test "sourcing stdlib is passive and preserves caller state" {
+    bats_run bash -c '
+        set -euo pipefail
+        stdlib_path="$1"
+        set -- "argument with spaces" "" "literal-*"
+        IFS="| "
+        OPTIND=7
+        umask 027
+        shopt -s extglob nullglob nocasematch
+        trap ":" EXIT HUP INT TERM
+        before_args=$(printf "%s\\n" "$#" "${1-}" "${2-}" "${3-}")
+        before_set=$(set +o)
+        before_shopt=$(shopt -p)
+        before_traps=$(trap -p)
+        before_exports=$(export -p)
+        before_cwd=$(pwd -P)
+        source "$stdlib_path"
+        after_args=$(printf "%s\\n" "$#" "${1-}" "${2-}" "${3-}")
+        [[ "$before_args" == "$after_args" ]]
+        [[ "$before_set" == "$(set +o)" ]]
+        [[ "$before_shopt" == "$(shopt -p)" ]]
+        [[ "$before_traps" == "$(trap -p)" ]]
+        [[ "$before_exports" == "$(export -p)" ]]
+        [[ "$before_cwd" == "$(pwd -P)" ]]
+        [[ ! -v __SCRIPT_ARGS__ && ! -v __SCRIPT_DIR__ ]]
+        [[ ! -v _log_levels && ! -v __std_cleanup_hooks ]]
+        printf "passive=yes\\nargs=%s\\n" "$#"
+    ' bash "$STDLIB_PATH"
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"passive=yes"* ]]
+    [[ "$output" == *"args=3"* ]]
+    [[ "$output" != *"unbound variable"* ]]
+}
+
+@test "explicit init filters args, publishes context, and is idempotent" {
+    local script="$TEST_TMPDIR/explicit-init.sh"
+    local expected_dir
+
+    create_script "$script" <<EOF
+#!/usr/bin/env bash
+# base-bash-libs: passive-source
+source "$STDLIB_PATH"
+set -- --debug-wrapper alpha --color -- --debug-wrapper omega
+before="\$*"
+declare -a filtered=()
+base_bash_libs_init filtered --source "\$0" -- "\$@"
+[[ "\$*" == "\$before" ]]
+printf 'filtered=%s\n' "\${filtered[*]}"
+printf 'original=%s\n' "\${__SCRIPT_ARGS__[*]}"
+printf 'source-dir=%s\n' "\$__SCRIPT_DIR__"
+if base_bash_libs_init filtered --source "\$0" -- "\$@"; then
+    printf 'repeat=same\n'
+else
+    exit 41
+fi
+if base_bash_libs_init filtered --source "\$0" -- changed; then
+    exit 42
+else
+    printf 'different=diagnosed\n'
+fi
+EOF
+
+    expected_dir="$(cd "$(dirname "$script")" && pwd -P)"
+    bats_run bash "$script"
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"filtered=alpha -- --debug-wrapper omega"* ]]
+    [[ "$output" == *"original=--debug-wrapper alpha --color -- --debug-wrapper omega"* ]]
+    [[ "$output" == *"source-dir=$expected_dir"* ]]
+    [[ "$output" == *"repeat=same"* ]]
+    [[ "$output" == *"different=diagnosed"* ]]
+    [[ "$output" != *"unbound variable"* ]]
+}
+
+@test "stdlib source guard rejects caller-owned incompatible metadata" {
+    bats_run bash -c '
+        BASE_BASH_LIBS_STD_SOURCE_GUARD=1
+        BASE_BASH_LIBS_STD_SOURCE_VERSION=0.0.0
+        source "$1"
+    ' bash "$STDLIB_PATH"
+
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"incompatible base-bash-libs stdlib versions"* ]]
+}
+
 @test "deprecated --verbose-wrapper preserves original args and enables VERBOSE compatibility" {
     local script="$TEST_TMPDIR/check-init.sh"
 
@@ -417,6 +514,8 @@ EOF
         set -euo pipefail
         cd -- "$2"
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args -- "$@"
         source_dir=""
         get_my_source_dir source_dir
         [[ "$-" == *e* && "$-" == *u* ]]
@@ -1370,6 +1469,8 @@ EOF
     bats_run bash -c '
         set -euo pipefail
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args -- "$@"
         log_info_enter
         log_info_leave
         printf "after-log\n"
@@ -1386,6 +1487,8 @@ EOF
     bats_run bash -c '
         set -euo pipefail
         source "$1"
+        declare -a app_args=()
+        base_bash_libs_init app_args -- "$@"
         set_log_level NOT_A_LEVEL
         printf "after-log-error\n"
     ' bash "$STDLIB_PATH"
@@ -2581,6 +2684,8 @@ EOF
     create_script "$runner_script" <<'EOF'
 #!/usr/bin/env bash
 source "$1"
+declare -a runner_args=()
+base_bash_libs_init runner_args --
 primary_log="$2"
 command_script="$3"
 canary="$4"
@@ -3855,6 +3960,8 @@ EOF
     for candidate in var_name var_name_re function_name output_name declaration attributes logger color message source_path; do
         bats_run "$BASH" -c '
             source "$1"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             printf -v "$2" %s unchanged
             readonly "$2"
             std_command_path "$2" bash
diff --git a/lib/bash/str/README.md b/lib/bash/str/README.md
index f21671a..a1e4112 100644
--- a/lib/bash/str/README.md
+++ b/lib/bash/str/README.md
@@ -34,6 +34,8 @@ helpers are available.
 
 ```bash
 source "/absolute/path/to/lib/bash/std/lib_std.sh"
+declare -a app_args=()
+base_bash_libs_init app_args --source "${BASH_SOURCE[0]}" --
 source "/absolute/path/to/lib/bash/str/lib_str.sh"
 
 name="  Example Project  "
diff --git a/lib/bash/str/tests/lib_str.bats b/lib/bash/str/tests/lib_str.bats
index f0df2cb..033db9f 100644
--- a/lib/bash/str/tests/lib_str.bats
+++ b/lib/bash/str/tests/lib_str.bats
@@ -5,12 +5,21 @@ load ../../tests/test_helper.sh
 setup() {
     setup_test_tmpdir
     source "$BASE_BASH_DIR/std/lib_std.sh"
+    declare -a setup_args=()
+    base_bash_libs_init setup_args --source "$BASE_BASH_DIR/str/tests/lib_str.bats" --
     source "$BASE_BASH_DIR/str/lib_str.sh"
 }
 
 create_script() {
     local script_path="$1"
-    cat > "$script_path"
+    local content source_line init_lines
+    content="$(cat)"
+    source_line="source \"$BASE_BASH_DIR/std/lib_std.sh\""
+    if [[ "$content" == *"$source_line"* ]]; then
+        init_lines=$'declare -a base_bash_libs_test_args=()\nbase_bash_libs_init base_bash_libs_test_args -- "$@"\nset -- "${base_bash_libs_test_args[@]}"'
+        content="${content/"$source_line"/"$source_line"$'\n'"$init_lines"}"
+    fi
+    printf '%s\n' "$content" > "$script_path"
     chmod +x "$script_path"
 }
 
@@ -58,6 +67,8 @@ create_script() {
                 case "$mode" in *u*) set -u ;; esac
                 case "$mode" in *p*) set -o pipefail ;; esac
                 source "$2"
+                declare -a app_args=()
+                base_bash_libs_init app_args --
                 source "$3"
                 "$4"
                 exit $?
@@ -123,6 +134,8 @@ create_script() {
     for candidate in result_name value sign digits normalized; do
         bats_run "$BASH" -c '
             source "$1"
+            declare -a app_args=()
+            base_bash_libs_init app_args --
             source "$2"
             printf -v "$3" %s MiXeD
             readonly "$3"
diff --git a/tests/bash-42-logging-smoke.sh b/tests/bash-42-logging-smoke.sh
index b2889e4..706fb2f 100755
--- a/tests/bash-42-logging-smoke.sh
+++ b/tests/bash-42-logging-smoke.sh
@@ -76,6 +76,11 @@ main() {
         smoke_fail "unable to source lib_std.sh."
         return 1
     fi
+    local -a smoke_args=()
+    if ! base_bash_libs_init smoke_args --source "${BASH_SOURCE[0]}" --; then
+        smoke_fail "unable to initialize lib_std.sh."
+        return 1
+    fi
 
     if ! check_bash_version; then
         smoke_fail "the running Bash did not satisfy the supported version check."
diff --git a/tests/bash-option-contract.sh b/tests/bash-option-contract.sh
index ce4ca3b..051330a 100755
--- a/tests/bash-option-contract.sh
+++ b/tests/bash-option-contract.sh
@@ -721,6 +721,9 @@ contract_run_mode() {
         contract_source_module "$module"
     done
 
+    local -a contract_init_args=()
+    base_bash_libs_init contract_init_args --source "$contract_script_dir/bash-option-contract.sh" --
+
     contract_run_api_smoke std contract_std_api_smoke
     contract_run_api_smoke str contract_str_api_smoke
     contract_run_api_smoke list contract_list_api_smoke