@kaelio/ktx 0.8.0 → 0.9.0

package/dist/cli-runtime.js

@@ -35,11 +35,58 @@ async function runInit(args, io) {
 export async function runInitForCommander(args, io) {
     return await runInit(args, io);
 }
+function signalExitCode(signal) {
+    // 128 + signal number: SIGINT (2) -> 130, SIGTERM (15) -> 143.
+    return signal === 'SIGTERM' ? 143 : 130;
+}
+/**
+ * Flush telemetry on interrupt for the real CLI process. `capture()` is
+ * fire-and-forget and the only flush guarantee lives in a `finally` a signal
+ * skips, so Ctrl-C / `kill` of a long-running command (ingest, `mcp stdio`)
+ * would otherwise drop its `command` event and queued events. Installed only
+ * when driving the actual process; programmatic/test callers pass their own
+ * `io` and never reach here. Returns a disposer that removes the listeners.
+ */
+function installTelemetrySignalFlush(io, info) {
+    let handling = false;
+    const handle = (signal) => {
+        if (handling) {
+            process.exit(signalExitCode(signal));
+        }
+        handling = true;
+        void (async () => {
+            try {
+                const { emitAbortedCommandAndShutdown } = await import('./telemetry/index.js');
+                await emitAbortedCommandAndShutdown({ packageInfo: info, io });
+            }
+            catch {
+                // Best-effort: never let a telemetry hiccup block the interrupt exit.
+            }
+            process.exit(signalExitCode(signal));
+        })();
+    };
+    const onSigint = () => handle('SIGINT');
+    const onSigterm = () => handle('SIGTERM');
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    return () => {
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+    };
+}
 export async function runKtxCli(argv = process.argv.slice(2), io = process, deps = {}) {
     const info = getKtxCliPackageInfo();
     profileMark('runtime:runKtxCli');
     const { runCommanderKtxCli } = await profileSpan('import ./cli-program.js', () => import('./cli-program.js'));
-    return await runCommanderKtxCli(argv, io, deps, info, {
-        runInit: runInitForCommander,
-    });
+    // Real-process entry only: flush telemetry if interrupted. Test/programmatic
+    // callers pass their own `io`, so they never install process-level handlers.
+    const removeSignalFlush = io === process ? installTelemetrySignalFlush(io, info) : undefined;
+    try {
+        return await runCommanderKtxCli(argv, io, deps, info, {
+            runInit: runInitForCommander,
+        });
+    }
+    finally {
+        removeSignalFlush?.();
+    }
 }

package/dist/commands/setup-commands.js

@@ -18,7 +18,7 @@ function embeddingBackend(value) {
     throw new InvalidArgumentError(`invalid choice '${value}'`);
 }
 function llmBackend(value) {
-    if (value === 'anthropic' || value === 'vertex' || value === 'claude-code') {
+    if (value === 'anthropic' || value === 'vertex' || value === 'claude-code' || value === 'codex') {
         return value;
     }
     throw new InvalidArgumentError(`invalid choice '${value}'`);

package/dist/connection-recovery.d.ts

@@ -0,0 +1,34 @@
+import type { KtxCliIo } from './cli-runtime.js';
+import type { KtxSetupPromptOption } from './setup-prompts.js';
+export type RecoveryOutcome = 'ready' | 'skip' | 'back' | 'failed';
+/** @internal */
+export interface RecoveryAction {
+    value: string;
+    label: string;
+    run: () => Promise<void>;
+}
+export type ConfigureResult = 'configured' | 'back' | 'cancelled';
+export type ValidateResult = {
+    status: 'ok';
+} | {
+    status: 'back';
+} | {
+    status: 'failed';
+    extraActions?: RecoveryAction[];
+};
+export interface ConnectionRecoveryInput {
+    label: string;
+    interactive: boolean;
+    allowSkip: boolean;
+    io: KtxCliIo;
+    prompts: {
+        select(options: {
+            message: string;
+            options: KtxSetupPromptOption[];
+        }): Promise<string>;
+    };
+    snapshot: () => Promise<() => Promise<void>>;
+    configure: () => Promise<ConfigureResult>;
+    validate: () => Promise<ValidateResult>;
+}
+export declare function runConnectionSetupWithRecovery(input: ConnectionRecoveryInput): Promise<RecoveryOutcome>;

package/dist/connection-recovery.js

@@ -0,0 +1,82 @@
+async function runRollbackOnce(input) {
+    if (input.state.rolledBack) {
+        return;
+    }
+    input.state.rolledBack = true;
+    await input.rollback();
+}
+function recoveryOptions(input) {
+    return [
+        { value: 'retry', label: 'Retry connection test' },
+        { value: 're-enter', label: 'Re-enter connection details' },
+        ...(input.extraActions ?? []).map((action) => ({
+            value: action.value,
+            label: action.label,
+        })),
+        ...(input.allowSkip ? [{ value: 'skip', label: 'Skip this connection' }] : []),
+        { value: 'back', label: 'Back' },
+    ];
+}
+export async function runConnectionSetupWithRecovery(input) {
+    const rollback = await input.snapshot();
+    const rollbackState = { rolledBack: false };
+    const firstConfig = await input.configure();
+    if (firstConfig === 'back') {
+        await runRollbackOnce({ rollback, state: rollbackState });
+        return 'back';
+    }
+    if (firstConfig === 'cancelled') {
+        await runRollbackOnce({ rollback, state: rollbackState });
+        return 'failed';
+    }
+    let validation = await input.validate();
+    while (validation.status !== 'ok') {
+        if (validation.status === 'back') {
+            await runRollbackOnce({ rollback, state: rollbackState });
+            return 'back';
+        }
+        if (!input.interactive) {
+            return 'failed';
+        }
+        const action = await input.prompts.select({
+            message: `Connection setup failed for ${input.label}`,
+            options: recoveryOptions({
+                allowSkip: input.allowSkip,
+                extraActions: validation.extraActions,
+            }),
+        });
+        if (action === 'back') {
+            await runRollbackOnce({ rollback, state: rollbackState });
+            return 'back';
+        }
+        if (action === 'skip' && input.allowSkip) {
+            await runRollbackOnce({ rollback, state: rollbackState });
+            return 'skip';
+        }
+        if (action === 're-enter') {
+            const nextConfig = await input.configure();
+            if (nextConfig === 'back') {
+                await runRollbackOnce({ rollback, state: rollbackState });
+                return 'back';
+            }
+            if (nextConfig === 'cancelled') {
+                await runRollbackOnce({ rollback, state: rollbackState });
+                return 'failed';
+            }
+            validation = await input.validate();
+            continue;
+        }
+        if (action === 'retry') {
+            validation = await input.validate();
+            continue;
+        }
+        const extraAction = validation.extraActions?.find((candidate) => candidate.value === action);
+        if (extraAction) {
+            await extraAction.run();
+            validation = await input.validate();
+            continue;
+        }
+        validation = await input.validate();
+    }
+    return 'ready';
+}

package/dist/connection.js

@@ -13,7 +13,7 @@ import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { profileMark } from './startup-profile.js';
 import { isDemoConnection } from './telemetry/demo-detect.js';
 import { emitTelemetryEvent } from './telemetry/index.js';
-import { scrubErrorClass } from './telemetry/scrubber.js';
+import { formatErrorDetail, scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:connection');
 const SUPPORTED_TEST_DRIVERS = [
     'sqlite',
@@ -168,6 +168,7 @@ async function testConnectionByDriver(project, connectionId, deps) {
 }
 async function emitConnectionTest(input) {
     const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
+    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
     await emitTelemetryEvent({
         name: 'connection_test',
         projectDir: input.project.projectDir,
@@ -178,6 +179,7 @@ async function emitConnectionTest(input) {
             outcome: input.outcome,
             durationMs: input.durationMs,
             ...(errorClass ? { errorClass } : {}),
+            ...(errorDetail ? { errorDetail } : {}),
         },
     });
 }

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,29 @@
+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[];
+}
+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>;

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

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { tableRefKey } from '../../../scan/table-ref.js';
+import { bucketDistinctUsers, bucketExecutions, bucketRecency } from './buckets.js';
+import { compileHistoricSqlRedactionPatterns, redactHistoricSqlText, } from './redaction.js';
+import { includedQueryHistoryTableRefs } from './scope-membership.js';
+import { aggregatedTemplateSchema, historicSqlUnifiedPullConfigSchema, } from './types.js';
+const queryHistoryFilterAdjudicationSchema = z.object({
+    roles: z.array(z.object({
+        role: z.string().min(1),
+        exclude: z.boolean(),
+        reason: z.string().min(1),
+    }).strict()),
+}).strict();
+function emptyProposal(skipped, warnings = []) {
+    return { excludedRoles: [], consideredRoleCount: 0, skipped, warnings };
+}
+function displayTableRef(ref) {
+    return [ref.catalog, ref.db, ref.name].filter((part) => !!part && part.length > 0).join('.');
+}
+function redactTemplateSqlForPicker(template, redactors) {
+    if (redactors.length === 0) {
+        return template;
+    }
+    return {
+        ...template,
+        canonicalSql: redactHistoricSqlText(template.canonicalSql, redactors),
+    };
+}
+/** @internal */
+export function regexEscapeForExactRolePattern(role) {
+    return `^${role.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')}$`;
+}
+function recordRole(acc, template, tables, executions) {
+    acc.executions += executions;
+    acc.distinctUsers = Math.max(acc.distinctUsers, template.stats.distinctUsers);
+    acc.lastSeen = template.stats.lastSeen > acc.lastSeen ? template.stats.lastSeen : acc.lastSeen;
+    for (const table of tables) {
+        acc.tables.set(tableRefKey(table), table);
+    }
+    acc.templates.push(template);
+}
+function roleRecords(parsedTemplates, now) {
+    const byRole = new Map();
+    for (const parsed of parsedTemplates) {
+        for (const entry of parsed.template.topUsers) {
+            if (!entry.user || entry.user.trim().length === 0 || entry.executions <= 0) {
+                continue;
+            }
+            const role = entry.user.trim();
+            const acc = byRole.get(role) ??
+                {
+                    role,
+                    executions: 0,
+                    distinctUsers: 0,
+                    lastSeen: '1970-01-01T00:00:00.000Z',
+                    tables: new Map(),
+                    templates: [],
+                };
+            recordRole(acc, parsed.template, parsed.includedTables, entry.executions);
+            byRole.set(role, acc);
+        }
+    }
+    return [...byRole.values()]
+        .sort((left, right) => right.executions - left.executions || left.role.localeCompare(right.role))
+        .map((acc) => ({
+        role: acc.role,
+        inScopeTables: [...acc.tables.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .slice(0, 25)
+            .map(([, ref]) => displayTableRef(ref)),
+        executionsBucket: bucketExecutions(acc.executions),
+        distinctUsersBucket: bucketDistinctUsers(acc.distinctUsers),
+        recencyBucket: bucketRecency(acc.lastSeen, now),
+        representativeTemplates: [...acc.templates]
+            .sort((left, right) => right.stats.executions - left.stats.executions || left.templateId.localeCompare(right.templateId))
+            .slice(0, 3)
+            .map((template) => ({
+            id: template.templateId,
+            canonicalSql: template.canonicalSql,
+            dialect: template.dialect,
+        })),
+    }));
+}
+function adjudicationSystemPrompt() {
+    return [
+        'You are helping ktx decide whether observed query-history roles are operational service accounts.',
+        'Default every role to keep. Mark exclude true only when the aggregate evidence clearly shows loader, ELT, reverse-ETL, export, refresh, or maintenance traffic rather than analyst or BI-dashboard usage.',
+        'Use only the observed role records. Do not rely on a hardcoded denylist. Return structured output only.',
+    ].join('\n');
+}
+export async function proposeQueryHistoryServiceAccountFilters(input) {
+    if (!input.llmRuntime) {
+        return emptyProposal({ reason: 'no-llm' });
+    }
+    const config = historicSqlUnifiedPullConfigSchema.parse(input.pullConfig);
+    const redactors = compileHistoricSqlRedactionPatterns(config.redactionPatterns);
+    const now = input.now ?? new Date();
+    const windowDays = 'windowDays' in config ? config.windowDays : 90;
+    const windowStart = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
+    const warnings = [];
+    const snapshot = [];
+    try {
+        for await (const row of input.reader.fetchAggregated(input.queryClient, { start: windowStart, end: now }, config)) {
+            snapshot.push(aggregatedTemplateSchema.parse(row));
+        }
+    }
+    catch (error) {
+        return emptyProposal(null, [
+            `query_history_filter_picker_read_failed:${error instanceof Error ? error.message : String(error)}`,
+        ]);
+    }
+    if (snapshot.length === 0) {
+        return emptyProposal({ reason: 'no-in-scope-history' });
+    }
+    const analysisItems = snapshot.map((template) => ({ id: template.templateId, sql: template.canonicalSql }));
+    const analysisOptions = config.modeledTableCatalog.length > 0 ? { catalog: { tables: config.modeledTableCatalog } } : undefined;
+    let analysis;
+    try {
+        analysis = await input.sqlAnalysis.analyzeBatch(analysisItems, input.dialect, analysisOptions);
+    }
+    catch (error) {
+        return emptyProposal({ reason: 'no-daemon' }, [
+            `query_history_filter_picker_analysis_failed:${error instanceof Error ? error.message : String(error)}`,
+        ]);
+    }
+    const parsedTemplates = [];
+    for (const template of snapshot) {
+        const parsed = analysis.get(template.templateId);
+        if (!parsed || parsed.error) {
+            warnings.push(`query_history_filter_picker_parse_failed:${template.templateId}`);
+            continue;
+        }
+        const tablesTouched = [...new Map(parsed.tablesTouched.map((ref) => [tableRefKey(ref), ref])).values()]
+            .filter((ref) => ref.name.length > 0)
+            .sort((left, right) => tableRefKey(left).localeCompare(tableRefKey(right)));
+        const includedTables = includedQueryHistoryTableRefs(tablesTouched, config);
+        if (includedTables.length === 0) {
+            continue;
+        }
+        parsedTemplates.push({
+            template: redactTemplateSqlForPicker(template, redactors),
+            tablesTouched,
+            includedTables,
+        });
+    }
+    const records = roleRecords(parsedTemplates, now);
+    if (records.length <= 1) {
+        return {
+            excludedRoles: [],
+            consideredRoleCount: records.length,
+            skipped: { reason: 'no-in-scope-history' },
+            warnings,
+        };
+    }
+    let generated;
+    try {
+        generated = await input.llmRuntime.generateObject({
+            role: 'candidateExtraction',
+            system: adjudicationSystemPrompt(),
+            prompt: JSON.stringify({ connectionId: input.connectionId, dialect: input.dialect, roles: records }),
+            schema: queryHistoryFilterAdjudicationSchema,
+        });
+    }
+    catch (error) {
+        return {
+            excludedRoles: [],
+            consideredRoleCount: records.length,
+            skipped: { reason: 'no-llm' },
+            warnings: [
+                ...warnings,
+                `query_history_filter_picker_llm_failed:${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    const knownRoles = new Set(records.map((record) => record.role));
+    const excludedRoles = generated.roles
+        .filter((role) => role.exclude && knownRoles.has(role.role))
+        .sort((left, right) => left.role.localeCompare(right.role))
+        .map((role) => ({
+        role: role.role,
+        reason: role.reason,
+        pattern: regexEscapeForExactRolePattern(role.role),
+    }));
+    return {
+        excludedRoles,
+        consideredRoleCount: records.length,
+        skipped: input.userServiceAccountsPresent ? { reason: 'user-block-present' } : null,
+        warnings,
+    };
+}

package/dist/context/ingest/adapters/historic-sql/scope-floor.d.ts

@@ -0,0 +1,18 @@
+import { type KtxTableRefKey } from '../../../scan/table-ref.js';
+import type { KtxTableRef } from '../../../scan/types.js';
+export interface QueryHistoryScopeFloorInput {
+    projectDir: string;
+    connectionId: string;
+    driver: string;
+    connection: Record<string, unknown>;
+    storedQueryHistory: Record<string, unknown>;
+}
+export interface QueryHistoryScopeFloor {
+    enabledTables: KtxTableRef[];
+    enabledTableKeys: ReadonlySet<KtxTableRefKey> | null;
+    enabledSchemas: string[];
+    modeledTableCatalog: KtxTableRef[];
+    floorDisabled: boolean;
+    warnings: string[];
+}
+export declare function resolveQueryHistoryScopeFloor(input: QueryHistoryScopeFloorInput): Promise<QueryHistoryScopeFloor>;