Claude Code → BigQuery: OTel-native OTLP receiver endpoint

# Claude Code → BigQuery: OTel-native OTLP receiver

A new OTLP ingest surface (Cloud Run → Pub/Sub → BigQuery Storage Write API, Terraform-deployed into the customer project) that lands Claude Code's OpenTelemetry logs/metrics/(gated) traces into **OTel-native BigQuery tables as the source of truth**, with BQAA `agent_events` delivered as a projection layer on top.

📄 **Full design spec:** [`docs/otlp_receiver_design.md`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/docs/otlp_receiver_design.md)

Key decisions (detail in the doc):
- ClickHouse-derived native `otel_*` tables, BigQuery-adapted and versioned (`otel_schema_version`): `otel_logs`, five per-type `otel_metric_*` tables, gated `otel_spans`, `otlp_dead_letter`.
- Native JSON attribute bags + promoted scalar columns for partition/cluster (can't cluster on JSON).
- Append-only writer + per-signal idempotency with a **required, replay-invariant `source_position`**; read-time dedup.
- BQAA `agent_events_otlp` projection as a scheduled-`MERGE` curated table (materialized views can't express the window-function dedup) + schema-parity test.
- Preserved metric temporality; two-mode raw bodies; auth-dependent identity; two-tier trace gating.

---

## Scope / notes

- Standalone delivery; no dependency on Anthropic-side changes.
- #317 reuses this same OTel-native receiver and Pub/Sub envelope for Codex.
- BQAA compatibility is delivered through views/projections so existing SDK workflows keep working without making `agent_events` the ingest schema.
- Relates to distribution work in #251.

## Acceptance criteria

- [ ] New OTLP receiver accepts OTLP/gRPC + OTLP/HTTP protobuf for logs and metrics on `/v1/logs` + `/v1/metrics`; traces gated behind a flag (HTTP+JSON out of scope).
- [ ] **Auth provisioning**: bearer/OTLP headers via Secret Manager + Cloud Run injection + rotation (mTLS optional); unauthenticated requests rejected.
- [ ] **OTel-native BigQuery tables** created for logs and metric points in P0, with trace/span table behind the trace gate; tables preserve resource attributes, scope, attributes, timestamps, ids, metric temporality/kind, and raw-preservation metadata.
- [ ] **Pub/Sub envelope v1** pinned around decoded OTLP records/points/spans, with idempotency, **required `source_position`** (request hash + indices) feeding the log/metric keys, source metadata, raw preservation, parse errors, DLQ, and replay fields.
- [ ] **Idempotency / backpressure** under load; regional BigQuery writes honored; append-only writer in P0 with read-time dedup views.
- [ ] **Malformed-OTLP handling** and dead-lettering of unparseable/failed records to `otlp_dead_letter` + DLQ, with replay.
- [ ] **Metrics temporality preserved**; no silent delta/cumulative mis-aggregation. Derived dashboard views document their temporality assumptions.
- [ ] **Raw-API-body two-mode** support: inline bodies stored natively with truncation metadata; file-mode `body_ref` stored as a non-dereferenceable source-local reference; raw bodies off by default.
- [ ] **BQAA projection views** provided (`agent_events_otlp`, metrics/dashboard views) with provenance/crosswalk fields and privacy gate state, without requiring an `agent_events` schema migration.
- [ ] **Projection crosswalk** includes `api_refusal` / body events / `plugin_loaded`; unknown events remain preserved in native OTel tables and may project to `otlp.unknown`.
- [ ] Retention/cardinality controls + partitioning/clustering on native OTel tables and projection views.
- [ ] OTLP conformance fixture suite: valid log, valid metric, malformed→dead-letter, unauthenticated, duplicate/idempotency replay, DLQ replay, regional write, privacy-gate states, and BQAA projection correctness.
- [ ] SQL views + sample dashboard/query pack provided; subprocess caveat documented.
- [ ] All data stays within the customer perimeter.

Start with docs/otlp_receiver_design.md, then trace the repository entry points for Terraform deployment, Cloud Run, Pub/Sub, and BigQuery writes. Implement the OTLP/gRPC and OTLP/HTTP logs and metrics paths, with gated traces, as specified; done means the listed conformance fixtures, auth, DLQ, idempotency, native tables, and BQAA projections satisfy the acceptance criteria.

Written by the indexing model from the issue text.