@kaelio/ktx 0.5.0 → 0.7.0

package/dist/context/ingest/historic-sql-probes/bigquery-runner.js

@@ -0,0 +1,99 @@
+import { HistoricSqlGrantsMissingError } from '../adapters/historic-sql/errors.js';
+import { BigQueryHistoricSqlQueryHistoryReader } from '../adapters/historic-sql/bigquery-query-history-reader.js';
+import { resolveKtxConfigReference } from '../../core/config-reference.js';
+import { isKtxBigQueryConnectionConfig, KtxBigQueryScanConnector, } from '../../../connectors/bigquery/connector.js';
+function bigQueryProjectId(connectionId, connection, env, resolveReference) {
+    const rawCredentials = typeof connection.credentials_json === 'string' ? connection.credentials_json : '';
+    const resolvedCredentials = resolveReference(rawCredentials, env);
+    if (!resolvedCredentials) {
+        throw new Error(`Query history BigQuery connection ${connectionId} requires credentials_json`);
+    }
+    const parsed = JSON.parse(resolvedCredentials);
+    if (typeof parsed.project_id !== 'string' || parsed.project_id.trim().length === 0) {
+        throw new Error(`Query history BigQuery connection ${connectionId} requires credentials_json.project_id`);
+    }
+    return parsed.project_id;
+}
+function bigQueryRegion(connection) {
+    return typeof connection.location === 'string' && connection.location.trim().length > 0
+        ? connection.location.trim()
+        : 'us';
+}
+function infoSuffix(info) {
+    return info && info.length > 0 ? `; ${info.join('; ')}` : '';
+}
+export class BigQueryJobsByProjectProbeRunner {
+    dialect = 'bigquery';
+    catalogName = 'INFORMATION_SCHEMA.JOBS_BY_PROJECT';
+    createReader;
+    createClient;
+    resolveReference;
+    constructor(options = {}) {
+        this.createReader =
+            options.createReader ??
+                ((readerOptions) => new BigQueryHistoricSqlQueryHistoryReader(readerOptions));
+        this.createClient =
+            options.createClient ??
+                ((input) => {
+                    const connector = new KtxBigQueryScanConnector({
+                        connectionId: input.connectionId,
+                        connection: input.connection,
+                        env: input.env,
+                    });
+                    return {
+                        client: {
+                            async executeQuery(sql) {
+                                const result = await connector.executeReadOnly({ connectionId: input.connectionId, sql }, {});
+                                return {
+                                    headers: result.headers,
+                                    rows: result.rows,
+                                    totalRows: result.totalRows,
+                                };
+                            },
+                        },
+                        cleanup: () => connector.cleanup(),
+                    };
+                });
+        this.resolveReference = options.resolveReference ?? resolveKtxConfigReference;
+    }
+    async run(input) {
+        const inputDriver = input.connection.driver ?? 'unknown';
+        if (!isKtxBigQueryConnectionConfig(input.connection)) {
+            throw new Error(`Native BigQuery connector cannot run driver "${inputDriver}"`);
+        }
+        const projectId = bigQueryProjectId(input.connectionId, input.connection, input.env ?? process.env, this.resolveReference);
+        const reader = this.createReader({
+            projectId,
+            region: bigQueryRegion(input.connection),
+        });
+        const handle = this.createClient({
+            ...input,
+            connection: input.connection,
+        });
+        try {
+            return await reader.probe(handle.client);
+        }
+        finally {
+            await handle.cleanup();
+        }
+    }
+    formatSuccessDetail(result) {
+        const probeResult = result;
+        return {
+            detail: `${this.catalogName} ready${infoSuffix(probeResult.info)}`,
+            warnings: probeResult.warnings,
+        };
+    }
+    fixAdvice(error) {
+        if (error instanceof HistoricSqlGrantsMissingError) {
+            return {
+                failHeadline: 'BigQuery principal cannot read INFORMATION_SCHEMA.JOBS_BY_PROJECT',
+                remediation: error.remediation,
+            };
+        }
+        return {
+            failHeadline: `${this.catalogName} readiness check failed`,
+            remediation: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/context/ingest/historic-sql-probes/postgres-runner.d.ts

@@ -0,0 +1,26 @@
+import type { PostgresPgssProbeResult } from '../adapters/historic-sql/types.js';
+import { type HistoricSqlFixAdvice, type HistoricSqlProbeInput, type HistoricSqlProbeRunner, type HistoricSqlSuccessDetail } from '../historic-sql-probes.js';
+import { type KtxPostgresConnectionConfig } from '../../../connectors/postgres/connector.js';
+interface ClientHandle {
+    client: unknown;
+    cleanup(): Promise<void>;
+}
+interface PostgresPgssProbeRunnerOptions {
+    reader?: {
+        probe(client: unknown): Promise<PostgresPgssProbeResult>;
+    };
+    createClient?: (input: HistoricSqlProbeInput & {
+        connection: KtxPostgresConnectionConfig;
+    }) => ClientHandle;
+}
+export declare class PostgresPgssProbeRunner implements HistoricSqlProbeRunner {
+    readonly dialect: "postgres";
+    readonly catalogName = "pg_stat_statements";
+    private readonly reader;
+    private readonly createClient;
+    constructor(options?: PostgresPgssProbeRunnerOptions);
+    run(input: HistoricSqlProbeInput): Promise<PostgresPgssProbeResult>;
+    formatSuccessDetail(result: unknown): HistoricSqlSuccessDetail;
+    fixAdvice(error: unknown): HistoricSqlFixAdvice;
+}
+export {};

package/dist/context/ingest/historic-sql-probes/postgres-runner.js

@@ -0,0 +1,76 @@
+import { HistoricSqlExtensionMissingError, HistoricSqlGrantsMissingError, HistoricSqlVersionUnsupportedError, } from '../adapters/historic-sql/errors.js';
+import { PostgresPgssReader } from '../adapters/historic-sql/postgres-pgss-reader.js';
+import { isKtxPostgresConnectionConfig, } from '../../../connectors/postgres/connector.js';
+import { KtxPostgresHistoricSqlQueryClient } from '../../../connectors/postgres/historic-sql-query-client.js';
+function genericAdvice(error, catalogName) {
+    return {
+        failHeadline: `${catalogName} readiness check failed`,
+        remediation: error instanceof Error ? error.message : String(error),
+    };
+}
+function infoSuffix(info) {
+    return info && info.length > 0 ? `; ${info.join('; ')}` : '';
+}
+export class PostgresPgssProbeRunner {
+    dialect = 'postgres';
+    catalogName = 'pg_stat_statements';
+    reader;
+    createClient;
+    constructor(options = {}) {
+        this.reader = options.reader ?? new PostgresPgssReader();
+        this.createClient =
+            options.createClient ??
+                ((input) => {
+                    const client = new KtxPostgresHistoricSqlQueryClient({
+                        connectionId: input.connectionId,
+                        connection: input.connection,
+                        env: input.env,
+                    });
+                    return { client, cleanup: () => client.cleanup() };
+                });
+    }
+    async run(input) {
+        const inputDriver = input.connection.driver ?? 'unknown';
+        if (!isKtxPostgresConnectionConfig(input.connection)) {
+            throw new Error(`Native PostgreSQL connector cannot run driver "${inputDriver}"`);
+        }
+        const handle = this.createClient({
+            ...input,
+            connection: input.connection,
+        });
+        try {
+            return await this.reader.probe(handle.client);
+        }
+        finally {
+            await handle.cleanup();
+        }
+    }
+    formatSuccessDetail(result) {
+        const pgssResult = result;
+        return {
+            detail: `pg_stat_statements ready (${pgssResult.pgServerVersion})${infoSuffix(pgssResult.info)}`,
+            warnings: pgssResult.warnings,
+        };
+    }
+    fixAdvice(error) {
+        if (error instanceof HistoricSqlExtensionMissingError) {
+            return {
+                failHeadline: 'pg_stat_statements extension is missing',
+                remediation: error.remediation,
+            };
+        }
+        if (error instanceof HistoricSqlGrantsMissingError) {
+            return {
+                failHeadline: 'Postgres connection role lacks pg_read_all_stats',
+                remediation: error.remediation,
+            };
+        }
+        if (error instanceof HistoricSqlVersionUnsupportedError) {
+            return {
+                failHeadline: 'Postgres version too old',
+                remediation: 'Use PostgreSQL 14 or newer, or disable query history for this connection',
+            };
+        }
+        return genericAdvice(error, this.catalogName);
+    }
+}

package/dist/context/ingest/historic-sql-probes/snowflake-runner.d.ts

@@ -0,0 +1,29 @@
+import { type HistoricSqlFixAdvice, type HistoricSqlProbeInput, type HistoricSqlProbeRunner, type HistoricSqlSuccessDetail } from '../historic-sql-probes.js';
+import { type KtxSnowflakeConnectionConfig } from '../../../connectors/snowflake/connector.js';
+interface GenericProbeResult {
+    warnings: string[];
+    info?: string[];
+}
+interface ClientHandle {
+    client: unknown;
+    cleanup(): Promise<void>;
+}
+interface SnowflakeAccountUsageProbeRunnerOptions {
+    reader?: {
+        probe(client: unknown): Promise<GenericProbeResult>;
+    };
+    createClient?: (input: HistoricSqlProbeInput & {
+        connection: KtxSnowflakeConnectionConfig;
+    }) => ClientHandle;
+}
+export declare class SnowflakeAccountUsageProbeRunner implements HistoricSqlProbeRunner {
+    readonly dialect: "snowflake";
+    readonly catalogName = "SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY";
+    private readonly reader;
+    private readonly createClient;
+    constructor(options?: SnowflakeAccountUsageProbeRunnerOptions);
+    run(input: HistoricSqlProbeInput): Promise<GenericProbeResult>;
+    formatSuccessDetail(result: unknown): HistoricSqlSuccessDetail;
+    fixAdvice(error: unknown): HistoricSqlFixAdvice;
+}
+export {};

package/dist/context/ingest/historic-sql-probes/snowflake-runner.js

@@ -0,0 +1,62 @@
+import { HistoricSqlGrantsMissingError } from '../adapters/historic-sql/errors.js';
+import { SnowflakeHistoricSqlQueryHistoryReader } from '../adapters/historic-sql/snowflake-query-history-reader.js';
+import { isKtxSnowflakeConnectionConfig, } from '../../../connectors/snowflake/connector.js';
+import { KtxSnowflakeHistoricSqlQueryClient } from '../../../connectors/snowflake/historic-sql-query-client.js';
+function infoSuffix(info) {
+    return info && info.length > 0 ? `; ${info.join('; ')}` : '';
+}
+export class SnowflakeAccountUsageProbeRunner {
+    dialect = 'snowflake';
+    catalogName = 'SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY';
+    reader;
+    createClient;
+    constructor(options = {}) {
+        this.reader = options.reader ?? new SnowflakeHistoricSqlQueryHistoryReader();
+        this.createClient =
+            options.createClient ??
+                ((input) => {
+                    const client = new KtxSnowflakeHistoricSqlQueryClient({
+                        connectionId: input.connectionId,
+                        connection: input.connection,
+                        projectDir: input.projectDir,
+                        env: input.env,
+                    });
+                    return { client, cleanup: () => client.cleanup() };
+                });
+    }
+    async run(input) {
+        const inputDriver = input.connection.driver ?? 'unknown';
+        if (!isKtxSnowflakeConnectionConfig(input.connection)) {
+            throw new Error(`Native Snowflake connector cannot run driver "${inputDriver}"`);
+        }
+        const handle = this.createClient({
+            ...input,
+            connection: input.connection,
+        });
+        try {
+            return await this.reader.probe(handle.client);
+        }
+        finally {
+            await handle.cleanup();
+        }
+    }
+    formatSuccessDetail(result) {
+        const probeResult = result;
+        return {
+            detail: `${this.catalogName} ready${infoSuffix(probeResult.info)}`,
+            warnings: probeResult.warnings,
+        };
+    }
+    fixAdvice(error) {
+        if (error instanceof HistoricSqlGrantsMissingError) {
+            return {
+                failHeadline: 'Snowflake role cannot read SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY',
+                remediation: error.remediation,
+            };
+        }
+        return {
+            failHeadline: `${this.catalogName} readiness check failed`,
+            remediation: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/context/ingest/historic-sql-probes.d.ts

@@ -0,0 +1,46 @@
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+import type { HistoricSqlDialect } from './adapters/historic-sql/types.js';
+export interface HistoricSqlFixAdvice {
+    failHeadline: string;
+    remediation: string;
+}
+export interface HistoricSqlSuccessDetail {
+    detail: string;
+    warnings: string[];
+}
+export interface HistoricSqlProbeInput {
+    projectDir: string;
+    connectionId: string;
+    connection: KtxProjectConnectionConfig;
+    env?: NodeJS.ProcessEnv;
+}
+export interface HistoricSqlProbeRunner {
+    readonly dialect: HistoricSqlDialect;
+    readonly catalogName: string;
+    run(input: HistoricSqlProbeInput): Promise<unknown>;
+    formatSuccessDetail(result: unknown): HistoricSqlSuccessDetail;
+    fixAdvice(error: unknown): HistoricSqlFixAdvice;
+}
+/** @internal */
+export interface HistoricSqlProbeRunnerFactoryEntry {
+    readonly catalogName: string;
+    load(): Promise<HistoricSqlProbeRunner>;
+}
+export type HistoricSqlProbeOutcome = {
+    ok: true;
+    dialect: HistoricSqlDialect;
+    runner: HistoricSqlProbeRunner;
+    result: unknown;
+} | {
+    ok: false;
+    dialect: HistoricSqlDialect;
+    runner: HistoricSqlProbeRunner;
+    error: unknown;
+};
+export type HistoricSqlReadinessProbe = (input: HistoricSqlProbeInput) => Promise<HistoricSqlProbeOutcome | null>;
+export interface HistoricSqlProbeRegistryDeps {
+    factories?: Record<HistoricSqlDialect, HistoricSqlProbeRunnerFactoryEntry>;
+    cache?: Map<HistoricSqlDialect, HistoricSqlProbeRunner>;
+}
+export declare function historicSqlProbeCatalogName(dialect: HistoricSqlDialect, deps?: HistoricSqlProbeRegistryDeps): string;
+export declare function runHistoricSqlReadinessProbe(input: HistoricSqlProbeInput, deps?: HistoricSqlProbeRegistryDeps): Promise<HistoricSqlProbeOutcome | null>;

package/dist/context/ingest/historic-sql-probes.js

@@ -0,0 +1,62 @@
+import { queryHistoryDialectForConnection } from './adapters/historic-sql/connection-dialect.js';
+const defaultHistoricSqlProbeRunnerFactories = {
+    postgres: {
+        catalogName: 'pg_stat_statements',
+        load: async () => {
+            const { PostgresPgssProbeRunner } = await import('./historic-sql-probes/postgres-runner.js');
+            return new PostgresPgssProbeRunner();
+        },
+    },
+    snowflake: {
+        catalogName: 'SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY',
+        load: async () => {
+            const { SnowflakeAccountUsageProbeRunner } = await import('./historic-sql-probes/snowflake-runner.js');
+            return new SnowflakeAccountUsageProbeRunner();
+        },
+    },
+    bigquery: {
+        catalogName: 'INFORMATION_SCHEMA.JOBS_BY_PROJECT',
+        load: async () => {
+            const { BigQueryJobsByProjectProbeRunner } = await import('./historic-sql-probes/bigquery-runner.js');
+            return new BigQueryJobsByProjectProbeRunner();
+        },
+    },
+};
+const DEFAULT_RUNNER_CACHE = new Map();
+function registryDeps(input) {
+    return {
+        factories: input.factories ?? defaultHistoricSqlProbeRunnerFactories,
+        cache: input.cache ?? DEFAULT_RUNNER_CACHE,
+    };
+}
+export function historicSqlProbeCatalogName(dialect, deps = {}) {
+    return registryDeps(deps).factories[dialect].catalogName;
+}
+async function loadHistoricSqlProbeRunner(dialect, deps = {}) {
+    const { factories, cache } = registryDeps(deps);
+    const cached = cache.get(dialect);
+    if (cached) {
+        return cached;
+    }
+    const runner = await factories[dialect].load();
+    cache.set(dialect, runner);
+    return runner;
+}
+export async function runHistoricSqlReadinessProbe(input, deps = {}) {
+    const dialect = queryHistoryDialectForConnection(input.connection);
+    if (!dialect) {
+        return null;
+    }
+    const runner = await loadHistoricSqlProbeRunner(dialect, deps);
+    try {
+        return {
+            ok: true,
+            dialect,
+            runner,
+            result: await runner.run(input),
+        };
+    }
+    catch (error) {
+        return { ok: false, dialect, runner, error };
+    }
+}

package/dist/context/ingest/local-adapters.js

@@ -103,7 +103,6 @@ function isRecord(value) {
 }
 const historicSqlDialectByDriver = new Map([
     ['postgres', 'postgres'],
-    ['postgresql', 'postgres'],
     ['bigquery', 'bigquery'],
     ['snowflake', 'snowflake'],
 ]);

package/dist/context/ingest/local-ingest.js

@@ -203,7 +203,7 @@ async function recordLocalMetabaseChildFailure(options) {
 }
 export async function runLocalMetabaseIngest(options) {
     if (options.sourceDir) {
-        throw new Error('source-dir uploads are not supported for the Metabase fan-out adapter');
+        throw new Error('source-dir uploads are not supported for the Metabase fanout adapter');
     }
     const metabaseConnectionId = safeSegment('metabase connection id', options.metabaseConnectionId);
     assertConfigured(options.project, 'metabase', metabaseConnectionId);

package/dist/context/llm/claude-code-runtime.js

@@ -28,6 +28,21 @@ const STRUCTURED_OUTPUT_TOOL_NAME = 'StructuredOutput';
 function isResult(message) {
     return message.type === 'result';
 }
+// Skip emissions the SDK does not count toward `num_turns`: `pause_turn` continuations and
+// errored partials (e.g. `max_output_tokens`) it retries internally. Without this, the
+// runtime's step counter outruns `maxTurns` and the HUD renders e.g. `step 69/40`.
+function countsAsAssistantTurn(message) {
+    if (message.type !== 'assistant' || message.parent_tool_use_id !== null) {
+        return false;
+    }
+    if (message.error !== undefined) {
+        return false;
+    }
+    if (message.message.stop_reason === 'pause_turn') {
+        return false;
+    }
+    return true;
+}
 function resultError(result) {
     if (result.subtype === 'success') {
         return undefined;
@@ -124,7 +139,7 @@ async function collectResult(params) {
     let result;
     for await (const message of params.query({ prompt: params.prompt, options: params.options })) {
         assertInitIsolation(message, params.allowedToolIds, params.expectedMcpServerNames);
-        if (message.type === 'assistant' && message.parent_tool_use_id === null) {
+        if (countsAsAssistantTurn(message)) {
             await params.onAssistantTurn?.();
         }
         if (isResult(message)) {

package/dist/context/mcp/context-tools.js

@@ -27,10 +27,10 @@ const toolDescriptions = {
     discover_data: 'Search across KTX wiki pages, semantic-layer sources, measures, dimensions, raw tables, and columns. Example: discover_data({ query: "monthly orders by customer", connectionId: "warehouse", kinds: ["sl_source", "table"] }).',
     wiki_search: 'Search KTX wiki pages for reusable business context. Example: wiki_search({ query: "revenue recognition", limit: 5 }).',
     wiki_read: 'Read a KTX wiki page by key returned from wiki_search. Example: wiki_read({ key: "global/revenue" }).',
-    entity_details: 'Read table and column metadata from the latest live-database scan snapshot. Example: entity_details({ connectionId: "warehouse", entities: [{ table: { schema: "public", table: "orders" }, columns: ["id"] }] }).',
+    entity_details: 'Read table and column metadata from the latest live-database scan snapshot. Example: entity_details({ connectionId: "warehouse", entities: [{ table: { catalog: null, db: "public", name: "orders" }, columns: ["id"] }] }).',
     dictionary_search: 'Search profile-sampled warehouse values to locate likely source columns for business values. Example: dictionary_search({ values: ["Acme Corp"], connectionId: "warehouse" }).',
     sl_read_source: 'Read a semantic-layer YAML source by connection id and source name. Example: sl_read_source({ connectionId: "warehouse", sourceName: "orders" }).',
-    sl_query: 'Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ dimension: "orders.created_at", granularity: "month" }] }).',
+    sl_query: 'Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }] }).',
     sql_execution: 'Execute one parser-validated read-only SQL query against a configured KTX connection. Example: sql_execution({ connectionId: "warehouse", sql: "select count(*) from public.orders", maxRows: 100 }).',
     memory_ingest: 'Ingest free-form markdown knowledge into durable KTX memory. Use this for business rules, metric definitions, schema gotchas, recurring findings, or explicit user requests to remember something. Example: memory_ingest({ connectionId: "warehouse", content: "ARR is reported in cents in this warehouse." }).',
     memory_ingest_status: 'Read the current or final status for a memory ingest run. Example: memory_ingest_status({ runId: "memory-run-1" }).',
@@ -54,40 +54,15 @@ const slQueryMeasureSchema = z.union([
         name: z.string().min(1).describe('Alias for the ad hoc measure, e.g. "gross_revenue".'),
     }),
 ]);
-const slQueryDimensionSchema = z.preprocess((value) => {
-    if (typeof value === 'string')
-        return { field: value };
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-        const obj = { ...value };
-        if (!('field' in obj) && typeof obj.dimension === 'string')
-            obj.field = obj.dimension;
-        return obj;
-    }
-    return value;
-}, z.object({
+const slQueryDimensionSchema = z.object({
     field: z.string().min(1).describe('Dimension to group by, e.g. "orders.created_at" or "orders.status".'),
     granularity: z
         .string()
         .min(1)
         .optional()
         .describe('Time grain for time dimensions: day, week, month, quarter, or year.'),
-}));
-const slQueryOrderBySchema = z.preprocess((value) => {
-    if (typeof value === 'string') {
-        return { field: value };
-    }
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-        const obj = { ...value };
-        if (!('field' in obj) && typeof obj.id === 'string') {
-            obj.field = obj.id;
-        }
-        if (!('direction' in obj) && 'desc' in obj) {
-            obj.direction = obj.desc === true ? 'desc' : 'asc';
-        }
-        return obj;
-    }
-    return value;
-}, z.object({
+});
+const slQueryOrderBySchema = z.object({
     field: z
         .string()
         .min(1)
@@ -96,7 +71,7 @@ const slQueryOrderBySchema = z.preprocess((value) => {
         .enum(['asc', 'desc'])
         .default('asc')
         .describe('Sort direction: "asc" or "desc". Defaults to "asc".'),
-}));
+});
 const slQuerySchema = z.object({
     connectionId: connectionIdSchema
         .optional()
@@ -105,7 +80,7 @@ const slQuerySchema = z.object({
     dimensions: z
         .array(slQueryDimensionSchema)
         .default([])
-        .describe('Dimensions to group by. Strings and {dimension, granularity} are accepted.'),
+        .describe('Dimensions to group by. Use {field, granularity?} entries.'),
     filters: z
         .array(z.string().describe('Semantic-layer filter expression, e.g. "orders.status = paid".'))
         .default([])
@@ -117,34 +92,22 @@ const slQuerySchema = z.object({
     order_by: z
         .array(slQueryOrderBySchema)
         .default([])
-        .describe('Sort clauses. Strings and Cube-style {id, desc} are accepted.'),
+        .describe('Sort clauses. Use {field, direction?} entries.'),
     limit: z.number().int().min(0).default(1000).describe('Maximum rows to return. Defaults to 1000.'),
     include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups. Defaults to true.'),
 });
-const entityDetailsTableRefSchema = z.preprocess((value) => {
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-        const obj = { ...value };
-        if (!('db' in obj) && typeof obj.schema === 'string')
-            obj.db = obj.schema;
-        if (!('name' in obj) && typeof obj.table === 'string')
-            obj.name = obj.table;
-        if (!('catalog' in obj))
-            obj.catalog = null;
-        return obj;
-    }
-    return value;
-}, z.object({
+const entityDetailsTableRefSchema = z.object({
     catalog: z.string().nullable().describe('Catalog/project/database. Use null when not applicable.'),
     db: z.string().nullable().describe('Schema/database/dataset. Use null when not applicable.'),
     name: z.string().min(1).describe('Table name.'),
-}));
+});
 const entityDetailsSchema = z.object({
     connectionId: connectionIdSchema.describe('Connection id whose latest scan snapshot should be read.'),
     entities: z
         .array(z.object({
         table: z
             .union([z.string().min(1), entityDetailsTableRefSchema])
-            .describe('Table display string or object ref. {schema, table} is accepted as an alias for {db, name}.'),
+            .describe('Table display string or canonical object ref.'),
         columns: z
             .array(z.string().min(1).describe('Column name to inspect.'))
             .optional()

package/dist/context/mcp/local-project-ports.js

@@ -7,17 +7,14 @@ import { readLocalKnowledgePage, searchLocalKnowledgePages } from '../wiki/local
 function dialectForDriver(driver) {
     const normalized = (driver ?? 'postgres').toUpperCase();
     const map = {
-        POSTGRESQL: 'postgres',
         POSTGRES: 'postgres',
         BIGQUERY: 'bigquery',
         SNOWFLAKE: 'snowflake',
         MYSQL: 'mysql',
         SQLSERVER: 'tsql',
-        MSSQL: 'tsql',
         SQLITE: 'sqlite',
         DUCKDB: 'duckdb',
         CLICKHOUSE: 'clickhouse',
-        REDSHIFT: 'redshift',
         DATABRICKS: 'databricks',
     };
     return map[normalized] ?? 'postgres';

package/dist/context/project/config.d.ts

@@ -106,10 +106,6 @@ declare const connectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     driver: z.ZodLiteral<"postgres">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$loose>, z.ZodObject<{
-    driver: z.ZodLiteral<"postgresql">;
-    url: z.ZodOptional<z.ZodString>;
-    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"mysql">;
     url: z.ZodOptional<z.ZodString>;
@@ -214,10 +210,6 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
         driver: z.ZodLiteral<"postgres">;
         url: z.ZodOptional<z.ZodString>;
         enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$loose>, z.ZodObject<{
-        driver: z.ZodLiteral<"postgresql">;
-        url: z.ZodOptional<z.ZodString>;
-        enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$loose>, z.ZodObject<{
         driver: z.ZodLiteral<"mysql">;
         url: z.ZodOptional<z.ZodString>;

package/dist/context/project/driver-schemas.d.ts

@@ -3,10 +3,6 @@ export declare const connectionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     driver: z.ZodLiteral<"postgres">;
     url: z.ZodOptional<z.ZodString>;
     enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$loose>, z.ZodObject<{
-    driver: z.ZodLiteral<"postgresql">;
-    url: z.ZodOptional<z.ZodString>;
-    enabled_tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>, z.ZodObject<{
     driver: z.ZodLiteral<"mysql">;
     url: z.ZodOptional<z.ZodString>;

package/dist/context/project/driver-schemas.js

@@ -2,7 +2,6 @@ import * as z from 'zod';
 import { lookerMappingsSchema, lookmlMappingsSchema, metabaseMappingsSchema, } from './mappings-yaml-schema.js';
 const warehouseDrivers = [
     'postgres',
-    'postgresql',
     'mysql',
     'snowflake',
     'bigquery',
@@ -28,7 +27,6 @@ function warehouseConnectionSchema(driver) {
 }
 const warehouseConnectionSchemas = [
     warehouseConnectionSchema('postgres'),
-    warehouseConnectionSchema('postgresql'),
     warehouseConnectionSchema('mysql'),
     warehouseConnectionSchema('snowflake'),
     warehouseConnectionSchema('bigquery'),

package/dist/context/scan/constraint-discovery.d.ts

@@ -0,0 +1,19 @@
+import type { KtxScanWarning } from './types.js';
+export type ConstraintDiscoveryKind = 'primary_key' | 'foreign_key';
+export interface ConstraintQueryContext {
+    schema: string;
+    kind: ConstraintDiscoveryKind;
+    isDeniedError: (error: unknown) => boolean;
+}
+export type ConstraintQueryOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    warning: KtxScanWarning;
+};
+export declare function constraintDiscoveryWarning(input: {
+    schema: string;
+    kind: ConstraintDiscoveryKind;
+}): KtxScanWarning;
+export declare function tryConstraintQuery<T>(ctx: ConstraintQueryContext, fn: () => Promise<T>): Promise<ConstraintQueryOutcome<T>>;