@kaelio/ktx 0.11.0 → 0.13.0

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

@@ -89,7 +89,23 @@ function assertInitIsolation(message, allowedToolIds, expectedMcpServerNames) {
 function expectedMcpServerNames(tools) {
     return tools && Object.keys(tools).length > 0 ? new Set([KTX_MCP_SERVER_NAME]) : new Set();
 }
-const CLAUDE_RATE_LIMIT_ERROR_MARKERS = /\b429\b|rate limit|too many requests|quota exceeded|overloaded|max_retries/i;
+// "session limit" is the Claude Code subscription cap ("You've hit your session
+// limit · resets …"); the rest are transient 429-style throttling. All mean
+// Claude Code authenticated successfully, so they must not be read as auth
+// failures by the governor classifier or the auth probe.
+const CLAUDE_RATE_LIMIT_ERROR_MARKERS = /\b429\b|rate limit|session limit|usage limit|too many requests|quota exceeded|overloaded|max_retries/i;
+// The subscription cap is its own case: re-authenticating and retrying both fail
+// until reset, so it gets a distinct message from transient rate limiting.
+const CLAUDE_SESSION_LIMIT_MARKERS = /session limit|usage limit/i;
+function describeClaudeProbeFailure(message) {
+    if (CLAUDE_SESSION_LIMIT_MARKERS.test(message)) {
+        return `Claude Code session limit reached. Wait for the reset shown, then rerun setup or the command. Details: ${message}`;
+    }
+    if (CLAUDE_RATE_LIMIT_ERROR_MARKERS.test(message)) {
+        return `Claude Code is rate limited. Retry shortly, then rerun setup or the command. Details: ${message}`;
+    }
+    return `Claude Code authentication is not usable. Authenticate Claude Code locally with the Claude Code CLI, then rerun setup or the command. ${message}`;
+}
 function normalizeClaudeResetAtMs(value) {
     if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
         return Math.round(value < 10_000_000_000 ? value * 1_000 : value);
@@ -176,7 +192,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',
@@ -402,7 +418,7 @@ export async function runClaudeCodeAuthProbe(input) {
         const message = error instanceof Error ? error.message : String(error);
         return {
             ok: false,
-            message: `Claude Code authentication is not usable. Authenticate Claude Code locally with the Claude Code CLI, then rerun setup or the command. ${message}`,
+            message: describeClaudeProbeFailure(message),
         };
     }
 }

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

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { emitTelemetryEvent, mcpTelemetrySampleRate, reportException, shouldEmitMcpTelemetry, } from '../../telemetry/index.js';
 import { collectTelemetryRedactionSecrets } from '../../telemetry/redaction-secrets.js';
-import { scrubErrorClass } from '../../telemetry/scrubber.js';
+import { formatErrorDetail, scrubErrorClass } from '../../telemetry/scrubber.js';
 const connectionIdSchema = z.string().min(1);
 const unknownRecordSchema = z.record(z.string(), z.unknown());
 const tableRefSchema = z.object({
@@ -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. A "_ktx_federated" entry (when present) queries all its member databases together; use its id for cross-database joins.',
+    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({});
@@ -160,6 +160,8 @@ const connectionListOutputSchema = z.object({
         id: z.string(),
         name: z.string(),
         connectionType: z.string(),
+        members: z.array(z.string()).optional(),
+        hint: z.string().optional(),
     })),
 });
 const wikiSearchOutputSchema = z.object({
@@ -442,6 +444,25 @@ function clientTelemetryFields(getClientInfo) {
         ...(client?.version ? { mcpClientVersion: client.version } : {}),
     };
 }
+// Tools registered via registerParsedTool catch their own errors and return an
+// isError result, so the telemetry layer never sees the thrown Error. Recover
+// the failure message from the result's text content (the same string the agent
+// reads) so the outcome event is self-diagnosing.
+function mcpErrorResultDetail(result) {
+    if (typeof result !== 'object' || result === null || !('content' in result)) {
+        return undefined;
+    }
+    const content = result.content;
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const text = content
+        .map((block) => typeof block === 'object' && block !== null && typeof block.text === 'string'
+        ? block.text
+        : '')
+        .join('\n');
+    return formatErrorDetail(text);
+}
 function instrumentMcpServer(server, telemetry) {
     return {
         registerTool(name, config, handler) {
@@ -451,6 +472,7 @@ function instrumentMcpServer(server, telemetry) {
                     const result = await handler(input, context);
                     if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
                         const isError = typeof result === 'object' && result !== null && 'isError' in result && result.isError === true;
+                        const errorDetail = isError ? mcpErrorResultDetail(result) : undefined;
                         await emitTelemetryEvent({
                             name: 'mcp_request_completed',
                             projectDir: telemetry.projectDir,
@@ -460,6 +482,7 @@ function instrumentMcpServer(server, telemetry) {
                                 outcome: isError ? 'error' : 'ok',
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
+                                ...(errorDetail ? { errorDetail } : {}),
                                 ...clientTelemetryFields(telemetry.getClientInfo),
                             },
                         });
@@ -483,6 +506,7 @@ function instrumentMcpServer(server, telemetry) {
                     }
                     if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
                         const errorClass = scrubErrorClass(error);
+                        const errorDetail = formatErrorDetail(error);
                         await emitTelemetryEvent({
                             name: 'mcp_request_completed',
                             projectDir: telemetry.projectDir,
@@ -491,6 +515,7 @@ function instrumentMcpServer(server, telemetry) {
                                 toolName: name,
                                 outcome: 'error',
                                 ...(errorClass ? { errorClass } : {}),
+                                ...(errorDetail ? { errorDetail } : {}),
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
                                 ...clientTelemetryFields(telemetry.getClientInfo),
@@ -641,7 +666,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,110 +1,87 @@
-import { localConnectionInfoFromConfig } from '../../context/connections/local-warehouse-descriptor.js';
+import { KtxExpectedError, KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
+import { executeProjectReadOnlySql } from '../../context/connections/project-sql-executor.js';
+import { FEDERATED_CONNECTION_ID, federatedConnectionListing } from '../../context/connections/federation.js';
+import { resolveConfiguredConnection } from '../../context/connections/resolve-connection.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);
-    const connection = project.config.connections[connectionId];
-    if (!connection) {
-        throw new Error(`Connection "${connectionId}" is not configured in ktx.yaml`);
-    }
     if (!options.sqlAnalysis) {
         throw new Error('sql_execution requires parser-backed SQL validation.');
     }
-    const validation = await options.sqlAnalysis.validateReadOnly(input.sql, sqlAnalysisDialectForDriver(connection.driver));
-    if (!validation.ok) {
-        throw new Error(validation.error ?? 'SQL is not read-only.');
-    }
     const createConnector = options.localScan?.createConnector;
     if (!createConnector) {
         throw new Error('sql_execution requires a local scan connector factory.');
     }
-    let connector = null;
-    try {
-        connector = await createConnector(connectionId);
-        if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
-            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 isFederated = input.connectionId === FEDERATED_CONNECTION_ID;
+    const connectionId = isFederated ? input.connectionId : assertSafeConnectionId(input.connectionId);
+    const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, connectionId);
+    const dialect = sqlAnalysisDialectForDriver(isFederated ? 'duckdb' : connection.driver);
+    const validation = await options.sqlAnalysis.validateReadOnly(input.sql, dialect);
+    if (!validation.ok) {
+        // A read-only guard rejecting the agent's SQL is an expected outcome, not a
+        // ktx fault: classify it so reportException keeps it out of Error Tracking.
+        throw new KtxQueryError(validation.error ?? 'SQL is not read-only.');
+    }
+    await onProgress?.({ progress: 0.3, message: 'Executing' });
+    const result = await executeProjectReadOnlySql({
+        project,
+        input: {
             connectionId,
+            projectDir: project.projectDir,
+            connection,
             sql: input.sql,
             maxRows: input.maxRows,
-        }, { runId: 'mcp-sql-execution' });
-        const response = {
-            headers: result.headers,
-            ...(result.headerTypes ? { headerTypes: result.headerTypes } : {}),
-            rows: result.rows,
-            rowCount: result.rowCount ?? result.rows.length,
-        };
-        await onProgress?.({ progress: 1, message: `Fetched ${response.rowCount} rows` });
-        return response;
-    }
-    finally {
-        await cleanupConnector(connector);
-    }
+        },
+        createConnector,
+        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) || error instanceof KtxExpectedError) {
+            throw error;
+        }
+        throw new KtxQueryError(error instanceof Error ? error.message : String(error), { cause: error });
+    });
+    const response = {
+        headers: result.headers,
+        ...(result.headerTypes ? { headerTypes: result.headerTypes } : {}),
+        rows: result.rows,
+        rowCount: result.rowCount ?? result.rows.length,
+    };
+    await onProgress?.({ progress: 1, message: `Fetched ${response.rowCount} rows` });
+    return response;
 }
 export function createLocalProjectMcpContextPorts(project, options) {
     const embeddingService = options.embeddingService;
     const ports = {
         connections: {
             async list() {
-                return Object.entries(project.config.connections)
+                const configured = Object.entries(project.config.connections)
                     .map(([id, config]) => localConnectionInfoFromConfig(id, config))
                     .filter((connection) => connection !== null)
                     .sort((a, b) => a.id.localeCompare(b.id));
+                const federated = federatedConnectionListing(project.config.connections, project.projectDir);
+                if (federated) {
+                    configured.push({
+                        id: federated.id,
+                        name: federated.id,
+                        connectionType: 'DUCKDB',
+                        members: federated.members,
+                        hint: federated.hint,
+                    });
+                }
+                return configured;
             },
         },
         knowledge: {
@@ -148,14 +125,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/mcp/types.d.ts

@@ -68,6 +68,8 @@ interface KtxConnectionSummary {
     id: string;
     name: string;
     connectionType: string;
+    members?: string[];
+    hint?: string;
 }
 interface KtxConnectionsMcpPort {
     list(): Promise<KtxConnectionSummary[]>;

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>;