learn: retrospective learnings

Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

Author: peco-engineer-bot[bot]

.claude/knowledge/learning-log.md

@@ -52,4 +52,10 @@ until a human merges it. The engineer author phase reads this log (see
 - **Context:** PR #924 added an e2e test verifying the kernel (Rust) and Python driver share a single `databricks.sql` FileHandler; it had to call `_kernel_mod.reset_logging()` before/after connecting because earlier tests had populated pyo3-log's effective-level cache.
   **Rule:** When testing or configuring pyo3-log-backed logging, changing a parent logger's level does not retroactively update pyo3-log's cached effective levels — reset the pyo3-log cache after adjusting levels (and beware cross-test cache pollution) so records actually flow at the expected level.
 
+### 2026-08-23: learnings since 2026-08-22T17:32:00Z
+- **Context:** PR #919 (kernel `auth_bridge.py`) added an `azure-oauth` U2M branch that `return`ed before the shared "ambiguity" guards; reviewers found it silently ignored `oauth_client_secret` / `credentials_provider` combos that the parallel `databricks-oauth` path rejects with a loud `NotSupportedError`, misrouting the session through the wrong flow.
+  **Rule:** A routing branch that returns early, before shared validation/ambiguity guards, silently bypasses those guards — route new variants through the shared post-guard path (or re-apply the guards in the branch) so conflicting-signal inputs fail loudly at session-open instead of being silently misrouted to the wrong principal/flow.
+- **Context:** PR #919 moved Azure endpoint/scope/app-id resolution out of the connector bridge and into the kernel, but left behind a `hostname` parameter on `kernel_auth_kwargs` (threaded from `client.py` and every new test), an unused `get_effective_azure_login_app_id` import, and a module docstring still describing the old bridge-computes-the-bundle design — reviewers flagged all three repeatedly as dead/misleading surface.
+  **Rule:** When you delegate a computation to another layer, delete the now-inert plumbing it leaves behind (parameters, call-site args, imports) and update docstrings/PR descriptions that still describe the pre-delegation behavior — stale dead surface misleads future readers into assuming it still affects resolution.
+
 --- *Add new entries above this line (oldest→newest); newest sections sort to the bottom.* ---