@kaelio/ktx 0.12.0 → 0.13.0

package/dist/context/connections/resolve-connection.d.ts

@@ -0,0 +1,12 @@
+import type { KtxProjectConfig, KtxProjectConnectionConfig } from '../project/config.js';
+/**
+ * Look up a connection by id, throwing an expected (caller-driven) error that
+ * names the configured connections so an agent or CLI user can self-correct.
+ */
+export declare function resolveConfiguredConnection(config: KtxProjectConfig, connectionId: string): KtxProjectConnectionConfig;
+/**
+ * Resolve the connection id to run against: validate a requested id against the
+ * configured connections, or default to the sole connection when none is given.
+ * Throws an expected error that lists the configured connections otherwise.
+ */
+export declare function resolveRequiredConnectionId(config: KtxProjectConfig, requested: string | undefined): string;

package/dist/context/connections/resolve-connection.js

@@ -0,0 +1,37 @@
+import { KtxExpectedError } from '../../errors.js';
+function configuredConnectionIds(config) {
+    return Object.keys(config.connections).sort();
+}
+function availableConnectionsHint(config) {
+    const ids = configuredConnectionIds(config);
+    return ids.length === 0
+        ? 'No connections are configured in ktx.yaml.'
+        : `Configured connections: ${ids.join(', ')}.`;
+}
+/**
+ * Look up a connection by id, throwing an expected (caller-driven) error that
+ * names the configured connections so an agent or CLI user can self-correct.
+ */
+export function resolveConfiguredConnection(config, connectionId) {
+    const connection = config.connections[connectionId];
+    if (!connection) {
+        throw new KtxExpectedError(`Connection "${connectionId}" is not configured in ktx.yaml. ${availableConnectionsHint(config)}`);
+    }
+    return connection;
+}
+/**
+ * Resolve the connection id to run against: validate a requested id against the
+ * configured connections, or default to the sole connection when none is given.
+ * Throws an expected error that lists the configured connections otherwise.
+ */
+export function resolveRequiredConnectionId(config, requested) {
+    if (requested !== undefined) {
+        resolveConfiguredConnection(config, requested);
+        return requested;
+    }
+    const ids = configuredConnectionIds(config);
+    if (ids.length === 1) {
+        return ids[0];
+    }
+    throw new KtxExpectedError(`connectionId is required. ${availableConnectionsHint(config)}`);
+}

package/dist/context/core/git-env.d.ts

@@ -6,6 +6,10 @@ import { type SimpleGit } from 'simple-git';
  * directory is an existing repo ktx did not create and the machine has no configured git
  * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
  * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ *
+ * `commit.gpgsign=false` is injected as a per-invocation `-c` override so ktx's commits never
+ * attempt GPG signing: ktx commits under a synthetic identity that can never own a secret key, so
+ * a user's `commit.gpgsign=true` would otherwise fail every commit with "No secret key".
  */
 export declare function createSimpleGit(baseDir: string, identity?: {
     name: string;

package/dist/context/core/git-env.js

@@ -28,6 +28,10 @@ function sanitizedGitEnv(env = process.env) {
  * directory is an existing repo ktx did not create and the machine has no configured git
  * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
  * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ *
+ * `commit.gpgsign=false` is injected as a per-invocation `-c` override so ktx's commits never
+ * attempt GPG signing: ktx commits under a synthetic identity that can never own a secret key, so
+ * a user's `commit.gpgsign=true` would otherwise fail every commit with "No secret key".
  */
 export function createSimpleGit(baseDir, identity) {
     const env = sanitizedGitEnv();
@@ -37,5 +41,5 @@ export function createSimpleGit(baseDir, identity) {
         env.GIT_COMMITTER_NAME = identity.name;
         env.GIT_COMMITTER_EMAIL = identity.email;
     }
-    return simpleGit({ baseDir, unsafe: { allowUnsafeAskPass: true } }).env(env);
+    return simpleGit({ baseDir, config: ['commit.gpgsign=false'], unsafe: { allowUnsafeAskPass: true } }).env(env);
 }

package/dist/context/ingest/adapters/live-database/manifest.d.ts

@@ -56,11 +56,14 @@ export interface BuildLiveDatabaseManifestShardsInput {
     existingPreservedJoins?: Map<string, LiveDatabaseManifestJoinEntry[]>;
     existingDescriptions?: Map<string, LiveDatabaseManifestExistingDescriptions>;
     existingUsage?: Map<string, TableUsageOutput>;
+    federatedSiblingTargets?: Set<string>;
 }
 export interface BuildLiveDatabaseManifestShardsResult {
     shards: Map<string, LiveDatabaseManifestShard>;
     tablesProcessed: number;
 }
 export declare function mergeUsagePreservingExternal(existing: TableUsageOutput | undefined, incoming: TableUsageOutput | undefined): TableUsageOutput | undefined;
+/** @internal */
+export declare function buildJoinsByTable(tableNames: Set<string>, joins: LiveDatabaseManifestJoinData[], preservedJoins: Map<string, LiveDatabaseManifestJoinEntry[]>, federatedSiblingTargets?: Set<string>): Map<string, LiveDatabaseManifestJoinEntry[]>;
 export declare function buildLiveDatabaseManifestShards(input: BuildLiveDatabaseManifestShardsInput): BuildLiveDatabaseManifestShardsResult;
 export {};

package/dist/context/ingest/adapters/live-database/manifest.js

@@ -106,10 +106,14 @@ function joinCondition(leftTable, leftColumns, rightTable, rightColumns) {
     })
         .join(' AND ');
 }
-function buildJoinsByTable(tableNames, joins, preservedJoins) {
+/** @internal */
+export function buildJoinsByTable(tableNames, joins, preservedJoins, federatedSiblingTargets = new Set()) {
     const joinsByTable = new Map();
     for (const join of joins) {
-        if (!tableNames.has(join.fromTable) || !tableNames.has(join.toTable)) {
+        const fromLocal = tableNames.has(join.fromTable);
+        const toLocal = tableNames.has(join.toTable);
+        const toSibling = federatedSiblingTargets.has(join.toTable);
+        if (!fromLocal || (!toLocal && !toSibling)) {
             continue;
         }
         const relationship = RELATIONSHIP_MAP[join.relationship] ?? join.relationship;
@@ -119,20 +123,24 @@ function buildJoinsByTable(tableNames, joins, preservedJoins) {
             relationship,
             source: join.source,
         });
-        const reverseRelationship = RELATIONSHIP_INVERSE[relationship] ?? 'one_to_many';
-        addJoinOnce(joinsByTable, join.toTable, {
-            to: join.fromTable,
-            on: joinCondition(join.toTable, join.toColumns, join.fromTable, join.fromColumns),
-            relationship: reverseRelationship,
-            source: join.source,
-        });
+        // Reverse direction only when the target is a local table in THIS snapshot;
+        // a federated sibling has no shard here, so it gets no reverse entry.
+        if (toLocal) {
+            const reverseRelationship = RELATIONSHIP_INVERSE[relationship] ?? 'one_to_many';
+            addJoinOnce(joinsByTable, join.toTable, {
+                to: join.fromTable,
+                on: joinCondition(join.toTable, join.toColumns, join.fromTable, join.fromColumns),
+                relationship: reverseRelationship,
+                source: join.source,
+            });
+        }
     }
     for (const [tableName, tableJoins] of preservedJoins) {
         if (!tableNames.has(tableName)) {
             continue;
         }
         for (const join of tableJoins) {
-            if (tableNames.has(join.to)) {
+            if (tableNames.has(join.to) || federatedSiblingTargets.has(join.to)) {
                 addJoinOnce(joinsByTable, tableName, join);
             }
         }
@@ -141,7 +149,7 @@ function buildJoinsByTable(tableNames, joins, preservedJoins) {
 }
 export function buildLiveDatabaseManifestShards(input) {
     const tableNames = new Set(input.tables.map((table) => table.name));
-    const joinsByTable = buildJoinsByTable(tableNames, input.joins, input.existingPreservedJoins ?? new Map());
+    const joinsByTable = buildJoinsByTable(tableNames, input.joins, input.existingPreservedJoins ?? new Map(), input.federatedSiblingTargets ?? new Set());
     const shards = new Map();
     for (const table of input.tables) {
         const shardKey = getShardKey(input.connectionType, table.catalog, table.db);

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);
@@ -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/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,7 +24,7 @@ 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.',
+    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" }).',
@@ -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),

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

@@ -1,5 +1,8 @@
-import { KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
-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';
@@ -8,75 +11,77 @@ import { createKtxDictionarySearchService } from '../../context/sl/dictionary-se
 import { readLocalSlSource } from '../../context/sl/local-sl.js';
 import { assertSafeConnectionId } from '../../context/sl/source-files.js';
 import { readLocalKnowledgePage, searchLocalKnowledgePages } from '../wiki/local-knowledge.js';
-async function cleanupConnector(connector) {
-    if (connector?.cleanup) {
-        await connector.cleanup();
-    }
-}
 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' })
-            .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 } : {}),
-            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: {

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/scan/local-enrichment-artifacts.js

@@ -1,6 +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';
@@ -113,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();
@@ -146,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) {
@@ -170,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),
@@ -178,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/sl/local-query.js

@@ -1,22 +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.';
+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
@@ -24,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 = sqlAnalysisDialectForDriver(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({
@@ -76,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.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import YAML from 'yaml';
 import { z } from 'zod';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from '../connections/federation.js';
 import { HybridSearchCore } from '../../context/search/hybrid-search-core.js';
 import { DEFAULT_PRIORITY, resolveDescription } from './descriptions.js';
 import { normalizeSemanticLayerDescriptions } from './description-normalization.js';
@@ -86,7 +87,32 @@ function parsedStandaloneSource(parsed, name) {
     });
 }
 export async function loadLocalSlSourceRecords(project, input) {
-    const connectionId = assertSafeConnectionId(input.connectionId);
+    if (input.connectionId === FEDERATED_CONNECTION_ID) {
+        const descriptor = deriveFederatedConnection(project.config.connections, project.projectDir);
+        if (!descriptor) {
+            return [];
+        }
+        const perMember = await Promise.all(descriptor.members.map(async (member) => {
+            const records = await loadSingleConnectionSourceRecords(project, member.connectionId);
+            return records.map((record) => {
+                // The federated view is one virtual connection: rows carry its id and a
+                // member-prefixed name, so a listing/search row round-trips to
+                // `ktx sl -c _ktx_federated read <name>`. Member origin lives in the name.
+                const name = `${member.connectionId}.${record.name}`;
+                return {
+                    ...record,
+                    connectionId: FEDERATED_CONNECTION_ID,
+                    name,
+                    source: { ...record.source, name },
+                };
+            });
+        }));
+        return perMember.flat();
+    }
+    return loadSingleConnectionSourceRecords(project, input.connectionId);
+}
+async function loadSingleConnectionSourceRecords(project, rawConnectionId) {
+    const connectionId = assertSafeConnectionId(rawConnectionId);
     const dir = `semantic-layer/${connectionId}`;
     const schemaDir = `${dir}/_schema`;
     const listed = await project.fileStore.listFiles(dir);

package/dist/context/sl/source-files.d.ts

@@ -1,4 +1,6 @@
 import type { KtxFileStorePort } from '../../context/core/file-store.js';
+/** @internal */
+export declare function isReservedConnectionId(connectionId: string): boolean;
 export declare function assertSafeConnectionId(connectionId: string): string;
 export declare function isSafeConnectionId(connectionId: string | undefined): connectionId is string;
 export declare function sourceNameFromPath(path: string): string;

package/dist/context/sl/source-files.js

@@ -17,7 +17,14 @@ function assertSafePathToken(kind, value) {
     }
     return value;
 }
+/** @internal */
+export function isReservedConnectionId(connectionId) {
+    return connectionId.startsWith('_ktx_');
+}
 export function assertSafeConnectionId(connectionId) {
+    if (isReservedConnectionId(connectionId)) {
+        throw new Error(`Connection id "${connectionId}" uses the reserved "_ktx_" prefix.`);
+    }
     if (!isSafeConnectionId(connectionId)) {
         throw new Error(`Unsafe connection id: ${connectionId}`);
     }