feat(kernel): statement query tags + http_headers/user_agent_entry on use_kernel

[vikrantpuppala]

What

Connector follow-up to kernel PR #119. Wires two features onto the use_kernel path and bumps KERNEL_REV:

1. Statement-level query tags — cursor.execute(..., query_tags=...) now works on use_kernel (was NotSupportedError).
2. http_headers + user_agent_entry — both now reach the kernel.

Query tags

execute_command calls stmt.set_query_tags(query_tags) after set_sql instead of rejecting. The connector already hands a Dict[str, Optional[str]], which the kernel accepts directly (a None value → bare key in the SEA query_tags conf).

http_headers + user_agent_entry

• The kernel client forwards http_headers to the kernel Session (http_headers kwarg) — previously accept-and-ignored. session.py already passes all_headers, which carries the connector's composed User-Agent (PyDatabricksSqlConnector/x (entry)) + any caller headers + the SPOG x-databricks-org-id.
• Kernel-side: its own Authorization / x-databricks-org-id win; a caller User-Agent is appended to the kernel base UA (the base carries the DatabricksJDBCDriverOSS token that gates the SEA result disposition, so it's never replaced).
• So user_agent_entry is honored end-to-end via the existing http_headers forwarding — no separate kwarg needed.

Verification

• Unit: query_tags forwarded to set_query_tags (replaces the old rejection test); http_headers forwarded to the kernel Session (and omitted when empty). 194 kernel unit tests pass.
• Live e2e (test_kernel_backend.py): a query-tagged query, and a connection with user_agent_entry + a custom http_header, both round-trip green against a dogfood warehouse. The UA case specifically guards the append behavior — replacing the base UA would 400 on the result disposition.
• black + mypy clean.

Caveat

KERNEL_REV currently pins kernel PR #119's branch HEAD (c2053f68…) so this PR's CI can build against the new set_query_tags / http_headers surface. Re-pin to the squash-merge SHA once #119 lands before merging this.

This pull request and its description were written by Isaac.

[gopalldb]

🔴 P0 — Block Merge

KERNEL_REV pins an unmerged-kernel-PR HEAD (KERNEL_REV:1)

• c2053f68... is the live HEAD of OPEN kernel PR Relax pandas and alembic requirements #119 (state: "OPEN", mergedAt: null). Once Relax pandas and alembic requirements #119 squash-merges, this SHA lives forever as a PR-branch-only commit, never reachable from main. When the kernel
  branch is deleted (standard squash-merge cleanup), actions/checkout@…ref: c2053f68… will start failing for every future connector commit.
• Exact same defect class as PR feat(kernel): wire OAuth (M2M/U2M), TLS/mTLS, and Geometry on use_kernel path #819 v1. Third time this needs catching by humans because no CI gate exists.
• Fix: Block merge until kernel Relax pandas and alembic requirements #119 lands, then re-pin to the squash-SHA. And add git -C databricks-sql-kernel merge-base --is-ancestor "$REV" origin/main || exit 1 to kernel-e2e.yml (~line 226). The third
  repetition under the same author is a clear signal the gate belongs in this PR.

🟡 P1

1. kernel_auth_kwargs() raising bypasses secret scrub (client.py:189-205)
   PR feat(kernel): statement query tags + http_headers/user_agent_entry on use_kernel #823 doesn't introduce this — but it adds http_headers_kwargs in the same outside-try pattern, locking it in. The finally: at line 230 that pops oauth_client_secret only runs if control reaches the try:.
   A token-refresh failure or malformed provider in kernel_auth_kwargs leaks the M2M secret onto the long-lived connector object. Carryover from PR feat(kernel): wire OAuth (M2M/U2M), TLS/mTLS, and Geometry on use_kernel path #819 v2, untouched.
   Fix: Move all kwarg builds inside the try:.
2. End-to-end user_agent_entry claim has no actual assertion (tests/e2e/test_kernel_backend.py:108-120, tests/unit/test_kernel_client.py:1064-1073)
   The unit test forwards a literal pre-composed UA string; the e2e test only verifies SELECT 1 returns 1. A regression where session.py stops folding user_agent_entry into all_headers under use_kernel=True
   would pass both tests. The kernel commit itself notes the disposition-gating risk ("replacing kernel base UA breaks SEA result disposition / HTTP 400") — precisely the risk this test should cover.
   Fix: Add a unit test that constructs Session(..., user_agent_entry="myentry", use_kernel=True), mocks KernelDatabricksClient, and asserts the constructed http_headers contains the entry.
3. No connector-side test pinning the Authorization-header defense (tests/unit/test_kernel_client.py:1037-1079)
   The connector forwards every (k, v) pair from self._http_headers verbatim, with no skip for Authorization / x-databricks-org-id. Kernel defends today (skip-and-warn at http.rs:665-672), but a kernel-side
   regression weakening that filter wouldn't be caught on the connector side.
   Fix: Add the same lower() in {"authorization", "x-databricks-org-id"} skip in client.py:201-204, with a test asserting caller-supplied Authorization doesn't reach the forwarded header list. Double-walled.

🟢 P2

• WARN spam per request: connector always injects x-databricks-org-id; kernel always skips it (and warns) because it re-derives from http_path. Filter on connector side, or demote the kernel warn.
• query_tags={} is a silent no-op: consistent with existing semantics, just flagged for completeness.
• Breaking change: query_tags no longer raises NotSupportedError on use_kernel — worth a CHANGELOG line.

[vikrantpuppala]

Thanks @gopalldb — addressed in 5850fd68:

P0 — KERNEL_REV pins unmerged #119 HEAD
Acknowledged, and you're right this keeps recurring. The pin is intentional-for-now so this PR's CI builds against #119's new set_query_tags / http_headers surface; I'll re-pin to the squash-merge SHA once #119 lands, and this PR is explicitly blocked on that (called out in the description). On the CI gate — strongly agree it belongs in the repo; I'll add the git merge-base --is-ancestor "$REV" origin/main check to kernel-e2e.yml as a focused follow-up so this can't merge with an orphan SHA again (keeping it out of this PR so the gate's own review is clean, but happy to fold it in if you'd prefer).

P1

1. Secret scrub vs kwarg-build raise — fixed. All kwarg builds moved inside the try; auth_kwargs/tls_kwargs pre-declared empty so the finally scrub runs even if kernel_auth_kwargs raises mid-build.
2. user_agent_entry has no assertion — added TestKernelUserAgentForwarding: connect(use_kernel=True, user_agent_entry="my-partner-app") → asserts the entry appears in the User-Agent within the http_headers passed to the kernel client. Catches the "session.py stops folding it" regression.
3. No connector-side Authorization defense — added. The connector now drops Authorization / x-databricks-org-id (new _KERNEL_MANAGED_HEADERS) before forwarding, double-walling the kernel's skip. Tests assert neither reaches the forwarded list.

P2

• org-id WARN spam — resolved by the P1.3 fix: the connector no longer forwards x-databricks-org-id, so the kernel never sees it and never warns.
• query_tags={} no-op — unchanged (consistent with existing semantics).
• CHANGELOG — deferred to release-cut: entries are added at version bump (the Bump to version X commits), not per-PR; feat(kernel): wire OAuth (M2M/U2M), TLS/mTLS, and Geometry on use_kernel path #819/feat(kernel): wire retry/backoff params + verify metric-view on use_kernel #820 followed the same convention.

197 kernel unit tests pass; black + mypy clean; 3 e2e pass live against dogfood (incl. query_tags + user_agent_entry/http_headers round-trips).