feat(sea): execute statements asynchronously (submit + poll) for Thrift runAsync parity

lib/sea/SeaNativeLoader.ts

@@ -64,6 +64,49 @@ export interface SeaNativeStatement {
   close(): Promise<void>;
 }
 
+/**
+ * Server-side execution status returned by `AsyncStatement.status()`.
+ * Mirrors the kernel `StatementStatus` enum collapsed to its variant
+ * name. `'Unknown'` is the forward-compat arm for kernel variants the
+ * binding doesn't recognise.
+ */
+export type SeaNativeStatementStatus =
+  | 'Pending'
+  | 'Running'
+  | 'Succeeded'
+  | 'Failed'
+  | 'Cancelled'
+  | 'Closed'
+  | 'Unknown';
+
+/**
+ * Typed surface for the opaque napi `AsyncResultHandle`. Returned by
+ * `AsyncStatement.awaitResult()`; same fetch-side surface as
+ * `SeaNativeStatement` but without `cancel()` / `close()` (the parent
+ * `AsyncStatement` owns server-side lifecycle).
+ */
+export interface SeaNativeAsyncResultHandle {
+  readonly statementId: string;
+  fetchNextBatch(): Promise<SeaArrowBatch | null>;
+  schema(): Promise<SeaArrowSchema>;
+}
+
+/**
+ * Typed surface for the opaque napi `AsyncStatement`. Returned by
+ * `Connection.submitStatement(...)`. The kernel submits with
+ * `wait_timeout=0s`, so the server returns a `statementId` while the
+ * query is still Pending/Running; JS drives polling via `status()`
+ * and materialises results with `awaitResult()`. This is the
+ * async-execution path the Thrift backend always uses (`runAsync`).
+ */
+export interface SeaNativeAsyncStatement {
+  readonly statementId: string;
+  status(): Promise<SeaNativeStatementStatus>;
+  awaitResult(): Promise<SeaNativeAsyncResultHandle>;
+  cancel(): Promise<void>;
+  close(): Promise<void>;
+}
+
 /**
  * Typed surface for the opaque napi `Connection` handle. Signatures
  * match `native/sea/index.d.ts` exactly as generated by napi-rs from
@@ -118,6 +161,18 @@ export interface SeaNativeConnection {
    */
   executeStatement(sql: string, options?: SeaNativeExecuteOptions): Promise<SeaNativeStatement>;
 
+  /**
+   * Submit a SQL statement asynchronously and return an
+   * `AsyncStatement` handle without blocking until the query
+   * finishes. The kernel sends `wait_timeout=0s`, so the server
+   * responds as soon as it has a `statementId` (Pending/Running);
+   * drive polling via the handle's `status()` / `awaitResult()`.
+   * Same option semantics as `executeStatement`; only the
+   * pending-vs-blocking return contract differs. This is the
+   * async-execution path the Thrift backend always uses.
+   */
+  submitStatement(sql: string, options?: SeaNativeExecuteOptions): Promise<SeaNativeAsyncStatement>;
+
   // ── Metadata methods ──────────────────────────────────────────────────
   /** All catalogs visible to the session. */
   listCatalogs(): Promise<SeaNativeStatement>;