ci: introduce dynamic matrix balancer for GHA

[ohmayr]

Adds gha_matrix_balancer.py to dynamically chunk and distribute Python packages across GitHub Actions runners.

This orchestrator sets the foundation to replace legacy sequential bash loops, eliminating massive execution latency and 6-hour CI timeouts.
It provides:

1. Protection against GitHub's 256-job limit via dynamic bucketing.
2. "Heavy Lifter" isolation, ensuring complex packages (e.g., spanner) get dedicated VMs and don't bottleneck smaller GAPIC clients.
3. Clean GHA UI labels for clear developer telemetry.

Note: This is a zero-risk foundation PR. It adds the script and tests but does not yet modify any active .yaml workflows.

[gemini-code-assist]

Code Review

This pull request introduces a GitHub Actions matrix balancer script and its corresponding unit tests to optimize CI performance by isolating heavy-load packages. The review feedback correctly identifies several robustness issues: the script needs to ensure a valid JSON output even when no packages are found to prevent workflow failures, handle potential division-by-zero or value errors in bucket calculations, and normalize input paths to correctly identify packages and generate job labels.

[gemini-code-assist]

This section has two robustness issues:

1. If no valid packages are found, the script returns early without setting the buckets output. This will cause fromJson() to fail in GitHub Actions workflows. It is better to always output a valid JSON array (e.g., []).
2. The max_buckets calculation can crash with a ZeroDivisionError if matrix-multiplier is 0, or cause a ValueError in distribute_packages if max_buckets evaluates to 0 (which happens if matrix-multiplier > 250 or max-vms is 0).

    jobs = []
    if packages:
        # Protect against GitHub's 256-job hard limit and ensure at least 1 bucket
        multiplier = max(1, args.matrix_multiplier)
        max_buckets = max(1, min(250 // multiplier, args.max_vms))

        buckets = distribute_packages(packages, max_buckets)
        jobs = build_github_actions_jobs(buckets)

    jobs_json = json.dumps(jobs)

[gemini-code-assist]

If CHANGED_DIRS contains paths with trailing slashes (e.g., packages/my-pkg/), os.path.basename() will return an empty string. This breaks the heavy lifter detection and results in invalid job labels like + 5. Normalizing the paths ensures consistent behavior across different environments and input formats.

Suggested change

	changed_dirs = os.environ.get("CHANGED_DIRS", "").split()
	changed_dirs = [os.path.normpath(d) for d in os.environ.get("CHANGED_DIRS", "").split()]