Skip to content

Commit 0e522ce

Browse files
committed
docs(bot): clarify lesson provenance and formatting
Signed-off-by: Vu Anh Phung <vu.phung@databricks.com>
1 parent 5195fc6 commit 0e522ce

3 files changed

Lines changed: 14 additions & 7 deletions

File tree

‎.claude/knowledge/learning-log.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ Preserves the entries from PR #500 at
55
New daily entries belong in `journal/`; bots receive distilled rules from
66
`lessons.md`. This archive is never updated or injected into bot prompts.
77

8+
Lesson counts measure archived occurrences, not distinct PRs. A
9+
`log:YYYY-MM-DD` source points to that dated section below, including its author-run IDs.
10+
811
## Entries
912

1013
### 2026-08-13: learnings since 2026-08-12T17:43:56Z

‎.claude/knowledge/lessons.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
<!-- distilled-through: none -->
44

55
## Configuration and authentication
6-
76
- L-0001 (3×, #457): Trace option support through DBSQLClient, auth adapters and each transport. Type declarations and class comments do not establish forwarding; shared preparation can precede backend-specific filtering.
87
- L-0002 (2×, #501 #505): New auth branches must preserve ambiguity, credential-exclusion and persistence guards, including checks bypassed by early returns.
98
- L-0003 (2×, #501 #505): Normalize native-bound strings with isBlankOrReserved so blank, placeholder and whitespace values do not select unintended auth modes.
@@ -26,8 +25,8 @@
2625
- L-0020 (1×, #589): Reject missing required napi arguments in TypeScript with matching Thrift message/SQLSTATE before opaque native conversion errors.
2726
- L-0021 (1×, #583): Activating formerly ignored configuration changes existing users' behavior. Document consequences and invalidate persisted caches whose inputs no longer match, including OAuth scopes.
2827
- L-0022 (1×, #588): Match host/URL normalization across backends for slashes, embedded ports and IPv6; compare edge cases on both before changing either.
29-
## Native packages and public compatibility
3028

29+
## Native packages and public compatibility
3130
- L-0023 (4×, #505 #513 #514): New native fields need published binding support. Land router capability/version checks and all platform optionalDependency pins together; source-only KERNEL_REV bumps or accepted TypeScript fields do not ship support.
3231
- L-0024 (2×, #514 #506 #528): Regenerate native index.d.ts from the pinned build and review its contract changes. Mocked JS tests cannot verify ABI behavior or live-server compatibility.
3332
- L-0025 (1×, #514): Changelog entries for source-only native features must state the required follow-up published package bump and reference the kernel change.
@@ -37,8 +36,8 @@
3736
- L-0029 (2×, #535 #594): Published-library overrides and lockfiles do not constrain downstream runtime dependencies. Fix declared ranges and test those ranges instead of claiming local overrides protect consumers.
3837
- L-0030 (1×, #535): Security pins must not downgrade an already patched resolution; verify the advisory applies to the exact package.
3938
- L-0031 (1×, #568): Put backend-shared code in neutral utilities. Preserve deep-import compatibility with deprecated re-export shims and smoke tests when moving modules.
40-
## Errors, logging and telemetry
4139

40+
## Errors, logging and telemetry
4241
- L-0032 (1×, #514): Negative tests must assert the intended error shape or message so unrelated warehouse/auth failures cannot satisfy them.
4342
- L-0033 (2×, #523 #592 #587): StatusError structurally implements Error without extending it. Preserve its instance and custom fields; inspect message/sqlState structurally rather than requiring instanceof Error.
4443
- L-0034 (1×, #553): Synthetic Thrift error results must cover initial, directResults and polled status paths, allocate per-operation schemas, and close only real server handles.
@@ -50,8 +49,8 @@
5049
- L-0040 (1×, #596): Error telemetry may carry class, SQLSTATE and terminal/retryable status only; exclude messages, stacks, URLs and other free-form error text.
5150
- L-0041 (1×, #608): Decode every napi error, including status/hasMore calls. Any call that may fetch must share fetchChunk's best-effort failure cleanup, with rejecting-fake tests per call site.
5251
- L-0042 (1×, #619): Detect user close/cancel with dedicated persistent intent flags read before cleanup, not lifecycle.isClosed. Fetch-failure cleanup must still close cancelled operations.
53-
## Resources, networking and performance
5452

53+
## Resources, networking and performance
5554
- L-0043 (1×, #497): Portable Bash with nounset must guard empty-array expansion on older shells and distinguish unset-only defaults from unset-or-empty defaults.
5655
- L-0044 (1×, #513): Skipped before hooks still allow after hooks; gate destructive teardown on completed setup/backup.
5756
- L-0045 (2×, #523): Memoize backend resources per connection and close them explicitly. Close must await pending initialization so late-created resources cannot be orphaned.
@@ -60,17 +59,17 @@
6059
- L-0048 (1×, #529): Configuration tests must assert observable downstream effects, not merely absence of an exception.
6160
- L-0049 (1×, #554): Sanitize CI values entering unquoted SQL identifiers to letters, digits and underscores.
6261
- L-0050 (1×, #569): Type parity fixes must cover both metadata type_name and Arrow fallback mappings; test both through the native-free StatementStub harness.
63-
- L-0051 (1×, #500): Local HTTP download tests must avoid using a connection's HTTPS agent so they exercise the intended response failure.
62+
- L-0051 (1×, log:2026-11-07): Local HTTP download tests must avoid using a connection's HTTPS agent so they exercise the intended response failure.
6463
- L-0052 (1×, #568): Client-side pre-RPC validation needs direct rejection assertions and a unit check that no RPC occurred, rather than an E2E hang harness.
65-
- L-0053 (1×, #500): Thrift complex strings may contain bare date/timestamp literals and invalid JSON. Investigate swallowed parse failures with Arrow disabled when containers become empty.
64+
- L-0053 (1×, log:2026-11-11): Thrift complex strings may contain bare date/timestamp literals and invalid JSON. Investigate swallowed parse failures with Arrow disabled when containers become empty.
6665
- L-0054 (2×, #600): Clamp Node timers to 2**31-1 ms. End-to-end cancellation must stop attempts and backoff sleeps, clearing timers and listeners.
6766
- L-0055 (1×, #598): Retry non-idempotent execution only for proven pre-connection errors; connected-socket resets, broken pipes and timeouts may follow server delivery.
6867
- L-0056 (1×, #590): Filter framing, auth and user-agent headers from caller overrides and keep managed-header lists identical across transports.
6968
- L-0057 (1×, #595): ProxyAgent needs TLS options at its top level. Verify proxy TLS/mTLS with a real CONNECT proxy and generated test certificate.
7069
- L-0058 (1×, #577): Merge Arrow result rows with indexed concatChunks copies. Preserve provider batches and track owned leftover slices with offsets.
7170
- L-0059 (1×, #611): Every auxiliary HTTP request, including OAuth, exchange and CloudFetch, must use the connection provider's getAgent to honor proxy/TLS settings.
72-
## Bot workflow and CI
7371

72+
## Bot workflow and CI
7473
- L-0060 (2×, #499): Use explicit bracket notation for hyphenated dispatch input names and string-typed numeric knobs in workflows also triggered by schedule.
7574
- L-0061 (2×, #499): Omit unused prompt-file keys to use engine defaults; MODEL_ENDPOINT must name concrete serving-endpoints/model/invocations, not anthropic/invocations.
7675
- L-0062 (2×, #499): Respect author-tool restrictions on workflow edits and route blocked fixes to a human. Verify actual remote branch HEAD before reporting a change as pushed.

‎.prettierignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,8 @@ native/kernel/index.js
2222
# conventions, not this repo's prettier profile. Reflowing them would mangle the
2323
# carefully-wrapped prompt text.
2424
.bot
25+
26+
# Engine-managed learning files use the engine's canonical format.
27+
.claude/knowledge/learning-log.md
28+
.claude/knowledge/lessons.md
29+
.claude/knowledge/journal

0 commit comments

Comments
 (0)