@kaelio/ktx 0.7.0 → 0.9.0

package/dist/context/sql-analysis/http-sql-analysis-port.js

@@ -59,6 +59,13 @@ function optionalString(raw, field) {
     }
     throw new Error(`sql analysis response has invalid optional string field ${field}`);
 }
+function optionalNullableStringField(raw, field) {
+    const value = raw[field];
+    if (value === null || value === undefined || typeof value === 'string') {
+        return value ?? null;
+    }
+    throw new Error(`sql analysis response has invalid optional nullable string field ${field}`);
+}
 function requiredStringArray(raw, field) {
     const value = raw[field];
     if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
@@ -136,10 +143,32 @@ function mapColumnsByClause(raw) {
     }
     return result;
 }
+function requiredTableRef(raw, field) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`sql analysis response contains invalid table ref in ${field}`);
+    }
+    const record = raw;
+    const name = record.name;
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(`sql analysis response table ref in ${field} is missing name`);
+    }
+    return {
+        catalog: optionalNullableStringField(record, 'catalog'),
+        db: optionalNullableStringField(record, 'db'),
+        name,
+    };
+}
+function requiredTableRefArray(raw, field) {
+    const value = raw[field];
+    if (!Array.isArray(value)) {
+        throw new Error(`sql analysis response is missing table-ref[] field ${field}`);
+    }
+    return value.map((item, index) => requiredTableRef(item, `${field}.${index}`));
+}
 function mapBatchResult(raw) {
     const error = optionalString(raw, 'error');
     return {
-        tablesTouched: requiredStringArray(raw, 'tables_touched'),
+        tablesTouched: requiredTableRefArray(raw, 'tables_touched'),
         columnsByClause: mapColumnsByClause(raw),
         ...(error !== undefined ? { error } : {}),
     };
@@ -170,10 +199,11 @@ export function createHttpSqlAnalysisPort(options) {
             });
             return mapResult(raw);
         },
-        async analyzeBatch(items, dialect) {
+        async analyzeBatch(items, dialect, options) {
             const raw = await requestJson('/sql/analyze-batch', {
                 dialect,
                 items,
+                ...(options?.catalog ? { catalog: options.catalog } : {}),
             });
             return mapBatchResponse(raw);
         },

package/dist/context/sql-analysis/ports.d.ts

@@ -1,3 +1,4 @@
+import type { KtxTableRef } from '../scan/types.js';
 export type SqlAnalysisDialect = 'bigquery' | 'snowflake' | 'postgres' | 'redshift' | 'mysql' | 'sqlite' | 'tsql' | 'clickhouse' | (string & {});
 export type SqlAnalysisLiteralSlotType = 'string' | 'number' | 'timestamp' | 'date' | 'boolean' | 'null' | 'unknown';
 export interface SqlAnalysisLiteralSlot {
@@ -17,8 +18,17 @@ export interface SqlAnalysisBatchItem {
     id: string;
     sql: string;
 }
+interface SqlAnalysisCatalogTable extends KtxTableRef {
+    columns?: string[];
+}
+interface SqlAnalysisCatalog {
+    tables: SqlAnalysisCatalogTable[];
+}
+export interface SqlAnalysisBatchOptions {
+    catalog?: SqlAnalysisCatalog;
+}
 export interface SqlAnalysisBatchResult {
-    tablesTouched: string[];
+    tablesTouched: KtxTableRef[];
     columnsByClause: Partial<Record<SqlAnalysisClause, string[]>>;
     error?: string | null;
 }
@@ -28,7 +38,7 @@ export interface SqlReadOnlyValidationResult {
 }
 export interface SqlAnalysisPort {
     analyzeForFingerprint(sql: string, dialect: SqlAnalysisDialect): Promise<SqlAnalysisFingerprintResult>;
-    analyzeBatch(items: SqlAnalysisBatchItem[], dialect: SqlAnalysisDialect): Promise<Map<string, SqlAnalysisBatchResult>>;
+    analyzeBatch(items: SqlAnalysisBatchItem[], dialect: SqlAnalysisDialect, options?: SqlAnalysisBatchOptions): Promise<Map<string, SqlAnalysisBatchResult>>;
     validateReadOnly(sql: string, dialect: SqlAnalysisDialect): Promise<SqlReadOnlyValidationResult>;
 }
 export {};

package/dist/context/tools/context-candidate-mark.tool.d.ts

@@ -8,8 +8,8 @@ declare const contextCandidateMarkInputSchema: z.ZodObject<{
         conflict: "conflict";
         merged: "merged";
         pending: "pending";
-        promoted: "promoted";
         rejected: "rejected";
+        promoted: "promoted";
     }>;
     rejectionReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
@@ -31,8 +31,8 @@ export declare class ContextCandidateMarkTool extends BaseTool<typeof contextCan
             conflict: "conflict";
             merged: "merged";
             pending: "pending";
-            promoted: "promoted";
             rejected: "rejected";
+            promoted: "promoted";
         }>;
         rejectionReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>;

package/dist/context/wiki/local-knowledge.d.ts

@@ -50,6 +50,16 @@ export declare function readLocalKnowledgePage(project: KtxLocalProject, input:
 export declare function listLocalKnowledgePages(project: KtxLocalProject, input?: {
     userId?: string;
 }): Promise<LocalKnowledgeSummary[]>;
+/**
+ * List wiki page keys without reading or parsing file contents.
+ *
+ * Keys are derived purely from file paths, so this stays cheap enough for
+ * shell tab-completion (unlike `listLocalKnowledgePages`, which reads every
+ * page to populate summaries).
+ */
+export declare function listLocalKnowledgePageKeys(project: KtxLocalProject, input?: {
+    userId?: string;
+}): Promise<string[]>;
 export declare function searchLocalKnowledgePages(project: KtxLocalProject, input: {
     query: string;
     userId?: string;

package/dist/context/wiki/local-knowledge.js

@@ -118,6 +118,28 @@ export async function listLocalKnowledgePages(project, input = {}) {
     }
     return pages.sort((left, right) => left.path.localeCompare(right.path));
 }
+/**
+ * List wiki page keys without reading or parsing file contents.
+ *
+ * Keys are derived purely from file paths, so this stays cheap enough for
+ * shell tab-completion (unlike `listLocalKnowledgePages`, which reads every
+ * page to populate summaries).
+ */
+export async function listLocalKnowledgePageKeys(project, input = {}) {
+    const userId = input.userId ?? 'local';
+    const keys = new Set();
+    for (const scope of ['GLOBAL', 'USER']) {
+        const root = scope === 'GLOBAL' ? 'wiki/global' : `wiki/user/${assertSafePathToken('user id', userId)}`;
+        const listed = await project.fileStore.listFiles(root);
+        for (const path of listed.files.filter((file) => file.endsWith('.md'))) {
+            const key = keyFromKnowledgePath(path, scope, userId);
+            if (key) {
+                keys.add(key);
+            }
+        }
+    }
+    return [...keys].sort();
+}
 function scorePage(page, terms) {
     const haystack = buildKnowledgeSearchText(page.key, page.summary, page.content, page.tags).toLowerCase();
     return terms.some((term) => haystack.includes(term)) ? 3 : 0;

package/dist/context-build-view.d.ts

@@ -39,9 +39,6 @@ export interface ContextBuildArgs {
     targetConnectionId?: string;
     all?: boolean;
     entrypoint?: 'setup' | 'ingest';
-    depth?: Extract<KtxPublicIngestArgs, {
-        command: 'run';
-    }>['depth'];
     queryHistory?: Extract<KtxPublicIngestArgs, {
         command: 'run';
     }>['queryHistory'];

package/dist/context-build-view.js

@@ -1,5 +1,5 @@
-import { publicDatabaseIngestMessage, publicQueryHistoryMessage } from './public-ingest-copy.js';
-import { buildPublicIngestPlan, executePublicIngestTarget } from './public-ingest.js';
+import { buildPublicIngestPlan, executePublicIngestTarget, publicProgressMessage } from './public-ingest.js';
+import { createAggregateProgressPort } from './progress-port-adapter.js';
 import { formatDuration } from './demo-metrics.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:context-build-view');
@@ -241,12 +241,11 @@ function renderMessageGroup(label, messages, styled) {
 function retryCommand(input) {
     const projectPart = input.projectDir ? ` --project-dir ${input.projectDir}` : '';
     if (input.entrypoint === 'ingest' && input.connectionId) {
-        const depthPart = input.depth ? ` --${input.depth}` : '';
         const queryHistoryPart = input.queryHistory ? ' --query-history' : '';
         const windowPart = input.queryHistory && input.queryHistoryWindowDays !== undefined
             ? ` --query-history-window-days ${input.queryHistoryWindowDays}`
             : '';
-        return `ktx ingest ${input.connectionId}${projectPart}${depthPart}${queryHistoryPart}${windowPart}`;
+        return `ktx ingest ${input.connectionId}${projectPart}${queryHistoryPart}${windowPart}`;
     }
     return input.projectDir ? `ktx setup --project-dir ${input.projectDir}` : 'ktx setup';
 }
@@ -563,7 +562,6 @@ function appendRetryIfNeeded(input) {
         projectDir: input.projectDir,
         entrypoint: input.entrypoint,
         connectionId: input.target.connectionId,
-        depth: input.target.databaseDepth,
         queryHistory: input.target.queryHistory?.enabled === true,
         queryHistoryWindowDays: input.target.queryHistory?.windowDays,
     })}`;
@@ -578,7 +576,6 @@ function failureTextForTarget(input) {
                 projectDir: input.projectDir,
                 entrypoint: input.entrypoint,
                 connectionId: input.target.connectionId,
-                depth: input.target.databaseDepth,
                 queryHistory: input.target.queryHistory?.enabled === true,
                 queryHistoryWindowDays: input.target.queryHistory?.windowDays,
             })}`,
@@ -593,7 +590,6 @@ function failureTextForTarget(input) {
                 projectDir: input.projectDir,
                 entrypoint: input.entrypoint,
                 connectionId: input.target.connectionId,
-                depth: input.target.databaseDepth,
                 queryHistory: input.target.queryHistory?.enabled === true,
                 queryHistoryWindowDays: input.target.queryHistory?.windowDays,
             })}`,
@@ -622,44 +618,15 @@ export function initViewState(targets) {
         totalElapsedMs: 0,
     };
 }
-function publicProgressMessage(message, target) {
-    let current = message;
-    if (target.operation === 'database-ingest') {
-        current = publicDatabaseIngestMessage(current);
-    }
-    if (target.steps.includes('query-history')) {
-        current = publicQueryHistoryMessage(current, target.connectionId);
-    }
-    return current;
-}
 function formatProgressDetail(update, target) {
     const percent = Math.max(0, Math.min(100, Math.round(update.percent)));
     return `[${percent}%] ${publicProgressMessage(update.message, target)}`;
 }
-function createContextBuildProgressPort(onProgress, state = { progress: 0 }, start = 0, weight = 1) {
-    return {
-        async update(value, message, options) {
-            const absoluteValue = start + Math.max(0, Math.min(1, value)) * weight;
-            state.progress = Math.max(state.progress, Math.min(1, absoluteValue));
-            if (!message)
-                return;
-            onProgress({
-                percent: Math.max(0, Math.min(100, Math.round(state.progress * 100))),
-                message,
-                ...(options?.transient !== undefined ? { transient: options.transient } : {}),
-            });
-        },
-        startPhase(phaseWeight) {
-            return createContextBuildProgressPort(onProgress, state, state.progress, weight * phaseWeight);
-        },
-    };
-}
 export async function runContextBuild(project, args, io, deps = {}) {
     const plan = buildPublicIngestPlan(project, {
         projectDir: args.projectDir,
         ...(args.targetConnectionId ? { targetConnectionId: args.targetConnectionId } : {}),
         all: args.all ?? true,
-        ...(args.depth ? { depth: args.depth } : {}),
         ...(args.queryHistory ? { queryHistory: args.queryHistory } : {}),
         ...(args.queryHistoryWindowDays !== undefined ? { queryHistoryWindowDays: args.queryHistoryWindowDays } : {}),
         ...(args.scanMode ? { scanMode: args.scanMode } : {}),
@@ -721,7 +688,6 @@ export async function runContextBuild(project, args, io, deps = {}) {
         all: args.all ?? true,
         json: false,
         inputMode: args.inputMode,
-        ...(args.depth ? { depth: args.depth } : {}),
         ...(args.queryHistory ? { queryHistory: args.queryHistory } : {}),
         ...(args.queryHistoryWindowDays !== undefined ? { queryHistoryWindowDays: args.queryHistoryWindowDays } : {}),
         ...(args.scanMode ? { scanMode: args.scanMode } : {}),
@@ -808,7 +774,7 @@ export async function runContextBuild(project, args, io, deps = {}) {
                 hasPendingProgressPublish = !publishSourceProgress(false);
             };
             const progressDeps = {
-                scanProgress: createContextBuildProgressPort(updateSchemaPhase),
+                scanProgress: createAggregateProgressPort(updateSchemaPhase),
                 ingestProgress: updateIngestPhase,
                 runtimeIo: io,
                 onPhaseStart,
@@ -817,7 +783,7 @@ export async function runContextBuild(project, args, io, deps = {}) {
             let result = null;
             let thrownError = null;
             try {
-                result = await execTarget(targetState.target, runArgs, capture.io, progressDeps);
+                result = await execTarget(targetState.target, runArgs, capture.io, progressDeps, project);
             }
             catch (error) {
                 thrownError = error;

package/dist/ingest.js

@@ -2,7 +2,7 @@ import { buildMemoryFlowViewModel } from './context/ingest/memory-flow/view-mode
 import { createMemoryFlowLiveBuffer, sanitizeMemoryFlowError } from './context/ingest/memory-flow/live-buffer.js';
 import { formatMemoryFlowFinalSummary } from './context/ingest/memory-flow/summary.js';
 import { getLatestLocalIngestStatus, getLocalIngestStatus, runLocalIngest, runLocalMetabaseIngest } from './context/ingest/local-ingest.js';
-import { savedMemoryCountsForReport } from './context/ingest/reports.js';
+import { ingestReportOutcome, savedMemoryCountsForReport } from './context/ingest/reports.js';
 import { ingestReportToMemoryFlowReplay } from './context/ingest/memory-flow/events.js';
 import { renderMemoryFlowReplay } from './context/ingest/memory-flow/render.js';
 import { loadKtxProject } from './context/project/project.js';
@@ -17,9 +17,6 @@ import { renderMemoryFlowTui, startLiveMemoryFlowTui, } from './memory-flow-tui.
 import { resolveVizFallback, warnVizFallbackOnce } from './viz-fallback.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:ingest');
-function reportStatus(report) {
-    return report.body.status === 'failed' || report.body.failedWorkUnits.length > 0 ? 'error' : 'done';
-}
 const REPORT_SOURCE_LABELS = new Map([
     ['live-database', 'Database schema'],
     ['historic-sql', 'Query history'],
@@ -106,7 +103,7 @@ function writeReportStatus(report, io) {
     if (report.body.tracePath) {
         io.stdout.write(`Trace: ${report.body.tracePath}\n`);
     }
-    io.stdout.write(`Status: ${reportStatus(report)}\n`);
+    io.stdout.write(`Status: ${ingestReportOutcome(report)}\n`);
     io.stdout.write(`Source: ${reportSourceLabel(report.sourceKey)}\n`);
     io.stdout.write(`Connection: ${report.connectionId}\n`);
     io.stdout.write(`Sync: ${report.body.syncId}\n`);
@@ -138,7 +135,7 @@ function writeMetabaseFanoutStatus(result, io) {
     }
     io.stdout.write(`Saved memory: ${counts.wikiCount} wiki, ${counts.slCount} SL\n`);
     for (const child of result.children) {
-        const status = reportStatus(child.report);
+        const status = ingestReportOutcome(child.report);
         io.stdout.write(`- target=${child.targetConnectionId} database=${child.metabaseDatabaseId} status=${status} job=${child.jobId} report=${child.report.id}\n`);
     }
 }
@@ -425,7 +422,7 @@ function initialRunMemoryFlowInput(args, runId) {
     };
 }
 function finalRunMemoryFlowInput(snapshot, report) {
-    const status = reportStatus(report);
+    const status = ingestReportOutcome(report) === 'error' ? 'error' : 'done';
     return {
         ...snapshot,
         runId: report.runId,
@@ -574,7 +571,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                 finally {
                     plainProgress?.flush();
                 }
-                return result.status === 'all_succeeded' ? 0 : 1;
+                return result.status === 'all_failed' ? 1 : 0;
             }
             const jobId = deps.jobIdFactory?.();
             let liveTui = null;
@@ -636,7 +633,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     liveTui?.close();
                     liveTui = null;
                     io.stdout.write(formatMemoryFlowFinalSummary(latestMemoryFlowSnapshot));
-                    return reportStatus(result.report) === 'done' ? 0 : 1;
+                    return ingestReportOutcome(result.report) === 'error' ? 1 : 0;
                 }
                 plainProgress?.flush();
                 await writeReportRecord(result.report, runOutputMode, io, {
@@ -644,7 +641,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     renderStoredMemoryFlow: deps.renderStoredMemoryFlow,
                     env,
                 });
-                return reportStatus(result.report) === 'done' ? 0 : 1;
+                return ingestReportOutcome(result.report) === 'error' ? 1 : 0;
             }
             finally {
                 plainProgress?.flush();

package/dist/io/buffered-command-io.d.ts

@@ -0,0 +1,11 @@
+import type { KtxCliIo } from '../cli-runtime.js';
+export interface BufferedCommandIo extends KtxCliIo {
+    stdoutText(): string;
+    stderrText(): string;
+}
+/**
+ * Captures stdout/stderr from a command (e.g. `runKtxConnection`) into buffers
+ * instead of the terminal. Callers decide whether to flush the captured text to
+ * the user or discard it.
+ */
+export declare function createBufferedCommandIo(): BufferedCommandIo;

package/dist/io/buffered-command-io.js

@@ -0,0 +1,28 @@
+/**
+ * Captures stdout/stderr from a command (e.g. `runKtxConnection`) into buffers
+ * instead of the terminal. Callers decide whether to flush the captured text to
+ * the user or discard it.
+ */
+export function createBufferedCommandIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        stdout: {
+            isTTY: false,
+            write(chunk) {
+                stdout += chunk;
+            },
+        },
+        stderr: {
+            write(chunk) {
+                stderr += chunk;
+            },
+        },
+        stdoutText() {
+            return stdout;
+        },
+        stderrText() {
+            return stderr;
+        },
+    };
+}

package/dist/knowledge.d.ts

@@ -18,6 +18,11 @@ export type KtxKnowledgeArgs = {
     limit?: number;
     debug?: boolean;
     cliVersion: string;
+} | {
+    command: 'read';
+    projectDir: string;
+    key: string;
+    userId: string;
 };
 type KtxKnowledgeIo = import('./cli-runtime.js').KtxCliIo;
 interface KtxKnowledgeDeps {

package/dist/knowledge.js

@@ -1,6 +1,6 @@
 import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
 import { loadKtxProject } from './context/project/project.js';
-import { listLocalKnowledgePages, searchLocalKnowledgePages as defaultSearchLocalKnowledgePages } from './context/wiki/local-knowledge.js';
+import { listLocalKnowledgePages, readLocalKnowledgePage, searchLocalKnowledgePages as defaultSearchLocalKnowledgePages, } from './context/wiki/local-knowledge.js';
 import { resolveProjectEmbeddingProvider, } from './embedding-resolution.js';
 import { resolveOutputMode } from './io/mode.js';
 import { createRankBadgeFormatter, printList } from './io/print-list.js';
@@ -72,6 +72,15 @@ export async function runKtxKnowledge(args, io = process, deps = {}) {
             });
             return 0;
         }
+        if (args.command === 'read') {
+            const page = await readLocalKnowledgePage(project, { key: args.key, userId: args.userId });
+            if (!page) {
+                throw new Error(`No wiki page found for key '${args.key}'`);
+            }
+            const raw = await project.fileStore.readFile(page.path);
+            io.stdout.write(raw.content);
+            return 0;
+        }
         if (args.command === 'search') {
             const embeddingService = await wikiSearchEmbeddingService(project, deps, { cliVersion: args.cliVersion }, io);
             const search = deps.searchLocalKnowledgePages ?? defaultSearchLocalKnowledgePages;

package/dist/llm/types.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel, TelemetrySettings, ToolCallRepairFunction, ToolSet } from 'ai';
 export declare const KTX_MODEL_ROLES: readonly ["default", "triage", "candidateExtraction", "curator", "reconcile", "repair"];
 export type KtxModelRole = (typeof KTX_MODEL_ROLES)[number];
-type KtxLlmBackend = 'anthropic' | 'vertex' | 'gateway' | 'claude-code';
+type KtxLlmBackend = 'anthropic' | 'vertex' | 'gateway' | 'claude-code' | 'codex';
 export type KtxPromptCacheTtl = '5m' | '1h';
 type KtxJsonValue = null | string | number | boolean | KtxJsonValue[] | {
     [key: string]: KtxJsonValue | undefined;

package/dist/local-adapters.d.ts

@@ -1,14 +1,22 @@
 import { type DefaultLocalIngestAdaptersOptions } from './context/ingest/local-adapters.js';
+import type { HistoricSqlDialect, HistoricSqlReader } from './context/ingest/adapters/historic-sql/types.js';
 import type { SourceAdapter } from './context/ingest/types.js';
 import type { KtxLocalProject } from './context/project/project.js';
 import type { SqlAnalysisPort } from './context/sql-analysis/ports.js';
-import { type ManagedPythonCoreDaemonOptions } from './managed-python-http.js';
+import { type ManagedPythonDaemonHttpOptions } from './managed-python-http.js';
 import type { KtxOperationalLogger } from './io/logger.js';
 export interface KtxCliLocalIngestAdaptersOptions extends DefaultLocalIngestAdaptersOptions {
     historicSqlConnectionId?: string;
     sqlAnalysis?: SqlAnalysisPort;
     sqlAnalysisUrl?: string;
-    managedDaemon?: ManagedPythonCoreDaemonOptions;
+    managedDaemon?: ManagedPythonDaemonHttpOptions;
     logger?: KtxOperationalLogger;
 }
+export interface KtxCliHistoricSqlRuntime {
+    dialect: HistoricSqlDialect;
+    sqlAnalysis: SqlAnalysisPort;
+    reader: HistoricSqlReader;
+    queryClient: unknown;
+}
+export declare function createKtxCliHistoricSqlRuntime(project: KtxLocalProject, connectionId: string, options?: KtxCliLocalIngestAdaptersOptions): KtxCliHistoricSqlRuntime | undefined;
 export declare function createKtxCliLocalIngestAdapters(project: KtxLocalProject, options?: KtxCliLocalIngestAdaptersOptions): SourceAdapter[];

package/dist/local-adapters.js

@@ -12,7 +12,7 @@ import { isKtxSqliteConnectionConfig } from './connectors/sqlite/connector.js';
 import { createSqlServerLiveDatabaseIntrospection } from './connectors/sqlserver/live-database-introspection.js';
 import { isKtxSqlServerConnectionConfig } from './connectors/sqlserver/connector.js';
 import { BigQueryHistoricSqlQueryHistoryReader } from './context/ingest/adapters/historic-sql/bigquery-query-history-reader.js';
-import { queryHistoryDialectForConnection } from './context/ingest/adapters/historic-sql/connection-dialect.js';
+import { historicSqlDialectForConnectionDriver } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { createDaemonLiveDatabaseIntrospection } from './context/ingest/adapters/live-database/daemon-introspection.js';
 import { createDefaultLocalIngestAdapters } from './context/ingest/local-adapters.js';
 import { LiveDatabaseSourceAdapter } from './context/ingest/adapters/live-database/live-database.adapter.js';
@@ -224,7 +224,12 @@ function historicSqlOptionsForLocalRun(project, options) {
         return undefined;
     }
     const connection = project.config.connections[connectionId];
-    const dialect = queryHistoryDialectForConnection(connection);
+    // historicSqlConnectionId is only set when query history was explicitly
+    // requested for this run (e.g. `--query-history`), so resolve the dialect from
+    // driver capability rather than the persisted context.queryHistory.enabled
+    // flag — otherwise the adapter is missing and findAdapter('historic-sql')
+    // throws even though the run asked for it.
+    const dialect = historicSqlDialectForConnectionDriver(connection);
     if (!dialect) {
         return undefined;
     }
@@ -234,6 +239,7 @@ function historicSqlOptionsForLocalRun(project, options) {
     if (dialect === 'postgres') {
         return {
             ...base,
+            dialect,
             reader: new PostgresPgssReader(),
             queryClient: createEphemeralPostgresHistoricSqlClient(project, connectionId),
         };
@@ -245,6 +251,7 @@ function historicSqlOptionsForLocalRun(project, options) {
         }
         return {
             ...base,
+            dialect,
             reader: new BigQueryHistoricSqlQueryHistoryReader({
                 projectId: bigQueryProjectId(connection, process.env),
                 region: bigQueryRegion(connection),
@@ -254,6 +261,7 @@ function historicSqlOptionsForLocalRun(project, options) {
     }
     return {
         ...base,
+        dialect,
         reader: new SnowflakeHistoricSqlQueryHistoryReader(),
         queryClient: {
             async executeQuery(query) {
@@ -264,8 +272,16 @@ function historicSqlOptionsForLocalRun(project, options) {
         },
     };
 }
+export function createKtxCliHistoricSqlRuntime(project, connectionId, options = {}) {
+    return historicSqlOptionsForLocalRun(project, {
+        ...options,
+        historicSqlConnectionId: connectionId,
+    });
+}
 export function createKtxCliLocalIngestAdapters(project, options = {}) {
-    const historicSql = historicSqlOptionsForLocalRun(project, options);
+    const historicSql = options.historicSqlConnectionId
+        ? createKtxCliHistoricSqlRuntime(project, options.historicSqlConnectionId, options)
+        : undefined;
     const base = createDefaultLocalIngestAdapters(project, {
         ...options,
         databaseIntrospection: ktxCliDaemonDatabaseIntrospectionOptions(options),

package/dist/next-steps.js

@@ -53,8 +53,7 @@ export function formatSetupNextStepLines(state, indent = '  ') {
     }
     if (!state.contextReady) {
         return [
-            `${indent}Build KTX context next.`,
-            `${indent}Run ingest to build database schema context before context-source ingest.`,
+            `${indent}Setup is complete. The only step left is to build context for your agents.`,
             ...commandLines(KTX_CONTEXT_BUILD_COMMANDS, indent),
         ];
     }

package/dist/progress-port-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { KtxProgressPort } from './context/scan/types.js';
+import type { KtxIngestProgressUpdate } from './ingest.js';
+export interface AggregateProgressState {
+    progress: number;
+}
+export declare function createAggregateProgressPort(onProgress: (update: KtxIngestProgressUpdate) => void, state?: AggregateProgressState, start?: number, weight?: number): KtxProgressPort;

package/dist/progress-port-adapter.js

@@ -0,0 +1,18 @@
+export function createAggregateProgressPort(onProgress, state = { progress: 0 }, start = 0, weight = 1) {
+    return {
+        async update(value, message, options) {
+            const absoluteValue = start + Math.max(0, Math.min(1, value)) * weight;
+            state.progress = Math.max(state.progress, Math.min(1, absoluteValue));
+            if (!message)
+                return;
+            onProgress({
+                percent: Math.max(0, Math.min(100, Math.round(state.progress * 100))),
+                message,
+                ...(options?.transient !== undefined ? { transient: options.transient } : {}),
+            });
+        },
+        startPhase(phaseWeight) {
+            return createAggregateProgressPort(onProgress, state, state.progress, weight * phaseWeight);
+        },
+    };
+}

package/dist/public-ingest-copy.js

@@ -11,7 +11,7 @@ const DATABASE_INGEST_REPLACEMENTS = [
         'Database enrichment failed after schema context completed',
     ],
     [/\bstructural scan\b/gi, 'schema context'],
-    [/\benriched scan\b/gi, 'deep database ingest'],
+    [/\benriched scan\b/gi, 'database ingest'],
     [/\bscan results\b/gi, 'database context'],
 ];
 export function publicDatabaseIngestMessage(message) {