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

@@ -102,4 +102,12 @@ until a human merges it. The engineer author phase reads this log (see
 - **Context:** PR #925 disabled kernel-path telemetry via `getattr(connection.session, "use_kernel", False) is True`, but backend routing selects the kernel with a plain truthiness check (`kwargs.get("use_kernel", False)`). An `is True` identity check diverges from truthiness for truthy-but-non-`True` values (e.g. `1`, `"true"`), so such a connection would route to the kernel yet keep Python-side telemetry on.
   **Rule:** When a second code path must mirror a routing/enable decision made elsewhere, reuse the *same* predicate form (truthiness vs identity) — an `is True` check silently diverges from a truthiness gate for non-bool truthy inputs.
 
+### 2026-09-05: learnings since 2026-09-04T17:27:09Z
+- **Context:** PR #940 forwarded `_pool_maxsize`→`max_connections` to the kernel's PyO3 `Session`; reviewer flagged (High) that it was passed unconditionally, and the author fixed it by routing through `_kernel_session_accepts_kwarg()`.
+  **Rule:** Any new kwarg forwarded to the kernel's `databricks_sql_kernel.Session` must be gated through `_kernel_session_accepts_kwarg(name)` — the PyO3 Session has a fixed signature with no `**kwargs` catch-all, so a kwarg the installed wheel doesn't declare raises `TypeError` and breaks every `use_kernel=True` connection on older in-range wheels (even when the value is None).
+- **Context:** In PR #940, `max_connections` only exists in kernel ≥1.1.0 but pyproject's floor stayed `^1.0.0`; reviewers noted the fall-closed gate silently drops the value on a 1.0.x wheel while the doc advertised it as unconditionally supported.
+  **Rule:** When forwarding an option that landed in a kernel version above the pyproject dependency floor, either bump the floor to that version or document that the option is honored only on kernel ≥ that version — a fall-closed capability gate drops it silently (no error/warning) on older in-range wheels, so docs must not overstate support for the pinned floor.
+- **Context:** PR #940's kernel-client tests mostly used a `**kwargs` MagicMock for `Session` that silently swallowed unsupported kwargs and hid the `TypeError` break; the regression was only exercised by a fixed-signature fake mirroring the real PyO3 surface.
+  **Rule:** To test that a caller correctly filters kwargs before passing them to a fixed-signature PyO3 object, assert against a fixed-signature fake (no `**kwargs`) that raises `TypeError` on an unexpected kwarg — a `**kwargs` MagicMock accepts everything and gives false confidence that forwarding is gated.
+
 --- *Add new entries above this line (oldest→newest); newest sections sort to the bottom.* ---