refactor(bigquery): route via SET @@reservation instead of multi-project

[MaxHalford]

Context

BigQuery now supports setting a reservation per query via the @@reservation system variable:

SET @@reservation = 'projects/P/locations/L/reservations/R';  -- run in R
SET @@reservation = 'none';                                   -- force on-demand

lea previously routed queries between compute projects with different reservation assignments, so BigQueryClient juggled a dict of bigquery.Client instances. This PR replaces that with a single client and picks reservations via SQL.

Changes

• BigQueryClient: single self.client. Replaces script_specific_compute_project_ids with script_specific_reservations. Adds determine_reservation_for_script and a _open_session/_attach_session pair that emits SET @@reservation = '<value>' inside a BQ session and carries it to the main query via session_id. Skips the SET when a script has no override (the compute project's GCP-assigned reservation applies) and in dry-run.
• BigBluePickAPI: one constructor arg (reservation). ON-DEMAND picks map to 'none', RESERVATION picks map to that string. BigQueryClient no longer inherits from it — composition only.
• Precedence: LEA_BQ_SCRIPT_SPECIFIC_RESERVATIONS > Pick API > project's GCP assignment. Static overrides deliberately win so routed scripts aren't re-routed behind the user's back.
• Env vars:
  • LEA_BQ_SCRIPT_SPECIFIC_COMPUTE_PROJECT_IDS → LEA_BQ_SCRIPT_SPECIFIC_RESERVATIONS (value: "none" or projects/.../reservations/...; parsed with validation so typos surface at startup).
  • LEA_BQ_BIG_BLUE_PICK_API_{ON_DEMAND,REVERVATION}_PROJECT_ID → LEA_BQ_BIG_BLUE_PICK_API_RESERVATION (single var; fixes the REVERVATION typo).
• Drive-by: BigQueryJob.metadata was reading statistics.reservationUsage[0].name, which is not populated on real jobs — switched to statistics.reservation_id. The log line now correctly reports reservation billing (<id>) / on-demand billing.

Caveat — overriding to on-demand is gated

During validation, SET @@reservation = 'none' (or equivalently bq query --reservation_id=none) on int-data-kaya-prod was rejected:

Override to 'none' is not enabled. The option 'reservation_override_mode' is set to 'RESERVATION_OVERRIDE_MODE_UNSPECIFIED'. See https://cloud.google.com/bigquery/docs/default-configuration for configuration details.

The referenced doc does not list this option or its enum; ~25 brute-force guesses all failed. Routing to a reservation path works fine out of the box; a GCP support ticket is probably needed to unlock the on-demand override. This refactor is still strictly better regardless (single client, single compute project, typo fix, fixed billing-model log line).

Test plan

• uv run pytest lea/ — 75/75 pass (4 new tests for reservation resolution precedence).
• Live dry-run: lea run --scripts ../carbonfact/kaya/scripts --select core.accounts --dry-run --production with LEA_BQ_SCRIPT_SPECIFIC_RESERVATIONS={"kaya.core__accounts":"projects/int-data-kaya-prod/locations/EU/reservations/default"} — logs Using reservation '<path>' for materializing ... and SUCCESS ... (reservation billing (int-data-kaya-prod:EU.default)).
• Live run without --dry-run once the repo owner is ready.
• Override-to-on-demand path — blocked until reservation_override_mode is enabled at the project/org level.

Migration

Existing users must:

1. Replace LEA_BQ_SCRIPT_SPECIFIC_COMPUTE_PROJECT_IDS={...} with LEA_BQ_SCRIPT_SPECIFIC_RESERVATIONS={...} whose values are "none" or projects/.../reservations/....
2. Replace LEA_BQ_BIG_BLUE_PICK_API_ON_DEMAND_PROJECT_ID / LEA_BQ_BIG_BLUE_PICK_API_REVERVATION_PROJECT_ID with a single LEA_BQ_BIG_BLUE_PICK_API_RESERVATION=projects/.../reservations/....

🤖 Generated with Claude Code

---

Summary by cubic

Route BigQuery jobs via per-query reservations using SET @@reservation instead of switching compute projects. This simplifies config to a single client and improves billing visibility.

• Refactors

  • Use one BigQueryClient and set reservations in a session (SET @@reservation), carried to the main query via session_id.
  • Replace script-specific compute projects with script_specific_reservations. Precedence: LEA_BQ_SCRIPT_SPECIFIC_RESERVATIONS > Big Blue Pick API > project's assignment.
  • Big Blue Pick API now maps picks to reservations: ON-DEMAND → 'none', RESERVATION → LEA_BQ_BIG_BLUE_PICK_API_RESERVATION. Composition only.
  • Fix billing logs by reading statistics.reservation_id; now reports reservation billing (<id>) or on-demand billing.
  • Note: forcing on-demand ('none') may be disabled by your project's reservation_override_mode.

• Migration

  • Replace LEA_BQ_SCRIPT_SPECIFIC_COMPUTE_PROJECT_IDS with LEA_BQ_SCRIPT_SPECIFIC_RESERVATIONS values: "none" or projects/.../reservations/....
  • Replace LEA_BQ_BIG_BLUE_PICK_API_ON_DEMAND_PROJECT_ID and LEA_BQ_BIG_BLUE_PICK_API_REVERVATION_PROJECT_ID with LEA_BQ_BIG_BLUE_PICK_API_RESERVATION.

^{Written for commit 47a3a44. Summary will update on new commits.}