@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/types.d.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+import type { SqlAnalysisPort } from '../../../sql-analysis/index.js';
+export declare const HISTORIC_SQL_SOURCE_KEY: "historic-sql";
+export declare const HISTORIC_SQL_OBJECT_TYPE: "historic_sql_template";
+declare const historicSqlDialectSchema: z.ZodEnum<{
+    postgres: "postgres";
+    bigquery: "bigquery";
+    snowflake: "snowflake";
+}>;
+export type HistoricSqlDialect = z.infer<typeof historicSqlDialectSchema>;
+export declare const historicSqlPullConfigSchema: z.ZodObject<{
+    dialect: z.ZodEnum<{
+        postgres: "postgres";
+        bigquery: "bigquery";
+        snowflake: "snowflake";
+    }>;
+    windowDays: z.ZodDefault<z.ZodNumber>;
+    lastSuccessfulCursor: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    serviceAccountUserPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    redactionPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    maxTemplatesPerRun: z.ZodDefault<z.ZodNumber>;
+    minCalls: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type HistoricSqlPullConfig = z.infer<typeof historicSqlPullConfigSchema>;
+export interface HistoricSqlTimeWindow {
+    start: Date;
+    end: Date;
+}
+export declare const historicSqlRawQueryRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    sql: z.ZodString;
+    user: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    runtimeMs: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    rowsProduced: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    success: z.ZodDefault<z.ZodBoolean>;
+    errorMessage: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type HistoricSqlRawQueryRow = z.infer<typeof historicSqlRawQueryRowSchema>;
+export interface HistoricSqlQueryHistoryReader {
+    probe(client: unknown): Promise<void>;
+    fetch(client: unknown, window: HistoricSqlTimeWindow, cursor?: string | null): AsyncIterable<HistoricSqlRawQueryRow>;
+}
+export interface KtxPostgresQueryClient {
+    executeQuery(sql: string, params?: unknown[]): Promise<{
+        headers: string[];
+        rows: unknown[][];
+        totalRows?: number;
+    }>;
+}
+export interface PostgresPgssProbeResult {
+    pgServerVersion: string;
+    warnings: string[];
+}
+export interface PostgresPgssSnapshot {
+    statsResetAt: string | null;
+    deallocCount: number | null;
+    rows: PostgresPgssRow[];
+}
+export interface PostgresPgssReader {
+    probe(client: KtxPostgresQueryClient): Promise<PostgresPgssProbeResult>;
+    readSnapshot(client: KtxPostgresQueryClient, options: {
+        minCalls: number;
+        maxTemplates: number;
+    }): Promise<PostgresPgssSnapshot>;
+}
+export interface PostgresPgssRow {
+    queryid: string;
+    userid: string;
+    username: string | null;
+    dbid: string;
+    database: string | null;
+    query: string;
+    calls: number;
+    totalExecTime: number;
+    meanExecTime: number;
+    totalRows: number;
+}
+export interface PostgresPgssAggregateRow {
+    id: string;
+    queryid: string;
+    dbid: string;
+    database: string | null;
+    query: string;
+    deltaCalls: number;
+    deltaExecTime: number;
+    deltaRows: number;
+    meanExecTime: number;
+    distinctUsersDelta: number;
+    users: string[];
+    firstObservedAt: string;
+}
+export interface HistoricSqlSourceAdapterDeps {
+    sqlAnalysis: SqlAnalysisPort;
+    reader: HistoricSqlQueryHistoryReader;
+    queryClient: unknown;
+    postgresReader?: PostgresPgssReader;
+    postgresQueryClient?: KtxPostgresQueryClient;
+    postgresBaselineRootDir?: string;
+    now?: () => Date;
+    onPullSucceeded?: (ctx: {
+        connectionId: string;
+        sourceKey: string;
+        syncId: string;
+        trigger: import('../../types.js').IngestTrigger;
+        completedAt: Date;
+        stagedDir: string;
+        nextSuccessfulCursor: string | null;
+    }) => Promise<void>;
+}
+declare const historicSqlLiteralSlotClassificationSchema: z.ZodEnum<{
+    categorical: "categorical";
+    constant: "constant";
+    runtime: "runtime";
+}>;
+export type HistoricSqlLiteralSlotClassification = z.infer<typeof historicSqlLiteralSlotClassificationSchema>;
+export declare const historicSqlMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    path: z.ZodString;
+    objectType: z.ZodLiteral<"historic_sql_template">;
+    lastEditedAt: z.ZodNull;
+    properties: z.ZodObject<{
+        fingerprint: z.ZodString;
+        sub_cluster_id: z.ZodNullable<z.ZodString>;
+        dialect: z.ZodEnum<{
+            postgres: "postgres";
+            bigquery: "bigquery";
+            snowflake: "snowflake";
+        }>;
+        tables_touched: z.ZodArray<z.ZodString>;
+        literal_slots: z.ZodArray<z.ZodObject<{
+            position: z.ZodNumber;
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                timestamp: "timestamp";
+                unknown: "unknown";
+                null: "null";
+            }>;
+            classification: z.ZodEnum<{
+                categorical: "categorical";
+                constant: "constant";
+                runtime: "runtime";
+            }>;
+        }, z.core.$strip>>;
+        triage_signals: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type HistoricSqlMetadata = z.infer<typeof historicSqlMetadataSchema>;
+export declare const historicSqlUsageSchema: z.ZodObject<{
+    stats: z.ZodObject<{
+        executions: z.ZodNumber;
+        distinct_users: z.ZodNumber;
+        first_seen: z.ZodString;
+        last_seen: z.ZodString;
+        p50_runtime_ms: z.ZodNullable<z.ZodNumber>;
+        p95_runtime_ms: z.ZodNullable<z.ZodNumber>;
+        mean_runtime_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        error_rate: z.ZodNumber;
+        rows_produced: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>;
+    literal_slots: z.ZodArray<z.ZodObject<{
+        position: z.ZodNumber;
+        distinct_values: z.ZodNumber;
+        top_values: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+    samples: z.ZodArray<z.ZodObject<{
+        started_at: z.ZodString;
+        user: z.ZodNullable<z.ZodString>;
+        bound_sql: z.ZodString;
+        rows_produced: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        runtime_ms: z.ZodNullable<z.ZodNumber>;
+        success: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type HistoricSqlUsage = z.infer<typeof historicSqlUsageSchema>;
+export declare const historicSqlManifestSchema: z.ZodObject<{
+    source: z.ZodLiteral<"historic-sql">;
+    connectionId: z.ZodString;
+    dialect: z.ZodEnum<{
+        postgres: "postgres";
+        bigquery: "bigquery";
+        snowflake: "snowflake";
+    }>;
+    fetchedAt: z.ZodString;
+    windowStart: z.ZodString;
+    windowEnd: z.ZodString;
+    nextSuccessfulCursor: z.ZodNullable<z.ZodString>;
+    templateCount: z.ZodNumber;
+    capped: z.ZodBoolean;
+    warnings: z.ZodArray<z.ZodString>;
+    degraded: z.ZodDefault<z.ZodBoolean>;
+    statsResetAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    baselineFirstRun: z.ZodDefault<z.ZodBoolean>;
+    pgServerVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    deallocCount: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    templates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        fingerprint: z.ZodString;
+        subClusterId: z.ZodNullable<z.ZodString>;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type HistoricSqlManifest = z.infer<typeof historicSqlManifestSchema>;
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/types.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+export const HISTORIC_SQL_SOURCE_KEY = 'historic-sql';
+export const HISTORIC_SQL_OBJECT_TYPE = 'historic_sql_template';
+const historicSqlDialectSchema = z.enum(['snowflake', 'bigquery', 'postgres']);
+export const historicSqlPullConfigSchema = z.object({
+    dialect: historicSqlDialectSchema,
+    windowDays: z.number().int().min(1).max(365).default(90),
+    lastSuccessfulCursor: z.string().datetime().nullable().default(null),
+    serviceAccountUserPatterns: z.array(z.string()).default([]),
+    redactionPatterns: z.array(z.string()).default([]),
+    maxTemplatesPerRun: z.number().int().min(1).max(5000).default(5000),
+    minCalls: z.number().int().min(1).default(5),
+});
+export const historicSqlRawQueryRowSchema = z.object({
+    id: z.string().min(1),
+    sql: z.string().min(1),
+    user: z.string().nullable().default(null),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable().default(null),
+    runtimeMs: z.number().nonnegative().nullable().default(null),
+    rowsProduced: z.number().int().nonnegative().nullable().optional(),
+    success: z.boolean().default(true),
+    errorMessage: z.string().nullable().default(null),
+});
+const historicSqlLiteralSlotClassificationSchema = z.enum(['constant', 'runtime', 'categorical']);
+export const historicSqlMetadataSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    path: z.string().min(1),
+    objectType: z.literal(HISTORIC_SQL_OBJECT_TYPE),
+    lastEditedAt: z.null(),
+    properties: z.object({
+        fingerprint: z.string().min(1),
+        sub_cluster_id: z.string().nullable(),
+        dialect: historicSqlDialectSchema,
+        tables_touched: z.array(z.string()),
+        literal_slots: z.array(z.object({
+            position: z.number().int().min(1),
+            type: z.enum(['string', 'number', 'timestamp', 'date', 'boolean', 'null', 'unknown']),
+            classification: historicSqlLiteralSlotClassificationSchema,
+        })),
+        triage_signals: z.record(z.string(), z.string()),
+    }),
+});
+export const historicSqlUsageSchema = z.object({
+    stats: z.object({
+        executions: z.number().int().nonnegative(),
+        distinct_users: z.number().int().nonnegative(),
+        first_seen: z.string().datetime(),
+        last_seen: z.string().datetime(),
+        p50_runtime_ms: z.number().nonnegative().nullable(),
+        p95_runtime_ms: z.number().nonnegative().nullable(),
+        mean_runtime_ms: z.number().nonnegative().nullable().optional(),
+        error_rate: z.number().min(0).max(1),
+        rows_produced: z.number().int().nonnegative().nullable().optional(),
+    }),
+    literal_slots: z.array(z.object({
+        position: z.number().int().min(1),
+        distinct_values: z.number().int().nonnegative(),
+        top_values: z.array(z.tuple([z.string(), z.number().int().nonnegative()])),
+    })),
+    samples: z.array(z.object({
+        started_at: z.string().datetime(),
+        user: z.string().nullable(),
+        bound_sql: z.string(),
+        rows_produced: z.number().int().nonnegative().nullable().optional(),
+        runtime_ms: z.number().nonnegative().nullable(),
+        success: z.boolean(),
+    })),
+});
+export const historicSqlManifestSchema = z.object({
+    source: z.literal(HISTORIC_SQL_SOURCE_KEY),
+    connectionId: z.string().min(1),
+    dialect: historicSqlDialectSchema,
+    fetchedAt: z.string().datetime(),
+    windowStart: z.string().datetime(),
+    windowEnd: z.string().datetime(),
+    nextSuccessfulCursor: z.string().datetime().nullable(),
+    templateCount: z.number().int().nonnegative(),
+    capped: z.boolean(),
+    warnings: z.array(z.string()),
+    degraded: z.boolean().default(false),
+    statsResetAt: z.string().datetime().nullable().default(null),
+    baselineFirstRun: z.boolean().default(false),
+    pgServerVersion: z.string().nullable().default(null),
+    deallocCount: z.number().int().nonnegative().nullable().default(null),
+    templates: z.array(z.object({
+        id: z.string().min(1),
+        fingerprint: z.string().min(1),
+        subClusterId: z.string().nullable(),
+        path: z.string().min(1),
+    })),
+});

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/chunk.d.ts

@@ -0,0 +1,2 @@
+import type { ChunkResult, DiffSet } from '../../types.js';
+export declare function chunkLiveDatabaseStagedDir(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/chunk.js

@@ -0,0 +1,44 @@
+import { LIVE_DATABASE_FOREIGN_KEYS_FILE, LIVE_DATABASE_META_FILE, readLiveDatabaseTableFiles } from './stage.js';
+function unitKey(table) {
+    const parts = [table.catalog, table.db, table.name]
+        .filter((part) => typeof part === 'string' && part.length > 0)
+        .map((part) => part
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, ''))
+        .filter(Boolean);
+    return `live-database-${parts.join('-') || 'table'}`;
+}
+function displayName(table) {
+    return [table.catalog, table.db, table.name].filter(Boolean).join('.');
+}
+function isTablePath(path) {
+    return path.startsWith('tables/') && path.endsWith('.json');
+}
+export async function chunkLiveDatabaseStagedDir(stagedDir, diffSet) {
+    const tableFiles = await readLiveDatabaseTableFiles(stagedDir);
+    const allTablePaths = tableFiles.map((file) => file.path);
+    const globalDeps = [LIVE_DATABASE_META_FILE, LIVE_DATABASE_FOREIGN_KEYS_FILE];
+    const touched = diffSet ? new Set([...diffSet.added, ...diffSet.modified]) : null;
+    const globalTouched = Boolean(touched && (touched.has(LIVE_DATABASE_META_FILE) || touched.has(LIVE_DATABASE_FOREIGN_KEYS_FILE)));
+    const workUnits = [];
+    for (const file of tableFiles) {
+        if (touched && !globalTouched && !touched.has(file.path)) {
+            continue;
+        }
+        const peers = allTablePaths.filter((path) => path !== file.path).sort();
+        workUnits.push({
+            unitKey: unitKey(file.table),
+            displayLabel: `Live database table ${displayName(file.table)}`,
+            rawFiles: [file.path],
+            peerFileIndex: peers,
+            dependencyPaths: globalDeps,
+            notes: `Database catalog snapshot for ${displayName(file.table)} with ${file.table.columns.length} column${file.table.columns.length === 1 ? '' : 's'}.`,
+        });
+    }
+    const deletedRawPaths = diffSet ? diffSet.deleted.filter(isTablePath).sort() : [];
+    return {
+        workUnits,
+        ...(deletedRawPaths.length > 0 ? { eviction: { deletedRawPaths } } : {}),
+    };
+}

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/chunk.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/chunk.test.js

@@ -0,0 +1,95 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { chunkLiveDatabaseStagedDir } from './chunk.js';
+import { liveDatabaseTablePath, writeLiveDatabaseSnapshot } from './stage.js';
+function snapshot() {
+    return {
+        connectionId: 'conn-1',
+        driver: 'postgres',
+        extractedAt: '2026-04-27T00:00:00.000Z',
+        scope: { schemas: ['public'] },
+        metadata: {},
+        tables: [
+            {
+                name: 'orders',
+                catalog: null,
+                db: 'public',
+                kind: 'table',
+                comment: null,
+                estimatedRows: null,
+                columns: [
+                    {
+                        name: 'id',
+                        nativeType: 'integer',
+                        normalizedType: 'integer',
+                        dimensionType: 'number',
+                        nullable: false,
+                        primaryKey: true,
+                        comment: null,
+                    },
+                ],
+                foreignKeys: [],
+            },
+            {
+                name: 'customers',
+                catalog: null,
+                db: 'public',
+                kind: 'table',
+                comment: null,
+                estimatedRows: null,
+                columns: [
+                    {
+                        name: 'id',
+                        nativeType: 'integer',
+                        normalizedType: 'integer',
+                        dimensionType: 'number',
+                        nullable: false,
+                        primaryKey: true,
+                        comment: null,
+                    },
+                ],
+                foreignKeys: [],
+            },
+        ],
+    };
+}
+describe('chunkLiveDatabaseStagedDir', () => {
+    it('emits one work unit per table on the first run', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'ktx-live-db-chunk-'));
+        await writeLiveDatabaseSnapshot(dir, snapshot());
+        const result = await chunkLiveDatabaseStagedDir(dir);
+        expect(result.workUnits.map((wu) => wu.unitKey)).toEqual([
+            'live-database-public-customers',
+            'live-database-public-orders',
+        ]);
+        expect(result.workUnits[0]?.dependencyPaths).toEqual(['connection.json', 'foreign-keys.json']);
+        expect(result.workUnits[0]?.peerFileIndex).toContain(liveDatabaseTablePath({ catalog: null, db: 'public', name: 'orders' }));
+    });
+    it('keeps only changed tables during incremental syncs and records table evictions', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'ktx-live-db-diff-'));
+        await writeLiveDatabaseSnapshot(dir, snapshot());
+        const ordersPath = liveDatabaseTablePath({ catalog: null, db: 'public', name: 'orders' });
+        const customersPath = liveDatabaseTablePath({ catalog: null, db: 'public', name: 'customers' });
+        const result = await chunkLiveDatabaseStagedDir(dir, {
+            added: [],
+            modified: [ordersPath],
+            deleted: [customersPath],
+            unchanged: ['connection.json', 'foreign-keys.json'],
+        });
+        expect(result.workUnits.map((wu) => wu.unitKey)).toEqual(['live-database-public-orders']);
+        expect(result.eviction?.deletedRawPaths).toEqual([customersPath]);
+    });
+    it('fans out all table work units when the foreign-key index changes', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'ktx-live-db-fk-'));
+        await writeLiveDatabaseSnapshot(dir, snapshot());
+        const result = await chunkLiveDatabaseStagedDir(dir, {
+            added: [],
+            modified: ['foreign-keys.json'],
+            deleted: [],
+            unchanged: [],
+        });
+        expect(result.workUnits).toHaveLength(2);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/daemon-introspection.d.ts

@@ -0,0 +1,20 @@
+import type { KtxProjectConnectionConfig } from '../../../project/config.js';
+import type { LiveDatabaseIntrospectionPort } from './types.js';
+export type KtxDaemonDatabaseIntrospectionCommand = 'database-introspect';
+export type KtxDaemonDatabaseJsonRunner = (subcommand: KtxDaemonDatabaseIntrospectionCommand, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export type KtxDaemonDatabaseHttpJsonRunner = (path: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export interface DaemonLiveDatabaseIntrospectionOptions {
+    connections: Record<string, KtxProjectConnectionConfig>;
+    schemas?: string[];
+    statementTimeoutMs?: number;
+    connectionTimeoutSeconds?: number;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    baseUrl?: string;
+    runJson?: KtxDaemonDatabaseJsonRunner;
+    requestJson?: KtxDaemonDatabaseHttpJsonRunner;
+    now?: () => Date;
+}
+export declare function createDaemonLiveDatabaseIntrospection(options: DaemonLiveDatabaseIntrospectionOptions): LiveDatabaseIntrospectionPort;

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/daemon-introspection.js

@@ -0,0 +1,190 @@
+import { spawn } from 'node:child_process';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+import { inferKtxDimensionType, normalizeKtxNativeType } from '../../../scan/type-normalization.js';
+const DEFAULT_SCHEMAS = ['public'];
+function parseJsonObject(raw, subcommand) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`ktx-daemon ${subcommand} returned non-object JSON`);
+    }
+    return parsed;
+}
+function runProcessJson(options) {
+    return async (subcommand, payload) => new Promise((resolve, reject) => {
+        const child = spawn(options.command, [...options.args, subcommand], {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            const stdoutText = Buffer.concat(stdout).toString('utf8').trim();
+            const stderrText = Buffer.concat(stderr).toString('utf8').trim();
+            if (code !== 0) {
+                reject(new Error(`ktx-daemon ${subcommand} failed: ${stderrText || `exit code ${code}`}`));
+                return;
+            }
+            try {
+                resolve(parseJsonObject(stdoutText, subcommand));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        child.stdin.end(`${JSON.stringify(payload)}\n`);
+    });
+}
+function normalizedBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}
+function postJson(baseUrl) {
+    return async (path, payload) => new Promise((resolve, reject) => {
+        const target = new URL(path.replace(/^\//, ''), normalizedBaseUrl(baseUrl));
+        const body = JSON.stringify(payload);
+        const client = target.protocol === 'https:' ? httpsRequest : httpRequest;
+        const request = client(target, {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(body),
+            },
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(chunk));
+            response.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                const statusCode = response.statusCode ?? 0;
+                if (statusCode < 200 || statusCode >= 300) {
+                    reject(new Error(`ktx-daemon HTTP ${path} failed with ${statusCode}: ${text}`));
+                    return;
+                }
+                try {
+                    resolve(parseJsonObject(text, path));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        request.on('error', reject);
+        request.end(body);
+    });
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function recordArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => item !== null && typeof item === 'object' && !Array.isArray(item))
+        : [];
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`ktx-daemon database introspection response is missing string field ${field}`);
+    }
+    return value;
+}
+function nullableString(value) {
+    return typeof value === 'string' ? value : null;
+}
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function normalizeDriver(driver) {
+    const normalized = String(driver ?? '').trim().toLowerCase();
+    return normalized === 'postgresql' ? 'postgres' : normalized;
+}
+function requirePostgresConnection(connections, connectionId) {
+    const connection = connections[connectionId];
+    const driver = normalizeDriver(connection?.driver);
+    if (driver !== 'postgres') {
+        throw new Error(`Local live-database ingest cannot run driver "${connection?.driver ?? 'unknown'}".`);
+    }
+    if (connection?.readonly !== true) {
+        throw new Error(`Local live-database ingest requires connections.${connectionId}.readonly: true.`);
+    }
+    if (typeof connection.url !== 'string' || connection.url.trim().length === 0) {
+        throw new Error(`Local live-database ingest requires connections.${connectionId}.url.`);
+    }
+    return connection;
+}
+function mapColumn(raw) {
+    const nativeType = requiredString(raw.type, 'tables[].columns[].type');
+    return {
+        name: requiredString(raw.name, 'tables[].columns[].name'),
+        nativeType,
+        normalizedType: normalizeKtxNativeType(nativeType),
+        dimensionType: inferKtxDimensionType(nativeType),
+        nullable: raw.nullable !== false ? true : false,
+        primaryKey: raw.primary_key === true,
+        comment: nullableString(raw.comment),
+    };
+}
+function mapForeignKey(raw) {
+    return {
+        fromColumn: requiredString(raw.from_column, 'tables[].foreign_keys[].from_column'),
+        toCatalog: null,
+        toDb: null,
+        toTable: requiredString(raw.to_table, 'tables[].foreign_keys[].to_table'),
+        toColumn: requiredString(raw.to_column, 'tables[].foreign_keys[].to_column'),
+        constraintName: nullableString(raw.constraint_name),
+    };
+}
+function mapTable(raw) {
+    return {
+        catalog: nullableString(raw.catalog),
+        db: nullableString(raw.db),
+        name: requiredString(raw.name, 'tables[].name'),
+        kind: 'table',
+        comment: nullableString(raw.comment),
+        estimatedRows: null,
+        columns: recordArray(raw.columns).map(mapColumn),
+        foreignKeys: recordArray(raw.foreign_keys).map(mapForeignKey),
+    };
+}
+function mapDaemonSnapshot(raw, input) {
+    return {
+        connectionId: requiredString(raw.connection_id, 'connection_id') || input.connectionId,
+        driver: 'postgres',
+        extractedAt: optionalString(raw.extracted_at) ?? input.extractedAt,
+        scope: { schemas: input.schemas },
+        metadata: recordValue(raw.metadata),
+        tables: recordArray(raw.tables).map(mapTable),
+    };
+}
+export function createDaemonLiveDatabaseIntrospection(options) {
+    const schemas = options.schemas ?? DEFAULT_SCHEMAS;
+    const command = options.command ?? 'python';
+    const args = options.args ?? ['-m', 'ktx_daemon'];
+    const runJson = options.runJson ?? runProcessJson({ command, args, cwd: options.cwd, env: options.env });
+    const requestJson = options.requestJson ?? (options.baseUrl ? postJson(options.baseUrl) : undefined);
+    const now = options.now ?? (() => new Date());
+    return {
+        async extractSchema(connectionId) {
+            const connection = requirePostgresConnection(options.connections, connectionId);
+            const payload = {
+                connection_id: connectionId,
+                driver: normalizeDriver(connection.driver),
+                url: connection.url,
+                schemas,
+                statement_timeout_ms: options.statementTimeoutMs ?? 30_000,
+                connection_timeout_seconds: options.connectionTimeoutSeconds ?? 5,
+            };
+            const raw = requestJson
+                ? await requestJson('/database/introspect', payload)
+                : await runJson('database-introspect', payload);
+            return mapDaemonSnapshot(raw, {
+                connectionId,
+                extractedAt: now().toISOString(),
+                schemas,
+            });
+        },
+    };
+}

package/node_modules/@ktx/context/dist/ingest/adapters/live-database/daemon-introspection.test.d.ts

@@ -0,0 +1 @@
+export {};