From f8604556d5a9704e02acc057dfd6a495982b55b0 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 19 Jun 2026 19:04:50 +0000 Subject: [PATCH] docs(lance-backend): scope no-cc claim to core-only; SDK rustls caveat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address codex P2: the lite-unified TL;DR command included `rustls`, which on non-WASM enables the `aws_lc_rs` backend; `aws-lc-sys 0.41.0` depends on `cc` + `cmake` (Cargo.lock L884-893). That contradicted the "zero cc/C++ in the closure" claim for the SDK build. - Make the core-only command (`cargo check -p surrealdb-core --no-default-features --features kv-lance`) THE no-native-toolchain proof; scope the "zero cc/C++" claim to it. - Add a caveat section: the SDK `kv-lance,rustls` build drops the C++/gRPC storage engines but is NOT cc-free — rustls's crypto backend pulls aws-lc-sys. For a no-cc SDK, switch to the `ring` backend or drop TLS. - Add a troubleshooting row for cc/cmake-despite-no-rocksdb. The storage-layer claim (drop RocksDB → no C++ storage dependency) was always correct; only the TLS-transport conflation needed fixing. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01CcpLeEC3XK8Eye53GKBVvi --- .claude/board/AGENT_LOG.md | 27 +++++++++++++ .claude/lance-backend/LANCE_FEATURE_GATES.md | 40 +++++++++++++++----- 2 files changed, 57 insertions(+), 10 deletions(-) diff --git a/.claude/board/AGENT_LOG.md b/.claude/board/AGENT_LOG.md index 482e8c47ce61..d4013bb7a7a3 100644 --- a/.claude/board/AGENT_LOG.md +++ b/.claude/board/AGENT_LOG.md @@ -376,3 +376,30 @@ lift. deferred (matches lance-graph's own arrow handling). **Commit(s):** _filled in by the committing session_ + +--- + +## 2026-06-19 — codex P2 follow-up: rustls is not cc-free (LANCE_FEATURE_GATES) + +**Session:** post-merge correction (Opus, main thread) +**Branch:** `claude/jirak-math-theorems-harvest-rfii13` + +Codex flagged (P2) that the lite-unified TL;DR command included +`rustls`, which on non-WASM enables the `aws_lc_rs` backend; +`aws-lc-sys 0.41.0` depends on `cc` + `cmake` (verified `Cargo.lock` +L884-893). That contradicted the doc's "zero cc/C++ in the closure" +claim for the SDK command. Correction: +- The **core-only** command (`cargo check -p surrealdb-core + --no-default-features --features kv-lance`) is now THE no-cc proof; + the "zero cc/C++" claim is scoped to it explicitly. +- Added a ⚠ section: the SDK `--features kv-lance,rustls` build drops + the C++/gRPC *storage* engines but is NOT cc-free — rustls's crypto + backend pulls aws-lc-sys. To prove a no-cc SDK, swap to the `ring` + backend or drop TLS. +- Added a troubleshooting-matrix row for the cc/cmake-despite-no-rocksdb + symptom. + +Storage-layer claim (drop RocksDB → no C++ storage dep) was always +correct; only the TLS-transport conflation was wrong. + +**Commit(s):** _filled in by the committing session_ diff --git a/.claude/lance-backend/LANCE_FEATURE_GATES.md b/.claude/lance-backend/LANCE_FEATURE_GATES.md index d60ba28a6cbe..e6bc3c52caf9 100644 --- a/.claude/lance-backend/LANCE_FEATURE_GATES.md +++ b/.claude/lance-backend/LANCE_FEATURE_GATES.md @@ -16,20 +16,39 @@ ## TL;DR — the one command ```bash -# Lite-unified: pure-Rust columnar surreal, no RocksDB(C++), no TiKV(gRPC). -cargo build -p surrealdb --no-default-features --features kv-lance,rustls -# ^^^^^^^^^^^^^^^^^^^^^^ drop protocol-ws default too -# core-only (no SDK transport surface), fastest troubleshooting loop: +# THE no-native-toolchain proof: pure-Rust columnar core, zero cc/C++. +# No RocksDB(C++), no TiKV(gRPC), no TLS crypto backend. cargo check -p surrealdb-core --no-default-features --features kv-lance ``` -`--no-default-features` is the load-bearing flag. Without it the -default set (`kv-mem` on `surrealdb-core`, `protocol-ws,rustls` on the -`surrealdb` SDK) is *added to* whatever you pass — you would still get a -clean build but you would NOT have proven that `kv-lance` stands alone. +`--no-default-features` is the load-bearing flag. Without it the core +default set (`kv-mem`, `graphql`) is *added to* whatever you pass — you +would still get a clean build but you would NOT have proven that +`kv-lance` stands alone. + +**Observed (core-only):** clean compile, ~5m43s cold (first build of the +lance dependency closure), seconds incremental. **Zero `cc`/C++ in the +closure** — this claim holds for the core-only command above. + +### ⚠ The SDK build is NOT cc-free — TLS pulls aws-lc-sys + +```bash +# Lite-unified SDK (adds the client transport surface) — NOT no-cc: +cargo build -p surrealdb --no-default-features --features kv-lance,rustls +``` + +This still drops the C++ *storage* engines (RocksDB) and the gRPC one +(TiKV), but `rustls` is **not** a pure-Rust choice here: +`surrealdb/Cargo.toml` enables `rustls` with the **`aws_lc_rs`** crypto +backend on non-WASM targets, and `aws-lc-sys` depends on **`cc` + +`cmake`** (verified in `Cargo.lock`). So this command can require native +build tooling and does **not** satisfy "zero cc/C++". -**Observed:** clean compile, ~5m43s cold (first build of the lance -dependency closure), seconds incremental. Zero `cc`/C++ in the closure. +To prove a no-native-toolchain *SDK* build you must also swap the TLS +backend off `aws_lc_rs` (e.g. the `ring` backend the WASM target uses) +or drop TLS entirely — `rustls`'s storage-engine independence does not +extend to its crypto backend. For the storage-layer proof that this card +is about, use the **core-only** command, which has no TLS surface at all. --- @@ -95,6 +114,7 @@ crates.io lance for a fork build to make a compile pass. |---|---|---| | `error: linker cc not found` / libstdc++ link errors | a C++ backend (`kv-rocksdb`) is in the feature set | confirm `--no-default-features`; do not pass `kv-rocksdb` | | `failed to run protoc` | `kv-tikv` pulled gRPC | drop `kv-tikv`; lite-unified never needs it | +| `cc`/`cmake` invoked despite no `kv-rocksdb` | the **SDK** `rustls` feature pulls `aws-lc-sys` (cc+cmake) for the `aws_lc_rs` TLS backend — unrelated to storage | use the core-only command for the no-cc proof; for a no-cc SDK, switch rustls to the `ring` backend or drop TLS | | `Patch lance ... was not used in the crate graph` | fork wiring / transitive semver mismatch | check direct `[patch]` + `Cargo.lock`; resolve the transitive blocker, do NOT fall back to crates.io (P0) | | `lancedb 0.30 requires lance =7.0.0 but =X found` | lance family drifted out of lockstep | re-pin all three (`lance`, `lance-index`, `lancedb`) to the lance-graph workspace versions together | | build "works" but kv-lance never exercised | default features silently re-added `kv-mem` | the proving build MUST use `--no-default-features` |