Make arg_parse outputs transactional

CHANGELOG.md

@@ -21,6 +21,8 @@ and versions are tracked in the repo-root `VERSION` file.
   into caller scope.
 - Routed `gh_api_with_retry` retry sleeps through the stdlib sleep helper so
   shell `sleep` aliases or functions cannot shadow retry delays.
+- Made `arg_parse` publish output arrays only after a parse succeeds, leaving
+  caller-owned outputs unchanged on late parse failures.
 - Reused shared marker validation inside `update_file_section`.
 
 ## [1.2.0] - 2026-07-04

lib/bash/arg/lib_arg.sh

@@ -79,7 +79,7 @@ arg_parse() {
     local __arg_options_name="${1-}" __arg_positionals_name="${2-}" __arg_specs_name="${3-}"
     local __arg_current __arg_option_token __arg_option_value __arg_option_name __arg_option_kind
     local -a __arg_positionals=()
-    local -A __arg_token_kind=() __arg_token_name=()
+    local -A __arg_options=() __arg_token_kind=() __arg_token_name=()
     local __arg_parse_options=1
 
     if (($# < 4)) || [[ "${4-}" != "--" ]]; then
@@ -104,8 +104,6 @@ arg_parse() {
 
     __arg_parse_specs__ "$__arg_specs_name" __arg_token_kind __arg_token_name || return $?
 
-    eval "$__arg_options_name=()"
-    eval "$__arg_positionals_name=()"
     shift 4
 
     while (($# > 0)); do
@@ -132,7 +130,7 @@ arg_parse() {
                 return 2
             fi
 
-            __arg_set_assoc_value__ "$__arg_options_name" "$__arg_option_name" "$__arg_option_value"
+            __arg_set_assoc_value__ __arg_options "$__arg_option_name" "$__arg_option_value"
             continue
         fi
 
@@ -147,7 +145,7 @@ arg_parse() {
             fi
 
             if [[ "$__arg_option_kind" == "flag" ]]; then
-                __arg_set_assoc_value__ "$__arg_options_name" "$__arg_option_name" "1"
+                __arg_set_assoc_value__ __arg_options "$__arg_option_name" "1"
                 continue
             fi
 
@@ -162,13 +160,17 @@ arg_parse() {
 
             __arg_option_value="$1"
             shift
-            __arg_set_assoc_value__ "$__arg_options_name" "$__arg_option_name" "$__arg_option_value"
+            __arg_set_assoc_value__ __arg_options "$__arg_option_name" "$__arg_option_value"
             continue
         fi
 
         __arg_positionals+=("$__arg_current")
     done
 
+    eval "$__arg_options_name=()"
+    for __arg_option_name in "${!__arg_options[@]}"; do
+        __arg_set_assoc_value__ "$__arg_options_name" "$__arg_option_name" "${__arg_options[$__arg_option_name]}"
+    done
     eval "$__arg_positionals_name=(\"\${__arg_positionals[@]}\")"
     return 0
 }

lib/bash/arg/tests/lib_arg.bats

@@ -110,6 +110,21 @@ create_script() {
     [ "$parse_status" -eq 2 ]
 }
 
+@test "arg_parse preserves caller outputs when an unknown option follows accepted args" {
+    local -a specs=("verbose|flag|--verbose|-v")
+    local -A options=([existing]="keep")
+    local -a positionals=("old")
+    local parse_status=0
+
+    arg_parse options positionals specs -- --verbose item --unknown || parse_status=$?
+
+    [ "$parse_status" -eq 2 ]
+    [ "${options[existing]}" = "keep" ]
+    [ -z "${options[verbose]+set}" ]
+    [ "${#positionals[@]}" -eq 1 ]
+    [ "${positionals[0]}" = "old" ]
+}
+
 @test "arg_parse returns usage status when option values are missing" {
     local -a specs=("output|value|--output|-o")
     local -A options=()
@@ -121,6 +136,25 @@ create_script() {
     [ "$parse_status" -eq 2 ]
 }
 
+@test "arg_parse preserves caller outputs when a value option fails late" {
+    local -a specs=(
+        "verbose|flag|--verbose|-v"
+        "output|value|--output|-o"
+    )
+    local -A options=([existing]="keep")
+    local -a positionals=("old")
+    local parse_status=0
+
+    arg_parse options positionals specs -- --verbose --output || parse_status=$?
+
+    [ "$parse_status" -eq 2 ]
+    [ "${options[existing]}" = "keep" ]
+    [ -z "${options[verbose]+set}" ]
+    [ -z "${options[output]+set}" ]
+    [ "${#positionals[@]}" -eq 1 ]
+    [ "${positionals[0]}" = "old" ]
+}
+
 @test "arg_parse rejects registered options as missing option values" {
     local -a specs=(
         "verbose|flag|--verbose|-v"