@kaelio/ktx 0.11.0 → 0.13.0

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,7 @@
 import YAML from 'yaml';
 import { buildLiveDatabaseManifestShards } from '../../context/ingest/adapters/live-database/manifest.js';
+import { isSlYamlPath } from '../../context/sl/source-files.js';
+import { deriveFederatedConnection } from '../connections/federation.js';
 import { buildKtxRelationshipArtifacts, buildKtxRelationshipDiagnostics, emptyKtxRelationshipProfileArtifact, } from './relationship-diagnostics.js';
 const LIVE_DATABASE_ADAPTER = 'live-database';
 const LOCAL_AUTHOR = 'ktx';
@@ -112,7 +114,32 @@ function joinReferencesExistingColumns(join, columnsByTable) {
     }
     return true;
 }
-async function loadExistingManifestState(project, connectionId, snapshot) {
+async function federatedSiblingTargets(project, connectionId) {
+    const descriptor = deriveFederatedConnection(project.config.connections, project.projectDir);
+    if (!descriptor) {
+        return new Set();
+    }
+    const siblings = descriptor.members.filter((member) => member.connectionId !== connectionId);
+    const perSibling = await Promise.all(siblings.map((sibling) => siblingJoinTargets(project, sibling.connectionId)));
+    return new Set(perSibling.flat());
+}
+async function siblingJoinTargets(project, connectionId) {
+    const listed = await project.fileStore.listFiles(schemaDir(connectionId)).catch(() => ({ files: [] }));
+    const files = listed.files.filter(isSlYamlPath);
+    const perFile = await Promise.all(files.map(async (file) => {
+        const shard = await project.fileStore
+            .readFile(file)
+            .then(({ content }) => YAML.parse(content))
+            .catch(() => null);
+        // entry.table is buildTableRef's member-local ref (1-3 parts:
+        // table / schema.table / catalog.schema.table), never connectionId-
+        // prefixed — so prefixing with the member id yields the fully-qualified
+        // `to:` form authored in cross-DB joins.
+        return Object.values(shard?.tables ?? {}).map((entry) => `${connectionId}.${entry.table}`);
+    }));
+    return perFile.flat();
+}
+async function loadExistingManifestState(project, connectionId, snapshot, siblingTargets) {
     const descriptions = new Map();
     const preservedJoins = new Map();
     const usage = new Map();
@@ -120,7 +147,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 };
@@ -145,7 +172,7 @@ async function loadExistingManifestState(project, connectionId, snapshot) {
                 }
                 const joins = (entry.joins ?? []).filter((join) => {
                     return ((join.source === 'manual' || join.source === 'inferred') &&
-                        validTableNames.has(join.to) &&
+                        (validTableNames.has(join.to) || siblingTargets.has(join.to)) &&
                         joinReferencesExistingColumns(join, columnsByTable));
                 });
                 if (joins.length > 0) {
@@ -169,7 +196,8 @@ export async function writeLocalScanManifestShards(input) {
             manifestShardsWritten: 0,
         };
     }
-    const existing = await loadExistingManifestState(input.project, input.connectionId, input.snapshot);
+    const siblingTargets = await federatedSiblingTargets(input.project, input.connectionId);
+    const existing = await loadExistingManifestState(input.project, input.connectionId, input.snapshot, siblingTargets);
     const { shards } = buildLiveDatabaseManifestShards({
         connectionType: input.driver.toUpperCase(),
         tables: snapshotTablesToManifestData(input.snapshot, input.descriptionUpdates),
@@ -177,6 +205,7 @@ export async function writeLocalScanManifestShards(input) {
         existingDescriptions: existing.descriptions,
         existingPreservedJoins: existing.preservedJoins,
         existingUsage: existing.usage,
+        federatedSiblingTargets: siblingTargets,
         mapColumnType: (dimensionType) => dimensionType,
     });
     const manifestShards = [];

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 },
                 });

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

@@ -25,7 +25,7 @@ function parseWarning(rawWarning, path) {
         !scanWarningCodes.has(rawWarning.code) ||
         typeof rawWarning.message !== 'string' ||
         typeof rawWarning.recoverable !== 'boolean') {
-        throw new Error(`Invalid KTX schema warning artifact: ${path}`);
+        throw new Error(`Invalid ktx schema warning artifact: ${path}`);
     }
     return {
         code: rawWarning.code,
@@ -42,7 +42,7 @@ async function readWarnings(input) {
         const warningRaw = await input.project.fileStore.readFile(path);
         const parsed = JSON.parse(warningRaw.content);
         if (!isRecord(parsed) || !Array.isArray(parsed.warnings)) {
-            throw new Error(`Invalid KTX schema warnings artifact: ${path}`);
+            throw new Error(`Invalid ktx schema warnings artifact: ${path}`);
         }
         return parsed.warnings.map((warning) => parseWarning(warning, path));
     }
@@ -68,7 +68,7 @@ function parseColumn(rawColumn, path) {
             rawColumn.dimensionType !== 'string' &&
             rawColumn.dimensionType !== 'number' &&
             rawColumn.dimensionType !== 'boolean')) {
-        throw new Error(`Invalid KTX schema column artifact: ${path}`);
+        throw new Error(`Invalid ktx schema column artifact: ${path}`);
     }
     return {
         name: rawColumn.name,
@@ -85,7 +85,7 @@ function parseForeignKey(rawForeignKey, path) {
         typeof rawForeignKey.fromColumn !== 'string' ||
         typeof rawForeignKey.toTable !== 'string' ||
         typeof rawForeignKey.toColumn !== 'string') {
-        throw new Error(`Invalid KTX schema foreign key artifact: ${path}`);
+        throw new Error(`Invalid ktx schema foreign key artifact: ${path}`);
     }
     return {
         fromColumn: rawForeignKey.fromColumn,
@@ -99,7 +99,7 @@ function parseForeignKey(rawForeignKey, path) {
 function parseTable(raw, path) {
     const parsed = JSON.parse(raw);
     if (!isRecord(parsed) || typeof parsed.name !== 'string' || !Array.isArray(parsed.columns)) {
-        throw new Error(`Invalid KTX schema table artifact: ${path}`);
+        throw new Error(`Invalid ktx schema table artifact: ${path}`);
     }
     return {
         catalog: optionalStringOrNull(parsed.catalog) ?? null,

package/dist/context/scan/relationship-benchmark-report.js

@@ -211,7 +211,7 @@ function compositeSkipBlocks(report) {
 }
 export function formatKtxRelationshipBenchmarkReportMarkdown(report) {
     const lines = [
-        '# KTX Relationship Discovery Benchmark Evidence',
+        '# ktx Relationship Discovery Benchmark Evidence',
         '',
         `Generated: ${report.generatedAt}`,
         '',

package/dist/context/scan/relationship-discovery.js

@@ -87,7 +87,7 @@ async function detectCompositeRelationships(input) {
     catch (error) {
         input.warnings.push({
             code: 'relationship_validation_failed',
-            message: `KTX composite relationship detection failed: ${error instanceof Error ? error.message : String(error)}`,
+            message: `ktx composite relationship detection failed: ${error instanceof Error ? error.message : String(error)}`,
             recoverable: true,
             metadata: { source: 'composite_relationship_detection' },
         });
@@ -110,7 +110,7 @@ function sqlExecutor(input) {
             warnings: [
                 {
                     code: 'connector_capability_missing',
-                    message: 'KTX scan connector cannot run read-only SQL relationship validation',
+                    message: 'ktx scan connector cannot run read-only SQL relationship validation',
                     recoverable: true,
                     metadata: { capability: 'readOnlySql' },
                 },
@@ -123,7 +123,7 @@ function sqlExecutor(input) {
             warnings: [
                 {
                     code: 'relationship_validation_failed',
-                    message: 'KTX scan connector advertises readOnlySql but does not expose executeReadOnly',
+                    message: 'ktx scan connector advertises readOnlySql but does not expose executeReadOnly',
                     recoverable: true,
                     metadata: { capability: 'readOnlySql' },
                 },

package/dist/context/scan/relationship-llm-proposal.js

@@ -116,7 +116,7 @@ function mapValidProposals(schema, output, settings) {
         const fromColumn = fromTable ? findColumn(fromTable, item.fromColumn) : null;
         const toColumn = toTable ? findColumn(toTable, item.toColumn) : null;
         if (!fromTable || !toTable || !fromColumn || !toColumn) {
-            warnings.push(invalidReferenceWarning('KTX relationship LLM proposal referenced a table or column that is not in the schema.', {
+            warnings.push(invalidReferenceWarning('ktx relationship LLM proposal referenced a table or column that is not in the schema.', {
                 proposal: item,
             }));
             continue;
@@ -148,7 +148,7 @@ function generationFailureWarning(error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
         code: 'relationship_llm_proposal_failed',
-        message: `KTX relationship LLM proposal failed: ${message}`,
+        message: `ktx relationship LLM proposal failed: ${message}`,
         recoverable: true,
     };
 }
@@ -159,7 +159,7 @@ export async function proposeKtxRelationshipCandidatesWithLlm(input) {
     const settings = mergeSettings(input.settings);
     const evidence = buildEvidencePacket(input.schema, input.profile, settings);
     const system = [
-        'You are helping KTX review possible SQL relationships before validation.',
+        'You are helping ktx review possible SQL relationships before validation.',
         'Use only the compact schema evidence. Propose likely primary keys and foreign keys for later SQL validation.',
         'Return structured output only; never assume a join is accepted.',
     ].join('\n');

package/dist/context/sl/local-query.js

@@ -1,52 +1,35 @@
+import { FEDERATED_CONNECTION_ID } from '../connections/federation.js';
+import { resolveRequiredConnectionId } from '../connections/resolve-connection.js';
+import { sqlAnalysisDialectForDriver } from '../sql-analysis/dialect.js';
 import { loadLocalSlSourceRecords } from './local-sl.js';
 import { toResolvedWire } from './semantic-layer.service.js';
+import { assertSafeConnectionId } from './source-files.js';
 const COMPILE_ONLY_REASON = 'Local semantic-layer query compiled SQL but no data-source execution adapter is configured.';
-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 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';
-}
+const FEDERATED_SL_QUERY_UNSUPPORTED = `Semantic-layer queries are per-connection and cannot target the federated connection '${FEDERATED_CONNECTION_ID}'. ` +
+    `Run a cross-database query as read-only SQL instead — ktx sql -c ${FEDERATED_CONNECTION_ID} "SELECT ..." or the sql_execution tool — ` +
+    'using catalog-qualified table names (connectionId.schema.table, or connectionId.table for sqlite; ' +
+    'double-quote ids that are not bare identifiers, e.g. "books-db".public.books).';
 function resolveLocalConnectionId(project, requested) {
-    if (requested) {
-        return assertSafeConnectionId(requested);
-    }
-    const ids = Object.keys(project.config.connections).sort();
-    if (ids.length === 1) {
-        return assertSafeConnectionId(ids[0]);
+    return assertSafeConnectionId(resolveRequiredConnectionId(project.config, requested));
+}
+// The planner rejects a source set carrying a join whose `to` names a source
+// outside that set, which would break every query for this connection. Keep only
+// joins resolvable within the connection's own sources; a cross-database join
+// (its `to` qualified by a sibling connection id) is just one such unresolvable
+// target and runs as raw SQL instead. Membership is the test, not a connection-id
+// prefix match, so a same-connection target whose name collides with a sibling
+// connection id is preserved.
+function withResolvableJoinsOnly(source, knownSourceNames) {
+    if (source.joins.length === 0) {
+        return source;
     }
-    throw new Error('connectionId is required when the local project has zero or multiple connections.');
+    const joins = source.joins.filter((join) => knownSourceNames.has(join.to));
+    return joins.length === source.joins.length ? source : { ...source, joins };
 }
 async function loadComputableSources(project, connectionId) {
-    return (await loadLocalSlSourceRecords(project, { connectionId: assertSafeConnectionId(connectionId) }))
-        .filter((record) => record.source.table || record.source.sql)
-        .map((record) => toResolvedWire(record.source));
+    const records = (await loadLocalSlSourceRecords(project, { connectionId })).filter((record) => record.source.table || record.source.sql);
+    const knownSourceNames = new Set(records.map((record) => record.source.name));
+    return records.map((record) => toResolvedWire(withResolvableJoinsOnly(record.source, knownSourceNames)));
 }
 function headersFromColumns(columns) {
     return columns
@@ -54,9 +37,13 @@ function headersFromColumns(columns) {
         .filter((name) => typeof name === 'string' && name.length > 0);
 }
 export async function compileLocalSlQuery(project, options) {
+    if (options.connectionId === FEDERATED_CONNECTION_ID) {
+        throw new Error(FEDERATED_SL_QUERY_UNSUPPORTED);
+    }
     await options.onProgress?.({ progress: 0, message: 'Compiling query' });
     const connectionId = resolveLocalConnectionId(project, options.connectionId);
-    const dialect = dialectForDriver(project.config.connections[connectionId]?.driver);
+    const driver = project.config.connections[connectionId]?.driver;
+    const dialect = sqlAnalysisDialectForDriver(driver);
     const sources = await loadComputableSources(project, connectionId);
     await options.onProgress?.({ progress: 0.3, message: 'Generating SQL' });
     const response = await options.compute.query({
@@ -106,7 +93,7 @@ export async function compileLocalSlQuery(project, options) {
             ...response.plan,
             execution: {
                 mode: 'executed',
-                driver: project.config.connections[connectionId]?.driver ?? 'unknown',
+                driver: driver ?? 'unknown',
                 maxRows,
                 rowCount: execution.rowCount,
             },

package/dist/context/sl/local-sl.d.ts

@@ -1,5 +1,4 @@
 import type { KtxEmbeddingPort } from '../../context/core/embedding.js';
-import type { KtxFileWriteResult } from '../../context/core/file-store.js';
 import type { KtxLocalProject } from '../../context/project/project.js';
 import type { PgliteSlSearchPrototypeOwnerOptions } from './pglite-sl-search-prototype.js';
 import type { SemanticLayerSource, SlDictionaryMatch, SlSearchLaneSummary, SlSearchMatchReason } from './types.js';
@@ -56,13 +55,6 @@ export declare function validateLocalSlSource(rawYaml: string, options?: {
     connectionId?: string;
     sourceName?: string;
 }): Promise<LocalSlValidationResult>;
-/** @internal */
-export declare function writeLocalSlSource(project: KtxLocalProject, input: {
-    connectionId: string;
-    sourceName: string;
-    yaml: string;
-}): Promise<KtxFileWriteResult>;
-/** @internal */
 export declare function readLocalSlSource(project: KtxLocalProject, input: {
     connectionId: string;
     sourceName: string;