Namespace public functions and globals for safe embedding

[codeforester]

Parent: #214

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

Problem

The framework exposes more than one hundred public functions and many generic names such as import, log_info, and COLOR_RED in Bash's process-global namespace. Broad adoption requires a collision-resistant public and internal naming contract.

Acceptance criteria

• Adopt one documented prefix for every public function, public global, environment variable, load guard, and internal symbol.
• Default loading exposes no generic public names or private-looking globals that can collide with applications or third-party libraries.
• Publish a complete old-to-new symbol map with migration guidance and, where practical, mechanical assistance.
• Ship v2 without legacy generic aliases or an opt-in compatibility layer; provide a symbol map and mechanical migration check or rewrite instead, and test that legacy names are not exported.
• Reserve and document the internal namespace while excluding it from compatibility guarantees.
• Add collision fixtures that source the framework alongside representative applications and third-party libraries.

Dependencies

• Make library sourcing passive and initialization explicit #222

Completion evidence

• PR Namespace v2 public symbols (#223) #251 merged to main on 2026-08-05.
• Added docs/v2-symbol-map.md and executable scripts/migrate-v2-symbols.
• Added namespace, collision, and migration contract tests in tests/namespace-contract.bats.
• ./tests/validate.sh passed: 479 BATS cases plus ShellCheck, Bash 4.2 option-contract, logging/release smoke, and examples.
• Public libraries remain single physical .sh files per STANDARDS.md.