feat(kernel): wire session-level query tags into KernelBackend.openSession

Ports the session-level query-tags wiring onto the post-#428 lib/kernel path
(originally lib/sea/SeaBackend, before the SEA→kernel rename). openSession
serializes request.queryTags into the reserved QUERY_TAGS session conf, which
the kernel allowlists (SESSION_CONF_ALLOWLIST) and forwards onto the SEA
CreateSession session_confs — mirroring ThriftBackend.openSession. queryTags
takes precedence over an explicit configuration.QUERY_TAGS.

Verified end-to-end against a live warehouse: the tag lands in
system.query.history.query_tags.

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

Author: msrathore-db

lib/kernel/KernelBackend.ts

@@ -19,6 +19,7 @@ import { ConnectionOptions, OpenSessionRequest } from '../contracts/IDBSQLClient
 import { InternalConnectionOptions } from '../contracts/InternalConnectionOptions';
 import { LogLevel } from '../contracts/IDBSQLLogger';
 import HiveDriverError from '../errors/HiveDriverError';
+import { serializeQueryTags } from '../utils';
 import { getKernelNative, KernelNativeBinding, KernelConnection } from './KernelNativeLoader';
 import { decodeNapiKernelError } from './KernelErrorMapping';
 import { buildKernelConnectionOptions, buildKernelRetryOptions, KernelNativeConnectionOptions } from './KernelAuth';
@@ -145,6 +146,20 @@ export default class KernelBackend implements IBackend {
     if (request.configuration !== undefined) {
       sessionOptions.sessionConf = { ...request.configuration };
     }
+    // Session-level query tags: serialize into the reserved `QUERY_TAGS`
+    // session conf. The kernel allowlists `QUERY_TAGS` (SESSION_CONF_ALLOWLIST)
+    // and forwards it onto the SEA `CreateSession` `session_confs`, mirroring
+    // the Thrift backend's `ThriftBackend.openSession`. Runs after the
+    // `configuration` merge so `queryTags` takes precedence over an explicit
+    // `configuration.QUERY_TAGS`, matching the documented contract.
+    if (request.queryTags !== undefined) {
+      const serialized = serializeQueryTags(request.queryTags);
+      if (serialized) {
+        sessionOptions.sessionConf = { ...(sessionOptions.sessionConf ?? {}), QUERY_TAGS: serialized };
+      } else if (sessionOptions.sessionConf) {
+        delete sessionOptions.sessionConf.QUERY_TAGS;
+      }
+    }
 
     let nativeConnection: KernelConnection;
     try {

tests/unit/kernel/execution.test.ts

@@ -551,6 +551,36 @@ describe('KernelBackend', () => {
     });
   });
 
+  it('openSession() serializes session-level queryTags into sessionConf.QUERY_TAGS', async () => {
+    const connection = new FakeNativeConnection();
+    const binding = makeBinding(connection);
+    const backend = new KernelBackend({ context: makeContext(), nativeBinding: binding });
+    await backend.connect({ host: 'h', path: '/p', token: 't' } as ConnectionOptions);
+
+    await backend.openSession({ queryTags: { team: 'eng', env: 'prod' } });
+
+    // Session-level tags land in the reserved QUERY_TAGS session conf (the
+    // kernel allowlists it → SEA CreateSession session_confs), mirroring Thrift.
+    const conf = (binding.openSessionStub.firstCall.args[0] as { sessionConf?: Record<string, string> }).sessionConf;
+    expect(conf?.QUERY_TAGS).to.be.a('string');
+    expect(conf?.QUERY_TAGS).to.contain('team:eng').and.to.contain('env:prod');
+  });
+
+  it('openSession() queryTags takes precedence over an explicit configuration.QUERY_TAGS', async () => {
+    const connection = new FakeNativeConnection();
+    const binding = makeBinding(connection);
+    const backend = new KernelBackend({ context: makeContext(), nativeBinding: binding });
+    await backend.connect({ host: 'h', path: '/p', token: 't' } as ConnectionOptions);
+
+    await backend.openSession({
+      configuration: { QUERY_TAGS: 'manual-raw-value' },
+      queryTags: { team: 'eng' },
+    });
+
+    const conf = (binding.openSessionStub.firstCall.args[0] as { sessionConf?: Record<string, string> }).sessionConf;
+    expect(conf?.QUERY_TAGS).to.contain('team:eng').and.to.not.equal('manual-raw-value');
+  });
+
   it('openSession() returns a KernelSessionBackend wrapping the napi Connection', async () => {
     const connection = new FakeNativeConnection();
     const binding = makeBinding(connection);