sea-napi-binding: scaffold native/sea/ crate with version() smoke test

Creates the napi-rs binding skeleton: Cargo.toml + lib.rs + module
stubs for database/connection/statement/result/error/logger. Captures
napi-rs tokio Handle via OnceCell in runtime.rs. Single working
#[napi] fn version() proves the binding loads + executes end-to-end
in Node.

Depends on krn-async-public-api branch (path dep on kernel).

Round 2 will add open/execute/fetch methods.

Author: msrathore-db

lib/sea/SeaNativeLoader.ts

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Loader for the SEA (Statement Execution API) native binding.
+ *
+ * Round 1b: minimal pass-through to the napi-rs auto-generated
+ * `index.js` shim in `native/sea/`. The shim itself picks the right
+ * per-platform `.node` artifact (linux-x64-gnu today; more triples in
+ * the bundling feature).
+ *
+ * Round 2+ will extend this with: lazy require to defer the `.node`
+ * load until the first SEA call, structured load-error diagnostics
+ * (which platform/arch was attempted, whether the package was
+ * installed at all), and a JS-side `DBSQLLogger` install path that
+ * forwards to the binding's `installLogger()` once that surface lands.
+ */
+
+// The path is relative to this file at runtime (`dist/sea/SeaNativeLoader.js`)
+// resolving to `dist/sea/../../native/sea/index.js` once `tsc` has emitted
+// to `dist/`. We use a require-time path resolution because the napi
+// shim is plain CommonJS and not part of the TS source tree.
+//
+// eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
+const native = require('../../native/sea/index.js');
+
+export interface SeaNativeBinding {
+  /** Returns the native crate version (smoke test for the binding's load path). */
+  version(): string;
+}
+
+/**
+ * Returns the loaded native binding. Throws if the platform-specific
+ * `.node` artifact cannot be found (napi-rs's auto-generated shim
+ * surfaces a descriptive error in that case).
+ */
+export function getSeaNative(): SeaNativeBinding {
+  return native as SeaNativeBinding;
+}
+
+/**
+ * Convenience accessor for the smoke-test path. Equivalent to
+ * `getSeaNative().version()` but reads more naturally in tests and
+ * REPLs.
+ */
+export function version(): string {
+  return getSeaNative().version();
+}

native/sea/.gitignore

@@ -0,0 +1,7 @@
+# Rust build artifacts
+target/
+Cargo.lock
+
+# Platform-specific `.node` binaries are produced per-platform by the
+# bundling feature; not committed.
+*.node

native/sea/Cargo.toml

@@ -0,0 +1,54 @@
+# Copyright (c) 2026 Databricks, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[package]
+name = "databricks-sea-native"
+version = "0.1.0"
+edition = "2021"
+authors = ["Databricks"]
+license = "Apache-2.0"
+description = "Databricks SQL Node.js SEA native binding (napi-rs)"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+# napi-rs v2 line; `napi6` enables N-API 6 surface, `async` enables the
+# `#[napi] async fn` glue that drives futures on napi-rs's tokio runtime.
+napi = { version = "2", default-features = false, features = ["napi6", "async"] }
+napi-derive = "2"
+
+# Kernel — path dep on the async-public-api branch worktree. Once the
+# kernel is published this becomes a version dep.
+databricks-sql-kernel = { path = "../../../../databricks-sql-kernel-sea-WT/async-public-api" }
+
+# Tokio is a transitive dep via the kernel and via napi's `async` feature;
+# declared explicitly so we can name `tokio::runtime::Handle` directly.
+tokio = { version = "1", default-features = false, features = ["rt"] }
+
+# Lazy `OnceCell` for the captured tokio Handle.
+once_cell = "1"
+
+# Tracing for kernel + binding diagnostics. The real subscriber is wired
+# in Round 3 via the ThreadsafeFunction logger bridge.
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt"] }
+
+[build-dependencies]
+napi-build = "2"
+
+[profile.release]
+lto = true
+strip = "symbols"

native/sea/build.rs

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+fn main() {
+    napi_build::setup();
+}

native/sea/index.d.ts

@@ -0,0 +1,60 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * JS-visible connection options. Empty in Round 1b; Round 2 may add
+ * per-connection scope fields (catalog, schema, session config map).
+ */
+export interface ConnectionOptions {
+  
+}
+/**
+ * JS-visible constructor options. Round 2 will populate this with
+ * real fields (host, warehouseId, auth, …); for the scaffold it is
+ * intentionally empty so the JS smoke test can call `new Database({})`
+ * without TypeScript complaining about unknown properties.
+ */
+export interface DatabaseOptions {
+  /**
+   * Workspace host URL (e.g. `https://workspace.databricks.com`).
+   * Optional in Round 1b; Round 2 makes it required.
+   */
+  host?: string
+  /** Warehouse id. Optional in Round 1b; Round 2 makes it required. */
+  warehouseId?: string
+}
+/**
+ * Returns the native binding's crate version (`CARGO_PKG_VERSION`).
+ *
+ * Acts as the round-1b smoke test: a JS `require()` of the `.node`
+ * artifact that successfully calls `version()` proves the binding's
+ * build + load + dispatch path is wired correctly.
+ */
+export declare function version(): string
+/** Opaque connection handle. Round 1b: marker only; no kernel state. */
+export declare class Connection {
+  /**
+   * Construct a new connection handle. Round 1b is a no-op shell;
+   * Round 2 will wire it to `Database`'s `Session` (likely via an
+   * async `Database::connect()` factory rather than a JS-side
+   * `new Connection()`).
+   */
+  constructor(options: ConnectionOptions)
+}
+/**
+ * Opaque database handle on the JS side.
+ *
+ * Holds `Option<Session>` so `close()` (Round 2) can `.take()` the
+ * session out and `.await` an async close, leaving `inner = None`.
+ * The `Drop` impl checks `inner` to decide whether to schedule a
+ * fire-and-forget close on the captured tokio runtime.
+ */
+export declare class Database {
+  /**
+   * Construct a new database handle. Round 1b: the options are
+   * stashed for diagnostic purposes only — no network call.
+   */
+  constructor(options: DatabaseOptions)
+}