sea-auth-u2m: address round-1 M2M review parity — shared fakeBinding helper, doc + loader cleanup

Ports the M2M-side round-1 review fixes (commit 88d7d21 on
sea-auth-m2m) onto the U2M worktree so the two branches stay aligned
in review quality. The U2M-specific work in 5eba37f is unchanged;
this commit is pure cleanup applied across all three SEA-auth test
files (PAT / M2M / U2M).

- Extracted `makeFakeBinding()` to
  `tests/unit/sea/_helpers/fakeBinding.ts` and refactored all three
  auth-*.test.ts files to import it. The U2M-worktree commit had
  THREE copies of the closure (the third was the cause for the
  bloat reviewer's "rule of three" call-out that the M2M-worktree
  fixup was meant to forestall).
- Dropped the unused `SeaAuthMode` type alias from `SeaAuth.ts` —
  zero callers; inlined literals already power the discriminated
  union.
- Tightened `SeaNativeBinding.openSession` parameter type to consume
  the discriminated `SeaNativeConnectionOptions` union from
  `SeaAuth.ts`, restoring compile-time per-mode field enforcement
  at the FFI seam.
- Augmented the Rust `AuthMode` doc-comment with the napi-emission
  explanation (PascalCase verbatim, not kebab-case) plus the
  cross-reference reminder to extend `open_session()`'s match on
  every new variant.
- Added the const-enum hazard note to `SeaNativeConnectionOptions`'
  doc-comment, locking in the duplicated-literal pattern as
  deliberate (importing the napi `const enum AuthMode` breaks
  `isolatedModules`).
- Cleaned up the conditional-type-cast lobotomy in `auth-pat.test.ts`
  on the token-provider fixture; plain `as any` + eslint-disable.

Skipped findings (same justification as M2M-worktree commit):
F-3 borderline error-class taxonomy, F-4 cosmetic arg-order,
F-5 redundant comment-anchor (compiler already enforces), F-8 null
vs undefined paranoia, F-9 mocha named-function style.

Tests:
- Unit: 55/55 pass (same count as 5eba37f — pure restructure).
- Native build: clean (1m04s release profile).
- Type-check: clean (tsc --noEmit).

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

lib/sea/SeaAuth.ts

@@ -16,14 +16,6 @@ import { ConnectionOptions } from '../contracts/IDBSQLClient';
 import AuthenticationError from '../errors/AuthenticationError';
 import HiveDriverError from '../errors/HiveDriverError';
 
-/**
- * Auth-mode discriminant value crossing the napi boundary. The string
- * literals are what napi-rs emits from the `#[napi(string_enum)] AuthMode`
- * enum at `native/sea/src/database.rs` — they MUST match the variant
- * names verbatim (`'Pat'`, `'OAuthM2m'`, `'OAuthU2m'`).
- */
-export type SeaAuthMode = 'Pat' | 'OAuthM2m' | 'OAuthU2m';
-
 /**
  * Default local listener port for the U2M authorization-code callback.
  * Hardcoded here so the override of the kernel default (8020) to the
@@ -47,6 +39,15 @@ const U2M_DEFAULT_REDIRECT_PORT = 8030;
  * - `'OAuthU2m'`  → `oauthRedirectPort` overrides the kernel default;
  *                   everything else (client_id, scopes, callback timeout,
  *                   token_url_override) uses kernel defaults.
+ *
+ * The `authMode` string literals MUST match the napi-emitted `AuthMode`
+ * variant names verbatim (`'Pat'`, `'OAuthM2m'`, `'OAuthU2m'` — napi-rs's
+ * `#[napi(string_enum)]` without an explicit case option emits the
+ * Rust variant identifier as-is). We duplicate the values here instead
+ * of importing `AuthMode` from `native/sea/index.d.ts` because that
+ * file declares `AuthMode` as `export const enum`, which is
+ * incompatible with `isolatedModules` and a runtime-coupling hazard.
+ * The Rust source of truth lives at `native/sea/src/database.rs`.
  */
 export type SeaNativeConnectionOptions =
   | {

lib/sea/SeaNativeLoader.ts

@@ -26,13 +26,13 @@
 import type {
   Connection as NativeConnection,
   Statement as NativeStatement,
-  ConnectionOptions,
   ExecuteOptions,
   ArrowBatch,
   ArrowSchema,
 } from '@sea-native';
+import type { SeaNativeConnectionOptions } from './SeaAuth';
 
-export type { ConnectionOptions, ExecuteOptions, ArrowBatch, ArrowSchema };
+export type { ExecuteOptions, ArrowBatch, ArrowSchema, SeaNativeConnectionOptions };
 export type Connection = NativeConnection;
 export type Statement = NativeStatement;
 
@@ -44,28 +44,18 @@ export type SeaExecuteOptions = ExecuteOptions;
 export type SeaArrowBatch = ArrowBatch;
 export type SeaArrowSchema = ArrowSchema;
 
-/**
- * Discriminated session-open options. Mirrors the auto-generated
- * `ConnectionOptions` in `native/sea/index.d.ts` as it lands across
- * the auth PRs (PAT today; OAuth M2M + U2M after the kernel-side
- * OAuth surface ships). Kept permissive (all OAuth fields optional)
- * so the JS adapter's auth-union narrows correctly without three
- * overloads on this method.
- */
-export interface SeaOpenSessionOptions {
-  hostName: string;
-  httpPath: string;
-  authMode: 'Pat' | 'OAuthM2m' | 'OAuthU2m';
-  token?: string;
-  oauthClientId?: string;
-  oauthClientSecret?: string;
-  oauthRedirectPort?: number;
-}
-
 export interface SeaNativeBinding {
   version(): string;
-  /** Open a session over PAT, OAuth M2M, or OAuth U2M auth. */
-  openSession(opts: SeaOpenSessionOptions): Promise<NativeConnection>;
+  /**
+   * Open a session over PAT, OAuth M2M, or OAuth U2M auth. Returns an
+   * opaque Connection. The discriminated `SeaNativeConnectionOptions`
+   * union from `SeaAuth` is the source of truth for the per-mode
+   * required fields, so the loader-seam enforces the same compile-time
+   * check the adapter applies — a caller can't bypass
+   * `buildSeaConnectionOptions` and pass, say, `{ authMode: 'Pat' }`
+   * with no token.
+   */
+  openSession(opts: SeaNativeConnectionOptions): Promise<NativeConnection>;
   Connection: typeof NativeConnection;
   Statement: typeof NativeStatement;
 }
@@ -115,6 +105,7 @@ function tryLoad(): SeaNativeBinding | undefined {
     cachedError = new Error(`SEA native binding failed to load with non-standard error: ${String(err)}`);
     return undefined;
   }
+}
 
 /**
  * Returns the loaded native binding. Throws a structured error if

native/sea/index.d.ts

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { SeaNativeBinding } from '../../../../lib/sea/SeaNativeLoader';
+
+export interface RecordedCall {
+  method: string;
+  args: unknown[];
+}
+
+export interface FakeBinding {
+  binding: SeaNativeBinding;
+  calls: RecordedCall[];
+}
+
+/**
+ * Build a fake `SeaNativeBinding` that records every `openSession` call
+ * and returns a `Connection` whose `close()` is also recorded. Shared
+ * across the SEA auth unit-test files (PAT / M2M / U2M / future flows)
+ * so the closure shape lives in exactly one place.
+ *
+ * No real native code runs — the fake is structural-typing-only.
+ */
+export function makeFakeBinding(): FakeBinding {
+  const calls: RecordedCall[] = [];
+
+  const fakeConnection = {
+    async executeStatement() {
+      throw new Error('not used in this test');
+    },
+    async close() {
+      calls.push({ method: 'connection.close', args: [] });
+    },
+  };
+
+  const binding: SeaNativeBinding = {
+    version() {
+      return 'fake-binding';
+    },
+    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
+      calls.push({ method: 'openSession', args: [opts] });
+      return fakeConnection as unknown;
+    },
+    Connection: function FakeConnection() {} as unknown as Function,
+    Statement: function FakeStatement() {} as unknown as Function,
+  };
+
+  return { binding, calls };
+}

tests/unit/sea/_helpers/fakeBinding.ts

@@ -15,37 +15,10 @@
 import { expect } from 'chai';
 import SeaBackend from '../../../lib/sea/SeaBackend';
 import { buildSeaConnectionOptions } from '../../../lib/sea/SeaAuth';
-import { SeaNativeBinding } from '../../../lib/sea/SeaNativeLoader';
 import { ConnectionOptions } from '../../../lib/contracts/IDBSQLClient';
 import AuthenticationError from '../../../lib/errors/AuthenticationError';
 import HiveDriverError from '../../../lib/errors/HiveDriverError';
-
-function makeFakeBinding() {
-  const calls: Array<{ method: string; args: unknown[] }> = [];
-
-  const fakeConnection = {
-    async executeStatement() {
-      throw new Error('not used in this test');
-    },
-    async close() {
-      calls.push({ method: 'connection.close', args: [] });
-    },
-  };
-
-  const binding: SeaNativeBinding = {
-    version() {
-      return 'fake-binding';
-    },
-    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
-      calls.push({ method: 'openSession', args: [opts] });
-      return fakeConnection as unknown;
-    },
-    Connection: function FakeConnection() {} as unknown as Function,
-    Statement: function FakeStatement() {} as unknown as Function,
-  };
-
-  return { binding, calls };
-}
+import { makeFakeBinding } from './_helpers/fakeBinding';
 
 describe('SeaAuth + SeaBackend — OAuth M2M auth flow', () => {
   describe('buildSeaConnectionOptions', () => {

tests/unit/sea/auth-m2m.test.ts

@@ -99,10 +99,8 @@ describe('SeaAuth — PAT auth options builder', () => {
         host: 'example.cloud.databricks.com',
         path: '/sql/1.0/warehouses/abc',
         authType: 'token-provider',
-        tokenProvider: { getToken: async () => 'tok' } as unknown as ConnectionOptions extends infer T
-          ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            any
-          : never,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        tokenProvider: { getToken: async () => 'tok' } as any,
       };
 
       expect(() => buildSeaConnectionOptions(opts)).to.throw(

tests/unit/sea/auth-pat.test.ts

@@ -15,36 +15,9 @@
 import { expect } from 'chai';
 import SeaBackend from '../../../lib/sea/SeaBackend';
 import { buildSeaConnectionOptions } from '../../../lib/sea/SeaAuth';
-import { SeaNativeBinding } from '../../../lib/sea/SeaNativeLoader';
 import { ConnectionOptions } from '../../../lib/contracts/IDBSQLClient';
 import HiveDriverError from '../../../lib/errors/HiveDriverError';
-
-function makeFakeBinding() {
-  const calls: Array<{ method: string; args: unknown[] }> = [];
-
-  const fakeConnection = {
-    async executeStatement() {
-      throw new Error('not used in this test');
-    },
-    async close() {
-      calls.push({ method: 'connection.close', args: [] });
-    },
-  };
-
-  const binding: SeaNativeBinding = {
-    version() {
-      return 'fake-binding';
-    },
-    async openSession(opts: Parameters<SeaNativeBinding['openSession']>[0]) {
-      calls.push({ method: 'openSession', args: [opts] });
-      return fakeConnection as unknown;
-    },
-    Connection: function FakeConnection() {} as unknown as Function,
-    Statement: function FakeStatement() {} as unknown as Function,
-  };
-
-  return { binding, calls };
-}
+import { makeFakeBinding } from './_helpers/fakeBinding';
 
 describe('SeaAuth + SeaBackend — OAuth U2M auth flow', () => {
   describe('buildSeaConnectionOptions', () => {