@kaelio/ktx 0.11.0 → 0.12.0

package/dist/context/ingest/stages/validate-wu-sources.js

@@ -1,13 +1,118 @@
+import { findMissingJoinTargets, formatMissingJoinTarget } from '../../../context/sl/semantic-layer.service.js';
+export function formatInvalidWuSources(invalid) {
+    return invalid.map((entry) => `${entry.source} (${entry.errors.join('; ')})`).join(', ');
+}
+function uniqueTouchedSources(sources) {
+    const seen = new Set();
+    const unique = [];
+    for (const source of sources) {
+        const key = `${source.connectionId}:${source.sourceName}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(source);
+    }
+    return unique.sort((left, right) => {
+        const byConnection = left.connectionId.localeCompare(right.connectionId);
+        return byConnection === 0 ? left.sourceName.localeCompare(right.sourceName) : byConnection;
+    });
+}
+/**
+ * Expand the touched set with direct join neighbors that exist: targets the
+ * touched sources join to, and existing sources that join to a touched one.
+ * Missing targets are not added here — they are reported as join-target
+ * errors on the source that declares them, so the failure names the file
+ * that must change instead of the phantom neighbor.
+ */
+function expandWithExistingJoinNeighbors(touched, sourcesByConnection) {
+    const expanded = [...touched];
+    const touchedByConnection = new Map();
+    for (const source of touched) {
+        const bucket = touchedByConnection.get(source.connectionId) ?? new Set();
+        bucket.add(source.sourceName);
+        touchedByConnection.set(source.connectionId, bucket);
+    }
+    for (const [connectionId, sources] of sourcesByConnection) {
+        const touchedNames = touchedByConnection.get(connectionId);
+        if (!touchedNames || touchedNames.size === 0) {
+            continue;
+        }
+        const existingNames = new Set(sources.map((source) => source.name));
+        for (const source of sources) {
+            if (touchedNames.has(source.name)) {
+                for (const join of source.joins ?? []) {
+                    if (existingNames.has(join.to)) {
+                        expanded.push({ connectionId, sourceName: join.to });
+                    }
+                }
+            }
+            if ((source.joins ?? []).some((join) => touchedNames.has(join.to))) {
+                expanded.push({ connectionId, sourceName: source.name });
+            }
+        }
+    }
+    return uniqueTouchedSources(expanded);
+}
+/**
+ * Join-target errors attributable to this change set: every join declared by
+ * a touched source must resolve, and no source may be left joining to a name
+ * this change set removed. Pre-existing dangling joins on untouched sources
+ * are out of scope — they must not block unrelated work. Resolution is the
+ * Python engine's: exact source-name match within the connection.
+ */
+function findJoinTargetErrors(touched, sourcesByConnection) {
+    const errorsBySource = new Map();
+    const touchedByConnection = new Map();
+    for (const source of touched) {
+        const bucket = touchedByConnection.get(source.connectionId) ?? new Set();
+        bucket.add(source.sourceName);
+        touchedByConnection.set(source.connectionId, bucket);
+    }
+    for (const [connectionId, sources] of sourcesByConnection) {
+        const touchedNames = touchedByConnection.get(connectionId);
+        if (!touchedNames || touchedNames.size === 0) {
+            continue;
+        }
+        const existingNames = sources.map((source) => source.name);
+        for (const source of sources) {
+            const sourceIsTouched = touchedNames.has(source.name);
+            const candidateJoins = sourceIsTouched
+                ? source.joins
+                : (source.joins ?? []).filter((join) => touchedNames.has(join.to));
+            const missing = findMissingJoinTargets(candidateJoins, existingNames);
+            if (missing.length === 0) {
+                continue;
+            }
+            const key = `${connectionId}:${source.name}`;
+            const messages = missing.map(formatMissingJoinTarget);
+            errorsBySource.set(key, [...(errorsBySource.get(key) ?? []), ...messages]);
+        }
+    }
+    return errorsBySource;
+}
 export async function validateWuTouchedSources(deps, touched) {
+    if (touched.length === 0) {
+        return { validSources: [], invalidSources: [] };
+    }
+    const sourcesByConnection = new Map();
+    for (const connectionId of new Set(touched.map((source) => source.connectionId))) {
+        const { sources } = await deps.semanticLayerService.loadAllSources(connectionId);
+        sourcesByConnection.set(connectionId, sources);
+    }
+    const expanded = expandWithExistingJoinNeighbors(touched, sourcesByConnection);
+    const joinTargetErrors = findJoinTargetErrors(touched, sourcesByConnection);
     const valid = [];
     const invalid = [];
-    for (const source of touched) {
+    for (const source of expanded) {
+        const key = `${source.connectionId}:${source.sourceName}`;
         const result = await deps.slValidator.validateSingleSource(deps, source.connectionId, source.sourceName);
-        if (result.errors.length === 0) {
-            valid.push(`${source.connectionId}:${source.sourceName}`);
+        const errors = [...result.errors, ...(joinTargetErrors.get(key) ?? [])];
+        if (errors.length === 0) {
+            valid.push(key);
         }
         else {
-            invalid.push(`${source.connectionId}:${source.sourceName}`);
+            invalid.push({ source: key, errors });
         }
     }
     return { validSources: valid, invalidSources: invalid };

package/dist/context/ingest/tools/warehouse-verification/create-warehouse-verification-tools.d.ts

@@ -1,8 +1,10 @@
 import type { KtxFileStorePort } from '../../../core/file-store.js';
 import type { SlConnectionCatalogPort } from '../../../sl/ports.js';
+import type { SqlAnalysisPort } from '../../../sql-analysis/ports.js';
 import type { BaseTool } from '../../../tools/base-tool.js';
 export declare function createWarehouseVerificationTools(deps: {
     connections: SlConnectionCatalogPort;
+    sqlAnalysis?: SqlAnalysisPort;
     fallbackFileStore: KtxFileStorePort;
     wikiSearchTool: BaseTool;
     slDiscoverTool: BaseTool;

package/dist/context/ingest/tools/warehouse-verification/create-warehouse-verification-tools.js

@@ -8,7 +8,7 @@ export function createWarehouseVerificationTools(deps) {
     });
     return [
         new EntityDetailsTool(catalogFactory),
-        new SqlExecutionTool(deps.connections),
+        new SqlExecutionTool(deps.connections, deps.sqlAnalysis),
         new DiscoverDataTool({
             wikiSearchTool: deps.wikiSearchTool,
             slDiscoverTool: deps.slDiscoverTool,

package/dist/context/ingest/tools/warehouse-verification/discover-data.tool.js

@@ -47,7 +47,7 @@ export class DiscoverDataTool extends BaseTool {
             };
         }
         if (input.sourceName) {
-            const sl = await this.deps.slDiscoverTool.call({ sourceName: input.sourceName, connectionId: input.connectionId }, context);
+            const sl = (await this.deps.slDiscoverTool.call({ sourceName: input.sourceName, connectionId: input.connectionId }, context));
             return { markdown: sl.markdown, structured: { wiki: null, sl: sl.structured, raw: null } };
         }
         const query = input.query?.trim() || '';
@@ -57,13 +57,13 @@ export class DiscoverDataTool extends BaseTool {
         let sl = null;
         let raw = null;
         if (query) {
-            const wikiResult = await this.deps.wikiSearchTool.call({ query, limit }, context);
+            const wikiResult = (await this.deps.wikiSearchTool.call({ query, limit }, context));
             if (totalFound(wikiResult.structured) > 0) {
                 parts.push('## Wiki Pages', '> use `wiki_read(blockKey)` for full content', wikiResult.markdown, '');
                 wiki = wikiResult.structured;
             }
         }
-        const slResult = await this.deps.slDiscoverTool.call({ query: query || undefined, connectionId: input.connectionId }, context);
+        const slResult = (await this.deps.slDiscoverTool.call({ query: query || undefined, connectionId: input.connectionId }, context));
         if (totalSources(slResult.structured) > 0) {
             parts.push('## Semantic Layer Sources', '> use `sl_read_source(sourceName)` for the YAML, or `entity_details` for warehouse-shape details', slResult.markdown, '');
             sl = slResult.structured;

package/dist/context/ingest/tools/warehouse-verification/sql-execution.tool.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { SlConnectionCatalogPort } from '../../../../context/sl/ports.js';
+import type { SqlAnalysisPort } from '../../../../context/sql-analysis/ports.js';
 import { BaseTool, type ToolContext, type ToolOutput } from '../../../../context/tools/base-tool.js';
 declare const sqlExecutionInputSchema: z.ZodObject<{
     connectionId: z.ZodString;
@@ -18,8 +19,9 @@ export interface SqlExecutionStructured {
 }
 export declare class SqlExecutionTool extends BaseTool<typeof sqlExecutionInputSchema> {
     private readonly connections;
+    private readonly sqlAnalysis?;
     readonly name = "sql_execution";
-    constructor(connections: SlConnectionCatalogPort);
+    constructor(connections: SlConnectionCatalogPort, sqlAnalysis?: SqlAnalysisPort | undefined);
     get description(): string;
     get inputSchema(): z.ZodObject<{
         connectionId: z.ZodString;

package/dist/context/ingest/tools/warehouse-verification/sql-execution.tool.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { assertReadOnlySql, limitSqlForExecution } from '../../../../context/connections/read-only-sql.js';
+import { sqlAnalysisDialectForDriver } from '../../../../context/sql-analysis/dialect.js';
 import { BaseTool } from '../../../../context/tools/base-tool.js';
 const sqlExecutionInputSchema = z.object({
     connectionId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),
@@ -23,10 +24,12 @@ function markdownTable(headers, rows, totalRows) {
 }
 export class SqlExecutionTool extends BaseTool {
     connections;
+    sqlAnalysis;
     name = 'sql_execution';
-    constructor(connections) {
+    constructor(connections, sqlAnalysis) {
         super();
         this.connections = connections;
+        this.sqlAnalysis = sqlAnalysis;
     }
     get description() {
         return 'Run a single read-only SELECT or WITH probe against an allowed warehouse connection and return a capped markdown table or the warehouse error.';
@@ -50,9 +53,20 @@ export class SqlExecutionTool extends BaseTool {
                 },
             };
         }
+        if (!this.sqlAnalysis) {
+            throw new Error('sql_execution requires parser-backed SQL validation.');
+        }
         let sql;
         let wrappedSql;
         try {
+            const connection = await this.connections.getConnectionById(input.connectionId);
+            if (!connection) {
+                throw new Error(`Connection not found: ${input.connectionId}`);
+            }
+            const validation = await this.sqlAnalysis.validateReadOnly(input.sql, sqlAnalysisDialectForDriver(connection.connectionType));
+            if (!validation.ok) {
+                throw new Error(validation.error ?? 'SQL is not read-only.');
+            }
             sql = assertReadOnlySql(input.sql);
             wrappedSql = limitSqlForExecution(sql, input.rowLimit);
         }

package/dist/context/llm/ai-sdk-runtime.js

@@ -189,7 +189,7 @@ export class AiSdkKtxLlmRuntime {
         const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), input.abortSignal, () => generateText(request));
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: toLlmTokenUsage(result.totalUsage ?? result.usage) });
         if (typeof result.text !== 'string') {
-            throw new Error('KTX LLM text generation returned no text');
+            throw new Error('ktx LLM text generation returned no text');
         }
         return result.text;
     }
@@ -223,7 +223,7 @@ export class AiSdkKtxLlmRuntime {
         const result = await this.generateTextWithRateLimitRetry(modelProviderName(model), input.abortSignal, () => generateText(request));
         input.onMetrics?.({ totalMs: Date.now() - startedAt, usage: toLlmTokenUsage(result.totalUsage ?? result.usage) });
         if (result.output == null) {
-            throw new Error('KTX LLM object generation returned no output');
+            throw new Error('ktx LLM object generation returned no output');
         }
         return result.output;
     }

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

@@ -176,7 +176,7 @@ function baseOptions(input) {
             ? { behavior: 'allow', toolUseID: options.toolUseID }
             : {
                 behavior: 'deny',
-                message: `KTX claude-code runtime only permits current KTX MCP tools; denied ${toolName}.`,
+                message: `ktx claude-code runtime only permits current ktx MCP tools; denied ${toolName}.`,
                 toolUseID: options.toolUseID,
             },
         permissionMode: 'dontAsk',

package/dist/context/llm/local-config.js

@@ -143,7 +143,7 @@ export function resolveLocalKtxEmbeddingConfig(config, env) {
             batchSize: config.batchSize,
         };
     }
-    throw new Error(`Unsupported KTX embedding backend: ${String(config.backend)}`);
+    throw new Error(`Unsupported ktx embedding backend: ${String(config.backend)}`);
 }
 /** @internal */
 export function createLocalKtxEmbeddingProviderFromConfig(config, deps = {}) {

package/dist/context/llm/runtime-tools.js

@@ -21,7 +21,7 @@ export function normalizeKtxRuntimeToolOutput(value) {
 }
 function assertObjectSchema(name, schema) {
     if (!(schema instanceof z.ZodObject)) {
-        throw new Error(`KTX runtime tool "${name}" must use z.object input schema for claude-code`);
+        throw new Error(`ktx runtime tool "${name}" must use z.object input schema for claude-code`);
     }
 }
 export function createAiSdkToolSet(tools = {}) {
@@ -57,7 +57,7 @@ export function createRuntimeToolDescriptorFromAiTool(name, aiSdkTool) {
         inputSchema: aiSdkTool.inputSchema,
         execute: async (input) => {
             if (typeof aiSdkTool.execute !== 'function') {
-                throw new Error(`KTX runtime tool "${name}" has no execute function`);
+                throw new Error(`ktx runtime tool "${name}" has no execute function`);
             }
             return normalizeKtxRuntimeToolOutput(await aiSdkTool.execute(input, { toolCallId: `runtime-${name}` }));
         },

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

@@ -24,16 +24,16 @@ const toolAnnotations = {
     memory_ingest_status: { title: 'Memory Ingest Status', readOnlyHint: true, openWorldHint: false },
 };
 const toolDescriptions = {
-    connection_list: 'List configured read-only data connections available to this KTX project. Use this before connection-scoped tools when the project may have multiple warehouses.',
-    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" }).',
+    connection_list: 'List configured read-only data connections available to this ktx project. Use this before connection-scoped tools when the project may have multiple warehouses.',
+    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: { 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 headers, rows, and total row count, plus correctness notes (e.g. compile-only or fan-out) when relevant. The generated SQL and full query plan are omitted by default; request them with include: ["sql"] and/or include: ["plan"]. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }], include: ["sql"] }).',
-    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." }).',
+    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" }).',
 };
 const connectionListSchema = z.object({});
@@ -641,7 +641,7 @@ export function registerKtxContextTools(deps) {
             const ingestInput = {
                 userId: userContext.userId,
                 chatId: `mcp-${randomUUID()}`,
-                userMessage: 'Ingest external knowledge into KTX memory.',
+                userMessage: 'Ingest external knowledge into ktx memory.',
                 assistantMessage: input.content,
                 connectionId: input.connectionId,
                 sourceType: 'external_ingest',

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

@@ -1,58 +1,18 @@
+import { KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
 import { localConnectionInfoFromConfig } from '../../context/connections/local-warehouse-descriptor.js';
 import { createKtxEntityDetailsService } from '../../context/scan/entity-details.js';
 import { createKtxDiscoverDataService } from '../../context/search/discover.js';
+import { sqlAnalysisDialectForDriver } from '../../context/sql-analysis/dialect.js';
 import { compileLocalSlQuery } from '../../context/sl/local-query.js';
 import { createKtxDictionarySearchService } from '../../context/sl/dictionary-search.js';
+import { readLocalSlSource } from '../../context/sl/local-sl.js';
+import { assertSafeConnectionId } from '../../context/sl/source-files.js';
 import { readLocalKnowledgePage, searchLocalKnowledgePages } from '../wiki/local-knowledge.js';
-function dialectForDriver(driver) {
-    const normalized = (driver ?? 'postgres').toUpperCase();
-    const map = {
-        POSTGRES: 'postgres',
-        BIGQUERY: 'bigquery',
-        SNOWFLAKE: 'snowflake',
-        MYSQL: 'mysql',
-        SQLSERVER: 'tsql',
-        SQLITE: 'sqlite',
-        DUCKDB: 'duckdb',
-        CLICKHOUSE: 'clickhouse',
-        DATABRICKS: 'databricks',
-    };
-    return map[normalized] ?? 'postgres';
-}
-function sqlAnalysisDialectForDriver(driver) {
-    return dialectForDriver(driver);
-}
-function assertSafePathToken(kind, value) {
-    if (value.trim().length === 0 ||
-        value.includes('..') ||
-        value.includes('\\') ||
-        value.startsWith('/') ||
-        value.startsWith('.') ||
-        value.includes('//')) {
-        throw new Error(`Unsafe ${kind}: ${value}`);
-    }
-    return value;
-}
-function assertSafeConnectionId(connectionId) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
-        throw new Error(`Unsafe connection id: ${connectionId}`);
-    }
-    return assertSafePathToken('connection id', connectionId);
-}
-function assertSafeSourceName(sourceName) {
-    if (!/^[a-z0-9][a-z0-9_]*$/.test(sourceName)) {
-        throw new Error(`Unsafe semantic-layer source name: ${sourceName}`);
-    }
-    return assertSafePathToken('semantic-layer source name', sourceName);
-}
 async function cleanupConnector(connector) {
     if (connector?.cleanup) {
         await connector.cleanup();
     }
 }
-function slPath(connectionId, sourceName) {
-    return `semantic-layer/${assertSafeConnectionId(connectionId)}/${assertSafeSourceName(sourceName)}.yaml`;
-}
 async function executeValidatedReadOnlySql(project, options, input, onProgress) {
     await onProgress?.({ progress: 0, message: 'Validating SQL' });
     const connectionId = assertSafeConnectionId(input.connectionId);
@@ -78,11 +38,23 @@ async function executeValidatedReadOnlySql(project, options, input, onProgress)
             throw new Error(`Connection "${connectionId}" does not support read-only SQL execution.`);
         }
         await onProgress?.({ progress: 0.3, message: 'Executing' });
-        const result = await connector.executeReadOnly({
+        const result = await connector
+            .executeReadOnly({
             connectionId,
             sql: input.sql,
             maxRows: input.maxRows,
-        }, { runId: 'mcp-sql-execution' });
+        }, { runId: 'mcp-sql-execution' })
+            .catch((error) => {
+            // A warehouse/driver rejection (e.g. the agent's SQL failed to compile)
+            // is a surfaced operational outcome, not a ktx fault: mark it expected
+            // while preserving the warehouse's own diagnostics. A native JS error
+            // (TypeError, etc.) signals a bug in connector code — let it propagate
+            // unchanged so Error Tracking still sees it.
+            if (isNativeProgrammingFault(error)) {
+                throw error;
+            }
+            throw new KtxQueryError(error instanceof Error ? error.message : String(error), { cause: error });
+        });
         const response = {
             headers: result.headers,
             ...(result.headerTypes ? { headerTypes: result.headerTypes } : {}),
@@ -148,14 +120,11 @@ export function createLocalProjectMcpContextPorts(project, options) {
         },
         semanticLayer: {
             async readSource(input) {
-                const path = slPath(input.connectionId, input.sourceName);
-                try {
-                    const result = await project.fileStore.readFile(path);
-                    return { sourceName: input.sourceName, yaml: result.content };
-                }
-                catch {
-                    return null;
-                }
+                const source = await readLocalSlSource(project, {
+                    connectionId: input.connectionId,
+                    sourceName: input.sourceName,
+                });
+                return source ? { sourceName: source.name, yaml: source.yaml } : null;
             },
             async query(input, executionOptions) {
                 if (!options.semanticLayerCompute) {

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

@@ -31,7 +31,7 @@ import { MemoryAgentService } from './memory-agent.service.js';
 import { MemoryIngestService } from './memory-runs.js';
 const promptsDir = fileURLToPath(new URL('../../prompts', import.meta.url));
 const skillsDir = fileURLToPath(new URL('../../skills', import.meta.url));
-const LOCAL_AUTHOR = { name: 'KTX Local', email: 'local@ktx.local' };
+const LOCAL_AUTHOR = { name: 'ktx Local', email: 'local@ktx.local' };
 const LOCAL_SHAPE_WARNING = 'Local memory ingest validates semantic-layer YAML shape only.';
 export function createLocalProjectMemoryIngest(project, options = {}) {
     const logger = options.logger ?? noopLogger;
@@ -307,6 +307,9 @@ class LocalShapeOnlySlValidator {
     async validateSingleSource(deps, connectionId, sourceName) {
         try {
             const file = await deps.semanticLayerService.readSourceFile(connectionId, sourceName);
+            if (!file) {
+                return { errors: [`${sourceName}: no standalone or overlay file found`], warnings: [] };
+            }
             const parsed = YAML.parse(file.content);
             const isOverlay = parsed.table == null && parsed.sql == null;
             const result = (isOverlay ? sourceOverlaySchema : sourceDefinitionSchema).safeParse(parsed);

package/dist/context/memory/memory-agent.service.js

@@ -391,7 +391,7 @@ export class MemoryAgentService {
         if (session.connectionId) {
             for (const { connectionId, sourceName } of listTouchedSlSources(session.touchedSlSources)) {
                 try {
-                    const file = await this.deps.semanticLayerService.readSourceFile(connectionId, sourceName).catch(() => null);
+                    const file = await this.deps.semanticLayerService.readSourceFile(connectionId, sourceName);
                     if (file?.content) {
                         const parsed = this.parseYamlOrNull(file.content);
                         if (parsed) {

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

@@ -317,7 +317,6 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
             "postgres-hybrid": "postgres-hybrid";
         }>>;
         git: z.ZodPrefault<z.ZodObject<{
-            auto_commit: z.ZodDefault<z.ZodBoolean>;
             author: z.ZodDefault<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -418,9 +417,6 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
             default_toolset: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
-    memory: z.ZodPrefault<z.ZodObject<{
-        auto_commit: z.ZodDefault<z.ZodBoolean>;
-    }, z.core.$strict>>;
     scan: z.ZodPrefault<z.ZodObject<{
         enrichment: z.ZodPrefault<z.ZodObject<{
             mode: z.ZodDefault<z.ZodEnum<{
@@ -472,12 +468,23 @@ export interface KtxConfigIssue {
     path: string;
     message: string;
     fix?: string;
+    /**
+     * 'error' blocks the project (bad value on a recognized field); 'warning' is
+     * a condition the loader recovers from on its own (an ignored unknown key).
+     */
+    severity: 'error' | 'warning';
 }
 export interface KtxConfigValidation {
     ok: boolean;
     issues: KtxConfigIssue[];
 }
 export declare function buildDefaultKtxProjectConfig(): KtxProjectConfig;
+/**
+ * Parse and validate a ktx.yaml document. Keys this ktx version does not
+ * recognize are stripped from the returned config — never from the file, which
+ * a load must not rewrite — so a config written by a different ktx version
+ * still loads. Malformed values on recognized fields still throw.
+ */
 export declare function parseKtxProjectConfig(raw: string): KtxProjectConfig;
 export declare function validateKtxProjectConfig(raw: string): KtxConfigValidation;
 export declare function generateKtxProjectConfigJsonSchema(): Record<string, unknown>;