@kaelio/ktx 0.10.0 → 0.12.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

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

package/dist/context/project/config.js

@@ -53,7 +53,7 @@ const llmSchema = z
     models: z
         .partialRecord(z.enum(KTX_MODEL_ROLES), z.string().min(1))
         .default({})
-        .describe('Per-role model overrides keyed by KTX model role (e.g. "default", "triage"). Values are provider-specific model identifiers.'),
+        .describe('Per-role model overrides keyed by ktx model role (e.g. "default", "triage"). Values are provider-specific model identifiers.'),
     promptCaching: promptCachingSchema.optional().describe('Optional prompt-caching tunables.'),
 })
     .describe('LLM provider, per-role model overrides, and prompt-caching tunables.');
@@ -205,27 +205,26 @@ const setupSchema = z
     .describe('Setup-wizard state captured during `ktx setup`.');
 const storageGitSchema = z
     .strictObject({
-    auto_commit: z.boolean().default(true).describe('When true, KTX automatically commits state changes to the local Git-backed store.'),
     author: z
         .string()
         .min(1)
         .default('ktx <ktx@example.com>')
-        .describe('Git author identity used for auto-commits, in standard "Name <email>" form.'),
+        .describe('Git author identity used for commits, in standard "Name <email>" form.'),
 })
-    .describe('Git-backed storage commit policy.');
+    .describe('Git-backed storage author policy.');
 const storageSchema = z
     .strictObject({
     state: z
         .enum(KTX_STORAGE_STATES)
         .default('sqlite')
-        .describe('Backend for KTX state storage. "sqlite" uses .ktx/db.sqlite; "postgres" expects a configured Postgres connection.'),
+        .describe('Backend for ktx state storage. "sqlite" uses .ktx/db.sqlite; "postgres" expects a configured Postgres connection.'),
     search: z
         .enum(KTX_SEARCH_BACKENDS)
         .default('sqlite-fts5')
         .describe('Backend for search indexes. "sqlite-fts5" uses SQLite FTS5; "postgres-hybrid" uses Postgres lexical + vector hybrid search.'),
     git: storageGitSchema.prefault({}).describe('Git-backed storage commit policy.'),
 })
-    .describe('Storage backends and commit policy for KTX state and search indexes.');
+    .describe('Storage backends and commit policy for ktx state and search indexes.');
 const connectionSchema = connectionConfigSchema;
 const agentSchema = z
     .strictObject({
@@ -247,11 +246,6 @@ const agentSchema = z
         .describe('Research-agent configuration.'),
 })
     .describe('Agent feature configuration.');
-const memorySchema = z
-    .strictObject({
-    auto_commit: z.boolean().default(true).describe('When true, KTX automatically commits memory updates to the Git-backed store.'),
-})
-    .describe('Memory subsystem configuration.');
 const ktxProjectConfigSchema = z
     .strictObject({
     setup: setupSchema.optional().describe('Setup-wizard state. Written by `ktx setup`; may be omitted.'),
@@ -259,14 +253,13 @@ const ktxProjectConfigSchema = z
         .record(z.string(), connectionSchema)
         .default({})
         .describe('Map of connection ID to connector configuration. Keys are user-chosen names referenced elsewhere in the config.'),
-    storage: storageSchema.prefault({}).describe('Storage backends and commit policy for KTX state and search indexes.'),
+    storage: storageSchema.prefault({}).describe('Storage backends and commit policy for ktx state and search indexes.'),
     llm: llmSchema.prefault({}).describe('LLM provider, per-role model overrides, and prompt-caching tunables.'),
     ingest: ingestSchema.prefault({}).describe('Ingest pipeline configuration.'),
     agent: agentSchema.prefault({}).describe('Agent feature configuration.'),
-    memory: memorySchema.prefault({}).describe('Memory subsystem configuration.'),
     scan: scanSchema.prefault({}).describe('Schema-scan configuration: enrichment and relationship discovery.'),
 })
-    .describe('Configuration schema for KTX project files (ktx.yaml).');
+    .describe('Configuration schema for ktx project files (ktx.yaml).');
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -282,21 +275,53 @@ function valueAtPath(root, path) {
     }
     return cursor;
 }
-function formatIssue(issue, input) {
-    const basePath = dottedPath(issue.path);
+/**
+ * Zod reports unknown keys in two shapes: strict objects emit
+ * `unrecognized_keys` (path → container, `keys` → offenders), enum-keyed
+ * records (`llm.models`) emit one `invalid_key` per offender (path ends with
+ * the key). Normalize both so the warning report and the strip always agree.
+ */
+function unknownKeyLocations(issue) {
     if (issue.code === 'unrecognized_keys') {
-        const keys = issue.keys ?? [];
-        return keys.map((key) => {
-            const fullPath = basePath.length > 0 ? `${basePath}.${key}` : key;
-            return { path: fullPath, message: `Unsupported ${fullPath}: unknown field` };
+        return issue.keys.map((key) => ({ containerPath: issue.path, key }));
+    }
+    if (issue.code === 'invalid_key' && issue.path.length > 0) {
+        return [
+            {
+                containerPath: issue.path.slice(0, -1),
+                key: String(issue.path[issue.path.length - 1]),
+            },
+        ];
+    }
+    return [];
+}
+function formatIssue(issue, input) {
+    const unknownKeys = unknownKeyLocations(issue);
+    if (unknownKeys.length > 0) {
+        return unknownKeys.map(({ containerPath, key }) => {
+            const base = dottedPath(containerPath);
+            const fullPath = base.length > 0 ? `${base}.${key}` : key;
+            return {
+                path: fullPath,
+                message: `Unsupported ${fullPath}: unknown field (ignored)`,
+                fix: 'Unknown to this ktx version; it is ignored. Delete it from ktx.yaml when convenient.',
+                severity: 'warning',
+            };
         });
     }
+    const basePath = dottedPath(issue.path);
     const lastSegment = issue.path[issue.path.length - 1];
     if (lastSegment === 'backend' && (issue.code === 'invalid_value' || issue.code === 'invalid_type')) {
         const value = valueAtPath(input, issue.path);
-        return [{ path: basePath, message: `Unsupported ${basePath}: ${String(value)}` }];
+        return [{ path: basePath, message: `Unsupported ${basePath}: ${String(value)}`, severity: 'error' }];
     }
-    return [{ path: basePath, message: basePath.length > 0 ? `${basePath}: ${issue.message}` : issue.message }];
+    return [
+        {
+            path: basePath,
+            message: basePath.length > 0 ? `${basePath}: ${issue.message}` : issue.message,
+            severity: 'error',
+        },
+    ];
 }
 function collectIssues(error, input) {
     return error.issues.flatMap((issue) => formatIssue(issue, input));
@@ -309,16 +334,44 @@ function formatZodError(error, input) {
 export function buildDefaultKtxProjectConfig() {
     return ktxProjectConfigSchema.parse({});
 }
+function stripUnrecognizedKeys(input) {
+    const result = ktxProjectConfigSchema.safeParse(input);
+    if (result.success) {
+        return input;
+    }
+    const unknownKeys = result.error.issues.flatMap(unknownKeyLocations);
+    if (unknownKeys.length === 0) {
+        return input;
+    }
+    const value = structuredClone(input);
+    for (const { containerPath, key } of unknownKeys) {
+        const container = valueAtPath(value, containerPath);
+        if (container === null || typeof container !== 'object')
+            continue;
+        delete container[key];
+    }
+    return value;
+}
+function parseTolerant(input) {
+    const value = stripUnrecognizedKeys(input);
+    const result = ktxProjectConfigSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(formatZodError(result.error, value));
+    }
+    return result.data;
+}
+/**
+ * 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 function parseKtxProjectConfig(raw) {
     const parsed = YAML.parse(raw);
     if (!isRecord(parsed)) {
         throw new Error('ktx.yaml must contain a YAML object');
     }
-    const result = ktxProjectConfigSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new Error(formatZodError(result.error, parsed));
-    }
-    return result.data;
+    return parseTolerant(parsed);
 }
 export function validateKtxProjectConfig(raw) {
     let parsed;
@@ -327,16 +380,18 @@ export function validateKtxProjectConfig(raw) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, issues: [{ path: '', message: `ktx.yaml parse error: ${message}` }] };
+        return { ok: false, issues: [{ path: '', message: `ktx.yaml parse error: ${message}`, severity: 'error' }] };
     }
     if (!isRecord(parsed)) {
-        return { ok: false, issues: [{ path: '', message: 'ktx.yaml must contain a YAML object' }] };
+        return { ok: false, issues: [{ path: '', message: 'ktx.yaml must contain a YAML object', severity: 'error' }] };
     }
     const result = ktxProjectConfigSchema.safeParse(parsed);
     if (result.success) {
         return { ok: true, issues: [] };
     }
-    return { ok: false, issues: collectIssues(result.error, parsed) };
+    const issues = collectIssues(result.error, parsed);
+    const ok = !issues.some((issue) => issue.severity === 'error');
+    return { ok, issues };
 }
 export function generateKtxProjectConfigJsonSchema() {
     const schema = z.toJSONSchema(ktxProjectConfigSchema, {

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

@@ -84,7 +84,7 @@ const lookerConnectionSchema = z
         .min(1)
         .optional()
         .describe('Reference to Looker OAuth client secret (e.g. env:LOOKER_CLIENT_SECRET).'),
-    mappings: lookerMappingsSchema.optional().describe('Looker connection-name to KTX warehouse mappings.'),
+    mappings: lookerMappingsSchema.optional().describe('Looker connection-name to ktx warehouse mappings.'),
 })
     .describe('Looker context-source connection.');
 const lookmlConnectionSchema = z

package/dist/context/project/mappings-yaml-schema.js

@@ -12,7 +12,7 @@ export const metabaseMappingsSchema = z
     databaseMappings: z
         .record(z.string(), stringTargetSchema)
         .default({})
-        .describe('Map of Metabase database ID (positive integer string) to KTX connection ID. Use null to explicitly unmap.'),
+        .describe('Map of Metabase database ID (positive integer string) to ktx connection ID. Use null to explicitly unmap.'),
     syncEnabled: z
         .record(z.string(), z.boolean())
         .default({})
@@ -34,7 +34,7 @@ export const lookerMappingsSchema = z
     connectionMappings: z
         .record(z.string().min(1), stringTargetSchema)
         .default({})
-        .describe('Map of Looker connection name to KTX connection ID. Use null to explicitly unmap.'),
+        .describe('Map of Looker connection name to ktx connection ID. Use null to explicitly unmap.'),
 })
     .describe('Looker connection-to-warehouse mapping configuration.');
 export const lookmlMappingsSchema = z

package/dist/context/project/project.js

@@ -1,6 +1,6 @@
 import { promises as fs } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { GitService } from '../../context/core/git.service.js';
+import { classifyKtxRepoOwnership, GitService, KtxForeignGitRepositoryError } from '../../context/core/git.service.js';
 import { noopLogger } from '../../context/core/config.js';
 import { buildDefaultKtxProjectConfig, parseKtxProjectConfig, serializeKtxProjectConfig } from './config.js';
 import { LocalGitFileStore } from './local-git-file-store.js';
@@ -69,14 +69,22 @@ export async function initKtxProject(options) {
     if (!options.force && (await fileExists(configPath))) {
         throw new Error(`Project already contains ktx.yaml: ${configPath}`);
     }
+    // Must run before ktx.yaml is written: once that file exists the directory
+    // classifies as ktx-managed, so a foreign repo would be silently adopted.
+    if ((await classifyKtxRepoOwnership(projectDir)) === 'foreign') {
+        throw new KtxForeignGitRepositoryError(projectDir);
+    }
     const config = buildDefaultKtxProjectConfig();
-    const runtime = await createRuntime(projectDir, config, authorName, authorEmail, logger);
-    await writeProjectFile(projectDir, 'ktx.yaml', serializeKtxProjectConfig(config));
+    // ktx.yaml (the ownership signal) is written before git init, so an
+    // interrupted init can never leave a bare `.git` without it — residue that
+    // would classify as a foreign repo and be unrecoverable.
     await fs.mkdir(join(projectDir, '.ktx/cache'), { recursive: true });
     for (const file of TRACKED_SCAFFOLD_FILES) {
         await writeProjectFile(projectDir, file.path, file.content);
     }
-    const commit = await runtime.git.commitFiles(['ktx.yaml', ...TRACKED_SCAFFOLD_FILES.map((file) => file.path)], `Initialize KTX project: ${projectName}`, authorName, authorEmail);
+    await writeProjectFile(projectDir, 'ktx.yaml', serializeKtxProjectConfig(config));
+    const runtime = await createRuntime(projectDir, config, authorName, authorEmail, logger);
+    const commit = await runtime.git.commitFiles(['ktx.yaml', ...TRACKED_SCAFFOLD_FILES.map((file) => file.path)], `Initialize ktx project: ${projectName}`, authorName, authorEmail);
     return {
         ...runtime,
         commitHash: commit.commitHash,

package/dist/context/scan/description-generation.js

@@ -330,7 +330,7 @@ export class KtxDescriptionGenerator {
         let fallbackReason = null;
         if (!connector.sampleTable) {
             fallbackReason = 'capability_missing';
-            this.logger?.warn('KTX scan connector does not support table sampling; falling back to metadata-only prompt', {
+            this.logger?.warn('ktx scan connector does not support table sampling; falling back to metadata-only prompt', {
                 connectorId: input.connector.id,
                 table: input.table.name,
             });
@@ -440,7 +440,7 @@ export class KtxDescriptionGenerator {
         let fallbackReason = null;
         if (!input.connector.sampleTable) {
             fallbackReason = 'capability_missing';
-            this.logger?.warn('KTX scan connector does not support table sampling; falling back to metadata-only prompt', {
+            this.logger?.warn('ktx scan connector does not support table sampling; falling back to metadata-only prompt', {
                 connectorId: input.connector.id,
                 table: input.table.name,
             });
@@ -579,7 +579,7 @@ export class KtxDescriptionGenerator {
             }
         }
         if (!input.connector.sampleTable) {
-            this.logger?.warn('KTX scan connector does not support table sampling for data-source description generation', {
+            this.logger?.warn('ktx scan connector does not support table sampling for data-source description generation', {
                 connectorId: input.connector.id,
             });
             return 'No accessible tables found in database';
@@ -647,7 +647,7 @@ export class KtxDescriptionGenerator {
             let columnValues = column.sampleValues;
             if (!columnValues || columnValues.length === 0) {
                 if (!input.connector.sampleColumn) {
-                    this.logger?.warn('KTX scan connector does not support column sampling; using available metadata only', {
+                    this.logger?.warn('ktx scan connector does not support column sampling; using available metadata only', {
                         connectorId: input.connector.id,
                         table: input.table.name,
                         column: column.name,

package/dist/context/scan/local-enrichment-artifacts.js

@@ -1,5 +1,6 @@
 import YAML from 'yaml';
 import { buildLiveDatabaseManifestShards } from '../../context/ingest/adapters/live-database/manifest.js';
+import { isSlYamlPath } from '../../context/sl/source-files.js';
 import { buildKtxRelationshipArtifacts, buildKtxRelationshipDiagnostics, emptyKtxRelationshipProfileArtifact, } from './relationship-diagnostics.js';
 const LIVE_DATABASE_ADAPTER = 'live-database';
 const LOCAL_AUTHOR = 'ktx';
@@ -120,7 +121,7 @@ async function loadExistingManifestState(project, connectionId, snapshot) {
     const columnsByTable = validColumns(snapshot);
     let files;
     try {
-        files = (await project.fileStore.listFiles(schemaDir(connectionId))).files.filter((file) => file.endsWith('.yaml'));
+        files = (await project.fileStore.listFiles(schemaDir(connectionId))).files.filter(isSlYamlPath);
     }
     catch {
         return { descriptions, preservedJoins, usage };

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

@@ -63,7 +63,7 @@ function scanReportPath(connectionId, syncId) {
 }
 function assertSupportedMode(mode) {
     if (mode !== 'structural' && mode !== 'relationships' && mode !== 'enriched') {
-        throw new Error(`Unsupported KTX scan mode: ${mode}`);
+        throw new Error(`Unsupported ktx scan mode: ${mode}`);
     }
 }
 async function resolveScanConnector(options, mode) {
@@ -381,7 +381,7 @@ export async function runLocalScan(options) {
                 }
                 report.warnings.push({
                     code: 'enrichment_failed',
-                    message: `KTX scan enrichment failed after structural scan completed: ${message}`,
+                    message: `ktx scan enrichment failed after structural scan completed: ${message}`,
                     recoverable: true,
                     metadata: { mode, detectRelationships: options.detectRelationships ?? false },
                 });