@kaelio/ktx 0.13.0 → 0.14.0

package/dist/context/scan/types.d.ts

@@ -1,6 +1,8 @@
 import type { KtxTableRefKey } from './table-ref.js';
-export type KtxConnectionDriver = 'sqlite' | 'postgres' | 'sqlserver' | 'bigquery' | 'snowflake' | 'mysql' | 'clickhouse';
-export type KtxScanMode = 'structural' | 'relationships' | 'enriched';
+export type KtxConnectionDriver = 'sqlite' | 'postgres' | 'sqlserver' | 'bigquery' | 'snowflake' | 'mysql' | 'clickhouse' | 'mongodb';
+/** Canonical scan-mode registry. Runtime validation derives its allowlist here. */
+export declare const KTX_SCAN_MODES: readonly ["structural", "relationships", "enriched"];
+export type KtxScanMode = (typeof KTX_SCAN_MODES)[number];
 export type KtxScanTrigger = 'cli' | 'mcp' | 'schema_scan' | 'scheduled' | 'manual';
 export interface KtxConnectorCapabilities {
     structuralIntrospection: true;
@@ -293,7 +295,7 @@ interface KtxScanArtifactPaths {
     manifestShards: string[];
     enrichmentArtifacts: string[];
 }
-type KtxScanWarningCode = 'connector_capability_missing' | 'sampling_failed' | 'statistics_failed' | 'llm_unavailable' | 'embedding_unavailable' | 'scan_enrichment_backend_not_configured' | 'relationship_validation_failed' | 'relationship_llm_invalid_reference' | 'relationship_llm_proposal_failed' | 'credential_redacted' | 'enrichment_failed' | 'description_fallback_used' | 'constraint_discovery_unauthorized';
+type KtxScanWarningCode = 'connector_capability_missing' | 'sampling_failed' | 'statistics_failed' | 'llm_unavailable' | 'embedding_unavailable' | 'scan_enrichment_backend_not_configured' | 'relationship_validation_failed' | 'relationship_detection_partial' | 'enrichment_stage_skipped' | 'enrichment_stage_stale' | 'relationship_llm_invalid_reference' | 'relationship_llm_proposal_failed' | 'credential_redacted' | 'enrichment_failed' | 'enrichment_timeout' | 'description_fallback_used' | 'constraint_discovery_unauthorized' | 'object_introspection_failed';
 export interface KtxScanWarning {
     code: KtxScanWarningCode;
     message: string;

package/dist/context/scan/types.js

@@ -1,3 +1,5 @@
+/** Canonical scan-mode registry. Runtime validation derives its allowlist here. */
+export const KTX_SCAN_MODES = ['structural', 'relationships', 'enriched'];
 export function createKtxConnectorCapabilities(capabilities = {}) {
     return {
         structuralIntrospection: true,

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

@@ -1,3 +1,4 @@
+import { isSqlQueryableDriver } from '../connections/dialects.js';
 import { FEDERATED_CONNECTION_ID } from '../connections/federation.js';
 import { resolveRequiredConnectionId } from '../connections/resolve-connection.js';
 import { sqlAnalysisDialectForDriver } from '../sql-analysis/dialect.js';
@@ -43,6 +44,10 @@ export async function compileLocalSlQuery(project, options) {
     await options.onProgress?.({ progress: 0, message: 'Compiling query' });
     const connectionId = resolveLocalConnectionId(project, options.connectionId);
     const driver = project.config.connections[connectionId]?.driver;
+    if (!isSqlQueryableDriver(driver)) {
+        throw new Error(`Semantic-layer queries require a SQL warehouse connection; '${connectionId}' uses the non-SQL driver ` +
+            `'${driver ?? 'unknown'}'. MongoDB and other context-only sources are searchable and ingestable, not SL-queryable.`);
+    }
     const dialect = sqlAnalysisDialectForDriver(driver);
     const sources = await loadComputableSources(project, connectionId);
     await options.onProgress?.({ progress: 0.3, message: 'Generating SQL' });

package/dist/context/sl/pglite-sl-search-prototype.js

@@ -41,7 +41,7 @@ async function loadCandidates(project, input = {}) {
     const connectionIds = [
         ...new Set(listed.files
             .map((path) => path.split('/')[1])
-            .filter((connectionId) => typeof connectionId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId))),
+            .filter((connectionId) => typeof connectionId === 'string' && /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(connectionId))),
     ].sort();
     const candidates = [];
     for (const connectionId of connectionIds) {

package/dist/context/sl/semantic-layer.service.js

@@ -4,7 +4,7 @@ import { normalizeSemanticLayerDescriptions } from './description-normalization.
 import { isOverlaySource, resolvedSourceSchema, sourceDefinitionSchema, sourceOverlaySchema } from './schemas.js';
 import { isSlYamlPath, resolveSlSourceFile, slDeclaredSourceName, slSourceFilePath } from './source-files.js';
 const SL_DIR_PREFIX = 'semantic-layer';
-const CONNECTION_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+const CONNECTION_ID_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/;
 /** @internal */
 export class UnknownColumnOverrideError extends Error {
 }

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

@@ -38,6 +38,11 @@ export declare function slSourceNameForFile(path: string, content: string): stri
  * filename — wrong for human-renamed files, whose filename is not the name.
  */
 export declare function slDeclaredSourceName(content: string): string | null;
+/**
+ * Every standalone/overlay source file for a connection (excludes the `_schema/`
+ * manifest). The one listing entry points share so a file is visible to all.
+ */
+export declare function listSlSourceFiles(fileStore: Pick<KtxFileStorePort, 'listFiles' | 'readFile'>, connectionId: string): Promise<SlSourceFile[]>;
 /**
  * Find the standalone/overlay file that defines `sourceName` for a connection.
  * Returns null when no file declares the name (the source may still exist as a

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

@@ -31,7 +31,7 @@ export function assertSafeConnectionId(connectionId) {
     return assertSafePathToken('connection id', connectionId);
 }
 export function isSafeConnectionId(connectionId) {
-    return typeof connectionId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId);
+    return typeof connectionId === 'string' && /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/.test(connectionId);
 }
 export function sourceNameFromPath(path) {
     return (path
@@ -113,24 +113,30 @@ export function slDeclaredSourceName(content) {
     return typeof name === 'string' && name.length > 0 ? name : null;
 }
 /**
- * Find the standalone/overlay file that defines `sourceName` for a connection.
- * Returns null when no file declares the name (the source may still exist as a
- * manifest entry under `_schema/`). Throws when more than one file declares the
- * same name — that breaks the one-file-per-name invariant and must be repaired
- * by hand rather than silently picking one.
+ * Every standalone/overlay source file for a connection (excludes the `_schema/`
+ * manifest). The one listing entry points share so a file is visible to all.
  */
-export async function resolveSlSourceFile(fileStore, connectionId, sourceName) {
+export async function listSlSourceFiles(fileStore, connectionId) {
     const dir = `semantic-layer/${assertSafeConnectionId(connectionId)}`;
     const schemaDir = `${dir}/_schema`;
     const listed = await fileStore.listFiles(dir);
     const paths = listed.files.filter((file) => isSlYamlPath(file) && !file.startsWith(`${schemaDir}/`)).sort();
-    const matches = [];
+    const files = [];
     for (const path of paths) {
         const raw = await fileStore.readFile(path);
-        if (slSourceNameForFile(path, raw.content) === sourceName) {
-            matches.push({ path, content: raw.content });
-        }
+        files.push({ path, content: raw.content });
     }
+    return files;
+}
+/**
+ * Find the standalone/overlay file that defines `sourceName` for a connection.
+ * Returns null when no file declares the name (the source may still exist as a
+ * manifest entry under `_schema/`). Throws when more than one file declares the
+ * same name — that breaks the one-file-per-name invariant and must be repaired
+ * by hand rather than silently picking one.
+ */
+export async function resolveSlSourceFile(fileStore, connectionId, sourceName) {
+    const matches = (await listSlSourceFiles(fileStore, connectionId)).filter((file) => slSourceNameForFile(file.path, file.content) === sourceName);
     if (matches.length > 1) {
         throw new Error(`Multiple semantic-layer files declare source "${sourceName}": ${matches.map((match) => match.path).join(', ')}`);
     }

package/dist/context/sl/tools/connection-id-schema.js

@@ -2,4 +2,4 @@ import { z } from 'zod';
 export const slToolConnectionIdSchema = z
     .string()
     .min(1)
-    .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/, 'Connection id must be alphanumeric and may contain _ or -');
+    .regex(/^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/, 'Connection id must be alphanumeric and may contain _ or -');

package/dist/context/sql-analysis/dialect-notes.d.ts

@@ -0,0 +1,9 @@
+import type { SqlAnalysisDialect } from './ports.js';
+/** @internal Dialects with an authored ./dialects/<dialect>.md file. */
+export declare const DIALECTS_WITH_NOTES: readonly ["postgres", "mysql", "snowflake", "bigquery", "sqlite", "clickhouse", "tsql"];
+/**
+ * SQL syntax notes for a resolved dialect. Falls back to `postgres` — the
+ * resolver's own default for unrecognized drivers — so any SQL connection yields
+ * usable guidance rather than an empty string.
+ */
+export declare function sqlDialectNotes(dialect: SqlAnalysisDialect): string;

package/dist/context/sql-analysis/dialect-notes.js

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// Per-engine SQL syntax notes live as markdown files under ./dialects (one per
+// dialect), served by the sql_dialect_notes MCP tool. They are package-internal:
+// copy-runtime-assets.mjs ships them to dist, and they are never installed onto an
+// agent target. The set covers every dialect reachable from a configured warehouse
+// driver; duckdb/databricks are intentionally absent because no connector produces
+// them.
+/** @internal Dialects with an authored ./dialects/<dialect>.md file. */
+export const DIALECTS_WITH_NOTES = [
+    'postgres',
+    'mysql',
+    'snowflake',
+    'bigquery',
+    'sqlite',
+    'clickhouse',
+    'tsql',
+];
+const notesCache = new Map();
+function readDialectNotes(dialect) {
+    const cached = notesCache.get(dialect);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const path = fileURLToPath(new URL(`./dialects/${dialect}.md`, import.meta.url));
+    const content = readFileSync(path, 'utf-8').trimEnd();
+    notesCache.set(dialect, content);
+    return content;
+}
+function hasNotes(dialect) {
+    return DIALECTS_WITH_NOTES.includes(dialect);
+}
+/**
+ * SQL syntax notes for a resolved dialect. Falls back to `postgres` — the
+ * resolver's own default for unrecognized drivers — so any SQL connection yields
+ * usable guidance rather than an empty string.
+ */
+export function sqlDialectNotes(dialect) {
+    return readDialectNotes(hasNotes(dialect) ? dialect : 'postgres');
+}

package/dist/context/sql-analysis/dialects/bigquery.md

@@ -0,0 +1,13 @@
+**bigquery** SQL conventions:
+- **FQTN:** backtick-quoted `` `project.dataset.table` `` (e.g. `` `my-proj.analytics.orders` ``); backticks are required when a name contains a dash.
+- **Identifiers:** backtick to quote; column and field names are case-insensitive, dataset and table names are case-sensitive.
+- **Date/time:** `DATE_TRUNC(d, MONTH)`, `EXTRACT(YEAR FROM ts)`, `PARSE_DATE('%Y-%m-%d', s)`, `FORMAT_DATE('%Y-%m', d)`, `CURRENT_DATE()`.
+- **Series:** build a spine with `UNNEST(GENERATE_DATE_ARRAY('2023-01-01', '2023-12-01', INTERVAL 1 MONTH))` for dates (or `GENERATE_ARRAY(1, n)` for integers), then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** `RANGE` frames are numeric, so range over an integer day key — `AVG(amount) OVER (ORDER BY UNIX_DATE(day) RANGE BETWEEN 29 PRECEDING AND CURRENT ROW)` is a trailing 30-day average that tolerates gaps; or build a spine (see **Series**) and use a `ROWS` frame.
+- **Safe cast:** `SAFE_CAST(x AS FLOAT64)` (or `SAFE_CAST(x AS NUMERIC)`) returns `NULL` instead of erroring on a value that does not parse, so counting residual `NULL`s among non-sentinel rows catches an encoding the sample missed.
+- **Safe divide:** `SAFE_DIVIDE(num, den)` returns `NULL` instead of erroring when the denominator is `0`, so a rate/ratio/share is one expression with no `CASE den = 0` guard; multiply by `100` for a percentage. Prefer it over `num / den` for any computed measure whose denominator can be zero.
+- **Top-N / windows:** `QUALIFY` filters on a window result, e.g. `QUALIFY ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) = 1`.
+- **JSON:** `JSON_VALUE(col, '$.k')` returns a scalar STRING, `JSON_QUERY(col, '$.k')` returns a subtree.
+- **Nested & repeated data (ARRAY / STRUCT):** the defining BigQuery shape (e.g. GA360 `ga_sessions.hits`, GA4 `event_params`/`user_properties`). Flatten a repeated column by cross-joining `UNNEST` correlated to its row — `FROM t, UNNEST(t.hits) AS h, UNNEST(h.product) AS p` — and read STRUCT fields with dot notation (`h.page.pagePath`, `p.productRevenue`). Pull one value out of a key-value parameter array with a scalar subquery: `(SELECT ep.value.int_value FROM UNNEST(event_params) AS ep WHERE ep.key = 'page_view')`. An `UNNEST` multiplies the parent row by the array's length, so a `COUNT(*)`/`SUM` after it double-counts the parent — count the parent key with `COUNT(DISTINCT visitId)` (or aggregate *inside* the unnest); use `LEFT JOIN UNNEST(arr)` to keep rows whose array is empty.
+- **Geospatial (GEOGRAPHY):** build a point with `ST_GEOGPOINT(longitude, latitude)` — **longitude first** — or parse text with `ST_GEOGFROMTEXT(wkt)` / `ST_GEOGFROMGEOJSON(s)`. Predicates: containment `ST_CONTAINS(area, pt)` / `ST_WITHIN(pt, area)` (`ST_WITHIN(a,b)=ST_CONTAINS(b,a)`); proximity `ST_DWITHIN(g1, g2, meters)` (geodesic); distance `ST_DISTANCE(g1, g2)` (meters); overlap `ST_INTERSECTS`. For areal allocation use `ST_AREA(g)` (m²) and `ST_AREA(ST_INTERSECTION(a, b))` for the overlapping area. Prefer these predicates over hand-rolled lat/lon `BETWEEN` boxes.
+- **Sharded tables:** query a wildcard table `` `dataset.events_*` `` and filter the shard with the `_TABLE_SUFFIX` pseudo-column, e.g. `WHERE _TABLE_SUFFIX BETWEEN '20240101' AND '20240131'`. The wildcard spans only the shards that exist — before a measure that pins specific dates/periods, confirm the matching shards are actually present (an absent endpoint silently yields no rows, not an error).

package/dist/context/sql-analysis/dialects/clickhouse.md

@@ -0,0 +1,9 @@
+**clickhouse** SQL conventions:
+- **FQTN:** `database.table` (e.g. `analytics.orders`).
+- **Identifiers:** quote with backticks (`` `Order` ``) or double quotes; identifiers are case-sensitive.
+- **Date/time:** native `Date`/`DateTime` types. Bucket with `toStartOfMonth(ts)`, `toStartOfDay(ts)`, `toYYYYMM(ts)`; parse with `toDate(s)` / `parseDateTimeBestEffort(s)`; format with `formatDateTime(ts, '%Y-%m')`.
+- **Series:** `numbers(n)` / `range(n)` generate an integer sequence; offset a start date with `addMonths(toDate('2023-01-01'), number)` (or `arrayJoin`) to form a spine, then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** a numeric range frame over a `Date` column counts in days and tolerates gaps — `AVG(amount) OVER (ORDER BY day RANGE BETWEEN 29 PRECEDING AND CURRENT ROW)` is a trailing 30-day average (use seconds for a `DateTime` key; the `INTERVAL` form is unsupported); or build a spine (see **Series**) and use a `ROWS` frame.
+- **Safe cast:** `toFloat64OrNull(x)` / `toDecimal64OrNull(x, s)` returns `NULL` on a value that does not parse (the `...OrZero` variants return `0` instead), so counting residual `NULL`s among non-sentinel rows catches an encoding the sample missed.
+- **Top-N / windows:** use the `LIMIT n BY key` clause for n rows per key, or rank in a CTE with `ROW_NUMBER() OVER (...)` and filter outside it.
+- **JSON:** extract from a String column with `JSONExtractString(col, 'k')`, `JSONExtractInt(col, 'k')`, etc.; a native `JSON`-typed column is traversed by dot path `col.k`.

package/dist/context/sql-analysis/dialects/mysql.md

@@ -0,0 +1,9 @@
+**mysql** SQL conventions:
+- **FQTN:** `database.table` (MySQL has no separate schema layer — a schema is a database).
+- **Identifiers:** quote with backticks (`` `order` ``); table-name case-sensitivity follows the server filesystem, while column names are case-insensitive.
+- **Date/time:** `DATE_FORMAT(ts, '%Y-%m')`, `STR_TO_DATE(s, fmt)`, `YEAR(ts)`/`MONTH(ts)`, `CURDATE()`, `NOW()`.
+- **Series:** no series function — build a spine with a recursive CTE, e.g. `WITH RECURSIVE months(d) AS (SELECT '2023-01-01' UNION ALL SELECT DATE_ADD(d, INTERVAL 1 MONTH) FROM months WHERE d < '2023-12-01')`, then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** a native interval range frame over a temporal order key tolerates gaps — `AVG(amount) OVER (ORDER BY day RANGE BETWEEN INTERVAL 29 DAY PRECEDING AND CURRENT ROW)` is a trailing 30-day average without a spine; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Safe cast:** MySQL has no `TRY_CAST`, and `CAST('abc' AS DECIMAL)` returns `0` with a warning rather than erroring — guard with a pattern test first: `CASE WHEN x REGEXP '^-?[0-9.]+$' THEN CAST(x AS DECIMAL(18,4)) END` makes a value that does not parse `NULL`, so a residual-`NULL` count catches an encoding the sample missed (`REGEXP_REPLACE` can strip symbols).
+- **Top-N / windows:** rank in a CTE with `ROW_NUMBER() OVER (...)` and filter outside it; use `ORDER BY ... LIMIT n` for a global top-N.
+- **JSON:** `JSON_EXTRACT(col, '$.k')`, or the `col->'$.k'` / `col->>'$.k'` shortcuts (`->>` unquotes to text).

package/dist/context/sql-analysis/dialects/postgres.md

@@ -0,0 +1,10 @@
+**postgres** SQL conventions:
+- **FQTN:** `schema.table` (e.g. `public.orders`); one query targets a single database, so qualify by schema, not by database.
+- **Identifiers:** unquoted names fold to lower-case; double-quote (`"Name"`) only to keep case or use a reserved word.
+- **Date/time:** `date_trunc('month', ts)`, `EXTRACT(YEAR FROM ts)`, `to_char(ts, 'YYYY-MM')`, `CURRENT_DATE`; cast text to a date with `col::date`.
+- **Series:** build a date/number spine with `generate_series('2023-01-01'::date, '2023-12-01'::date, interval '1 month')` (or `generate_series(1, n)` for integers), then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** a native calendar-range frame spans real dates and tolerates gaps — `AVG(amount) OVER (ORDER BY day RANGE BETWEEN INTERVAL '29 days' PRECEDING AND CURRENT ROW)` is a trailing 30-day average without a spine; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Integer division:** `/` between two integers truncates (`5 / 2` → `2`), so a rate or `SUM(a) / COUNT(*)` silently floors to an integer; cast one operand first — `a::numeric / b` or `a * 1.0 / b` — and round only in the final projection.
+- **Safe cast:** postgres has no `TRY_CAST`; guard a text-encoded number with a pattern test before casting — `CASE WHEN x ~ '^-?[0-9.]+$' THEN x::numeric END` yields `NULL` for a value that does not parse, so counting residual `NULL`s among non-sentinel rows catches an encoding the sample missed (`regexp_replace` can strip symbols, but chained `REPLACE` is the portable default).
+- **Top-N / windows:** rank in a CTE with `ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...)` and filter in the outer query, or use `DISTINCT ON (key) ... ORDER BY key, ...` for one row per key.
+- **JSON:** `col->'k'` returns json, `col->>'k'` returns text, deep path `col#>>'{a,b}'`; prefer `jsonb` operators on `jsonb` columns.

package/dist/context/sql-analysis/dialects/snowflake.md

@@ -0,0 +1,10 @@
+**snowflake** SQL conventions:
+- **FQTN:** three-part `DATABASE.SCHEMA.TABLE` (e.g. `analytics.public.orders`).
+- **Identifiers:** unquoted names fold to UPPER-case; double-quote for a case-sensitive or reserved name — `orders` resolves to `"ORDERS"`, which is a different object from `"orders"`.
+- **Date/time:** `DATE_TRUNC('month', ts)`, `TO_DATE(s[, fmt])`, `DATEADD(day, -7, CURRENT_DATE)`, `CURRENT_DATE`.
+- **Series:** generate rows with `TABLE(GENERATOR(ROWCOUNT => n))` and offset a start date via `DATEADD('month', SEQ4(), '2023-01-01')` (or a recursive CTE) to form a spine, then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** a native interval range frame over a date/timestamp order key tolerates gaps — `AVG(amount) OVER (ORDER BY day RANGE BETWEEN INTERVAL '29 days' PRECEDING AND CURRENT ROW)` is a trailing 30-day average without a spine; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Safe cast:** `TRY_TO_NUMBER(x)` / `TRY_TO_DECIMAL(x, p, s)` (or `TRY_CAST(x AS NUMBER)`) returns `NULL` instead of erroring on a value that does not parse, so a residual-`NULL` count among non-sentinel rows catches an encoding the sample missed.
+- **Top-N / windows:** `QUALIFY` filters on a window result without a subquery, e.g. `QUALIFY ROW_NUMBER() OVER (PARTITION BY ... ORDER BY ...) = 1`.
+- **Semi-structured (VARIANT):** traverse with a colon path and cast with `::`, e.g. `src:vehicle[0].make::string`, `payload:events.date::date`; expand arrays with `LATERAL FLATTEN`.
+- **Geospatial (GEOGRAPHY):** build a point with `ST_MAKEPOINT(longitude, latitude)` — **longitude first** — or `TO_GEOGRAPHY(wkt_or_geojson)`; an area polygon from a closed ring of corner points with `ST_MAKEPOLYGON(ST_MAKELINE(ARRAY_CONSTRUCT(p1, p2, …, p1)))` (repeat the first point last to close). Predicates: proximity `ST_DWITHIN(g1, g2, meters)` (geodesic) and distance `ST_DISTANCE(g1, g2)` (meters); containment `ST_CONTAINS(area, pt)` / `ST_WITHIN(pt, area)` where `ST_WITHIN(a,b)=ST_CONTAINS(b,a)`; overlap `ST_INTERSECTS`. Prefer these predicates over hand-rolled lat/lon `BETWEEN` boxes.

package/dist/context/sql-analysis/dialects/sqlite.md

@@ -0,0 +1,11 @@
+**sqlite** SQL conventions:
+- **FQTN:** usually the bare `table`; `main.table` to be explicit, `attached.table` for an attached database.
+- **Identifiers:** case-insensitive; double-quote (`"Name"`) to preserve a name with spaces or a keyword.
+- **Date/time:** there is no native date type — values are TEXT, INTEGER, or REAL. Format and bucket with `strftime('%Y-%m', col)`, `date(col)`, `datetime(col)`, and take day differences with `julianday(a) - julianday(b)`. Confirm the stored encoding (ISO text vs Unix epoch) before comparing.
+- **Series:** no series function — build a spine with a recursive CTE, e.g. `WITH RECURSIVE months(d) AS (SELECT '2023-01-01' UNION ALL SELECT date(d, '+1 month') FROM months WHERE d < '2023-12-01')`, then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** there is no date-interval range frame (a `RANGE` offset needs a single numeric order key, and dates are TEXT), so build a gap-free date spine (see **Series**) and use a row frame — `AVG(amount) OVER (ORDER BY day ROWS BETWEEN 29 PRECEDING AND CURRENT ROW)` then equals a trailing 30-day average; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Integer division:** `/` between two integers truncates (`5 / 2` → `2`), so a rate or `SUM(a) / COUNT(*)` silently floors to an integer; force real division with `a * 1.0 / b` (or `CAST(a AS REAL) / b`) and round only in the final projection.
+- **Safe cast:** sqlite has no failure-signaling cast — `CAST('abc' AS REAL)` returns `0.0` and `CAST('12abc' AS REAL)` returns `12.0` (no error, no `NULL`), so an `IS NULL` coverage check silently passes. Detect a value that did not parse with a pattern guard before casting, e.g. `CASE WHEN cleaned NOT GLOB '*[^0-9.]*' THEN CAST(cleaned AS REAL) END` (strip any leading sign first), then count the residual `NULL`s.
+- **Rounding (exact half-up at `.5` boundaries):** `ROUND(x, n)` rounds half-away-from-zero, but binary floating-point stores an exact half-way value just *below* it, so the round goes the wrong way — `ROUND(6.475, 2)` returns `6.47`, not `6.48`. When a rounded measure must match exact half-up (a displayed average, rate, or price), nudge by a tiny epsilon below display precision before rounding: `ROUND(x + 1e-9, n)` lifts `6.4749999…` back to `6.475` so it rounds to `6.48` (it leaves non-boundary values unchanged). Round once, at full precision, in the final projection — never in intermediate CTEs.
+- **Top-N / windows:** rank in a CTE with `ROW_NUMBER() OVER (...)` and filter in the outer query; use `ORDER BY ... LIMIT n` for a global top-N.
+- **JSON:** `json_extract(col, '$.k')`, or the `col->'$.k'` / `col->>'$.k'` operators (`->>` returns text).

package/dist/context/sql-analysis/dialects/tsql.md

@@ -0,0 +1,10 @@
+**tsql** (SQL Server) SQL conventions:
+- **FQTN:** `schema.table` (e.g. `dbo.orders`), or `database.schema.table` across databases.
+- **Identifiers:** quote with square brackets (`[Order]`), or double quotes when `QUOTED_IDENTIFIER` is on; case-sensitivity is set by the database collation (commonly case-insensitive).
+- **Date/time:** `DATEPART(year, ts)`, `DATEADD(day, -7, ts)`, `DATEDIFF(day, a, b)`, `CONVERT(date, ts)`, `FORMAT(ts, 'yyyy-MM')`, `GETDATE()`.
+- **Series:** no series function — build a spine with a recursive CTE, e.g. `WITH months AS (SELECT CAST('2023-01-01' AS date) AS d UNION ALL SELECT DATEADD(month, 1, d) FROM months WHERE d < '2023-12-01')` (cap with `OPTION (MAXRECURSION 0)`), or a numbers/tally table, then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** `RANGE` supports only `UNBOUNDED`/`CURRENT ROW` (no offset frame), so build a gap-free date spine (see **Series**) and use a row frame — `AVG(amount) OVER (ORDER BY day ROWS BETWEEN 29 PRECEDING AND CURRENT ROW)` — or a date-keyed self-join on `f.day BETWEEN DATEADD(day, -29, d.day) AND d.day`; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Integer division:** `/` between two `int`s truncates (`5 / 2` → `2`), so a rate or `SUM(a) / COUNT(*)` silently floors to an integer; cast one operand first — `CAST(a AS decimal(18,4)) / b` or `a * 1.0 / b` — and round only in the final projection.
+- **Safe cast:** `TRY_CAST(x AS DECIMAL(18,4))` (or `TRY_CONVERT(decimal(18,4), x)`) returns `NULL` instead of erroring on a value that does not parse, so a residual-`NULL` count among non-sentinel rows catches an encoding the sample missed.
+- **Top-N / windows:** `SELECT TOP (n) ... ORDER BY ...` for a global top-N; for per-group, rank in a CTE with `ROW_NUMBER() OVER (...)` and filter in the outer query.
+- **JSON:** `JSON_VALUE(col, '$.k')` returns a scalar, `JSON_QUERY(col, '$.k')` returns an object/array, and `OPENJSON(col)` shreds JSON into rows.

package/dist/context/wiki/keys.js

@@ -1,4 +1,4 @@
-const FLAT_WIKI_KEY_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+const FLAT_WIKI_KEY_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/;
 export function suggestFlatWikiKey(key) {
     const suggested = key
         .trim()

package/dist/context/wiki/knowledge-wiki.service.d.ts

@@ -1,5 +1,5 @@
 import type { KtxEmbeddingPort } from '../../context/core/embedding.js';
-import type { KtxFileStorePort } from '../../context/core/file-store.js';
+import type { KtxFileStorePort, KtxFileWriteResult } from '../../context/core/file-store.js';
 import type { KtxLogger } from '../../context/core/config.js';
 import type { ReindexWorkResult } from '../index-sync/types.js';
 import type { KnowledgeGitDiffPort, KnowledgeIndexPort } from './ports.js';
@@ -31,9 +31,9 @@ export declare class KnowledgeWikiService {
     serializePage(frontmatter: WikiFrontmatter, content: string): string;
     writePage(scope: string, scopeId: string | null | undefined, pageKey: string, frontmatter: WikiFrontmatter, content: string, author: string, authorEmail: string, commitMessage?: string, options?: {
         skipLock?: boolean;
-    }): Promise<import("../../context/core/file-store.js").KtxFileWriteResult>;
+    }): Promise<KtxFileWriteResult>;
     readPage(scope: string, scopeId: string | null | undefined, pageKey: string): Promise<WikiPage | null>;
-    deletePage(scope: string, scopeId: string | null | undefined, pageKey: string, author: string, authorEmail: string): Promise<import("../../context/core/file-store.js").KtxFileWriteResult | null>;
+    deletePage(scope: string, scopeId: string | null | undefined, pageKey: string, author: string, authorEmail: string): Promise<KtxFileWriteResult | null>;
     listPageKeys(scope: string, scopeId?: string | null): Promise<string[]>;
     getPageHistory(scope: string, scopeId: string | null | undefined, pageKey: string): Promise<unknown>;
     readPageForUser(userId: string, pageKey: string): Promise<WikiPageWithScope | null>;
@@ -49,7 +49,7 @@ export declare class KnowledgeWikiService {
      * Write a wiki page and then sync it to the DB search index.
      * Chains the two operations so the index is only updated after the file write succeeds.
      */
-    writePageAndSync(scope: string, scopeId: string | null | undefined, pageKey: string, frontmatter: WikiFrontmatter, content: string, author: string, authorEmail: string, commitMessage?: string): Promise<void>;
+    writePageAndSync(scope: string, scopeId: string | null | undefined, pageKey: string, frontmatter: WikiFrontmatter, content: string, author: string, authorEmail: string, commitMessage?: string): Promise<KtxFileWriteResult>;
     /**
      * Sync a single page to the DB search index after a write.
      * Computes search_text and embedding, then upserts to knowledge index.

package/dist/context/wiki/knowledge-wiki.service.js

@@ -166,10 +166,11 @@ export class KnowledgeWikiService {
      * Chains the two operations so the index is only updated after the file write succeeds.
      */
     async writePageAndSync(scope, scopeId, pageKey, frontmatter, content, author, authorEmail, commitMessage) {
-        await this.writePage(scope, scopeId, pageKey, frontmatter, content, author, authorEmail, commitMessage);
+        const writeResult = await this.writePage(scope, scopeId, pageKey, frontmatter, content, author, authorEmail, commitMessage);
         const serialized = this.serializePage(frontmatter, content);
         const contentHash = createHash('sha256').update(serialized).digest('hex');
         await this.syncSinglePage(scope, scopeId, pageKey, frontmatter, content, contentHash);
+        return writeResult;
     }
     // ── Index sync (files → DB) ───────────────────────────────────
     /**

package/dist/context/wiki/local-knowledge.d.ts

@@ -12,6 +12,7 @@ export interface LocalKnowledgePage {
     tags: string[];
     refs: string[];
     slRefs: string[];
+    connections: string[];
 }
 export interface LocalKnowledgeSummary {
     key: string;
@@ -40,6 +41,7 @@ export interface WriteLocalKnowledgePageInput {
     representativeSql?: string;
     usage?: HistoricSqlWikiUsageFrontmatter;
     fingerprints?: string[];
+    connections?: string[];
 }
 /** @internal */
 export declare function writeLocalKnowledgePage(project: KtxLocalProject, input: WriteLocalKnowledgePageInput): Promise<KtxFileWriteResult>;
@@ -49,6 +51,7 @@ export declare function readLocalKnowledgePage(project: KtxLocalProject, input:
 }): Promise<LocalKnowledgePage | null>;
 export declare function listLocalKnowledgePages(project: KtxLocalProject, input?: {
     userId?: string;
+    connectionId?: string;
 }): Promise<LocalKnowledgeSummary[]>;
 /**
  * List wiki page keys without reading or parsing file contents.
@@ -60,9 +63,19 @@ export declare function listLocalKnowledgePages(project: KtxLocalProject, input?
 export declare function listLocalKnowledgePageKeys(project: KtxLocalProject, input?: {
     userId?: string;
 }): Promise<string[]>;
+/**
+ * Connection ids referenced by any stored page's `connections` frontmatter,
+ * sorted and deduped. Derived from files; an id here that is not configured in
+ * `ktx.yaml` is a warn-only condition (config and content evolve independently)
+ * and never blocks loading, searching, or reading.
+ */
+export declare function listReferencedConnectionIds(project: KtxLocalProject, input?: {
+    userId?: string;
+}): Promise<string[]>;
 export declare function searchLocalKnowledgePages(project: KtxLocalProject, input: {
     query: string;
     userId?: string;
+    connectionId?: string;
     embeddingService?: KtxEmbeddingPort | null;
     limit?: number;
 }): Promise<LocalKnowledgeSearchResult[]>;

package/dist/context/wiki/local-knowledge.js

@@ -20,6 +20,17 @@ function assertSafePathToken(kind, value) {
 function stringArray(value) {
     return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
 }
+/** Coerce a YAML scalar or list into a string list — `connections` accepts a single id or a list. */
+function stringList(value) {
+    if (typeof value === 'string') {
+        return value.trim().length > 0 ? [value] : [];
+    }
+    return stringArray(value);
+}
+/** A page applies to `connectionId` when it is unscoped (empty) or lists that id. */
+function pageMatchesConnection(connections, connectionId) {
+    return connectionId === undefined || connections.length === 0 || connections.includes(connectionId);
+}
 function knowledgePath(scope, userId, key) {
     const safeKey = assertFlatWikiKey(key);
     if (scope === 'GLOBAL') {
@@ -47,6 +58,7 @@ function parseKnowledgePage(key, path, scope, raw) {
             tags: [],
             refs: [],
             slRefs: [],
+            connections: [],
         };
     }
     const frontmatter = (YAML.parse(match[1]) ?? {});
@@ -59,6 +71,7 @@ function parseKnowledgePage(key, path, scope, raw) {
         tags: stringArray(frontmatter.tags),
         refs: stringArray(frontmatter.refs),
         slRefs: stringArray(frontmatter.sl_refs),
+        connections: stringList(frontmatter.connections),
     };
 }
 function serializeKnowledgePage(input) {
@@ -74,6 +87,7 @@ function serializeKnowledgePage(input) {
         ...(input.representativeSql === undefined ? {} : { representative_sql: input.representativeSql }),
         ...(input.usage === undefined ? {} : { usage: input.usage }),
         ...(input.fingerprints === undefined ? {} : { fingerprints: input.fingerprints }),
+        ...(input.connections === undefined ? {} : { connections: input.connections }),
     };
     return `---\n${YAML.stringify(frontmatter, { indent: 2, lineWidth: 0 }).trimEnd()}\n---\n\n${input.content.trim()}\n`;
 }
@@ -111,7 +125,7 @@ export async function listLocalKnowledgePages(project, input = {}) {
                 continue;
             }
             const page = await readPageAtPath(project, key, path, scope);
-            if (page) {
+            if (page && pageMatchesConnection(page.connections, input.connectionId)) {
                 pages.push({ key, path, scope, summary: page.summary });
             }
         }
@@ -140,6 +154,22 @@ export async function listLocalKnowledgePageKeys(project, input = {}) {
     }
     return [...keys].sort();
 }
+/**
+ * Connection ids referenced by any stored page's `connections` frontmatter,
+ * sorted and deduped. Derived from files; an id here that is not configured in
+ * `ktx.yaml` is a warn-only condition (config and content evolve independently)
+ * and never blocks loading, searching, or reading.
+ */
+export async function listReferencedConnectionIds(project, input = {}) {
+    const pages = await loadAllKnowledgePages(project, { userId: input.userId });
+    const ids = new Set();
+    for (const page of pages) {
+        for (const id of page.connections) {
+            ids.add(id);
+        }
+    }
+    return [...ids].sort();
+}
 function scorePage(page, terms) {
     const haystack = buildKnowledgeSearchText(page.key, page.summary, page.content, page.tags).toLowerCase();
     return terms.some((term) => haystack.includes(term)) ? 3 : 0;
@@ -170,7 +200,10 @@ function tokenLaneCandidates(pages, terms) {
         .sort((left, right) => right.score - left.score || left.page.path.localeCompare(right.page.path));
 }
 async function loadAllKnowledgePages(project, input = {}) {
-    const summaries = await listLocalKnowledgePages(project, { userId: input.userId });
+    const summaries = await listLocalKnowledgePages(project, {
+        userId: input.userId,
+        connectionId: input.connectionId,
+    });
     const pages = [];
     for (const summary of summaries) {
         const page = await readPageAtPath(project, summary.key, summary.path, summary.scope);
@@ -181,8 +214,17 @@ async function loadAllKnowledgePages(project, input = {}) {
     return pages;
 }
 async function searchLocalKnowledgePagesWithSqlite(project, input) {
+    // The sqlite index is shared across connections and `index.sync` deletes any
+    // page not in its input, so sync the FULL corpus and apply the connection
+    // filter only to the candidate/result set (`allowedPaths`), never to sync.
     const pages = await loadAllKnowledgePages(project, { userId: input.userId });
-    const byPath = new Map(pages.map((page) => [page.path, page]));
+    const allowedPaths = new Set(pages.filter((page) => pageMatchesConnection(page.connections, input.connectionId)).map((page) => page.path));
+    const allowedPages = pages.filter((page) => allowedPaths.has(page.path));
+    // Scope the lexical/semantic lanes inside the query so their LIMIT applies to
+    // in-scope rows; only narrow when a connection is requested (otherwise every
+    // path is allowed and the filter is a no-op).
+    const scopedPaths = input.connectionId === undefined ? undefined : [...allowedPaths];
+    const byPath = new Map(allowedPages.map((page) => [page.path, page]));
     const embeddingService = input.embeddingService ?? null;
     const index = new SqliteKnowledgeIndex({ dbPath: sqliteKnowledgeDbPath(project) });
     const existingPages = index.getExistingPages();
@@ -204,7 +246,7 @@ async function searchLocalKnowledgePagesWithSqlite(project, input) {
         });
     }
     index.sync(indexPages);
-    const finalLimit = input.limit ?? Math.max(1, indexPages.length);
+    const finalLimit = input.limit ?? Math.max(1, allowedPages.length);
     const core = new HybridSearchCore();
     const generators = [
         {
@@ -213,6 +255,7 @@ async function searchLocalKnowledgePagesWithSqlite(project, input) {
                 const rows = index.searchLexicalCandidates({
                     queryText: args.queryText,
                     limit: args.laneCandidatePoolLimit,
+                    allowedPaths: scopedPaths,
                 });
                 return {
                     candidates: rows.map((row) => ({ id: row.id, rank: row.rank, rawScore: row.rawScore })),
@@ -222,7 +265,7 @@ async function searchLocalKnowledgePagesWithSqlite(project, input) {
         {
             lane: 'token',
             async generate(args) {
-                const rows = tokenLaneCandidates(pages, args.normalizedQuery.terms).slice(0, args.laneCandidatePoolLimit);
+                const rows = tokenLaneCandidates(allowedPages, args.normalizedQuery.terms).slice(0, args.laneCandidatePoolLimit);
                 return {
                     candidates: rows.map((row, index) => ({
                         id: row.page.path,
@@ -244,6 +287,7 @@ async function searchLocalKnowledgePagesWithSqlite(project, input) {
                     const rows = index.searchSemanticCandidates({
                         queryEmbedding,
                         limit: args.laneCandidatePoolLimit,
+                        allowedPaths: scopedPaths,
                     });
                     return {
                         candidates: rows
@@ -285,7 +329,7 @@ async function searchLocalKnowledgePagesWithScan(project, input) {
         .split(/\s+/)
         .map((term) => term.trim())
         .filter(Boolean);
-    const pages = await loadAllKnowledgePages(project, { userId: input.userId });
+    const pages = await loadAllKnowledgePages(project, { userId: input.userId, connectionId: input.connectionId });
     const results = [];
     for (const page of pages) {
         const score = scorePage(page, terms);

package/dist/context/wiki/sqlite-knowledge-index.d.ts

@@ -36,10 +36,12 @@ export declare class SqliteKnowledgeIndex {
     searchLexicalCandidates(input: {
         queryText: string;
         limit: number;
+        allowedPaths?: readonly string[];
     }): WikiSqliteLaneCandidate[];
     searchSemanticCandidates(input: {
         queryEmbedding: number[];
         limit: number;
+        allowedPaths?: readonly string[];
     }): WikiSqliteLaneCandidate[];
     search(query: string, limit: number): SqliteKnowledgeIndexSearchResult[];
     private pathForPage;

package/dist/context/wiki/sqlite-knowledge-index.js

@@ -38,6 +38,17 @@ function parseEmbedding(raw) {
         return null;
     }
 }
+/** A provided-but-empty allowlist means "no page is in scope", distinct from an absent (unfiltered) one. */
+function isEmptyAllowlist(allowedPaths) {
+    return allowedPaths !== undefined && allowedPaths.length === 0;
+}
+/** Build a `<keyword> path IN (?, …)` fragment so the scope filter applies inside the query, before any LIMIT. */
+function pathInClause(keyword, allowedPaths) {
+    if (allowedPaths === undefined || allowedPaths.length === 0) {
+        return { sql: '', params: [] };
+    }
+    return { sql: ` ${keyword} path IN (${allowedPaths.map(() => '?').join(', ')})`, params: [...allowedPaths] };
+}
 function normalizeFtsQuery(query) {
     const terms = query
         .toLowerCase()
@@ -156,18 +167,19 @@ export class SqliteKnowledgeIndex {
     }
     searchLexicalCandidates(input) {
         const ftsQuery = normalizeFtsQuery(input.queryText);
-        if (!ftsQuery) {
+        if (!ftsQuery || isEmptyAllowlist(input.allowedPaths)) {
             return [];
         }
+        const pathFilter = pathInClause('AND', input.allowedPaths);
         const rows = this.db
             .prepare(`
         SELECT path, bm25(knowledge_pages_fts) AS rank
         FROM knowledge_pages_fts
-        WHERE knowledge_pages_fts MATCH ?
+        WHERE knowledge_pages_fts MATCH ?${pathFilter.sql}
         ORDER BY rank ASC, path ASC
         LIMIT ?
       `)
-            .all(ftsQuery, Math.max(1, input.limit));
+            .all(ftsQuery, ...pathFilter.params, Math.max(1, input.limit));
         return rows.map((row, index) => ({
             id: row.path,
             path: row.path,
@@ -176,13 +188,17 @@ export class SqliteKnowledgeIndex {
         }));
     }
     searchSemanticCandidates(input) {
+        if (isEmptyAllowlist(input.allowedPaths)) {
+            return [];
+        }
+        const pathFilter = pathInClause('WHERE', input.allowedPaths);
         const rows = this.db
             .prepare(`
         SELECT path, embedding_json
-        FROM knowledge_pages
+        FROM knowledge_pages${pathFilter.sql}
         ORDER BY path ASC
       `)
-            .all();
+            .all(...pathFilter.params);
         return rows
             .flatMap((row) => {
             if (!row.embedding_json) {

package/dist/context/wiki/tools/wiki-write.tool.d.ts

@@ -15,6 +15,7 @@ declare const wikiWriteInputSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sl_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    connections: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     source: z.ZodOptional<z.ZodString>;
     intent: z.ZodOptional<z.ZodString>;
     tables: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -58,6 +59,7 @@ export declare class WikiWriteTool extends BaseTool<typeof wikiWriteInputSchema>
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         sl_refs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        connections: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
         source: z.ZodOptional<z.ZodString>;
         intent: z.ZodOptional<z.ZodString>;
         tables: z.ZodOptional<z.ZodArray<z.ZodString>>;