# GCP Dedicated TopSQL Hive Source Isolation

## Background

GCP Dedicated TopSQL data is stored as Parquet below per-instance Delta roots.
The broad external-table source URI, `component=.../*`, also matches each
instance's `_delta_log`. Those paths do not contain the complete Hive
partition-key sequence, so BigQuery rejects external-table DDL with
`invalidQuery`.

## Target behavior

- TopSQL remains a Parquet Hive external table; it must not combine multiple
  per-instance Delta roots as one Delta Lake table.
- TiDB and TiKV discover only immediate `instance=<value>/` child prefixes
  and build sorted `instance=<value>/date=*` source URIs. SQL and plan meta
  use `date=*`.
- Every generated URI has one wildcard and excludes sibling `_delta_log`
  directories. Empty components use reserved nonmatching URI shapes and return
  an empty query result.
- GCS discovery is authoritative for every TopSQL request. A discovery failure
  fails the request safely instead of using an existing potentially stale
  external table.
- Existing broad Parquet, legacy Delta, and known nested-component Clinic
  objects migrate atomically. Unrecognized objects remain conflicts.

## Implementation

- Add delimiter-based GCS child-prefix discovery, safe instance validation,
  deterministic URI construction, limits, source fingerprints, and per-table
  singleflight coordination to the BigQuery engine.
- Update the physical-table state machine and DDL postconditions for multiple
  managed source URIs. Physical tables use `CREATE OR REPLACE EXTERNAL TABLE`
  and are never deleted.
- Preserve guarded logical-view migration. The view is created only after all
  physical objects reconcile successfully.
- Add typed source-discovery errors and structured trace-correlated logs with
  fixed operation/reason enums and counts, without caller SQL, credentials, or
  GCS paths.

## Validation and delivery

- Cover source discovery, empty sources, limits, errors, state migration,
  unchanged fingerprints, changed instance sets, concurrency, and service
  error handling with focused unit tests.
- Run engine, service, handler, and API tests plus formatting and diff checks.
- Deploy only `clinic-data-service` to staging first. Verify logical and
  physical GCP TopSQL queries, no repeated DDL for an unchanged source set,
  safe failure on GCS-list errors, and the existing unknown-field contract.
- Production release, generated app-delivery PR merge, and production rollout
  remain separately authorized.