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

@@ -40,4 +40,12 @@ until a human merges it. The engineer author phase reads this log (see
 - **Context:** In PR #920's review of the SEA deprecation warning, a reviewer noted RT/Lakehouse warehouses *require* `use_sea=True` and refuse Thrift, so an unqualified "SEA should not be used in production, switch to kernel" message is misleading for those users.
   **Rule:** SEA (`use_sea=True`) is the only available backend for RT/Lakehouse warehouse types (they refuse Thrift), so deprecation/steering messaging must frame the kernel backend as the recommended path *where supported* rather than an unconditional drop-in replacement for all SEA users.
 
+### 2026-08-21: learnings since 2026-08-20T17:35:31Z
+- **Context:** In PR #922 a reviewer bot benchmarked kernel `row_limit=0` semantics against the SEA backend (`sea/models/requests.py`, which treats 0 as unlimited); a human corrected that SEA is deprecated and the kernel/server matches Thrift, which treats 0 as a real zero-row limit.
+  **Rule:** SEA is deprecated — when reasoning about cross-backend parity or value semantics for the kernel path (row limits, auth, etc.), use Thrift as the reference backend, not SEA; their conventions can diverge.
+- **Context:** In PR #921 a new JWT private-key M2M branch was inserted ahead of the existing branches in `kernel_auth_kwargs`, but it omitted the `oauth_jwt_key_file` + `auth_type="databricks-oauth"` ambiguity guard that its shared-secret sibling has, and the shared-secret branch never forwarded `token_url` even though docs said it applied there — both caught in review as silent-misroute / silently-dropped-option bugs.
+  **Rule:** When adding a higher-priority branch to a multi-branch resolver (e.g. auth routing), replicate every mutual-exclusion/conflict guard its sibling branches enforce and forward the same shared optional kwargs on all applicable branches, or callers get silently misrouted and documented options are dropped.
+- **Context:** PR #922 removed connector-side `row_limit` normalization/enforcement and delegated it to the kernel/server; the reviewer flagged that boundary cases (`0`, negatives) were dropped from the parametrized tests once enforcement moved server-side.
+  **Rule:** When removing connector-side normalization and delegating a contract to the server/kernel, keep tests that pin the boundary values (0, negative, None) — the server's semantics may differ from the old connector behavior, and delegation is exactly when a silent behavior regression can slip through.
+
 --- *Add new entries above this line (oldest→newest); newest sections sort to the bottom.* ---