@kaelio/ktx 0.8.0 → 0.10.0

package/dist/connectors/mysql/connector.js

@@ -6,7 +6,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { constraintDiscoveryWarning, tryConstraintQuery, } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 class DefaultMysqlPoolFactory {
     createPool(config) {
         return mysql.createPool(config);
@@ -185,7 +185,7 @@ export class KtxMysqlScanConnector {
     capabilities = createKtxConnectorCapabilities({
         tableSampling: true,
         columnSampling: true,
-        columnStats: false,
+        columnStats: true,
         readOnlySql: true,
         nestedAnalysis: true,
         formalForeignKeys: true,
@@ -219,7 +219,7 @@ export class KtxMysqlScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {
@@ -324,8 +324,28 @@ export class KtxMysqlScanConnector {
         const values = result.rows.filter((row) => row.length > 0 && row[0] !== null).map((row) => row[0]);
         return { values, nullCount: null, distinctCount: null };
     }
-    async columnStats(_input, _ctx) {
-        return null;
+    async columnStats(input, _ctx) {
+        const stats = await this.getColumnStatistics(input.table);
+        const value = stats?.cardinalityByColumn.get(input.column);
+        return value === undefined
+            ? null
+            : { min: null, max: null, average: null, nullCount: null, distinctCount: value };
+    }
+    async getColumnStatistics(table) {
+        const schema = table.db ?? this.poolConfig.database;
+        const sql = this.dialect.generateColumnStatisticsQuery(schema, table.name);
+        if (!sql) {
+            return null;
+        }
+        const rows = await this.queryRaw(sql);
+        const cardinalityByColumn = new Map();
+        for (const row of rows) {
+            const cardinality = Number(row.estimated_cardinality);
+            if (Number.isFinite(cardinality) && cardinality >= 0) {
+                cardinalityByColumn.set(row.column_name, cardinality);
+            }
+        }
+        return cardinalityByColumn.size > 0 ? { cardinalityByColumn } : null;
     }
     async executeReadOnly(input, _ctx) {
         this.assertConnection(input.connectionId);

package/dist/connectors/mysql/dialect.d.ts

@@ -25,7 +25,7 @@ export declare class KtxMysqlDialect implements KtxDialect {
     getSampleValueAggregation(innerSql: string): string;
     generateCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
     generateDistinctValuesQuery(tableName: string, columnName: string, limit: number): string;
-    generateColumnStatisticsQuery(_schemaName: string, _tableName: string): string | null;
+    generateColumnStatisticsQuery(schemaName: string, tableName: string): string | null;
     generateRandomizedCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
 }
 export {};

package/dist/connectors/mysql/dialect.js

@@ -135,8 +135,18 @@ export class KtxMysqlDialect {
       LIMIT ${limit}
     `;
     }
-    generateColumnStatisticsQuery(_schemaName, _tableName) {
-        return null;
+    generateColumnStatisticsQuery(schemaName, tableName) {
+        return `
+      SELECT
+        COLUMN_NAME AS column_name,
+        MAX(CARDINALITY) AS estimated_cardinality
+      FROM INFORMATION_SCHEMA.STATISTICS
+      WHERE TABLE_SCHEMA = '${schemaName.replace(/'/g, "''")}'
+        AND TABLE_NAME = '${tableName.replace(/'/g, "''")}'
+        AND CARDINALITY IS NOT NULL
+        AND SEQ_IN_INDEX = 1
+      GROUP BY COLUMN_NAME
+    `;
     }
     generateRandomizedCardinalitySampleQuery(tableName, columnName, sampleSize) {
         return `

package/dist/connectors/postgres/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxPostgresConnectionConfig {
     driver?: string;
     host?: string;
@@ -117,10 +117,7 @@ export declare class KtxPostgresScanConnector implements KtxScanConnector {
     private lastIdlePoolError;
     private resolvedEndpoint;
     constructor(options: KtxPostgresScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxPostgresTableSampleResult>;
     sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;

package/dist/connectors/postgres/connector.js

@@ -5,7 +5,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import { Pool } from 'pg';
 const PG_OID_TYPE_MAP = {
     16: 'boolean',
@@ -231,7 +231,7 @@ export class KtxPostgresScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {

package/dist/connectors/snowflake/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxSnowflakeConnectionConfig {
     driver?: string;
     authMethod?: 'password' | 'rsa';
@@ -117,10 +117,7 @@ export declare class KtxSnowflakeScanConnector implements KtxScanConnector {
     private readonly now;
     private driverInstance;
     constructor(options: KtxSnowflakeScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult>;
     sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;

package/dist/connectors/snowflake/connector.js

@@ -6,7 +6,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import snowflake from 'snowflake-sdk';
 import { assertSafeSnowflakeIdentifier, quoteSnowflakeIdentifier } from './identifiers.js';
 import { configureSnowflakeSdkLogger } from './sdk-logger.js';
@@ -282,7 +282,7 @@ class SnowflakeSdkDriver {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async getPool() {

package/dist/connectors/sqlite/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxSqliteConnectionConfig {
     driver?: string;
     path?: string;
@@ -39,10 +39,7 @@ export declare class KtxSqliteScanConnector implements KtxScanConnector {
     private readonly dialect;
     private db;
     constructor(options: KtxSqliteScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     listSchemas(): Promise<string[]>;
     listTables(_schemas?: string[]): Promise<KtxTableListEntry[]>;

package/dist/connectors/sqlite/connector.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { normalizeQueryRows } from '../../context/connections/query-executor.js';
-import { createKtxConnectorCapabilities } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities } from '../../context/scan/types.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
 function stringConfigValue(connection, key) {
     const value = connection?.[key];
@@ -106,7 +106,7 @@ export class KtxSqliteScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {

package/dist/connectors/sqlserver/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxSqlServerConnectionConfig {
     driver?: string;
     host?: string;
@@ -113,10 +113,7 @@ export declare class KtxSqlServerScanConnector implements KtxScanConnector {
     private pool;
     private resolvedEndpoint;
     constructor(options: KtxSqlServerScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxSqlServerTableSampleResult>;
     sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;

package/dist/connectors/sqlserver/connector.js

@@ -2,7 +2,7 @@ import { assertReadOnlySql } from '../../context/connections/read-only-sql.js';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
@@ -235,7 +235,7 @@ export class KtxSqlServerScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {

package/dist/context/connections/drivers.d.ts

@@ -14,7 +14,6 @@ export interface KtxDriverRegistration {
     readonly driver: KtxConnectionDriver;
     readonly scopeConfigKey: KtxScopeConfigKey | null;
     readonly hasHistoricSqlReader: boolean;
-    readonly hasLocalQueryExecutor: boolean;
     load(): Promise<KtxDriverConnectorModule>;
 }
 /** @internal */

package/dist/context/connections/drivers.js

@@ -7,7 +7,6 @@ export const driverRegistrations = {
         driver: 'bigquery',
         scopeConfigKey: 'dataset_ids',
         hasHistoricSqlReader: true,
-        hasLocalQueryExecutor: false,
         load: async () => {
             const m = await import('../../connectors/bigquery/connector.js');
             return {
@@ -29,7 +28,6 @@ export const driverRegistrations = {
         driver: 'clickhouse',
         scopeConfigKey: 'databases',
         hasHistoricSqlReader: false,
-        hasLocalQueryExecutor: false,
         load: async () => {
             const m = await import('../../connectors/clickhouse/connector.js');
             return {
@@ -51,7 +49,6 @@ export const driverRegistrations = {
         driver: 'mysql',
         scopeConfigKey: 'schemas',
         hasHistoricSqlReader: false,
-        hasLocalQueryExecutor: false,
         load: async () => {
             const m = await import('../../connectors/mysql/connector.js');
             return {
@@ -73,7 +70,6 @@ export const driverRegistrations = {
         driver: 'postgres',
         scopeConfigKey: 'schemas',
         hasHistoricSqlReader: true,
-        hasLocalQueryExecutor: true,
         load: async () => {
             const m = await import('../../connectors/postgres/connector.js');
             return {
@@ -95,7 +91,6 @@ export const driverRegistrations = {
         driver: 'sqlite',
         scopeConfigKey: null,
         hasHistoricSqlReader: false,
-        hasLocalQueryExecutor: true,
         load: async () => {
             const m = await import('../../connectors/sqlite/connector.js');
             return {
@@ -117,7 +112,6 @@ export const driverRegistrations = {
         driver: 'snowflake',
         scopeConfigKey: 'schema_names',
         hasHistoricSqlReader: true,
-        hasLocalQueryExecutor: false,
         load: async () => {
             const m = await import('../../connectors/snowflake/connector.js');
             return {
@@ -139,7 +133,6 @@ export const driverRegistrations = {
         driver: 'sqlserver',
         scopeConfigKey: 'schemas',
         hasHistoricSqlReader: false,
-        hasLocalQueryExecutor: false,
         load: async () => {
             const m = await import('../../connectors/sqlserver/connector.js');
             return {

package/dist/context/connections/query-executor.d.ts

@@ -6,7 +6,7 @@ export interface KtxSqlQueryExecutionInput {
     sql: string;
     maxRows?: number;
 }
-export interface KtxSqlQueryExecutionResult {
+interface KtxSqlQueryExecutionResult {
     headers: string[];
     rows: unknown[][];
     totalRows: number;
@@ -17,3 +17,4 @@ export interface KtxSqlQueryExecutorPort {
     execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult>;
 }
 export declare function normalizeQueryRows(rows: unknown[]): unknown[][];
+export {};

package/dist/context/core/abort.d.ts

@@ -0,0 +1,9 @@
+/** @internal */
+export declare function createAbortError(message?: string): DOMException;
+export declare function isAbortError(error: unknown): boolean;
+/** @internal */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function linkAbortSignal(parent?: AbortSignal): {
+    controller: AbortController;
+    dispose: () => void;
+};

package/dist/context/core/abort.js

@@ -0,0 +1,36 @@
+/** @internal */
+export function createAbortError(message = 'Aborted') {
+    return new DOMException(message, 'AbortError');
+}
+export function isAbortError(error) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return true;
+    }
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const record = error;
+    return record.name === 'AbortError' || record.code === 'ABORT_ERR';
+}
+/** @internal */
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw createAbortError();
+    }
+}
+export function linkAbortSignal(parent) {
+    const controller = new AbortController();
+    if (!parent) {
+        return { controller, dispose: () => undefined };
+    }
+    if (parent.aborted) {
+        controller.abort(createAbortError());
+        return { controller, dispose: () => undefined };
+    }
+    const onAbort = () => controller.abort(createAbortError());
+    parent.addEventListener('abort', onAbort, { once: true });
+    return {
+        controller,
+        dispose: () => parent.removeEventListener('abort', onAbort),
+    };
+}

package/dist/context/ingest/adapters/historic-sql/bigquery-query-history-reader.js

@@ -154,27 +154,78 @@ export class BigQueryHistoricSqlQueryHistoryReader {
     }
     async *fetchAggregated(client, window, config) {
         const sql = `
+WITH filtered_jobs AS (
+  SELECT
+    COALESCE(query_info.query_hashes.normalized_literals, TO_HEX(SHA256(query))) AS template_id,
+    query,
+    user_email,
+    creation_time,
+    end_time,
+    error_result
+  FROM ${this.viewPath}
+  WHERE job_type = 'QUERY'
+    AND statement_type IN ('SELECT', 'MERGE')
+    AND creation_time >= ${timestampExpression(window.start)}
+    AND creation_time < ${timestampExpression(window.end)}
+    AND query IS NOT NULL
+),
+template_stats AS (
+  SELECT
+    template_id,
+    MIN(query) AS canonical_sql,
+    COUNT(*) AS executions,
+    COUNT(DISTINCT user_email) AS distinct_users,
+    MIN(creation_time) AS first_seen,
+    MAX(creation_time) AS last_seen,
+    APPROX_QUANTILES(TIMESTAMP_DIFF(end_time, creation_time, MILLISECOND), 100)[OFFSET(50)] AS p50_ms,
+    APPROX_QUANTILES(TIMESTAMP_DIFF(end_time, creation_time, MILLISECOND), 100)[OFFSET(95)] AS p95_ms,
+    SAFE_DIVIDE(COUNTIF(error_result IS NOT NULL), COUNT(*)) AS error_rate,
+    CAST(NULL AS INT64) AS rows_produced
+  FROM filtered_jobs
+  GROUP BY template_id
+  HAVING COUNT(*) >= ${config.minExecutions}
+),
+template_users AS (
+  SELECT
+    template_id,
+    user_email AS user,
+    COUNT(*) AS executions,
+    MAX(creation_time) AS last_seen
+  FROM filtered_jobs
+  GROUP BY template_id, user_email
+)
 SELECT
-  query_hash AS template_id,
-  MIN(query) AS canonical_sql,
-  COUNT(*) AS executions,
-  COUNT(DISTINCT user_email) AS distinct_users,
-  MIN(creation_time) AS first_seen,
-  MAX(creation_time) AS last_seen,
-  APPROX_QUANTILES(TIMESTAMP_DIFF(end_time, creation_time, MILLISECOND), 100)[OFFSET(50)] AS p50_ms,
-  APPROX_QUANTILES(TIMESTAMP_DIFF(end_time, creation_time, MILLISECOND), 100)[OFFSET(95)] AS p95_ms,
-  SAFE_DIVIDE(COUNTIF(error_result IS NOT NULL), COUNT(*)) AS error_rate,
-  CAST(NULL AS INT64) AS rows_produced,
-  TO_JSON_STRING(ARRAY_AGG(STRUCT(user_email AS user, 1 AS executions) ORDER BY creation_time DESC LIMIT 5)) AS top_users
-FROM ${this.viewPath}
-WHERE job_type = 'QUERY'
-  AND statement_type IN ('SELECT', 'MERGE')
-  AND creation_time >= ${timestampExpression(window.start)}
-  AND creation_time < ${timestampExpression(window.end)}
-  AND query IS NOT NULL
-GROUP BY query_hash
-HAVING COUNT(*) >= ${config.minExecutions}
-ORDER BY executions DESC`.trim();
+  stats.template_id,
+  stats.canonical_sql,
+  stats.executions,
+  stats.distinct_users,
+  stats.first_seen,
+  stats.last_seen,
+  stats.p50_ms,
+  stats.p95_ms,
+  stats.error_rate,
+  stats.rows_produced,
+  TO_JSON_STRING(
+    ARRAY_AGG(
+      STRUCT(users.user AS user, users.executions AS executions)
+      ORDER BY users.executions DESC, users.last_seen DESC
+    )
+  ) AS top_users
+FROM template_stats AS stats
+JOIN template_users AS users
+  ON users.template_id = stats.template_id
+GROUP BY
+  stats.template_id,
+  stats.canonical_sql,
+  stats.executions,
+  stats.distinct_users,
+  stats.first_seen,
+  stats.last_seen,
+  stats.p50_ms,
+  stats.p95_ms,
+  stats.error_rate,
+  stats.rows_produced
+ORDER BY stats.executions DESC`.trim();
         const result = await queryClient(client).executeQuery(sql);
         if (result.error) {
             throw grantsError(result.error);

package/dist/context/ingest/adapters/historic-sql/chunk-unified.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readFile, readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
+import { tableRefKey } from '../../../scan/table-ref.js';
 import { isHistoricSqlPatternInputShardPath } from './pattern-inputs.js';
 import { stagedManifestSchema, stagedPatternsInputSchema, stagedTableInputSchema } from './types.js';
 async function walk(root) {
@@ -30,7 +31,7 @@ export async function chunkHistoricSqlUnifiedStagedDir(stagedDir, diffSet) {
         }
         const table = stagedTableInputSchema.parse(await readJson(stagedDir, path));
         workUnits.push({
-            unitKey: `historic-sql-table-${safeUnitKey(table.table)}`,
+            unitKey: `historic-sql-table-${safeUnitKey(tableRefKey(table.tableRef))}`,
             displayLabel: `Historic SQL usage: ${table.table}`,
             rawFiles: [path],
             dependencyPaths: ['manifest.json'],

package/dist/context/ingest/adapters/historic-sql/connection-dialect.d.ts

@@ -1,5 +1,14 @@
 import type { HistoricSqlDialect } from './types.js';
 export declare function isQueryHistoryEnabled(connection: unknown): boolean;
+/**
+ * Resolves the query-history dialect from the connection's driver capability
+ * alone, ignoring whether query history is enabled in ktx.yaml. Use this on the
+ * adapter-registration path when query history has been explicitly requested
+ * for the run (e.g. via `--query-history`, which is itself the opt-in): the
+ * persisted `context.queryHistory.enabled` flag must not gate registration.
+ * Returns null when the connection's driver has no query-history reader.
+ */
+export declare function historicSqlDialectForConnectionDriver(connection: unknown): HistoricSqlDialect | null;
 /**
  * Resolves the query-history dialect for a connection. Returns null when
  * query history is disabled, or when the connection's driver has no

package/dist/context/ingest/adapters/historic-sql/connection-dialect.js

@@ -18,6 +18,20 @@ function historicSqlDialectForDriver(driver) {
 export function isQueryHistoryEnabled(connection) {
     return queryHistoryRecord(connection)?.enabled === true;
 }
+/**
+ * Resolves the query-history dialect from the connection's driver capability
+ * alone, ignoring whether query history is enabled in ktx.yaml. Use this on the
+ * adapter-registration path when query history has been explicitly requested
+ * for the run (e.g. via `--query-history`, which is itself the opt-in): the
+ * persisted `context.queryHistory.enabled` flag must not gate registration.
+ * Returns null when the connection's driver has no query-history reader.
+ */
+export function historicSqlDialectForConnectionDriver(connection) {
+    const conn = recordOrNull(connection);
+    const driver = String(conn?.driver ?? '').toLowerCase();
+    const registration = getDriverRegistration(driver);
+    return registration?.hasHistoricSqlReader ? historicSqlDialectForDriver(registration.driver) : null;
+}
 /**
  * Resolves the query-history dialect for a connection. Returns null when
  * query history is disabled, or when the connection's driver has no
@@ -27,8 +41,5 @@ export function queryHistoryDialectForConnection(connection) {
     if (!isQueryHistoryEnabled(connection)) {
         return null;
     }
-    const conn = recordOrNull(connection);
-    const driver = String(conn?.driver ?? '').toLowerCase();
-    const registration = getDriverRegistration(driver);
-    return registration?.hasHistoricSqlReader ? historicSqlDialectForDriver(registration.driver) : null;
+    return historicSqlDialectForConnectionDriver(connection);
 }

package/dist/context/ingest/adapters/historic-sql/pattern-inputs.js

@@ -1,4 +1,5 @@
 import { Buffer } from 'node:buffer';
+import { tableRefKey } from '../../../scan/table-ref.js';
 const HISTORIC_SQL_PATTERN_WORKUNIT_DIR = 'patterns-input';
 /** @internal */
 export const HISTORIC_SQL_PATTERN_WORKUNIT_MAX_BYTES = 110_000;
@@ -19,12 +20,17 @@ function sortedAuditTemplates(templates) {
 function sortedPatternCandidates(templates) {
     return [...templates]
         .filter((template) => template.tablesTouched.length >= 2)
-        .map((template) => ({ ...template, tablesTouched: [...template.tablesTouched].sort() }))
+        .map((template) => ({
+        ...template,
+        tablesTouched: [...template.tablesTouched].sort((left, right) => tableRefKey(left).localeCompare(tableRefKey(right))),
+    }))
         .sort((left, right) => {
         const cardinality = right.tablesTouched.length - left.tablesTouched.length;
         if (cardinality !== 0)
             return cardinality;
-        const tableSignature = left.tablesTouched.join('\0').localeCompare(right.tablesTouched.join('\0'));
+        const leftSignature = left.tablesTouched.map(tableRefKey).join('\0');
+        const rightSignature = right.tablesTouched.map(tableRefKey).join('\0');
+        const tableSignature = leftSignature.localeCompare(rightSignature);
         if (tableSignature !== 0)
             return tableSignature;
         return left.id.localeCompare(right.id);

package/dist/context/ingest/adapters/historic-sql/query-history-filter-picker.d.ts

@@ -0,0 +1,30 @@
+import type { KtxLlmRuntimePort } from '../../../../context/llm/runtime-port.js';
+import type { SqlAnalysisPort } from '../../../../context/sql-analysis/ports.js';
+import { type HistoricSqlDialect, type HistoricSqlReader } from './types.js';
+export interface QueryHistoryFilterProposal {
+    excludedRoles: Array<{
+        role: string;
+        reason: string;
+        pattern: string;
+    }>;
+    consideredRoleCount: number;
+    skipped: {
+        reason: 'no-llm' | 'no-daemon' | 'no-in-scope-history' | 'user-block-present';
+    } | null;
+    warnings: string[];
+    parseFailedTemplateIds: string[];
+}
+export interface ProposeQueryHistoryServiceAccountFiltersInput {
+    connectionId: string;
+    dialect: HistoricSqlDialect;
+    queryClient: unknown;
+    reader: HistoricSqlReader;
+    sqlAnalysis: SqlAnalysisPort;
+    llmRuntime: KtxLlmRuntimePort | null;
+    pullConfig: unknown;
+    now?: Date;
+    userServiceAccountsPresent?: boolean;
+}
+/** @internal */
+export declare function regexEscapeForExactRolePattern(role: string): string;
+export declare function proposeQueryHistoryServiceAccountFilters(input: ProposeQueryHistoryServiceAccountFiltersInput): Promise<QueryHistoryFilterProposal>;