Standardize public error, status, output, and mutation semantics

[codeforester]

Parent: #214

Train position: 10 of 26
Phase: P1 — Passive, stable runtime and API

Problem

Public APIs vary in whether they return or terminate, how they place named outputs, which statuses mean usage or operational failure, and what goes to stdout, stderr, or logs. Inconsistent contracts make composition and automated reasoning unnecessarily risky.

Acceptance criteria

• Publish an API design charter for return versus exit, usage status, predicates, operational failures, timeouts, interruptions, stdout, stderr, logging, and named outputs.
• Make ordinary library functions return recoverable failures; expose explicitly named fatal or exit behavior only where process termination is intentional.
• Use one named-output signature convention and validate outputs, readonly state, array kind, aliases, and internal collisions before side effects.
• Declare mutation, idempotency, dry-run, environment, trap, cwd, and filesystem effects for every public API.
• Define and test interactive defaults, EOF and non-TTY behavior, including acceptance of the default displayed by [y/N] or [Y/n].
• Document and test metadata preservation, symlink handling, concurrent-write detection, and failure semantics for file mutation APIs.
• Audit the full public surface against the charter and record every v1.4.0-to-v2 behavior change in the migration inventory and checker; do not preserve inconsistent legacy behavior solely for compatibility.

Implementation notes

• PR Standardize v2 API contracts and adopt bl namespace #252 established the contract behavior; PR Adopt base_ public function namespace #253 corrected the unreleased namespace before Publish a machine-readable API and module manifest #225: merged commit c890ea385ba1d52f1288f98ac4e884e21b36146b.
• The unreleased v2 public function namespace is base_<module>_<name>: base_std_*, base_file_*, base_git_*, base_gh_*, base_str_*, base_arg_*, base_list_*, and base_launcher_*, with lifecycle functions base_init and base_require_version.
• Framework globals remain BASE_BASH_LIBS_*; implementation internals remain __base_bash_libs_*__. No bl_ or legacy aliases are defined.
• Ordinary import/version/filesystem/list failures return status; explicit base_std_fatal_error, base_std_exit_if_error, base_std_assert_*, and launcher process-boundary behavior remain intentionally terminating.
• base_file_update_file_section returns status 6 on optimistic-concurrency conflict and leaves the newer target untouched.
• Validation: ./tests/validate.sh </dev/null passed all 483 BATS tests, ShellCheck, smoke tests, examples, and the eight-option Bash contract matrix. Hosted macOS, Ubuntu, and Bash 4.2.53 checks passed for both PRs.

Dependencies

• Guarantee public APIs under caller-selected Bash options #216
• Harden cleanup deletion, trap, and resource-unwinding contracts #221
• Namespace public functions and globals for safe embedding #223