feat(duckdb): cross-database federation via derived DuckDB connection (#295)

* feat(duckdb): add @duckdb/node-api dependency for federation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * refactor(connectors): extract resolveStringReference to shared module Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * refactor(connectors): route all identical connectors through shared resolveStringReference Collapse the 5 remaining private copies in bigquery, clickhouse, mysql, snowflake, and sqlserver into the shared module. Fix a latent bug in the shared module where `~/path` was incorrectly sliced (dropping only `~`, leaving the leading `/` and making resolve() ignore homedir). Add a tilde-expansion test that caught the bug and now covers that branch. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(sl): reserve _ktx_ connection-id prefix for virtual connections Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(connections): derive virtual federated connection from compatible members Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(duckdb): federated executor builds READ_ONLY attaches and runs SQL Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(duckdb): close federated DuckDB instance and escape quotes in attach url Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(sl): union member source directories for _ktx_federated Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(query): route _ktx_federated through DuckDB executor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(sl): use duckdb dialect for federated query compilation Bypass assertSafeConnectionId for _ktx_federated in resolveLocalConnectionId and loadComputableSources, and resolve the compute dialect to 'duckdb' when connectionId is FEDERATED_CONNECTION_ID instead of falling through to the default postgres lookup. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(duckdb): end-to-end cross-catalog federated join Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(duckdb): harden federated join test with multi-book join-key coverage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(ingest): keep declared cross-DB joins to federated siblings Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(setup): surface federated connection availability after adding a member Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(setup): mark federationNoticeFor @internal for dead-code gate Also marks attachTypeForDriver, buildAttachStatements, and isReservedConnectionId @internal — all three are exported solely for unit-test access with no production cross-file consumer. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(concepts): document cross-database federation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(concepts): correct sqlite two-part naming in federation doc Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(duckdb): quote federated catalog alias so hyphenated connection ids attach * refactor(duckdb): single-source federation driver list, dedup attach loads Collapse the parallel ATTACH_COMPATIBLE_DRIVERS set and ATTACH_TYPE_BY_DRIVER map into one map in federation.ts whose keys are the membership rule. Replace FederatedMember.config (read only via a type-erasing cast) with a typed url field extracted at derive time. Emit INSTALL/LOAD once per distinct driver type instead of once per member. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(duckdb): close federated DuckDB instance on connect failure; dedup id validation Wrap the federated DuckDB instance in its own try/finally so a failing connect() or a throwing connection.closeSync() no longer leaks the native instance. Route setup-sources connection-id validation through the canonical assertSafeConnectionId so the reserved _ktx_ prefix guard applies there too. Derive the federated dialect through sqlAnalysisDialectForDriver instead of a hardcoded literal. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(federation): carry member connection config and projectDir on FederatedMember Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(federation): resolve per-member attach targets via canonical connector resolvers Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): quote mysql attach-string values like postgres Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): resolve member attach targets via canonical resolvers, supporting sqlite path: Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(federation): thread projectDir through deriveFederatedConnection callers Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(federation): add shared project read-only SQL executor that routes _ktx_federated Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(federation): exercise shared executor default federated path with real DuckDB Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(federation): route ingest query executor through shared executor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): route MCP sql_execution _ktx_federated through shared executor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): preserve cross-DB joins to federated siblings in manifest re-emit Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): preserve declared cross-DB joins through scan re-ingest Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(federation): document sibling-ref invariant, drop unsafe casts in test Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): namespace federated source names by member to avoid collisions Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(federation): document member-namespaced federated source names Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): preserve member SSL/search_path in attach, classify federated MCP errors Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(federation): simplify federated dispatch and parallelize sibling reads Dedup the federated driver ternary in local-query, derive the prefixed source.name from the already-built name, drop the duplicated error in federatedAttachTarget's exhaustive switch, inline the one-line cleanupConnector wrapper, and parallelize federatedSiblingTargets' shard reads (was sequential await-in-for on the scan hot path). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(federation): carry headerTypes through shared SQL executor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(federation): add shared federated connection listing builder Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): route ktx sql through shared executor for _ktx_federated parity Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(federation): show _ktx_federated in ktx connection list Surfaces the virtual federated connection in the output of `ktx connection list` so agents and users can discover cross-database querying when 2+ attach-compatible connections are configured. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(federation): surface _ktx_federated in MCP connection_list Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(federation): ktx sql federated cross-file join end-to-end Drive runKtxSql with the real federated DuckDB executor against two on-disk sqlite files, stubbing only SQL validation. The test surfaced that the JSON output path could not serialize bigint values DuckDB returns for integer columns; printJson now coerces bigint to JSON numbers, matching the plain/pretty paths. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(federation): document direct _ktx_federated query surface Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): coerce DuckDB bigint to number in shared federated executor DuckDB returns integer columns as JS bigint, which JSON.stringify cannot serialize. The CLI --json path worked around this with a replacer, but the MCP sql_execution tool serializes via plain JSON.stringify and crashed on any federated query selecting an integer column. Coerce bigint to Number once in executeFederatedQuery so every consumer (CLI, MCP, ingest, SL) gets a JSON-safe result, and remove the now-redundant CLI replacer. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(federation): simplify driver map and collapse forked MCP SQL path - Replace the identity-valued ATTACH_TYPE_BY_DRIVER record with a ATTACH_COMPATIBLE_DRIVERS Set; the driver name doubles as the attach type, so the map encoded nothing beyond membership. - Switch federatedAttachTarget directly on the driver with a default throw, dropping the unreachable post-switch throw and its comment. - Route the MCP sql_execution standard-connection case through the shared executeProjectReadOnlySql instead of reimplementing the connector create/capability-check/execute/cleanup ceremony, so federated and standard connections share one execution path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(federation): allowlist placeholder credentials for detect-secrets The federation doc example URL and the federated-attach test fixtures use literal placeholder credentials that trip detect-secrets. Mark them with line-scoped pragma allowlist comments so a real secret added later is still caught. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(federation): correct SL addressing, join pruning, and id-quoting guidance - Federated SL list/search records carry the virtual `_ktx_federated` connection id (member origin stays in the prefixed source name), so rows round-trip to `ktx sl -c _ktx_federated read` and the fts index no longer clobbers per-connection partitions. - Prune semantic-layer joins by membership in the connection's own source set instead of matching the target's first dotted segment against other connection ids; a same-connection join whose target name collides with a sibling connection id is preserved, and orphan targets that would poison the planner are dropped. - Document double-quoting for connection ids that are not bare SQL identifiers (e.g. "books-db".public.books) in the federated naming hint, the sl-query rejection error, and the federation docs. - Preserve exact federated BIGINT values beyond 2^53 as strings instead of rounding, and steer the setup federation notice to raw SQL against `_ktx_federated`. * fix(federation): carry ssl:true into postgres URL attach target A postgres member configured with `url` plus `ssl: true` resolved to both a connectionString and an ssl flag, but the federated attach builder early-returned the bare URL and dropped the ssl intent. DuckDB then handed libpq a URL with no sslmode, so the URL path silently diverged from the discrete-field path (which emits sslmode=require) and from the direct scan path (which enforces TLS). Append sslmode=require to the URL when the member sets ssl, unless the URL already pins a stronger sslmode. --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Andrey Avtomonov <andreybavt@gmail.com>
2026-06-25 08:48:08 +02:00 · 2026-06-15 22:01:39 +07:00 · 2026-06-15 22:01:39 +07:00 · 6c815ef529
commit 6c815ef529
parent b81391cd9f
51 changed files with 2608 additions and 271 deletions
--- a/packages/cli/test/context/sl/local-query-federated.integration.test.ts
+++ b/packages/cli/test/context/sl/local-query-federated.integration.test.ts
@ -0,0 +1,111 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildDefaultKtxProjectConfig } from '../../../src/context/project/config.js';
+import { executeProjectReadOnlySql } from '../../../src/context/connections/project-sql-executor.js';
+import type { GitService } from '../../../src/context/core/git.service.js';
+import { LocalGitFileStore } from '../../../src/context/project/local-git-file-store.js';
+import type { KtxLocalProject } from '../../../src/context/project/project.js';
+import { loadLocalSlSourceRecords } from '../../../src/context/sl/local-sl.js';
+
+const BOOKS_MANIFEST = `tables:
+  books:
+    table: main.books
+    columns:
+      - name: id
+        type: number
+        pk: true
+      - name: title
+        type: string
+`;
+
+const REVIEWS_MANIFEST = `tables:
+  reviews:
+    table: main.reviews
+    columns:
+      - name: book_id
+        type: number
+        pk: true
+      - name: stars
+        type: number
+`;
+
+// On-disk file store only (no git init/commit) so manifest seeding never hits
+// the gpg-signing path; connections also carry real sqlite paths so the
+// federated executor can attach them.
+function fakeProject(projectDir: string, connections: KtxLocalProject['config']['connections']): KtxLocalProject {
+  const fileStore = new LocalGitFileStore({ rootDir: projectDir, git: {} as GitService });
+  const config = { ...buildDefaultKtxProjectConfig(), connections };
+  return {
+    projectDir,
+    configPath: join(projectDir, 'ktx.yaml'),
+    config,
+    coreConfig: {} as KtxLocalProject['coreConfig'],
+    git: {} as GitService,
+    fileStore,
+  };
+}
+
+async function seedManifest(project: KtxLocalProject, path: string, content: string): Promise<void> {
+  await project.fileStore.writeFile(path, content, 'ktx', 'ktx@example.com', 'seed manifest', { skipLock: true });
+}
+
+describe('federated SL source loading and physical execution (real DuckDB)', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'ktx-local-query-fed-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('namespaces source names while keeping physical table refs, and executes against them', async () => {
+    const projectDir = join(tempDir, 'project');
+    const booksPath = join(tempDir, 'books.db');
+    const reviewsPath = join(tempDir, 'reviews.db');
+
+    const books = new Database(booksPath);
+    books.exec("CREATE TABLE books (id INTEGER, title TEXT); INSERT INTO books VALUES (1, 'Dune'), (2, 'Foundation');");
+    books.close();
+    const reviews = new Database(reviewsPath);
+    reviews.exec('CREATE TABLE reviews (book_id INTEGER, stars INTEGER); INSERT INTO reviews VALUES (1, 5), (1, 4), (2, 2);');
+    reviews.close();
+
+    const project = fakeProject(projectDir, {
+      sqlite_books: { driver: 'sqlite', path: booksPath },
+      sqlite_reviews: { driver: 'sqlite', path: reviewsPath },
+    });
+    await seedManifest(project, 'semantic-layer/sqlite_books/_schema/main.yaml', BOOKS_MANIFEST);
+    await seedManifest(project, 'semantic-layer/sqlite_reviews/_schema/main.yaml', REVIEWS_MANIFEST);
+
+    // (a) Name-vs-physical separation: federated loading namespaces source.name
+    // by member id while source.table stays the unprefixed physical ref.
+    const records = await loadLocalSlSourceRecords(project, { connectionId: '_ktx_federated' });
+    const byName = new Map(records.map((record) => [record.source.name, record.source.table]));
+    expect([...byName.keys()].sort()).toEqual(['sqlite_books.books', 'sqlite_reviews.reviews']);
+    expect(byName.get('sqlite_books.books')).toBe('main.books');
+    expect(byName.get('sqlite_reviews.reviews')).toBe('main.reviews');
+
+    // (b) Physical targeting end-to-end: a federated query joining the two
+    // attached catalogs by their connectionId-prefixed physical refs returns
+    // the correct joined rows through live DuckDB.
+    const result = await executeProjectReadOnlySql({
+      project,
+      input: {
+        connectionId: '_ktx_federated',
+        connection: undefined,
+        sql: 'SELECT b.title, AVG(r.stars) AS avg_stars FROM sqlite_books.books b JOIN sqlite_reviews.reviews r ON b.id = r.book_id GROUP BY b.title ORDER BY b.title',
+        maxRows: 100,
+      },
+      createConnector: () => {
+        throw new Error('federated path must not create a scan connector');
+      },
+    });
+    expect(result.rows.map((row) => row[0])).toEqual(['Dune', 'Foundation']);
+    expect(Number(result.rows[0][1])).toBeCloseTo(4.5);
+  });
+});
--- a/packages/cli/test/context/sl/local-query-federated.test.ts
+++ b/packages/cli/test/context/sl/local-query-federated.test.ts
@ -0,0 +1,207 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { KtxSemanticLayerComputePort } from '../../../src/context/daemon/semantic-layer-compute.js';
+import type { KtxLocalProject } from '../../../src/context/project/project.js';
+import { compileLocalSlQuery } from '../../../src/context/sl/local-query.js';
+
+function makeFakeProject(): KtxLocalProject {
+  const fileStore = {
+    listFiles: vi.fn(async () => ({ files: [] })),
+    readFile: vi.fn(async () => ({ content: '' })),
+    writeFile: vi.fn(async () => ({})),
+    deleteFile: vi.fn(async () => ({})),
+    fileHistory: vi.fn(async () => []),
+    headCommit: vi.fn(async () => null),
+  } as unknown as KtxLocalProject['fileStore'];
+
+  return {
+    projectDir: '/tmp/fake-ktx-project',
+    configPath: '/tmp/fake-ktx-project/ktx.yaml',
+    config: {
+      connections: {
+        pg_books: { driver: 'postgres' },
+        sqlite_reviews: { driver: 'sqlite' },
+      },
+      storage: { state: 'sqlite', search: 'sqlite-fts5', git: {} },
+      llm: {},
+      ingest: {},
+      agent: {},
+      scan: {},
+    } as unknown as KtxLocalProject['config'],
+    coreConfig: {} as KtxLocalProject['coreConfig'],
+    git: {} as KtxLocalProject['git'],
+    fileStore,
+  };
+}
+
+function makeFakeProjectWithFiles(
+  connections: Record<string, { driver: string }>,
+  files: Record<string, string>,
+): KtxLocalProject {
+  const fileStore = {
+    listFiles: vi.fn(async (dir: string) => ({
+      files: Object.keys(files).filter((path) => path.startsWith(`${dir}/`)),
+    })),
+    readFile: vi.fn(async (path: string) => ({ content: files[path] ?? '' })),
+    writeFile: vi.fn(async () => ({})),
+    deleteFile: vi.fn(async () => ({})),
+    fileHistory: vi.fn(async () => []),
+    headCommit: vi.fn(async () => null),
+  } as unknown as KtxLocalProject['fileStore'];
+
+  return {
+    projectDir: '/tmp/fake-ktx-project',
+    configPath: '/tmp/fake-ktx-project/ktx.yaml',
+    config: {
+      connections,
+      storage: { state: 'sqlite', search: 'sqlite-fts5', git: {} },
+      llm: {},
+      ingest: {},
+      agent: {},
+      scan: {},
+    } as unknown as KtxLocalProject['config'],
+    coreConfig: {} as KtxLocalProject['coreConfig'],
+    git: {} as KtxLocalProject['git'],
+    fileStore,
+  };
+}
+
+function makeFakeCompute(): KtxSemanticLayerComputePort & {
+  lastDialect: string | undefined;
+  lastSources: Array<{ name: string; joins?: Array<{ to: string }> }> | undefined;
+} {
+  const fake = {
+    lastDialect: undefined as string | undefined,
+    lastSources: undefined as Array<{ name: string; joins?: Array<{ to: string }> }> | undefined,
+    query: vi.fn(async (input: { dialect: string; query: unknown; sources: unknown[] }) => {
+      fake.lastDialect = input.dialect;
+      fake.lastSources = input.sources as Array<{ name: string; joins?: Array<{ to: string }> }>;
+      return {
+        sql: 'select 1',
+        dialect: input.dialect,
+        columns: [],
+        plan: { measures: [], dimensions: [] },
+      };
+    }),
+    validateSources: vi.fn(),
+    generateSources: vi.fn(),
+  };
+  return fake;
+}
+
+describe('compileLocalSlQuery — federated connection', () => {
+  it('rejects federated queries and points to raw SQL', async () => {
+    const project = makeFakeProject();
+    const compute = makeFakeCompute();
+
+    await expect(
+      compileLocalSlQuery(project, {
+        connectionId: '_ktx_federated',
+        query: { measures: [], dimensions: [] },
+        compute,
+        execute: false,
+      }),
+    ).rejects.toThrow(/_ktx_federated[\s\S]*ktx sql/);
+    // The compute adapter must never be invoked for a federated query.
+    expect(compute.query).not.toHaveBeenCalled();
+  });
+
+  it('still uses the driver dialect for a normal connection', async () => {
+    const project = makeFakeProject();
+    const compute = makeFakeCompute();
+
+    await compileLocalSlQuery(project, {
+      connectionId: 'pg_books',
+      query: { measures: [], dimensions: [] },
+      compute,
+      execute: false,
+    });
+
+    expect(compute.lastDialect).toBe('postgres');
+  });
+
+  it('drops a cross-connection join target so a member query is not poisoned', async () => {
+    // A preserved cross-DB join (to: sqlite_reviews.reviews) would otherwise be
+    // an orphan target the planner rejects, breaking every pg_books SL query.
+    const manifest = `tables:
+  books:
+    table: public.books
+    columns:
+      - name: id
+        type: number
+        pk: true
+      - name: author_id
+        type: number
+    joins:
+      - to: sqlite_reviews.reviews
+        on: books.id = reviews.book_id
+        relationship: one_to_many
+      - to: authors
+        on: books.author_id = authors.id
+        relationship: many_to_one
+  authors:
+    table: public.authors
+    columns:
+      - name: id
+        type: number
+        pk: true
+`;
+    const project = makeFakeProjectWithFiles(
+      { pg_books: { driver: 'postgres' }, sqlite_reviews: { driver: 'sqlite' } },
+      { 'semantic-layer/pg_books/_schema/public.yaml': manifest },
+    );
+    const compute = makeFakeCompute();
+
+    await compileLocalSlQuery(project, {
+      connectionId: 'pg_books',
+      query: { measures: [], dimensions: [] },
+      compute,
+      execute: false,
+    });
+
+    expect(compute.query).toHaveBeenCalledTimes(1);
+    const books = compute.lastSources?.find((source) => source.name === 'books');
+    // The same-connection join survives; only the federated-sibling target is dropped.
+    expect(books?.joins?.map((join) => join.to)).toEqual(['authors']);
+  });
+
+  it('keeps a same-connection join whose target name collides with another connection id', async () => {
+    // Connection ids and source names share a vocabulary, so a sibling connection
+    // can be named `authors` while a same-connection source is also `authors`. The
+    // join target resolves within the connection and must not be pruned.
+    const manifest = `tables:
+  books:
+    table: public.books
+    columns:
+      - name: id
+        type: number
+        pk: true
+      - name: author_id
+        type: number
+    joins:
+      - to: authors
+        on: books.author_id = authors.id
+        relationship: many_to_one
+  authors:
+    table: public.authors
+    columns:
+      - name: id
+        type: number
+        pk: true
+`;
+    const project = makeFakeProjectWithFiles(
+      { pg_books: { driver: 'postgres' }, authors: { driver: 'postgres' } },
+      { 'semantic-layer/pg_books/_schema/public.yaml': manifest },
+    );
+    const compute = makeFakeCompute();
+
+    await compileLocalSlQuery(project, {
+      connectionId: 'pg_books',
+      query: { measures: [], dimensions: [] },
+      compute,
+      execute: false,
+    });
+
+    const books = compute.lastSources?.find((source) => source.name === 'books');
+    expect(books?.joins?.map((join) => join.to)).toEqual(['authors']);
+  });
+});
--- a/packages/cli/test/context/sl/local-sl-federated.test.ts
+++ b/packages/cli/test/context/sl/local-sl-federated.test.ts
@ -0,0 +1,108 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildDefaultKtxProjectConfig } from '../../../src/context/project/config.js';
+import type { GitService } from '../../../src/context/core/git.service.js';
+import { LocalGitFileStore } from '../../../src/context/project/local-git-file-store.js';
+import type { KtxLocalProject } from '../../../src/context/project/project.js';
+import { loadLocalSlSourceRecords } from '../../../src/context/sl/local-sl.js';
+
+const BOOKS_MANIFEST = `tables:
+  books:
+    table: public.books
+    columns:
+      - name: book_id
+        type: number
+        pk: true
+      - name: title
+        type: string
+`;
+
+const REVIEWS_MANIFEST = `tables:
+  reviews:
+    table: main.reviews
+    columns:
+      - name: review_id
+        type: number
+        pk: true
+      - name: rating
+        type: number
+`;
+
+// Build a project backed only by an on-disk file store (no git init, no
+// commit), so the fixture never hits the gpg-signing path during init.
+function fakeProject(projectDir: string, connections: KtxLocalProject['config']['connections']): KtxLocalProject {
+  const fileStore = new LocalGitFileStore({ rootDir: projectDir, git: {} as GitService });
+  const config = { ...buildDefaultKtxProjectConfig(), connections };
+  return {
+    projectDir,
+    configPath: join(projectDir, 'ktx.yaml'),
+    config,
+    coreConfig: {} as KtxLocalProject['coreConfig'],
+    git: {} as GitService,
+    fileStore,
+  };
+}
+
+// `skipLock: true` writes the file to disk without committing, avoiding git.
+async function seedManifest(project: KtxLocalProject, path: string, content: string): Promise<void> {
+  await project.fileStore.writeFile(path, content, 'ktx', 'ktx@example.com', 'seed manifest', { skipLock: true });
+}
+
+describe('federated semantic-layer source loading', () => {
+  let tempDir: string;
+  let project: KtxLocalProject;
+  let singleMemberProject: KtxLocalProject;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'ktx-local-sl-fed-'));
+
+    project = fakeProject(join(tempDir, 'project'), {
+      pg_books: { driver: 'postgres' },
+      sqlite_reviews: { driver: 'sqlite' },
+    });
+    await seedManifest(project, 'semantic-layer/pg_books/_schema/public.yaml', BOOKS_MANIFEST);
+    await seedManifest(project, 'semantic-layer/sqlite_reviews/_schema/main.yaml', REVIEWS_MANIFEST);
+
+    singleMemberProject = fakeProject(join(tempDir, 'single'), {
+      pg_books: { driver: 'postgres' },
+    });
+    await seedManifest(singleMemberProject, 'semantic-layer/pg_books/_schema/public.yaml', BOOKS_MANIFEST);
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('namespaces member source records by connection id for _ktx_federated', async () => {
+    const records = await loadLocalSlSourceRecords(project, { connectionId: '_ktx_federated' });
+    const names = records.map((r) => r.source.name).sort();
+    expect(names).toEqual(['pg_books.books', 'sqlite_reviews.reviews']);
+  });
+
+  it('keeps colliding member table names distinct via namespacing', async () => {
+    const collide = fakeProject(join(tempDir, 'collide'), {
+      pg_a: { driver: 'postgres' },
+      sqlite_b: { driver: 'sqlite' },
+    });
+    const usersManifest = `tables:\n  users:\n    table: public.users\n    columns:\n      - name: id\n        type: number\n`;
+    await seedManifest(collide, 'semantic-layer/pg_a/_schema/public.yaml', usersManifest);
+    await seedManifest(collide, 'semantic-layer/sqlite_b/_schema/main.yaml', usersManifest);
+    const records = await loadLocalSlSourceRecords(collide, { connectionId: '_ktx_federated' });
+    expect(records.map((r) => r.source.name).sort()).toEqual(['pg_a.users', 'sqlite_b.users']);
+  });
+
+  it('tags member records with the virtual federated connection id so reads round-trip', async () => {
+    const records = await loadLocalSlSourceRecords(project, { connectionId: '_ktx_federated' });
+    // The federated connection owns no directory and is addressed by one virtual
+    // id; the member-prefixed names (asserted above) prove the union read from
+    // member dirs, so the (connectionId, name) pair resolves back via `sl read`.
+    expect(records.map((r) => r.connectionId)).toEqual(['_ktx_federated', '_ktx_federated']);
+  });
+
+  it('returns empty for _ktx_federated when fewer than 2 compatible members', async () => {
+    const records = await loadLocalSlSourceRecords(singleMemberProject, { connectionId: '_ktx_federated' });
+    expect(records).toEqual([]);
+  });
+});
--- a/packages/cli/test/context/sl/source-files-reserved.test.ts
+++ b/packages/cli/test/context/sl/source-files-reserved.test.ts
@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { assertSafeConnectionId, isReservedConnectionId } from '../../../src/context/sl/source-files.js';
+
+describe('reserved connection ids', () => {
+  it('flags _ktx_ prefixed ids as reserved', () => {
+    expect(isReservedConnectionId('_ktx_federated')).toBe(true);
+    expect(isReservedConnectionId('_ktx_anything')).toBe(true);
+  });
+
+  it('does not flag normal ids', () => {
+    expect(isReservedConnectionId('pg_books')).toBe(false);
+    expect(isReservedConnectionId('sqlite_reviews')).toBe(false);
+  });
+
+  it('rejects a user-supplied reserved id', () => {
+    expect(() => assertSafeConnectionId('_ktx_federated')).toThrow(/reserved/i);
+  });
+
+  it('still accepts normal ids', () => {
+    expect(assertSafeConnectionId('pg_books')).toBe('pg_books');
+  });
+});