Bump version: 0.38.0-beta.2 → 0.38.0-beta.3

chore: update lance dependency to v11.0.0-beta.16 (#3992 )
Updates Lance dependencies and Java lance-core to v11.0.0-beta.16. Also narrows the dependency updater's package matching so the local LanceDB crate remains a path dependency. Lance tag: https://github.com/lance-format/lance/releases/tag/v11.0.0-beta.16 --------- Co-authored-by: Yang Cen <bubble-cal@outlook.com>
2026-08-28 08:58:41 +00:00 · 2026-08-21 10:25:20 +00:00 · 2026-08-21 18:24:22 +08:00 · 2026-08-21 18:18:55 +08:00 · 2026-08-21 17:19:13 +08:00 · 2026-08-21 17:01:04 +08:00
129 changed files with 8225 additions and 1236 deletions
@@ -5,7 +5,3 @@ This directory contains repo-scoped code agent skills for the LanceDB project.
 Each skill is a folder that contains a required `SKILL.md` and optional bundled resources.

 Codex discovers skills from `.agents/skills` in the current working directory and parent directories.
-
-The `lancedb` skill lives in the `plugins/lancedb` plugin (see `plugins/lancedb/skills/lancedb`)
-so it can be installed via the plugin marketplaces (`.claude-plugin/marketplace.json` and
-`.agents/plugins/marketplace.json`); the `lancedb` entry here is a symlink into that plugin.
@@ -1 +0,0 @@
-../../plugins/lancedb/skills/lancedb
@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.38.0-beta.0"
+current_version = "0.38.0-beta.3"
 parse = """(?x)
    (?P<major>0|[1-9]\\d*)\\.
    (?P<minor>0|[1-9]\\d*)\\.
@@ -9,6 +9,18 @@ debug = true
 codegen-units = 16
 lto = "thin"

+[profile.release-no-lto]
+inherits = "release"
+debug = true
+lto = false
+# Prioritize compile time when LTO is not relevant to the measurement.
+codegen-units = 16
+
+[profile.bench]
+inherits = "release"
+lto = "thin"
+codegen-units = 16
+
 [target.'cfg(all())']
 rustflags = [
    "-Wclippy::all",
@@ -0,0 +1,30 @@
+name: CI scripts
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ci/set_lance_version.py
+      - ci/tests/**
+      - .github/workflows/ci-scripts.yml
+  pull_request:
+    paths:
+      - ci/set_lance_version.py
+      - ci/tests/**
+      - .github/workflows/ci-scripts.yml
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test CI scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Run tests
+        run: python -m unittest discover -s ci/tests -v
@@ -229,7 +229,8 @@ jobs:
      # Make sure wheels are not included in the Rust cache
      - name: Delete wheels
        run: rm -rf target/wheels
-  pydantic1x:
+  min-deps:
+    name: "Minimum dependencies"
    timeout-minutes: 60
    runs-on: "ubuntu-24.04"
    defaults:
@@ -259,8 +260,7 @@ jobs:
          save-if: ${{ github.ref == 'refs/heads/main' }}
      - name: Install lancedb
        run: |
-          pip install "pydantic<2"
-          pip install pyarrow==16
+          pip install "pydantic==2.7.4" "pyarrow==16"
          pip install --extra-index-url https://pypi.fury.io/lance-format/ --extra-index-url https://pypi.fury.io/lancedb/ -e .[tests]
      - name: Run tests
        run: pytest -m "not slow and not s3_test" -x -v --durations=30 python/tests
@@ -121,7 +121,6 @@ jobs:
      # Need up-to-date compilers for kernels
      CC: clang-18
      CXX: clang++-18
-      GH_TOKEN: ${{ secrets.SOPHON_READ_TOKEN }}
    steps:
      - uses: actions/checkout@v6
        with:
@@ -165,11 +164,40 @@ jobs:
      - name: Run feature tests
        run: CARGO_ARGS="--profile ci" make -C ./lancedb feature-tests
      - name: Run examples
-        run: cargo run  --profile ci --example simple --locked
+        run: cargo run --profile ci --all-features --example simple --locked
+
+  remote:
+    timeout-minutes: 30
+    # Running this requires access to secrets, so skip if this is a PR from a
+    # fork. Keep it separate from the all-features build so Cargo does not
+    # retain both dependency graphs in one target directory.
+    if: github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork
+    runs-on: ubuntu-2404-4x-x64
+    defaults:
+      run:
+        shell: bash
+        working-directory: rust
+    env:
+      CC: clang-18
+      CXX: clang++-18
+      GH_TOKEN: ${{ secrets.SOPHON_READ_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          lfs: true
+      - uses: Swatinem/rust-cache@v2
+        with:
+          # Remote tests use a different feature graph from the main Linux
+          # job. Cache downloads, but build into a fresh target directory.
+          cache-targets: false
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+      - name: Install dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y protobuf-compiler libssl-dev
+      - uses: rui314/setup-mold@v1
      - name: Run remote tests
-        # Running this requires access to secrets, so skip if this is
-        # a PR from a fork.
-        if: github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork
        run: CARGO_ARGS="--profile ci" make -C ./lancedb remote-tests

  macos:
@@ -18,6 +18,9 @@ Common commands:
 * Run specific test: `cargo test --quiet --features remote -p <package_name> --test <test_name>`
 * Lint: `cargo clippy --quiet --features remote --tests --examples`
 * Format Rust: `cargo fmt --all`
+* Use repository-defined Cargo profiles instead of ad hoc LTO overrides.
+* Use `release-with-debug` for benchmarks and profiling so optimized builds keep debug symbols without a rebuild.
+* Use `release-no-lto` only for local debugging, IO-bound benchmarks, or compile-time-sensitive performance investigation where LTO would not affect the measured bottleneck.
 * Format Python: `ruff format .`
 * Lint Python: `ruff check .`
 * Bootstrap Python dev env: `cd python && uv run --extra tests --extra dev maturin develop --extras tests,dev`
@@ -959,7 +959,7 @@ dependencies = [
 "aws-smithy-runtime-api",
 "aws-smithy-types",
 "h2 0.3.27",
- "h2 0.4.14",
+ "h2 0.4.16",
 "http 0.2.12",
 "http 1.5.0",
 "http-body 0.4.6",
@@ -1740,9 +1740,9 @@ dependencies = [

 [[package]]
 name = "cmov"
-version = "0.5.3"
+version = "0.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3f88a43d011fc4a6876cb7344703e297c71dda42494fee094d5f7c76bf13f746"
+checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a"

 [[package]]
 name = "colorchoice"
@@ -3455,8 +3455,8 @@ checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"

 [[package]]
 name = "fsst"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "rand 0.9.5",
@@ -3877,9 +3877,9 @@ dependencies = [

 [[package]]
 name = "h2"
-version = "0.4.14"
+version = "0.4.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "171fefbc92fe4a4de27e0698d6a5b392d6a0e333506bc49133760b3bcf948733"
+checksum = "a9f37a958b41b3b19ee2707c06439c0e9e547e847223eb791ecb0cb821c65e27"
 dependencies = [
 "atomic-waker",
 "bytes",
@@ -4188,7 +4188,7 @@ dependencies = [
 "bytes",
 "futures-channel",
 "futures-core",
- "h2 0.4.14",
+ "h2 0.4.16",
 "http 1.5.0",
 "http-body 1.1.0",
 "httparse",
@@ -4815,8 +4815,8 @@ checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"

 [[package]]
 name = "lance"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arc-swap",
 "arrow",
@@ -4888,8 +4888,8 @@ dependencies = [

 [[package]]
 name = "lance-arrow"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4911,7 +4911,7 @@ dependencies = [
 [[package]]
 name = "lance-arrow-scalar"
 version = "58.0.0"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4925,7 +4925,7 @@ dependencies = [
 [[package]]
 name = "lance-arrow-stats"
 version = "58.0.0"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -4934,8 +4934,8 @@ dependencies = [

 [[package]]
 name = "lance-bitpacking"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrayref",
 "crunchy",
@@ -4945,8 +4945,8 @@ dependencies = [

 [[package]]
 name = "lance-core"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4983,8 +4983,8 @@ dependencies = [

 [[package]]
 name = "lance-datafusion"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5013,8 +5013,8 @@ dependencies = [

 [[package]]
 name = "lance-datagen"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5031,8 +5031,8 @@ dependencies = [

 [[package]]
 name = "lance-derive"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -5041,8 +5041,8 @@ dependencies = [

 [[package]]
 name = "lance-encoding"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-arith",
 "arrow-array",
@@ -5075,8 +5075,8 @@ dependencies = [

 [[package]]
 name = "lance-file"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-arith",
 "arrow-array",
@@ -5107,8 +5107,8 @@ dependencies = [

 [[package]]
 name = "lance-index"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arc-swap",
 "arrow",
@@ -5172,8 +5172,8 @@ dependencies = [

 [[package]]
 name = "lance-index-core"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5195,8 +5195,8 @@ dependencies = [

 [[package]]
 name = "lance-io"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5232,8 +5232,8 @@ dependencies = [

 [[package]]
 name = "lance-linalg"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5247,8 +5247,8 @@ dependencies = [

 [[package]]
 name = "lance-namespace"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow",
 "async-trait",
@@ -5260,8 +5260,8 @@ dependencies = [

 [[package]]
 name = "lance-namespace-impls"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow",
 "arrow-ipc",
@@ -5314,8 +5314,8 @@ dependencies = [

 [[package]]
 name = "lance-select"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -5329,8 +5329,8 @@ dependencies = [

 [[package]]
 name = "lance-table"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5370,8 +5370,8 @@ dependencies = [

 [[package]]
 name = "lance-testing"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5384,8 +5384,8 @@ dependencies = [

 [[package]]
 name = "lance-tokenizer"
-version = "11.0.0-beta.13"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.13#ee41152ceb9a78e5df4d2456fdbdb98542eb2059"
+version = "11.0.0-beta.16"
+source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.16#d514a61fa7e449dedcd03571eabd338b3c84b170"
 dependencies = [
 "frostem",
 "icu_segmenter",
@@ -5398,7 +5398,7 @@ dependencies = [

 [[package]]
 name = "lancedb"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.2"
 dependencies = [
 "ahash",
 "anyhow",
@@ -5486,7 +5486,7 @@ dependencies = [

 [[package]]
 name = "lancedb-nodejs"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.2"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -5511,7 +5511,7 @@ dependencies = [

 [[package]]
 name = "lancedb-python"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.2"
 dependencies = [
 "arrow",
 "async-trait",
@@ -8426,7 +8426,7 @@ dependencies = [
 "encoding_rs",
 "futures-core",
 "futures-util",
- "h2 0.4.14",
+ "h2 0.4.16",
 "http 1.5.0",
 "http-body 1.1.0",
 "http-body-util",
@@ -10082,7 +10082,7 @@ dependencies = [
 "async-trait",
 "base64 0.22.1",
 "bytes",
- "h2 0.4.14",
+ "h2 0.4.16",
 "http 1.5.0",
 "http-body 1.1.0",
 "http-body-util",
@@ -13,20 +13,21 @@ categories = ["database-implementations"]
 rust-version = "1.91.0"

 [workspace.dependencies]
-lance = { "version" = "=11.0.0-beta.13", default-features = false, "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-core = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-datagen = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-file = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-io = { "version" = "=11.0.0-beta.13", default-features = false, "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-index = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-linalg = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace-impls = { "version" = "=11.0.0-beta.13", default-features = false, "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-table = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-testing = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-datafusion = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-encoding = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
-lance-arrow = { "version" = "=11.0.0-beta.13", "tag" = "v11.0.0-beta.13", "git" = "https://github.com/lance-format/lance.git" }
+lance = { "version" = "=11.0.0-beta.16", default-features = false, "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-core = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-datagen = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-file = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-io = { "version" = "=11.0.0-beta.16", default-features = false, "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-index = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-linalg = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace-impls = { "version" = "=11.0.0-beta.16", default-features = false, "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-table = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-testing = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-datafusion = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-encoding = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance-arrow = { "version" = "=11.0.0-beta.16", "tag" = "v11.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lancedb = { path = "rust/lancedb", default-features = false }
 ahash = "0.8"
 # Note that this one does not include pyarrow
 arrow = { version = "58.0.0", optional = false }
@@ -39,6 +40,7 @@ arrow-schema = "58.0.0"
 arrow-select = "58.0.0"
 arrow-cast = "58.0.0"
 async-trait = "0"
+bytes = "1"
 datafusion = { version = "54.0.0", default-features = false }
 datafusion-catalog = "54.0.0"
 datafusion-common = { version = "54.0.0", default-features = false }
@@ -65,7 +67,12 @@ url = "2"
 num-traits = "0.2"
 regex = "1.10"
 semver = "1.0.25"
-chrono = "0.4"
+serde = "1"
+serde_json = "1"
+tempfile = "3.5.0"
+tokio = { version = "1.23", features = ["rt-multi-thread", "sync"] }
+uuid = { version = "1.7.0", features = ["v4"] }
+chrono = { version = "0.4", default-features = false, features = ["clock"] }

 [profile.ci]
 debug = "line-tables-only"
@@ -2,6 +2,7 @@
 Check whether there are any breaking changes in the PRs between the base and head commits.
 If there are, assert that we have incremented the minor version.
 """
+
 import argparse
 import os
 from packaging.version import parse
@@ -27,7 +28,7 @@ if __name__ == "__main__":
    else:
        print("No breaking changes found.")
        exit(0)
-    
+
    last_stable_version = parse(args.last_stable_version)
    current_version = parse(args.current_version)
    if current_version.minor <= last_stable_version.minor:
@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 """Determine whether a newer Lance tag exists and expose results for CI."""
+
 from __future__ import annotations

 import argparse
@@ -36,8 +37,16 @@ class SemVer:
    prerelease: Tuple[Union[int, str], ...]

    def __lt__(self, other: "SemVer") -> bool:  # pragma: no cover - simple comparison
-        if (self.major, self.minor, self.patch) != (other.major, other.minor, other.patch):
-            return (self.major, self.minor, self.patch) < (other.major, other.minor, other.patch)
+        if (self.major, self.minor, self.patch) != (
+            other.major,
+            other.minor,
+            other.patch,
+        ):
+            return (self.major, self.minor, self.patch) < (
+                other.major,
+                other.minor,
+                other.patch,
+            )
        if self.prerelease == other.prerelease:
            return False
        if not self.prerelease:
@@ -142,7 +151,9 @@ def read_current_version(repo_root: Path) -> str:
        deps = data["workspace"]["dependencies"]
        entry = deps["lance"]
    except KeyError as exc:  # pragma: no cover - configuration guard
-        raise RuntimeError("Failed to locate workspace.dependencies.lance in Cargo.toml") from exc
+        raise RuntimeError(
+            "Failed to locate workspace.dependencies.lance in Cargo.toml"
+        ) from exc

    if isinstance(entry, str):
        raw_version = entry
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright The LanceDB Authors
 """A zero-dependency mock OpenAI embeddings API endpoint for testing purposes."""
+
 import argparse
 import json
 import http.server
@@ -22,11 +23,13 @@ class MockOpenAIRequestHandler(http.server.BaseHTTPRequestHandler):

        data = []
        for i in range(num_inputs):
-            data.append({
-                "object": "embedding",
-                "embedding": [0.1] * 1536,
-                "index": i,
-            })
+            data.append(
+                {
+                    "object": "embedding",
+                    "embedding": [0.1] * 1536,
+                    "index": i,
+                }
+            )

        response = {
            "object": "list",
@@ -35,7 +38,7 @@ class MockOpenAIRequestHandler(http.server.BaseHTTPRequestHandler):
            "usage": {
                "prompt_tokens": 0,
                "total_tokens": 0,
-            }
+            },
        }

        self.send_response(200)
@@ -7,6 +7,7 @@ from packaging.version import parse, InvalidVersion

 if __name__ == "__main__":
    import argparse
+
    parser = argparse.ArgumentParser()
    parser.add_argument("prefix", default="v")
    args = parser.parse_args()
@@ -22,7 +22,7 @@ def run_command(command: str) -> str:
 def get_latest_stable_version() -> str:
    version_line = run_command("cargo info lance | grep '^version:'")
    # Example output: "version: 0.35.0 (latest 0.37.0)"
-    match = re.search(r'\(latest ([0-9.]+)\)', version_line)
+    match = re.search(r"\(latest ([0-9.]+)\)", version_line)
    if match:
        return match.group(1)
    # Fallback: use the first version after 'version:'
@@ -69,7 +69,7 @@ def extract_default_features(line: str) -> bool:
    """
    import re

-    match = re.search(r'default-features\s*=\s*false', line)
+    match = re.search(r"default-features\s*=\s*false", line)
    return match is not None


@@ -104,7 +104,7 @@ def dict_to_toml_line(package_name: str, config: dict) -> str:
            # This shouldn't happen with our current usage
            parts.append(f'"{key}" = {json.dumps(value)}')

-    return f'{package_name} = {{ {", ".join(parts)} }}\n'
+    return f"{package_name} = {{ {', '.join(parts)} }}\n"


 def update_cargo_toml(line_updater):
@@ -119,7 +119,7 @@ def update_cargo_toml(line_updater):
    lance_line = ""
    is_parsing_lance_line = False
    for line in lines:
-        if line.startswith("lance"):
+        if re.match(r"^lance(?:\s|[-_])", line):
            # Check if this is a single-line or multi-line entry
            # Single-line entries either:
            # 1. End with } (complete inline table)
@@ -0,0 +1,185 @@
+import os
+import stat
+import subprocess
+import sys
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SCRIPT = REPO_ROOT / "ci" / "set_lance_version.py"
+LANCE_GIT_URL = "https://github.com/lance-format/lance.git"
+
+CARGO_TOML = """\
+[workspace.dependencies]
+lance = { "version" = "=1.0.0", default-features = false, "features" = ["dynamodb"] }
+lance-core = "1.0.0"
+lance_datafusion = {
+    "version" = "=1.0.0",
+    "features" = ["substrait"]
+}
+lancedb = { path = "rust/lancedb", default-features = false }
+lancedb-common = { path = "rust/lancedb-common" }
+lancewood = "1.0.0"
+my-lance = "1.0.0"
+"""
+
+UNTOUCHED_DEPENDENCIES = """\
+lancedb = { path = "rust/lancedb", default-features = false }
+lancedb-common = { path = "rust/lancedb-common" }
+lancewood = "1.0.0"
+my-lance = "1.0.0"
+"""
+
+
+class SetLanceVersionTest(unittest.TestCase):
+    def test_supported_update_modes_only_rewrite_lance_dependencies(self):
+        cases = {
+            "stable": (
+                """\
+lance = { "version" = "=9.9.9", default-features = false, "features" = ["dynamodb"] }
+lance-core = "=9.9.9"
+lance_datafusion = { "version" = "=9.9.9", "features" = ["substrait"] }
+""",
+                ["cargo info lance", "cargo metadata"],
+            ),
+            "preview": (
+                f"""\
+lance = {{ "version" = "=10.0.0-beta.3", default-features = false, "features" = ["dynamodb"], "tag" = "v10.0.0-beta.3", "git" = "{LANCE_GIT_URL}" }}
+lance-core = {{ "version" = "=10.0.0-beta.3", "tag" = "v10.0.0-beta.3", "git" = "{LANCE_GIT_URL}" }}
+lance_datafusion = {{ "version" = "=10.0.0-beta.3", "features" = ["substrait"], "tag" = "v10.0.0-beta.3", "git" = "{LANCE_GIT_URL}" }}
+""",
+                ["git ls-remote --tags", "cargo metadata"],
+            ),
+            "local": (
+                """\
+lance = { "path" = "../lance/rust/lance", default-features = false, "features" = ["dynamodb"] }
+lance-core = { "path" = "../lance/rust/lance-core" }
+lance_datafusion = { "path" = "../lance/rust/lance_datafusion", "features" = ["substrait"] }
+""",
+                ["cargo metadata"],
+            ),
+            "v8.1.2": (
+                """\
+lance = { "version" = "=8.1.2", default-features = false, "features" = ["dynamodb"] }
+lance-core = "=8.1.2"
+lance_datafusion = { "version" = "=8.1.2", "features" = ["substrait"] }
+""",
+                ["cargo metadata"],
+            ),
+            "v8.2.0-beta.4": (
+                f"""\
+lance = {{ "version" = "=8.2.0-beta.4", default-features = false, "features" = ["dynamodb"], "tag" = "v8.2.0-beta.4", "git" = "{LANCE_GIT_URL}" }}
+lance-core = {{ "version" = "=8.2.0-beta.4", "tag" = "v8.2.0-beta.4", "git" = "{LANCE_GIT_URL}" }}
+lance_datafusion = {{ "version" = "=8.2.0-beta.4", "features" = ["substrait"], "tag" = "v8.2.0-beta.4", "git" = "{LANCE_GIT_URL}" }}
+""",
+                ["cargo metadata"],
+            ),
+        }
+
+        for version, (updated_dependencies, expected_commands) in cases.items():
+            with self.subTest(version=version), tempfile.TemporaryDirectory() as tmp:
+                workdir = Path(tmp)
+                (workdir / "Cargo.toml").write_text(CARGO_TOML)
+                command_log = workdir / "commands.log"
+                fake_bin = workdir / "bin"
+                fake_bin.mkdir()
+                self._write_fake_executables(fake_bin)
+                self._write_fake_python_dependencies(workdir)
+
+                env = os.environ.copy()
+                env["PATH"] = os.pathsep.join([str(fake_bin), env["PATH"]])
+                env["FAKE_COMMAND_LOG"] = str(command_log)
+                env["PYTHONPATH"] = os.pathsep.join(
+                    filter(None, [str(workdir), env.get("PYTHONPATH")])
+                )
+                result = subprocess.run(
+                    [sys.executable, str(SCRIPT), version],
+                    cwd=workdir,
+                    env=env,
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                )
+
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertEqual(
+                    (workdir / "Cargo.toml").read_text(),
+                    "[workspace.dependencies]\n"
+                    + updated_dependencies
+                    + UNTOUCHED_DEPENDENCIES,
+                )
+                commands = command_log.read_text().splitlines()
+                for command in expected_commands:
+                    self.assertTrue(
+                        any(line.startswith(command) for line in commands),
+                        f"{command!r} not found in {commands!r}",
+                    )
+
+    def _write_fake_executables(self, fake_bin: Path) -> None:
+        cargo = fake_bin / "cargo"
+        cargo.write_text(
+            textwrap.dedent(
+                """\
+                #!/bin/sh
+                printf 'cargo %s\\n' "$*" >> "$FAKE_COMMAND_LOG"
+                case "$1" in
+                  info)
+                    printf '%s\\n' 'version: 8.8.8 (latest 9.9.9)'
+                    ;;
+                  metadata)
+                    ;;
+                  *)
+                    exit 2
+                    ;;
+                esac
+                """
+            )
+        )
+        cargo.chmod(cargo.stat().st_mode | stat.S_IXUSR)
+
+        git = fake_bin / "git"
+        git.write_text(
+            textwrap.dedent(
+                """\
+                #!/bin/sh
+                printf 'git %s\\n' "$*" >> "$FAKE_COMMAND_LOG"
+                if [ "$1" != "ls-remote" ]; then
+                  exit 2
+                fi
+                printf '%s\\n' \\
+                  '111111 refs/tags/v9.9.9' \\
+                  '222222 refs/tags/v10.0.0-beta.1' \\
+                  '333333 refs/tags/v10.0.0-beta.3'
+                """
+            )
+        )
+        git.chmod(git.stat().st_mode | stat.S_IXUSR)
+
+    def _write_fake_python_dependencies(self, workdir: Path) -> None:
+        packaging = workdir / "packaging"
+        packaging.mkdir()
+        (packaging / "__init__.py").write_text("")
+        (packaging / "version.py").write_text(
+            textwrap.dedent(
+                """\
+                class Version:
+                    def __init__(self, value):
+                        release, _, prerelease = value.partition("-beta.")
+                        self._key = (
+                            tuple(int(part) for part in release.split(".")),
+                            not prerelease,
+                            int(prerelease or 0),
+                        )
+
+                    def __lt__(self, other):
+                        return self._key < other._key
+                """
+            )
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -12,7 +12,7 @@ with open("Cargo.toml", "rb") as f:
            elif isinstance(dep, dict):
                # Version doesn't have the beta tag in it, so we instead look
                # at the git tag.
-                version = dep.get('tag', dep.get('version'))
+                version = dep.get("tag", dep.get("version"))
            else:
                raise ValueError("Unexpected type for dependency: " + str(dep))

@@ -108,6 +108,12 @@ ignore = [
    # compact_str/smol_str, so clearing this requires polars to migrate.
    # https://rustsec.org/advisories/RUSTSEC-2026-0249
    { id = "RUSTSEC-2026-0249", reason = "smartstring unmaintained via polars; no fixed upstream release" },
+
+    # h2 0.3: empty DATA frames can be queued without limit. The patched
+    # h2 0.4 line is locked to 0.4.16, but no patched 0.3 release exists.
+    # The old copy is pulled in by aws-smithy's legacy hyper 0.14 client.
+    # https://rustsec.org/advisories/RUSTSEC-2026-0258
+    { id = "RUSTSEC-2026-0258", reason = "h2 0.3 via legacy aws-smithy/hyper 0.14; no patched 0.3 release" },
 ]

 # ---------------------------------------------------------------------------
@@ -171,6 +177,11 @@ multiple-versions = "warn"
 # Wildcard version requirements (`foo = "*"`) are a footgun — they let any
 # future release in without review. Ban them outright.
 wildcards = "deny"
+# Lint every dependency declared by a workspace member against the shared
+# `[workspace.dependencies]` table: any crate used by more than one member must
+# go through `workspace = true`, and entries nothing uses are an error. This
+# keeps versions from drifting between the core crate and the bindings.
+workspace-dependencies = { duplicates = "deny", unused = "deny" }
 # Internal workspace crates reference each other via `path = "..."`, which
 # cargo-deny sees as a wildcard version. That's fine for private workspace
 # members (not published to crates.io), so allow it specifically for paths.
@@ -5,5 +5,5 @@ mkdocs-autorefs>=0.5,<=1.0
 mkdocstrings[python]>=0.24,<1.0
 griffe>=0.40,<1.0
 mkdocs-render-swagger-plugin>=0.1.0
-pydantic>=2.0,<3.0
-mkdocs-redirects>=1.2.0
+pydantic>=2.7.4,<3
+mkdocs-redirects>=1.2.0
@@ -14,7 +14,7 @@ Add the following dependency to your `pom.xml`:
 <dependency>
    <groupId>com.lancedb</groupId>
    <artifactId>lancedb-core</artifactId>
-    <version>0.38.0-beta.0</version>
+    <version>0.38.0-beta.3</version>
 </dependency>
 ```

@@ -55,6 +55,38 @@ LanceNamespace namespaceClient = LanceDbNamespaceClientBuilder.newBuilder()
 | `region(String)` | AWS region (default: "us-east-1") | No |
 | `config(String, String)` | Additional configuration parameters | No |

+### Opening a Table with Vended Credentials
+
+When the catalog vends temporary object store credentials, open the table through the
+namespace client. The Lance dataset builder fetches the table location and storage options
+from the catalog and refreshes the credentials when they expire.
+
+```java
+import com.lancedb.LanceDbNamespaceClientBuilder;
+import org.lance.Dataset;
+import org.lance.namespace.LanceNamespace;
+
+import java.util.Arrays;
+
+LanceNamespace namespaceClient = LanceDbNamespaceClientBuilder.newBuilder()
+    .apiKey(System.getenv("LANCEDB_API_KEY"))
+    .database(System.getenv("LANCEDB_DATABASE"))
+    // Set the endpoint for a LanceDB Enterprise deployment.
+    // .endpoint("https://your-enterprise-endpoint")
+    .build();
+
+try (Dataset dataset = Dataset.open()
+        .namespaceClient(namespaceClient)
+        .tableId(Arrays.asList("my_namespace", "my_table"))
+        .build()) {
+    System.out.println("Rows: " + dataset.countRows());
+}
+```
+
+Do not call `describeTable()` and then open the returned location with `Dataset.open(uri)`.
+Opening through `namespaceClient()` is what applies the vended storage options and enables
+automatic credential refresh. No object store credentials need to be passed by the application.
+
 ## Metadata Operations

 ### Creating a Namespace Path
@@ -213,6 +213,39 @@ version of the table.

 ***

+### checkpointLsm()
+
+```ts
+abstract checkpointLsm(): Promise<void>
+```
+
+Converge this table's LSM write path into its base table.
+
+Seals once, then triggers compaction and polls until the L0 that existed
+at the start is gone. The target set is fixed at the start, so
+generations created *during* the checkpoint are ignored — that is what
+lets it terminate under write load, and what makes it best-effort: it
+converges the fresh tier as of some instant. Idempotent, abandonable at
+any point, and safe to run on a cadence.
+
+There is no liveness bound — the compactor pool is shared across tables,
+so a checkpoint queued behind unrelated work looks exactly like one that
+is merging. The caller owns the deadline.
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+#### Example
+
+```ts
+const before = await table.getLsmStats();
+await table.checkpointLsm();
+const after = await table.getLsmStats();
+```
+
+***
+
 ### close()

 ```ts
@@ -250,6 +283,24 @@ It is a no-op when no writers are cached.

 ***

+### compactLsm()
+
+```ts
+abstract compactLsm(): Promise<void>
+```
+
+Trigger a background L0 → base compaction pass per bucket.
+
+Returns once the passes are *dispatched*, not once they finish — watch
+[Table#getLsmStats](Table.md#getlsmstats) for progress, or use
+[Table#checkpointLsm](Table.md#checkpointlsm) to wait for convergence.
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+***
+
 ### countRows()

 ```ts
@@ -448,6 +499,48 @@ Drop an index from the table.

 ***

+### flushLsm()
+
+```ts
+abstract flushLsm(): Promise<void>
+```
+
+Seal every bucket's active memtable into a new L0 generation.
+
+Returns once the seal is committed. Sealing an empty memtable is a no-op,
+so this is safe to call repeatedly.
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+***
+
+### getLsmStats()
+
+```ts
+abstract getLsmStats(includeGenerationRows?): Promise<undefined | LsmStats>
+```
+
+Read live per-bucket LSM state.
+
+Answers "how far behind is my fresh tier", "which bucket is hot", and
+"why is my fresh-tier vector search brute-force". Mutates no table state.
+
+Resolves to `undefined` only when the LSM write path is not enabled.
+
+#### Parameters
+
+* **includeGenerationRows?**: `boolean`
+    Also count rows per L0 generation.
+    Off by default because each count opens an uncached Lance dataset.
+
+#### Returns
+
+`Promise`&lt;`undefined` \| [`LsmStats`](../interfaces/LsmStats.md)&gt;
+
+***
+
 ### getLsmWriteSpec()

 ```ts
@@ -58,6 +58,7 @@
 - [BranchDiff](interfaces/BranchDiff.md)
 - [BranchIndexSummary](interfaces/BranchIndexSummary.md)
 - [BranchRowCountSummary](interfaces/BranchRowCountSummary.md)
+- [BucketStats](interfaces/BucketStats.md)
 - [ClientConfig](interfaces/ClientConfig.md)
 - [ColumnAlteration](interfaces/ColumnAlteration.md)
 - [ColumnOrdering](interfaces/ColumnOrdering.md)
@@ -81,6 +82,7 @@
 - [FtsToken](interfaces/FtsToken.md)
 - [FullTextQuery](interfaces/FullTextQuery.md)
 - [FullTextSearchOptions](interfaces/FullTextSearchOptions.md)
+- [GenerationStats](interfaces/GenerationStats.md)
 - [HnswPqOptions](interfaces/HnswPqOptions.md)
 - [HnswSqOptions](interfaces/HnswSqOptions.md)
 - [IndexConfig](interfaces/IndexConfig.md)
@@ -94,7 +96,9 @@
 - [JobInfo](interfaces/JobInfo.md)
 - [ListNamespacesOptions](interfaces/ListNamespacesOptions.md)
 - [ListNamespacesResponse](interfaces/ListNamespacesResponse.md)
+- [LsmStats](interfaces/LsmStats.md)
 - [LsmWriteSpec](interfaces/LsmWriteSpec.md)
+- [MemtableStats](interfaces/MemtableStats.md)
 - [MergeBlocker](interfaces/MergeBlocker.md)
 - [MergeBranchResult](interfaces/MergeBranchResult.md)
 - [MergePreview](interfaces/MergePreview.md)
@@ -0,0 +1,116 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / BucketStats
+
+# Interface: BucketStats
+
+Live state of one bucket. A table is N buckets on one node; flattening to a
+single number hides the one hot bucket that is usually why someone opened
+this endpoint.
+
+## Properties
+
+### compacting
+
+```ts
+compacting: boolean;
+```
+
+Whether a pass owns this bucket's compaction latch right now. Says *a*
+driver is running, not *whose*, and the latch is held from dispatch —
+including while the pass queues for a pod-wide compactor permit. Read it
+as "do not pile on", never as "mine is progressing".
+
+***
+
+### currentGeneration
+
+```ts
+currentGeneration: number;
+```
+
+The generation the active memtable will become.
+
+***
+
+### generations
+
+```ts
+generations: GenerationStats[];
+```
+
+Flushed L0 generations not yet merged into the base table.
+
+***
+
+### manifestVersion
+
+```ts
+manifestVersion: number;
+```
+
+Version of the shard manifest these numbers were read from.
+
+***
+
+### memtables?
+
+```ts
+optional memtables: MemtableStats[];
+```
+
+Oldest first, active last. Absent for a `"Sealed"` bucket, whose
+in-memory state is torn down.
+
+***
+
+### replayAfterWalEntryPosition
+
+```ts
+replayAfterWalEntryPosition: number;
+```
+
+WAL position replay resumes from.
+
+***
+
+### shardId
+
+```ts
+shardId: string;
+```
+
+The shard this bucket writes.
+
+***
+
+### status
+
+```ts
+status: string;
+```
+
+`"Active"` or `"Sealed"` (drop-table 2PC in flight).
+
+***
+
+### walEntryPositionLastSeen
+
+```ts
+walEntryPositionLastSeen: number;
+```
+
+Highest WAL position the writer has seen. The difference against
+`replayAfterWalEntryPosition` is the WAL lag.
+
+***
+
+### writerEpoch
+
+```ts
+writerEpoch: number;
+```
+
+Epoch of the writer that currently owns the shard.
@@ -0,0 +1,40 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / GenerationStats
+
+# Interface: GenerationStats
+
+One flushed L0 generation.
+
+## Properties
+
+### bytes
+
+```ts
+bytes: number;
+```
+
+On-disk size of the generation.
+
+***
+
+### generation
+
+```ts
+generation: number;
+```
+
+The generation number. Increases as memtables are sealed into L0.
+
+***
+
+### rows?
+
+```ts
+optional rows: number;
+```
+
+Present only when `includeGenerationRows` was requested. Off by default
+because each count opens an uncached Lance dataset.
@@ -0,0 +1,22 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / LsmStats
+
+# Interface: LsmStats
+
+Live per-bucket LSM state, as returned by `Table#getLsmStats`.
+
+Nothing here is derived: sums and differences (total L0 bytes, WAL lag) are
+the caller's to compute.
+
+## Properties
+
+### buckets
+
+```ts
+buckets: BucketStats[];
+```
+
+One entry per bucket backing this table.
@@ -0,0 +1,60 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / MemtableStats
+
+# Interface: MemtableStats
+
+One in-memory memtable.
+
+## Properties
+
+### batches
+
+```ts
+batches: number;
+```
+
+Record batches currently buffered.
+
+***
+
+### bytes
+
+```ts
+bytes: number;
+```
+
+Estimated in-memory size.
+
+***
+
+### generation
+
+```ts
+generation: number;
+```
+
+The generation this memtable will become once sealed.
+
+***
+
+### indexes
+
+```ts
+indexes: string[];
+```
+
+Names of the indexes this memtable carries. An absent name is the whole
+answer to "why is my fresh-tier search on that column brute-force".
+
+***
+
+### rows
+
+```ts
+rows: number;
+```
+
+Rows currently buffered.
@@ -52,6 +52,56 @@ listing a storage directory.

 ::: lancedb.table.Branches

+::: lancedb.LsmWriteSpec
+
+## Functions and Jobs
+
+::: lancedb.functions.FunctionArtifact
+
+::: lancedb.functions.FunctionParameter
+
+::: lancedb.functions.FunctionResultField
+
+::: lancedb.functions.FunctionOutput
+
+::: lancedb.functions.FunctionSignature
+
+::: lancedb.functions.PythonEnvironmentSpec
+
+::: lancedb.functions.udf
+
+::: lancedb.functions.UdfDefinition
+
+::: lancedb.functions.FunctionRegistrationRequest
+
+::: lancedb.functions.FunctionArtifactRequest
+
+::: lancedb.functions.FunctionArtifactContent
+
+::: lancedb.functions.PythonAdapterSpec
+
+::: lancedb.functions.FunctionVersion
+
+::: lancedb.functions.PythonRuntimeSpec
+
+::: lancedb.functions.FunctionVersionRef
+
+::: lancedb.functions.ApplicationInput
+
+::: lancedb.functions.FunctionApplication
+
+::: lancedb.functions.InputBinding
+
+::: lancedb.functions.OutputMapping
+
+::: lancedb.functions.FunctionBinding
+
+::: lancedb.functions.RefreshColumnResult
+
+::: lancedb.job.Job
+
+::: lancedb.job.AsyncJob
+
 ## Expressions

 Type-safe expression builder for filters and projections. Use these instead
@@ -151,8 +201,9 @@ The same option is available on `lancedb.tokenize(...)` and the deprecated
 ```python
 import lancedb

-tokens = list(lancedb.tokenize("acme makes searchable data",
-                               custom_stop_words=["acme"]))
+tokens = list(
+    lancedb.tokenize("acme makes searchable data", custom_stop_words=["acme"])
+)
 ```

 ::: lancedb.tokenize
@@ -29,6 +29,48 @@ LanceNamespace namespaceClient = LanceDbNamespaceClientBuilder.newBuilder()
    .build();
 ```

+## MemWAL LSM write path
+
+Most table operations reach LanceDB through the `LanceNamespace` above, which is
+generated from the Lance Namespace specification. The MemWAL LSM routes are not part
+of that specification, so they are issued through a separate client:
+
+```java
+import com.lancedb.LanceDbRestClient;
+import com.lancedb.LanceDbTableLsm;
+import com.lancedb.LsmWriteSpec;
+
+LanceDbRestClient client = LanceDbNamespaceClientBuilder.newBuilder()
+    .apiKey("your_lancedb_cloud_api_key")
+    .database("your_database_name")
+    .buildRestClient();
+
+LanceDbTableLsm lsm = new LanceDbTableLsm(client, "my_table");
+
+// Route future merge_insert upserts through the MemWAL, hash-bucketed by `id`.
+lsm.setLsmWriteSpec(LsmWriteSpec.bucket("id", 16));
+
+// ... merge_insert traffic ...
+
+// Converge the fresh tier into the base table.
+lsm.checkpointLsm();
+
+// Inspect live per-bucket state.
+lsm.getLsmStats().ifPresent(stats -> stats.buckets().forEach(bucket ->
+    System.out.println(bucket.shardId() + ": " + bucket.generations().size() + " L0 generations")));
+
+client.close();
+```
+
+`maintainedIndexes` is tri-state, and the null default is the opposite of what a Java
+reader usually expects:
+
+| Value | Meaning |
+| --- | --- |
+| unset (null) | Maintain **every** index the MemWAL can, resolved on install |
+| `Collections.emptyList()` | Maintain **none** |
+| `Arrays.asList("id_idx")` | Maintain exactly those |
+
 ## Development

 Build:
@@ -8,7 +8,7 @@
    <parent>
      <groupId>com.lancedb</groupId>
      <artifactId>lancedb-parent</artifactId>
-      <version>0.38.0-beta.0</version>
+      <version>0.38.0-beta.3</version>
      <relativePath>../pom.xml</relativePath>
    </parent>

@@ -33,6 +33,20 @@
            <artifactId>arrow-memory-netty</artifactId>
        </dependency>

+        <!-- Transport for the LanceDB routes outside the Lance Namespace spec.
+             Versions match what lance-namespace-apache-client resolves to. -->
+        <dependency>
+            <groupId>org.apache.httpcomponents.client5</groupId>
+            <artifactId>httpclient5</artifactId>
+            <version>5.2.1</version>
+        </dependency>
+
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>2.17.1</version>
+        </dependency>
+
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
@@ -0,0 +1,194 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+import java.util.OptionalLong;
+
+/**
+ * Live state of one bucket. A table is N buckets on one node; flattening to a single number hides
+ * the one hot bucket that is usually why someone opened this endpoint.
+ */
+public class BucketStats {
+  private static final String CONTEXT = "bucket stats";
+
+  private final String shardId;
+  private final String status;
+  private final long writerEpoch;
+  private final long manifestVersion;
+  private final long currentGeneration;
+  private final long replayAfterWalEntryPosition;
+  private final long walEntryPositionLastSeen;
+  private final List<GenerationStats> generations;
+  private final boolean compacting;
+  private final List<MemtableStats> memtables;
+
+  BucketStats(
+      String shardId,
+      String status,
+      long writerEpoch,
+      long manifestVersion,
+      long currentGeneration,
+      long replayAfterWalEntryPosition,
+      long walEntryPositionLastSeen,
+      List<GenerationStats> generations,
+      boolean compacting,
+      List<MemtableStats> memtables) {
+    this.shardId = shardId;
+    this.status = status;
+    this.writerEpoch = writerEpoch;
+    this.manifestVersion = manifestVersion;
+    this.currentGeneration = currentGeneration;
+    this.replayAfterWalEntryPosition = replayAfterWalEntryPosition;
+    this.walEntryPositionLastSeen = walEntryPositionLastSeen;
+    this.generations = Collections.unmodifiableList(generations);
+    this.compacting = compacting;
+    this.memtables = memtables == null ? null : Collections.unmodifiableList(memtables);
+  }
+
+  /** The shard this bucket writes. */
+  public String shardId() {
+    return shardId;
+  }
+
+  /** {@code "Active"} or {@code "Sealed"} (drop-table 2PC in flight). */
+  public String status() {
+    return status;
+  }
+
+  /** Epoch of the writer that currently owns the shard. */
+  public long writerEpoch() {
+    return writerEpoch;
+  }
+
+  /** Version of the shard manifest these numbers were read from. */
+  public long manifestVersion() {
+    return manifestVersion;
+  }
+
+  /** The generation the active memtable will become. */
+  public long currentGeneration() {
+    return currentGeneration;
+  }
+
+  /** WAL position replay resumes from. */
+  public long replayAfterWalEntryPosition() {
+    return replayAfterWalEntryPosition;
+  }
+
+  /**
+   * Highest WAL position the writer has seen. The difference against {@link
+   * #replayAfterWalEntryPosition()} is the WAL lag.
+   */
+  public long walEntryPositionLastSeen() {
+    return walEntryPositionLastSeen;
+  }
+
+  /** Flushed L0 generations not yet merged into the base table. */
+  public List<GenerationStats> generations() {
+    return generations;
+  }
+
+  /**
+   * Whether a pass owns this bucket's compaction latch right now. Says <em>a</em> driver is
+   * running, not <em>whose</em>, and the latch is held from dispatch — including while the pass
+   * queues for a pod-wide compactor permit. Read it as "do not pile on", never as "mine is
+   * progressing".
+   */
+  public boolean compacting() {
+    return compacting;
+  }
+
+  /** Oldest first, active last. Empty for a {@code "Sealed"} bucket, whose state is torn down. */
+  public Optional<List<MemtableStats>> memtables() {
+    return Optional.ofNullable(memtables);
+  }
+
+  /** The newest flushed generation, or empty when L0 is empty. */
+  OptionalLong newestGeneration() {
+    OptionalLong newest = OptionalLong.empty();
+    for (GenerationStats generation : generations) {
+      if (!newest.isPresent() || generation.generation() > newest.getAsLong()) {
+        newest = OptionalLong.of(generation.generation());
+      }
+    }
+    return newest;
+  }
+
+  /**
+   * How many generations at or below {@code target} are still in L0.
+   *
+   * <p>A count, not a boolean: one pass drains a bounded prefix rather than the whole target set,
+   * so a boolean would read as "no progress" for every pass but the last. Compaction drains
+   * oldest-first, so this decreases monotonically.
+   */
+  long outstandingGenerations(long target) {
+    long count = 0;
+    for (GenerationStats generation : generations) {
+      if (generation.generation() <= target) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  static BucketStats fromJson(JsonNode node) {
+    JsonFields.requiredObject(node, CONTEXT);
+    List<GenerationStats> generations = new ArrayList<GenerationStats>();
+    for (JsonNode generation : JsonFields.requiredArray(node, "generations", CONTEXT)) {
+      generations.add(GenerationStats.fromJson(generation));
+    }
+
+    JsonNode memtablesNode = JsonFields.optionalArray(node, "memtables", CONTEXT);
+    List<MemtableStats> memtables = null;
+    if (memtablesNode != null) {
+      memtables = new ArrayList<MemtableStats>();
+      for (JsonNode memtable : memtablesNode) {
+        memtables.add(MemtableStats.fromJson(memtable));
+      }
+    }
+
+    return new BucketStats(
+        JsonFields.requiredText(node, "shard_id", CONTEXT),
+        JsonFields.requiredText(node, "status", CONTEXT),
+        JsonFields.requiredLong(node, "writer_epoch", CONTEXT),
+        JsonFields.requiredLong(node, "manifest_version", CONTEXT),
+        JsonFields.requiredLong(node, "current_generation", CONTEXT),
+        JsonFields.requiredLong(node, "replay_after_wal_entry_position", CONTEXT),
+        JsonFields.requiredLong(node, "wal_entry_position_last_seen", CONTEXT),
+        generations,
+        JsonFields.requiredBoolean(node, "compacting", CONTEXT),
+        memtables);
+  }
+
+  @Override
+  public String toString() {
+    return "BucketStats{shardId="
+        + shardId
+        + ", status="
+        + status
+        + ", currentGeneration="
+        + currentGeneration
+        + ", generations="
+        + generations
+        + ", compacting="
+        + compacting
+        + "}";
+  }
+}
@@ -0,0 +1,64 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.OptionalLong;
+
+/** One flushed L0 generation. */
+public class GenerationStats {
+  private static final String CONTEXT = "generation stats";
+
+  private final long generation;
+  private final long bytes;
+  private final Long rows;
+
+  GenerationStats(long generation, long bytes, Long rows) {
+    this.generation = generation;
+    this.bytes = bytes;
+    this.rows = rows;
+  }
+
+  /** The generation number. Increases as memtables are sealed into L0. */
+  public long generation() {
+    return generation;
+  }
+
+  /** On-disk size of the generation. */
+  public long bytes() {
+    return bytes;
+  }
+
+  /**
+   * Rows in this generation, present only when {@code includeGenerationRows} was requested. Off by
+   * default because each count opens an uncached Lance dataset.
+   */
+  public OptionalLong rows() {
+    return rows == null ? OptionalLong.empty() : OptionalLong.of(rows);
+  }
+
+  static GenerationStats fromJson(JsonNode node) {
+    JsonFields.requiredObject(node, CONTEXT);
+    return new GenerationStats(
+        JsonFields.requiredLong(node, "generation", CONTEXT),
+        JsonFields.requiredLong(node, "bytes", CONTEXT),
+        JsonFields.optionalLong(node, "rows", CONTEXT));
+  }
+
+  @Override
+  public String toString() {
+    return "GenerationStats{generation=" + generation + ", bytes=" + bytes + ", rows=" + rows + "}";
+  }
+}
@@ -0,0 +1,109 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+/**
+ * Strict readers for decoding LanceDB JSON responses.
+ *
+ * <p>Every reader fails closed: a missing, null, or wrong-typed field throws rather than
+ * defaulting. That mirrors the serde decoding the Rust client applies to the same payloads in
+ * {@code rust/lancedb/src/table/lsm_stats.rs}, where a required field has no default and a
+ * malformed response is an error rather than a zero.
+ *
+ * <p>The alternative — Jackson's {@code path()}, which yields a missing node that reads as an empty
+ * array or a zero — is unsafe here because {@link LanceDbTableLsm#checkpointLsm()} decides
+ * convergence from these numbers. A defaulted {@code generations} array is indistinguishable from a
+ * drained one, so a malformed response would report a checkpoint that never happened.
+ */
+final class JsonFields {
+  private JsonFields() {}
+
+  /** The node itself, once confirmed to be a JSON object. */
+  static JsonNode requiredObject(JsonNode node, String context) {
+    if (node == null || !node.isObject()) {
+      throw new IllegalStateException(context + " is not a JSON object: " + node);
+    }
+    return node;
+  }
+
+  static String requiredText(JsonNode owner, String field, String context) {
+    JsonNode value = required(owner, field, context);
+    if (!value.isTextual()) {
+      throw new IllegalStateException(fieldIs(context, field, "a string", value));
+    }
+    return value.asText();
+  }
+
+  static long requiredLong(JsonNode owner, String field, String context) {
+    JsonNode value = required(owner, field, context);
+    if (!value.isIntegralNumber()) {
+      throw new IllegalStateException(fieldIs(context, field, "an integer", value));
+    }
+    return value.asLong();
+  }
+
+  static boolean requiredBoolean(JsonNode owner, String field, String context) {
+    JsonNode value = required(owner, field, context);
+    if (!value.isBoolean()) {
+      throw new IllegalStateException(fieldIs(context, field, "a boolean", value));
+    }
+    return value.asBoolean();
+  }
+
+  static JsonNode requiredArray(JsonNode owner, String field, String context) {
+    JsonNode value = required(owner, field, context);
+    if (!value.isArray()) {
+      throw new IllegalStateException(fieldIs(context, field, "an array", value));
+    }
+    return value;
+  }
+
+  /** Null when the field is absent or JSON null, mirroring a serde {@code Option}. */
+  static Long optionalLong(JsonNode owner, String field, String context) {
+    JsonNode value = owner.get(field);
+    if (value == null || value.isNull()) {
+      return null;
+    }
+    if (!value.isIntegralNumber()) {
+      throw new IllegalStateException(fieldIs(context, field, "an integer", value));
+    }
+    return value.asLong();
+  }
+
+  /** Null when the field is absent or JSON null, mirroring a serde {@code Option}. */
+  static JsonNode optionalArray(JsonNode owner, String field, String context) {
+    JsonNode value = owner.get(field);
+    if (value == null || value.isNull()) {
+      return null;
+    }
+    if (!value.isArray()) {
+      throw new IllegalStateException(fieldIs(context, field, "an array", value));
+    }
+    return value;
+  }
+
+  private static JsonNode required(JsonNode owner, String field, String context) {
+    JsonNode value = owner.get(field);
+    if (value == null || value.isNull()) {
+      throw new IllegalStateException(context + " is missing required field '" + field + "'");
+    }
+    return value;
+  }
+
+  private static String fieldIs(String context, String field, String expected, JsonNode value) {
+    return context + " field '" + field + "' is not " + expected + ": " + value;
+  }
+}
@@ -136,29 +136,48 @@ public class LanceDbNamespaceClientBuilder {
   * @throws IllegalStateException if required parameters are missing
   */
  public LanceNamespace build() {
-    // Validate required fields
+    validate();
+
+    // Build configuration map
+    Map<String, String> config = new HashMap<>(additionalConfig);
+    config.put("header.x-lancedb-database", database);
+    config.put("header.x-api-key", apiKey);
+    config.put("uri", resolveUri());
+
+    return LanceNamespace.connect("rest", config, null);
+  }
+
+  /**
+   * Build a {@link LanceDbRestClient} for the same endpoint.
+   *
+   * <p>Needed only for LanceDB routes that the Lance Namespace specification does not cover — the
+   * MemWAL LSM write path, reached through {@link LanceDbTableLsm}. Every other table operation
+   * belongs on the {@link LanceNamespace} from {@link #build()}.
+   *
+   * <p>The returned client owns an HTTP connection pool; close it when you are done with it.
+   *
+   * @return A configured LanceDbRestClient
+   * @throws IllegalStateException if required parameters are missing
+   */
+  public LanceDbRestClient buildRestClient() {
+    validate();
+    return new LanceDbRestClient(resolveUri(), apiKey, database);
+  }
+
+  private void validate() {
    if (apiKey == null) {
      throw new IllegalStateException("API key is required");
    }
    if (database == null) {
      throw new IllegalStateException("Database is required");
    }
+  }

-    // Build configuration map
-    Map<String, String> config = new HashMap<>(additionalConfig);
-    config.put("header.x-lancedb-database", database);
-    config.put("header.x-api-key", apiKey);
-
-    // Determine base URL
-    String uri;
+  /** The custom endpoint when set, else the LanceDB Cloud URL for this database and region. */
+  private String resolveUri() {
    if (endpoint.isPresent()) {
-      uri = endpoint.get();
-    } else {
-      String effectiveRegion = region.orElse(DEFAULT_REGION);
-      uri = String.format(CLOUD_URL_PATTERN, database, effectiveRegion);
+      return endpoint.get();
    }
-    config.put("uri", uri);
-
-    return LanceNamespace.connect("rest", config, null);
+    return String.format(CLOUD_URL_PATTERN, database, region.orElse(DEFAULT_REGION));
  }
 }
@@ -0,0 +1,119 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.apache.hc.client5.http.classic.methods.HttpPost;
+import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
+import org.apache.hc.client5.http.impl.classic.HttpClients;
+import org.apache.hc.core5.http.ContentType;
+import org.apache.hc.core5.http.io.entity.EntityUtils;
+import org.apache.hc.core5.http.io.entity.StringEntity;
+
+import java.io.Closeable;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+
+/**
+ * Minimal HTTP client for LanceDB Cloud and Enterprise routes that the Lance Namespace
+ * specification does not cover.
+ *
+ * <p>Most table operations reach LanceDB through {@link org.lance.namespace.LanceNamespace}, which
+ * is generated from the namespace spec. A handful of routes — the MemWAL LSM write path in
+ * particular — are served by the same endpoint but are not part of that spec, so they are issued
+ * directly here. See {@link LanceDbTableLsm}.
+ *
+ * <p>Obtain one from {@link LanceDbNamespaceClientBuilder#buildRestClient()}.
+ */
+public class LanceDbRestClient implements Closeable {
+  private static final ObjectMapper MAPPER = new ObjectMapper();
+
+  private final String baseUri;
+  private final String apiKey;
+  private final String database;
+  private final CloseableHttpClient http;
+
+  LanceDbRestClient(String baseUri, String apiKey, String database) {
+    this.baseUri = baseUri.endsWith("/") ? baseUri.substring(0, baseUri.length() - 1) : baseUri;
+    this.apiKey = apiKey;
+    this.database = database;
+    // Automatic retries off, deliberately. The default strategy retries 429 and 503 —
+    // exactly the two statuses LanceDbTableLsm.checkpointLsm() acts on — which would
+    // silently double its explicit retry budget and would also retry compact_lsm in
+    // place, where the loop is designed to fall through to a fresh stats poll instead.
+    // The checkpoint loop owns the 421/429/503 transitions; the transport must not.
+    this.http = HttpClients.custom().disableAutomaticRetries().build();
+  }
+
+  /**
+   * POST {@code path}, sending {@code body} as JSON when it is non-null.
+   *
+   * @param path Absolute request path, beginning with {@code /}.
+   * @param body Object to serialize as the request body, or null to send no body.
+   * @return The parsed response body, or null when the response carried no content.
+   * @throws HttpException if the server returned a non-2xx status.
+   */
+  public JsonNode post(String path, Object body) {
+    HttpPost request = new HttpPost(baseUri + path);
+    request.setHeader("x-api-key", apiKey);
+    request.setHeader("x-lancedb-database", database);
+    try {
+      if (body != null) {
+        request.setEntity(
+            new StringEntity(MAPPER.writeValueAsString(body), ContentType.APPLICATION_JSON));
+      }
+      return http.execute(
+          request,
+          response -> {
+            String text =
+                response.getEntity() == null ? "" : EntityUtils.toString(response.getEntity());
+            int status = response.getCode();
+            if (status < 200 || status >= 300) {
+              throw new HttpException(status, "LanceDB request to " + path + " failed: " + text);
+            }
+            return text.isEmpty() ? null : MAPPER.readTree(text);
+          });
+    } catch (IOException e) {
+      throw new UncheckedIOException("LanceDB request to " + path + " failed", e);
+    }
+  }
+
+  @Override
+  public void close() throws IOException {
+    http.close();
+  }
+
+  /**
+   * A non-2xx response.
+   *
+   * <p>The status is exposed because callers act on it: {@link LanceDbTableLsm#checkpointLsm()}
+   * treats 429 and 503 as retryable and 421 as a lost node claim.
+   */
+  public static class HttpException extends RuntimeException {
+    private static final long serialVersionUID = 1L;
+
+    private final int statusCode;
+
+    public HttpException(int statusCode, String message) {
+      super(message);
+      this.statusCode = statusCode;
+    }
+
+    /** The HTTP status the failed response carried. */
+    public int statusCode() {
+      return statusCode;
+    }
+  }
+}
@@ -0,0 +1,394 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.OptionalLong;
+
+/**
+ * The MemWAL LSM write path for one LanceDB Cloud or Enterprise table.
+ *
+ * <p>Installing an {@link LsmWriteSpec} routes {@code mergeInsert} upserts through Lance's MemWAL —
+ * an LSM-style append — instead of the standard merge path. Rows land in an in-memory memtable,
+ * seal into L0 generations, and are merged into the base table by compaction.
+ *
+ * <p>These routes are not part of the Lance Namespace specification, so they are issued directly
+ * rather than through {@link org.lance.namespace.LanceNamespace}.
+ *
+ * <pre>{@code
+ * LanceDbRestClient client = LanceDbNamespaceClientBuilder.newBuilder()
+ *     .apiKey("your_lancedb_cloud_api_key")
+ *     .database("your_database_name")
+ *     .buildRestClient();
+ *
+ * LanceDbTableLsm lsm = new LanceDbTableLsm(client, "my_table");
+ * lsm.setLsmWriteSpec(LsmWriteSpec.bucket("id", 16));
+ * // ... merge_insert traffic ...
+ * lsm.checkpointLsm();
+ * }</pre>
+ */
+public class LanceDbTableLsm {
+
+  /**
+   * Interval between {@code get_lsm_stats} polls during a checkpoint. One interval is roughly one
+   * compaction pass, the granularity at which the answer can change.
+   */
+  private static final long POLL_INTERVAL_MS = 5_000L;
+
+  /**
+   * Cap on re-issues from {@code flushLsm} after a 421, so a crash-looping node cannot turn flush →
+   * compact → 421 → flush into a spin.
+   *
+   * <p>Deliberately not shared with {@link #MAX_RETRIES}: a claim that keeps evaporating is a
+   * broken node, while contention is routine and wants a real budget.
+   */
+  private static final int MAX_REISSUES = 3;
+
+  /**
+   * Retryable faults tolerated on a <em>single</em> request, reset on every success — scattered
+   * contention across a long checkpoint must not accumulate toward a cap.
+   */
+  private static final int MAX_RETRIES = 8;
+
+  private static final long RETRY_BACKOFF_BASE_MS = 100L;
+  private static final long RETRY_BACKOFF_MAX_MS = 5_000L;
+
+  private final LanceDbRestClient client;
+  private final String tableIdentifier;
+
+  /**
+   * Bind the LSM routes for one table.
+   *
+   * @param client Transport for the LanceDB endpoint.
+   * @param tableIdentifier The table's full identifier, {@code $}-delimited when it sits inside a
+   *     namespace, such as {@code analytics$events}.
+   */
+  public LanceDbTableLsm(LanceDbRestClient client, String tableIdentifier) {
+    if (client == null) {
+      throw new IllegalArgumentException("Client cannot be null");
+    }
+    if (tableIdentifier == null || tableIdentifier.trim().isEmpty()) {
+      throw new IllegalArgumentException("Table identifier cannot be null or empty");
+    }
+    this.client = client;
+    this.tableIdentifier = tableIdentifier;
+  }
+
+  /**
+   * Install an {@link LsmWriteSpec} on this table, selecting the MemWAL LSM write path for future
+   * {@code mergeInsert} calls.
+   *
+   * <p>All variants require the table to have an unenforced primary key; bucket sharding
+   * additionally requires it to be the single column being bucketed.
+   */
+  public void setLsmWriteSpec(LsmWriteSpec spec) {
+    if (spec == null) {
+      throw new IllegalArgumentException("Spec cannot be null");
+    }
+    client.post(route("set_lsm_write_spec"), spec.toRequestBody());
+  }
+
+  /**
+   * Remove the {@link LsmWriteSpec} from this table, reverting to the standard {@code mergeInsert}
+   * write path.
+   *
+   * <p>Errors if no spec is currently set.
+   */
+  public void unsetLsmWriteSpec() {
+    client.post(route("unset_lsm_write_spec"), null);
+  }
+
+  /**
+   * Read the {@link LsmWriteSpec} currently installed on this table.
+   *
+   * <p>Empty when the LSM write path is not enabled. The returned spec mirrors what was installed,
+   * except that {@link LsmWriteSpec#maintainedIndexes()} always reports the concrete list resolved
+   * when the spec was set — a null selection never round-trips.
+   */
+  public Optional<LsmWriteSpec> getLsmWriteSpec() {
+    JsonNode response = client.post(route("get_lsm_write_spec"), null);
+    if (response == null || !response.hasNonNull("lsm_write_spec")) {
+      return Optional.empty();
+    }
+    return Optional.of(LsmWriteSpec.fromJson(response.get("lsm_write_spec")));
+  }
+
+  /**
+   * Seal every bucket's active memtable into a new L0 generation.
+   *
+   * <p>Returns once the seal is committed. Sealing an empty memtable is a no-op, so this is safe to
+   * call repeatedly.
+   */
+  public void flushLsm() {
+    client.post(route("flush_lsm"), null);
+  }
+
+  /**
+   * Trigger a background L0 → base compaction pass per bucket.
+   *
+   * <p>Returns once the passes are <em>dispatched</em>, not once they finish — watch {@link
+   * #getLsmStats}, or use {@link #checkpointLsm} to wait for convergence.
+   */
+  public void compactLsm() {
+    client.post(route("compact_lsm"), null);
+  }
+
+  /**
+   * Read live per-bucket LSM state.
+   *
+   * <p>Answers "how far behind is my fresh tier", "which bucket is hot", and "why is my fresh-tier
+   * vector search brute-force". Mutates no table state.
+   *
+   * <p>Empty only when the LSM write path is not enabled — that is, when the server sends an absent
+   * or null {@code lsm_stats}. A stats object that is present is decoded strictly, and a malformed
+   * one throws rather than decoding to something empty, because {@link #checkpointLsm} reads
+   * convergence out of these numbers and cannot tell a defaulted array from a drained one.
+   *
+   * @param includeGenerationRows Also count rows per L0 generation. Off by default because each
+   *     count opens an uncached Lance dataset.
+   * @throws IllegalStateException if the response is absent or does not decode.
+   */
+  public Optional<LsmStats> getLsmStats(boolean includeGenerationRows) {
+    Map<String, Object> body = new LinkedHashMap<String, Object>();
+    body.put("include_generation_rows", includeGenerationRows);
+    JsonNode response = client.post(route("get_lsm_stats"), body);
+    if (response == null) {
+      throw new IllegalStateException("get_lsm_stats returned an empty response body");
+    }
+    JsonNode stats = response.get("lsm_stats");
+    if (stats == null || stats.isNull()) {
+      return Optional.empty();
+    }
+    return Optional.of(LsmStats.fromJson(stats));
+  }
+
+  /** Equivalent to {@code getLsmStats(false)}. */
+  public Optional<LsmStats> getLsmStats() {
+    return getLsmStats(false);
+  }
+
+  /**
+   * Converge this table's LSM write path into its base table.
+   *
+   * <p>Seals once, fixes a target watermark from the resulting L0, then triggers compaction and
+   * polls until that L0 is gone. The target set is fixed at the start, so generations created
+   * <em>during</em> the checkpoint are ignored — that is what lets it terminate under write load,
+   * and what makes it best-effort: it converges the fresh tier as of some instant. Idempotent,
+   * abandonable at any point, safe on a cadence.
+   *
+   * <p>The loop runs here, not on the server: {@link #compactLsm} dispatches a pass and returns, so
+   * nothing holds a socket and a client can vanish mid-operation with nothing to reconcile.
+   * Completion is read from generation numbers in the shard manifest — durable state, unlike a
+   * count in a compact response, which a concurrent write invalidates.
+   *
+   * <p>No liveness bound — the caller owns the deadline. The compactor pool is shared across
+   * tables, so a checkpoint queued behind unrelated work looks exactly like one that is merging.
+   */
+  public void checkpointLsm() {
+    for (int reissue = 0; reissue <= MAX_REISSUES; reissue++) {
+      // The seal turns everything written before this call into a generation, so the
+      // watermark has to be read after it. Idempotent: sealing an empty memtable is a
+      // no-op, so a re-issue does not churn empty generations.
+      if (issueVoid(this::flushLsm)) {
+        backoff(reissue);
+        continue;
+      }
+
+      Attempt<Optional<LsmStats>> stats = issue(() -> getLsmStats(false));
+      if (stats.lostClaim) {
+        backoff(reissue);
+        continue;
+      }
+      if (!stats.value.isPresent()) {
+        // Not WAL-backed; flushLsm would have errored first but for a race.
+        return;
+      }
+
+      Map<String, Long> targets = newestGenerations(stats.value.get());
+      if (targets.isEmpty()) {
+        return;
+      }
+
+      if (drainToTargets(targets)) {
+        return;
+      }
+      backoff(reissue);
+    }
+    throw new IllegalStateException(
+        "checkpointLsm: the owning node kept losing its claim; re-issued from flush the maximum "
+            + "number of times");
+  }
+
+  /**
+   * Trigger and poll until no bucket holds a generation at or below its target.
+   *
+   * @return true when the drain finished, false when the table needs re-claiming from flush.
+   */
+  private boolean drainToTargets(Map<String, Long> targets) {
+    while (true) {
+      Attempt<Optional<LsmStats>> stats = issue(() -> getLsmStats(false));
+      if (stats.lostClaim) {
+        return false;
+      }
+      if (!stats.value.isPresent()) {
+        return true;
+      }
+
+      // `compacting` is the bucket's compaction latch, held from dispatch until the pass
+      // ends — including while it waits on a pod-wide permit. So it answers one question
+      // only: do not pile on. Buckets with nothing outstanding are skipped, not counted
+      // as idle.
+      long outstanding = 0;
+      boolean allCompacting = true;
+      for (BucketStats bucket : stats.value.get().buckets()) {
+        Long target = targets.get(bucket.shardId());
+        if (target == null) {
+          continue;
+        }
+        long remaining = bucket.outstandingGenerations(target);
+        if (remaining > 0) {
+          outstanding += remaining;
+          allCompacting &= bucket.compacting();
+        }
+      }
+      if (outstanding == 0) {
+        return true;
+      }
+
+      if (!allCompacting) {
+        try {
+          compactLsm();
+        } catch (LanceDbRestClient.HttpException e) {
+          if (isLostClaim(e)) {
+            return false;
+          }
+          if (!isRetryable(e)) {
+            throw e;
+          }
+          // A 429 here means the server could latch no bucket at all, which the poll
+          // above already handles. Not retried in place: the latch it would contend for
+          // is the one doing the work, so fall through and re-read — POLL_INTERVAL_MS is
+          // the backoff.
+        }
+      }
+      sleep(POLL_INTERVAL_MS);
+    }
+  }
+
+  /** The newest generation held by each bucket, skipping buckets holding none. */
+  private static Map<String, Long> newestGenerations(LsmStats stats) {
+    Map<String, Long> targets = new HashMap<String, Long>();
+    for (BucketStats bucket : stats.buckets()) {
+      OptionalLong newest = bucket.newestGeneration();
+      if (newest.isPresent()) {
+        targets.put(bucket.shardId(), newest.getAsLong());
+      }
+    }
+    return targets;
+  }
+
+  /**
+   * 429 (latch held, pool saturated, or the pod replaying its WAL) and 503 (a draining node, or a
+   * proxy between here and it).
+   */
+  private static boolean isRetryable(LanceDbRestClient.HttpException e) {
+    return e.statusCode() == 429 || e.statusCode() == 503;
+  }
+
+  /**
+   * 421: the owning node holds no claim. Only {@code flush} re-claims and replays, so this cannot
+   * be retried in place — the caller has to start over.
+   */
+  private static boolean isLostClaim(LanceDbRestClient.HttpException e) {
+    return e.statusCode() == 421;
+  }
+
+  /**
+   * Issue one LSM request, retrying in place while the fault is retryable.
+   *
+   * <p>The two recoverable faults have separate budgets: contention clears on its own and retries
+   * here against {@link #MAX_RETRIES}, while a 421 needs {@code flush} to re-claim, which only the
+   * caller can drive.
+   *
+   * <p>An exhausted budget propagates the last error as itself rather than a synthesized one — "429
+   * after nine tries" beats "checkpoint failed".
+   */
+  private static <T> Attempt<T> issue(Call<T> call) {
+    int retries = 0;
+    while (true) {
+      try {
+        return new Attempt<T>(call.run(), false);
+      } catch (LanceDbRestClient.HttpException e) {
+        if (isLostClaim(e)) {
+          return new Attempt<T>(null, true);
+        }
+        if (!isRetryable(e) || retries >= MAX_RETRIES) {
+          throw e;
+        }
+        backoff(retries);
+        retries++;
+      }
+    }
+  }
+
+  /** {@link #issue} for a call with no return value. Returns true when the claim was lost. */
+  private static boolean issueVoid(Runnable call) {
+    return issue(
+            () -> {
+              call.run();
+              return Boolean.TRUE;
+            })
+        .lostClaim;
+  }
+
+  /** Sleep before re-issuing a retryable request. Doubles up to {@link #RETRY_BACKOFF_MAX_MS}. */
+  private static void backoff(int attempt) {
+    long delay = RETRY_BACKOFF_BASE_MS << Math.min(attempt, 8);
+    sleep(Math.min(delay, RETRY_BACKOFF_MAX_MS));
+  }
+
+  private static void sleep(long millis) {
+    try {
+      Thread.sleep(millis);
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+      throw new IllegalStateException("Interrupted while waiting on the LSM checkpoint", e);
+    }
+  }
+
+  private String route(String operation) {
+    return "/v1/table/" + tableIdentifier + "/" + operation + "/";
+  }
+
+  /** What one LSM request produced: its value, or word that the owning node holds no claim. */
+  private static final class Attempt<T> {
+    private final T value;
+    private final boolean lostClaim;
+
+    private Attempt(T value, boolean lostClaim) {
+      this.value = value;
+      this.lostClaim = lostClaim;
+    }
+  }
+
+  @FunctionalInterface
+  private interface Call<T> {
+    T run();
+  }
+}
@@ -0,0 +1,56 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Live per-bucket LSM state, as returned by {@link LanceDbTableLsm#getLsmStats()}.
+ *
+ * <p>Nothing here is derived: sums and differences (total L0 bytes, WAL lag) are the caller's to
+ * compute. There is no "LSM is off" shape — that case is an empty {@link java.util.Optional},
+ * because a stats object of zeros would read as measurements.
+ */
+public class LsmStats {
+  private static final String CONTEXT = "lsm stats";
+
+  private final List<BucketStats> buckets;
+
+  LsmStats(List<BucketStats> buckets) {
+    this.buckets = Collections.unmodifiableList(buckets);
+  }
+
+  /** One entry per bucket. */
+  public List<BucketStats> buckets() {
+    return buckets;
+  }
+
+  static LsmStats fromJson(JsonNode node) {
+    JsonFields.requiredObject(node, CONTEXT);
+    List<BucketStats> buckets = new ArrayList<BucketStats>();
+    for (JsonNode bucket : JsonFields.requiredArray(node, "buckets", CONTEXT)) {
+      buckets.add(BucketStats.fromJson(bucket));
+    }
+    return new LsmStats(buckets);
+  }
+
+  @Override
+  public String toString() {
+    return "LsmStats{buckets=" + buckets + "}";
+  }
+}
@@ -0,0 +1,260 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Specification selecting Lance's MemWAL LSM-style write path for {@code mergeInsert}.
+ *
+ * <p>Construct via {@link #bucket}, {@link #identity}, or {@link #unsharded}, then optionally chain
+ * {@link #withMaintainedIndexes} and {@link #withWriterConfigDefaults}. Install it with {@link
+ * LanceDbTableLsm#setLsmWriteSpec} and remove it with {@link LanceDbTableLsm#unsetLsmWriteSpec}.
+ *
+ * <p>This is deliberately not {@code org.lance.memwal.InitializeMemWalParams}. That type is Lance's
+ * own, and its maintained-index default is the opposite of this one: it defaults to maintaining
+ * <em>nothing</em>, while a fresh spec here maintains <em>every</em> index. It also cannot express
+ * the null that asks the server to resolve the set.
+ */
+public class LsmWriteSpec {
+
+  /** How writes are routed to MemWAL shards. */
+  public enum Sharding {
+    /** Hash-bucket writes by a scalar column. */
+    BUCKET("bucket"),
+    /** Shard by the raw value of a scalar column. */
+    IDENTITY("identity"),
+    /** Route every write to a single shard. */
+    UNSHARDED("unsharded");
+
+    private final String wireName;
+
+    Sharding(String wireName) {
+      this.wireName = wireName;
+    }
+
+    String wireName() {
+      return wireName;
+    }
+
+    static Sharding fromWireName(String name) {
+      for (Sharding s : values()) {
+        if (s.wireName.equals(name)) {
+          return s;
+        }
+      }
+      throw new IllegalArgumentException("Unknown sharding mode: " + name);
+    }
+  }
+
+  private final Sharding sharding;
+  private final String column;
+  private final Integer numBuckets;
+  private final List<String> maintainedIndexes;
+  private final Map<String, String> writerConfigDefaults;
+
+  private LsmWriteSpec(
+      Sharding sharding,
+      String column,
+      Integer numBuckets,
+      List<String> maintainedIndexes,
+      Map<String, String> writerConfigDefaults) {
+    this.sharding = sharding;
+    this.column = column;
+    this.numBuckets = numBuckets;
+    this.maintainedIndexes = maintainedIndexes;
+    this.writerConfigDefaults = writerConfigDefaults;
+  }
+
+  /**
+   * Hash-bucket sharding by a scalar column, maintaining every index on the table.
+   *
+   * <p>Iceberg-compatible Murmur3-x86-32 (seed 0) is used, so each row's {@code bucket(column,
+   * numBuckets)} value is stable across processes.
+   *
+   * @param column A non-nested column with a supported scalar type.
+   * @param numBuckets The number of buckets, in {@code [1, 1024]}.
+   */
+  public static LsmWriteSpec bucket(String column, int numBuckets) {
+    if (column == null || column.trim().isEmpty()) {
+      throw new IllegalArgumentException("Column cannot be null or empty");
+    }
+    return new LsmWriteSpec(
+        Sharding.BUCKET, column, numBuckets, null, new HashMap<String, String>());
+  }
+
+  /**
+   * Identity sharding — shard by the raw value of {@code column} — maintaining every index on the
+   * table.
+   *
+   * <p>{@code column} must be a deterministic function of the unenforced primary key: every row
+   * with a given primary key must always produce the same {@code column} value, or upserts of that
+   * key can land in different shards and a stale version can win.
+   */
+  public static LsmWriteSpec identity(String column) {
+    if (column == null || column.trim().isEmpty()) {
+      throw new IllegalArgumentException("Column cannot be null or empty");
+    }
+    return new LsmWriteSpec(Sharding.IDENTITY, column, null, null, new HashMap<String, String>());
+  }
+
+  /** No sharding — every write goes to a single MemWAL shard — maintaining every index. */
+  public static LsmWriteSpec unsharded() {
+    return new LsmWriteSpec(Sharding.UNSHARDED, null, null, null, new HashMap<String, String>());
+  }
+
+  /**
+   * Set the indexes the MemWAL keeps up to date as rows are appended.
+   *
+   * <p>Pass {@code null} — the default for a fresh spec — to maintain every index the MemWAL can,
+   * resolved when the spec is installed. That is a snapshot: indexes created later are not
+   * maintained until the spec is unset and set again. Pass an empty list to maintain none.
+   *
+   * <p>Note that {@code null} and the empty list mean opposite things here.
+   */
+  public LsmWriteSpec withMaintainedIndexes(List<String> maintainedIndexes) {
+    return new LsmWriteSpec(
+        sharding,
+        column,
+        numBuckets,
+        maintainedIndexes == null ? null : new ArrayList<String>(maintainedIndexes),
+        writerConfigDefaults);
+  }
+
+  /**
+   * Set default {@code ShardWriter} configuration recorded in the MemWAL index.
+   *
+   * <p>A sparse override map — only the keys you set are recorded. Recognized keys include {@code
+   * durable_write}, {@code max_wal_buffer_size}, {@code max_memtable_size}, {@code
+   * max_memtable_rows}, {@code max_memtable_batches}, {@code manifest_scan_batch_size}, {@code
+   * max_unflushed_memtable_bytes}, and {@code enable_memtable}. Duration knobs carry an {@code _ms}
+   * suffix, such as {@code max_wal_flush_interval_ms}.
+   */
+  public LsmWriteSpec withWriterConfigDefaults(Map<String, String> writerConfigDefaults) {
+    if (writerConfigDefaults == null) {
+      throw new IllegalArgumentException("writerConfigDefaults cannot be null");
+    }
+    return new LsmWriteSpec(
+        sharding,
+        column,
+        numBuckets,
+        maintainedIndexes,
+        new HashMap<String, String>(writerConfigDefaults));
+  }
+
+  /** How writes are routed to shards. */
+  public Sharding sharding() {
+    return sharding;
+  }
+
+  /** The sharding column for {@link Sharding#BUCKET} and {@link Sharding#IDENTITY}, else null. */
+  public String column() {
+    return column;
+  }
+
+  /** The bucket count for {@link Sharding#BUCKET}, else null. */
+  public Integer numBuckets() {
+    return numBuckets;
+  }
+
+  /**
+   * The indexes the MemWAL maintains, or null to have the server resolve every maintainable index
+   * on install. An empty list means none.
+   */
+  public List<String> maintainedIndexes() {
+    return maintainedIndexes == null ? null : Collections.unmodifiableList(maintainedIndexes);
+  }
+
+  /** Default {@code ShardWriter} configuration recorded in the MemWAL index. */
+  public Map<String, String> writerConfigDefaults() {
+    return Collections.unmodifiableMap(writerConfigDefaults);
+  }
+
+  /** Render this spec as the {@code set_lsm_write_spec} request body. */
+  Map<String, Object> toRequestBody() {
+    Map<String, Object> shardingBody = new LinkedHashMap<String, Object>();
+    shardingBody.put("mode", sharding.wireName());
+    if (column != null) {
+      shardingBody.put("column", column);
+    }
+    if (numBuckets != null) {
+      shardingBody.put("num_buckets", numBuckets);
+    }
+
+    Map<String, Object> body = new LinkedHashMap<String, Object>();
+    body.put("sharding", shardingBody);
+    // Null is meaningful: it asks the server to resolve every maintainable index.
+    body.put("maintained_indexes", maintainedIndexes);
+    body.put("writer_config_defaults", writerConfigDefaults);
+    return body;
+  }
+
+  /**
+   * Rebuild a spec from a {@code get_lsm_write_spec} response body.
+   *
+   * <p>The server always reports a concrete maintained-index list, so a null selection never
+   * round-trips.
+   */
+  static LsmWriteSpec fromJson(JsonNode node) {
+    JsonNode shardingNode = node.get("sharding");
+    if (shardingNode == null || shardingNode.get("mode") == null) {
+      throw new IllegalStateException("get_lsm_write_spec response has no sharding mode");
+    }
+    Sharding sharding = Sharding.fromWireName(shardingNode.get("mode").asText());
+
+    String column = shardingNode.hasNonNull("column") ? shardingNode.get("column").asText() : null;
+    Integer numBuckets =
+        shardingNode.hasNonNull("num_buckets") ? shardingNode.get("num_buckets").asInt() : null;
+
+    List<String> maintainedIndexes = new ArrayList<String>();
+    JsonNode indexesNode = node.get("maintained_indexes");
+    if (indexesNode != null && indexesNode.isArray()) {
+      for (JsonNode index : indexesNode) {
+        maintainedIndexes.add(index.asText());
+      }
+    }
+
+    Map<String, String> defaults = new HashMap<String, String>();
+    JsonNode defaultsNode = node.get("writer_config_defaults");
+    if (defaultsNode != null && defaultsNode.isObject()) {
+      defaultsNode
+          .fieldNames()
+          .forEachRemaining(name -> defaults.put(name, defaultsNode.get(name).asText()));
+    }
+
+    return new LsmWriteSpec(sharding, column, numBuckets, maintainedIndexes, defaults);
+  }
+
+  @Override
+  public String toString() {
+    return "LsmWriteSpec{sharding="
+        + sharding
+        + ", column="
+        + column
+        + ", numBuckets="
+        + numBuckets
+        + ", maintainedIndexes="
+        + maintainedIndexes
+        + ", writerConfigDefaults="
+        + writerConfigDefaults
+        + "}";
+  }
+}
@@ -0,0 +1,99 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/** One in-memory memtable. */
+public class MemtableStats {
+  private static final String CONTEXT = "memtable stats";
+
+  private final long generation;
+  private final long rows;
+  private final long bytes;
+  private final long batches;
+  private final List<String> indexes;
+
+  MemtableStats(long generation, long rows, long bytes, long batches, List<String> indexes) {
+    this.generation = generation;
+    this.rows = rows;
+    this.bytes = bytes;
+    this.batches = batches;
+    this.indexes = Collections.unmodifiableList(indexes);
+  }
+
+  /** The generation this memtable will become once sealed. */
+  public long generation() {
+    return generation;
+  }
+
+  /** Rows currently buffered. */
+  public long rows() {
+    return rows;
+  }
+
+  /** Estimated in-memory size. */
+  public long bytes() {
+    return bytes;
+  }
+
+  /** Record batches currently buffered. */
+  public long batches() {
+    return batches;
+  }
+
+  /**
+   * Names of the indexes this memtable carries. An absent name is the whole answer to "why is my
+   * fresh-tier search on that column brute-force".
+   */
+  public List<String> indexes() {
+    return indexes;
+  }
+
+  static MemtableStats fromJson(JsonNode node) {
+    JsonFields.requiredObject(node, CONTEXT);
+    List<String> indexes = new ArrayList<String>();
+    for (JsonNode index : JsonFields.requiredArray(node, "indexes", CONTEXT)) {
+      if (!index.isTextual()) {
+        throw new IllegalStateException(CONTEXT + " has a non-string index name: " + index);
+      }
+      indexes.add(index.asText());
+    }
+    return new MemtableStats(
+        JsonFields.requiredLong(node, "generation", CONTEXT),
+        JsonFields.requiredLong(node, "rows", CONTEXT),
+        JsonFields.requiredLong(node, "bytes", CONTEXT),
+        JsonFields.requiredLong(node, "batches", CONTEXT),
+        indexes);
+  }
+
+  @Override
+  public String toString() {
+    return "MemtableStats{generation="
+        + generation
+        + ", rows="
+        + rows
+        + ", bytes="
+        + bytes
+        + ", batches="
+        + batches
+        + ", indexes="
+        + indexes
+        + "}";
+  }
+}
@@ -0,0 +1,570 @@
+/*
+ * 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 com.lancedb;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.sun.net.httpserver.HttpServer;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Deque;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Unit tests for the MemWAL LSM routes, run against a scripted local HTTP server.
+ *
+ * <p>The wire assertions mirror the Rust mocked-endpoint tests in {@code
+ * rust/lancedb/src/remote/table.rs}, which are the contract these routes have to match.
+ */
+public class LanceDbTableLsmTest {
+  private static final ObjectMapper MAPPER = new ObjectMapper();
+
+  private HttpServer server;
+  private LanceDbRestClient client;
+  private LanceDbTableLsm lsm;
+
+  private final List<String> requestPaths = Collections.synchronizedList(new ArrayList<String>());
+  private final List<String> requestBodies = Collections.synchronizedList(new ArrayList<String>());
+  private final Map<String, Deque<Reply>> replies = new ConcurrentHashMap<String, Deque<Reply>>();
+
+  @BeforeEach
+  public void setUp() throws IOException {
+    start();
+  }
+
+  /** Tear down and restart the scripted server, for a test that scripts several exchanges. */
+  private void setUpFresh() {
+    try {
+      client.close();
+      server.stop(0);
+      requestPaths.clear();
+      requestBodies.clear();
+      replies.clear();
+      start();
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
+
+  private void start() throws IOException {
+    server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+    server.createContext(
+        "/",
+        exchange -> {
+          String path = exchange.getRequestURI().getPath();
+          requestPaths.add(path);
+          requestBodies.add(readAll(exchange.getRequestBody()));
+
+          Reply reply = nextReply(path);
+          byte[] out = reply.body.getBytes(StandardCharsets.UTF_8);
+          exchange.sendResponseHeaders(reply.status, out.length == 0 ? -1 : out.length);
+          if (out.length > 0) {
+            exchange.getResponseBody().write(out);
+          }
+          exchange.close();
+        });
+    server.start();
+
+    client =
+        LanceDbNamespaceClientBuilder.newBuilder()
+            .apiKey("test-key")
+            .database("test-db")
+            .endpoint("http://127.0.0.1:" + server.getAddress().getPort())
+            .buildRestClient();
+    lsm = new LanceDbTableLsm(client, "my_table");
+  }
+
+  @AfterEach
+  public void tearDown() throws IOException {
+    client.close();
+    server.stop(0);
+  }
+
+  // ===========================================================================
+  // set / unset / get spec
+  // ===========================================================================
+
+  @Test
+  public void testSetLsmWriteSpecUnsharded() throws Exception {
+    enqueue("set_lsm_write_spec", 200, "");
+
+    lsm.setLsmWriteSpec(LsmWriteSpec.unsharded());
+
+    assertEquals("/v1/table/my_table/set_lsm_write_spec/", requestPaths.get(0));
+    JsonNode body = MAPPER.readTree(requestBodies.get(0));
+    assertEquals("unsharded", body.get("sharding").get("mode").asText());
+    assertFalse(body.get("sharding").has("column"));
+    assertFalse(body.get("sharding").has("num_buckets"));
+  }
+
+  @Test
+  public void testSetLsmWriteSpecBucket() throws Exception {
+    enqueue("set_lsm_write_spec", 200, "");
+
+    lsm.setLsmWriteSpec(
+        LsmWriteSpec.bucket("id", 16).withMaintainedIndexes(Arrays.asList("id_idx")));
+
+    JsonNode body = MAPPER.readTree(requestBodies.get(0));
+    assertEquals("bucket", body.get("sharding").get("mode").asText());
+    assertEquals("id", body.get("sharding").get("column").asText());
+    assertEquals(16, body.get("sharding").get("num_buckets").asInt());
+    assertEquals(1, body.get("maintained_indexes").size());
+    assertEquals("id_idx", body.get("maintained_indexes").get(0).asText());
+  }
+
+  @Test
+  public void testSetLsmWriteSpecIdentity() throws Exception {
+    enqueue("set_lsm_write_spec", 200, "");
+
+    lsm.setLsmWriteSpec(LsmWriteSpec.identity("tenant"));
+
+    JsonNode body = MAPPER.readTree(requestBodies.get(0));
+    assertEquals("identity", body.get("sharding").get("mode").asText());
+    assertEquals("tenant", body.get("sharding").get("column").asText());
+    assertFalse(body.get("sharding").has("num_buckets"));
+  }
+
+  /**
+   * The tri-state that motivated a LanceDB-owned spec type: a null selection asks the server to
+   * resolve every maintainable index, while an empty list asks for none. They must not collapse.
+   */
+  @Test
+  public void testMaintainedIndexesNullAndEmptyAreDistinctOnTheWire() throws Exception {
+    enqueue("set_lsm_write_spec", 200, "");
+
+    lsm.setLsmWriteSpec(LsmWriteSpec.unsharded());
+    JsonNode fresh = MAPPER.readTree(requestBodies.get(0));
+    assertTrue(fresh.has("maintained_indexes"), "the key must be present");
+    assertTrue(fresh.get("maintained_indexes").isNull(), "a fresh spec sends null, not []");
+
+    lsm.setLsmWriteSpec(
+        LsmWriteSpec.unsharded().withMaintainedIndexes(Collections.<String>emptyList()));
+    JsonNode none = MAPPER.readTree(requestBodies.get(1));
+    assertTrue(none.get("maintained_indexes").isArray());
+    assertEquals(0, none.get("maintained_indexes").size());
+  }
+
+  @Test
+  public void testSetLsmWriteSpecWriterConfigDefaults() throws Exception {
+    enqueue("set_lsm_write_spec", 200, "");
+
+    Map<String, String> defaults = new HashMap<String, String>();
+    defaults.put("max_memtable_rows", "50000");
+    lsm.setLsmWriteSpec(LsmWriteSpec.unsharded().withWriterConfigDefaults(defaults));
+
+    JsonNode body = MAPPER.readTree(requestBodies.get(0));
+    assertEquals("50000", body.get("writer_config_defaults").get("max_memtable_rows").asText());
+  }
+
+  @Test
+  public void testUnsetLsmWriteSpec() {
+    enqueue("unset_lsm_write_spec", 200, "");
+
+    lsm.unsetLsmWriteSpec();
+
+    assertEquals("/v1/table/my_table/unset_lsm_write_spec/", requestPaths.get(0));
+    assertEquals("", requestBodies.get(0));
+  }
+
+  @Test
+  public void testGetLsmWriteSpec() {
+    enqueue(
+        "get_lsm_write_spec",
+        200,
+        "{\"lsm_write_spec\":{\"sharding\":{\"mode\":\"bucket\",\"column\":\"id\","
+            + "\"num_buckets\":16},\"maintained_indexes\":[\"id_idx\"],"
+            + "\"writer_config_defaults\":{\"durable_write\":\"true\"}}}");
+
+    Optional<LsmWriteSpec> spec = lsm.getLsmWriteSpec();
+
+    assertTrue(spec.isPresent());
+    assertEquals(LsmWriteSpec.Sharding.BUCKET, spec.get().sharding());
+    assertEquals("id", spec.get().column());
+    assertEquals(Integer.valueOf(16), spec.get().numBuckets());
+    assertEquals(Arrays.asList("id_idx"), spec.get().maintainedIndexes());
+    assertEquals("true", spec.get().writerConfigDefaults().get("durable_write"));
+  }
+
+  @Test
+  public void testGetLsmWriteSpecAbsent() {
+    enqueue("get_lsm_write_spec", 200, "{\"lsm_write_spec\":null}");
+
+    assertFalse(lsm.getLsmWriteSpec().isPresent());
+  }
+
+  // ===========================================================================
+  // stats
+  // ===========================================================================
+
+  @Test
+  public void testGetLsmStats() throws Exception {
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false, 7L, 8L)));
+
+    Optional<LsmStats> got = lsm.getLsmStats(true);
+
+    assertEquals("/v1/table/my_table/get_lsm_stats/", requestPaths.get(0));
+    assertTrue(MAPPER.readTree(requestBodies.get(0)).get("include_generation_rows").asBoolean());
+    assertTrue(got.isPresent());
+    BucketStats decoded = got.get().buckets().get(0);
+    assertEquals("shard-0", decoded.shardId());
+    assertEquals("Active", decoded.status());
+    assertEquals(1, decoded.writerEpoch());
+    assertEquals(2, decoded.manifestVersion());
+    assertEquals(9, decoded.currentGeneration());
+    assertFalse(decoded.compacting());
+    assertEquals(Arrays.asList(7L, 8L), generationNumbers(decoded));
+    assertEquals(1024, decoded.generations().get(0).bytes());
+    assertFalse(decoded.generations().get(0).rows().isPresent(), "rows absent unless requested");
+    assertFalse(decoded.memtables().isPresent(), "absent memtables stay absent");
+  }
+
+  /** The optional fields decode when the server does send them. */
+  @Test
+  public void testGetLsmStatsDecodesOptionalFields() {
+    enqueue(
+        "get_lsm_stats",
+        200,
+        "{\"lsm_stats\":{\"buckets\":[{\"shard_id\":\"shard-0\",\"status\":\"Active\","
+            + "\"writer_epoch\":1,\"manifest_version\":2,\"current_generation\":9,"
+            + "\"replay_after_wal_entry_position\":3,\"wal_entry_position_last_seen\":11,"
+            + "\"generations\":[{\"generation\":7,\"bytes\":1024,\"rows\":42}],"
+            + "\"compacting\":true,\"memtables\":[{\"generation\":8,\"rows\":5,"
+            + "\"bytes\":64,\"batches\":2,\"indexes\":[\"id_idx\"]}]}]}}");
+
+    BucketStats decoded = lsm.getLsmStats(true).get().buckets().get(0);
+
+    assertEquals(3, decoded.replayAfterWalEntryPosition());
+    assertEquals(11, decoded.walEntryPositionLastSeen());
+    assertTrue(decoded.compacting());
+    assertEquals(42, decoded.generations().get(0).rows().getAsLong());
+    assertTrue(decoded.memtables().isPresent());
+    MemtableStats memtable = decoded.memtables().get().get(0);
+    assertEquals(8, memtable.generation());
+    assertEquals(5, memtable.rows());
+    assertEquals(64, memtable.bytes());
+    assertEquals(2, memtable.batches());
+    assertEquals(Arrays.asList("id_idx"), memtable.indexes());
+  }
+
+  @Test
+  public void testGetLsmStatsAbsentWhenLsmDisabled() {
+    enqueue("get_lsm_stats", 200, "{\"lsm_stats\":null}");
+
+    assertFalse(lsm.getLsmStats().isPresent());
+  }
+
+  @Test
+  public void testGetLsmStatsDefaultsToExcludingGenerationRows() throws Exception {
+    enqueue("get_lsm_stats", 200, stats());
+
+    lsm.getLsmStats();
+
+    assertFalse(MAPPER.readTree(requestBodies.get(0)).get("include_generation_rows").asBoolean());
+  }
+
+  // ===========================================================================
+  // flush / compact
+  // ===========================================================================
+
+  @Test
+  public void testFlushAndCompactRoutes() {
+    enqueue("flush_lsm", 200, "");
+    enqueue("compact_lsm", 200, "");
+
+    lsm.flushLsm();
+    lsm.compactLsm();
+
+    assertEquals("/v1/table/my_table/flush_lsm/", requestPaths.get(0));
+    assertEquals("/v1/table/my_table/compact_lsm/", requestPaths.get(1));
+  }
+
+  @Test
+  public void testHttpErrorCarriesStatus() {
+    enqueue("flush_lsm", 404, "no such table");
+
+    LanceDbRestClient.HttpException e =
+        assertThrows(LanceDbRestClient.HttpException.class, () -> lsm.flushLsm());
+    assertEquals(404, e.statusCode());
+  }
+
+  // ===========================================================================
+  // checkpoint
+  // ===========================================================================
+
+  @Test
+  public void testCheckpointReturnsWhenLsmDisabled() {
+    enqueue("flush_lsm", 200, "");
+    enqueue("get_lsm_stats", 200, "{\"lsm_stats\":null}");
+
+    lsm.checkpointLsm();
+
+    assertEquals(0, countCalls("compact_lsm"), "nothing to compact when the LSM path is off");
+  }
+
+  @Test
+  public void testCheckpointReturnsWhenNoGenerationsOutstanding() {
+    enqueue("flush_lsm", 200, "");
+    // A bucket with no L0 generations yields no target, so the drain never starts.
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false)));
+
+    lsm.checkpointLsm();
+
+    assertEquals(0, countCalls("compact_lsm"));
+  }
+
+  @Test
+  public void testCheckpointConvergesOnceTargetGenerationsAreGone() {
+    enqueue("flush_lsm", 200, "");
+    // Watermark read: shard-0 holds generations 7 and 8, so target = 8.
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false, 7L, 8L)));
+    // First drain poll: both still outstanding, nothing compacting -> dispatch a pass.
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false, 7L, 8L)));
+    // Second drain poll: drained past the target -> done.
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false, 9L)));
+    enqueue("compact_lsm", 200, "");
+
+    lsm.checkpointLsm();
+
+    assertEquals(1, countCalls("compact_lsm"), "one pass dispatched");
+    assertEquals(3, countCalls("get_lsm_stats"), "watermark read plus two drain polls");
+  }
+
+  @Test
+  public void testCheckpointDoesNotPileOnWhileEveryTargetBucketIsCompacting() {
+    enqueue("flush_lsm", 200, "");
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", true, 4L)));
+    // Still compacting on the first poll, so no pass is dispatched; then it drains.
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", true, 4L)));
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false, 5L)));
+
+    lsm.checkpointLsm();
+
+    assertEquals(0, countCalls("compact_lsm"), "a latched bucket is left alone");
+  }
+
+  @Test
+  public void testCheckpointRetriesFromFlushAfterLostClaim() {
+    // 421 on the watermark read: the node lost its claim, so the whole thing restarts
+    // from flush rather than retrying the read in place.
+    enqueue("flush_lsm", 200, "");
+    enqueue("get_lsm_stats", 421, "no claim");
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false)));
+
+    lsm.checkpointLsm();
+
+    assertEquals(2, countCalls("flush_lsm"), "re-issued from flush");
+  }
+
+  @Test
+  public void testCheckpointRetriesRetryableStatusInPlace() {
+    enqueue("flush_lsm", 429, "latch held");
+    enqueue("flush_lsm", 200, "");
+    enqueue("get_lsm_stats", 200, stats(bucket("shard-0", false)));
+
+    lsm.checkpointLsm();
+
+    assertEquals(2, countCalls("flush_lsm"), "429 retried in place, not re-issued");
+  }
+
+  @Test
+  public void testCheckpointPropagatesTerminalStatus() {
+    enqueue("flush_lsm", 400, "bad request");
+
+    LanceDbRestClient.HttpException e =
+        assertThrows(LanceDbRestClient.HttpException.class, () -> lsm.checkpointLsm());
+    assertEquals(400, e.statusCode());
+    assertEquals(1, countCalls("flush_lsm"), "a terminal status is not retried");
+  }
+
+  @Test
+  public void testCheckpointGivesUpAfterRepeatedLostClaims() {
+    enqueue("flush_lsm", 421, "no claim");
+
+    IllegalStateException e = assertThrows(IllegalStateException.class, () -> lsm.checkpointLsm());
+    assertTrue(e.getMessage().contains("kept losing its claim"), e.getMessage());
+    assertEquals(4, countCalls("flush_lsm"), "the initial attempt plus MAX_REISSUES");
+  }
+
+  // ===========================================================================
+  // strict decoding
+  // ===========================================================================
+
+  /**
+   * A stats payload that does not decode must fail closed. Every one of these bodies used to be
+   * read as "no buckets", which is indistinguishable from a drained table, so {@code checkpointLsm}
+   * reported convergence for a checkpoint that never ran.
+   */
+  @Test
+  public void testCheckpointRejectsMalformedStats() {
+    Map<String, String> malformed = new LinkedHashMap<String, String>();
+    malformed.put("no response body at all", "");
+    malformed.put("stats object with no buckets", "{\"lsm_stats\":{}}");
+    malformed.put("bucket missing its required fields", "{\"lsm_stats\":{\"buckets\":[{}]}}");
+    malformed.put(
+        "bucket missing generations",
+        "{\"lsm_stats\":{\"buckets\":[{\"shard_id\":\"shard-0\",\"status\":\"Active\","
+            + "\"writer_epoch\":1,\"manifest_version\":2,\"current_generation\":9,"
+            + "\"replay_after_wal_entry_position\":0,\"wal_entry_position_last_seen\":0,"
+            + "\"compacting\":false}]}}");
+    malformed.put(
+        "generation with a non-numeric generation number",
+        "{\"lsm_stats\":{\"buckets\":[{\"shard_id\":\"shard-0\",\"status\":\"Active\","
+            + "\"writer_epoch\":1,\"manifest_version\":2,\"current_generation\":9,"
+            + "\"replay_after_wal_entry_position\":0,\"wal_entry_position_last_seen\":0,"
+            + "\"generations\":[{\"generation\":\"7\",\"bytes\":1024}],"
+            + "\"compacting\":false}]}}");
+
+    for (Map.Entry<String, String> each : malformed.entrySet()) {
+      setUpFresh();
+      enqueue("flush_lsm", 200, "");
+      enqueue("get_lsm_stats", 200, each.getValue());
+
+      assertThrows(
+          IllegalStateException.class,
+          () -> lsm.checkpointLsm(),
+          each.getKey() + " must not report convergence");
+    }
+  }
+
+  /** The one shape that legitimately means "this table has no LSM write path". */
+  @Test
+  public void testCheckpointTreatsNullStatsAsNotWalBacked() {
+    enqueue("flush_lsm", 200, "");
+    enqueue("get_lsm_stats", 200, "{\"lsm_stats\":null}");
+
+    lsm.checkpointLsm();
+
+    assertEquals(1, countCalls("get_lsm_stats"));
+  }
+
+  // ===========================================================================
+  // retry budget
+  // ===========================================================================
+
+  /**
+   * The transport must not retry on the checkpoint loop's behalf. Apache HttpClient's default
+   * strategy retries exactly 429 and 503 — the two statuses {@code isRetryable} owns — which
+   * doubled every budget here and also retried {@code compact_lsm} in place, where the loop is
+   * built to fall through to a fresh stats poll instead.
+   */
+  @Test
+  public void testCheckpointRetryBudgetIsNotDoubledByTheTransport() {
+    enqueue("flush_lsm", 429, "latch held");
+
+    LanceDbRestClient.HttpException e =
+        assertThrows(LanceDbRestClient.HttpException.class, () -> lsm.checkpointLsm());
+
+    assertEquals(429, e.statusCode(), "the exhausted budget propagates the last error as itself");
+    assertEquals(9, countCalls("flush_lsm"), "the initial request plus MAX_RETRIES, and no more");
+  }
+
+  // ===========================================================================
+  // harness
+  // ===========================================================================
+
+  private static List<Long> generationNumbers(BucketStats bucket) {
+    List<Long> numbers = new ArrayList<Long>();
+    for (GenerationStats generation : bucket.generations()) {
+      numbers.add(generation.generation());
+    }
+    return numbers;
+  }
+
+  /** Build an {@code lsm_stats} response body from bucket fragments. */
+  private static String stats(String... buckets) {
+    return "{\"lsm_stats\":{\"buckets\":[" + String.join(",", buckets) + "]}}";
+  }
+
+  private static String bucket(String shardId, boolean compacting, Long... generations) {
+    StringBuilder gens = new StringBuilder();
+    for (Long generation : generations) {
+      if (gens.length() > 0) {
+        gens.append(",");
+      }
+      gens.append("{\"generation\":").append(generation).append(",\"bytes\":1024}");
+    }
+    return "{\"shard_id\":\""
+        + shardId
+        + "\",\"status\":\"Active\",\"writer_epoch\":1,\"manifest_version\":2,"
+        + "\"current_generation\":9,\"replay_after_wal_entry_position\":0,"
+        + "\"wal_entry_position_last_seen\":0,\"generations\":["
+        + gens
+        + "],\"compacting\":"
+        + compacting
+        + "}";
+  }
+
+  /** Queue a reply for an operation. The last queued reply repeats once the queue drains. */
+  private void enqueue(String operation, int status, String body) {
+    replies.computeIfAbsent(operation, key -> new ArrayDeque<Reply>()).add(new Reply(status, body));
+  }
+
+  private Reply nextReply(String path) {
+    String operation = operationOf(path);
+    Deque<Reply> queued = replies.get(operation);
+    if (queued == null || queued.isEmpty()) {
+      return new Reply(200, "");
+    }
+    return queued.size() > 1 ? queued.poll() : queued.peek();
+  }
+
+  private long countCalls(String operation) {
+    return requestPaths.stream().filter(path -> operationOf(path).equals(operation)).count();
+  }
+
+  /** {@code /v1/table/my_table/flush_lsm/} -> {@code flush_lsm}. */
+  private static String operationOf(String path) {
+    String[] segments = path.split("/");
+    return segments.length == 0 ? "" : segments[segments.length - 1];
+  }
+
+  private static String readAll(InputStream in) throws IOException {
+    ByteArrayOutputStream out = new ByteArrayOutputStream();
+    byte[] buffer = new byte[4096];
+    int read;
+    while ((read = in.read(buffer)) != -1) {
+      out.write(buffer, 0, read);
+    }
+    return new String(out.toByteArray(), StandardCharsets.UTF_8);
+  }
+
+  private static final class Reply {
+    private final int status;
+    private final String body;
+
+    private Reply(int status, String body) {
+      this.status = status;
+      this.body = body;
+    }
+  }
+}
@@ -6,7 +6,7 @@

    <groupId>com.lancedb</groupId>
    <artifactId>lancedb-parent</artifactId>
-    <version>0.38.0-beta.0</version>
+    <version>0.38.0-beta.3</version>
    <packaging>pom</packaging>
    <name>${project.artifactId}</name>
    <description>LanceDB Java SDK Parent POM</description>
@@ -28,7 +28,7 @@
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <arrow.version>15.0.0</arrow.version>
-        <lance-core.version>11.0.0-beta.13</lance-core.version>
+        <lance-core.version>11.0.0-beta.16</lance-core.version>
        <spotless.skip>false</spotless.skip>
        <spotless.version>2.30.0</spotless.version>
        <spotless.java.googlejavaformat.version>1.7</spotless.java.googlejavaformat.version>
@@ -1,7 +1,7 @@
 [package]
 name = "lancedb-nodejs"
 edition.workspace = true
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.3"
 publish = false
 license.workspace = true
 description.workspace = true
@@ -16,12 +16,12 @@ crate-type = ["cdylib"]
 async-trait.workspace = true
 arrow-ipc.workspace = true
 arrow-array.workspace = true
-arrow-buffer = "58.0.0"
+arrow-buffer.workspace = true
 half.workspace = true
 arrow-schema.workspace = true
 env_logger.workspace = true
 futures.workspace = true
-lancedb = { path = "../rust/lancedb", default-features = false }
+lancedb.workspace = true
 lance-namespace.workspace = true
 napi = { version = "3.8.3", default-features = false, features = [
    "napi9",
@@ -29,8 +29,8 @@ napi = { version = "3.8.3", default-features = false, features = [
    "chrono_date",
    "serde-json",
 ] }
-chrono = { version = "0.4", default-features = false, features = ["clock"] }
-serde_json = "1"
+chrono.workspace = true
+serde_json.workspace = true
 napi-derive = "3.5.2"
 # Prevent dynamic linking of lzma, which comes from datafusion
 lzma-sys = { version = "0.1", features = ["static"] }
@@ -3341,6 +3341,59 @@ describe("LSM merge insert", () => {
  });
 });

+describe("LSM convergence and stats", () => {
+  let tmpDir: tmp.DirResult;
+
+  beforeEach(() => {
+    tmpDir = tmp.dirSync({ unsafeCleanup: true });
+  });
+  afterEach(() => tmpDir.removeCallback());
+
+  async function lsmTable(conn: Connection): Promise<Table> {
+    const table = await conn.createEmptyTable(
+      "t",
+      new arrow.Schema([new arrow.Field("id", new arrow.Utf8(), false)]),
+    );
+    await table.setUnenforcedPrimaryKey("id");
+    await table.setLsmWriteSpec({ specType: "unsharded" });
+    return table;
+  }
+
+  // These four route through the server that owns the MemWAL, so a local table
+  // rejects them rather than answering. What is asserted here is that the
+  // bindings reach the core at all; the behavior against a real endpoint is
+  // covered by the mocked endpoint tests in rust/lancedb/src/remote/table.rs.
+  it("rejects flushLsm on a local table", async () => {
+    const conn = await connect(tmpDir.name);
+    const table = await lsmTable(conn);
+
+    await expect(table.flushLsm()).rejects.toThrow(/not supported/i);
+  });
+
+  it("rejects compactLsm on a local table", async () => {
+    const conn = await connect(tmpDir.name);
+    const table = await lsmTable(conn);
+
+    await expect(table.compactLsm()).rejects.toThrow(/not supported/i);
+  });
+
+  it("rejects getLsmStats on a local table", async () => {
+    const conn = await connect(tmpDir.name);
+    const table = await lsmTable(conn);
+
+    await expect(table.getLsmStats()).rejects.toThrow(/not supported/i);
+    await expect(table.getLsmStats(true)).rejects.toThrow(/not supported/i);
+  });
+
+  it("rejects checkpointLsm on a local table", async () => {
+    const conn = await connect(tmpDir.name);
+    const table = await lsmTable(conn);
+
+    // checkpointLsm seals first, so it surfaces flushLsm's rejection.
+    await expect(table.checkpointLsm()).rejects.toThrow(/not supported/i);
+  });
+});
+
 describe("computed columns", () => {
  let tmpDir: tmp.DirResult;
  beforeEach(() => {
@@ -147,6 +147,10 @@ export {
  FtsToken,
  TokenizeTableOptions,
  LsmWriteSpec,
+  LsmStats,
+  BucketStats,
+  GenerationStats,
+  MemtableStats,
  ColumnAlteration,
  FieldMetadataUpdate,
 } from "./table";
@@ -31,6 +31,7 @@ import {
  IndexConfig,
  IndexStatistics,
  Job,
+  LsmStats,
  Branches as NativeBranches,
  OptimizeStats,
  RefreshColumnResult,
@@ -50,6 +51,12 @@ import {
 import { sanitizeType } from "./sanitize";
 import { IntoSql, toSQL } from "./util";
 export { IndexConfig } from "./native";
+export {
+  BucketStats,
+  GenerationStats,
+  LsmStats,
+  MemtableStats,
+} from "./native";

 /**
 * Progress snapshot for a write operation, delivered to the `progress`
@@ -706,6 +713,59 @@ export abstract class Table {
   * @returns {Promise<void>}
   */
  abstract closeLsmWriters(): Promise<void>;
+  /**
+   * Seal every bucket's active memtable into a new L0 generation.
+   *
+   * Returns once the seal is committed. Sealing an empty memtable is a no-op,
+   * so this is safe to call repeatedly.
+   * @returns {Promise<void>}
+   */
+  abstract flushLsm(): Promise<void>;
+  /**
+   * Trigger a background L0 → base compaction pass per bucket.
+   *
+   * Returns once the passes are *dispatched*, not once they finish — watch
+   * {@link Table#getLsmStats} for progress, or use
+   * {@link Table#checkpointLsm} to wait for convergence.
+   * @returns {Promise<void>}
+   */
+  abstract compactLsm(): Promise<void>;
+  /**
+   * Converge this table's LSM write path into its base table.
+   *
+   * Seals once, then triggers compaction and polls until the L0 that existed
+   * at the start is gone. The target set is fixed at the start, so
+   * generations created *during* the checkpoint are ignored — that is what
+   * lets it terminate under write load, and what makes it best-effort: it
+   * converges the fresh tier as of some instant. Idempotent, abandonable at
+   * any point, and safe to run on a cadence.
+   *
+   * There is no liveness bound — the compactor pool is shared across tables,
+   * so a checkpoint queued behind unrelated work looks exactly like one that
+   * is merging. The caller owns the deadline.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * const before = await table.getLsmStats();
+   * await table.checkpointLsm();
+   * const after = await table.getLsmStats();
+   * ```
+   */
+  abstract checkpointLsm(): Promise<void>;
+  /**
+   * Read live per-bucket LSM state.
+   *
+   * Answers "how far behind is my fresh tier", "which bucket is hot", and
+   * "why is my fresh-tier vector search brute-force". Mutates no table state.
+   *
+   * Resolves to `undefined` only when the LSM write path is not enabled.
+   * @param {boolean} includeGenerationRows Also count rows per L0 generation.
+   *   Off by default because each count opens an uncached Lance dataset.
+   * @returns {Promise<LsmStats | undefined>}
+   */
+  abstract getLsmStats(
+    includeGenerationRows?: boolean,
+  ): Promise<LsmStats | undefined>;
  /** Retrieve the version of the table */

  abstract version(): Promise<number>;
@@ -1266,6 +1326,24 @@ export class LocalTable extends Table {
    return await this.inner.closeLsmWriters();
  }

+  async flushLsm(): Promise<void> {
+    return await this.inner.flushLsm();
+  }
+
+  async compactLsm(): Promise<void> {
+    return await this.inner.compactLsm();
+  }
+
+  async checkpointLsm(): Promise<void> {
+    return await this.inner.checkpointLsm();
+  }
+
+  async getLsmStats(
+    includeGenerationRows: boolean = false,
+  ): Promise<LsmStats | undefined> {
+    return (await this.inner.getLsmStats(includeGenerationRows)) ?? undefined;
+  }
+
  async version(): Promise<number> {
    return await this.inner.version();
  }
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-darwin-arm64",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.3",
 	"os": ["darwin"],
 	"cpu": ["arm64"],
 	"main": "lancedb.darwin-arm64.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-gnu",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.3",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-gnu.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-musl",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.3",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-musl.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-gnu",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.3",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-gnu.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-musl",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.3",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-musl.node",
@@ -1,6 +1,6 @@
 {
  "name": "@lancedb/lancedb-win32-arm64-msvc",
-  "version": "0.38.0-beta.0",
+  "version": "0.38.0-beta.3",
  "os": [
    "win32"
  ],
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-win32-x64-msvc",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.3",
 	"os": ["win32"],
 	"cpu": ["x64"],
 	"main": "lancedb.win32-x64-msvc.node",
@@ -1,12 +1,12 @@
 {
  "name": "@lancedb/lancedb",
-  "version": "0.38.0-beta.0",
+  "version": "0.38.0-beta.2",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@lancedb/lancedb",
-      "version": "0.38.0-beta.0",
+      "version": "0.38.0-beta.2",
      "cpu": [
        "x64",
        "arm64"
@@ -11,7 +11,7 @@
    "ann"
  ],
  "private": false,
-  "version": "0.38.0-beta.0",
+  "version": "0.38.0-beta.3",
  "main": "dist/index.js",
  "exports": {
    ".": "./dist/index.js",
@@ -497,6 +497,34 @@ impl Table {
        self.inner_ref()?.close_lsm_writers().await.default_error()
    }

+    #[napi(catch_unwind)]
+    pub async fn flush_lsm(&self) -> napi::Result<()> {
+        self.inner_ref()?.flush_lsm().await.default_error()
+    }
+
+    #[napi(catch_unwind)]
+    pub async fn compact_lsm(&self) -> napi::Result<()> {
+        self.inner_ref()?.compact_lsm().await.default_error()
+    }
+
+    #[napi(catch_unwind)]
+    pub async fn checkpoint_lsm(&self) -> napi::Result<()> {
+        self.inner_ref()?.checkpoint_lsm().await.default_error()
+    }
+
+    #[napi(catch_unwind)]
+    pub async fn get_lsm_stats(
+        &self,
+        include_generation_rows: bool,
+    ) -> napi::Result<Option<LsmStats>> {
+        let stats = self
+            .inner_ref()?
+            .get_lsm_stats(include_generation_rows)
+            .await
+            .default_error()?;
+        Ok(stats.map(LsmStats::from))
+    }
+
    #[napi(catch_unwind)]
    pub async fn version(&self) -> napi::Result<i64> {
        self.inner_ref()?
@@ -889,6 +917,129 @@ impl From<lancedb::table::LsmWriteSpec> for LsmWriteSpec {
    }
 }

+/// One flushed L0 generation.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct GenerationStats {
+    /// The generation number. Increases as memtables are sealed into L0.
+    pub generation: i64,
+    /// On-disk size of the generation.
+    pub bytes: i64,
+    /// Present only when `includeGenerationRows` was requested. Off by default
+    /// because each count opens an uncached Lance dataset.
+    pub rows: Option<i64>,
+}
+
+impl From<lancedb::table::GenerationStats> for GenerationStats {
+    fn from(g: lancedb::table::GenerationStats) -> Self {
+        Self {
+            generation: g.generation as i64,
+            bytes: g.bytes as i64,
+            rows: g.rows.map(|r| r as i64),
+        }
+    }
+}
+
+/// One in-memory memtable.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct MemtableStats {
+    /// The generation this memtable will become once sealed.
+    pub generation: i64,
+    /// Rows currently buffered.
+    pub rows: i64,
+    /// Estimated in-memory size.
+    pub bytes: i64,
+    /// Record batches currently buffered.
+    pub batches: i64,
+    /// Names of the indexes this memtable carries. An absent name is the whole
+    /// answer to "why is my fresh-tier search on that column brute-force".
+    pub indexes: Vec<String>,
+}
+
+impl From<lancedb::table::MemtableStats> for MemtableStats {
+    fn from(m: lancedb::table::MemtableStats) -> Self {
+        Self {
+            generation: m.generation as i64,
+            rows: m.rows as i64,
+            bytes: m.bytes as i64,
+            batches: m.batches as i64,
+            indexes: m.indexes,
+        }
+    }
+}
+
+/// Live state of one bucket. A table is N buckets on one node; flattening to a
+/// single number hides the one hot bucket that is usually why someone opened
+/// this endpoint.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct BucketStats {
+    /// The shard this bucket writes.
+    pub shard_id: String,
+    /// `"Active"` or `"Sealed"` (drop-table 2PC in flight).
+    pub status: String,
+    /// Epoch of the writer that currently owns the shard.
+    pub writer_epoch: i64,
+    /// Version of the shard manifest these numbers were read from.
+    pub manifest_version: i64,
+    /// The generation the active memtable will become.
+    pub current_generation: i64,
+    /// WAL position replay resumes from.
+    pub replay_after_wal_entry_position: i64,
+    /// Highest WAL position the writer has seen. The difference against
+    /// `replayAfterWalEntryPosition` is the WAL lag.
+    pub wal_entry_position_last_seen: i64,
+    /// Flushed L0 generations not yet merged into the base table.
+    pub generations: Vec<GenerationStats>,
+    /// Whether a pass owns this bucket's compaction latch right now. Says *a*
+    /// driver is running, not *whose*, and the latch is held from dispatch —
+    /// including while the pass queues for a pod-wide compactor permit. Read it
+    /// as "do not pile on", never as "mine is progressing".
+    pub compacting: bool,
+    /// Oldest first, active last. Absent for a `"Sealed"` bucket, whose
+    /// in-memory state is torn down.
+    pub memtables: Option<Vec<MemtableStats>>,
+}
+
+impl From<lancedb::table::BucketStats> for BucketStats {
+    fn from(b: lancedb::table::BucketStats) -> Self {
+        Self {
+            shard_id: b.shard_id,
+            status: b.status,
+            writer_epoch: b.writer_epoch as i64,
+            manifest_version: b.manifest_version as i64,
+            current_generation: b.current_generation as i64,
+            replay_after_wal_entry_position: b.replay_after_wal_entry_position as i64,
+            wal_entry_position_last_seen: b.wal_entry_position_last_seen as i64,
+            generations: b.generations.into_iter().map(Into::into).collect(),
+            compacting: b.compacting,
+            memtables: b
+                .memtables
+                .map(|ms| ms.into_iter().map(Into::into).collect()),
+        }
+    }
+}
+
+/// Live per-bucket LSM state, as returned by `Table#getLsmStats`.
+///
+/// Nothing here is derived: sums and differences (total L0 bytes, WAL lag) are
+/// the caller's to compute.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct LsmStats {
+    /// One entry per bucket backing this table.
+    pub buckets: Vec<BucketStats>,
+}
+
+impl From<lancedb::table::LsmStats> for LsmStats {
+    fn from(stats: lancedb::table::LsmStats) -> Self {
+        Self {
+            buckets: stats.buckets.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
 /// Statistics about a compaction operation.
 #[napi(object)]
 #[derive(Clone, Debug)]
@@ -20,18 +20,16 @@ Do NOT assume local-only table helpers exist on remote tables. If the user asks

 1. Identify the SDK: Python, TypeScript, or both.
 2. Identify the table mode: local/embedded OSS, remote Enterprise/Cloud, or portable across both. If the user says "LanceDB Enterprise", choose the remote table path. If the task involves jobs in any way (listing, inspecting, creating, or canceling jobs), it is always the remote path and requires a remote server connection — see "Connecting to the LanceDB remote server" below before doing anything else.
-3. Read the matching language branch before writing or changing code:
-   - Python patterns: `references/python/patterns.md`
-   - Python API quick reference: `references/python/api_reference.md`
-   - Python performance guidance: `references/python/performance.md`
-   - TypeScript patterns: `references/typescript/patterns.md`
-   - TypeScript API quick reference: `references/typescript/api_reference.md`
-   - TypeScript performance guidance: `references/typescript/performance.md`
+3. Read the matching topic reference before writing or changing code:
   - Column metadata authoring (both SDKs): `references/column_metadata.md`
   - Branch operations (both SDKs): `references/branch_ops.md`
   - Remote server connection resolution (jobs, raw REST): `references/remote_connect.md`
   - Job operations REST API (list/describe/cancel/query_events): `references/remote_jobs.md`
-4. Start with `patterns.md` for the selected SDK. Read `api_reference.md` when choosing method names or return collectors. Read `performance.md` when the task involves ingestion, indexing, filtering, query tuning, diagnostics, or large datasets. Read `column_metadata.md` when the task is documenting, tagging, classifying, or grouping table columns (field descriptions, `lancedb:tag:*` tags, logical column families). Read `branch_ops.md` when the task involves branch lifecycle (list/create/delete), writing to a non-main branch, or verifying a change stayed off main. Read `remote_connect.md` when the task involves jobs or direct REST access to an Enterprise deployment, and `remote_jobs.md` for the job REST methods themselves (list, describe, cancel, query_events).
+
+   There is no bundled per-language guide. For exact method names, signatures, and options, look them up in the canonical sources instead of relying on memory:
+   - Python: `docs/src/python/python.md` (the hand-maintained API reference) and the source under `python/python/lancedb/` when working inside the LanceDB repo; otherwise <https://lancedb.github.io/lancedb/python/python/>.
+   - TypeScript: the generated typedoc under `docs/src/js/` and the source under `nodejs/lancedb/` when working inside the LanceDB repo; otherwise <https://lancedb.github.io/lancedb/js/globals/>.
+4. Apply the SDK invariants in "Per-SDK Invariants" below. Read `column_metadata.md` when the task is documenting, tagging, classifying, or grouping table columns (field descriptions, `lancedb:tag:*` tags, logical column families). Read `branch_ops.md` when the task involves branch lifecycle (list/create/delete), writing to a non-main branch, or verifying a change stayed off main. Read `remote_connect.md` when the task involves jobs or direct REST access to an Enterprise deployment, and `remote_jobs.md` for the job REST methods themselves (list, describe, cancel, query_events).
 5. For Python schemas, favor Pydantic models and validate records before writing. Use PyArrow schemas when Arrow-native, streaming, or highly dynamic data makes them materially better suited.
 6. Prefer `search()` or `query()` builders with explicit `select()` and `limit()` for reads.
 7. Avoid table-level full materialization in remote or portable code. This is the main local-vs-remote read pitfall.
@@ -54,6 +52,23 @@ The unsafe pattern is table-level or unbounded collection, plus local-only datas
 - Python: `table.to_pandas()`, `table.to_arrow()`, `table.to_polars()`; `table.to_lance()` is local/OSS-only dataset access, not materialization
 - TypeScript: `await table.toArrow()`, `await table.query().toArray()` without `limit()`

+## Per-SDK Invariants
+
+Python:
+
+- Result collectors: default to `.to_list()` (plain dicts, no extra dependency) or `.to_arrow()` (PyArrow ships with LanceDB). Use `.to_pandas()` / `.to_polars()` only when the project already declares that dependency — do not assume pandas or polars is installed.
+- Plain scans differ by client: the sync client has no `.query()` method — use `table.search()` with no argument; the async client uses `await async_table.query()`.
+
+TypeScript:
+
+- Collect bounded results with `.toArray()` (objects) or `.toArrow()` (Arrow) after `select()` and `limit()`.
+- For large reads, stream batches instead of collecting: `for await (const batch of table.query().where(...).select(...).limit(...)) { ... }`.
+
+Both SDKs:
+
+- Ingest in bulk or in batches of thousands of rows; never write per-row in a loop — each write creates a version and fragment, slowing ingestion and later queries.
+- Build a vector index once brute-force search is too slow (rule of thumb: beyond roughly 100K vectors locally), and scalar indexes for filtered columns and merge/upsert keys. Use index defaults unless the task states recall/latency requirements.
+
 ## Enterprise: never drop-then-reuse the same table name

 LanceDB Enterprise/Cloud splits a **control plane** (DDL: create/drop/rename) from a **data plane** (query nodes that serve reads). Query nodes cache the resolved dataset for a table name for up to `table_cache_ttl` — **default 300 seconds (5 minutes)**. After you drop or overwrite a table, the control plane updates immediately but the data plane keeps serving the *old* dataset until that cache entry expires. During the window the two planes disagree.
@@ -1,138 +0,0 @@
-# Python API Reference
-
-Quick method reference for Python LanceDB code. Cross-check source for non-trivial claims.
-
-## Connect
-
-If you're connecting to a remote database, use this:
-```python
-import lancedb
-
-db = lancedb.connect("db://my-db", api_key=api_key, host_override=host_override) # remote
-```
-(values may be found in LANCEDB_API_KEY and LANCEDB_HOST_OVERRIDE, either in env vars or a .env file)
-
-If you're connecting to a local table using OSS LanceDB, use this:
-```python
-db = lancedb.connect("./camelot-db") # local/OSS
-```
-If you're not sure which, or if you can't find the api_key or host_override params, ask the user.
-
-**Place the local database directory next to the script/entrypoint that opens it** (i.e. resolve the path relative to the script, `Path(__file__).parent / "camelot-db"`), not buried under a shared `data/` folder. The Lance dataset is the database, not a data file — keeping it beside its code makes ownership obvious and paths stable regardless of the working directory the script is launched from.
-
-**Do not name the directory `lancedb`** (e.g. `./lancedb`, `./data/lancedb`). It collides with the imported `lancedb` package name, which is confusing to read and easy to shadow in scripts. Give it a name derived from the repo or dataset with a clear prefix/suffix — for example `./<dataset>-db`, `./<repo>_lancedb`, or `./vectordb`.
-
-Async:
-
-```python
-db = await lancedb.connect_async("./camelot-db")
-```
-
-## Table Reads
-
-| Task | Preferred API |
-| --- | --- |
-| Vector search | `table.search(query_vector).limit(k)` |
-| Full scan with filters/projection (sync) | `table.search().where(...).select(...).limit(...)` |
-| Full scan with filters/projection (async) | `table.query().where(...).select(...).limit(...)` |
-| Filter | `.where("col > 10")` |
-| Projection | `.select(["id", "text"])` |
-| Bound result count | `.limit(20)` |
-| Collect bounded result as Python objects (default, no extra deps) | `.to_list()` on query/search result |
-| Collect bounded result as Arrow (default, `pyarrow` always available) | `.to_arrow()` on query/search result |
-| Collect bounded result as pandas (only if project uses pandas) | `.to_pandas()` on query/search result |
-| Collect bounded result as Polars (only if project uses polars) | `.to_polars()` on query/search result |
-
-## Sync vs Async Scan API
-
-The plain-scan entry point differs between the sync and async clients. **Verified against `lancedb` 0.34.0** — re-check if the pinned version changes:
-
- **Sync** (`lancedb.connect(...)`): the table has **no `.query()` method**. Use `.search()` with no argument for a plain scan; it returns a query builder that supports `.where()`, `.select()`, `.limit()`, and the `.to_list()` / `.to_arrow()` / `.to_pandas()` / `.to_polars()` collectors.
-  ```python
-  rows = table.search().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
-  ```
- **Async** (`lancedb.connect_async(...)`): the table has **both** `.query()` and `.search()`. Use `.query()` for a plain scan.
-  ```python
-  rows = await async_table.query().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
-  ```
-
-Do not call `table.query()` on a sync table — it raises `AttributeError`.
-
-## Local vs Remote Table Methods
-
-| API | Local table | Remote table | Agent guidance |
-| --- | --- | --- | --- |
-| `table.search(...)` | Yes | Yes | Preferred read path (sync + async) |
-| `table.query()` | Async only | Async only | Sync scan path is `table.search()`; `.query()` is the async scan builder |
-| `table.to_pandas()` | Yes | No / unsafe for portability | Avoid in portable code |
-| `table.to_arrow()` | Yes | No / unsafe for portability | Avoid in portable code |
-| `table.to_polars()` | Yes | No / unsafe for portability | Avoid in portable code |
-| `table.to_lance()` | Yes | No | Local/OSS escape hatch only |
-
-## Indexes
-
-Use `create_index(...)` for vector indexes and modern index configs. Use scalar indexes for filtered or merge keys.
-
-Common calls:
-
-```python
-table.create_index("vector")
-table.create_scalar_index("status")
-table.create_fts_index("text")
-```
-
-Check source docs before specifying advanced index config names or parameters.
-
-## Filtering And Recall Knobs
-
-```python
-table.search(query_vector).where("status = 'ready'")  # pre-filter by default
-table.search(query_vector).where("status = 'ready'", prefilter=False)
-table.search(query_vector).limit(10).refine_factor(20)
-table.search(query_vector).limit(10).nprobes(50)
-```
-
-Use post-filtering only when fewer than `limit` results are acceptable.
-
-## Diagnostics
-
-```python
-print(table.search(query_vector).where("year > 2000").limit(10).analyze_plan())
-print(table.index_stats("vector_idx"))
-```
-
-Use these before changing indexes or search tuning.
-
-## Column (Field) Metadata
-
-```python
-schema = table.schema                       # sync property; async: await table.schema()
-meta = schema.field("category").metadata    # dict[bytes, bytes] — Arrow metadata is bytes-keyed
-res = table.update_field_metadata(          # varargs: one dict per field; works local + remote
-    {"path": "category", "metadata": {"lancedb:description": "...", "lancedb:tag:field_type": "label"}}
-)
-res.version  # new table version
-```
-
-Merges by default; a `None` value deletes that key; `"replace": True` swaps the whole map. Nested fields use dot-paths (`"a.b.c"`). `replace_field_metadata` is deprecated. See `references/column_metadata.md` for key conventions (`lancedb:description`, `lancedb:tag:<name>`, `lancedb:logical-column`) and the authoring workflow.
-
-## Branches
-
-```python
-table.branches.list()                          # non-main branches; {} = only main
-exp = table.branches.create("exp")             # fork off main -> handle scoped to the branch
-wip = table.branches.checkout("wip")           # existing branch -> scoped handle (version= pins read-only)
-wip = db.open_table("t", branch="wip")         # or open scoped directly
-table.branches.delete("stale")                 # removes only the branch pointer
-table.current_branch()                         # None = main
-```
-
-There is no global switch — scoping is per table handle: any read/write on a branch handle lands on that branch; the original handle keeps targeting main. See `references/branch_ops.md` for the model and isolation checks.
-
-## Maintenance
-
-```python
-table.optimize()
-```
-
-Call this after every successful local/OSS ingestion. It handles compaction, cleanup of old versions according to retention, and index optimization. Do not add this for LanceDB Enterprise/Cloud remote tables; Enterprise handles compaction and cleanup automatically from cluster configuration.
@@ -1,173 +0,0 @@
-# Python Patterns
-
-Use these patterns when writing Python code with `lancedb`.
-
-## Before Writing Code
-
-Choose the output type from what the project actually depends on. **Do not assume `pandas` or `polars` is installed** — they are heavy dependencies that many LanceDB projects do not use. `pyarrow`, by contrast, ships as a LanceDB dependency and is always available, so it is a safe default to lean on.
-
-Default output (after applying `select()` and `limit()`):
-
- **Python objects**: `.to_list()` — a list of dicts, no extra dependencies. Prefer this for scripts, examples, and agent-generated code unless there is a reason to do otherwise.
- **PyArrow**: `.to_arrow()` — a `pyarrow.Table`, when the surrounding code is Arrow-native or you need columnar/zero-copy handoff.
-
-Only reach for a DataFrame when the project *already* declares that dependency:
-
- Pandas projects (pandas in `pyproject.toml`/requirements): `.to_pandas()`.
- Polars projects (polars declared): `.to_polars()`.
-
-If unsure, check the dependency manifest or the imports in surrounding files. When in doubt, use `.to_list()` or `.to_arrow()`.
-
-## Schema Design and Validation
-
-Favor `LanceModel` and Pydantic validation for Python schemas. They keep field
-types readable, validate source records before a write, and map directly to a
-LanceDB schema. Use `Vector(dimension)` for fixed-size vectors:
-
-```python
-from lancedb.pydantic import LanceModel, Vector
-
-class Document(LanceModel):
-    id: int
-    text: str
-    vector: Vector(384, nullable=False)
-
-rows = [Document.model_validate(row) for row in source_rows]
-table = db.create_table("documents", schema=Document)
-table.add(rows)
-```
-
-Use PyArrow schemas instead when the pipeline is already Arrow-native, needs
-record-batch streaming, or has runtime schema requirements that would make a
-Pydantic model harder to understand. Declare Pydantic as a direct project
-dependency when application code imports it, even if LanceDB also depends on it.
-
-## Recommended Patterns
-
-### Bounded search or query
-
-Use this for application reads, examples, notebooks, and agent-generated scripts:
-
-```python
-results = (
-    table.search(query_vector)
-    .where("status = 'ready'")
-    .select(["id", "text"])
-    .limit(20)
-    .to_list()  # or .to_arrow(); .to_pandas()/.to_polars() only if the project uses them
-)
-```
-
-Why: `search()` works across local and remote tables and on both the sync and async clients. `select()` avoids fetching unused columns. `limit()` prevents accidental full-table reads. `.to_list()` and `.to_arrow()` avoid assuming pandas/polars is installed (see "Before Writing Code").
-
-For a **plain scan** (no query vector), the entry point differs by client:
-
-```python
-# Sync client: no .query() method — use .search() with no argument.
-rows = table.search().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
-
-# Async client: use .query().
-rows = await async_table.query().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
-```
-
-`table.query()` on a sync table raises `AttributeError` (verified on `lancedb` 0.34.0). See the "Sync vs Async Scan API" section in `api_reference.md`.
-
-### Bounded query result conversion
-
-It is fine to collect bounded query/search results:
-
-```python
-arrow_table = table.search().select(["id"]).limit(100).to_arrow()  # sync plain scan
-rows = table.search(query_vector).limit(10).to_list()
-df = table.search(query_vector).limit(10).to_pandas()  # only if pandas is a project dep
-```
-
-### Local-only Lance dataset API
-
-`table.to_lance()` does not itself materialize the full dataset. It returns the underlying `lance.LanceDataset`, making the table accessible through the PyLance dataset API. Use it when the task is explicitly local/OSS and needs Lance dataset methods not exposed by LanceDB:
-
-```python
-# Local/OSS only: RemoteTable does not expose table.to_lance().
-ds = table.to_lance()
-for batch in ds.to_batches(columns=["id", "text"], batch_size=10_000):
-    process(batch)
-```
-
-### Async Python
-
-Keep the same shape and bound the result before collecting:
-
-```python
-results = await (
-    async_table.query()
-    .where("status = 'ready'")
-    .select(["id", "text"])
-    .limit(20)
-    .to_list()  # or .to_arrow()
-)
-```
-
-## Anti-Patterns
-
-**Avoid the following anti-patterns in your code.**
-
-### Table-level full materialization
-
-Avoid whole-table collectors in portable or large-table code:
-
-```python
-df = table.to_pandas()
-arrow_table = table.to_arrow()
-polars_df = table.to_polars()
-```
-
-Why: local tables expose these whole-table collectors, but remote tables intentionally do not — a remote production table can be far larger than a local development table, so it is easy to accidentally pull the entire table into memory.
-
-`table.to_lance()` is different: it is not a full materialization call, but it is still local/OSS-only and should not appear in code meant to run against remote Enterprise tables.
-
-### Unbounded result collection
-
-Avoid query/search collection without a meaningful limit:
-
-```python
-rows = table.search().to_list()               # unbounded plain scan
-rows = table.search(query_vector).to_list()   # unbounded vector search
-```
-
-Prefer `select(...).limit(...)` before collecting; for large reads, stream in batches instead.
-
-### Per-row writes
-
-Avoid loops that write one row per call:
-
-```python
-for row in rows:
-    table.add([row])  # one commit + fragment per row
-```
-
-Each `add()` creates a new version and fragment. Pass the whole batch in a single call, or chunk very large inputs:
-
-```python
-table.add(rows)  # single commit
-# for very large inputs, add batches of several thousand rows
-```
-
-After the final successful write to an embedded OSS table, call
-`table.optimize()`. Skip this for Enterprise/Cloud tables because their
-maintenance is automatic.
-
-### Drop-then-reuse the same table name (Enterprise/Cloud)
-
-Avoid dropping or overwriting a remote table and then reusing that name right away:
-
-```python
-db.drop_table("my_table")
-table = db.create_table("my_table", data=rows)          # reads 500 for ~5 min
-table = db.create_table("my_table", data=rows, mode="overwrite")  # same problem
-```
-
-Why: Enterprise/Cloud splits DDL (control plane) from query serving (data plane). The data plane caches the dataset behind a table name for up to `table_cache_ttl` (default 300s / 5 min), so after a drop/overwrite the DDL succeeds but queries against the reused name return `500 Internal Server Error` until the cache expires — and a fresh `describe` may still show the old schema. Instead, write to a **fresh name**, use `list_tables()` and fail if it already exists, then `rename_table(fresh, final)` onto the final name only after the old table's drop has propagated (~5 min). See the "Enterprise: never drop-then-reuse the same table name" section in `SKILL.md`. Local/OSS tables have no separate data plane — overwrite freely there.
-
-### Guessing performance fixes
-
-Avoid changing `nprobes`, `refine_factor`, or index types before checking the query plan and index stats. Diagnose first, then tune one knob at a time.
@@ -1,131 +0,0 @@
-# Python Performance Guidance
-
-Use this when writing Python code that ingests data, queries large tables, builds indexes, or investigates latency.
-
-## Ingestion
-
-### Recommended: validate schemas and records with Pydantic
-
-Favor `LanceModel` for readable Python schema definitions and validate source
-records before writing. Use PyArrow directly for Arrow-native or streaming
-pipelines where it is the clearer representation.
-
-```python
-from lancedb.pydantic import LanceModel, Vector
-
-class Document(LanceModel):
-    id: int
-    text: str
-    vector: Vector(384, nullable=False)
-
-rows = [Document.model_validate(row) for row in source_rows]
-table = db.create_table("documents", schema=Document)
-table.add(rows)
-```
-
-### Recommended: bulk ingestion for materialized data
-
-```python
-table.add(arrow_table)
-table.add(df)
-table.add(pa.dataset("data/", format="parquet"))
-```
-
-For very large initial loads, create the table empty first, then call `add(...)`. Passing data directly to `create_table(name, data)` can skip the auto-parallel write path.
-
-### Recommended: iterator ingestion for generated or streamed data
-
-```python
-def batches():
-    for raw in source:
-        vectors = model.encode(raw["text"])
-        yield pa.RecordBatch.from_pydict({**raw, "vector": vectors})
-
-table.add(batches())
-```
-
-Use chunks of several thousand rows or more when practical. Tiny batches and per-row writes create many small fragments.
-
-### Anti-pattern: per-row `add()`
-
-```python
-for row in rows:
-    table.add([row])
-```
-
-Each call creates a version and fragment. This slows ingestion and later queries.
-
-## Indexing
-
- Build a vector index once brute-force vector search becomes too slow. As a rule of thumb, local brute force is fine below roughly 100K vectors; beyond that, build an index.
- Use `IVF_PQ` as the general-purpose default. Enterprise builds this automatically.
- Use scalar indexes for filtered columns and merge/upsert keys.
- Use `BTREE` for mostly distinct numeric/string/temporal columns, `BITMAP` for booleans and low-cardinality columns, and `LABEL_LIST` for list membership queries.
- Keep full-text defaults unless phrase queries require position data.
-
-## Querying
-
-Always be explicit:
-
-```python
-table.search(query_vector).select(["id", "title"]).limit(20)
-```
-
- `select()` reduces bytes read and transferred.
- `limit()` prevents accidental full-table materialization.
- Pre-filtering is the default and guarantees returned rows satisfy the predicate.
- Use post-filtering only when fewer than `limit` results are acceptable.
-
-## Recall Tuning
-
-Tune one knob at a time:
-
- Quantized indexes: raise `refine_factor` to rescore more candidates on full vectors.
- HNSW-backed indexes: raise `ef`; start around `1.5 * k`, increase toward `10 * k` if recall is short.
- IVF candidate breadth: `nprobes` is auto-tuned; override only when a selective pre-filter leaves too few neighbors.
-
-## Maintenance
-
-After every successful embedded OSS/local ingestion, call `table.optimize()`.
-Do not add this to LanceDB Enterprise/Cloud remote table code; remote compaction
-and cleanup are handled automatically based on the Enterprise cluster
-configuration.
-
-Why local maintenance is needed:
-
- Frequent writes can create many small fragments. Queries then need to scan across more files, which can increase latency.
- Updates, deletes, and appends create new table versions. Old versions are retained for time travel and rollback, which can grow disk usage.
- Indexes may have newly added rows that are not yet fully optimized into the index structure.
-
-For local/OSS tables, run `optimize()` after the final successful ingestion
-write. Also run it after later batches of update/delete operations or on a
-regular maintenance schedule:
-
-```python
-table.optimize()
-```
-
-If the user wants more aggressive local disk cleanup, pass a shorter cleanup retention window:
-
-```python
-from datetime import timedelta
-
-table.optimize(cleanup_older_than=timedelta(days=1))
-```
-
-Do not use very short cleanup windows when the application depends on time travel, rollback, or old versions.
-
-## Diagnostics
-
-Before changing code or indexes, inspect:
-
-```python
-print(table.search(query_vector).where("year > 2000").limit(10).analyze_plan())
-print(table.index_stats("vector_idx"))
-```
-
-Look for high scan bytes, missing indexes, fragmented data, and unindexed rows.
-
-## Python Multiprocessing
-
-When using multiprocessing, use `spawn` rather than `fork`. LanceDB is multi-threaded internally, and `fork` plus a multi-threaded process is unsafe.
@@ -1,105 +0,0 @@
-# TypeScript API Reference
-
-Quick method reference for TypeScript LanceDB code. Cross-check source for non-trivial claims.
-
-## Connect
-
-```typescript
-import * as lancedb from "@lancedb/lancedb";
-
-const db = await lancedb.connect("./camelot-db");
-```
-
-**Place the local database directory next to the script/entrypoint that opens it** (resolve the path relative to the module, e.g. via `import.meta.dirname` / `__dirname`), not buried under a shared `data/` folder. The Lance dataset is the database, not a data file — keeping it beside its code makes ownership obvious and paths stable regardless of the working directory the script is launched from.
-
-**Do not name the directory `lancedb`** (e.g. `./lancedb`, `./data/lancedb`). It collides with the imported `lancedb` package/namespace, which is confusing to read. Give it a name derived from the repo or dataset with a clear prefix/suffix — for example `./<dataset>-db`, `./<repo>_lancedb`, or `./vectordb`.
-
-Remote connections use `db://...` plus Enterprise/Cloud credentials and deployment settings. Check current source/docs for exact connection options.
-
-## Table Reads
-
-| Task | Preferred API |
-| --- | --- |
-| Vector search | `table.search(queryVector).limit(k)` |
-| Full scan with filters/projection | `table.query().where(...).select(...).limit(...)` |
-| Filter | `.where("col > 10")` |
-| Projection | `.select(["id", "text"])` |
-| Bound result count | `.limit(20)` |
-| Collect bounded result as objects | `.toArray()` on query/search result |
-| Collect bounded result as Arrow | `.toArrow()` on query/search result |
-| Stream result batches | `for await (const batch of table.query()...)` |
-
-## Local vs Remote Safety
-
-| API | Agent guidance |
-| --- | --- |
-| `table.search(...)` | Preferred read path |
-| `table.query()` | Preferred scan/filter path |
-| `await table.toArrow()` | Avoid in portable or large-table code |
-| `await table.query().toArray()` with no `limit()` | Avoid; unbounded collection |
-| `await table.query().toArrow()` with no `limit()` | Avoid; unbounded collection |
-
-## Indexes
-
-```typescript
-await table.createIndex("vector");
-await table.createIndex("status");
-```
-
-Use vector indexes for large vector search workloads and scalar indexes for filtered columns or merge/upsert keys. Check source/docs before specifying advanced index options.
-
-## Filtering And Recall Knobs
-
-```typescript
-await table.search(queryVector).where("status = 'ready'").limit(10).toArray();
-await table.search(queryVector).limit(10).refineFactor(20).toArray();
-await table.search(queryVector).limit(10).nprobes(50).toArray();
-await table.search(queryVector).limit(10).ef(100).toArray();
-await table.search(queryVector).where("status = 'ready'").postfilter().limit(10).toArray();
-```
-
-Use `postfilter()` only when fewer than `limit` results are acceptable.
-
-## Diagnostics
-
-```typescript
-console.log(await table.search(queryVector).where("year > 2000").limit(10).analyzePlan());
-console.log(await table.indexStats("vector_idx"));
-```
-
-Use these before changing indexes or search tuning.
-
-## Column (Field) Metadata
-
-```typescript
-const schema = await table.schema();
-const meta = schema.fields.find((f) => f.name === "category")?.metadata; // Map<string, string>
-const res = await table.updateFieldMetadata([
-  { path: "category", metadata: { "lancedb:description": "...", "lancedb:tag:field_type": "label" } },
-]);
-res.version; // new table version
-```
-
-Merges by default; a `null` value deletes that key; `replace: true` swaps the whole map. Nested fields use dot-paths (`"a.b.c"`). See `references/column_metadata.md` for key conventions (`lancedb:description`, `lancedb:tag:<name>`, `lancedb:logical-column`) and the authoring workflow.
-
-## Branches
-
-```typescript
-const branches = await table.branches();       // async manager
-await branches.list();                         // non-main branches; {} = only main
-const exp = await branches.create("exp");      // fork off main -> Table scoped to the branch
-const wip = await branches.checkout("wip");    // existing branch -> scoped Table (version arg pins read-only)
-const wip2 = await db.openTable("t", { branch: "wip" }); // or open scoped directly
-await branches.delete("stale");                // removes only the branch pointer
-table.currentBranch();                         // null = main
-```
-
-There is no global switch — scoping is per table handle: any read/write on a branch handle lands on that branch; the original handle keeps targeting main. See `references/branch_ops.md` for the model and isolation checks.
-
-## Maintenance
-
-```typescript
-await table.optimize();
-```
-
-Call this after every successful local/OSS ingestion. It handles compaction, cleanup of old versions according to retention, and index optimization. Do not add this for LanceDB Enterprise/Cloud remote tables; Enterprise handles compaction and cleanup automatically from cluster configuration.
@@ -1,100 +0,0 @@
-# TypeScript Patterns
-
-Use these patterns when writing TypeScript code with `@lancedb/lancedb`.
-
-## Recommended Patterns
-
-### Bounded query
-
-Use this for application reads, scripts, and examples:
-
-```typescript
-const rows = await table
-  .query()
-  .where("status = 'ready'")
-  .select(["id", "text"])
-  .limit(20)
-  .toArray();
-```
-
-### Bounded vector search
-
-```typescript
-const rows = await table
-  .search(queryVector)
-  .select(["id", "text"])
-  .limit(20)
-  .toArray();
-```
-
-### Batch streaming for larger reads
-
-When the task needs many rows, avoid collecting everything at once:
-
-```typescript
-for await (const batch of table
-  .query()
-  .where("status = 'ready'")
-  .select(["id", "text"])
-  .limit(10_000)) {
-  process(batch);
-}
-```
-
-## Anti-Patterns
-
-**Avoid the following anti-patterns in your code.**
-
-### Table-level full materialization
-
-Avoid whole-table collectors in portable or large-table code:
-
-```typescript
-const tableArrow = await table.toArrow();
-```
-
-Why: local tables expose these whole-table collectors, but remote tables intentionally do not — a remote production table can be far larger than a local development table, so it is easy to accidentally pull the entire table into memory.
-
-### Unbounded result collection
-
-Avoid query/search collection without a meaningful limit:
-
-```typescript
-const rows = await table.query().toArray();              // unbounded plain scan
-const rows = await table.search(queryVector).toArray();  // unbounded vector search
-```
-
-Prefer `select(...).limit(...)` before collecting; for large reads, stream in batches instead.
-
-### Per-row writes
-
-Avoid loops that write one row per call:
-
-```typescript
-for (const row of rows) {
-  await table.add([row]); // one commit + fragment per row
-}
-```
-
-Each `add()` creates a new version and fragment. Pass the whole batch in a single call, or chunk very large inputs:
-
-```typescript
-await table.add(rows); // single commit
-// for very large inputs, add in chunks of several thousand rows
-```
-
-### Drop-then-reuse the same table name (Enterprise/Cloud)
-
-Avoid dropping or overwriting a remote table and then reusing that name right away:
-
-```typescript
-await db.dropTable("my_table");
-const table = await db.createTable("my_table", rows);                    // reads 500 for ~5 min
-const table = await db.createTable("my_table", rows, { mode: "overwrite" }); // same problem
-```
-
-Why: Enterprise/Cloud splits DDL (control plane) from query serving (data plane). The data plane caches the dataset behind a table name for up to `table_cache_ttl` (default 300s / 5 min), so after a drop/overwrite the DDL succeeds but queries against the reused name return `500 Internal Server Error` until the cache expires — and a fresh `describe` may still show the old schema. Instead, write to a **fresh name**, use `tableNames()` and fail if it already exists, then `renameTable(fresh, final)` onto the final name only after the old table's drop has propagated (~5 min). See the "Enterprise: never drop-then-reuse the same table name" section in `SKILL.md`. Local/OSS tables have no separate data plane — overwrite freely there.
-
-### Guessing performance fixes
-
-Avoid changing `nprobes`, `refineFactor`, `ef`, or index settings before checking `analyzePlan()` and `indexStats(...)`. Diagnose first, then tune one knob at a time.
@@ -1,78 +0,0 @@
-# TypeScript Performance Guidance
-
-Use this when writing TypeScript code that ingests data, queries large tables, builds indexes, or investigates latency.
-
-## Ingestion
-
- Prefer bulk or batched writes.
- Avoid per-row write loops; they create many small commits/fragments.
- For generated data, accumulate reasonable batches before adding.
- For file-backed data, prefer APIs that stream from Arrow/Parquet-style inputs when available.
-
-## Indexing
-
- Build a vector index once brute-force vector search becomes too slow. As a rule of thumb, local brute force is fine below roughly 100K vectors; beyond that, build an index.
- Use the general-purpose vector index defaults unless the task has explicit recall/latency requirements.
- Build scalar indexes for filtered columns and merge/upsert keys.
- Use full-text index phrase options only when phrase queries require them.
-
-## Querying
-
-Always be explicit:
-
-```typescript
-await table.search(queryVector).select(["id", "title"]).limit(20).toArray();
-```
-
- `select()` reduces bytes read and transferred.
- `limit()` prevents accidental full-table collection.
- Pre-filtering is the default behavior. Use `postfilter()` only when fewer than `limit` results are acceptable.
-
-## Recall Tuning
-
-Tune one knob at a time:
-
- Quantized indexes: raise `refineFactor(...)` to rescore more candidates on full vectors.
- HNSW-backed indexes: raise `ef(...)`; start around `1.5 * k`, increase toward `10 * k` if recall is short.
- IVF candidate breadth: `nprobes(...)` is usually auto-tuned; override only when a selective pre-filter leaves too few neighbors.
-
-## Maintenance
-
-After every successful embedded OSS/local ingestion, call `table.optimize()`.
-Do not add this to LanceDB Enterprise/Cloud remote table code; remote compaction
-and cleanup are handled automatically based on the Enterprise cluster
-configuration.
-
-Why local maintenance is needed:
-
- Frequent writes can create many small fragments. Queries then need to scan across more files, which can increase latency.
- Updates, deletes, and appends create new table versions. Old versions are retained for time travel and rollback, which can grow disk usage.
- Indexes may have newly added rows that are not yet fully optimized into the index structure.
-
-For local/OSS tables, run `optimize()` after the final successful ingestion
-write. Also run it after later batches of update/delete operations or on a
-regular maintenance schedule:
-
-```typescript
-await table.optimize();
-```
-
-If the user wants more aggressive local disk cleanup, pass a shorter cleanup retention window:
-
-```typescript
-const olderThan = new Date(Date.now() - 24 * 60 * 60 * 1000);
-await table.optimize({ cleanupOlderThan: olderThan });
-```
-
-Do not use very short cleanup windows when the application depends on time travel, rollback, or old versions.
-
-## Diagnostics
-
-Before changing code or indexes, inspect:
-
-```typescript
-console.log(await table.search(queryVector).where("year > 2000").limit(10).analyzePlan());
-console.log(await table.indexStats("vector_idx"));
-```
-
-Look for high scan cost, missing indexes, fragmented data, and unindexed rows.
@@ -64,7 +64,9 @@ def scan_python(path: Path, text: str) -> list[Finding]:

 def statement_around(text: str, start: int, end: int) -> str:
    before = max(text.rfind(";", 0, start), text.rfind("\n\n", 0, start))
-    after_candidates = [pos for pos in (text.find(";", end), text.find("\n\n", end)) if pos != -1]
+    after_candidates = [
+        pos for pos in (text.find(";", end), text.find("\n\n", end)) if pos != -1
+    ]
    after = min(after_candidates) if after_candidates else len(text)
    return text[before + 1 : after].strip()

@@ -1,6 +1,6 @@
 [package]
 name = "lancedb-python"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.3"
 publish = false
 edition.workspace = true
 description = "Python bindings for LanceDB"
@@ -15,10 +15,10 @@ name = "_lancedb"
 crate-type = ["cdylib"]

 [dependencies]
-arrow = { version = "58.0.0", features = ["pyarrow"] }
-async-trait = "0.1"
-bytes = "1"
-lancedb = { path = "../rust/lancedb", default-features = false }
+arrow = { workspace = true, features = ["pyarrow"] }
+async-trait.workspace = true
+bytes.workspace = true
+lancedb.workspace = true
 datafusion-common.workspace = true
 lance-core.workspace = true
 lance-namespace.workspace = true
@@ -27,17 +27,17 @@ lance-io.workspace = true
 env_logger.workspace = true
 log.workspace = true
 pyo3 = { version = "0.28", features = ["extension-module", "abi3-py310", "chrono"] }
-chrono = { version = "0.4", default-features = false, features = ["clock"] }
+chrono.workspace = true
 pyo3-async-runtimes = { version = "0.28", features = [
    "attributes",
    "tokio-runtime",
 ] }
-pin-project = "1.1.5"
+pin-project.workspace = true
 futures.workspace = true
-serde = "1"
-serde_json = "1"
+serde.workspace = true
+serde_json.workspace = true
 snafu.workspace = true
-tokio = { version = "1.40", features = ["sync", "rt-multi-thread"] }
+tokio.workspace = true
 libc = "0.2"

 [build-dependencies]
@@ -8,7 +8,7 @@ dependencies = [
    "overrides>=0.7; python_version<'3.12'",
    "packaging>=23.0",
    "pyarrow>=16",
-    "pydantic>=1.10",
+    "pydantic>=2.7.4,<3",
    "tqdm>=4.27.0",
    "lance-namespace>=0.3.2"
 ]
@@ -12,6 +12,7 @@ __version__ = importlib.metadata.version("lancedb")

 from ._lancedb import connect as lancedb_connect
 from ._lancedb import FtsToken
+from ._lancedb import LsmWriteSpec
 from ._lancedb import tokenize as _tokenize
 from .common import URI, sanitize_uri
 from urllib.parse import urlparse
@@ -21,6 +22,16 @@ from .remote.db import RemoteDBConnection
 from .expr import Expr, col, lit, func
 from .schema import blob, vector, BlobType
 from .job import AsyncJob, Job
+from .functions import (
+    FunctionArtifactRequest as FunctionArtifactRequest,
+    FunctionApplication as FunctionApplication,
+    FunctionBinding as FunctionBinding,
+    FunctionRegistrationRequest as FunctionRegistrationRequest,
+    FunctionVersion as FunctionVersion,
+    PythonRuntimeSpec as PythonRuntimeSpec,
+    UdfDefinition as UdfDefinition,
+    udf as udf,
+)
 from .table import AsyncTable, Table
 from .types import BaseTokenizerType
 from ._lancedb import Session
@@ -518,6 +529,7 @@ __all__ = [
    "Job",
    "LanceDBConnection",
    "LanceNamespaceDBConnection",
+    "LsmWriteSpec",
    "RemoteDBConnection",
    "Session",
    "Table",
@@ -147,6 +147,8 @@ class Connection(object):
        limit: Optional[int],
    ) -> list[str]: ...  # Deprecated: Use list_tables instead
    def job(self, job_id: str) -> Job: ...
+    async def create_function_async(self, request_json: str) -> FunctionJob: ...
+    async def get_function(self, name: str, version: str) -> str: ...
    async def list_jobs(self) -> List[JobInfo]: ...
    async def get_job(self, job_id: str) -> Optional[JobDescription]: ...
    async def cancel_job(self, job_id: str) -> bool: ...
@@ -226,6 +228,13 @@ class Job:
    async def wait(self) -> None: ...
    async def cancel(self) -> None: ...

+class FunctionJob:
+    @property
+    def id(self) -> Optional[str]: ...
+    async def status(self) -> str: ...
+    async def wait(self) -> str: ...
+    async def cancel(self) -> None: ...
+
 class JobInfo:
    @property
    def job_id(self) -> str: ...
@@ -341,6 +350,9 @@ class Table:
    async def add_computed_columns(
        self, columns: list[tuple[str, str]]
    ) -> AddColumnsResult: ...
+    async def add_function_columns(
+        self, application_json: str, output_name: Optional[str]
+    ) -> AddColumnsResult: ...
    async def refresh_column(self, column: str) -> RefreshColumnResult: ...
    async def refresh_column_async(self, column: str) -> Job: ...
    async def add_columns_with_schema(self, schema: pa.Schema) -> AddColumnsResult: ...
@@ -45,7 +45,8 @@ from lance_namespace.errors import NamespaceNotEmptyError, TableNotFoundError

 from . import __version__
 from ._lancedb import connect as lancedb_connect  # type: ignore
-from .job import AsyncJob, Job
+from .functions import FunctionVersion, UdfDefinition
+from .job import AsyncJob, Job, _function_job
 from .table import (
    AsyncTable,
    LanceTable,
@@ -616,6 +617,31 @@ class DBConnection(EnforceOverrides):
        """
        raise NotImplementedError("serialize is not supported for this connection type")

+    def create_function(self, definition: UdfDefinition) -> FunctionVersion:
+        """Register a scalar Python UDF and wait for its immutable version.
+
+        This is the blocking counterpart of :meth:`create_function_async`.
+        Local connections raise ``NotImplementedError``.
+        """
+        return self.create_function_async(definition).wait()
+
+    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
+        """Register a scalar Python UDF through the remote Function catalog.
+
+        Submission returns a typed job. The immutable Function version becomes
+        available only when :meth:`Job.wait` succeeds. Local connections raise
+        ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Function catalog operations are not supported for this connection type"
+        )
+
+    def get_function(self, name: str, *, version: str) -> FunctionVersion:
+        """Open one exact immutable Function version from the remote catalog."""
+        raise NotImplementedError(
+            "Function catalog operations are not supported for this connection type"
+        )
+
    def job(self, job_id: str) -> Job:
        """A [Job][lancedb.job.Job] handle for a server-side job by id.

@@ -1256,6 +1282,15 @@ class LanceDBConnection(DBConnection):
        """
        return Job(self._conn.job(job_id))

+    @override
+    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
+        job = LOOP.run(self._conn.create_function_async(definition))
+        return Job(job)
+
+    @override
+    def get_function(self, name: str, *, version: str) -> FunctionVersion:
+        return LOOP.run(self._conn.get_function(name, version=version))
+
    @override
    def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
@@ -2023,6 +2058,25 @@ class AsyncConnection(object):
        """
        return AsyncJob(self._inner.job(job_id))

+    async def create_function_async(
+        self, definition: UdfDefinition
+    ) -> AsyncJob[FunctionVersion]:
+        """Register a scalar Python UDF through the remote Function catalog.
+
+        The returned typed job resolves to the immutable Function version.
+        Local connections raise ``NotImplementedError``.
+        """
+        if not isinstance(definition, UdfDefinition):
+            raise TypeError("create_function_async requires a @udf definition")
+        inner = await self._inner.create_function_async(
+            definition.registration_request.to_canonical_json()
+        )
+        return _function_job(inner)
+
+    async def get_function(self, name: str, *, version: str) -> FunctionVersion:
+        """Open one exact immutable Function version from the remote catalog."""
+        return FunctionVersion.from_json(await self._inner.get_function(name, version))
+
    async def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
        return await self._inner.list_jobs()
@@ -26,7 +26,6 @@ class EmbeddingFunction(BaseModel, ABC):
    3. ndims() which returns the number of dimensions of the vector column
    """

-    __slots__ = ("__weakref__",)  # pydantic 1.x compatibility
    max_retries: int = (
        7  # Setting 0 disables retires. Maybe this should not be enabled by default,
    )
@@ -7,8 +7,7 @@ from functools import cached_property
 from typing import List, Union

 import numpy as np
-
-from lancedb.pydantic import PYDANTIC_VERSION
+from pydantic import ConfigDict

 from ..util import attempt_import_or_raise
 from .base import TextEmbeddingFunction
@@ -67,13 +66,7 @@ class BedRockText(TextEmbeddingFunction):
    source_input_type: str = "search_document"
    query_input_type: str = "search_query"

-    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
-
-        class Config:
-            keep_untouched = (cached_property,)
-    else:
-        model_config = dict()
-        model_config["ignored_types"] = (cached_property,)
+    model_config = ConfigDict(ignored_types=(cached_property,))

    def ndims(self):
        # return len(self._generate_embedding("test"))
@@ -7,8 +7,7 @@ from functools import cached_property
 from typing import List, Optional, Union

 import numpy as np
-
-from lancedb.pydantic import PYDANTIC_VERSION
+from pydantic import ConfigDict

 from ..util import attempt_import_or_raise
 from .base import TextEmbeddingFunction
@@ -87,13 +86,7 @@ class GeminiText(TextEmbeddingFunction):
    query_task_type: str = "retrieval_query"
    source_task_type: str = "retrieval_document"

-    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
-
-        class Config:
-            keep_untouched = (cached_property,)
-    else:
-        model_config = dict()
-        model_config["ignored_types"] = (cached_property,)
+    model_config = ConfigDict(ignored_types=(cached_property,))

    def ndims(self):
        if self.dim:
@@ -7,14 +7,13 @@ from typing import List, Union

 import numpy as np
 import pyarrow as pa
+from pydantic import ConfigDict

 from ..util import attempt_import_or_raise
 from .base import EmbeddingFunction
 from .registry import register
 from .utils import AUDIO, IMAGES, TEXT

-from lancedb.pydantic import PYDANTIC_VERSION
-

@register("imagebind")
 class ImageBindEmbeddings(EmbeddingFunction):
@@ -31,13 +30,7 @@ class ImageBindEmbeddings(EmbeddingFunction):
    device: str = "cpu"
    normalize: bool = False

-    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
-
-        class Config:
-            keep_untouched = (cached_property,)
-    else:
-        model_config = dict()
-        model_config["ignored_types"] = (cached_property,)
+    model_config = ConfigDict(ignored_types=(cached_property,))

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
@@ -7,8 +7,7 @@ from typing import List, Any

 import numpy as np

-from pydantic import PrivateAttr
-from lancedb.pydantic import PYDANTIC_VERSION
+from pydantic import ConfigDict, PrivateAttr

 from ..util import attempt_import_or_raise
 from .base import EmbeddingFunction
@@ -59,13 +58,7 @@ class TransformersEmbeddingFunction(EmbeddingFunction):
        )
        self._model.to(self.device)

-    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
-
-        class Config:
-            keep_untouched = (cached_property,)
-    else:
-        model_config = dict()
-        model_config["ignored_types"] = (cached_property,)
+    model_config = ConfigDict(ignored_types=(cached_property,))

    def ndims(self):
        self._ndims = self._model.config.hidden_size
@@ -0,0 +1,911 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Canonical values exchanged with LanceDB Enterprise Function services.
+
+These immutable models contain client/wire state only. Catalog persistence,
+environment bake, secret resolution, and execution are owned by Sophon.
+"""
+
+from __future__ import annotations
+
+import ast
+import base64
+import functools
+import hashlib
+import inspect
+import json
+import math
+import re
+import sys
+import textwrap
+import types
+from collections.abc import Mapping
+from datetime import date, datetime
+from typing import (
+    Annotated,
+    Any,
+    Callable,
+    Optional,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+    overload,
+)
+
+import pyarrow as pa
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    conint,
+    field_validator,
+    model_validator,
+)
+
+_Int32 = conint(strict=True, ge=-(2**31), le=2**31 - 1)
+_UInt32 = conint(strict=True, ge=0, le=2**32 - 1)
+_UInt64 = conint(strict=True, ge=0, le=2**64 - 1)
+
+
+class _FrozenDict(dict):
+    def _immutable(self, *args, **kwargs):
+        raise TypeError("remote canonical values are immutable")
+
+    __setitem__ = _immutable
+    __delitem__ = _immutable
+    clear = _immutable
+    pop = _immutable
+    popitem = _immutable
+    setdefault = _immutable
+    update = _immutable
+
+    def __ior__(self, other):
+        self._immutable()
+
+
+def _freeze_value(value):
+    if isinstance(value, Mapping):
+        return _FrozenDict({key: _freeze_value(child) for key, child in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze_value(child) for child in value)
+    return value
+
+
+def _validate_literal(value):
+    if isinstance(value, float):
+        raise ValueError(
+            "floating-point Function literals are not part of the Slice 1 "
+            "canonical wire contract"
+        )
+    if isinstance(value, int) and not isinstance(value, bool):
+        if not -(2**63) <= value <= 2**64 - 1:
+            raise ValueError(
+                "Function integer literal is outside the canonical JSON range"
+            )
+    elif isinstance(value, Mapping):
+        for child in value.values():
+            _validate_literal(child)
+    elif isinstance(value, (list, tuple)):
+        for child in value:
+            _validate_literal(child)
+    return value
+
+
+def _known_wire_value(value):
+    if isinstance(value, _RemoteValue):
+        return value._known_dict()
+    if isinstance(value, Mapping):
+        return {key: _known_wire_value(child) for key, child in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_known_wire_value(child) for child in value]
+    return value
+
+
+class _RemoteValue(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    @model_validator(mode="after")
+    def _freeze_mappings(self):
+        for name, value in self.__dict__.items():
+            object.__setattr__(self, name, _freeze_value(value))
+        return self
+
+    @classmethod
+    def from_json(cls, payload: str):
+        return cls.model_validate_json(payload)
+
+    def _known_dict(self) -> dict[str, Any]:
+        known = {}
+        for name, field in self.__class__.model_fields.items():
+            value = getattr(self, name)
+            if value is None:
+                continue
+            if not field.is_required():
+                default_factory = field.default_factory
+                if default_factory is not None and value == default_factory():
+                    continue
+                if default_factory is None and value == field.default:
+                    continue
+            known[name] = _known_wire_value(value)
+        return known
+
+    def _copy(self, *, update: Mapping[str, Any]):
+        update = {name: _freeze_value(value) for name, value in update.items()}
+        return self.model_copy(update=update)
+
+    def to_canonical_json(self) -> str:
+        return json.dumps(
+            self._known_dict(),
+            ensure_ascii=False,
+            allow_nan=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+
+class _OpenRemoteValue(_RemoteValue):
+    """Forward-readable value whose extras stay out of canonical encoding."""
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+    def _unknown_field_names(self) -> set[str]:
+        return set((self.__pydantic_extra__ or {}).keys())
+
+
+class FunctionArtifact(_RemoteValue):
+    """Content-addressed Python artifact identity."""
+
+    kind: str
+    digest: str
+    entrypoint: str
+
+
+class FunctionArtifactContent(_RemoteValue):
+    """Encoded artifact bytes uploaded during remote registration."""
+
+    encoding: str
+    data: str
+
+
+class PythonAdapterSpec(_RemoteValue):
+    """Internal scalar-callable to Arrow-batch adapter selection."""
+
+    kind: str
+    version: _UInt32
+
+
+class FunctionArtifactRequest(_RemoteValue):
+    """Source artifact uploaded while registering a Function."""
+
+    kind: str
+    digest: str
+    entrypoint: str
+    content: FunctionArtifactContent
+    adapter: PythonAdapterSpec
+
+
+class FunctionParameter(_RemoteValue):
+    name: str
+    arrow_type: str
+    nullable: bool
+
+
+class FunctionResultField(_OpenRemoteValue):
+    name: str
+    arrow_type: str
+    nullable: bool
+
+
+class FunctionOutput(_OpenRemoteValue):
+    """Scalar or ordered named-struct output; unknown kinds remain decodable."""
+
+    kind: str
+    arrow_type: Optional[str] = None
+    nullable: Optional[bool] = None
+    fields: tuple[FunctionResultField, ...] = ()
+
+
+class FunctionSignature(_RemoteValue):
+    inputs: tuple[FunctionParameter, ...]
+    output: FunctionOutput
+
+
+class PythonEnvironmentSpec(_RemoteValue):
+    """One Sophon-managed Python environment source."""
+
+    kind: str
+    packages: tuple[str, ...] = ()
+    path: Optional[str] = None
+    modules: tuple[str, ...] = ()
+    image: Optional[str] = None
+
+
+class PythonRuntimeSpec(_RemoteValue):
+    """Remote runtime definition with non-secret environment values.
+
+    V1 supports ``kind="python"``. Newer runtime kinds remain readable, while
+    their unknown payload fields are intentionally not retained by the client.
+    """
+
+    kind: str
+    python_version: Optional[str] = None
+    environment: Optional[PythonEnvironmentSpec] = None
+    env: Optional[Mapping[str, str]] = None
+
+    @model_validator(mode="after")
+    def _validate_runtime_kind(self):
+        if self.kind == "python":
+            if self.python_version is None:
+                raise ValueError("python runtime requires python_version")
+            if self.environment is None:
+                raise ValueError("python runtime requires environment")
+        else:
+            object.__setattr__(self, "python_version", None)
+            object.__setattr__(self, "environment", None)
+            object.__setattr__(self, "env", None)
+        return self
+
+
+class FunctionVersion(_RemoteValue):
+    """An exact immutable Function version returned by Enterprise.
+
+    Scheduling resources, priority, concurrency, and retry policy belong to
+    the submitting Job and are not part of this identity.
+    """
+
+    name: str
+    version: str
+    artifact: FunctionArtifact
+    signature: FunctionSignature
+    runtime: PythonRuntimeSpec
+    runtime_digest: str
+    environment_digest: str
+    required_secrets: tuple[str, ...] = ()
+    created_at: str
+
+
+class FunctionRegistrationRequest(_RemoteValue):
+    """Stable remote registration envelope produced by :func:`udf`.
+
+    Only secret names are represented. Secret values are resolved inside the
+    remote service and have no client request field.
+    """
+
+    name: str
+    artifact: FunctionArtifactRequest
+    signature: FunctionSignature
+    runtime: PythonRuntimeSpec
+    required_secrets: tuple[str, ...] = ()
+
+
+class FunctionVersionRef(_OpenRemoteValue):
+    name: str
+    version: str
+
+
+class ApplicationInput(_OpenRemoteValue):
+    """One parameter value.
+
+    Slice 1 freezes integers, strings, booleans, nulls, arrays, and objects.
+    Floating-point literal encoding is deferred until Python authoring is
+    introduced with a language-neutral numeric representation.
+    """
+
+    parameter: str
+    kind: str
+    value: Any
+
+    @field_validator("value")
+    @classmethod
+    def _validate_value(cls, value):
+        return _validate_literal(value)
+
+
+class FunctionApplication(_OpenRemoteValue):
+    """Immutable pre-declaration application of an exact Function version."""
+
+    function: FunctionVersionRef
+    inputs: tuple[ApplicationInput, ...]
+    output: FunctionOutput
+    group_id: str
+    columns: Mapping[str, str] = Field(default_factory=dict)
+
+    def _known_dict(self) -> dict[str, Any]:
+        value = super()._known_dict()
+        for name in self._unknown_field_names():
+            value.pop(name, None)
+        return value
+
+    def _ensure_declarable(self) -> None:
+        unknown = {f"application.{name}" for name in self._unknown_field_names()}
+        unknown.update(
+            f"function.{name}" for name in self.function._unknown_field_names()
+        )
+        for index, input_value in enumerate(self.inputs):
+            unknown.update(
+                f"inputs[{index}].{name}" for name in input_value._unknown_field_names()
+            )
+        unknown.update(f"output.{name}" for name in self.output._unknown_field_names())
+        for index, field in enumerate(self.output.fields):
+            unknown.update(
+                f"output.fields[{index}].{name}"
+                for name in field._unknown_field_names()
+            )
+        if unknown:
+            raise ValueError(
+                "Function application contains fields from a newer contract: "
+                f"{sorted(unknown)!r}"
+            )
+
+    def rename(self, *, columns: Mapping[str, str]) -> FunctionApplication:
+        """Return a copy with result-field to table-column aliases."""
+        if self.output.kind != "named_struct":
+            raise ValueError("rename(columns=...) requires a named-struct application")
+        result_fields = {field.name for field in self.output.fields}
+        unknown = set(columns) - result_fields
+        if unknown:
+            raise ValueError(f"unknown Function result fields: {sorted(unknown)!r}")
+        merged = dict(self.columns)
+        merged.update(columns)
+        destinations = tuple(
+            merged.get(field.name, field.name) for field in self.output.fields
+        )
+        if len(set(destinations)) != len(destinations):
+            raise ValueError("FunctionApplication rename destinations must be unique")
+        return self._copy(update={"columns": merged})
+
+
+class InputBinding(_RemoteValue):
+    parameter: str
+    field_id: _Int32
+    field_path: str
+    arrow_type: str
+    nullable: bool
+
+
+class OutputMapping(_RemoteValue):
+    """One stable result-field mapping.
+
+    Assignment state is outside the Slice 1 client contract. During the NULL
+    transition Lance exposes no public cell-flag identifier to persist here.
+    """
+
+    result_field: str
+    output_name: str
+    output_field_id: _Int32
+    output_ordinal: _UInt32
+    arrow_type: str
+    nullable: bool
+
+
+class FunctionBinding(_RemoteValue):
+    """Immutable grouped binding persisted by the Enterprise table service."""
+
+    binding_id: str
+    revision: _UInt64
+    function: FunctionVersionRef
+    group_id: str
+    inputs: tuple[InputBinding, ...]
+    outputs: tuple[OutputMapping, ...]
+    input_schema: Optional[Mapping[str, Any]] = None
+    output_schema: Optional[Mapping[str, Any]] = None
+
+
+class RefreshColumnResult(_RemoteValue):
+    """Terminal result of a remote Function-column refresh Job."""
+
+    rows_assigned: _UInt64
+    rows_failed: _UInt64
+    rows_remaining: _UInt64
+    source_version: _UInt64
+    published_version: Optional[_UInt64] = None
+
+    @property
+    def rows_filled(self) -> int:
+        """Deprecated compatibility alias for :attr:`rows_assigned`."""
+        return self.rows_assigned
+
+    @property
+    def version(self) -> Optional[int]:
+        """Deprecated compatibility alias for :attr:`published_version`."""
+        return self.published_version
+
+
+_FUNCTION_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+_SECRET_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _canonical_arrow_type(data_type: pa.DataType) -> str:
+    primitive_types = (
+        (pa.bool_(), "bool"),
+        (pa.int8(), "int8"),
+        (pa.int16(), "int16"),
+        (pa.int32(), "int32"),
+        (pa.int64(), "int64"),
+        (pa.uint8(), "uint8"),
+        (pa.uint16(), "uint16"),
+        (pa.uint32(), "uint32"),
+        (pa.uint64(), "uint64"),
+        (pa.float16(), "float16"),
+        (pa.float32(), "float32"),
+        (pa.float64(), "float64"),
+        (pa.string(), "utf8"),
+        (pa.large_utf8(), "large_utf8"),
+        (pa.binary(), "binary"),
+        (pa.large_binary(), "large_binary"),
+        (pa.date32(), "date32"),
+        (pa.date64(), "date64"),
+    )
+    for candidate, name in primitive_types:
+        if data_type == candidate:
+            return name
+    if pa.types.is_fixed_size_binary(data_type):
+        return f"fixed_size_binary[{data_type.byte_width}]"
+    if pa.types.is_list(data_type):
+        return f"list<{_canonical_arrow_type(data_type.value_type)}>"
+    if pa.types.is_large_list(data_type):
+        return f"large_list<{_canonical_arrow_type(data_type.value_type)}>"
+    if pa.types.is_fixed_size_list(data_type):
+        return (
+            f"fixed_size_list<{_canonical_arrow_type(data_type.value_type)}>"
+            f"[{data_type.list_size}]"
+        )
+    if pa.types.is_struct(data_type):
+        fields = ",".join(
+            f"{field.name}:{_canonical_arrow_type(field.type)}" for field in data_type
+        )
+        return f"struct<{fields}>"
+    if pa.types.is_timestamp(data_type):
+        timezone = f",tz={data_type.tz}" if data_type.tz is not None else ""
+        return f"timestamp[{data_type.unit}{timezone}]"
+    if pa.types.is_time32(data_type) or pa.types.is_time64(data_type):
+        return f"time[{data_type.unit}]"
+    if pa.types.is_duration(data_type):
+        return f"duration[{data_type.unit}]"
+    if pa.types.is_decimal(data_type):
+        bit_width = data_type.bit_width
+        return f"decimal{bit_width}({data_type.precision},{data_type.scale})"
+    raise TypeError(f"unsupported Arrow type for Function signature: {data_type}")
+
+
+def _annotation_type(annotation: Any) -> tuple[pa.DataType, bool]:
+    nullable = False
+    origin = get_origin(annotation)
+    if origin in (Union, types.UnionType):
+        arguments = get_args(annotation)
+        non_none = tuple(
+            argument for argument in arguments if argument is not type(None)
+        )
+        if len(non_none) != 1 or len(non_none) == len(arguments):
+            raise TypeError(f"unsupported union annotation: {annotation!r}")
+        annotation = non_none[0]
+        nullable = True
+
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        base, *metadata = get_args(annotation)
+        arrow_types = [value for value in metadata if isinstance(value, pa.DataType)]
+        if len(arrow_types) != 1:
+            raise TypeError(
+                "Annotated Function types require exactly one PyArrow DataType"
+            )
+        _, base_nullable = _annotation_type(base)
+        return arrow_types[0], nullable or base_nullable
+
+    if isinstance(annotation, pa.DataType):
+        return annotation, nullable
+    if annotation is bool:
+        return pa.bool_(), nullable
+    if annotation is int:
+        return pa.int64(), nullable
+    if annotation is float:
+        return pa.float64(), nullable
+    if annotation is str:
+        return pa.string(), nullable
+    if annotation is bytes:
+        return pa.binary(), nullable
+    if annotation is date:
+        return pa.date32(), nullable
+    if annotation is datetime:
+        return pa.timestamp("us"), nullable
+    if get_origin(annotation) is list:
+        arguments = get_args(annotation)
+        if len(arguments) != 1:
+            raise TypeError(f"unsupported list annotation: {annotation!r}")
+        value_type, value_nullable = _annotation_type(arguments[0])
+        if value_nullable:
+            raise TypeError("nullable Function list elements are not supported")
+        return pa.list_(value_type), nullable
+    raise TypeError(f"unsupported Function annotation: {annotation!r}")
+
+
+def _callable_parameters(function: Callable[..., Any]) -> tuple[inspect.Parameter, ...]:
+    parameters = tuple(inspect.signature(function).parameters.values())
+    for parameter in parameters:
+        if parameter.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            raise TypeError("Function callables require named, non-variadic parameters")
+        if parameter.default is not inspect.Parameter.empty:
+            raise TypeError("Function callable defaults are not supported")
+    return parameters
+
+
+def _function_output(output: pa.DataType | pa.Field | pa.Schema) -> FunctionOutput:
+    if isinstance(output, pa.Schema):
+        fields = tuple(output)
+    elif isinstance(output, pa.Field) and pa.types.is_struct(output.type):
+        if output.nullable:
+            raise ValueError("Function output must be non-nullable")
+        fields = tuple(output.type)
+    elif isinstance(output, pa.DataType) and pa.types.is_struct(output):
+        fields = tuple(output)
+    else:
+        field = (
+            output
+            if isinstance(output, pa.Field)
+            else pa.field("result", output, nullable=False)
+        )
+        if not isinstance(field, pa.Field):
+            raise TypeError(
+                "output_schema must be a PyArrow DataType, Field, or Schema"
+            )
+        if field.nullable:
+            raise ValueError("Function output must be non-nullable")
+        return FunctionOutput(
+            kind="scalar",
+            arrow_type=_canonical_arrow_type(field.type),
+            nullable=False,
+        )
+
+    if not fields:
+        raise ValueError("named-struct Function output must contain at least one field")
+    if any(field.nullable for field in fields):
+        raise ValueError("Function output fields must be non-nullable")
+    names = [field.name for field in fields]
+    if len(set(names)) != len(names):
+        raise ValueError("Function output field names must be unique")
+    return FunctionOutput(
+        kind="named_struct",
+        fields=tuple(
+            FunctionResultField(
+                name=field.name,
+                arrow_type=_canonical_arrow_type(field.type),
+                nullable=False,
+            )
+            for field in fields
+        ),
+    )
+
+
+def _infer_signature(
+    function: Callable[..., Any],
+    input_schema: Optional[pa.Schema],
+    output_schema: Optional[pa.DataType | pa.Field | pa.Schema],
+) -> FunctionSignature:
+    parameters = _callable_parameters(function)
+    if (input_schema is None) != (output_schema is None):
+        raise ValueError("input_schema and output_schema must be provided together")
+
+    if input_schema is not None:
+        if not isinstance(input_schema, pa.Schema):
+            raise TypeError("input_schema must be a PyArrow Schema")
+        expected = tuple(parameter.name for parameter in parameters)
+        actual = tuple(input_schema.names)
+        if actual != expected:
+            raise ValueError(
+                "input_schema fields must exactly match callable parameters in order: "
+                f"expected {expected!r}, got {actual!r}"
+            )
+        inputs = tuple(
+            FunctionParameter(
+                name=field.name,
+                arrow_type=_canonical_arrow_type(field.type),
+                nullable=field.nullable,
+            )
+            for field in input_schema
+        )
+        return FunctionSignature(inputs=inputs, output=_function_output(output_schema))
+
+    try:
+        annotations = get_type_hints(function, include_extras=True)
+    except Exception as error:
+        raise TypeError(f"failed to resolve Function annotations: {error}") from error
+    missing = [
+        parameter.name for parameter in parameters if parameter.name not in annotations
+    ]
+    if missing or "return" not in annotations:
+        names = missing + ([] if "return" in annotations else ["return"])
+        raise TypeError(f"missing Function annotations: {names!r}")
+    inputs = []
+    for parameter in parameters:
+        data_type, nullable = _annotation_type(annotations[parameter.name])
+        inputs.append(
+            FunctionParameter(
+                name=parameter.name,
+                arrow_type=_canonical_arrow_type(data_type),
+                nullable=nullable,
+            )
+        )
+    output_type, output_nullable = _annotation_type(annotations["return"])
+    if output_nullable:
+        raise ValueError("Function output must be non-nullable")
+    return FunctionSignature(
+        inputs=tuple(inputs),
+        output=_function_output(pa.field("result", output_type, nullable=False)),
+    )
+
+
+def _is_udf_decorator(node: ast.expr) -> bool:
+    if isinstance(node, ast.Call):
+        node = node.func
+    return (isinstance(node, ast.Name) and node.id == "udf") or (
+        isinstance(node, ast.Attribute) and node.attr == "udf"
+    )
+
+
+def _literal_source(value: Any) -> str:
+    if value is None or type(value) in (bool, int, str, bytes):
+        return repr(value)
+    if type(value) is float and math.isfinite(value):
+        return repr(value)
+    if type(value) is tuple:
+        children = ", ".join(_literal_source(child) for child in value)
+        if len(value) == 1:
+            children += ","
+        return f"({children})"
+    raise TypeError(
+        "Function source references an unsupported global value of type "
+        f"{type(value).__name__}"
+    )
+
+
+def _package_source(function: Callable[..., Any]) -> bytes:
+    if not inspect.isfunction(function) or inspect.iscoroutinefunction(function):
+        raise TypeError("@udf requires a synchronous Python function")
+    try:
+        source = textwrap.dedent(inspect.getsource(function))
+    except (OSError, TypeError) as error:
+        raise ValueError("@udf requires inspectable Python source") from error
+    module = ast.parse(source)
+    definitions = [
+        node
+        for node in module.body
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and node.name == function.__name__
+    ]
+    if len(definitions) != 1 or not isinstance(definitions[0], ast.FunctionDef):
+        raise ValueError("@udf source must contain exactly one synchronous function")
+    definition = definitions[0]
+    if any(not _is_udf_decorator(decorator) for decorator in definition.decorator_list):
+        raise ValueError("@udf cannot package additional Python decorators")
+    definition.decorator_list = []
+
+    closure = inspect.getclosurevars(function)
+    if closure.nonlocals:
+        raise ValueError("@udf cannot package functions that capture closure values")
+    if closure.unbound:
+        raise ValueError(
+            f"@udf source contains unresolved global names: {sorted(closure.unbound)!r}"
+        )
+    globals_source = []
+    for name, value in sorted(closure.globals.items()):
+        if isinstance(value, types.ModuleType):
+            globals_source.append(f"import {value.__name__} as {name}")
+        else:
+            globals_source.append(f"{name} = {_literal_source(value)}")
+
+    function_source = ast.unparse(definition)
+    parts = ["from __future__ import annotations"]
+    if globals_source:
+        parts.extend(["", *globals_source])
+    parts.extend(["", function_source, ""])
+    return "\n".join(parts).encode("utf-8")
+
+
+class UdfDefinition:
+    """A scalar Python callable prepared for remote Function registration.
+
+    Instances are created with :func:`udf`. Calling an instance executes the
+    original scalar Python function, which keeps local unit testing ordinary.
+    Remote execution adapts that scalar callable to the internal Arrow batch
+    ABI described by the registration artifact.
+    """
+
+    def __init__(
+        self,
+        function: Callable[..., Any],
+        *,
+        name: Optional[str],
+        input_schema: Optional[pa.Schema],
+        output_schema: Optional[pa.DataType | pa.Field | pa.Schema],
+        pip: tuple[str, ...],
+        env: Mapping[str, str],
+        secrets: tuple[str, ...],
+        python_version: Optional[str],
+    ):
+        function_name = name or function.__name__
+        if not _FUNCTION_NAME.fullmatch(function_name):
+            raise ValueError(f"invalid Function name: {function_name!r}")
+        packages = tuple(sorted(set(pip)))
+        if any(not package or package != package.strip() for package in packages):
+            raise ValueError("pip requirements must be non-empty and trimmed")
+        environment = dict(env)
+        if any(
+            not isinstance(key, str) or not isinstance(value, str)
+            for key, value in environment.items()
+        ):
+            raise TypeError("Function env keys and values must be strings")
+        required_secrets = tuple(sorted(set(secrets)))
+        invalid_secrets = [
+            secret for secret in required_secrets if not _SECRET_NAME.fullmatch(secret)
+        ]
+        if invalid_secrets:
+            raise ValueError(f"invalid Function secret names: {invalid_secrets!r}")
+        overlap = set(environment) & set(required_secrets)
+        if overlap:
+            raise ValueError(
+                f"Function env and secret names must be disjoint: {sorted(overlap)!r}"
+            )
+
+        signature = _infer_signature(function, input_schema, output_schema)
+        source = _package_source(function)
+        digest = f"sha256:{hashlib.sha256(source).hexdigest()}"
+        runtime = PythonRuntimeSpec(
+            kind="python",
+            python_version=python_version
+            or f"{sys.version_info.major}.{sys.version_info.minor}",
+            environment=PythonEnvironmentSpec(kind="pip", packages=packages),
+            env=environment,
+        )
+        self._function = function
+        self._request = FunctionRegistrationRequest(
+            name=function_name,
+            artifact=FunctionArtifactRequest(
+                kind="python_callable",
+                digest=digest,
+                entrypoint=function.__name__,
+                content=FunctionArtifactContent(
+                    encoding="base64",
+                    data=base64.b64encode(source).decode("ascii"),
+                ),
+                adapter=PythonAdapterSpec(
+                    kind="scalar_to_arrow_batch",
+                    version=1,
+                ),
+            ),
+            signature=signature,
+            runtime=runtime,
+            required_secrets=required_secrets,
+        )
+        functools.update_wrapper(self, function)
+
+    @property
+    def registration_request(self) -> FunctionRegistrationRequest:
+        """The immutable request sent by ``create_function_async``."""
+        return self._request
+
+    def __call__(self, *args, **kwargs):
+        return self._function(*args, **kwargs)
+
+
+@overload
+def udf(function: Callable[..., Any]) -> UdfDefinition: ...
+
+
+@overload
+def udf(
+    function: None = None,
+    *,
+    name: Optional[str] = None,
+    input_schema: Optional[pa.Schema] = None,
+    output_schema: Optional[pa.DataType | pa.Field | pa.Schema] = None,
+    pip: tuple[str, ...] | list[str] = (),
+    env: Optional[Mapping[str, str]] = None,
+    secrets: tuple[str, ...] | list[str] = (),
+    python_version: Optional[str] = None,
+) -> Callable[[Callable[..., Any]], UdfDefinition]: ...
+
+
+def udf(
+    function: Optional[Callable[..., Any]] = None,
+    *,
+    name: Optional[str] = None,
+    input_schema: Optional[pa.Schema] = None,
+    output_schema: Optional[pa.DataType | pa.Field | pa.Schema] = None,
+    pip: tuple[str, ...] | list[str] = (),
+    env: Optional[Mapping[str, str]] = None,
+    secrets: tuple[str, ...] | list[str] = (),
+    python_version: Optional[str] = None,
+):
+    """Prepare a scalar Python callable for remote Function registration.
+
+    Input and output signatures are inferred from supported annotations. For
+    Arrow types annotations cannot express precisely, pass ``input_schema``
+    and ``output_schema`` together. Nullable outputs are rejected because V1
+    uses physical NULL to represent unassigned computed-column rows.
+
+    Parameters
+    ----------
+    function : Callable, optional
+        The synchronous scalar callable to package.
+    name : str, optional
+        The remote Function name. Defaults to the callable name.
+    input_schema : pyarrow.Schema, optional
+        Explicit input fields in the exact order of the callable parameters.
+        Must be provided together with ``output_schema``.
+    output_schema : pyarrow.DataType, pyarrow.Field, or pyarrow.Schema, optional
+        Explicit scalar or named-struct output. Must be non-nullable and be
+        provided together with ``input_schema``.
+    pip : sequence of str, optional
+        Pip requirements for the remote environment.
+    env : mapping of str to str, optional
+        Non-secret environment variables. Use ``secrets`` for credentials.
+    secrets : sequence of str, optional
+        Names of secrets resolved by the remote service. Secret values are not
+        accepted by this API or included in the registration request.
+    python_version : str, optional
+        Remote Python major/minor version. Defaults to the client version.
+
+    Returns
+    -------
+    UdfDefinition
+        A callable definition accepted by
+        :meth:`lancedb.db.DBConnection.create_function`,
+        :meth:`lancedb.db.AsyncConnection.create_function_async` and
+        :meth:`lancedb.db.DBConnection.create_function_async`.
+
+    Examples
+    --------
+    >>> from lancedb import udf
+    >>> @udf(pip=["numpy==2.2.0"], secrets=["MODEL_TOKEN"])
+    ... def score(value: float) -> float:
+    ...     return value * 2
+    >>> score(1.5)
+    3.0
+    """
+
+    def decorate(target: Callable[..., Any]) -> UdfDefinition:
+        return UdfDefinition(
+            target,
+            name=name,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            pip=tuple(pip),
+            env={} if env is None else env,
+            secrets=tuple(secrets),
+            python_version=python_version,
+        )
+
+    if function is None:
+        return decorate
+    return decorate(function)
+
+
+__all__ = [
+    "ApplicationInput",
+    "FunctionApplication",
+    "FunctionArtifact",
+    "FunctionArtifactContent",
+    "FunctionArtifactRequest",
+    "FunctionBinding",
+    "FunctionOutput",
+    "FunctionParameter",
+    "FunctionRegistrationRequest",
+    "FunctionResultField",
+    "FunctionSignature",
+    "FunctionVersion",
+    "FunctionVersionRef",
+    "InputBinding",
+    "OutputMapping",
+    "PythonEnvironmentSpec",
+    "PythonAdapterSpec",
+    "PythonRuntimeSpec",
+    "RefreshColumnResult",
+    "UdfDefinition",
+    "udf",
+]
@@ -5,20 +5,23 @@

 import asyncio
 from datetime import timedelta
-from typing import Optional
+from typing import Any, Generic, Optional, TypeVar, cast

 from lancedb.background_loop import LOOP

 from . import _lancedb
+from .functions import FunctionVersion
+
+T = TypeVar("T")


-class AsyncJob:
+class AsyncJob(Generic[T]):
    """A handle to an operation that may still be running.

    The operation may already be complete when the handle is created.
    """

-    def __init__(self, inner: Optional["_lancedb.Job"]):
+    def __init__(self, inner: Optional[Any]):
        self._inner = inner

    @property
@@ -44,18 +47,20 @@ class AsyncJob:
            return "finished"
        return await self._inner.status()

-    async def wait(self, timeout: Optional[timedelta] = None):
+    async def wait(self, timeout: Optional[timedelta] = None) -> T:
        """Wait until the operation reaches a terminal state.

        Raises `JobFailedError` if the operation failed, `JobCancelledError`
        if it was cancelled, and `TimeoutError` if `timeout` elapses first.
        """
        if self._inner is None:
-            return
+            return cast(T, None)
        if timeout is None:
-            await self._inner.wait()
-        else:
-            await asyncio.wait_for(self._inner.wait(), timeout.total_seconds())
+            return cast(T, await self._inner.wait())
+        return cast(
+            T,
+            await asyncio.wait_for(self._inner.wait(), timeout.total_seconds()),
+        )

    async def cancel(self):
        """Request cancellation. Cancelling a finished operation is a no-op."""
@@ -64,10 +69,10 @@ class AsyncJob:
        await self._inner.cancel()


-class Job:
+class Job(Generic[T]):
    """Synchronous counterpart of `AsyncJob`."""

-    def __init__(self, inner: Optional[AsyncJob]):
+    def __init__(self, inner: Optional[AsyncJob[T]]):
        self._inner = inner

    @property
@@ -88,18 +93,40 @@ class Job:
            return "finished"
        return LOOP.run(self._inner.status())

-    def wait(self, timeout: Optional[timedelta] = None):
+    def wait(self, timeout: Optional[timedelta] = None) -> T:
        """Block until the operation reaches a terminal state.

        Raises `JobFailedError` if the operation failed, `JobCancelledError`
        if it was cancelled, and `TimeoutError` if `timeout` elapses first.
        """
        if self._inner is None:
-            return
-        LOOP.run(self._inner.wait(timeout))
+            return cast(T, None)
+        return LOOP.run(self._inner.wait(timeout))

    def cancel(self):
        """Request cancellation. Cancelling a finished operation is a no-op."""
        if self._inner is None:
            return
        LOOP.run(self._inner.cancel())
+
+
+class _FunctionJobAdapter:
+    def __init__(self, inner: "_lancedb.FunctionJob"):
+        self._inner = inner
+
+    @property
+    def id(self) -> Optional[str]:
+        return self._inner.id
+
+    async def status(self) -> str:
+        return await self._inner.status()
+
+    async def wait(self) -> FunctionVersion:
+        return FunctionVersion.from_json(await self._inner.wait())
+
+    async def cancel(self):
+        await self._inner.cancel()
+
+
+def _function_job(inner: "_lancedb.FunctionJob") -> AsyncJob[FunctionVersion]:
+    return AsyncJob(_FunctionJobAdapter(inner))
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright The LanceDB Authors

-"""Pydantic (v1 / v2) adapter for LanceDB"""
+"""Pydantic adapter for LanceDB."""

 from __future__ import annotations

@@ -14,9 +14,6 @@ from enum import Enum
 from typing import (
    TYPE_CHECKING,
    Any,
-    Callable,
-    Dict,
-    Generator,
    List,
    Type,
    Union,
@@ -24,17 +21,9 @@ from typing import (
    GenericAlias,
 )

-import numpy as np
 import pyarrow as pa
 import pydantic
-from packaging.version import Version
-
-PYDANTIC_VERSION = Version(pydantic.__version__)
-try:
-    from pydantic_core import CoreSchema, core_schema
-except ImportError:
-    if PYDANTIC_VERSION.major >= 2:
-        raise
+from pydantic_core import CoreSchema, core_schema

 if TYPE_CHECKING:
    from pydantic.fields import FieldInfo
@@ -131,25 +120,6 @@ def Vector(
                ),
            )

-        @classmethod
-        def __get_validators__(cls) -> Generator[Callable, None, None]:
-            yield cls.validate
-
-        # For pydantic v1
-        @classmethod
-        def validate(cls, v):
-            if not isinstance(v, (list, range, np.ndarray)) or len(v) != dim:
-                raise TypeError("A list of numbers or numpy.ndarray is needed")
-            return cls(v)
-
-        if PYDANTIC_VERSION.major < 2:
-
-            @classmethod
-            def __modify_schema__(cls, field_schema: Dict[str, Any]):
-                field_schema["items"] = {"type": "number"}
-                field_schema["maxItems"] = dim
-                field_schema["minItems"] = dim
-
    return FixedSizeList


@@ -157,9 +127,8 @@ def _raise_bare_vector_error(*_args):
    raise TypeError("Vector must be parameterized with a dimension, e.g. Vector(128).")


-# Pydantic v1 and v2 otherwise treat the bare Vector factory as a field validator
-# and inspect its signature, which produces misleading errors about internal types.
-setattr(Vector, "__get_validators__", _raise_bare_vector_error)
+# Pydantic otherwise inspects the bare factory as a field type and produces
+# misleading errors about its internal annotations.
 setattr(Vector, "__get_pydantic_core_schema__", _raise_bare_vector_error)


@@ -233,31 +202,6 @@ def MultiVector(
                ),
            )

-        @classmethod
-        def __get_validators__(cls) -> Generator[Callable, None, None]:
-            yield cls.validate
-
-        # For pydantic v1
-        @classmethod
-        def validate(cls, v):
-            if not isinstance(v, (list, range)):
-                raise TypeError("A list of vectors is needed")
-            for vec in v:
-                if not isinstance(vec, (list, range, np.ndarray)) or len(vec) != dim:
-                    raise TypeError(f"Each vector must be a list of {dim} numbers")
-            return cls(v)
-
-        if PYDANTIC_VERSION.major < 2:
-
-            @classmethod
-            def __modify_schema__(cls, field_schema: Dict[str, Any]):
-                field_schema["items"] = {
-                    "type": "array",
-                    "items": {"type": "number"},
-                    "minItems": dim,
-                    "maxItems": dim,
-                }
-
    return MultiVectorList


@@ -303,20 +247,10 @@ def _py_type_to_arrow_type(py_type: Type[Any], field: FieldInfo) -> pa.DataType:
    )


-if PYDANTIC_VERSION.major < 2:
-
-    def _pydantic_model_to_fields(model: pydantic.BaseModel) -> List[pa.Field]:
-        return [
-            _pydantic_to_field(name, field) for name, field in model.__fields__.items()
-        ]
-
-else:
-
-    def _pydantic_model_to_fields(model: pydantic.BaseModel) -> List[pa.Field]:
-        return [
-            _pydantic_to_field(name, field)
-            for name, field in model.model_fields.items()
-        ]
+def _pydantic_model_to_fields(model: pydantic.BaseModel) -> List[pa.Field]:
+    return [
+        _pydantic_to_field(name, field) for name, field in model.model_fields.items()
+    ]


 def _pydantic_type_to_arrow_type(tp: Any, field: FieldInfo) -> pa.DataType:
@@ -509,8 +443,6 @@ class LanceModel(pydantic.BaseModel):

    @classmethod
    def safe_get_fields(cls):
-        if PYDANTIC_VERSION.major < 2:
-            return cls.__fields__
        return cls.model_fields

    @classmethod
@@ -548,23 +480,9 @@ def get_extras(field_info: FieldInfo, key: str) -> Any:
    """
    Get the extra metadata from a Pydantic FieldInfo.
    """
-    if PYDANTIC_VERSION.major >= 2:
-        return (field_info.json_schema_extra or {}).get(key)
-    return (field_info.field_info.extra or {}).get("json_schema_extra", {}).get(key)
+    return (field_info.json_schema_extra or {}).get(key)


-if PYDANTIC_VERSION.major < 2:
-
-    def model_to_dict(model: pydantic.BaseModel) -> Dict[str, Any]:
-        """
-        Convert a Pydantic model to a dictionary.
-        """
-        return model.dict()
-
-else:
-
-    def model_to_dict(model: pydantic.BaseModel) -> Dict[str, Any]:
-        """
-        Convert a Pydantic model to a dictionary.
-        """
-        return model.model_dump()
+def model_to_dict(model: pydantic.BaseModel) -> dict[str, Any]:
+    """Convert a Pydantic model to a dictionary."""
+    return model.model_dump()
@@ -32,8 +32,6 @@ from typing_extensions import Annotated

 from lancedb._lancedb import fts_query_to_json
 from lancedb.background_loop import LOOP
-from lancedb.pydantic import PYDANTIC_VERSION
-
 from . import __version__
 from .arrow import AsyncRecordBatchReader
 from .dependencies import pandas as pd
@@ -827,12 +825,7 @@ class Query(pydantic.BaseModel):

    # This tells pydantic to allow custom types (needed for the `vector` query since
    # pa.Array wouln't be allowed otherwise)
-    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
-
-        class Config:
-            arbitrary_types_allowed = True
-    else:
-        model_config = {"arbitrary_types_allowed": True}
+    model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)


 class LanceQueryBuilder(ABC):
@@ -2235,6 +2228,7 @@ class LanceHybridQueryBuilder(LanceQueryBuilder):
            reranker=self._reranker,
            limit=self._limit,
            with_row_ids=True,
+            offset=self._offset,
        )
        return self._finish_hybrid_results(results)

@@ -2256,6 +2250,7 @@ class LanceHybridQueryBuilder(LanceQueryBuilder):
        reranker,
        limit: int,
        with_row_ids: bool,
+        offset: Optional[int] = None,
    ) -> pa.Table:
        if norm == "rank":
            vector_results = LanceHybridQueryBuilder._rank(vector_results, "_distance")
@@ -2332,7 +2327,7 @@ class LanceHybridQueryBuilder(LanceQueryBuilder):
            score_i = results.column_names.index("_score")
            results = results.set_column(score_i, "_score", original_scores)

-        results = results.slice(length=limit)
+        results = results.slice(offset=offset or 0, length=limit)

        if not with_row_ids:
            results = results.drop(["_rowid"])
@@ -2679,8 +2674,12 @@ class LanceHybridQueryBuilder(LanceQueryBuilder):

        # Apply common configurations
        if self._limit:
-            self._vector_query.limit(self._limit)
-            self._fts_query.limit(self._limit)
+            # The final offset/limit window is sliced out of the combined,
+            # reranked results, so each sub-query must fetch enough rows to
+            # cover the skipped prefix as well as the window itself.
+            sub_query_limit = self._limit + (self._offset or 0)
+            self._vector_query.limit(sub_query_limit)
+            self._fts_query.limit(sub_query_limit)
        if self._columns:
            self._vector_query.select(self._columns)
            self._fts_query.select(self._columns)
@@ -3245,12 +3244,7 @@ class AsyncStandardQuery(AsyncQueryBase):
        if ordering is None:
            self._inner.order_by(None)
        else:
-            self._inner.order_by(
-                [
-                    o.model_dump() if hasattr(o, "model_dump") else o.dict()
-                    for o in ordering
-                ]
-            )
+            self._inner.order_by([o.model_dump() for o in ordering])
        return self

    def fast_search(self) -> Self:
@@ -23,6 +23,7 @@ import pyarrow as pa

 from ..common import DATA
 from ..db import DBConnection, LOOP
+from ..functions import FunctionVersion, UdfDefinition
 from ..job import AsyncJob, Job

 if TYPE_CHECKING:
@@ -713,6 +714,14 @@ class RemoteDBConnection(DBConnection):
        """
        return Job(self._conn.job(job_id))

+    @override
+    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
+        return Job(LOOP.run(self._conn.create_function_async(definition)))
+
+    @override
+    def get_function(self, name: str, *, version: str) -> FunctionVersion:
+        return LOOP.run(self._conn.get_function(name, version=version))
+
    @override
    def list_jobs(self) -> List["JobInfo"]:
        """List server-side jobs across the database's tables."""
@@ -49,6 +49,7 @@ from lancedb.index import (
    LabelList,
 )
 from lancedb.job import Job
+from lancedb.functions import FunctionApplication
 from lancedb.remote.db import LOOP
 from lancedb.table import IndexConfigType, KNOWN_METRICS
 import pyarrow as pa
@@ -960,7 +961,9 @@ class RemoteTable(Table):

    def add_columns(
        self,
-        transforms: Dict[str, str] | None = None,
+        transforms: Dict[str, str | FunctionApplication]
+        | FunctionApplication
+        | None = None,
        *,
        computed: Dict[str, str] | None = None,
    ) -> AddColumnsResult:
@@ -990,17 +993,39 @@ class RemoteTable(Table):
        return LOOP.run(self._table.set_unenforced_primary_key(columns))

    def set_lsm_write_spec(self, spec: "LsmWriteSpec") -> None:
-        """Not supported on LanceDB Cloud."""
+        """Install an LsmWriteSpec."""
        return LOOP.run(self._table.set_lsm_write_spec(spec))

    def unset_lsm_write_spec(self) -> None:
-        """Not supported on LanceDB Cloud."""
+        """Remove the LsmWriteSpec."""
        return LOOP.run(self._table.unset_lsm_write_spec())

    def get_lsm_write_spec(self) -> Optional["LsmWriteSpec"]:
        """Read the installed LsmWriteSpec, or ``None``."""
        return LOOP.run(self._table.get_lsm_write_spec())

+    def checkpoint_lsm(self) -> None:
+        """Synchronous version of
+        [`AsyncTable.checkpoint_lsm`][lancedb.AsyncTable.checkpoint_lsm]."""
+        return LOOP.run(self._table.checkpoint_lsm())
+
+    def flush_lsm(self) -> None:
+        """Synchronous version of
+        [`AsyncTable.flush_lsm`][lancedb.AsyncTable.flush_lsm]."""
+        return LOOP.run(self._table.flush_lsm())
+
+    def compact_lsm(self) -> None:
+        """Synchronous version of
+        [`AsyncTable.compact_lsm`][lancedb.AsyncTable.compact_lsm]."""
+        return LOOP.run(self._table.compact_lsm())
+
+    def get_lsm_stats(self, *, include_generation_rows: bool = False) -> Optional[dict]:
+        """Synchronous version of
+        [`AsyncTable.get_lsm_stats`][lancedb.AsyncTable.get_lsm_stats]."""
+        return LOOP.run(
+            self._table.get_lsm_stats(include_generation_rows=include_generation_rows)
+        )
+
    def close_lsm_writers(self) -> None:
        """No-op on LanceDB Cloud (no local shard writers)."""
        return LOOP.run(self._table.close_lsm_writers())
@@ -72,6 +72,7 @@ from .index import (
    FTS,
 )
 from .expr import Expr
+from .functions import FunctionApplication
 from .merge import LanceMergeInsertBuilder
 from .pydantic import LanceModel, model_to_dict
 from .query import (
@@ -433,6 +434,20 @@ def _cast_to_target_schema(
    return pa.RecordBatchReader.from_batches(reordered_schema, gen())


+def _field_extension_name(field: pa.Field) -> Optional[str]:
+    extension_name = getattr(field.type, "extension_name", None)
+    if extension_name is not None:
+        return extension_name
+
+    metadata = field.metadata or {}
+    extension_name = metadata.get(b"ARROW:extension:name") or metadata.get(
+        "ARROW:extension:name"
+    )
+    if isinstance(extension_name, bytes):
+        return extension_name.decode()
+    return extension_name
+
+
 def _align_field_types(
    fields: List[pa.Field],
    target_fields: List[pa.Field],
@@ -445,6 +460,16 @@ def _align_field_types(
        target_field = next((f for f in target_fields if f.name == field.name), None)
        if target_field is None:
            raise ValueError(f"Field '{field.name}' not found in target schema")
+        # Preserve arrow.json input until it reaches Lance. LanceDB exposes stored
+        # JSON columns as lance.json (JSONB-backed LargeBinary), but casting the
+        # input to that storage type here merely relabels the raw JSON bytes as
+        # JSONB. Lance must see arrow.json so it can perform the JSONB encoding.
+        if (
+            _field_extension_name(field) == "arrow.json"
+            and _field_extension_name(target_field) == "lance.json"
+        ):
+            new_fields.append(field)
+            continue
        if pa.types.is_struct(target_field.type):
            if pa.types.is_struct(field.type):
                new_type = pa.struct(
@@ -1918,7 +1943,8 @@ class Table(ABC):
    @abstractmethod
    def add_columns(
        self,
-        transforms: Dict[str, str]
+        transforms: Dict[str, str | FunctionApplication]
+        | FunctionApplication
        | pa.Field
        | List[pa.Field]
        | pa.Schema
@@ -1931,13 +1957,21 @@ class Table(ABC):

        Parameters
        ----------
-        transforms: Dict[str, str], pa.Field, List[pa.Field], pa.Schema
+        transforms: Dict[str, str | FunctionApplication], FunctionApplication,
+            pa.Field, List[pa.Field], pa.Schema
            A map of column name to a SQL expression to use to calculate the
            value of the new column. These expressions will be evaluated for
            each row in the table, and can reference existing columns.
            Alternatively, a pyarrow Field or Schema can be provided to add
            new columns with the specified data types. The new columns will
            be initialized with null values.
+
+            A mapping with one ``FunctionApplication`` value keeps its scalar
+            or named-struct result in the named table column. A bare
+            named-struct application expands its ordered result fields as one
+            atomic sibling group; aliases come from ``rename(columns=...)``.
+            Function columns are supported only on LanceDB Cloud and
+            Enterprise.
        computed: Dict[str, str], optional
            A map of column name to a SQL expression defining the column. The
            column's type and inputs are derived from the expression, so no
@@ -4032,9 +4066,10 @@ class LanceTable(Table):

    def add_columns(
        self,
-        transforms: Dict[str, str]
-        | pa.field
-        | List[pa.field]
+        transforms: Dict[str, str | FunctionApplication]
+        | FunctionApplication
+        | pa.Field
+        | List[pa.Field]
        | pa.Schema
        | None = None,
        *,
@@ -4801,7 +4836,7 @@ class AsyncTable:

        Examples
        --------
-        >>> from lancedb._lancedb import LsmWriteSpec
+        >>> from lancedb import LsmWriteSpec
        >>> # table.set_unenforced_primary_key("id")
        >>> # table.set_lsm_write_spec(LsmWriteSpec.bucket("id", 16))
        """
@@ -4846,7 +4881,7 @@ class AsyncTable:
        ``asyncio.wait_for`` for a wall-clock bound; abandoning it partway
        costs nothing.
        """
-        return await self._inner.checkpoint_lsm()
+        await self._inner.checkpoint_lsm()

    async def flush_lsm(self) -> None:
        """Seal every bucket's active memtable into L0.
@@ -4855,7 +4890,7 @@ class AsyncTable:
        `compact_lsm`. On a node that has not claimed this table, this claims
        it and replays its WAL log first.
        """
-        return await self._inner.flush_lsm()
+        await self._inner.flush_lsm()

    async def compact_lsm(self) -> None:
        """Trigger a background L0 to base compaction pass per bucket.
@@ -4864,7 +4899,7 @@ class AsyncTable:
        ``get_lsm_stats`` for progress, or use ``checkpoint_lsm`` to loop
        until the current L0 has reached base.
        """
-        return await self._inner.compact_lsm()
+        await self._inner.compact_lsm()

    async def get_lsm_stats(
        self, *, include_generation_rows: bool = False
@@ -5968,9 +6003,10 @@ class AsyncTable:

    async def add_columns(
        self,
-        transforms: dict[str, str]
-        | pa.field
-        | List[pa.field]
+        transforms: dict[str, str | FunctionApplication]
+        | FunctionApplication
+        | pa.Field
+        | List[pa.Field]
        | pa.Schema
        | None = None,
        *,
@@ -5981,12 +6017,19 @@ class AsyncTable:

        Parameters
        ----------
-        transforms: Dict[str, str]
+        transforms: Dict[str, str | FunctionApplication] or FunctionApplication
            A map of column name to a SQL expression to use to calculate the
            value of the new column. These expressions will be evaluated for
            each row in the table, and can reference existing columns.
            Alternatively, you can pass a pyarrow field or schema to add
            new columns with NULLs.
+
+            A mapping with one ``FunctionApplication`` value keeps its scalar
+            or named-struct result in the named table column. A bare
+            named-struct application expands its ordered result fields as one
+            atomic sibling group; aliases come from ``rename(columns=...)``.
+            Function columns are supported only on LanceDB Cloud and
+            Enterprise.
        computed: Dict[str, str], optional
            A map of column name to a SQL expression defining the column. The
            column's type and inputs are derived from the expression.
@@ -6010,6 +6053,32 @@ class AsyncTable:
            version: the new version number of the table after adding columns.

        """
+        function_application = None
+        function_output_name = None
+        if isinstance(transforms, FunctionApplication):
+            function_application = transforms
+        elif isinstance(transforms, dict) and any(
+            isinstance(value, FunctionApplication) for value in transforms.values()
+        ):
+            if len(transforms) != 1 or not all(
+                isinstance(value, FunctionApplication) for value in transforms.values()
+            ):
+                raise ValueError(
+                    "one add_columns call declares exactly one Function sibling group"
+                )
+            function_output_name, function_application = next(iter(transforms.items()))
+
+        if function_application is not None:
+            if computed:
+                raise ValueError(
+                    "add_columns cannot mix a Function application with SQL "
+                    "computed columns"
+                )
+            function_application._ensure_declarable()
+            return await self._inner.add_function_columns(
+                function_application.to_canonical_json(), function_output_name
+            )
+
        if isinstance(transforms, pa.Field):
            transforms = [transforms]
        if isinstance(transforms, list) and all(
@@ -632,3 +632,101 @@ class TestExprBytesIntegration:
            .to_arrow()
        )
        assert result.num_rows == 2
+
+
+# ── datetime / timezone integration for lit() (issue #3262) ──────────────────
+
+
+class TestExprDatetimeTimezoneIntegration:
+    """Integration coverage for lit(datetime) against table timestamp columns.
+
+    PyArrow stores naive timestamps as UTC wall-clock microseconds. Python's
+    datetime.timestamp() treats naive values as *local* time, which used to
+    shift lit(naive) by the host UTC offset and break equality filters on
+    non-UTC machines. These cases lock the expected semantics.
+    """
+
+    def test_both_naive_match(self, tmp_path):
+        """Table naive + lit naive with the same wall clock must match."""
+        db = lancedb.connect(str(tmp_path / "naive"))
+        ts = datetime(2024, 7, 1, 10, 0, 0)
+        table = db.create_table(
+            "t", [{"id": 1, "ts": ts}, {"id": 2, "ts": datetime(2024, 7, 2, 10, 0, 0)}]
+        )
+        result = table.search().where(col("ts") == lit(ts)).to_list()
+        assert len(result) == 1
+        assert result[0]["id"] == 1
+
+    def test_both_same_timezone_match(self, tmp_path):
+        """Table UTC + lit UTC for the same instant must match."""
+        db = lancedb.connect(str(tmp_path / "utc"))
+        ts = datetime(2024, 7, 1, 10, 0, 0, tzinfo=timezone.utc)
+        table = db.create_table(
+            "t",
+            pa.table(
+                {
+                    "id": [1, 2],
+                    "ts": pa.array(
+                        [ts, datetime(2024, 7, 2, 10, 0, 0, tzinfo=timezone.utc)],
+                        type=pa.timestamp("us", tz="UTC"),
+                    ),
+                }
+            ),
+        )
+        result = table.search().where(col("ts") == lit(ts)).to_list()
+        assert len(result) == 1
+        assert result[0]["id"] == 1
+
+    def test_different_timezones_same_instant(self, tmp_path):
+        """UTC table row equals lit of the same instant in a different zone."""
+        db = lancedb.connect(str(tmp_path / "diff_tz"))
+        ts_utc = datetime(2024, 7, 1, 10, 0, 0, tzinfo=timezone.utc)
+        # Same instant as 06:00 in UTC-4
+        ts_est = datetime(2024, 7, 1, 6, 0, 0, tzinfo=timezone(timedelta(hours=-4)))
+        table = db.create_table(
+            "t",
+            pa.table(
+                {
+                    "id": [1],
+                    "ts": pa.array([ts_utc], type=pa.timestamp("us", tz="UTC")),
+                }
+            ),
+        )
+        result = table.search().where(col("ts") == lit(ts_est)).to_list()
+        assert len(result) == 1
+        assert result[0]["id"] == 1
+
+    def test_table_tz_literal_naive(self, tmp_path):
+        """UTC table + naive lit uses wall-clock equality (10:00 == 10:00 UTC)."""
+        db = lancedb.connect(str(tmp_path / "tz_naive"))
+        ts_utc = datetime(2024, 7, 1, 10, 0, 0, tzinfo=timezone.utc)
+        ts_naive = datetime(2024, 7, 1, 10, 0, 0)
+        table = db.create_table(
+            "t",
+            pa.table(
+                {
+                    "id": [1],
+                    "ts": pa.array([ts_utc], type=pa.timestamp("us", tz="UTC")),
+                }
+            ),
+        )
+        result = table.search().where(col("ts") == lit(ts_naive)).to_list()
+        assert len(result) == 1
+        assert result[0]["id"] == 1
+
+    def test_table_naive_literal_aware(self, tmp_path):
+        """Naive table + UTC lit with the same wall clock must match."""
+        db = lancedb.connect(str(tmp_path / "naive_aware"))
+        ts_naive = datetime(2024, 7, 1, 10, 0, 0)
+        ts_utc = datetime(2024, 7, 1, 10, 0, 0, tzinfo=timezone.utc)
+        table = db.create_table("t", [{"id": 1, "ts": ts_naive}])
+        result = table.search().where(col("ts") == lit(ts_utc)).to_list()
+        assert len(result) == 1
+        assert result[0]["id"] == 1
+
+    def test_naive_lit_sql_is_wall_clock_not_local_shifted(self):
+        """Regression: naive lit must not apply the host local UTC offset."""
+        ts = datetime(2024, 7, 1, 10, 0, 0)
+        sql = lit(ts).to_sql()
+        # Must encode 10:00 wall clock, not 10:00+local_offset.
+        assert "2024-07-01 10:00:00" in sql
@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import json
+from pathlib import Path
+
+import pytest
+
+import lancedb.functions as functions
+from lancedb.functions import (
+    FunctionApplication,
+    FunctionBinding,
+    FunctionVersion,
+    PythonRuntimeSpec,
+    RefreshColumnResult,
+)
+from lancedb.table import AsyncTable
+
+
+FIXTURES = (
+    Path(__file__).parents[3]
+    / "rust"
+    / "lancedb"
+    / "tests"
+    / "fixtures"
+    / "first_class_functions"
+    / "v1"
+)
+
+
+def fixture(name: str) -> str:
+    return (FIXTURES / name).read_text()
+
+
+def job_result(name: str) -> dict:
+    return json.loads(fixture(name))["result"]
+
+
+def assert_no_secret_values(value):
+    if isinstance(value, dict):
+        for key, child in value.items():
+            assert key not in {
+                "secret_value",
+                "secret_values",
+                "resolved_secret",
+                "resolved_secrets",
+            }
+            assert_no_secret_values(child)
+    elif isinstance(value, list):
+        for child in value:
+            assert_no_secret_values(child)
+
+
+def test_public_function_values_are_in_api_reference():
+    docs = Path(__file__).parents[3] / "docs" / "src" / "python" / "python.md"
+    rendered = docs.read_text()
+    for name in functions.__all__:
+        assert f"::: lancedb.functions.{name}" in rendered
+
+
+@pytest.mark.parametrize(
+    ("fixture_name", "canonical_name", "model", "nested_result"),
+    [
+        (
+            "remote_function_job.json",
+            "remote_function_version.canonical.json",
+            FunctionVersion,
+            True,
+        ),
+        (
+            "remote_function_application.json",
+            "remote_function_application.canonical.json",
+            FunctionApplication,
+            False,
+        ),
+        (
+            "remote_function_binding.json",
+            "remote_function_binding.canonical.json",
+            FunctionBinding,
+            False,
+        ),
+        (
+            "remote_refresh_job.json",
+            "remote_refresh_result.canonical.json",
+            RefreshColumnResult,
+            True,
+        ),
+        (
+            "remote_refresh_result_without_published_version.json",
+            "remote_refresh_result_without_published_version.canonical.json",
+            RefreshColumnResult,
+            False,
+        ),
+    ],
+)
+def test_python_and_rust_share_remote_canonical_goldens(
+    fixture_name, canonical_name, model, nested_result
+):
+    value = json.loads(fixture(fixture_name))
+    if nested_result:
+        value = value["result"]
+    decoded = model.from_json(json.dumps(value))
+    assert decoded.to_canonical_json() == fixture(canonical_name).strip()
+
+
+def test_function_version_identity_is_immutable_and_exact():
+    value = job_result("remote_function_job.json")
+    version = FunctionVersion.from_json(json.dumps(value))
+    assert version.name == "embed"
+    assert version.version == "fv_01K3EXACT"
+    assert version.required_secrets == ("HF_TOKEN",)
+
+    with pytest.raises((TypeError, ValueError)):
+        version.version = "fv_changed"
+    with pytest.raises(TypeError, match="immutable"):
+        version.runtime.env["TOKENIZERS_PARALLELISM"] = "true"
+
+    changed = dict(value)
+    changed["version"] = "fv_changed"
+    assert FunctionVersion(**changed) != version
+
+
+def test_unknown_fields_and_discriminators_are_forward_decodable():
+    value = job_result("remote_function_job.json")
+    value["future_version_metadata"] = {"retention_class": "catalog"}
+    value["runtime"] = {"kind": "wasm", "module_digest": "sha256:wasm"}
+    value["signature"]["output"]["kind"] = "future_output_shape"
+
+    version = FunctionVersion.from_json(json.dumps(value))
+    assert version.runtime.kind == "wasm"
+    assert version.runtime.python_version is None
+    assert version.runtime.environment is None
+    assert json.loads(version.to_canonical_json())["runtime"] == {"kind": "wasm"}
+    assert version.signature.output.kind == "future_output_shape"
+
+
+def test_function_application_uses_rename_columns_only():
+    application = FunctionApplication.from_json(
+        fixture("remote_function_application.json")
+    )
+    renamed = application.rename(columns={"normalized_text": "body_normalized"})
+
+    assert application.columns["normalized_text"] == "search_text"
+    assert renamed.columns["normalized_text"] == "body_normalized"
+    assert renamed.function == application.function
+    assert renamed.group_id == application.group_id
+    assert not hasattr(application, "rename_outputs")
+    with pytest.raises(TypeError, match="immutable"):
+        renamed.columns["normalized_text"] = "changed"
+    with pytest.raises(TypeError, match="immutable"):
+        application.inputs[0].value["path"] = "changed"
+
+    with pytest.raises(ValueError, match="unknown Function result fields"):
+        application.rename(columns={"missing": "search_text"})
+    with pytest.raises(ValueError, match="destinations must be unique"):
+        application.rename(columns={"normalized_text": "same", "token_count": "same"})
+
+    bare_value = json.loads(fixture("remote_function_application.json"))
+    bare_value.pop("columns")
+    bare = FunctionApplication(**bare_value)
+    with pytest.raises(ValueError, match="destinations must be unique"):
+        bare.rename(columns={"normalized_text": "token_count"})
+
+
+def test_binding_and_refresh_result_keep_stable_remote_fields():
+    binding = FunctionBinding.from_json(fixture("remote_function_binding.json"))
+    assert binding.revision == 3
+    assert binding.function.version == "fv_01K3TEXT"
+    assert [output.output_ordinal for output in binding.outputs] == [0, 1]
+    assert binding.input_schema is not None
+    assert binding.output_schema is not None
+
+    result = RefreshColumnResult.from_json(
+        json.dumps(job_result("remote_refresh_job.json"))
+    )
+    assert result.rows_filled == result.rows_assigned
+    assert result.version == result.published_version
+
+    result = RefreshColumnResult.from_json(
+        fixture("remote_refresh_result_without_published_version.json")
+    )
+    assert result.published_version is None
+    assert RefreshColumnResult.from_json(result.to_canonical_json()) == result
+
+
+def test_function_literal_numeric_domain_matches_rust():
+    with pytest.raises(ValueError, match="floating-point Function literals"):
+        FunctionApplication.from_json(fixture("remote_function_application_float.json"))
+
+    value = json.loads(fixture("remote_function_application_float.json"))
+    value["inputs"][0]["value"] = 2**64
+    with pytest.raises(ValueError, match="outside the canonical JSON range"):
+        FunctionApplication.from_json(json.dumps(value))
+
+
+def test_empty_default_maps_have_stable_canonical_bytes():
+    runtime = PythonRuntimeSpec(
+        kind="python", python_version="3.12", environment={"kind": "pip"}
+    )
+    assert runtime.to_canonical_json() == (
+        '{"environment":{"kind":"pip"},"kind":"python","python_version":"3.12"}'
+    )
+
+    value = json.loads(fixture("remote_function_application.json"))
+    value.pop("columns")
+    application = FunctionApplication.from_json(json.dumps(value))
+    assert "columns" not in json.loads(application.to_canonical_json())
+
+
+@pytest.mark.parametrize("field", ["rows_assigned", "source_version"])
+def test_refresh_result_rejects_non_u64_values(field):
+    value = job_result("remote_refresh_job.json")
+    value[field] = -1
+    with pytest.raises(ValueError):
+        RefreshColumnResult.from_json(json.dumps(value))
+
+    value[field] = "1"
+    with pytest.raises(ValueError):
+        RefreshColumnResult.from_json(json.dumps(value))
+
+
+def test_canonical_client_values_contain_secret_names_only():
+    version = FunctionVersion.from_json(
+        json.dumps(job_result("remote_function_job.json"))
+    )
+    canonical = json.loads(version.to_canonical_json())
+    assert canonical["required_secrets"] == ["HF_TOKEN"]
+    assert_no_secret_values(canonical)
+
+
+class _FunctionDeclarationInner:
+    def __init__(self):
+        self.calls = []
+
+    async def add_function_columns(self, application_json, output_name):
+        self.calls.append((json.loads(application_json), output_name))
+        return "declared"
+
+
+def known_application() -> FunctionApplication:
+    value = json.loads(fixture("remote_function_application.json"))
+    value.pop("future_application")
+    return FunctionApplication(**value)
+
+
+@pytest.mark.asyncio
+async def test_add_columns_routes_struct_as_one_and_grouped_expansion_atomically():
+    inner = _FunctionDeclarationInner()
+    table = AsyncTable(inner)
+    application = known_application()
+
+    result = await table.add_columns(
+        {"features": application._copy(update={"columns": {}})}
+    )
+    assert result == "declared"
+    assert inner.calls[-1][1] == "features"
+
+    bare = application._copy(update={"columns": {}}).rename(
+        columns={"normalized_text": "search_text"}
+    )
+    result = await table.add_columns(bare)
+    assert result == "declared"
+    assert inner.calls[-1][1] is None
+    assert inner.calls[-1][0]["columns"] == {"normalized_text": "search_text"}
+
+
+@pytest.mark.asyncio
+async def test_add_columns_rejects_mixed_groups_and_unknown_newer_application():
+    inner = _FunctionDeclarationInner()
+    table = AsyncTable(inner)
+    application = known_application()
+
+    with pytest.raises(ValueError, match="exactly one Function sibling group"):
+        await table.add_columns({"a": application, "b": application})
+
+    future = json.loads(fixture("remote_function_application.json"))
+    application = FunctionApplication(**future)
+    with pytest.raises(ValueError, match="newer contract"):
+        await table.add_columns(application)
+
+    future.pop("future_application")
+    future["output"]["assignment"] = "cell_flag"
+    application = FunctionApplication(**future)
+    assert "assignment" not in json.loads(application.to_canonical_json())["output"]
+    with pytest.raises(ValueError, match="output.assignment"):
+        await table.add_columns(application)
+    assert inner.calls == []
+
+
+def test_rename_requires_named_struct_and_keeps_partial_mapping_immutable():
+    scalar = FunctionApplication.from_json(
+        json.dumps(
+            {
+                "function": {"name": "embed", "version": "fv_exact"},
+                "inputs": [],
+                "output": {
+                    "kind": "scalar",
+                    "arrow_type": "list<float32>",
+                    "nullable": False,
+                },
+                "group_id": "fg_scalar",
+            }
+        )
+    )
+    with pytest.raises(ValueError, match="named-struct"):
+        scalar.rename(columns={"value": "embedding"})
+
+    application = known_application()._copy(update={"columns": {}})
+    renamed = application.rename(columns={"normalized_text": "search_text"})
+    assert dict(application.columns) == {}
+    assert dict(renamed.columns) == {"normalized_text": "search_text"}
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+from __future__ import annotations
+
+import contextlib
+import http.server
+import json
+from pathlib import Path
+import threading
+from typing import Optional
+
+import pyarrow as pa
+import pytest
+
+import lancedb
+from lancedb.functions import UdfDefinition, udf
+
+
+FIXTURES = (
+    Path(__file__).parents[3]
+    / "rust"
+    / "lancedb"
+    / "tests"
+    / "fixtures"
+    / "first_class_functions"
+    / "v1"
+)
+
+
+@udf(
+    pip=["numpy>=2"],
+    env={"MODE": "test"},
+    secrets=["API_TOKEN"],
+    python_version="3.12",
+)
+def normalize_score(value: float) -> float:
+    return value / 100.0
+
+
+def _assert_no_secret_values(value):
+    if isinstance(value, dict):
+        for key, child in value.items():
+            assert key not in {
+                "secret_value",
+                "secret_values",
+                "resolved_secret",
+                "resolved_secrets",
+            }
+            _assert_no_secret_values(child)
+    elif isinstance(value, list):
+        for child in value:
+            _assert_no_secret_values(child)
+
+
+def test_scalar_udf_matches_shared_registration_golden_and_remains_callable():
+    assert isinstance(normalize_score, UdfDefinition)
+    assert normalize_score(25.0) == 0.25
+    assert (
+        normalize_score.registration_request.to_canonical_json()
+        == (FIXTURES / "remote_function_registration_request.canonical.json")
+        .read_text()
+        .strip()
+    )
+    request = json.loads(normalize_score.registration_request.to_canonical_json())
+    assert request["artifact"]["adapter"] == {
+        "kind": "scalar_to_arrow_batch",
+        "version": 1,
+    }
+    assert request["required_secrets"] == ["API_TOKEN"]
+    _assert_no_secret_values(request)
+
+
+def test_explicit_arrow_schema_is_deterministic():
+    input_schema = pa.schema([pa.field("value", pa.float32(), nullable=True)])
+    output_schema = pa.field("embedding", pa.list_(pa.float32(), 3), nullable=False)
+
+    @udf(input_schema=input_schema, output_schema=output_schema)
+    def explicit(value):
+        return [value, value, value]
+
+    signature = explicit.registration_request.signature
+    assert signature.inputs[0].arrow_type == "float32"
+    assert signature.inputs[0].nullable is True
+    assert signature.output.arrow_type == "fixed_size_list<float32>[3]"
+    assert signature.output.nullable is False
+
+
+def test_annotation_and_explicit_schema_validation_fail_closed():
+    with pytest.raises(TypeError, match="missing Function annotations"):
+
+        @udf
+        def missing(value):
+            return value
+
+    with pytest.raises(TypeError, match="unsupported Function annotation"):
+
+        @udf
+        def unsupported(value: set[str]) -> str:
+            return ""
+
+    with pytest.raises(ValueError, match="output must be non-nullable"):
+
+        @udf
+        def nullable_output(value: int) -> Optional[int]:
+            return value
+
+    with pytest.raises(ValueError, match="provided together"):
+
+        @udf(input_schema=pa.schema([pa.field("value", pa.int64())]))
+        def partial_schema(value):
+            return value
+
+    with pytest.raises(ValueError, match="exactly match callable parameters"):
+
+        @udf(
+            input_schema=pa.schema([pa.field("other", pa.int64())]),
+            output_schema=pa.int64(),
+        )
+        def wrong_name(value):
+            return value
+
+    with pytest.raises(ValueError, match="output must be non-nullable"):
+
+        @udf(
+            input_schema=pa.schema([pa.field("value", pa.int64())]),
+            output_schema=pa.field("result", pa.int64(), nullable=True),
+        )
+        def nullable_explicit(value):
+            return value
+
+
+def test_environment_rejects_secret_value_overlap():
+    with pytest.raises(ValueError, match="must be disjoint"):
+
+        @udf(env={"TOKEN": "plaintext"}, secrets=["TOKEN"])
+        def overlapping(value: int) -> int:
+            return value
+
+
+def test_local_function_catalog_operations_are_not_supported(tmp_path):
+    db = lancedb.connect(tmp_path)
+    message = "Function catalog operations are not supported by this database"
+    with pytest.raises(NotImplementedError, match=message):
+        db.create_function(normalize_score)
+    with pytest.raises(NotImplementedError, match=message):
+        db.create_function_async(normalize_score)
+    with pytest.raises(NotImplementedError, match=message):
+        db.get_function("normalize_score", version="fv_exact")
+
+
+@contextlib.contextmanager
+def _mock_remote_function_catalog():
+    state = {"requests": [], "version": None}
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def log_message(self, *args):
+            pass
+
+        def do_POST(self):
+            length = int(self.headers.get("Content-Length", "0"))
+            body = json.loads(self.rfile.read(length) or b"{}")
+            state["requests"].append((self.path, body))
+            status = 200
+            if self.path == "/v1/function/create":
+                state["version"] = {
+                    "name": body["name"],
+                    "version": "fv_exact",
+                    "artifact": {
+                        key: body["artifact"][key]
+                        for key in ("kind", "digest", "entrypoint")
+                    },
+                    "signature": body["signature"],
+                    "runtime": body["runtime"],
+                    "runtime_digest": "sha256:runtime",
+                    "environment_digest": "sha256:environment",
+                    "required_secrets": body.get("required_secrets", []),
+                    "created_at": "2026-08-21T00:00:00Z",
+                }
+                response = {"job_id": "job-register"}
+                status = 202
+            elif self.path == "/v1/jobs/describe":
+                assert body == {"job_id": "job-register"}
+                response = {
+                    "job_id": "job-register",
+                    "job_type": "create_function",
+                    "job_state": "DONE",
+                    "result": state["version"],
+                }
+            elif self.path == "/v1/function/describe":
+                assert body == {
+                    "name": "normalize_score",
+                    "version": "fv_exact",
+                }
+                response = state["version"]
+            else:
+                status = 404
+                response = {"error": "not found"}
+            encoded = json.dumps(response).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+
+    with http.server.HTTPServer(("localhost", 0), Handler) as server:
+        thread = threading.Thread(target=server.serve_forever)
+        thread.start()
+        try:
+            yield f"http://localhost:{server.server_address[1]}", state
+        finally:
+            server.shutdown()
+            thread.join()
+
+
+def test_remote_registration_job_and_exact_version_reopen_round_trip():
+    with _mock_remote_function_catalog() as (host, state):
+        db = lancedb.connect(
+            "db://dev",
+            api_key="fake",
+            host_override=host,
+            client_config={"retry_config": {"retries": 0}},
+        )
+        registration = db.create_function_async(normalize_score)
+        assert registration.id == "job-register"
+        created = registration.wait()
+        reopened = db.get_function("normalize_score", version=created.version)
+
+    assert created == reopened
+    assert reopened.name == "normalize_score"
+    assert reopened.version == "fv_exact"
+    create_request = state["requests"][0][1]
+    assert create_request == json.loads(
+        normalize_score.registration_request.to_canonical_json()
+    )
+    _assert_no_secret_values(create_request)
+
+
+def test_blocking_remote_registration_returns_function_version():
+    with _mock_remote_function_catalog() as (host, state):
+        db = lancedb.connect(
+            "db://dev",
+            api_key="fake",
+            host_override=host,
+            client_config={"retry_config": {"retries": 0}},
+        )
+        created = db.create_function(normalize_score)
+
+    assert created.name == "normalize_score"
+    assert created.version == "fv_exact"
+    assert [path for path, _ in state["requests"]] == [
+        "/v1/function/create",
+        "/v1/jobs/describe",
+    ]
@@ -203,6 +203,31 @@ async def test_async_hybrid_query_default_limit(table: AsyncTable):
    assert texts.count("a") == 1


+def test_hybrid_query_offset(sync_table: Table):
+    # The offset window of a hybrid query must be a suffix of the same query
+    # run without an offset -- it must not be silently ignored.
+    full = (
+        sync_table.search(query_type="hybrid")
+        .vector([0.0, 0.4])
+        .text("dog")
+        .limit(4)
+        .with_row_id(True)
+        .to_arrow()
+    )
+    assert len(full) == 4
+
+    offset_result = (
+        sync_table.search(query_type="hybrid")
+        .vector([0.0, 0.4])
+        .text("dog")
+        .offset(2)
+        .limit(2)
+        .with_row_id(True)
+        .to_arrow()
+    )
+    assert offset_result["_rowid"].to_pylist() == full["_rowid"].to_pylist()[2:]
+
+
 def test_hybrid_query_minimum_nprobes_zero_raises(sync_table: Table):
    # minimum_nprobes(0) must raise the same validation error a plain vector
    # query raises, not silently no-op because 0 is falsy.
@@ -21,6 +21,11 @@ SCHEMA = pa.schema(
 )


+def test_lsm_write_spec_module_metadata():
+    assert lancedb.LsmWriteSpec is LsmWriteSpec
+    assert LsmWriteSpec.__module__ == "lancedb._lancedb"
+
+
 def _batch(ids, vs):
    return pa.RecordBatch.from_arrays(
        [pa.array(ids, type=pa.utf8()), pa.array(vs, type=pa.int32())],
@@ -10,11 +10,10 @@ import pyarrow as pa
 import pydantic
 import pytest
 from lancedb.pydantic import (
-    PYDANTIC_VERSION,
    LanceModel,
+    MultiVector,
    Vector,
    pydantic_to_schema,
-    MultiVector,
 )
 from pydantic import BaseModel
 from pydantic import Field
@@ -432,16 +431,10 @@ def test_fixed_size_list_field():
        li: List[int]

    data = TestModel(vec=list(range(16)), li=[1, 2, 3])
-    if PYDANTIC_VERSION.major >= 2:
-        assert json.loads(data.model_dump_json()) == {
-            "vec": list(range(16)),
-            "li": [1, 2, 3],
-        }
-    else:
-        assert data.dict() == {
-            "vec": list(range(16)),
-            "li": [1, 2, 3],
-        }
+    assert json.loads(data.model_dump_json()) == {
+        "vec": list(range(16)),
+        "li": [1, 2, 3],
+    }

    schema = pydantic_to_schema(TestModel)
    assert schema == pa.schema(
@@ -451,10 +444,7 @@ def test_fixed_size_list_field():
        ]
    )

-    if PYDANTIC_VERSION.major >= 2:
-        json_schema = TestModel.model_json_schema()
-    else:
-        json_schema = TestModel.schema()
+    json_schema = TestModel.model_json_schema()

    assert json_schema == {
        "properties": {
@@ -1133,6 +1133,131 @@ def test_stats():
        assert res == stats


+@contextlib.contextmanager
+def lsm_test_table(lsm_handler):
+    """A remote table whose LSM routes are served by ``lsm_handler``.
+
+    ``lsm_handler(request, route)`` is called for ``/v1/table/test/<route>/``
+    where route is one of flush_lsm, compact_lsm, get_lsm_stats, and is
+    responsible for writing the response.
+    """
+    routes = ("flush_lsm", "compact_lsm", "get_lsm_stats")
+
+    def handler(request):
+        match = re.fullmatch(r"/v1/table/test/(\w+)/", request.path)
+        route = match.group(1) if match else None
+        if route in routes:
+            lsm_handler(request, route)
+        elif route == "describe":
+            request.send_response(200)
+            request.send_header("Content-Type", "application/json")
+            request.end_headers()
+            request.wfile.write(b'{"version": 1, "schema": {"fields": []}}')
+        else:
+            request.send_response(404)
+            request.end_headers()
+
+    with mock_lancedb_connection(handler) as db:
+        yield db.open_table("test")
+
+
+def read_json_body(request):
+    content_len = int(request.headers.get("Content-Length"))
+    return json.loads(request.rfile.read(content_len))
+
+
+def send_json(request, payload, status=200):
+    request.send_response(status)
+    request.send_header("Content-Type", "application/json")
+    request.end_headers()
+    request.wfile.write(json.dumps(payload).encode())
+
+
+def test_get_lsm_stats_sync():
+    """The sync wrapper round-trips the server payload into a dict."""
+    bucket = {
+        "shard_id": "b0",
+        "status": "Active",
+        "writer_epoch": 3,
+        "manifest_version": 12,
+        "current_generation": 6,
+        "replay_after_wal_entry_position": 40,
+        "wal_entry_position_last_seen": 42,
+        "generations": [{"generation": 5, "bytes": 1024, "rows": 7}],
+        "compacting": False,
+        "memtables": [
+            {
+                "generation": 6,
+                "rows": 2,
+                "bytes": 64,
+                "batches": 1,
+                "indexes": ["vec_idx"],
+            }
+        ],
+    }
+    seen_bodies = []
+
+    def lsm_handler(request, route):
+        assert route == "get_lsm_stats"
+        seen_bodies.append(read_json_body(request))
+        send_json(request, {"lsm_stats": {"buckets": [bucket]}})
+
+    with lsm_test_table(lsm_handler) as table:
+        assert table.get_lsm_stats() == {"buckets": [bucket]}
+        # Off by default, and forwarded when asked for.
+        assert seen_bodies == [{"include_generation_rows": False}]
+        table.get_lsm_stats(include_generation_rows=True)
+        assert seen_bodies[-1] == {"include_generation_rows": True}
+
+
+def test_get_lsm_stats_sync_returns_none_when_lsm_disabled():
+    """A null envelope means the LSM write path is not enabled, not an error."""
+
+    def lsm_handler(request, route):
+        send_json(request, {"lsm_stats": None})
+
+    with lsm_test_table(lsm_handler) as table:
+        assert table.get_lsm_stats() is None
+
+
+def test_flush_and_compact_lsm_sync():
+    """Both are one-shot POSTs answered 202 with no body."""
+    called = []
+
+    def lsm_handler(request, route):
+        called.append(route)
+        request.send_response(202)
+        request.end_headers()
+
+    with lsm_test_table(lsm_handler) as table:
+        assert table.flush_lsm() is None
+        assert table.compact_lsm() is None
+        assert called == ["flush_lsm", "compact_lsm"]
+
+
+def test_checkpoint_lsm_sync():
+    """Seal, read the watermark, and return once L0 holds nothing.
+
+    The convergence loop itself is covered in Rust; this pins the sync
+    binding to the endpoints it drives.
+    """
+    called = []
+
+    def lsm_handler(request, route):
+        called.append(route)
+        if route == "get_lsm_stats":
+            # An empty L0 yields no target watermark, so the loop is done
+            # after the seal without ever polling compaction.
+            send_json(request, {"lsm_stats": {"buckets": []}})
+        else:
+            request.send_response(202)
+            request.end_headers()
+
+    with lsm_test_table(lsm_handler) as table:
+        assert table.checkpoint_lsm() is None
+        assert called == ["flush_lsm", "get_lsm_stats"]
+
+
@contextlib.contextmanager
 def query_test_table(query_handler, *, server_version=Version("0.1.0")):
    def handler(request):
@@ -2772,6 +2772,56 @@ async def test_merge_insert_async(mem_db_async: AsyncConnection):
    assert (await table.to_arrow()).sort_by("a") == expected


+@pytest.mark.skipif(not hasattr(pa, "json_"), reason="requires PyArrow JSON type")
+@pytest.mark.asyncio
+async def test_merge_insert_encodes_json(mem_db_async: AsyncConnection):
+    json_type = pa.json_()
+    schema = pa.schema([pa.field("id", pa.string()), pa.field("j", json_type)])
+
+    def json_table(rows):
+        json_values = pa.ExtensionArray.from_storage(
+            json_type,
+            pa.array([value for _, value in rows], type=json_type.storage_type),
+        )
+        return pa.Table.from_arrays(
+            [pa.array([row_id for row_id, _ in rows]), json_values], schema=schema
+        )
+
+    table = await mem_db_async.create_table("json_merge", schema=schema)
+    await table.add(json_table([("a", '{"k": 1}'), ("b", '{"k": 9}')]))
+
+    await (
+        table.merge_insert("id")
+        .when_matched_update_all()
+        .execute(json_table([("a", '{"k": 2}')]))
+    )
+
+    rows = sorted(await table.query().to_list(), key=lambda row: row["id"])
+    assert rows == [
+        {"id": "a", "j": '{"k":2}'},
+        {"id": "b", "j": '{"k":9}'},
+    ]
+    filtered = await table.query().where("json_extract(j, '$.k') = '2'").to_list()
+    assert filtered == [{"id": "a", "j": '{"k":2}'}]
+
+
+@pytest.mark.skipif(not hasattr(pa, "json_"), reason="requires PyArrow JSON type")
+@pytest.mark.asyncio
+async def test_add_sanitization_encodes_json(mem_db_async: AsyncConnection):
+    json_type = pa.json_()
+    schema = pa.schema([pa.field("id", pa.string()), pa.field("j", json_type)])
+    json_values = pa.ExtensionArray.from_storage(
+        json_type, pa.array(['{"k": 3}'], type=json_type.storage_type)
+    )
+    data = pa.Table.from_arrays([pa.array(["c"]), json_values], schema=schema)
+
+    table = await mem_db_async.create_table("json_add", schema=schema)
+    await table.add(data, on_bad_vectors="fill")
+
+    rows = await table.query().where("json_extract(j, '$.k') = '3'").to_list()
+    assert rows == [{"id": "c", "j": '{"k":3}'}]
+
+
 def test_create_with_embedding_function(mem_db: DBConnection):
    class MyTable(LanceModel):
        text: str
@@ -563,6 +563,38 @@ impl Connection {
        Ok(crate::job::Job::new(inner.job(job_id).infer_error()?))
    }

+    pub fn create_function_async(
+        self_: PyRef<'_, Self>,
+        request_json: String,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        let request = lancedb::function::FunctionRegistrationRequest::from_json(&request_json)
+            .infer_error()?;
+        future_into_py(self_.py(), async move {
+            inner
+                .create_function_async(request)
+                .await
+                .infer_error()
+                .map(crate::job::FunctionJob::new)
+        })
+    }
+
+    pub fn get_function(
+        self_: PyRef<'_, Self>,
+        name: String,
+        version: String,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .get_function(name, version)
+                .await
+                .infer_error()?
+                .to_canonical_json()
+                .infer_error()
+        })
+    }
+
    pub fn list_jobs(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
        let inner = self_.get_inner()?.clone();
        future_into_py(self_.py(), async move {
@@ -191,8 +191,27 @@ pub fn expr_lit(value: Bound<'_, PyAny>) -> PyResult<PyExpr> {
    }

    // datetime.datetime is a subclass of datetime.date, so it must be checked first.
+    //
+    // Python's datetime.timestamp() treats *naive* datetimes as local wall time.
+    // PyArrow (and therefore Lance table storage) encodes naive timestamps as
+    // UTC wall-clock microseconds. Using .timestamp() for naive values therefore
+    // shifts the literal by the local UTC offset on non-UTC machines, so
+    // `col("ts") == lit(naive_dt)` fails against a table that holds the same
+    // naive value. Fix: treat naive datetimes as UTC wall clock (match Arrow);
+    // keep aware datetimes on the real .timestamp() path (correct epoch).
    if let Ok(dt) = value.cast::<PyDateTime>() {
-        let ts: f64 = dt.call_method0("timestamp")?.extract()?;
+        let ts: f64 = if dt.getattr("tzinfo")?.is_none() {
+            // Force UTC interpretation of the naive wall clock.
+            let utc = pyo3::types::PyModule::import(value.py(), "datetime")?
+                .getattr("timezone")?
+                .getattr("utc")?;
+            let kwargs = pyo3::types::PyDict::new(value.py());
+            kwargs.set_item("tzinfo", utc)?;
+            let aware = dt.call_method("replace", (), Some(&kwargs))?;
+            aware.call_method0("timestamp")?.extract()?
+        } else {
+            dt.call_method0("timestamp")?.extract()?
+        };
        let micros = (ts * 1_000_000.0).round() as i64;
        return Ok(PyExpr(df_lit(ScalarValue::TimestampMicrosecond(
            Some(micros),
@@ -13,6 +13,23 @@ pub struct Job {
    inner: Arc<lancedb::Job>,
 }

+/// Python bridge for a typed remote Function registration job.
+///
+/// The public Python layer decodes the canonical JSON returned by `wait`
+/// into its immutable `FunctionVersion` model.
+#[pyclass]
+pub struct FunctionJob {
+    inner: Arc<lancedb::Job<lancedb::function::FunctionVersion>>,
+}
+
+impl FunctionJob {
+    pub(crate) fn new(inner: lancedb::Job<lancedb::function::FunctionVersion>) -> Self {
+        Self {
+            inner: Arc::new(inner),
+        }
+    }
+}
+
 impl Job {
    pub(crate) fn new(inner: lancedb::Job) -> Self {
        Self {
@@ -21,6 +38,42 @@ impl Job {
    }
 }

+#[pymethods]
+impl FunctionJob {
+    #[getter]
+    pub fn id(&self) -> Option<String> {
+        self.inner.id().map(str::to_string)
+    }
+
+    pub fn status(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(
+            self_.py(),
+            async move { inner.status().await.infer_error() },
+        )
+    }
+
+    pub fn wait(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .wait()
+                .await
+                .infer_error()?
+                .to_canonical_json()
+                .infer_error()
+        })
+    }
+
+    pub fn cancel(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner.cancel().await.infer_error()?;
+            Ok(())
+        })
+    }
+}
+
 #[pymethods]
 impl Job {
    #[getter]
@@ -47,6 +47,7 @@ pub fn _lancedb(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<Session>()?;
    m.add_class::<Table>()?;
    m.add_class::<crate::job::Job>()?;
+    m.add_class::<crate::job::FunctionJob>()?;
    m.add_class::<crate::job::JobInfo>()?;
    m.add_class::<crate::job::JobDescription>()?;
    m.add_class::<crate::job::JobFailureInfo>()?;
@@ -262,7 +262,7 @@ fn fmt_maintained(maintained: &Option<Vec<String>>) -> String {
 /// classmethods, then optionally chain `with_maintained_indexes(...)` and
 /// `with_writer_config_defaults(...)`. A fresh spec maintains every index the
 /// MemWAL supports, resolved on install.
-#[pyclass(from_py_object)]
+#[pyclass(module = "lancedb._lancedb", from_py_object)]
 #[derive(Clone, Debug)]
 pub struct LsmWriteSpec {
    inner: lancedb::table::LsmWriteSpec,
@@ -1551,6 +1551,24 @@ impl Table {
        })
    }

+    pub fn add_function_columns(
+        self_: PyRef<'_, Self>,
+        application_json: String,
+        output_name: Option<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let application =
+            lancedb::function::FunctionApplication::from_json(&application_json).infer_error()?;
+        let inner = self_.inner_ref()?.clone();
+        future_into_py(self_.py(), async move {
+            let builder = match output_name {
+                Some(name) => inner.add_columns().function_as(name, application),
+                None => inner.add_columns().function(application),
+            };
+            let result = builder.execute().await.infer_error()?;
+            Ok(AddColumnsResult::from(result))
+        })
+    }
+
    pub fn refresh_column(self_: PyRef<'_, Self>, column: String) -> PyResult<Bound<'_, PyAny>> {
        let inner = self_.inner_ref()?.clone();
        future_into_py(self_.py(), async move {
@@ -2003,7 +2003,7 @@ requires-dist = [
    { name = "pyarrow", specifier = ">=16" },
    { name = "pyarrow", marker = "extra == 'tests'", specifier = "<25" },
    { name = "pyarrow-stubs", marker = "extra == 'tests'", specifier = ">=16.0" },
-    { name = "pydantic", specifier = ">=1.10" },
+    { name = "pydantic", specifier = ">=2.7.4,<3" },
    { name = "pylance", marker = "extra == 'pylance'", specifier = ">=5.0.0b5" },
    { name = "pylance", marker = "extra == 'tests'", specifier = "==9.0.0rc1" },
    { name = "pyright", marker = "extra == 'dev'", specifier = ">=1.1.350" },
@@ -1,6 +1,6 @@
 [package]
 name = "lancedb"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.3"
 edition.workspace = true
 description = "LanceDB: A serverless, low-latency vector database for AI applications"
 license.workspace = true
@@ -51,20 +51,20 @@ metrics = { workspace = true, optional = true }
 metrics-util = { workspace = true, optional = true }
 moka = { workspace = true }
 pin-project = { workspace = true }
-tokio = { version = "1.23", features = ["rt-multi-thread", "sync"] }
+tokio = { workspace = true }
 log.workspace = true
-async-trait = "0"
-bytes = "1"
+async-trait = { workspace = true }
+bytes = { workspace = true }
 futures.workspace = true
 num-traits.workspace = true
 url.workspace = true
 rand.workspace = true
 regex.workspace = true
-serde = { version = "^1" }
-serde_json = { version = "1" }
+serde = { workspace = true }
+serde_json = { workspace = true }
 async-openai = { version = "0.20.0", optional = true }
 serde_with = { version = "3.8.1" }
-tempfile = "3.5.0"
+tempfile = { workspace = true }
 aws-sdk-bedrockruntime = { version = "1.27.0", optional = true }
 # For remote feature
 reqwest = { version = "0.12.0", default-features = false, features = [
@@ -79,7 +79,7 @@ reqwest = { version = "0.12.0", default-features = false, features = [
 ], optional = true }
 http = { version = "1", optional = true } # Matching what is in reqwest
 urlencoding = { version = "2", optional = true }
-uuid = { version = "1.7.0", features = ["v4", "v5"] }
+uuid = { workspace = true, features = ["v5"] }
 polars-arrow = { version = ">=0.37,<0.40.0", optional = true }
 polars = { version = ">=0.37,<0.40.0", optional = true }
 hf-hub = { version = "0.4.1", optional = true, default-features = false, features = [
@@ -96,11 +96,11 @@ semver = { workspace = true }
 [dev-dependencies]
 anyhow = "1"
 lance-testing = { workspace = true }
-tempfile = "3.5.0"
+tempfile = { workspace = true }
 random_word = { version = "0.4.3", features = ["en"] }
 roaring = "0.11.4"
-tokio = { version = "1.23", features = ["io-util", "macros", "net", "rt-multi-thread", "sync", "test-util"] }
-uuid = { version = "1.7.0", features = ["v4"] }
+tokio = { workspace = true, features = ["io-util", "macros", "net", "test-util"] }
+uuid = { workspace = true }
 walkdir = "2"
 aws-sdk-dynamodb = { version = "1.55.0" }
 aws-sdk-s3 = { version = "1.55.0" }
@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors

-// Release benchmark for opening a missing table as sibling-table cardinality grows.
+// Benchmark for opening a missing table as sibling-table cardinality grows.
 //
 // The fixture uses real `.lance` directories and marker files. Fixture creation is
 // outside the timed section. Defaults intentionally cover 1k, 10k, and 100k siblings
 // with 10 warmups and 100 distinct missing-table opens per scale:
 //
 // ```text
-// cargo run --release -p lancedb --example bench_open_missing_table
+// cargo run --profile release-no-lto -p lancedb --example bench_open_missing_table
 // ```
 //
 // `BENCH_SIBLINGS`, `BENCH_WARMUPS`, and `BENCH_TRIALS` override those defaults.
@@ -5,10 +5,10 @@
 //! streaming dataloader.
 //!
 //! Normal sweep:
-//!   cargo run --release --example bench_streaming_dataloader
+//!   cargo run --profile release-with-debug --example bench_streaming_dataloader
 //!
 //! Flamegraph (self-contained, no perf/dtrace needed):
-//!   BENCH_PROFILE=1 BENCH_CHUNK=64 cargo run --release \
+//!   BENCH_PROFILE=1 BENCH_CHUNK=64 cargo run --profile release-with-debug \
 //!       --example bench_streaming_dataloader
 //!   # writes flamegraph.svg in the current directory
 //!
@@ -496,6 +496,33 @@ impl Connection {
        )
    }

+    /// Register a Python callable as a new immutable Function version.
+    ///
+    /// Registration is remote-only and always asynchronous. Waiting on the
+    /// returned typed job yields the durable [`crate::function::FunctionVersion`].
+    /// Local databases return [`Error::NotSupported`].
+    pub async fn create_function_async(
+        &self,
+        request: crate::function::FunctionRegistrationRequest,
+    ) -> Result<crate::job::Job<crate::function::FunctionVersion>> {
+        self.internal.create_function_async(request).await
+    }
+
+    /// Look up one exact immutable Function version in the remote catalog.
+    ///
+    /// Both the logical name and server-assigned version id are required;
+    /// mutable aliases and latest-version lookup are intentionally absent.
+    /// Local databases return [`Error::NotSupported`].
+    pub async fn get_function(
+        &self,
+        name: impl AsRef<str>,
+        version: impl AsRef<str>,
+    ) -> Result<crate::function::FunctionVersion> {
+        self.internal
+            .get_function(name.as_ref(), version.as_ref())
+            .await
+    }
+
    /// Rename a table in the database.
    ///
    /// This is only supported in LanceDB Cloud.
@@ -241,6 +241,12 @@ fn job_op_not_supported<T>(what: &str) -> Result<T> {
    })
 }

+fn function_catalog_not_supported<T>() -> Result<T> {
+    Err(crate::error::Error::NotSupported {
+        message: "Function catalog operations are not supported by this database".to_string(),
+    })
+}
+
 /// The `Database` trait defines the interface for database implementations.
 ///
 /// A database is responsible for managing tables and their metadata.
@@ -286,6 +292,21 @@ pub trait Database:
    ///
    /// See [`CloneTableRequest`] for detailed documentation and examples.
    async fn clone_table(&self, request: CloneTableRequest) -> Result<Arc<dyn BaseTable>>;
+    /// Register an immutable Function version through the remote catalog.
+    async fn create_function_async(
+        &self,
+        _request: crate::function::FunctionRegistrationRequest,
+    ) -> Result<crate::job::Job<crate::function::FunctionVersion>> {
+        function_catalog_not_supported()
+    }
+    /// Look up one exact immutable Function version.
+    async fn get_function(
+        &self,
+        _name: &str,
+        _version: &str,
+    ) -> Result<crate::function::FunctionVersion> {
+        function_catalog_not_supported()
+    }
    /// A [`crate::job::Job`] handle for a server-side job by id, suitable for
    /// waiting on or cancelling the job. The handle is constructed without a
    /// server round trip; an unknown id surfaces when the handle is used.
@@ -0,0 +1,606 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+//! Canonical values exchanged with the Enterprise Function service.
+//!
+//! This module contains client/wire values only. Catalog persistence,
+//! environment bake, secret resolution, and execution are owned by Sophon.
+
+use std::collections::BTreeMap;
+
+use serde::de::{self, DeserializeOwned};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use serde_json::Value;
+
+use crate::{Error, Result};
+
+fn invalid_json(error: impl std::fmt::Display) -> Error {
+    Error::InvalidInput {
+        message: format!("invalid remote Function JSON: {error}"),
+    }
+}
+
+fn write_canonical_json(value: &Value, output: &mut String) -> serde_json::Result<()> {
+    match value {
+        Value::Object(map) => {
+            output.push('{');
+            let mut entries = map.iter().collect::<Vec<_>>();
+            entries.sort_unstable_by_key(|(key, _)| *key);
+            for (index, (key, value)) in entries.into_iter().enumerate() {
+                if index != 0 {
+                    output.push(',');
+                }
+                output.push_str(&serde_json::to_string(key)?);
+                output.push(':');
+                write_canonical_json(value, output)?;
+            }
+            output.push('}');
+        }
+        Value::Array(values) => {
+            output.push('[');
+            for (index, value) in values.iter().enumerate() {
+                if index != 0 {
+                    output.push(',');
+                }
+                write_canonical_json(value, output)?;
+            }
+            output.push(']');
+        }
+        other => output.push_str(&serde_json::to_string(other)?),
+    }
+    Ok(())
+}
+
+fn canonical_json<T: Serialize>(value: &T) -> Result<String> {
+    let value = serde_json::to_value(value).map_err(invalid_json)?;
+    let mut output = String::new();
+    write_canonical_json(&value, &mut output).map_err(invalid_json)?;
+    Ok(output)
+}
+
+fn from_json<T: DeserializeOwned>(json: &str) -> Result<T> {
+    serde_json::from_str(json).map_err(invalid_json)
+}
+
+fn validate_literal(value: &Value) -> Result<()> {
+    match value {
+        Value::Number(number) if number.is_f64() => Err(Error::InvalidInput {
+            message: "floating-point Function literals are not part of the Slice 1 canonical wire contract"
+                .to_string(),
+        }),
+        Value::Array(values) => values.iter().try_for_each(validate_literal),
+        Value::Object(values) => values.values().try_for_each(validate_literal),
+        _ => Ok(()),
+    }
+}
+
+fn has_unknown_keys(value: &Value, allowed: &[&str]) -> bool {
+    value
+        .as_object()
+        .is_some_and(|object| object.keys().any(|key| !allowed.contains(&key.as_str())))
+}
+
+fn application_has_unknown_nested_fields(value: &Value) -> bool {
+    let Some(application) = value.as_object() else {
+        return false;
+    };
+    if application
+        .get("function")
+        .is_some_and(|value| has_unknown_keys(value, &["name", "version"]))
+    {
+        return true;
+    }
+    if application
+        .get("inputs")
+        .and_then(Value::as_array)
+        .is_some_and(|inputs| {
+            inputs
+                .iter()
+                .any(|input| has_unknown_keys(input, &["parameter", "kind", "value"]))
+        })
+    {
+        return true;
+    }
+    application.get("output").is_some_and(|output| {
+        has_unknown_keys(output, &["kind", "arrow_type", "nullable", "fields"])
+            || output
+                .get("fields")
+                .and_then(Value::as_array)
+                .is_some_and(|fields| {
+                    fields
+                        .iter()
+                        .any(|field| has_unknown_keys(field, &["name", "arrow_type", "nullable"]))
+                })
+    })
+}
+
+macro_rules! impl_json {
+    ($type:ty) => {
+        impl $type {
+            /// Decode a remote value. Unknown fields and discriminator values
+            /// are accepted so newer servers remain readable.
+            pub fn from_json(json: &str) -> Result<Self> {
+                from_json(json)
+            }
+
+            /// Encode the known client contract with bytewise-sorted JSON keys.
+            pub fn to_canonical_json(&self) -> Result<String> {
+                canonical_json(self)
+            }
+        }
+    };
+}
+
+/// Packaged Python artifact identity. Source bytes are never part of this value.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionArtifact {
+    pub kind: String,
+    pub digest: String,
+    pub entrypoint: String,
+}
+
+/// One ordered Arrow input parameter.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionParameter {
+    pub name: String,
+    pub arrow_type: String,
+    pub nullable: bool,
+}
+
+/// One field of an ordered named-struct result.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionResultField {
+    pub name: String,
+    pub arrow_type: String,
+    pub nullable: bool,
+}
+
+/// Scalar or named-struct Function output.
+///
+/// `kind` remains a string so unknown future result shapes can be decoded.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionOutput {
+    pub kind: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub arrow_type: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub nullable: Option<bool>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub fields: Vec<FunctionResultField>,
+}
+
+/// Ordered language-neutral Function signature.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionSignature {
+    pub inputs: Vec<FunctionParameter>,
+    pub output: FunctionOutput,
+}
+
+/// One Python environment source.
+///
+/// The selected source is interpreted by Sophon. `kind` is open for forward
+/// compatible decoding.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PythonEnvironmentSpec {
+    pub kind: String,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub packages: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub modules: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub image: Option<String>,
+}
+
+/// Reproducible Python runtime definition understood by Sophon.
+///
+/// `env` contains non-secret values. Secret values have no client model;
+/// [`FunctionVersion::required_secrets`] contains names only.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum PythonRuntimeSpec {
+    /// The V1 Sophon-managed Python runtime.
+    Python {
+        python_version: String,
+        environment: PythonEnvironmentSpec,
+        env: BTreeMap<String, String>,
+    },
+    /// A runtime kind introduced by a newer server.
+    ///
+    /// Unknown payload fields are intentionally not retained because the
+    /// client does not proxy catalog values.
+    Unrecognized { kind: String },
+}
+
+impl PythonRuntimeSpec {
+    /// The wire discriminator reported by Sophon.
+    pub fn kind(&self) -> &str {
+        match self {
+            Self::Python { .. } => "python",
+            Self::Unrecognized { kind } => kind,
+        }
+    }
+
+    /// The Python version for the V1 runtime, or `None` for an unknown kind.
+    pub fn python_version(&self) -> Option<&str> {
+        match self {
+            Self::Python { python_version, .. } => Some(python_version),
+            Self::Unrecognized { .. } => None,
+        }
+    }
+
+    /// The Python environment for the V1 runtime, or `None` for an unknown kind.
+    pub fn environment(&self) -> Option<&PythonEnvironmentSpec> {
+        match self {
+            Self::Python { environment, .. } => Some(environment),
+            Self::Unrecognized { .. } => None,
+        }
+    }
+
+    /// Non-secret environment variables, or `None` for an unknown kind.
+    pub fn env(&self) -> Option<&BTreeMap<String, String>> {
+        match self {
+            Self::Python { env, .. } => Some(env),
+            Self::Unrecognized { .. } => None,
+        }
+    }
+}
+
+#[derive(Deserialize)]
+struct PythonRuntimeWire {
+    kind: String,
+    #[serde(default)]
+    python_version: Option<String>,
+    #[serde(default)]
+    environment: Option<PythonEnvironmentSpec>,
+    #[serde(default)]
+    env: BTreeMap<String, String>,
+}
+
+impl<'de> Deserialize<'de> for PythonRuntimeSpec {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
+        let wire = PythonRuntimeWire::deserialize(deserializer)?;
+        if wire.kind == "python" {
+            Ok(Self::Python {
+                python_version: wire
+                    .python_version
+                    .ok_or_else(|| de::Error::missing_field("python_version"))?,
+                environment: wire
+                    .environment
+                    .ok_or_else(|| de::Error::missing_field("environment"))?,
+                env: wire.env,
+            })
+        } else {
+            Ok(Self::Unrecognized { kind: wire.kind })
+        }
+    }
+}
+
+impl Serialize for PythonRuntimeSpec {
+    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
+        #[derive(Serialize)]
+        struct PythonRuntimeRef<'a> {
+            kind: &'static str,
+            python_version: &'a str,
+            environment: &'a PythonEnvironmentSpec,
+            #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+            env: &'a BTreeMap<String, String>,
+        }
+
+        #[derive(Serialize)]
+        struct UnrecognizedRuntimeRef<'a> {
+            kind: &'a str,
+        }
+
+        match self {
+            Self::Python {
+                python_version,
+                environment,
+                env,
+            } => PythonRuntimeRef {
+                kind: "python",
+                python_version,
+                environment,
+                env,
+            }
+            .serialize(serializer),
+            Self::Unrecognized { kind } => UnrecognizedRuntimeRef { kind }.serialize(serializer),
+        }
+    }
+}
+
+/// Immutable Function version returned by the Enterprise catalog.
+///
+/// Scheduling resources, priority, concurrency, and retry policy belong to
+/// the submitting Job and are not part of this identity.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionVersion {
+    name: String,
+    version: String,
+    artifact: FunctionArtifact,
+    signature: FunctionSignature,
+    runtime: PythonRuntimeSpec,
+    runtime_digest: String,
+    environment_digest: String,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    required_secrets: Vec<String>,
+    created_at: String,
+}
+
+impl FunctionVersion {
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    pub fn version(&self) -> &str {
+        &self.version
+    }
+
+    pub fn artifact(&self) -> &FunctionArtifact {
+        &self.artifact
+    }
+
+    pub fn signature(&self) -> &FunctionSignature {
+        &self.signature
+    }
+
+    pub fn runtime(&self) -> &PythonRuntimeSpec {
+        &self.runtime
+    }
+
+    pub fn runtime_digest(&self) -> &str {
+        &self.runtime_digest
+    }
+
+    pub fn environment_digest(&self) -> &str {
+        &self.environment_digest
+    }
+
+    /// Required secret names. Resolved values exist only inside Sophon.
+    pub fn required_secrets(&self) -> &[String] {
+        &self.required_secrets
+    }
+
+    pub fn created_at(&self) -> &str {
+        &self.created_at
+    }
+}
+
+impl_json!(FunctionVersion);
+
+/// Encoded artifact bytes uploaded with a Function registration request.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionArtifactContent {
+    /// Encoding of `data`. V1 Python authoring uses `base64`.
+    pub encoding: String,
+    pub data: String,
+}
+
+/// Internal execution adapter selected for a Python callable artifact.
+///
+/// The adapter converts the public scalar callable to the Arrow batch ABI
+/// used by the remote executor. It is part of the request envelope, not a
+/// public batch-UDF authoring mode.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PythonAdapterSpec {
+    pub kind: String,
+    pub version: u32,
+}
+
+/// Python artifact uploaded while registering a Function.
+///
+/// Unlike [`FunctionArtifact`], which is the durable artifact identity
+/// returned by the catalog, this request value contains the encoded source
+/// bytes that Sophon must durably bake before publishing a FunctionVersion.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionArtifactRequest {
+    pub kind: String,
+    pub digest: String,
+    pub entrypoint: String,
+    pub content: FunctionArtifactContent,
+    pub adapter: PythonAdapterSpec,
+}
+
+/// Stable request envelope for remote immutable Function registration.
+///
+/// Secret values deliberately have no field in this model. The only secret
+/// material the client may send is the ordered set of names Sophon resolves
+/// inside the remote runtime.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionRegistrationRequest {
+    pub name: String,
+    pub artifact: FunctionArtifactRequest,
+    pub signature: FunctionSignature,
+    pub runtime: PythonRuntimeSpec,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub required_secrets: Vec<String>,
+}
+
+impl_json!(FunctionRegistrationRequest);
+
+/// Exact FunctionVersion reference embedded in applications and bindings.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionVersionRef {
+    pub name: String,
+    pub version: String,
+}
+
+/// Parameter binding in a FunctionApplication.
+///
+/// `kind` remains open until Python authoring is added in Slice 2. Slice 1
+/// freezes JSON integers, strings, booleans, nulls, arrays, and objects as
+/// canonical literal values. Floating-point literals are rejected until a
+/// language-neutral numeric representation is defined.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ApplicationInput {
+    pub parameter: String,
+    pub kind: String,
+    pub value: Value,
+}
+
+/// Pre-declaration application of an exact FunctionVersion.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct FunctionApplication {
+    function: FunctionVersionRef,
+    inputs: Vec<ApplicationInput>,
+    output: FunctionOutput,
+    group_id: String,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    columns: BTreeMap<String, String>,
+    #[serde(default, flatten, skip_serializing)]
+    unknown_fields: BTreeMap<String, Value>,
+    #[serde(default, skip)]
+    unknown_nested_fields: bool,
+}
+
+impl FunctionApplication {
+    pub fn function(&self) -> &FunctionVersionRef {
+        &self.function
+    }
+
+    pub fn inputs(&self) -> &[ApplicationInput] {
+        &self.inputs
+    }
+
+    pub fn output(&self) -> &FunctionOutput {
+        &self.output
+    }
+
+    pub fn group_id(&self) -> &str {
+        &self.group_id
+    }
+
+    pub fn columns(&self) -> &BTreeMap<String, String> {
+        &self.columns
+    }
+    /// Whether a newer writer attached application fields this client cannot
+    /// validate. Such applications remain readable but must not be declared.
+    pub fn has_unknown_fields(&self) -> bool {
+        !self.unknown_fields.is_empty() || self.unknown_nested_fields
+    }
+
+    /// Decode a remote application after validating the Slice 1 literal domain.
+    pub fn from_json(json: &str) -> Result<Self> {
+        let value: Value = from_json(json)?;
+        let has_unknown_nested_fields = application_has_unknown_nested_fields(&value);
+        let mut application: Self = serde_json::from_value(value).map_err(invalid_json)?;
+        application.unknown_nested_fields = has_unknown_nested_fields;
+        application
+            .inputs
+            .iter()
+            .try_for_each(|input| validate_literal(&input.value))?;
+        Ok(application)
+    }
+
+    /// Encode the application with bytewise-sorted JSON keys.
+    pub fn to_canonical_json(&self) -> Result<String> {
+        self.inputs
+            .iter()
+            .try_for_each(|input| validate_literal(&input.value))?;
+        canonical_json(self)
+    }
+}
+
+/// Stable table input bound to a registered parameter.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct InputBinding {
+    pub parameter: String,
+    pub field_id: i32,
+    pub field_path: String,
+    pub arrow_type: String,
+    pub nullable: bool,
+}
+
+/// Ordered result-field to table-field mapping for a grouped binding.
+///
+/// Assignment state is not part of the Slice 1 client contract. During the
+/// NULL transition there is no public Lance cell-flag identifier to persist.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OutputMapping {
+    pub result_field: String,
+    pub output_name: String,
+    pub output_field_id: i32,
+    pub output_ordinal: u32,
+    pub arrow_type: String,
+    pub nullable: bool,
+}
+
+/// Immutable grouped binding persisted by the Enterprise table service.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct FunctionBinding {
+    binding_id: String,
+    revision: u64,
+    function: FunctionVersionRef,
+    group_id: String,
+    inputs: Vec<InputBinding>,
+    outputs: Vec<OutputMapping>,
+    /// Exact Arrow schema presented to the Function, encoded with the Lance
+    /// Namespace Arrow JSON representation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    input_schema: Option<Value>,
+    /// Exact physical Arrow schema of the grouped table outputs.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    output_schema: Option<Value>,
+}
+
+impl FunctionBinding {
+    pub fn binding_id(&self) -> &str {
+        &self.binding_id
+    }
+
+    pub fn revision(&self) -> u64 {
+        self.revision
+    }
+
+    pub fn function(&self) -> &FunctionVersionRef {
+        &self.function
+    }
+
+    pub fn group_id(&self) -> &str {
+        &self.group_id
+    }
+
+    pub fn inputs(&self) -> &[InputBinding] {
+        &self.inputs
+    }
+
+    pub fn outputs(&self) -> &[OutputMapping] {
+        &self.outputs
+    }
+
+    pub fn input_schema(&self) -> Option<&Value> {
+        self.input_schema.as_ref()
+    }
+
+    pub fn output_schema(&self) -> Option<&Value> {
+        self.output_schema.as_ref()
+    }
+}
+
+impl_json!(FunctionBinding);
+
+/// Stable terminal result of a remote Function-column refresh Job.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RefreshColumnResult {
+    pub rows_assigned: u64,
+    pub rows_failed: u64,
+    pub rows_remaining: u64,
+    pub source_version: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub published_version: Option<u64>,
+}
+
+impl RefreshColumnResult {
+    /// Deprecated compatibility alias for `rows_assigned`.
+    pub fn rows_filled(&self) -> u64 {
+        self.rows_assigned
+    }
+
+    /// Deprecated compatibility alias for `published_version`.
+    pub fn version(&self) -> Option<u64> {
+        self.published_version
+    }
+}
+
+impl_json!(RefreshColumnResult);
@@ -6,6 +6,8 @@
 use std::sync::Arc;

 use async_trait::async_trait;
+use serde::de::DeserializeOwned;
+use serde_json::Value;
 use tokio::sync::watch;
 use tokio::task::{AbortHandle, JoinHandle};

@@ -19,43 +21,126 @@ pub(crate) trait JobHandle: Send + Sync {
        None
    }
    async fn status(&self) -> Result<String>;
-    async fn wait(&self) -> Result<()>;
+    async fn wait(&self) -> Result<TerminalResult>;
    async fn cancel(&self) -> Result<()>;
 }

+/// A backend-neutral successful terminal result.
+///
+/// Local operations do not carry a value. Remote operations may carry JSON
+/// that the public [`Job`] decodes according to its result type.
+pub(crate) struct TerminalResult {
+    #[allow(dead_code)] // Typed remote submit endpoints consume this after Slice 1.
+    value: Option<Value>,
+    #[allow(dead_code)] // Preserved so typed decode errors retain request correlation.
+    request_id: Option<String>,
+}
+
+impl TerminalResult {
+    pub(crate) fn local() -> Self {
+        Self {
+            value: None,
+            request_id: None,
+        }
+    }
+
+    pub(crate) fn remote(value: Option<Value>, request_id: String) -> Self {
+        Self {
+            value,
+            request_id: Some(request_id),
+        }
+    }
+
+    #[allow(dead_code)] // Exercised by the remote typed-result fixtures in Slice 1.
+    fn decode<T: DeserializeOwned>(self) -> Result<T> {
+        let request_id = self.request_id.unwrap_or_default();
+        let value = self.value.ok_or_else(|| Error::Http {
+            source: "successful typed job response did not contain a result".into(),
+            request_id: request_id.clone(),
+            status_code: None,
+        })?;
+        serde_json::from_value(value).map_err(|error| Error::Http {
+            source: format!("failed to parse typed job result: {error}").into(),
+            request_id,
+            status_code: None,
+        })
+    }
+}
+
+type ResultDecoder<T> = fn(TerminalResult) -> Result<T>;
+
+enum JobInner<T> {
+    Handle {
+        handle: Box<dyn JobHandle>,
+        decode: ResultDecoder<T>,
+    },
+    Completed(T),
+}
+
 /// A handle to an operation that may still be running.
 ///
 /// The operation may already be complete when the handle is created.
-pub struct Job {
-    handle: Option<Box<dyn JobHandle>>,
+pub struct Job<T = ()>
+where
+    T: Clone + Send + Sync + 'static,
+{
+    inner: JobInner<T>,
 }

-impl std::fmt::Debug for Job {
+impl<T> std::fmt::Debug for Job<T>
+where
+    T: Clone + Send + Sync + 'static,
+{
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Job")
            .field("id", &self.id())
-            .field("done", &self.handle.is_none())
+            .field("done", &matches!(self.inner, JobInner::Completed(_)))
            .finish()
    }
 }

-impl Job {
+impl Job<()> {
    /// A job whose operation finished before the handle was created.
    pub(crate) fn new_done() -> Self {
-        Self { handle: None }
+        Self {
+            inner: JobInner::Completed(()),
+        }
    }

    pub(crate) fn new(handle: Box<dyn JobHandle>) -> Self {
        Self {
-            handle: Some(handle),
+            inner: JobInner::Handle {
+                handle,
+                decode: |_| Ok(()),
+            },
        }
    }

-    /// A job running as a task in this process.
+    /// A unit-result job running as a task in this process.
    pub(crate) fn spawned(task: JoinHandle<Result<()>>) -> Self {
        Self::new(Box::new(SpawnedJob::new(task)))
    }
+}

+impl<T> Job<T>
+where
+    T: Clone + DeserializeOwned + Send + Sync + 'static,
+{
+    /// Construct a typed remote Job for a result-specific submit API.
+    pub(crate) fn new_typed(handle: Box<dyn JobHandle>) -> Self {
+        Self {
+            inner: JobInner::Handle {
+                handle,
+                decode: TerminalResult::decode::<T>,
+            },
+        }
+    }
+}
+
+impl<T> Job<T>
+where
+    T: Clone + Send + Sync + 'static,
+{
    /// Identifies the operation on the server that is running it.
    ///
    /// Returned for correlating with server logs or the jobs API. Operations
@@ -63,7 +148,10 @@ impl Job {
    /// value is opaque: parsing it or storing it to resume the job later is
    /// not supported.
    pub fn id(&self) -> Option<&str> {
-        self.handle.as_ref().and_then(|handle| handle.id())
+        match &self.inner {
+            JobInner::Handle { handle, .. } => handle.id(),
+            JobInner::Completed(_) => None,
+        }
    }

    /// The operation's current lifecycle state: "running", "finished",
@@ -73,9 +161,9 @@ impl Job {
    /// terminal failure state, or retry. States a newer server reports that
    /// this client version does not know pass through as-is.
    pub async fn status(&self) -> Result<String> {
-        match &self.handle {
-            None => Ok("finished".to_string()),
-            Some(handle) => handle.status().await,
+        match &self.inner {
+            JobInner::Handle { handle, .. } => handle.status().await,
+            JobInner::Completed(_) => Ok("finished".to_string()),
        }
    }

@@ -83,10 +171,10 @@ impl Job {
    ///
    /// Returns [`crate::Error::JobFailed`] if the operation failed and
    /// [`crate::Error::JobCancelled`] if it was cancelled.
-    pub async fn wait(&self) -> Result<()> {
-        match &self.handle {
-            None => Ok(()),
-            Some(handle) => handle.wait().await,
+    pub async fn wait(&self) -> Result<T> {
+        match &self.inner {
+            JobInner::Handle { handle, decode } => decode(handle.wait().await?),
+            JobInner::Completed(result) => Ok(result.clone()),
        }
    }

@@ -94,9 +182,9 @@ impl Job {
    ///
    /// Cancelling an operation that already finished is a no-op.
    pub async fn cancel(&self) -> Result<()> {
-        match &self.handle {
-            None => Ok(()),
-            Some(handle) => handle.cancel().await,
+        match &self.inner {
+            JobInner::Handle { handle, .. } => handle.cancel().await,
+            JobInner::Completed(_) => Ok(()),
        }
    }
 }
@@ -162,7 +250,7 @@ impl JobHandle for SpawnedJob {
        Ok(label.to_string())
    }

-    async fn wait(&self) -> Result<()> {
+    async fn wait(&self) -> Result<TerminalResult> {
        let mut outcome = self.outcome.clone();
        let settled = outcome
            .wait_for(|outcome| outcome.is_some())
@@ -172,7 +260,8 @@ impl JobHandle for SpawnedJob {
            })?
            .clone()
            .expect("wait_for returns once an outcome is set");
-        settled.into_result()
+        settled.into_result()?;
+        Ok(TerminalResult::local())
    }

    async fn cancel(&self) -> Result<()> {
--- a/Show More
+++ b/Show More