feat(sdk): add Lance backend struct + endpoint helper (companion to #35)

[AdaWorldAPI]

Summary

Companion to PR #35 (which forwarded the kv-lance feature from the SDK to surrealdb-core). PR #35 made the feature reachable at the SDK level; this PR adds the actual surface adopters need to USE the Lance backend from the SDK:

• Lance struct in engine::local (mirror of RocksDb, gated by kv-lance feature)
• opt/endpoint/lance.rs: endpoint helper that converts paths into lance:// URLs (mirror of rocksdb.rs)
• opt/endpoint/mod.rs: register mod lance; + Lance EndpointKind variant + "lance" URL scheme parser arm
• engine/any/native.rs: Lance arm in the connect-by-scheme match
• engine/any/wasm.rs: same for wasm

Pattern is a direct mirror of RocksDb; reviewers can diff the new files against rocksdb.rs / RocksDb's existing wiring to verify the correspondence.

Concrete downstream use (AdaWorldAPI/bardioc substrate-b)

use surrealdb::engine::local::Lance;
use surrealdb::Surreal;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = Surreal::new::<Lance>("path/to/lance/dataset").await?;
    // ... use db with the Lance backend
    Ok(())
}

Without this PR, declaring features = ["kv-lance"] at the SDK level (PR #35) lets the kv-lance backend compile in via surrealdb-core but the SDK exposes no Lance struct + no lance:// endpoint helper — so adopters cannot instantiate Surreal::new::<Lance>(...) from SDK-only code. Adopters had to depend directly on surrealdb-core OR construct the Datastore by hand, both of which defeat the SDK's purpose.

Tests

The existing RocksDb integration test in surrealdb/tests/api_integration/mod.rs uses the pattern use surrealdb::engine::local::{Db, RocksDb};. A parallel Lance test follows the same shape — happy to add in a follow-up PR (or in this one if maintainers want it bundled).

Provenance

• bardioc B1-step2 brutal 02 (code-correctness lens) surfaced the gap
• PR feat(sdk): forward kv-lance feature from surrealdb-core #35 (merged) forwarded the feature
• This PR completes the surface
• Draft: bardioc/.agent-logs/upstream-contributions/surrealdb-01-kv-lance-feature-on-sdk.md

Summary by CodeRabbit

Release Notes

• New Features
  • Added support for Lance as a key-value storage backend. Users can now connect to Lance-backed SurrealDB instances using the lance:// endpoint protocol with flexible configuration options. Live queries and database backup functionality are fully enabled for Lance connections. Lance support is available when the kv-lance feature is enabled during the build process.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5a634b83-559b-4e9c-8f91-1602ce621050

📥 Commits

Reviewing files that changed from the base of the PR and between 20ed488 and 1a5d51e.

📒 Files selected for processing (5)

• surrealdb/src/engine/any/native.rs
• surrealdb/src/engine/any/wasm.rs
• surrealdb/src/engine/local/mod.rs
• surrealdb/src/opt/endpoint/lance.rs
• surrealdb/src/opt/endpoint/mod.rs

---

📝 Walkthrough

Walkthrough

This PR adds Lance storage backend support to SurrealDB by integrating endpoint type registration, endpoint-to-configuration conversion, and engine-specific connection routing across native and WASM implementations.

Changes

Lance Backend Integration

Layer / File(s)	Summary
Endpoint type and module registration surrealdb/src/opt/endpoint/mod.rs, surrealdb/src/engine/local/mod.rs	Registers EndpointKind::Lance enum variant, declares the lance module, updates scheme parsing to recognize "lance" URIs, and introduces the public Lance engine marker struct with documentation and examples.
Endpoint conversion and trait wiring surrealdb/src/opt/endpoint/lance.rs	Implements IntoEndpoint<Lance> and into_endpoint::Sealed<Lance> traits via a macro that generates conversions for string/path types (&str, &String, String, &Path, PathBuf) and their config-paired forms, all using the "lance://" protocol.
Native and WASM engine routing surrealdb/src/engine/any/native.rs, surrealdb/src/engine/any/wasm.rs	Adds EndpointKind::Lance routing arms in native and WASM connection routers, spawning local routers with appropriate feature flags (Backup and LiveQueries for native; LiveQueries for WASM) and returning configuration errors when the kv-lance feature is disabled.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• AdaWorldAPI/surrealdb#35: Forwards the kv-lance Cargo feature flag so that the endpoint routing and engine paths added in this PR can be compiled and activated.

Poem

🐰 A lance so shiny, now at your command,
Local storage magic, everywhere we stand—
Endpoints convert with strings and paths so bright,
Routers route the connections left and right!
✨ SurrealDB grows more complete tonight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding Lance backend struct and endpoint helper to the SDK, which matches the core objective of exposing the Lance key-value backend at the SDK surface.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sdk-lance-backend-struct

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}