[nathanjcochran]

First pass at branches for Fluid Services, in the CLI and MCP. Branch commands and tools are behind TIGER_EXPERIMENTAL. It's built on the API's service-nested branch endpoints (/projects/{project_id}/services/{service_id}/branches/...) and its new resolve endpoint (/projects/{project_id}/resolve), both synced into openapi.yaml. Neither is deployed yet, so this has only been tested against mocks.

Resolving refs. The branch and db commands resolve refs (an ID or a name) through the resolve endpoint, via common.Resolve, restricted by its type parameter:

• tiger branch commands resolve only branches. That one call also gives the parent service ID the nested branch endpoints need.
• tiger db commands resolve anything they can connect to: a service, a read replica set, or (behind the experimental gate) a branch.

tiger service commands still resolve through the ref filter on the service list, unchanged. The resolve endpoint's SERVICE type doesn't match read replica set IDs, which those commands accept today.

CLI. tiger branch has create, list, get, delete, start/resume, stop/pause, resize, rename, and update-password. tiger service branch is the same command as tiger branch create, built by one shared builder.

• Branch commands take a branch by ID or name. There's no default branch: service_id only ever holds a service ID, and create never changes it.
• Shell completion offers branch names, falling back to IDs, from the API's internal endpoint listing every branch in a project.
• create and list take a service, falling back to the default service.
• create saves the branch's initial tsdbadmin password (returned once by the API) the same way service create/fork do, and ends with "Connect with: tiger db psql ".
• Flags and output follow the matching tiger service commands. CPU/memory are checked against the fluid combinations.
• create and resize take --iops, matching the flag on the service commands: it's sent only when given, and resize accepts an IOPS-only change. The branch's IOPS is shown when the API returns it.
• get, create, and list show the parent service's name with its ID (service_name in JSON/YAML). get fetches the parent for it; a failed fetch is a warning, and the ID is shown alone.
• tiger service get shows a fluid service's branch count (branch_count), behind the gate. It lists the service's branches to count them; a failed listing is a warning, and the count is left out.

MCP. There's a tool for each branch command (branch_create, branch_list, branch_get, branch_delete, branch_start, branch_stop, branch_resize, branch_rename, branch_update_password), registered only behind the experimental gate.

• They take IDs only. Since the resolve endpoint also matches names, a match by name is refused.
• branch_create and branch_resize take an iops parameter, like the flag. The branch tools return a branch's IOPS in resources, as the service tools do.
• branch_get returns the parent's service_name, and service_get returns branch_count for a fluid service behind the gate (the field is left out of its schema otherwise).
• db_query and db_schema also go through the resolve endpoint now, so behind the gate they accept branch IDs too.

Read-only. A branch has no environment tag and always counts as DEV (common.BranchEnvironmentTag). So read_only=prod allows every branch operation, even on branches of a PROD service, and all blocks them all.

Supporting changes.

• Some existing functions took an api.Service and now need to work with branches too:
  • Password storage (the keyring and pgpass Save/Get/Remove, SavePasswordWithResult, and GetPassword) takes a PasswordTarget: the project ID, ID, and endpoint a password is keyed by. ServicePasswordTarget and BranchPasswordTarget build one. The keyring key format is unchanged.
  • ConnectionTarget, which the db commands and the db_query/db_schema tools connect through, held two api.Service values (the one to connect to, and the one whose credentials to use). It now holds just what connecting needs: kind (service, read replica, or branch), ID, name, status, environment, endpoint, pooler, and the credential owner. There's a constructor for each kind.
  • GetConnectionDetails takes a ConnectionTarget, and CheckServiceReady became CheckReady, taking a status.
• The db commands' help (behind the gate) says they take a branch, and their errors name a branch and the tiger branch commands (or branch_* tools) for one. db psql skips its read-replica menu for a branch, and its password recovery resets a branch's password through the branch endpoint.
• The wait loop is shared by WaitForService and WaitForBranch.
• sizeCompletion takes a configs func, so the branch commands can complete fluid-only sizes.
• A few helpers moved to _helper.go files because more than one group now uses them.

Changes to existing (public) commands

• Release ordering. The db commands now depend on the resolve endpoint (marked x-tigerdata-internal), so this can't be released before the API ships it.
• No guessed ports. A service endpoint or connection pooler without a port is no longer shown with 5432 or 6432 filled in, in tiger service get/list or the MCP service detail. pgpass password storage, which keys entries by host and port, refuses such an endpoint rather than assuming 5432. Branches follow the same rule.
• Empty lists stay structured. service list, service backup list, and branch list print [] for an empty list with -o json/yaml instead of nothing. Empty-result messages appear only in table output, on stderr.
• service delete lists branches. The API deletes a fluid service's branches along with it. tiger service delete lists them before its confirmation prompt and after the delete, and service_delete names them in its PROD prompt and its result. This isn't gated, since the branches go either way; only the help text and tool description mention branches behind the gate.
• db messages. "Not found" now reads "service or read replica set '…' not found". A read replica set that isn't active reads as "not ready" rather than "paused". Under discussion; likely to be reverted to the old behaviour.

Follow-ups

• Move the service commands to the resolve endpoint. Once read replica sets have their own commands (tiger replica … or similar), the tiger service commands no longer need to accept replica set IDs and can move to the resolve endpoint. Until then they keep the service-list lookup, which is the only way to reach a replica set today (TODO on resolveService).
• branch logs. The API has no branch logs endpoint, and the PRD puts branch logs at GA.
• Missing fields. There's no storage breakdown (the API doesn't return one).
• Branch Console URL. The branch commands don't print a Console URL, because the Console doesn't support branches yet. Its prototype puts a branch at /projects/<project>/branches/<branch>/overview, not under its parent service as the PRD has it, so add one once that's settled (TODO in prepareBranchForOutput).
• Service Console URL. tiger service get prints /dashboard/services/<service>, a legacy path the Console redirects into the browser's active project, which may not be the CLI's. The canonical form is /projects/<project>/services/<service>.
• MCP test harness. An unexpected mock call inside a tool handler makes the test hang until the go test timeout instead of failing, because gomock's Fatalf ends the handler goroutine without a response.

[nathanjcochran]

Split into a stack of smaller PRs: #268, #269, #270, #271, #272.