feat(sea): enrich kernel error mapping with displayMessage/diagnosticInfo/errorDetailsJson

The napi error envelope already emits displayMessage / diagnosticInfo /
errorDetailsJson, but SeaErrorMapping.buildKernelMetadata dropped them. Surface
them under kernelMetadata so SEA stays at parity with:
- Thrift, which carries the same data via OperationStateError.response
  (TGetOperationStatusResp.displayMessage / .errorMessage / .errorDetailsJson)
- the Python use_kernel connector, which forwards all of them onto its exceptions

Also make the kernelMetadata attach-guard a key-count check so future fields are
covered automatically. Adds unit tests incl. explicit Thrift-parity assertions.

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

Author: msrathore-db

lib/sea/SeaErrorMapping.ts

@@ -68,6 +68,18 @@ export interface KernelMetadata {
   httpStatus?: number;
   retryable?: boolean;
   queryId?: string;
+  /**
+   * Rich server-error diagnostics from the SEA terminal-error payload. These
+   * mirror the fields the **Thrift** backend already surfaces via
+   * `OperationStateError.response` (`TGetOperationStatusResp.displayMessage` /
+   * `.errorMessage` / `.errorDetailsJson`) and that the Python `use_kernel`
+   * connector forwards onto its exceptions — so SEA stays at parity rather
+   * than dropping them. Kernel sources: `Error.display_message` /
+   * `.diagnostic_info` / `.error_details_json`.
+   */
+  displayMessage?: string;
+  diagnosticInfo?: string;
+  errorDetailsJson?: string;
 }
 
 /**
@@ -209,6 +221,16 @@ function buildKernelMetadata(parsed: Record<string, unknown>): KernelMetadata {
   if (typeof parsed.queryId === 'string') {
     meta.queryId = parsed.queryId;
   }
+  // Rich diagnostics — Thrift/Python parity (were previously dropped).
+  if (typeof parsed.displayMessage === 'string') {
+    meta.displayMessage = parsed.displayMessage;
+  }
+  if (typeof parsed.diagnosticInfo === 'string') {
+    meta.diagnosticInfo = parsed.diagnosticInfo;
+  }
+  if (typeof parsed.errorDetailsJson === 'string') {
+    meta.errorDetailsJson = parsed.errorDetailsJson;
+  }
   return meta;
 }
 
@@ -288,14 +310,9 @@ export function decodeNapiKernelError(err: unknown): Error {
   const meta = buildKernelMetadata(envelope);
   // Skip the namespace attachment entirely when no fields validated
   // through — keeps `err.kernelMetadata` absent rather than `{}` for
-  // simple envelopes (the common case).
-  if (
-    meta.errorCode !== undefined ||
-    meta.vendorCode !== undefined ||
-    meta.httpStatus !== undefined ||
-    meta.retryable !== undefined ||
-    meta.queryId !== undefined
-  ) {
+  // simple envelopes (the common case). Key-count check so new
+  // `KernelMetadata` fields are covered automatically.
+  if (Object.keys(meta).length > 0) {
     defineErrorMetadata(jsErr, 'kernelMetadata', meta);
   }
   return jsErr;

tests/unit/sea/error-mapping.test.ts

@@ -1,5 +1,11 @@
 import { expect } from 'chai';
-import { mapKernelErrorToJsError, KernelErrorCode, KernelErrorShape } from '../../../lib/sea/SeaErrorMapping';
+import {
+  mapKernelErrorToJsError,
+  decodeNapiKernelError,
+  KernelErrorCode,
+  KernelErrorShape,
+  ErrorWithSqlState,
+} from '../../../lib/sea/SeaErrorMapping';
 import HiveDriverError from '../../../lib/errors/HiveDriverError';
 import AuthenticationError from '../../../lib/errors/AuthenticationError';
 import OperationStateError, { OperationStateErrorCode } from '../../../lib/errors/OperationStateError';
@@ -219,3 +225,90 @@ describe('SeaErrorMapping.mapKernelErrorToJsError', () => {
     });
   });
 });
+
+describe('SeaErrorMapping.decodeNapiKernelError — diagnostics enrichment (Thrift/Python parity)', () => {
+  // The wire sentinel the napi binding prefixes onto structured kernel errors
+  // (mirrors `__databricks_error__:` in SeaErrorMapping.ts / native/sea/src/error.rs).
+  const SENTINEL = '__databricks_error__:';
+  const envelope = (fields: Record<string, unknown>): Error => new Error(SENTINEL + JSON.stringify(fields));
+
+  it('surfaces displayMessage / diagnosticInfo / errorDetailsJson in kernelMetadata (were dropped before)', () => {
+    const err = decodeNapiKernelError(
+      envelope({
+        code: 'SqlError',
+        message: '[TABLE_OR_VIEW_NOT_FOUND] table not found',
+        sqlState: '42P01',
+        errorCode: 'TABLE_OR_VIEW_NOT_FOUND',
+        vendorCode: 0,
+        displayMessage: 'TABLE_OR_VIEW_NOT_FOUND: `main`.`x` cannot be found',
+        diagnosticInfo: 'org.apache.spark.sql.AnalysisException: ...',
+        errorDetailsJson: '{"errorClass":"TABLE_OR_VIEW_NOT_FOUND"}',
+      }),
+    ) as ErrorWithSqlState;
+
+    // Class parity with Thrift: a server SQL failure → OperationStateError(Error).
+    expect(err).to.be.instanceOf(OperationStateError);
+    expect((err as OperationStateError).errorCode).to.equal(OperationStateErrorCode.Error);
+
+    // The three previously-dropped diagnostics are now surfaced.
+    expect(err.kernelMetadata?.displayMessage).to.equal('TABLE_OR_VIEW_NOT_FOUND: `main`.`x` cannot be found');
+    expect(err.kernelMetadata?.diagnosticInfo).to.match(/AnalysisException/);
+    expect(err.kernelMetadata?.errorDetailsJson).to.equal('{"errorClass":"TABLE_OR_VIEW_NOT_FOUND"}');
+  });
+
+  it('keeps the existing envelope fields alongside the new diagnostics', () => {
+    const err = decodeNapiKernelError(
+      envelope({
+        code: 'SqlError',
+        message: 'boom',
+        sqlState: '42000',
+        errorCode: 'PARSE_SYNTAX_ERROR',
+        vendorCode: 1234,
+        httpStatus: 400,
+        retryable: false,
+        queryId: '01ef-abcd',
+        displayMessage: 'Syntax error',
+      }),
+    ) as ErrorWithSqlState;
+    expect(err.sqlState).to.equal('42000');
+    expect(err.kernelMetadata?.errorCode).to.equal('PARSE_SYNTAX_ERROR');
+    expect(err.kernelMetadata?.vendorCode).to.equal(1234);
+    expect(err.kernelMetadata?.queryId).to.equal('01ef-abcd');
+    expect(err.kernelMetadata?.displayMessage).to.equal('Syntax error');
+  });
+
+  it('attaches kernelMetadata even when ONLY a diagnostic field is present', () => {
+    // Previously the attach-guard enumerated only errorCode/vendorCode/httpStatus/
+    // retryable/queryId, so a diagnostics-only envelope dropped them silently.
+    const err = decodeNapiKernelError(
+      envelope({ code: 'Internal', message: 'kaboom', diagnosticInfo: 'stack trace here' }),
+    ) as ErrorWithSqlState;
+    expect(err.kernelMetadata?.diagnosticInfo).to.equal('stack trace here');
+  });
+
+  it('omits kernelMetadata entirely for a bare envelope (no optional fields)', () => {
+    const err = decodeNapiKernelError(envelope({ code: 'Internal', message: 'plain' })) as ErrorWithSqlState;
+    expect(err.kernelMetadata).to.equal(undefined);
+  });
+
+  it('Thrift parity: SEA exposes the same diagnostics Thrift carries via OperationStateError.response', () => {
+    // Thrift's OperationStateError carries the full TGetOperationStatusResp on
+    // `.response` (displayMessage + sqlState + numeric errorCode + diagnostics).
+    // SEA must expose the equivalent set so a consumer gets parity regardless of
+    // backend: same class + sqlState + a diagnostics surface.
+    const err = decodeNapiKernelError(
+      envelope({
+        code: 'SqlError',
+        message: 'div by zero',
+        sqlState: '22012',
+        vendorCode: 0,
+        displayMessage: 'Division by zero',
+        diagnosticInfo: 'ArithmeticException',
+      }),
+    ) as ErrorWithSqlState;
+    expect(err).to.be.instanceOf(OperationStateError); // class parity (Thrift: OperationStateError)
+    expect(err.sqlState).to.equal('22012'); // Thrift: response.sqlState
+    expect(err.kernelMetadata?.displayMessage).to.equal('Division by zero'); // Thrift: response.displayMessage
+    expect(err.kernelMetadata?.diagnosticInfo).to.equal('ArithmeticException'); // Thrift: response.errorMessage
+  });
+});