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>

docs-site/content/docs/concepts/cross-database-federation.mdx

@@ -0,0 +1,154 @@
+---
+title: Cross-database federation
+description: How ktx federates postgres, mysql, and sqlite connections so a single read-only SQL query can join across them without copying data.
+---
+
+Cross-database federation lets a single read-only SQL query join tables that
+live in different databases. **ktx** achieves this by embedding DuckDB and
+using its `ATTACH` mechanism to connect each member database read-only. The
+join executes inside DuckDB at query time — live data, no ETL, no copy.
+
+You run federated queries as raw SQL against the `_ktx_federated` connection
+(see [Querying the federated connection
+directly](#querying-the-federated-connection-directly)). Semantic-layer queries
+(`ktx sl query` / the `sl_query` tool) stay per-connection; pointing one at
+`_ktx_federated` returns an error telling you to use raw SQL instead.
+
+Federation activates automatically when a `ktx.yaml` file declares two or more
+attach-compatible connections. There is nothing to configure and no federation
+block to add. With zero or one compatible connection the behavior is unchanged.
+
+## Which connections participate
+
+The v1 federation engine supports three drivers:
+
+| Driver | Participates in federation |
+|--------|---------------------------|
+| `postgres` | Yes |
+| `mysql` | Yes |
+| `sqlite` | Yes |
+| `snowflake` | No — standalone connection |
+| `bigquery` | No — standalone connection |
+| `clickhouse` | No — standalone connection |
+| `sqlserver` | No — standalone connection |
+
+Non-participating connections continue to work exactly as they did. They are
+queried independently; they do not appear as federation members.
+
+## How it activates
+
+**ktx** inspects the connections in `ktx.yaml` at startup. When it finds two or
+more connections whose driver is `postgres`, `mysql`, or `sqlite`, it
+instantiates the DuckDB federation engine and attaches each one read-only.
+There is no `federation:` key, no opt-in flag, and no connection-level setting
+to enable. The engine is derived entirely from what is already declared.
+
+A minimal `ktx.yaml` that triggers federation:
+
+```yaml
+connections:
+  pg_books:
+    driver: postgres
+    url: "postgres://user:pass@localhost:5432/books" # pragma: allowlist secret
+  sqlite_reviews:
+    driver: sqlite
+    path: ./data/reviews.db
+```
+
+Two attach-compatible connections are present, so federation is active.
+
+## Table naming in federated queries
+
+Inside a federated query, postgres and mysql tables use a three-part name:
+`connectionId.schema.table`. SQLite tables, which have no schema layer in
+DuckDB, use the two-part form `connectionId.table`. In both cases the
+connection's `id` field in `ktx.yaml` becomes the catalog name inside DuckDB.
+
+If a connection `id` is not a bare SQL identifier — for example it contains a
+hyphen, like `books-db` — double-quote it in the query the same way DuckDB
+quotes any identifier: `"books-db".public.books`. Writing it unquoted
+(`books-db.public.books`) is a SQL syntax error, not a federation feature.
+
+For the example above:
+
+- `pg_books.public.books` — the `books` table in the `public` schema of the
+  postgres connection
+- `sqlite_reviews.reviews` — the `reviews` table in the sqlite connection
+
+These fully qualified names are what you write when you query the federated
+connection with raw SQL (see [Querying the federated connection
+directly](#querying-the-federated-connection-directly)). A source file's own
+`table:` field is not prefixed this way — see [Source files keep member-native
+table refs](#source-files-keep-member-native-table-refs) below.
+
+## Source names in the federated view
+
+When you list or search semantic-layer sources under the federated connection,
+each source's `name` is prefixed with its member connection id — for example
+`pg_books.books` and `sqlite_reviews.reviews`. The prefix keeps names unique
+when two members own a table with the same name: a `users` table in each of
+`pg_app` and `sqlite_app` surfaces as `pg_app.users` and `sqlite_app.users`
+rather than colliding on a bare `users`.
+
+## Source files keep member-native table refs
+
+A source file's physical `table:` field is not prefixed with the connection id.
+It stays the member-native reference the connector uses on its own —
+`public.books` for the postgres member, `reviews` for the sqlite member —
+because the same file backs a per-connection semantic-layer query against that
+member, which runs on the member's own driver where a `pg_books.` catalog prefix
+would point at a database that does not exist. The connection-id prefix is a
+DuckDB catalog name that appears only in raw federated SQL; the member prefix on
+the source `name` (above) is independent of it.
+
+## Cross-database joins
+
+Write a cross-database join as raw SQL against `_ktx_federated` — see
+[Querying the federated connection
+directly](#querying-the-federated-connection-directly) below for a runnable
+example. DuckDB attaches both members and resolves the join live at query time.
+
+Declaring the join in a source file's `joins:` block is not supported yet. The
+semantic layer plans each connection on its own, so a `joins:` entry whose `to:`
+points at a table in another member is not resolved across the federation
+boundary. Until that lands, express cross-database joins as raw SQL.
+
+## Querying the federated connection directly
+
+The federated connection is addressable by its id,
+`_ktx_federated`, anywhere **ktx** runs read-only SQL. The same id works for the
+`ktx sql` command and for a data agent calling the `sql_execution` MCP tool, so
+both surfaces can run a cross-database query without a source file:
+
+```bash
+ktx sql -c _ktx_federated \
+  "SELECT b.title, avg(r.rating) AS avg_rating
+   FROM pg_books.public.books b
+   JOIN sqlite_reviews.reviews r ON b.id = r.book_id
+   GROUP BY b.title"
+```
+
+Table names follow the rules from
+[Table naming in federated queries](#table-naming-in-federated-queries):
+three-part `connectionId.schema.table` for postgres and mysql, two-part
+`connectionId.table` for sqlite. The `_ktx_federated` id is virtual — it is
+never written to `ktx.yaml` and only exists when two or more attach-compatible
+connections are declared. It surfaces in `ktx connection` and in the agent's
+connection list so the id is discoverable. Querying a single member database
+directly with its own connection id (`ktx sql -c pg_books ...`) is unchanged.
+
+## Federated queries are read-only
+
+DuckDB attaches every member database with read-only access. Federated queries
+are `SELECT`/`WITH` only. No writes, no DDL, and no mutations reach any member
+database through the federation engine.
+
+## Current limitations
+
+- **Raw SQL joins only.** Cross-database joins are written as raw SQL; declaring
+  them in a source's `joins:` block and automatic discovery of cross-database
+  relationships are not available yet. Intra-database relationship discovery for
+  each member connection is unchanged.
+- **postgres, mysql, and sqlite only.** Other drivers (snowflake, bigquery,
+  clickhouse, sqlserver) do not participate in federation in this version. They
+  remain usable as standalone connections.

docs-site/content/docs/concepts/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Concepts",
   "defaultOpen": true,
-  "pages": ["the-context-layer", "semantic-layer-internals", "wiki-retrieval"]
+  "pages": ["the-context-layer", "semantic-layer-internals", "cross-database-federation", "wiki-retrieval"]
 }