diff --git a/.claude/knowledge/journal/2026-11-18.md b/.claude/knowledge/journal/2026-11-18.md new file mode 100644 index 000000000..f8bc64be9 --- /dev/null +++ b/.claude/knowledge/journal/2026-11-18.md @@ -0,0 +1,10 @@ +# Learning journal 2026-11-18 + +### 2026-11-18: Backend contracts and configuration — Injected session_conf defaults must yield to case-insensitive user overrides +**Context:** PR #1066 forwarded `max_download_threads` to the kernel by adding `cloudfetch_max_chunks_in_memory` to `session_conf`. It adds the key only when no key matching it case-insensitively is already in the user's `session_configuration`. It builds a new dict so the caller's mapping is not changed, and tests check both lowercase and uppercase overrides and that the original dict is untouched. +**Rule:** When injecting a connector-derived default into user-supplied session configuration, skip it if the user already set the key under any letter case, copy the mapping instead of mutating it, and test both override casings plus non-mutation. + +### 2026-11-18: Backend contracts and configuration — Reject bool when validating positive-integer options forwarded to the kernel +**Context:** PR #1066 validated `max_download_threads` with `isinstance(v, bool) or not isinstance(v, int) or v <= 0` in the kernel client before anything is forwarded. The invalid-value tests cover `True`, `0`, `-1`, `None`, `"4"` and `1.5`, and very large values are clamped to 256 before forwarding. +**Rule:** Validate integer options at the Python boundary by rejecting bool explicitly along with non-int and out-of-range values, test True alongside 0, negative, None, str and float, and clamp large values before forwarding them to native config. + diff --git a/.claude/knowledge/lessons.md b/.claude/knowledge/lessons.md index d7853a5eb..3f64682d5 100644 --- a/.claude/knowledge/lessons.md +++ b/.claude/knowledge/lessons.md @@ -1,6 +1,6 @@ # Lessons - + ## Backend contracts and configuration - L-0001 (1×, log:2026-08-13): When changing cursor.description type_code strings, update every downstream conversion branch that matches them. @@ -24,7 +24,8 @@ - L-0019 (1×, #951): TLS certfile may contain both certificate and key; reject keyfile without certfile. Validate each identity file separately for readable, non-empty contents before load_cert_chain. - L-0020 (1×, #974): Before replacing permissive wire parsing with typed parsing, verify real server representations and test case, quoting and numeric/bool variants. - L-0021 (1×, #985): SQL LIKE escape handling depends on preceding backslash-run parity; a one-character negative lookbehind cannot establish JDBC equivalence. -- L-0022 (1×, #1026): Reject bool explicitly when validating integer options before native conversion, so True/False cannot silently become 1/0. +- L-0022 (2×, #1066 #1026): Validate integer options at the Python boundary: reject bool explicitly plus non-int and out-of-range values, test True alongside 0, negative, None, str and float, and clamp large values before native conversion. +- L-0048 (1×, #1066): Inject connector-derived session_conf defaults only when the user has not set the key under any letter case; copy rather than mutate the mapping, and test both override casings plus non-mutation. ## Results and lifecycle - L-0023 (2×, #1019): Verify server metadata and forwarded configuration behavior with live tests and an opposite-setting positive control; fabricated metadata or forwarding-only unit tests cannot establish server behavior.