@kaelio/ktx 0.4.1 → 0.6.0

package/dist/context/connections/local-warehouse-descriptor.js

@@ -0,0 +1,70 @@
+const DRIVER_TO_CONNECTION_TYPE = {
+    postgres: 'POSTGRESQL',
+    sqlite: 'SQLITE',
+    sqlserver: 'SQLSERVER',
+    mysql: 'MYSQL',
+    clickhouse: 'CLICKHOUSE',
+    snowflake: 'SNOWFLAKE',
+    bigquery: 'BIGQUERY',
+};
+export function localConnectionToWarehouseDescriptor(id, connection) {
+    if (!connection) {
+        return null;
+    }
+    const connectionType = DRIVER_TO_CONNECTION_TYPE[String(connection.driver ?? '').toLowerCase()];
+    if (!connectionType) {
+        return null;
+    }
+    const info = {
+        id,
+        connection_type: connectionType,
+        connection_params: { ...connection },
+    };
+    const url = typeof connection.url === 'string' ? connection.url : null;
+    if (url && !url.startsWith('env:') && !url.startsWith('file:')) {
+        try {
+            const parsed = new URL(url);
+            info.host = parsed.hostname || null;
+            if (parsed.pathname.length > 1) {
+                const [first, second] = parsed.pathname.slice(1).split('/');
+                if (connectionType === 'BIGQUERY') {
+                    info.project_id = stringField(connection.project_id) ?? parsed.hostname ?? first ?? null;
+                    info.dataset_id = stringField(connection.dataset_id) ?? second ?? null;
+                }
+                else {
+                    info.database = first ?? null;
+                }
+            }
+        }
+        catch {
+            info.host = stringField(connection.host);
+        }
+    }
+    info.host = stringField(connection.host) ?? info.host ?? null;
+    info.database = stringField(connection.database) ?? info.database ?? null;
+    info.account = stringField(connection.account) ?? null;
+    info.project_id = stringField(connection.project_id) ?? info.project_id ?? null;
+    info.dataset_id = stringField(connection.dataset_id) ?? info.dataset_id ?? null;
+    return info;
+}
+export function localConnectionTypeForConfig(id, connection) {
+    const descriptor = localConnectionToWarehouseDescriptor(id, connection);
+    if (descriptor) {
+        return descriptor.connection_type;
+    }
+    const driver = typeof connection?.driver === 'string' ? connection.driver.trim() : '';
+    return driver.length > 0 ? driver : 'unknown';
+}
+export function localConnectionInfoFromConfig(id, connection) {
+    if (!connection) {
+        return null;
+    }
+    return {
+        id,
+        name: id,
+        connectionType: localConnectionTypeForConfig(id, connection),
+    };
+}
+function stringField(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}

package/dist/context/connections/notion-config.d.ts

@@ -0,0 +1,44 @@
+import { type NotionPullConfig } from '../ingest/adapters/notion/types.js';
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+declare const KTX_NOTION_ORG_KNOWLEDGE_WARNING = "Anything accessible to this Notion integration can become organization knowledge.";
+type KtxNotionCrawlMode = 'all_accessible' | 'selected_roots';
+type RawKtxNotionConnectionConfig = Extract<KtxProjectConnectionConfig, {
+    driver: 'notion';
+}>;
+export type KtxNotionConnectionConfig = Omit<RawKtxNotionConnectionConfig, 'auth_token' | 'auth_token_ref' | 'crawl_mode' | 'root_page_ids' | 'root_database_ids' | 'root_data_source_ids' | 'max_pages_per_run' | 'max_knowledge_creates_per_run' | 'max_knowledge_updates_per_run'> & {
+    driver: 'notion';
+    auth_token: string | null;
+    auth_token_ref: string | null;
+    crawl_mode: KtxNotionCrawlMode;
+    root_page_ids: string[];
+    root_database_ids: string[];
+    root_data_source_ids: string[];
+    max_pages_per_run: number;
+    max_knowledge_creates_per_run: number;
+    max_knowledge_updates_per_run: number;
+};
+/** @internal */
+export interface RedactedKtxNotionConnectionConfig {
+    driver: 'notion';
+    hasAuthToken: boolean;
+    crawlMode: KtxNotionCrawlMode;
+    rootPageIds: string[];
+    rootDatabaseIds: string[];
+    rootDataSourceIds: string[];
+    maxPagesPerRun: number;
+    maxKnowledgeCreatesPerRun: number;
+    maxKnowledgeUpdatesPerRun: number;
+    warning: typeof KTX_NOTION_ORG_KNOWLEDGE_WARNING;
+}
+interface ResolveNotionTokenOptions {
+    env?: Record<string, string | undefined>;
+    readTextFile?: (path: string) => Promise<string>;
+}
+export declare function parseNotionConnectionConfig(raw: unknown): KtxNotionConnectionConfig;
+/** @internal */
+export declare function redactNotionConnectionConfig(config: KtxNotionConnectionConfig): RedactedKtxNotionConnectionConfig;
+/** @internal */
+export declare function resolveNotionAuthToken(authTokenRef: string, options?: ResolveNotionTokenOptions): Promise<string>;
+export declare function resolveNotionConnectionAuthToken(config: Pick<KtxNotionConnectionConfig, 'auth_token' | 'auth_token_ref'>, options?: ResolveNotionTokenOptions): Promise<string>;
+export declare function notionConnectionToPullConfig(config: KtxNotionConnectionConfig, options?: ResolveNotionTokenOptions): Promise<NotionPullConfig>;
+export {};

package/dist/context/connections/notion-config.js

@@ -0,0 +1,134 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { NOTION_DEFAULT_MAX_KNOWLEDGE_CREATES_PER_RUN, notionPullConfigSchema, } from '../ingest/adapters/notion/types.js';
+const KTX_NOTION_ORG_KNOWLEDGE_WARNING = 'Anything accessible to this Notion integration can become organization knowledge.';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function record(value) {
+    if (!isRecord(value)) {
+        throw new Error('Notion connection config must be an object');
+    }
+    return value;
+}
+function stringValue(value, fallback) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function stringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+}
+function integerWithFallback(value, fallback, name) {
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new Error(`${name} must be an integer`);
+    }
+    return value;
+}
+function boundedInteger(value, fallback, name, min, max) {
+    const parsed = integerWithFallback(value, fallback, name);
+    if (parsed < min || parsed > max) {
+        throw new Error(`${name} must be between ${min} and ${max}`);
+    }
+    return parsed;
+}
+export function parseNotionConnectionConfig(raw) {
+    const input = record(raw);
+    if (input.driver !== 'notion') {
+        throw new Error('Notion connection config requires driver: notion');
+    }
+    const authToken = optionalString(input.auth_token);
+    const authTokenRef = optionalString(input.auth_token_ref);
+    if (!authToken && !authTokenRef) {
+        throw new Error('Notion connection config requires auth_token or auth_token_ref');
+    }
+    if (authTokenRef && !authTokenRef.startsWith('env:') && !authTokenRef.startsWith('file:')) {
+        throw new Error('Notion auth_token_ref must use env:NAME or file:/path');
+    }
+    const crawlMode = stringValue(input.crawl_mode, 'selected_roots');
+    if (crawlMode !== 'selected_roots' && crawlMode !== 'all_accessible') {
+        throw new Error(`Unsupported Notion crawl_mode: ${crawlMode}`);
+    }
+    const rootPageIds = stringArray(input.root_page_ids);
+    const rootDatabaseIds = stringArray(input.root_database_ids);
+    const rootDataSourceIds = stringArray(input.root_data_source_ids);
+    if (crawlMode === 'selected_roots' && rootPageIds.length + rootDatabaseIds.length + rootDataSourceIds.length === 0) {
+        throw new Error('selected_roots requires at least one root page, database, or data source id');
+    }
+    return {
+        driver: 'notion',
+        auth_token: authToken,
+        auth_token_ref: authTokenRef,
+        crawl_mode: crawlMode,
+        root_page_ids: rootPageIds,
+        root_database_ids: rootDatabaseIds,
+        root_data_source_ids: rootDataSourceIds,
+        max_pages_per_run: boundedInteger(input.max_pages_per_run, 1000, 'max_pages_per_run', 1, 10_000),
+        max_knowledge_creates_per_run: boundedInteger(input.max_knowledge_creates_per_run, NOTION_DEFAULT_MAX_KNOWLEDGE_CREATES_PER_RUN, 'max_knowledge_creates_per_run', 0, 25),
+        max_knowledge_updates_per_run: boundedInteger(input.max_knowledge_updates_per_run, 20, 'max_knowledge_updates_per_run', 0, 100),
+    };
+}
+/** @internal */
+export function redactNotionConnectionConfig(config) {
+    return {
+        driver: 'notion',
+        hasAuthToken: Boolean(config.auth_token ?? config.auth_token_ref),
+        crawlMode: config.crawl_mode,
+        rootPageIds: config.root_page_ids,
+        rootDatabaseIds: config.root_database_ids,
+        rootDataSourceIds: config.root_data_source_ids,
+        maxPagesPerRun: config.max_pages_per_run,
+        maxKnowledgeCreatesPerRun: config.max_knowledge_creates_per_run,
+        maxKnowledgeUpdatesPerRun: config.max_knowledge_updates_per_run,
+        warning: KTX_NOTION_ORG_KNOWLEDGE_WARNING,
+    };
+}
+function expandHome(path) {
+    return path === '~' || path.startsWith('~/') ? resolve(homedir(), path.slice(2)) : path;
+}
+/** @internal */
+export async function resolveNotionAuthToken(authTokenRef, options = {}) {
+    if (authTokenRef.startsWith('env:')) {
+        const envName = authTokenRef.slice('env:'.length);
+        const value = (options.env ?? process.env)[envName];
+        if (!value) {
+            throw new Error(`Notion token environment variable ${envName} is not set`);
+        }
+        return value.trim();
+    }
+    if (authTokenRef.startsWith('file:')) {
+        const path = expandHome(authTokenRef.slice('file:'.length));
+        const readTextFile = options.readTextFile ?? ((filePath) => readFile(filePath, 'utf-8'));
+        const value = (await readTextFile(path)).trim();
+        if (!value) {
+            throw new Error(`Notion token file is empty: ${path}`);
+        }
+        return value;
+    }
+    throw new Error('Notion auth_token_ref must use env:NAME or file:/path');
+}
+export async function resolveNotionConnectionAuthToken(config, options = {}) {
+    return config.auth_token ?? (await resolveNotionAuthToken(config.auth_token_ref ?? '', options));
+}
+export async function notionConnectionToPullConfig(config, options = {}) {
+    const authToken = await resolveNotionConnectionAuthToken(config, options);
+    return notionPullConfigSchema.parse({
+        authToken,
+        crawlMode: config.crawl_mode,
+        rootPageIds: config.root_page_ids,
+        rootDatabaseIds: config.root_database_ids,
+        rootDataSourceIds: config.root_data_source_ids,
+        maxPagesPerRun: config.max_pages_per_run,
+        maxKnowledgeCreatesPerRun: config.max_knowledge_creates_per_run,
+        maxKnowledgeUpdatesPerRun: config.max_knowledge_updates_per_run,
+        lastSuccessfulCursor: null,
+    });
+}

package/dist/context/connections/postgres-query-executor.js

@@ -0,0 +1,53 @@
+import { Client } from 'pg';
+import { limitSqlForExecution } from './read-only-sql.js';
+function connectionDriver(input) {
+    return String(input.connection?.driver ?? '').toLowerCase();
+}
+function createDefaultClient(config) {
+    return new Client(config);
+}
+export function createPostgresQueryExecutor(options = {}) {
+    const clientFactory = options.clientFactory ?? createDefaultClient;
+    return {
+        async execute(input) {
+            const driver = connectionDriver(input);
+            const connection = input.connection;
+            if (driver !== 'postgres') {
+                throw new Error(`Local Postgres execution cannot run driver "${connection?.driver ?? 'unknown'}".`);
+            }
+            if (typeof connection?.url !== 'string' || connection.url.trim().length === 0) {
+                throw new Error(`Local Postgres execution requires connections.${input.connectionId}.url.`);
+            }
+            const client = clientFactory({
+                connectionString: connection.url,
+                statement_timeout: options.statementTimeoutMs ?? 30_000,
+                query_timeout: options.queryTimeoutMs ?? 35_000,
+                connectionTimeoutMillis: options.connectionTimeoutMs ?? 5_000,
+                application_name: 'ktx-local-query',
+            });
+            await client.connect();
+            try {
+                await client.query('BEGIN READ ONLY');
+                const result = await client.query({
+                    text: limitSqlForExecution(input.sql, input.maxRows),
+                    rowMode: 'array',
+                });
+                await client.query('COMMIT');
+                return {
+                    headers: result.fields.map((field) => field.name),
+                    rows: result.rows,
+                    totalRows: result.rows.length,
+                    command: result.command,
+                    rowCount: result.rowCount,
+                };
+            }
+            catch (error) {
+                await client.query('ROLLBACK').catch(() => undefined);
+                throw error;
+            }
+            finally {
+                await client.end();
+            }
+        },
+    };
+}

package/dist/context/connections/query-executor.d.ts

@@ -0,0 +1,19 @@
+import type { KtxProjectConnectionConfig } from '../../context/project/config.js';
+export interface KtxSqlQueryExecutionInput {
+    connectionId: string;
+    projectDir?: string;
+    connection: KtxProjectConnectionConfig | undefined;
+    sql: string;
+    maxRows?: number;
+}
+export interface KtxSqlQueryExecutionResult {
+    headers: string[];
+    rows: unknown[][];
+    totalRows: number;
+    command: string;
+    rowCount: number | null;
+}
+export interface KtxSqlQueryExecutorPort {
+    execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult>;
+}
+export declare function normalizeQueryRows(rows: unknown[]): unknown[][];

package/dist/context/connections/sqlite-query-executor.d.ts

@@ -0,0 +1,4 @@
+import type { KtxSqlQueryExecutionInput, KtxSqlQueryExecutorPort } from './query-executor.js';
+/** @internal */
+export declare function sqliteDatabasePathFromConnection(input: KtxSqlQueryExecutionInput): string;
+export declare function createSqliteQueryExecutor(): KtxSqlQueryExecutorPort;

package/dist/context/connections/sqlite-query-executor.js

@@ -0,0 +1,74 @@
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Database from 'better-sqlite3';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { normalizeQueryRows } from './query-executor.js';
+import { limitSqlForExecution } from './read-only-sql.js';
+function connectionDriver(input) {
+    return String(input.connection?.driver ?? '').toLowerCase();
+}
+function stringConfigValue(connection, key) {
+    const value = connection?.[key];
+    return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(key, value.trim()) : undefined;
+}
+function resolveStringReference(key, value) {
+    if (value.startsWith('env:')) {
+        return process.env[value.slice('env:'.length)] ?? '';
+    }
+    if (key !== 'url' && value.startsWith('file:')) {
+        const rawPath = value.slice('file:'.length);
+        const path = rawPath.startsWith('~') ? resolve(homedir(), rawPath.slice(1)) : rawPath;
+        return readFileSync(path, 'utf-8').trim();
+    }
+    return value;
+}
+function sqlitePathFromUrl(url) {
+    if (url.startsWith('file:')) {
+        return fileURLToPath(url);
+    }
+    if (url.startsWith('sqlite:')) {
+        const parsed = new URL(url);
+        if (parsed.pathname.length > 0) {
+            return decodeURIComponent(parsed.pathname);
+        }
+    }
+    return url;
+}
+/** @internal */
+export function sqliteDatabasePathFromConnection(input) {
+    const driver = connectionDriver(input);
+    if (driver !== 'sqlite') {
+        throw new Error(`Local SQLite execution cannot run driver "${input.connection?.driver ?? 'unknown'}".`);
+    }
+    const pathValue = stringConfigValue(input.connection, 'path');
+    const urlValue = stringConfigValue(input.connection, 'url');
+    if (!pathValue && !urlValue) {
+        throw new Error(`Local SQLite execution requires connections.${input.connectionId}.path or connections.${input.connectionId}.url.`);
+    }
+    const candidate = pathValue ?? sqlitePathFromUrl(urlValue);
+    return isAbsolute(candidate) ? candidate : resolve(input.projectDir ?? process.cwd(), candidate);
+}
+export function createSqliteQueryExecutor() {
+    return {
+        async execute(input) {
+            const sql = limitSqlForExecution(input.sql, input.maxRows);
+            const dbPath = sqliteDatabasePathFromConnection(input);
+            const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+            try {
+                const statement = db.prepare(sql);
+                const rows = statement.all();
+                return {
+                    headers: statement.columns().map((column) => column.name),
+                    rows: normalizeQueryRows(rows),
+                    totalRows: rows.length,
+                    command: 'SELECT',
+                    rowCount: rows.length,
+                };
+            }
+            finally {
+                db.close();
+            }
+        },
+    };
+}

package/dist/context/core/config-reference.d.ts

@@ -0,0 +1,3 @@
+/** @internal */
+export declare function resolveKtxHomePath(path: string): string;
+export declare function resolveKtxConfigReference(value: string | undefined, env: NodeJS.ProcessEnv): string | undefined;

package/dist/context/core/config-reference.js

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/** @internal */
+export function resolveKtxHomePath(path) {
+    if (path === '~') {
+        return homedir();
+    }
+    if (path.startsWith('~/')) {
+        return resolve(homedir(), path.slice(2));
+    }
+    return resolve(path);
+}
+export function resolveKtxConfigReference(value, env) {
+    if (!value) {
+        return undefined;
+    }
+    if (value.startsWith('env:')) {
+        const envName = value.slice('env:'.length).trim();
+        const envValue = env[envName];
+        return envValue && envValue.trim().length > 0 ? envValue.trim() : undefined;
+    }
+    if (value.startsWith('file:')) {
+        const filePath = resolveKtxHomePath(value.slice('file:'.length).trim());
+        const fileValue = readFileSync(filePath, 'utf8').trim();
+        return fileValue.length > 0 ? fileValue : undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/dist/context/core/config.d.ts

@@ -0,0 +1,26 @@
+interface KtxStorageConfig {
+    configDir?: string;
+    homeDir?: string;
+    worktreesDir?: string;
+}
+interface KtxGitConfig {
+    userName: string;
+    userEmail: string;
+    bootstrapMessage?: string;
+    bootstrapAuthor?: string;
+    bootstrapAuthorEmail?: string;
+}
+export interface KtxCoreConfig {
+    storage: KtxStorageConfig;
+    git: KtxGitConfig;
+}
+export interface KtxLogger {
+    debug(message: string): void;
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: string, error?: unknown): void;
+}
+export declare const noopLogger: KtxLogger;
+export declare function resolveConfigDir(config: KtxCoreConfig): string;
+export declare function resolveWorktreesDir(config: KtxCoreConfig): string;
+export {};

package/dist/context/core/redaction.d.ts

@@ -0,0 +1,5 @@
+/** @internal */
+export declare const REDACTED_KTX_CREDENTIAL_VALUE = "<redacted>";
+export declare function redactKtxSensitiveValue(key: string, value: unknown): unknown;
+export declare function redactKtxSensitiveMetadata(metadata: Record<string, unknown>): Record<string, unknown>;
+export declare function redactKtxSensitiveText(value: string): string;

package/dist/context/core/redaction.js

@@ -0,0 +1,40 @@
+/** @internal */
+export const REDACTED_KTX_CREDENTIAL_VALUE = '<redacted>';
+const SENSITIVE_FIELD_NAME = /(password|secret|token|api[_-]?key|private[_-]?key|passphrase|credential|authorization|url)/i;
+const URL_CREDENTIAL_PATTERN = /([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)([^@\s/]+)(@)/gi;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSensitiveField(key) {
+    return SENSITIVE_FIELD_NAME.test(key);
+}
+export function redactKtxSensitiveValue(key, value) {
+    if (isSensitiveField(key)) {
+        return REDACTED_KTX_CREDENTIAL_VALUE;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactKtxSensitiveValue(key, item));
+    }
+    if (isRecord(value)) {
+        return redactKtxSensitiveMetadata(value);
+    }
+    return value;
+}
+export function redactKtxSensitiveMetadata(metadata) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (Array.isArray(value)) {
+            redacted[key] = value.map((item) => isRecord(item) ? redactKtxSensitiveMetadata(item) : redactKtxSensitiveValue(key, item));
+            continue;
+        }
+        if (isRecord(value)) {
+            redacted[key] = redactKtxSensitiveValue(key, value);
+            continue;
+        }
+        redacted[key] = redactKtxSensitiveValue(key, value);
+    }
+    return redacted;
+}
+export function redactKtxSensitiveText(value) {
+    return value.replace(URL_CREDENTIAL_PATTERN, `$1${REDACTED_KTX_CREDENTIAL_VALUE}$3`);
+}

package/dist/context/core/session-worktree.service.d.ts

@@ -0,0 +1,31 @@
+import { type KtxCoreConfig, type KtxLogger } from './config.js';
+import { GitService } from './git.service.js';
+export type SessionOutcome = 'success' | 'empty' | 'conflict' | 'crash';
+export interface WorktreeConfigPort<TConfig> {
+    forWorktree(workdir: string): TConfig;
+}
+export interface SessionWorktree<TConfig> {
+    chatId: string;
+    workdir: string;
+    branch: string;
+    baseSha: string;
+    createdAt: Date;
+    git: GitService;
+    config: TConfig;
+}
+export interface SessionWorktreeServiceDeps<TConfig extends WorktreeConfigPort<TConfig>> {
+    coreConfig: KtxCoreConfig;
+    gitService: GitService;
+    configService: TConfig;
+    logger?: KtxLogger;
+}
+export declare class SessionWorktreeService<TConfig extends WorktreeConfigPort<TConfig> = WorktreeConfigPort<never>> {
+    private readonly deps;
+    private readonly logger;
+    private readonly worktreesRoot;
+    constructor(deps: SessionWorktreeServiceDeps<TConfig>);
+    create(sessionKey: string, baseSha: string): Promise<SessionWorktree<TConfig>>;
+    cleanup(session: SessionWorktree<TConfig>, outcome: SessionOutcome, extra?: {
+        conflictPaths?: string[];
+    }): Promise<void>;
+}

package/dist/context/daemon/semantic-layer-compute.d.ts

@@ -0,0 +1,84 @@
+import type { ResolvedSemanticLayerSource, SemanticLayerQueryInput } from '../sl/types.js';
+interface KtxSemanticLayerComputeQueryResult {
+    sql: string;
+    dialect: string;
+    columns: Array<Record<string, unknown>>;
+    plan: Record<string, unknown>;
+}
+interface KtxSemanticLayerComputeValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    perSourceWarnings: Record<string, string[]>;
+}
+interface KtxSemanticLayerSourceGenerationColumnInput {
+    name: string;
+    type: string;
+    primaryKey?: boolean;
+    nullable?: boolean;
+    comment?: string | null;
+}
+interface KtxSemanticLayerSourceGenerationTableInput {
+    name: string;
+    catalog?: string | null;
+    db?: string | null;
+    comment?: string | null;
+    columns: KtxSemanticLayerSourceGenerationColumnInput[];
+}
+interface KtxSemanticLayerSourceGenerationLinkInput {
+    fromTable: string;
+    fromColumn: string;
+    toTable: string;
+    toColumn: string;
+    relationshipType: string;
+}
+interface KtxSemanticLayerSourceGenerationInput {
+    tables: KtxSemanticLayerSourceGenerationTableInput[];
+    links: KtxSemanticLayerSourceGenerationLinkInput[];
+    dialect?: string;
+}
+interface KtxSemanticLayerSourceGenerationResult {
+    sources: Array<Record<string, unknown>>;
+    sourceCount: number;
+}
+export interface KtxSemanticLayerComputePort {
+    /**
+     * Callers must pass sources sanitized through toResolvedWire. The Python
+     * daemon rejects authoring-only fields such as usage and inherits_columns_from.
+     */
+    query(input: {
+        sources: ResolvedSemanticLayerSource[];
+        query: SemanticLayerQueryInput;
+        dialect: string;
+    }): Promise<KtxSemanticLayerComputeQueryResult>;
+    /**
+     * Callers must pass sources sanitized through toResolvedWire. The Python
+     * daemon rejects authoring-only fields such as usage and inherits_columns_from.
+     */
+    validateSources(input: {
+        sources: ResolvedSemanticLayerSource[];
+        dialect: string;
+        recentlyTouched?: string[];
+    }): Promise<KtxSemanticLayerComputeValidationResult>;
+    generateSources(input: KtxSemanticLayerSourceGenerationInput): Promise<KtxSemanticLayerSourceGenerationResult>;
+}
+type KtxDaemonCommand = 'semantic-query' | 'semantic-validate' | 'semantic-generate-sources';
+type KtxDaemonJsonRunner = (subcommand: KtxDaemonCommand, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+type KtxDaemonHttpJsonRunner = (path: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export interface PythonSemanticLayerComputeOptions {
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    runJson?: KtxDaemonJsonRunner;
+    projectId?: string;
+}
+/** @internal */
+export interface HttpSemanticLayerComputeOptions {
+    baseUrl: string;
+    requestJson?: KtxDaemonHttpJsonRunner;
+}
+export declare function createPythonSemanticLayerComputePort(options?: PythonSemanticLayerComputeOptions): KtxSemanticLayerComputePort;
+/** @internal */
+export declare function createHttpSemanticLayerComputePort(options: HttpSemanticLayerComputeOptions): KtxSemanticLayerComputePort;
+export {};