feat: add table branch support to remote tables and Python/TS bindings (#3540)

### Description
Adding branch support for RemoteTable by threading a branch selector
onto every operation the data plane accepts it on. Exposes the
currentBranch to nodejs and python through the bindings.

Matching the server handlers, the branch rides as:
- a `?branch=` query parameter for Arrow-body and query-only ops
(insert, merge_insert, multipart_*, version/list, drop_index)
- a `branch` field in the JSON body for everything else (count_rows,
query, update, delete, create_index, column ops, index list/stats,
stats, restore, describe, tags create/update)

A main-branch handle (`branch == None`) produces byte-identical requests
to before: no `branch` field and no `?branch=`

- Handle-per-branch: `create_branch` / `checkout_branch` return a new
handle with fresh caches and reset version/freshness state, mirroring
`NativeTable`.
- `create_branch` maps 409 to already-exists, 400 to invalid, and 404 to
not-found with source context, and sends without retry so the 409 stays
observable.
- `Ref` translation covers version, version-number (relative to the
handle's branch), and tag (resolved via the tags endpoint); `"main"` and
empty normalize to the main branch.
- Python branch handles persist their branch (and pinned version) across
pickle/fork, so a forked or pickled handle reopens on its branch rather
than silently reverting to main.

### Tests

- Rust mock tests per op category (query-param and body mechanisms,
branch CRUD, error paths, backward-compat).
- Python sync branch CRUD, `open_table(branch=)`, and a pickle
round-trip regression test.

nodejs/__test__/remote.test.ts

@@ -191,30 +191,36 @@ describe("remote connection", () => {
     );
   });
 
-  it("allows version on remote but rejects a non-main branch", async () => {
+  it("supports version time-travel and branches on remote", async () => {
     await withMockDatabase(
-      (_req, res) => {
-        // describe (table open + version validation) always succeeds
-        const body = JSON.stringify({
-          name: "t",
-          version: 2,
-          schema: { fields: [] },
-        });
+      (req, res) => {
+        const body = req.url?.includes("/branches/list")
+          ? JSON.stringify({
+              branches: {
+                exp: { parentVersion: 1, createAt: 1, manifestSize: 1 },
+              },
+            })
+          : JSON.stringify({ name: "t", version: 2, schema: { fields: [] } });
         res.writeHead(200, { "Content-Type": "application/json" }).end(body);
       },
       async (db) => {
-        // version-only (and "main" + version) is allowed: remote supports
-        // version time-travel even though it has no branches
-        await db.openTable("t", undefined, { version: 2 });
-        await db.openTable("t", undefined, { branch: "main", version: 2 });
+        // version-only (and "main" + version) time-travel the main chain
+        const v2 = await db.openTable("t", undefined, { version: 2 });
+        expect(v2.currentBranch()).toBeNull();
+        const mainV2 = await db.openTable("t", undefined, {
+          branch: "main",
+          version: 2,
+        });
+        expect(mainV2.currentBranch()).toBeNull();
 
-        // a non-main branch is rejected, with or without a version
-        await expect(
-          db.openTable("t", undefined, { branch: "exp" }),
-        ).rejects.toThrow(/branching/);
-        await expect(
-          db.openTable("t", undefined, { branch: "exp", version: 2 }),
-        ).rejects.toThrow(/branching/);
+        // a non-main branch opens a handle scoped to that branch
+        const exp = await db.openTable("t", undefined, { branch: "exp" });
+        expect(exp.currentBranch()).toBe("exp");
+        const expV2 = await db.openTable("t", undefined, {
+          branch: "exp",
+          version: 2,
+        });
+        expect(expV2.currentBranch()).toBe("exp");
       },
     );
   });

nodejs/__test__/table.test.ts

@@ -89,8 +89,11 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
       await table.add([{ id: 1 }]);
       expect(await table.countRows()).toBe(1);
 
+      expect(table.currentBranch()).toBeNull();
+
       // fork an isolated, writable branch from main
       const branch = await (await table.branches()).create("exp");
+      expect(branch.currentBranch()).toBe("exp");
       expect(await branch.countRows()).toBe(1);
       await branch.add([{ id: 2 }]);
       expect(await branch.countRows()).toBe(2);
@@ -109,6 +112,7 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
 
       // checkout returns a handle scoped to the branch's latest
       const checkedOut = await (await table.branches()).checkout("exp");
+      expect(checkedOut.currentBranch()).toBe("exp");
       expect(await checkedOut.countRows()).toBe(2);
 
       // delete removes it

nodejs/lancedb/table.ts

@@ -663,6 +663,14 @@ export abstract class Table {
    */
   abstract branches(): Promise<Branches>;
 
+  /**
+   * The branch this table handle is scoped to, or `null` for the main branch.
+   *
+   * A handle returned by {@link Branches.create} or {@link Branches.checkout}
+   * reports the branch it targets; a handle opened normally reports `null`.
+   */
+  abstract currentBranch(): string | null;
+
   /**
    * Restore the table to the currently checked out version
    *
@@ -1122,6 +1130,10 @@ export class LocalTable extends Table {
     return new Branches(await this.inner.branches());
   }
 
+  currentBranch(): string | null {
+    return this.inner.currentBranch() ?? null;
+  }
+
   async optimize(options?: Partial<OptimizeOptions>): Promise<OptimizeStats> {
     let cleanupOlderThanMs;
     if (

nodejs/src/table.rs

@@ -487,6 +487,12 @@ impl Table {
         })
     }
 
+    /// The branch this handle is scoped to, or `null` for the main branch.
+    #[napi]
+    pub fn current_branch(&self) -> napi::Result<Option<String>> {
+        Ok(self.inner_ref()?.current_branch())
+    }
+
     #[napi(catch_unwind)]
     pub async fn optimize(
         &self,