feat(remote): route list_tables by what the server serves

`list_tables` asked for `/v2` unconditionally, which 404s against every server that is not a recent Phalanx -- including `RestAdapter`, the namespace spec's own reference implementation. The connection now asks `/v1/version` once, before its first listing, and keeps the one bit it needs: whether this server serves the `/v2` listing. Servers that do not keep the listing they have always served, which is correct and merely slower. The answer has to be known before the first page rather than learned from it. The two routes resume from different things, so a walk that started on one cannot finish on the other, and a walk that learned from its own first page would hand `/v2` a token `/v1` minted. What is cached is that bit, not the `ServerVersion` it came from. A server that sends no version header is indistinguishable from one running the oldest version we know of, so caching the version would let a stripped header switch off multivector, structural FTS, multipart write and blobs for the life of the connection. A missing header can only cost a listing its pushdown. `table_names` is untouched: it stays on `/v1`, where `page_token` is a table name to resume after that its callers build themselves.
chore: pin lance to the read_dir_page branch
2026-08-27 00:18:31 +00:00 · 2026-08-19 17:05:27 -07:00 · 2026-08-19 13:32:34 -07:00 · 2026-08-19 13:30:26 -07:00 · 2026-08-19 13:28:26 -07:00 · 2026-08-19 15:18:27 -05:00
68 changed files with 3977 additions and 183 deletions
@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.38.0-beta.0"
+current_version = "0.38.0-beta.2"
 parse = """(?x)
    (?P<major>0|[1-9]\\d*)\\.
    (?P<minor>0|[1-9]\\d*)\\.
@@ -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",
@@ -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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 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,23 @@ 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" }
+# TEMPORARY: `ObjectStore::read_dir_page` is not in a lance release yet, so these point at
+# lance-format/lance#8606 cherry-picked onto the v11.0.0-beta.15 tag. Put the tag back once that
+# PR has merged and shipped in a release.
+lance = { "version" = "=11.0.0-beta.15", default-features = false, "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-core = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-datagen = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-file = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-io = { "version" = "=11.0.0-beta.15", default-features = false, "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-index = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-linalg = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace-impls = { "version" = "=11.0.0-beta.15", default-features = false, "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-table = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-testing = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-datafusion = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-encoding = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-arrow = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
 ahash = "0.8"
 # Note that this one does not include pyarrow
 arrow = { version = "58.0.0", optional = false }
@@ -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" },
 ]

 # ---------------------------------------------------------------------------
@@ -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.2</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
@@ -529,6 +529,71 @@ Child namespace names and

 ***

+### listTables()
+
+#### listTables(options)
+
+```ts
+abstract listTables(options?): Promise<ListTablesResponse>
+```
+
+List a page of tables in this database.
+
+Results may be paginated. To retrieve subsequent pages, pass the
+`pageToken` returned by a previous call. A page may be shorter than
+`limit` without being the last one, so walk until the response carries no
+page token:
+
+```ts
+const names = [];
+let pageToken = undefined;
+do {
+  const page = await conn.listTables({ pageToken, limit: 100 });
+  names.push(...page.tables);
+  pageToken = page.pageToken;
+} while (pageToken);
+```
+
+##### Parameters
+
+* **options?**: `Partial`&lt;[`ListTablesOptions`](../interfaces/ListTablesOptions.md)&gt;
+    Pagination options
+    (`pageToken`, `limit`).
+
+##### Returns
+
+`Promise`&lt;[`ListTablesResponse`](../interfaces/ListTablesResponse.md)&gt;
+
+Table names and an optional token
+  for fetching the next page.
+
+#### listTables(namespacePath, options)
+
+```ts
+abstract listTables(namespacePath?, options?): Promise<ListTablesResponse>
+```
+
+List a page of tables in this database.
+
+##### Parameters
+
+* **namespacePath?**: `string`[]
+    The namespace path to list tables from
+    (defaults to root namespace)
+
+* **options?**: `Partial`&lt;[`ListTablesOptions`](../interfaces/ListTablesOptions.md)&gt;
+    Pagination options
+    (`pageToken`, `limit`).
+
+##### Returns
+
+`Promise`&lt;[`ListTablesResponse`](../interfaces/ListTablesResponse.md)&gt;
+
+Table names and an optional token
+  for fetching the next page.
+
+***
+
 ### openTable()

 ```ts
@@ -590,7 +655,7 @@ a "not supported" error.

 ***

-### tableNames()
+### ~~tableNames()~~

 #### tableNames(options)

@@ -612,6 +677,10 @@ Tables will be returned in lexicographical order.

 `Promise`&lt;`string`[]&gt;

+##### Deprecated
+
+Use [Connection.listTables](Connection.md#listtables) instead.
+
 #### tableNames(namespacePath, options)

 ```ts
@@ -634,3 +703,7 @@ Tables will be returned in lexicographical order.
 ##### Returns

 `Promise`&lt;`string`[]&gt;
+
+##### Deprecated
+
+Use [Connection.listTables](Connection.md#listtables) instead.
@@ -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,11 @@
 - [JobInfo](interfaces/JobInfo.md)
 - [ListNamespacesOptions](interfaces/ListNamespacesOptions.md)
 - [ListNamespacesResponse](interfaces/ListNamespacesResponse.md)
+- [ListTablesOptions](interfaces/ListTablesOptions.md)
+- [ListTablesResponse](interfaces/ListTablesResponse.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,33 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ListTablesOptions
+
+# Interface: ListTablesOptions
+
+## Properties
+
+### limit?
+
+```ts
+optional limit: number;
+```
+
+An upper bound on how many tables to return.
+
+A page may hold fewer than this and still not be the last one, so continue
+while the response carries a page token rather than while pages are full.
+
+***
+
+### pageToken?
+
+```ts
+optional pageToken: string;
+```
+
+Token from a previous response for pagination.
+
+The token is opaque: it carries whatever the database needs to resume, and
+callers should not construct or interpret one.
@@ -0,0 +1,23 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ListTablesResponse
+
+# Interface: ListTablesResponse
+
+## Properties
+
+### pageToken?
+
+```ts
+optional pageToken: string;
+```
+
+***
+
+### tables
+
+```ts
+tables: string[];
+```
@@ -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.
@@ -4,11 +4,16 @@

 [@lancedb/lancedb](../globals.md) / TableNamesOptions

-# Interface: TableNamesOptions
+# Interface: ~~TableNamesOptions~~
+
+## Deprecated
+
+Use [ListTablesOptions](ListTablesOptions.md) with [Connection.listTables](../classes/Connection.md#listtables)
+instead.

 ## Properties

-### limit?
+### ~~limit?~~

 ```ts
 optional limit: number;
@@ -18,7 +23,7 @@ An optional limit to the number of results to return.

 ***

-### startAfter?
+### ~~startAfter?~~

 ```ts
 optional startAfter: string;
@@ -52,6 +52,8 @@ listing a storage directory.

 ::: lancedb.table.Branches

+::: lancedb.LsmWriteSpec
+
 ## Expressions

 Type-safe expression builder for filters and projections. Use these instead
@@ -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.2</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.2</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.15</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.2"
 publish = false
 license.workspace = true
 description.workspace = true
@@ -4,7 +4,13 @@
 import { readdirSync } from "fs";
 import { Field, Float64, Schema } from "apache-arrow";
 import * as tmp from "tmp";
-import { Connection, Table, connect, connectNamespace } from "../lancedb";
+import {
+  Connection,
+  ListTablesResponse,
+  Table,
+  connect,
+  connectNamespace,
+} from "../lancedb";
 import { LocalTable } from "../lancedb/table";

 describe("when connecting", () => {
@@ -129,6 +135,56 @@ describe("given a connection", () => {
    expect(tables).toEqual(["b", "c"]);
  });

+  it("should list tables with a page token", async () => {
+    const db = await connect(tmpDir.name);
+
+    await db.createTable("b", [{ id: 1 }]);
+    await db.createTable("a", [{ id: 1 }]);
+    await db.createTable("c", [{ id: 1 }]);
+
+    const all = await db.listTables();
+    expect(all.tables).toEqual(["a", "b", "c"]);
+    expect(all.pageToken).toBeUndefined();
+
+    const first = await db.listTables({ limit: 1 });
+    expect(first.tables).toEqual(["a"]);
+    expect(first.pageToken).toBeDefined();
+
+    const second = await db.listTables({
+      limit: 1,
+      pageToken: first.pageToken,
+    });
+    expect(second.tables).toEqual(["b"]);
+  });
+
+  it("should visit every table exactly once when paging", async () => {
+    const db = await connect(tmpDir.name);
+
+    const created = ["a", "b", "c", "d", "e"];
+    for (const name of created) {
+      await db.createTable(name, [{ id: 1 }]);
+    }
+
+    const seen: string[] = [];
+    let pageToken: string | undefined = undefined;
+    do {
+      const page: ListTablesResponse = await db.listTables({
+        limit: 2,
+        pageToken,
+      });
+      seen.push(...page.tables);
+      pageToken = page.pageToken;
+    } while (pageToken);
+
+    expect(seen.sort()).toEqual(created);
+  });
+
+  it("should reject listTables on a closed connection", async () => {
+    const db = await connect(tmpDir.name);
+    db.close();
+    await expect(db.listTables()).rejects.toThrow("Connection is closed");
+  });
+
  it("should create tables in v2 mode", async () => {
    const db = await connect(tmpDir.name);
    const data = [...Array(10000).keys()].map((i) => ({ id: i }));
@@ -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(() => {
@@ -25,12 +25,14 @@ import type {
  JobDescription,
  JobInfo,
  ListNamespacesResponse,
+  ListTablesResponse,
 } from "./native";
 export type {
  CreateNamespaceResponse,
  DescribeNamespaceResponse,
  DropNamespaceResponse,
  ListNamespacesResponse,
+  ListTablesResponse,
 };
 import { sanitizeTable } from "./sanitize";
 import { LocalTable, Table } from "./table";
@@ -128,6 +130,10 @@ export interface OpenTableOptions {
  indexCacheSize?: number;
 }

+/**
+ * @deprecated Use {@link ListTablesOptions} with {@link Connection.listTables}
+ * instead.
+ */
 export interface TableNamesOptions {
  /**
   * If present, only return names that come lexicographically after the
@@ -141,6 +147,23 @@ export interface TableNamesOptions {
  limit?: number;
 }

+export interface ListTablesOptions {
+  /**
+   * Token from a previous response for pagination.
+   *
+   * The token is opaque: it carries whatever the database needs to resume, and
+   * callers should not construct or interpret one.
+   */
+  pageToken?: string;
+  /**
+   * An upper bound on how many tables to return.
+   *
+   * A page may hold fewer than this and still not be the last one, so continue
+   * while the response carries a page token rather than while pages are full.
+   */
+  limit?: number;
+}
+
 export interface ListNamespacesOptions {
  /** Token from a previous response for pagination. */
  pageToken?: string;
@@ -225,6 +248,7 @@ export abstract class Connection {
   * @param {Partial<TableNamesOptions>} options - options to control the
   * paging / start point (backwards compatibility)
   *
+   * @deprecated Use {@link Connection.listTables} instead.
   */
  abstract tableNames(options?: Partial<TableNamesOptions>): Promise<string[]>;
  /**
@@ -235,12 +259,54 @@ export abstract class Connection {
   * @param {Partial<TableNamesOptions>} options - options to control the
   * paging / start point
   *
+   * @deprecated Use {@link Connection.listTables} instead.
   */
  abstract tableNames(
    namespacePath?: string[],
    options?: Partial<TableNamesOptions>,
  ): Promise<string[]>;

+  /**
+   * List a page of tables in this database.
+   *
+   * Results may be paginated. To retrieve subsequent pages, pass the
+   * `pageToken` returned by a previous call. A page may be shorter than
+   * `limit` without being the last one, so walk until the response carries no
+   * page token:
+   *
+   * ```ts
+   * const names = [];
+   * let pageToken = undefined;
+   * do {
+   *   const page = await conn.listTables({ pageToken, limit: 100 });
+   *   names.push(...page.tables);
+   *   pageToken = page.pageToken;
+   * } while (pageToken);
+   * ```
+   *
+   * @param {Partial<ListTablesOptions>} options - Pagination options
+   *   (`pageToken`, `limit`).
+   * @returns {Promise<ListTablesResponse>} Table names and an optional token
+   *   for fetching the next page.
+   */
+  abstract listTables(
+    options?: Partial<ListTablesOptions>,
+  ): Promise<ListTablesResponse>;
+  /**
+   * List a page of tables in this database.
+   *
+   * @param {string[]} namespacePath - The namespace path to list tables from
+   *   (defaults to root namespace)
+   * @param {Partial<ListTablesOptions>} options - Pagination options
+   *   (`pageToken`, `limit`).
+   * @returns {Promise<ListTablesResponse>} Table names and an optional token
+   *   for fetching the next page.
+   */
+  abstract listTables(
+    namespacePath?: string[],
+    options?: Partial<ListTablesOptions>,
+  ): Promise<ListTablesResponse>;
+
  /**
   * Open a table in the database.
   * @param {string} name - The name of the table
@@ -531,6 +597,29 @@ export class LocalConnection extends Connection {
    );
  }

+  async listTables(
+    namespacePathOrOptions?: string[] | Partial<ListTablesOptions>,
+    options?: Partial<ListTablesOptions>,
+  ): Promise<ListTablesResponse> {
+    // Detect if first argument is namespacePath array or options object
+    let namespacePath: string[] | undefined;
+    let listTablesOptions: Partial<ListTablesOptions> | undefined;
+
+    if (Array.isArray(namespacePathOrOptions)) {
+      namespacePath = namespacePathOrOptions;
+      listTablesOptions = options;
+    } else {
+      namespacePath = undefined;
+      listTablesOptions = namespacePathOrOptions;
+    }
+
+    return this.inner.listTables(
+      namespacePath ?? [],
+      listTablesOptions?.pageToken,
+      listTablesOptions?.limit,
+    );
+  }
+
  async openTable(
    name: string,
    namespacePath?: string[],
@@ -75,11 +75,13 @@ export {
  Connection,
  CreateTableOptions,
  TableNamesOptions,
+  ListTablesOptions,
  OpenTableOptions,
  ListNamespacesOptions,
  CreateNamespaceOptions,
  DropNamespaceOptions,
  ListNamespacesResponse,
+  ListTablesResponse,
  CreateNamespaceResponse,
  DropNamespaceResponse,
  DescribeNamespaceResponse,
@@ -147,6 +149,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.2",
 	"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.2",
 	"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.2",
 	"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.2",
 	"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.2",
 	"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.2",
  "os": [
    "win32"
  ],
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-win32-x64-msvc",
-	"version": "0.38.0-beta.0",
+	"version": "0.38.0-beta.2",
 	"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.2",
  "main": "dist/index.js",
  "exports": {
    ".": "./dist/index.js",
@@ -36,6 +36,12 @@ pub struct ListNamespacesResponse {
    pub page_token: Option<String>,
 }

+#[napi(object)]
+pub struct ListTablesResponse {
+    pub tables: Vec<String>,
+    pub page_token: Option<String>,
+}
+
 #[napi(object)]
 pub struct CreateNamespaceResponse {
    pub properties: Option<HashMap<String, String>>,
@@ -189,6 +195,8 @@ impl Connection {

    /// List all tables in the dataset.
    #[napi(catch_unwind)]
+    // Deprecated in favour of `list_tables`, but still exposed to JavaScript.
+    #[allow(deprecated)]
    pub async fn table_names(
        &self,
        namespace_path: Option<Vec<String>>,
@@ -206,6 +214,29 @@ impl Connection {
        op.execute().await.default_error()
    }

+    /// List a page of tables in the database.
+    #[napi(catch_unwind)]
+    pub async fn list_tables(
+        &self,
+        namespace_path: Option<Vec<String>>,
+        page_token: Option<String>,
+        limit: Option<u32>,
+    ) -> napi::Result<ListTablesResponse> {
+        let mut op = self.get_inner()?.list_tables();
+        op = op.namespace(namespace_path.unwrap_or_default());
+        if let Some(page_token) = page_token {
+            op = op.page_token(page_token);
+        }
+        if let Some(limit) = limit {
+            op = op.limit(limit);
+        }
+        let resp = op.execute().await.default_error()?;
+        Ok(ListTablesResponse {
+            tables: resp.tables,
+            page_token: resp.page_token,
+        })
+    }
+
    /// Create table from a Apache Arrow IPC (file) buffer.
    ///
    /// Parameters:
@@ -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)]
@@ -1,6 +1,6 @@
 [package]
 name = "lancedb-python"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.2"
 publish = false
 edition.workspace = true
 description = "Python bindings for LanceDB"
@@ -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
@@ -518,6 +519,7 @@ __all__ = [
    "Job",
    "LanceDBConnection",
    "LanceNamespaceDBConnection",
+    "LsmWriteSpec",
    "RemoteDBConnection",
    "Session",
    "Table",
@@ -2235,6 +2235,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 +2257,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 +2334,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 +2681,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)
@@ -990,17 +990,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())
@@ -4801,7 +4801,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 +4846,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 +4855,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 +4864,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
@@ -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
@@ -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.
@@ -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):
@@ -121,6 +121,8 @@ impl Connection {
    }

    #[pyo3(signature = (namespace_path=None, start_after=None, limit=None))]
+    // Deprecated in favour of `list_tables`, but still exposed to Python.
+    #[allow(deprecated)]
    pub fn table_names(
        self_: PyRef<'_, Self>,
        namespace_path: Option<Vec<String>>,
@@ -522,14 +524,17 @@ impl Connection {
        let inner = self_.get_inner()?.clone();
        let py = self_.py();
        future_into_py(py, async move {
-            use lance_namespace::models::ListTablesRequest;
-            let request = ListTablesRequest {
-                id: namespace_path,
-                page_token,
-                limit: limit.map(|l| l as i32),
-                ..Default::default()
-            };
-            let response = inner.list_tables(request).await.infer_error()?;
+            let mut request = inner.list_tables();
+            if let Some(namespace_path) = namespace_path {
+                request = request.namespace(namespace_path);
+            }
+            if let Some(page_token) = page_token {
+                request = request.page_token(page_token);
+            }
+            if let Some(limit) = limit {
+                request = request.limit(limit);
+            }
+            let response = request.execute().await.infer_error()?;
            Python::attach(|py| -> PyResult<Py<PyDict>> {
                let dict = PyDict::new(py);
                dict.set_item("tables", response.tables)?;
@@ -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),
@@ -1,6 +1,6 @@
 [package]
 name = "lancedb"
-version = "0.38.0-beta.0"
+version = "0.38.0-beta.2"
 edition.workspace = true
 description = "LanceDB: A serverless, low-latency vector database for AI applications"
 license.workspace = true
@@ -27,7 +27,7 @@ async fn main() -> Result<()> {
    // --8<-- [end:connect]

    // --8<-- [start:list_names]
-    println!("{:?}", db.table_names().execute().await?);
+    println!("{:?}", db.list_tables().execute().await?.tables);
    // --8<-- [end:list_names]
    let tbl = create_table(&db).await?;
    create_index(&tbl).await?;
@@ -73,11 +73,13 @@ fn set_storage_options_provider(
 }

 /// A builder for configuring a [`Connection::table_names`] operation
+#[deprecated(note = "Use Connection::list_tables instead")]
 pub struct TableNamesBuilder {
    parent: Arc<dyn Database>,
    request: TableNamesRequest,
 }

+#[allow(deprecated)]
 impl TableNamesBuilder {
    fn new(parent: Arc<dyn Database>) -> Self {
        Self {
@@ -115,6 +117,57 @@ impl TableNamesBuilder {
    }
 }

+/// A builder for configuring a [`Connection::list_tables`] operation
+pub struct ListTablesBuilder {
+    parent: Arc<dyn Database>,
+    request: ListTablesRequest,
+}
+
+impl ListTablesBuilder {
+    fn new(parent: Arc<dyn Database>) -> Self {
+        Self {
+            parent,
+            request: ListTablesRequest {
+                // The root namespace is an empty path, not an absent one: a
+                // namespace-backed database rejects a request that names no namespace.
+                id: Some(Vec::new()),
+                ..Default::default()
+            },
+        }
+    }
+
+    /// Resume listing from a previous page.
+    ///
+    /// Pass the `page_token` from the previous [`ListTablesResponse`]. The token is
+    /// opaque: it carries whatever the database needs to resume, and callers should
+    /// not construct or interpret one. A response whose token is `None` or empty is
+    /// the end of the listing.
+    pub fn page_token(mut self, page_token: impl Into<String>) -> Self {
+        self.request.page_token = Some(page_token.into());
+        self
+    }
+
+    /// An upper bound on how many tables to return.
+    ///
+    /// A page may hold fewer than this and still not be the last one, so continue
+    /// while the response carries a page token rather than while pages are full.
+    pub fn limit(mut self, limit: u32) -> Self {
+        self.request.limit = Some(i32::try_from(limit).unwrap_or(i32::MAX));
+        self
+    }
+
+    /// Set the namespace path to list tables from. Defaults to the root namespace.
+    pub fn namespace(mut self, namespace_path: Vec<String>) -> Self {
+        self.request.id = Some(namespace_path);
+        self
+    }
+
+    /// Execute the list tables operation
+    pub async fn execute(self) -> Result<ListTablesResponse> {
+        self.parent.clone().list_tables(self.request).await
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct OpenTableBuilder {
    parent: Arc<dyn Database>,
@@ -414,7 +467,9 @@ impl Connection {
    /// under creation, may contain only uncommitted storage, or may be concurrently
    /// dropped before it is opened.
    ///
-    /// The parameters `page_token` and `limit` can be used to paginate the results
+    /// The parameters `start_after` and `limit` can be used to paginate the results
+    #[deprecated(note = "Use Connection::list_tables instead")]
+    #[allow(deprecated)]
    pub fn table_names(&self) -> TableNamesBuilder {
        TableNamesBuilder::new(self.internal.clone())
    }
@@ -652,9 +707,32 @@ impl Connection {
        self.internal.namespace_client_config().await
    }

-    /// List tables with pagination support
-    pub async fn list_tables(&self, request: ListTablesRequest) -> Result<ListTablesResponse> {
-        self.internal.list_tables(request).await
+    /// List the tables in the database, a page at a time
+    ///
+    /// ```
+    /// # use lancedb::Connection;
+    /// # async fn list_all(conn: &Connection) -> Result<Vec<String>, lancedb::Error> {
+    /// let mut names = Vec::new();
+    /// let mut token = None;
+    /// loop {
+    ///     let mut request = conn.list_tables().limit(100);
+    ///     if let Some(token) = token {
+    ///         request = request.page_token(token);
+    ///     }
+    ///     let page = request.execute().await?;
+    ///     names.extend(page.tables);
+    ///     // A page may be short without being the last one, so the token is what ends
+    ///     // the walk.
+    ///     token = page.page_token.filter(|token| !token.is_empty());
+    ///     if token.is_none() {
+    ///         break;
+    ///     }
+    /// }
+    /// # Ok(names)
+    /// # }
+    /// ```
+    pub fn list_tables(&self) -> ListTablesBuilder {
+        ListTablesBuilder::new(self.internal.clone())
    }

    /// Get the in-memory embedding registry.
@@ -1310,6 +1388,8 @@ mod test_utils {
 }

 #[cfg(test)]
+// `table_names` is deprecated but still supported, so its tests still call it.
+#[allow(deprecated)]
 mod tests {
    use arrow_schema::{DataType, Field, Schema};
    use lance_testing::datagen::{BatchGenerator, IncrementingInt32};
@@ -1652,6 +1732,75 @@ mod tests {
        assert_eq!(tables, names[..7]);
    }

+    #[tokio::test]
+    async fn test_list_tables_paginates() {
+        let tc = new_test_connection().await.unwrap();
+        if tc.is_remote {
+            // What resumes a page is the server's to decide, and asserting it here would be
+            // asserting the server's contract rather than this one.
+            return;
+        }
+        let db = tc.connection;
+        let schema = Arc::new(Schema::new(vec![Field::new("x", DataType::Int32, false)]));
+        let mut names = Vec::with_capacity(25);
+        for _ in 0..25 {
+            let name = uuid::Uuid::new_v4().to_string();
+            names.push(name.clone());
+            db.create_empty_table(name, schema.clone())
+                .execute()
+                .await
+                .unwrap();
+        }
+        names.sort();
+
+        let page = db.list_tables().limit(10).execute().await.unwrap();
+        assert_eq!(page.tables, names[..10]);
+        // The token is opaque and is not a table name: it is whatever resumes the store
+        // the database sits on, so a caller checks that there is one, not what it says.
+        assert!(page.page_token.is_some());
+
+        // Walking in pages has to reach every table exactly once, with nothing lost
+        // at a page boundary.
+        let mut seen = Vec::with_capacity(names.len());
+        let mut page_token = None;
+        loop {
+            let mut request = db.list_tables().limit(10);
+            if let Some(token) = page_token {
+                request = request.page_token(token);
+            }
+            let page = request.execute().await.unwrap();
+            seen.extend(page.tables);
+            page_token = page.page_token.filter(|token| !token.is_empty());
+            if page_token.is_none() {
+                break;
+            }
+        }
+        assert_eq!(seen, names);
+    }
+
+    #[tokio::test]
+    async fn test_list_tables_exhausted_has_no_token() {
+        let tc = new_test_connection().await.unwrap();
+        let db = tc.connection;
+        let schema = Arc::new(Schema::new(vec![Field::new("x", DataType::Int32, false)]));
+        for i in 0..3 {
+            db.create_empty_table(format!("table{i}"), schema.clone())
+                .execute()
+                .await
+                .unwrap();
+        }
+
+        // A limit the listing does not fill leaves no token behind.
+        let page = db.list_tables().limit(10).execute().await.unwrap();
+        assert_eq!(page.tables.len(), 3);
+        assert_eq!(page.page_token, None);
+
+        // Neither does one that exactly exhausts it.
+        let page = db.list_tables().limit(3).execute().await.unwrap();
+        assert_eq!(page.tables.len(), 3);
+        assert_eq!(page.page_token, None);
+    }
+
    #[tokio::test]
    async fn test_open_table() {
        let tc = new_test_connection().await.unwrap();
@@ -13,7 +13,7 @@ use lance::dataset::{ReadParams, WriteMode, builder::DatasetBuilder};
 use lance::io::{ObjectStore, ObjectStoreParams, WrappingObjectStore};
 use lance_datafusion::utils::StreamingWriteSource;
 use lance_file::version::LanceFileVersion;
-use lance_io::object_store::{StorageOptionsAccessor, StorageOptionsProvider};
+use lance_io::object_store::{ReadDirOptions, StorageOptionsAccessor, StorageOptionsProvider};
 use lance_table::io::commit::commit_handler_from_url;
 use object_store::local::LocalFileSystem;
 use snafu::ResultExt;
@@ -281,6 +281,21 @@ impl std::fmt::Display for ListingDatabase {
 }

 const LANCE_EXTENSION: &str = "lance";
+
+/// The table a listed child of the database names, or `None` if the child is not a table.
+///
+/// A table is the directory `<name>.lance`; a loose file or any other directory under the
+/// database prefix belongs to something else. `dir_suffix` is `.lance`, built once by the
+/// caller rather than per child.
+/// The table a listed child directory holds, or `None` if it is not a table at all.
+///
+/// Only directories are considered, so a loose object named like a table is not one.
+fn table_name(location: &object_store::path::Path, dir_suffix: &str) -> Option<String> {
+    location
+        .filename()?
+        .strip_suffix(dir_suffix)
+        .map(String::from)
+}
 const ENGINE: &str = "engine";
 const MIRRORED_STORE: &str = "mirroredStore";

@@ -988,53 +1003,75 @@ impl Database for ListingDatabase {
        Ok(f)
    }

+    /// List the tables in the database, a page at a time.
+    ///
+    /// The page token and the page size go into the object store's list request rather than
+    /// being applied to a full listing, so a page costs what the page holds and not what the
+    /// database holds. Stores with no paginated list API list the level in full and page it
+    /// locally, which is what every store did before.
+    ///
+    /// The token is opaque and is only meaningful to the store that issued it: it carries a
+    /// continuation token where the store has one. It is not a table name, and a caller must
+    /// not construct one. A page can be shorter than `limit` and still be followed by more, so
+    /// the token is what ends a walk.
+    ///
+    /// Tables come back in the order the store lists directories, which is by key. That
+    /// differs from sorting by name only between a name and one that extends it:
+    /// `users-archive` precedes `users`, because the `-` of `users-archive.lance` sorts below
+    /// the `.` of `users.lance`.
    async fn list_tables(&self, request: ListTablesRequest) -> Result<ListTablesResponse> {
        if request.id.as_ref().map(|v| !v.is_empty()).unwrap_or(false) {
            return self.namespace_database().list_tables(request).await;
        }
-        let mut f = self
-            .object_store
-            .read_dir(self.base_path.clone())
-            .await?
-            .iter()
-            .map(Path::new)
-            .filter(|path| {
-                let is_lance = path
-                    .extension()
-                    .and_then(|e| e.to_str())
-                    .map(|e| e == LANCE_EXTENSION);
-                is_lance.unwrap_or(false)
-            })
-            .filter_map(|p| p.file_stem().and_then(|s| s.to_str().map(String::from)))
-            .collect::<Vec<String>>();
-        f.sort();
+        let limit = request.limit.map(|limit| limit.max(0) as usize);
+        let dir_suffix = format!(".{LANCE_EXTENSION}");
+        let mut tables = Vec::new();
+        let mut page_token = request.page_token.filter(|token| !token.is_empty());

-        // Handle pagination with page_token
-        if let Some(ref page_token) = request.page_token {
-            let index = f
-                .iter()
-                .position(|name| name.as_str() > page_token.as_str())
-                .unwrap_or(f.len());
-            f.drain(0..index);
+        // A page of nothing: the store rejects a limit of zero, and no table was handed over
+        // for a token to resume after.
+        if limit == Some(0) {
+            return Ok(ListTablesResponse {
+                context: None,
+                tables,
+                page_token: None,
+            });
        }

-        // Determine if there's a next page
-        let next_page_token = if let Some(limit) = request.limit {
-            if f.len() > limit as usize {
-                let token = f[limit as usize].clone();
-                f.truncate(limit as usize);
-                Some(token)
-            } else {
-                None
+        loop {
+            // Ask only for what the page still has room for, so a database holding more
+            // than one page costs one request per page rather than one per table.
+            let listing = self
+                .object_store
+                .read_dir_page(
+                    self.base_path.clone(),
+                    ReadDirOptions {
+                        page_token: page_token.take(),
+                        limit: limit.map(|limit| limit - tables.len()),
+                    },
+                )
+                .await?;
+            page_token = listing.page_token;
+            // Only child directories can be tables, and the store already separates them
+            // out, so the objects in the page are not looked at.
+            tables.extend(
+                listing
+                    .result
+                    .common_prefixes
+                    .iter()
+                    .filter_map(|location| table_name(location, &dir_suffix)),
+            );
+            // Children that are not tables leave the page short of the limit, so keep
+            // going until the page is full or the database runs out.
+            if page_token.is_none() || limit.is_none_or(|limit| tables.len() >= limit) {
+                break;
            }
-        } else {
-            None
-        };
+        }

        Ok(ListTablesResponse {
            context: None,
-            tables: f,
-            page_token: next_page_token,
+            tables,
+            page_token,
        })
    }

@@ -1308,6 +1345,171 @@ mod tests {
    use tokio::sync::Barrier;
    use tokio::time::timeout;

+    async fn create_tables(db: &ListingDatabase, names: &[&str]) {
+        let schema = Arc::new(Schema::new(vec![Field::new("id", DataType::Int32, false)]));
+        for name in names {
+            db.create_table(CreateTableRequest {
+                name: name.to_string(),
+                namespace_path: vec![],
+                data: Box::new(RecordBatch::new_empty(schema.clone())) as Box<dyn Scannable>,
+                mode: CreateTableMode::Create,
+                write_options: Default::default(),
+                location: None,
+                namespace_client: None,
+            })
+            .await
+            .unwrap();
+        }
+    }
+
+    /// Every table in the database, taken `limit` at a time, which is how a caller walks a
+    /// listing: the token ends the walk, never a short page.
+    async fn walk(db: &ListingDatabase, limit: Option<i32>) -> Vec<String> {
+        let mut seen = Vec::new();
+        let mut page_token = None;
+        loop {
+            let page = db
+                .list_tables(ListTablesRequest {
+                    limit,
+                    page_token,
+                    ..Default::default()
+                })
+                .await
+                .unwrap();
+            seen.extend(page.tables);
+            page_token = page.page_token;
+            if page_token.is_none() {
+                return seen;
+            }
+            assert!(
+                seen.len() < 100,
+                "the walk is serving tables more than once"
+            );
+        }
+    }
+
+    /// Paging with the returned token has to visit every table exactly once, whatever the
+    /// page size, with nothing lost or repeated at a boundary.
+    #[rstest::rstest]
+    #[tokio::test]
+    async fn test_list_tables_pages_over_every_table_once(#[values(1, 2, 3, 5, 10)] limit: i32) {
+        let (_tempdir, db) = setup_database().await;
+        create_tables(&db, &["a", "b", "c", "d", "e"]).await;
+
+        assert_eq!(walk(&db, Some(limit)).await, vec!["a", "b", "c", "d", "e"]);
+    }
+
+    /// The token is opaque: it is whatever resumes the store the database sits on, not a
+    /// table name. Callers hand it back and nothing else.
+    ///
+    /// Nothing validates a token, so one invented by a caller is read as a position rather
+    /// than refused — which is why the token has to come back from a previous page.
+    #[tokio::test]
+    async fn test_the_page_token_is_not_a_table_name() {
+        let (_tempdir, db) = setup_database().await;
+        create_tables(&db, &["a", "b", "c"]).await;
+
+        let page = db
+            .list_tables(ListTablesRequest {
+                limit: Some(1),
+                ..Default::default()
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(page.tables, vec!["a"]);
+        let token = page.page_token.expect("two tables are still to come");
+        assert_ne!(token, "a");
+
+        // Handing it back is the only thing a caller does with it, and it resumes.
+        let rest = db
+            .list_tables(ListTablesRequest {
+                page_token: Some(token),
+                ..Default::default()
+            })
+            .await
+            .unwrap();
+        assert_eq!(rest.tables, vec!["b", "c"]);
+    }
+
+    /// A limit the listing does not fill leaves no token behind, so a caller paging by token
+    /// stops without asking for an empty page.
+    #[tokio::test]
+    async fn test_a_listing_that_runs_out_has_no_token() {
+        let (_tempdir, db) = setup_database().await;
+        create_tables(&db, &["a", "b"]).await;
+
+        let page = db
+            .list_tables(ListTablesRequest {
+                limit: Some(10),
+                ..Default::default()
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(page.tables, vec!["a", "b"]);
+        assert_eq!(page.page_token, None);
+    }
+
+    /// An empty page token means "from the start", which is how a client looping on a token
+    /// spells its first request.
+    #[tokio::test]
+    async fn test_an_empty_page_token_lists_from_the_start() {
+        let (_tempdir, db) = setup_database().await;
+        create_tables(&db, &["a", "b"]).await;
+
+        let page = db
+            .list_tables(ListTablesRequest {
+                page_token: Some(String::new()),
+                ..Default::default()
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(page.tables, vec!["a", "b"]);
+    }
+
+    /// Listing follows the order the object store lists directories in, so a name that
+    /// extends another comes first: the `-` of `users-archive.lance` sorts below the `.` of
+    /// `users.lance`. Pagination pushes its cursor into the list request, so it cannot report
+    /// an order other than the one it resumes in.
+    #[tokio::test]
+    async fn test_listing_order_follows_the_store_not_the_table_name() {
+        let (_tempdir, db) = setup_database().await;
+        create_tables(&db, &["users", "users-archive", "users.old"]).await;
+
+        assert_eq!(
+            walk(&db, None).await,
+            vec!["users-archive", "users", "users.old"]
+        );
+        // And paging reports the same order, so a walk sees each table once.
+        assert_eq!(
+            walk(&db, Some(1)).await,
+            vec!["users-archive", "users", "users.old"]
+        );
+    }
+
+    /// Only directories named `<name>.lance` are tables; loose files and other directories
+    /// under the database prefix are not. A page spent on them is filled from the next one,
+    /// so a page holding only non-tables does not read as an empty database.
+    #[tokio::test]
+    async fn test_listing_ignores_non_table_children() {
+        let (tempdir, db) = setup_database().await;
+        create_tables(&db, &["real"]).await;
+        std::fs::write(tempdir.path().join("aaa-loose.lance"), b"not a table").unwrap();
+        create_dir_all(tempdir.path().join("aaa-scratch")).unwrap();
+
+        let page = db
+            .list_tables(ListTablesRequest {
+                limit: Some(1),
+                ..Default::default()
+            })
+            .await
+            .unwrap();
+
+        assert_eq!(page.tables, vec!["real"]);
+    }
+
    async fn setup_database() -> (tempfile::TempDir, ListingDatabase) {
        let tempdir = tempdir().unwrap();
        let uri = tempdir.path().to_str().unwrap();
@@ -621,7 +621,10 @@ impl Database for LanceNamespaceDatabase {
 }

 #[cfg(test)]
-#[cfg(not(windows))] // TODO: support windows for lance-namespace
+#[cfg(not(windows))]
+// TODO: support windows for lance-namespace
+// `table_names` is deprecated but still supported, so its tests still call it.
+#[allow(deprecated)]
 mod tests {
    use super::*;
    use crate::connect_namespace;
@@ -7,6 +7,7 @@ use std::{fmt::Formatter, sync::Arc};

 use futures::{StreamExt, TryFutureExt, stream::BoxStream};
 use lance::io::WrappingObjectStore;
+use object_store::list::PaginatedListStore;
 use object_store::{
    CopyOptions, Error, GetOptions, GetResult, ListResult, MultipartUpload, ObjectMeta,
    ObjectStore, ObjectStoreExt, PutMultipartOptions, PutOptions, PutPayload, PutResult, Result,
@@ -187,6 +188,16 @@ impl WrappingObjectStore for MirroringObjectStoreWrapper {
            secondary: self.secondary.clone(),
        })
    }
+
+    // Only writes are mirrored, and a listing reads, so a pushed-down listing sees the same
+    // primary this wrapper would have read from.
+    fn wrap_paginated(
+        &self,
+        _store_prefix: &str,
+        original: Arc<dyn PaginatedListStore>,
+    ) -> Option<Arc<dyn PaginatedListStore>> {
+        Some(original)
+    }
 }

 // windows pathing can't be simply concatenated
@@ -57,6 +57,16 @@ impl WrappingObjectStore for IoStatsHolder {
            stats: self.0.clone(),
        })
    }
+
+    // This exists to count requests, so it gives up the pushdown rather than let a listing
+    // go around the counter.
+    fn wrap_paginated(
+        &self,
+        _store_prefix: &str,
+        _original: Arc<dyn object_store::list::PaginatedListStore>,
+    ) -> Option<Arc<dyn object_store::list::PaginatedListStore>> {
+        None
+    }
 }

 impl IoTrackingStore {
@@ -33,7 +33,7 @@ use super::client::{
    ClientConfig, HeaderProvider, HttpSend, RequestResultExt, RestfulLanceDbClient, Sender,
 };
 use super::table::RemoteTable;
-use super::util::parse_server_version;
+use super::util::{SERVER_VERSION_HEADER, parse_server_version};
 use super::{ARROW_STREAM_CONTENT_TYPE, extract_job_id};

 // Request structure for the remote clone table API
@@ -86,6 +86,10 @@ impl ServerVersion {
    pub fn support_blobs(&self) -> bool {
        self.0 >= semver::Version::new(0, 5, 0)
    }
+
+    pub fn support_paginated_list_tables(&self) -> bool {
+        self.0 >= semver::Version::new(0, 6, 0)
+    }
 }

 pub const OPT_REMOTE_PREFIX: &str = "remote_database_";
@@ -207,6 +211,14 @@ pub struct RemoteDatabase<S: HttpSend = Sender> {
    namespace_context_provider: Option<Arc<dyn DynamicContextProvider>>,
    /// TLS configuration for mTLS support
    tls_config: Option<super::client::TlsConfig>,
+    /// Whether this server serves the `/v2` table listing, learned once per connection.
+    ///
+    /// This holds the one answer it is asked for rather than the server version it was
+    /// derived from. A server that sends no version header is indistinguishable from one
+    /// running the oldest version we know of, and caching that as a version would let a
+    /// stripped header switch off multivector, structural FTS, multipart write and blobs for
+    /// the life of the connection. A missing header can only cost a listing its pushdown.
+    serves_paginated_list: tokio::sync::OnceCell<bool>,
 }

 #[derive(Clone)]
@@ -325,11 +337,45 @@ impl RemoteDatabase {
            namespace_headers,
            namespace_context_provider,
            tls_config: client_config.tls_config,
+            serves_paginated_list: tokio::sync::OnceCell::new(),
        })
    }
 }

 impl<S: HttpSend> RemoteDatabase<S> {
+    /// Whether this server serves the `/v2` table listing, asking it once per connection.
+    ///
+    /// The answer has to be known before the first listing rather than learned from it. The
+    /// two listing routes resume from different things, so a walk that started on one cannot
+    /// finish on the other, and a walk that learned the answer from its own first page would
+    /// do exactly that: page one goes to `/v1` for want of an answer, and page two, now
+    /// holding one, hands `/v2` a token `/v1` minted.
+    ///
+    /// `/v1/version` is the question. A server too old to serve it still answers, because the
+    /// version header is on its 404 as well, and a server that is not Phalanx sends no header
+    /// at all, which is the answer for every implementation of the namespace spec: they serve
+    /// `/v1` only.
+    async fn serves_paginated_list(&self) -> Result<bool> {
+        self.serves_paginated_list
+            .get_or_try_init(|| async {
+                let req = self.client.get("/v1/version");
+                // Deliberately not `check_response`: a 404 is a useful answer here, and its
+                // headers carry the version just as a 200's do.
+                let (request_id, rsp) = self.client.send(req).await?;
+                let Some(version) = rsp.headers().get(SERVER_VERSION_HEADER) else {
+                    return Ok(false);
+                };
+                let version = version.to_str().map_err(|e| Error::Http {
+                    source: e.into(),
+                    request_id,
+                    status_code: Some(rsp.status()),
+                })?;
+                Ok(ServerVersion::parse(version)?.support_paginated_list_tables())
+            })
+            .await
+            .copied()
+    }
+
    async fn submit_drop_table(
        &self,
        name: &str,
@@ -366,6 +412,7 @@ mod test_utils {
                namespace_headers: HashMap::new(),
                namespace_context_provider: None,
                tls_config: None,
+                serves_paginated_list: tokio::sync::OnceCell::new(),
            }
        }

@@ -388,6 +435,7 @@ mod test_utils {
                namespace_headers: config.extra_headers.clone(),
                namespace_context_provider,
                tls_config: config.tls_config.clone(),
+                serves_paginated_list: tokio::sync::OnceCell::new(),
            }
        }
    }
@@ -676,9 +724,17 @@ impl<S: HttpSend> Database for RemoteDatabase<S> {
    async fn list_tables(&self, request: ListTablesRequest) -> Result<ListTablesResponse> {
        let namespace_parts = request.id.as_deref().unwrap_or(&[]);
        let namespace_id = build_namespace_identifier(namespace_parts, &self.client.id_delimiter);
-        let mut req = self
-            .client
-            .get(&format!("/v1/namespace/{}/table/list", namespace_id));
+        // v1 takes a table name in `page_token` to resume after, which `table_names` callers
+        // build themselves from the last name they saw, so its meaning cannot change. Only a
+        // token the server minted can resume a listing in the store, and that contract needs a
+        // route no name-passing caller reaches. Servers that do not serve it keep the listing
+        // they have always served, which is correct and merely slower.
+        let path = if self.serves_paginated_list().await? {
+            format!("/v2/namespace/{}/table/list", namespace_id)
+        } else {
+            format!("/v1/namespace/{}/table/list", namespace_id)
+        };
+        let mut req = self.client.get(&path);

        if let Some(limit) = request.limit {
            req = req.query(&[("limit", limit)]);
@@ -1134,8 +1190,10 @@ impl From<StorageOptions> for RemoteOptions {
 }

 #[cfg(test)]
+// `table_names` is deprecated but still supported, so its tests still call it.
+#[allow(deprecated)]
 mod tests {
-    use super::{NamespaceHeaderProviderContext, build_cache_key};
+    use super::{NamespaceHeaderProviderContext, SERVER_VERSION_HEADER, build_cache_key};
    use std::collections::HashMap;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::sync::{Arc, OnceLock};
@@ -1664,6 +1722,125 @@ mod tests {
        assert_eq!(names, vec!["table1", "table2"]);
    }

+    /// Answer the capability probe with a version, or with no header at all for `None`.
+    fn version_probe(version: Option<&str>) -> http::Response<String> {
+        let builder = http::Response::builder().status(if version.is_some() { 200 } else { 404 });
+        match version {
+            Some(version) => builder
+                .header(SERVER_VERSION_HEADER, version)
+                .body(format!(r#"{{"version": "{version}"}}"#))
+                .unwrap(),
+            None => builder.body(String::new()).unwrap(),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_list_tables_uses_the_opaque_token_route() {
+        // `table_names` keeps /v1, where `page_token` is a table name to resume after. Only
+        // /v2 round-trips a server-minted token, so that is where this API has to go.
+        let conn = Connection::new_with_handler(|request| {
+            if request.url().path() == "/v1/version" {
+                return version_probe(Some("0.6.0"));
+            }
+            assert_eq!(request.url().path(), "/v2/namespace/$/table/list");
+            assert_eq!(request.url().query(), None);
+
+            http::Response::builder()
+                .status(200)
+                .body(r#"{"tables": ["table1"], "page_token": "opaque=="}"#.to_string())
+                .unwrap()
+        });
+        let page = conn.list_tables().execute().await.unwrap();
+        assert_eq!(page.tables, vec!["table1"]);
+        assert_eq!(page.page_token.as_deref(), Some("opaque=="));
+    }
+
+    #[tokio::test]
+    async fn test_list_tables_resumes_with_the_server_token() {
+        let conn = Connection::new_with_handler(|request| {
+            if request.url().path() == "/v1/version" {
+                return version_probe(Some("0.6.0"));
+            }
+            assert_eq!(request.url().path(), "/v2/namespace/ns1$ns2/table/list");
+            assert_eq!(request.url().query(), Some("page_token=opaque%3D%3D"));
+
+            http::Response::builder()
+                .status(200)
+                .body(r#"{"tables": ["table2"]}"#.to_string())
+                .unwrap()
+        });
+        let page = conn
+            .list_tables()
+            .namespace(vec!["ns1".to_string(), "ns2".to_string()])
+            .page_token("opaque==")
+            .execute()
+            .await
+            .unwrap();
+        assert_eq!(page.tables, vec!["table2"]);
+        assert_eq!(page.page_token, None);
+    }
+
+    #[tokio::test]
+    async fn test_a_server_without_the_route_keeps_the_v1_listing() {
+        // Every implementation of the namespace spec is this case: no version header, and only
+        // /v1 to serve. Asking it for /v2 would 404 a listing that /v1 can answer.
+        let conn = Connection::new_with_handler(|request| {
+            if request.url().path() == "/v1/version" {
+                return version_probe(None);
+            }
+            assert_eq!(request.url().path(), "/v1/namespace/$/table/list");
+
+            http::Response::builder()
+                .status(200)
+                .body(r#"{"tables": ["table1"]}"#.to_string())
+                .unwrap()
+        });
+        let page = conn.list_tables().execute().await.unwrap();
+        assert_eq!(page.tables, vec!["table1"]);
+    }
+
+    #[tokio::test]
+    async fn test_a_server_older_than_the_route_keeps_the_v1_listing() {
+        let conn = Connection::new_with_handler(|request| {
+            if request.url().path() == "/v1/version" {
+                return version_probe(Some("0.5.0"));
+            }
+            assert_eq!(request.url().path(), "/v1/namespace/$/table/list");
+
+            http::Response::builder()
+                .status(200)
+                .body(r#"{"tables": ["table1"]}"#.to_string())
+                .unwrap()
+        });
+        assert_eq!(
+            conn.list_tables().execute().await.unwrap().tables,
+            vec!["table1"]
+        );
+    }
+
+    #[tokio::test]
+    async fn test_the_probe_is_asked_once_per_connection() {
+        // A walk resumes from what its first page returned, so every page of it has to reach
+        // the same route. Re-asking per request would let a rolling deploy answer differently
+        // mid-walk and hand /v2 a token /v1 minted.
+        let probes = Arc::new(AtomicUsize::new(0));
+        let counted = probes.clone();
+        let conn = Connection::new_with_handler(move |request| {
+            if request.url().path() == "/v1/version" {
+                counted.fetch_add(1, Ordering::SeqCst);
+                return version_probe(Some("0.6.0"));
+            }
+            http::Response::builder()
+                .status(200)
+                .body(r#"{"tables": ["table1"]}"#.to_string())
+                .unwrap()
+        });
+        for _ in 0..3 {
+            conn.list_tables().execute().await.unwrap();
+        }
+        assert_eq!(probes.load(Ordering::SeqCst), 1);
+    }
+
    #[tokio::test]
    async fn test_table_names_with_nested_namespace() {
        // When namespace is vec!["ns1", "ns2"], should use /v1/namespace/ns1$ns2/table/list
@@ -2272,10 +2449,9 @@ mod tests {

            // List tables in the child namespace
            let list_response = conn
-                .list_tables(ListTablesRequest {
-                    id: Some(namespace.clone()),
-                    ..Default::default()
-                })
+                .list_tables()
+                .namespace(namespace.clone())
+                .execute()
                .await
                .expect("Failed to list tables");
            assert_eq!(list_response.tables, vec!["test_table"]);
@@ -2346,10 +2522,9 @@ mod tests {

            // List tables in the child namespace
            let list_response = conn
-                .list_tables(ListTablesRequest {
-                    id: Some(namespace.clone()),
-                    ..Default::default()
-                })
+                .list_tables()
+                .namespace(namespace.clone())
+                .execute()
                .await
                .unwrap();
            assert_eq!(list_response.tables.len(), 3);
@@ -47,10 +47,15 @@ pub fn stream_as_body(data: SendableRecordBatchStream) -> Result<reqwest::Body>
    Ok(reqwest::Body::wrap_stream(stream))
 }

+/// The response header a Phalanx server stamps its version onto.
+///
+/// A global layer adds it, so it is on error responses as well as successful ones.
+pub const SERVER_VERSION_HEADER: &str = "phalanx-version";
+
 pub fn parse_server_version(req_id: &str, rsp: &Response) -> Result<ServerVersion> {
    let version = rsp
        .headers()
-        .get("phalanx-version")
+        .get(SERVER_VERSION_HEADER)
        .map(|v| {
            let v = v.to_str().map_err(|e| crate::Error::Http {
                source: e.into(),
@@ -4065,6 +4065,16 @@ mod tests {
                parent_list_calls: self.parent_list_calls.clone(),
            })
        }
+
+        // The guard counts listings through `wrap`, so a pushed-down listing would slip
+        // past it.
+        fn wrap_paginated(
+            &self,
+            _store_prefix: &str,
+            _original: Arc<dyn object_store::list::PaginatedListStore>,
+        ) -> Option<Arc<dyn object_store::list::PaginatedListStore>> {
+            None
+        }
    }

    #[tokio::test]
@@ -4168,6 +4178,15 @@ mod tests {
            self.called.store(true, Ordering::Relaxed);
            original
        }
+
+        // Hands the store back untouched, so a listing has nothing to go around.
+        fn wrap_paginated(
+            &self,
+            _store_prefix: &str,
+            original: Arc<dyn object_store::list::PaginatedListStore>,
+        ) -> Option<Arc<dyn object_store::list::PaginatedListStore>> {
+            Some(original)
+        }
    }

    #[tokio::test]
@@ -12,7 +12,7 @@
 //! decides whether the fragment is staged at all -- a fragment where nothing
 //! would change stages nothing, which is what lets an expression yielding
 //! null settle instead of restaging forever. The second streams the
-//! fragment's physical rows into `write_column` a batch at a time, so peak
+//! fragment's physical rows into `write_columns` a batch at a time, so peak
 //! memory is bounded by a scan batch. The expression is evaluated by this
 //! module, never through a projection alias, and only over rows being
 //! filled: every other row -- deleted, or already holding a value -- has its
@@ -67,7 +67,7 @@ pub(crate) async fn execute_refresh_column(
        .ok_or_else(|| Error::ColumnNotFound {
            name: column.to_string(),
        })?;
-    // The dataset's own field, so the identity write_column checks against the
+    // The dataset's own field, so the identity write_columns checks against the
    // manifest holds by construction.
    let column_schema = LanceSchema {
        fields: vec![field.clone()],
@@ -83,7 +83,7 @@ pub(crate) async fn execute_refresh_column(
        }
        rows_filled += gained;
        let values = fill_stream(&dataset, &fragment, bound.clone(), column).await?;
-        replacements.push(fragment.write_column(values, &column_schema).await?);
+        replacements.push(fragment.write_columns(values, &column_schema).await?);
    }

    if replacements.is_empty() {
@@ -117,8 +117,8 @@ async fn test_minio_lifecycle() -> Result<()> {
    let row_count = table.count_rows(None).await?;
    assert_eq!(row_count, 3);

-    let table_names = db.table_names().execute().await?;
-    assert_eq!(table_names, vec!["test_table"]);
+    let tables = db.list_tables().execute().await?.tables;
+    assert_eq!(tables, vec!["test_table"]);

    // Re-open the table
    let table = db.open_table("test_table").execute().await?;