@kaelio/ktx 0.4.0 → 0.5.0

package/dist/context/scan/local-scan.test.js

@@ -0,0 +1,1663 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import YAML from 'yaml';
+import { initKtxProject, loadKtxProject } from '../../context/project/project.js';
+import { resolveEnabledTables } from './enabled-tables.js';
+import { getLocalScanReport, getLocalScanStatus, runLocalScan } from './local-scan.js';
+import { tableRefKey, tableRefSet } from './table-ref.js';
+function relationshipSqlResult(input, options = {}) {
+    if (input.sql.includes('child_values')) {
+        if (options.throwOnCoverage) {
+            throw new Error('validation failed for postgres://reader:secret@example.test/db'); // pragma: allowlist secret
+        }
+        return {
+            headers: ['child_distinct', 'parent_distinct', 'overlap', 'violation_count'],
+            rows: [[100, 100, 99, 0]],
+            totalRows: 1,
+            rowCount: 1,
+        };
+    }
+    if (input.sql.includes(' AS column_name')) {
+        const tableRowCount = input.sql.includes('orders') || input.sql.includes('users') ? 1000 : 100;
+        const columnNames = Array.from(input.sql.matchAll(/'([^']+)' AS column_name/g), (match) => match[1]);
+        return {
+            headers: [
+                'column_name',
+                'table_row_count',
+                'row_count',
+                'null_count',
+                'distinct_count',
+                'min_text_length',
+                'max_text_length',
+                'sample_values',
+            ],
+            rows: columnNames.map((columnName) => [
+                columnName,
+                tableRowCount,
+                tableRowCount,
+                0,
+                columnName === 'id' ? tableRowCount : 100,
+                1,
+                3,
+                '1\u001f2',
+            ]),
+            totalRows: columnNames.length,
+            rowCount: columnNames.length,
+        };
+    }
+    if (input.sql.includes('COUNT(*) AS row_count') && !input.sql.includes('COUNT(DISTINCT')) {
+        return {
+            headers: ['row_count'],
+            rows: [[input.sql.includes('orders') ? 1000 : 100]],
+            totalRows: 1,
+            rowCount: 1,
+        };
+    }
+    if (input.sql.includes('COUNT(DISTINCT')) {
+        return {
+            headers: ['row_count', 'null_count', 'distinct_count', 'min_text_length', 'max_text_length'],
+            rows: [[input.sql.includes('orders') ? 1000 : 100, 0, input.sql.includes('orders') ? 100 : 100, 1, 3]],
+            totalRows: 1,
+            rowCount: 1,
+        };
+    }
+    if (input.sql.includes(' AS value')) {
+        return {
+            headers: ['value'],
+            rows: [[1], [2]],
+            totalRows: 2,
+            rowCount: 2,
+        };
+    }
+    throw new Error(`Unexpected relationship SQL: ${input.sql}`);
+}
+function deterministicLlmRuntime() {
+    return {
+        generateText: vi.fn(async (input) => `Deterministic description for ${input.prompt.slice(0, 64).trim() || 'data source'}`),
+        generateObject: vi.fn(async () => ({ pkCandidates: [], fkCandidates: [] })),
+        runAgentLoop: vi.fn(),
+    };
+}
+async function writeLiveDatabaseConfig(projectDir) {
+    await writeFile(join(projectDir, 'ktx.yaml'), [
+        'connections:',
+        '  warehouse:',
+        '    driver: postgres',
+        '    url: env:DATABASE_URL',
+        'ingest:',
+        '  adapters:',
+        '    - live-database',
+        '',
+    ].join('\n'), 'utf-8');
+}
+async function writeDatabaseConfigWithoutIngestAdapters(projectDir) {
+    await writeFile(join(projectDir, 'ktx.yaml'), [
+        'connections:',
+        '  warehouse:',
+        '    driver: postgres',
+        '    url: env:DATABASE_URL',
+        '    readonly: true',
+        '',
+    ].join('\n'), 'utf-8');
+}
+function defaultFetchSnapshot(options = {}) {
+    return {
+        connectionId: 'warehouse',
+        driver: 'postgres',
+        extractedAt: options.extractedAt?.() ?? '2026-04-29T09: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: [],
+            },
+        ],
+    };
+}
+function fetchOnlyAdapter(options = {}) {
+    const scanSnapshot = options.snapshot
+        ? { ...options.snapshot, ...(options.extractedAt ? { extractedAt: options.extractedAt() } : {}) }
+        : defaultFetchSnapshot(options);
+    return {
+        source: 'live-database',
+        skillNames: ['live_database_ingest'],
+        async fetch(_pullConfig, stagedDir) {
+            await mkdir(join(stagedDir, 'tables'), { recursive: true });
+            await writeFile(join(stagedDir, 'connection.json'), `${JSON.stringify({
+                connectionId: scanSnapshot.connectionId,
+                driver: scanSnapshot.driver,
+                extractedAt: scanSnapshot.extractedAt,
+                scope: scanSnapshot.scope,
+                metadata: scanSnapshot.metadata,
+            })}\n`, 'utf-8');
+            await writeFile(join(stagedDir, 'foreign-keys.json'), '{"foreignKeys":[]}\n', 'utf-8');
+            for (const table of scanSnapshot.tables) {
+                await writeFile(join(stagedDir, 'tables', `${table.name}.json`), `${JSON.stringify(table)}\n`, 'utf-8');
+            }
+        },
+        async detect() {
+            return true;
+        },
+        async chunk() {
+            return {
+                workUnits: scanSnapshot.tables.map((table) => ({
+                    unitKey: `live-database-${table.db ?? 'default'}-${table.name}`,
+                    rawFiles: [`tables/${table.name}.json`],
+                    dependencyPaths: ['connection.json', 'foreign-keys.json'],
+                    peerFileIndex: [],
+                })),
+            };
+        },
+    };
+}
+function nativeScanSnapshot() {
+    return {
+        connectionId: 'warehouse',
+        driver: 'postgres',
+        extractedAt: '2026-04-29T09:00:00.000Z',
+        scope: { schemas: ['public'] },
+        metadata: {},
+        tables: [
+            {
+                catalog: null,
+                db: 'public',
+                name: 'orders',
+                kind: 'table',
+                comment: 'Orders',
+                estimatedRows: 1,
+                foreignKeys: [],
+                columns: [
+                    {
+                        name: 'id',
+                        nativeType: 'integer',
+                        normalizedType: 'integer',
+                        dimensionType: 'number',
+                        nullable: false,
+                        primaryKey: true,
+                        comment: 'Order id',
+                    },
+                ],
+            },
+        ],
+    };
+}
+function nativeScanConnector(options = {}) {
+    return {
+        id: 'test:warehouse',
+        driver: 'postgres',
+        capabilities: {
+            structuralIntrospection: true,
+            tableSampling: true,
+            columnSampling: true,
+            columnStats: false,
+            readOnlySql: false,
+            nestedAnalysis: false,
+            eventStreamDiscovery: false,
+            formalForeignKeys: false,
+            estimatedRowCounts: false,
+        },
+        introspect: vi.fn(async () => nativeScanSnapshot()),
+        sampleTable: vi.fn(async () => ({ headers: ['id'], rows: [[1]], totalRows: 1 })),
+        sampleColumn: vi.fn(async () => ({ values: ['1'], nullCount: 0, distinctCount: 1 })),
+        ...(options.cleanup ? { cleanup: options.cleanup } : {}),
+    };
+}
+describe('local scan', () => {
+    let tempDir;
+    let project;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-local-scan-'));
+        const projectDir = join(tempDir, 'project');
+        await initKtxProject({ projectDir });
+        await writeLiveDatabaseConfig(projectDir);
+        project = await loadKtxProject({ projectDir });
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('runs a structural live-database scan and writes a durable scan report', async () => {
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-run-1',
+            now: () => new Date('2026-04-29T09:00:00.000Z'),
+        });
+        expect(result.report).toMatchObject({
+            connectionId: 'warehouse',
+            driver: 'postgres',
+            runId: 'scan-run-1',
+            syncId: '2026-04-29-090000-scan-run-1',
+            trigger: 'cli',
+            mode: 'structural',
+            dryRun: false,
+            artifactPaths: {
+                rawSourcesDir: 'raw-sources/warehouse/live-database/2026-04-29-090000-scan-run-1',
+                reportPath: 'raw-sources/warehouse/live-database/2026-04-29-090000-scan-run-1/scan-report.json',
+                manifestShards: ['semantic-layer/warehouse/_schema/public.yaml'],
+                enrichmentArtifacts: [],
+            },
+            diffSummary: {
+                tablesAdded: 1,
+                tablesModified: 0,
+                tablesDeleted: 0,
+                tablesUnchanged: 0,
+                columnsAdded: 0,
+                columnsModified: 0,
+                columnsDeleted: 0,
+            },
+            manifestShardsWritten: 1,
+            relationships: { accepted: 0, review: 0, rejected: 0, skipped: 0 },
+        });
+        await expect(readFile(join(project.projectDir, 'raw-sources/warehouse/live-database/2026-04-29-090000-scan-run-1/scan-report.json'), 'utf-8')).resolves.toContain('"runId": "scan-run-1"');
+        const structuralManifest = await readFile(join(project.projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8');
+        expect(structuralManifest).toContain('orders:');
+        expect(structuralManifest).toContain('table: public.orders');
+        expect(structuralManifest).toContain('name: id');
+        expect(structuralManifest).not.toContain('ai:');
+        await expect(getLocalScanStatus(project, 'scan-run-1')).resolves.toMatchObject({
+            runId: 'scan-run-1',
+            status: 'done',
+            done: true,
+            connectionId: 'warehouse',
+            mode: 'structural',
+            reportPath: 'raw-sources/warehouse/live-database/2026-04-29-090000-scan-run-1/scan-report.json',
+        });
+        await expect(getLocalScanReport(project, 'scan-run-1')).resolves.toMatchObject({
+            runId: 'scan-run-1',
+            connectionId: 'warehouse',
+        });
+    });
+    it('passes enabled_tables as fetch context tableScope and does not post-filter staged snapshots', async () => {
+        project.config.connections.warehouse = {
+            ...project.config.connections.warehouse,
+            enabled_tables: ['public.orders'],
+        };
+        let capturedTableScope;
+        const adapter = {
+            source: 'live-database',
+            skillNames: ['live_database_ingest'],
+            async fetch(_pullConfig, stagedDir, ctx) {
+                capturedTableScope = ctx.tableScope;
+                await mkdir(join(stagedDir, 'tables'), { recursive: true });
+                await writeFile(join(stagedDir, 'connection.json'), '{"connectionId":"warehouse","driver":"postgres","scope":{"schemas":["public"]},"metadata":{}}\n', 'utf-8');
+                await writeFile(join(stagedDir, 'foreign-keys.json'), '{"foreignKeys":[]}\n', 'utf-8');
+                await writeFile(join(stagedDir, 'tables', 'customers.json'), '{"name":"customers","catalog":null,"db":"public","kind":"table","comment":null,"estimatedRows":100,"columns":[{"name":"id","nativeType":"integer","normalizedType":"integer","dimensionType":"number","nullable":false,"primaryKey":true,"comment":null}],"foreignKeys":[]}\n', 'utf-8');
+                await writeFile(join(stagedDir, 'tables', 'orders.json'), '{"name":"orders","catalog":null,"db":"public","kind":"table","comment":null,"estimatedRows":1000,"columns":[{"name":"id","nativeType":"integer","normalizedType":"integer","dimensionType":"number","nullable":false,"primaryKey":true,"comment":null}],"foreignKeys":[]}\n', 'utf-8');
+            },
+            async detect() {
+                return true;
+            },
+            async chunk() {
+                return {
+                    workUnits: [
+                        {
+                            unitKey: 'live-database-public-customers',
+                            rawFiles: ['tables/customers.json'],
+                            dependencyPaths: ['connection.json', 'foreign-keys.json'],
+                            peerFileIndex: [],
+                        },
+                        {
+                            unitKey: 'live-database-public-orders',
+                            rawFiles: ['tables/orders.json'],
+                            dependencyPaths: ['connection.json', 'foreign-keys.json'],
+                            peerFileIndex: [],
+                        },
+                    ],
+                };
+            },
+        };
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            jobId: 'scan-strict-scope-fetch',
+            now: () => new Date('2026-05-22T00:00:00.000Z'),
+        });
+        expect([...(capturedTableScope ?? [])]).toEqual([...tableRefSet([{ catalog: null, db: 'public', name: 'orders' }])]);
+        expect(result.report.diffSummary.tablesAdded).toBe(2);
+        const structuralManifest = await readFile(join(project.projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8');
+        expect(structuralManifest).toContain('customers:');
+        expect(structuralManifest).toContain('orders:');
+    });
+    it('runs a structural database scan when live-database is not listed in ktx.yaml', async () => {
+        await writeDatabaseConfigWithoutIngestAdapters(project.projectDir);
+        project = await loadKtxProject({ projectDir: project.projectDir });
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-run-without-public-adapter',
+            now: () => new Date('2026-04-29T09:10:00.000Z'),
+        });
+        expect(result.report).toMatchObject({
+            connectionId: 'warehouse',
+            runId: 'scan-run-without-public-adapter',
+            artifactPaths: {
+                reportPath: 'raw-sources/warehouse/live-database/2026-04-29-091000-scan-run-without-public-adapter/scan-report.json',
+            },
+        });
+    });
+    it('threads the structural snapshot into enrichment without connector re-introspection', async () => {
+        project.config.scan.enrichment = { mode: 'deterministic' };
+        const connector = nativeScanConnector();
+        const introspect = vi.mocked(connector.introspect);
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            mode: 'enriched',
+            connector,
+            jobId: 'scan-enrichment-snapshot-threading',
+            now: () => new Date('2026-04-29T09:11:00.000Z'),
+        });
+        expect(result.report.enrichment.tableDescriptions).toBe('completed');
+        expect(introspect).not.toHaveBeenCalled();
+    });
+    it('cleans up a scan connector constructed by local scan', async () => {
+        const cleanup = vi.fn(async () => undefined);
+        await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            createConnector: vi.fn(async () => nativeScanConnector({ cleanup })),
+            jobId: 'scan-owned-connector-cleanup',
+            now: () => new Date('2026-04-29T09:13:00.000Z'),
+        });
+        expect(cleanup).toHaveBeenCalledTimes(1);
+    });
+    it('does not clean up a caller-supplied scan connector', async () => {
+        const cleanup = vi.fn(async () => undefined);
+        await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector: nativeScanConnector({ cleanup }),
+            jobId: 'scan-supplied-connector-cleanup',
+            now: () => new Date('2026-04-29T09:13:30.000Z'),
+        });
+        expect(cleanup).not.toHaveBeenCalled();
+    });
+    it('reuses scan report and raw-source paths when the same local scan run id is retried', async () => {
+        const first = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-idempotent-run',
+            now: () => new Date('2026-04-29T09:20:00.000Z'),
+        });
+        const retry = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-idempotent-run',
+            now: () => new Date('2026-04-29T10:20:00.000Z'),
+        });
+        expect(retry.runId).toBe(first.runId);
+        expect(retry.syncId).toBe(first.syncId);
+        expect(retry.report.artifactPaths.rawSourcesDir).toBe(first.report.artifactPaths.rawSourcesDir);
+        expect(retry.report.artifactPaths.reportPath).toBe(first.report.artifactPaths.reportPath);
+        expect(retry.report.artifactPaths.manifestShards).toEqual(first.report.artifactPaths.manifestShards);
+        const status = await getLocalScanStatus(project, 'scan-idempotent-run');
+        expect(status?.syncId).toBe(first.syncId);
+        expect(status?.reportPath).toBe(first.report.artifactPaths.reportPath);
+        const files = await project.fileStore.listFiles('raw-sources/warehouse/live-database');
+        expect(files.files.every((file) => file.includes('2026-04-29-092000-scan-idempotent-run'))).toBe(true);
+        expect(files.files.some((file) => file.includes('2026-04-29-102000-scan-idempotent-run'))).toBe(false);
+    });
+    it('reuses existing scan artifacts without writing when a new scan run has unchanged input', async () => {
+        let extractedAt = '2026-04-29T09:25:00.000Z';
+        const adapter = fetchOnlyAdapter({ extractedAt: () => extractedAt });
+        const first = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            jobId: 'scan-idempotent-new-run-1',
+            now: () => new Date('2026-04-29T09:25:00.000Z'),
+        });
+        const writeSpy = vi.spyOn(project.fileStore, 'writeFile');
+        const commitSpy = vi.spyOn(project.git, 'commitFiles');
+        extractedAt = '2026-04-29T10:25:00.000Z';
+        const second = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            jobId: 'scan-idempotent-new-run-2',
+            now: () => new Date('2026-04-29T10:25:00.000Z'),
+        });
+        expect(second.runId).toBe('scan-idempotent-new-run-2');
+        expect(second.syncId).toBe(first.syncId);
+        expect(second.report.runId).toBe('scan-idempotent-new-run-2');
+        expect(second.report.artifactPaths.rawSourcesDir).toBe(first.report.artifactPaths.rawSourcesDir);
+        expect(second.report.artifactPaths.reportPath).toBe(first.report.artifactPaths.reportPath);
+        expect(second.report.artifactPaths.manifestShards).toEqual(first.report.artifactPaths.manifestShards);
+        expect(second.report.diffSummary).toMatchObject({
+            tablesAdded: 0,
+            tablesModified: 0,
+            tablesDeleted: 0,
+            tablesUnchanged: 1,
+        });
+        expect(writeSpy).not.toHaveBeenCalled();
+        expect(commitSpy).not.toHaveBeenCalled();
+        await expect(getLocalScanReport(project, 'scan-idempotent-new-run-2')).resolves.toMatchObject({
+            runId: 'scan-idempotent-new-run-2',
+            syncId: first.syncId,
+            diffSummary: {
+                tablesAdded: 0,
+                tablesModified: 0,
+                tablesDeleted: 0,
+                tablesUnchanged: 1,
+                columnsAdded: 0,
+                columnsModified: 0,
+                columnsDeleted: 0,
+            },
+        });
+        const files = await project.fileStore.listFiles('raw-sources/warehouse/live-database');
+        expect(files.files.every((file) => file.includes(first.syncId))).toBe(true);
+        writeSpy.mockRestore();
+        commitSpy.mockRestore();
+    });
+    it('returns an in-memory dry-run report without persisting scan status or report files', async () => {
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-dry-run-1',
+            now: () => new Date('2026-04-29T09:05:00.000Z'),
+            dryRun: true,
+        });
+        expect(result.report).toMatchObject({
+            runId: 'scan-dry-run-1',
+            dryRun: true,
+            artifactPaths: {
+                rawSourcesDir: null,
+                reportPath: null,
+                manifestShards: [],
+                enrichmentArtifacts: [],
+            },
+        });
+        await expect(getLocalScanStatus(project, 'scan-dry-run-1')).resolves.toBeNull();
+        await expect(getLocalScanReport(project, 'scan-dry-run-1')).resolves.toBeNull();
+    });
+    it('runs relationship scans through a native scan connector and records relationship summary', async () => {
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: false,
+                readOnlySql: false,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: false,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:00:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'customers',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: null,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: null,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'customer_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+        };
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector,
+            jobId: 'scan-relationships-1',
+            now: () => new Date('2026-04-29T09:10:00.000Z'),
+        });
+        expect(result.report.mode).toBe('relationships');
+        expect(result.report.enrichment.deterministicRelationships).toBe('completed');
+        expect(result.report.relationships).toEqual({ accepted: 0, review: 1, rejected: 0, skipped: 0 });
+    });
+    it('records standalone statistical validation results in the scan report', async () => {
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: true,
+                readOnlySql: true,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: true,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:00:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'customers',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 100,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 1000,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'customer_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async executeReadOnly(input) {
+                return relationshipSqlResult(input);
+            },
+        };
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector,
+            jobId: 'scan-statistical-relationships-1',
+            now: () => new Date('2026-04-29T09:12:00.000Z'),
+        });
+        expect(result.report.enrichment.statisticalValidation).toBe('completed');
+        expect(result.report.relationships).toEqual({ accepted: 1, review: 0, rejected: 0, skipped: 0 });
+        expect(result.report.warnings).toEqual([]);
+    });
+    it('keeps prototype connector methods when enabled_tables is configured', async () => {
+        project.config.connections.warehouse = {
+            ...project.config.connections.warehouse,
+            enabled_tables: ['public.customers', 'public.orders'],
+        };
+        const scopedAdapter = {
+            source: 'live-database',
+            skillNames: ['live_database_ingest'],
+            async fetch(_pullConfig, stagedDir) {
+                await mkdir(join(stagedDir, 'tables'), { recursive: true });
+                await writeFile(join(stagedDir, 'connection.json'), '{"connectionId":"warehouse","driver":"postgres","scope":{"schemas":["public"]},"metadata":{}}\n', 'utf-8');
+                await writeFile(join(stagedDir, 'foreign-keys.json'), '{"foreignKeys":[]}\n', 'utf-8');
+                await writeFile(join(stagedDir, 'tables', 'customers.json'), '{"name":"customers","catalog":null,"db":"public","kind":"table","comment":null,"estimatedRows":100,"columns":[{"name":"id","nativeType":"integer","normalizedType":"integer","dimensionType":"number","nullable":false,"primaryKey":true,"comment":null}],"foreignKeys":[]}\n', 'utf-8');
+                await writeFile(join(stagedDir, 'tables', 'orders.json'), '{"name":"orders","catalog":null,"db":"public","kind":"table","comment":null,"estimatedRows":1000,"columns":[{"name":"customer_id","nativeType":"integer","normalizedType":"integer","dimensionType":"number","nullable":false,"primaryKey":false,"comment":null}],"foreignKeys":[]}\n', 'utf-8');
+            },
+            async detect() {
+                return true;
+            },
+            async chunk() {
+                return {
+                    workUnits: [
+                        {
+                            unitKey: 'live-database-public-customers',
+                            rawFiles: ['tables/customers.json'],
+                            dependencyPaths: ['connection.json', 'foreign-keys.json'],
+                            peerFileIndex: [],
+                        },
+                        {
+                            unitKey: 'live-database-public-orders',
+                            rawFiles: ['tables/orders.json'],
+                            dependencyPaths: ['connection.json', 'foreign-keys.json'],
+                            peerFileIndex: [],
+                        },
+                    ],
+                };
+            },
+        };
+        class FakeClassConnector {
+            id = 'test:warehouse';
+            driver = 'postgres';
+            capabilities = {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: true,
+                readOnlySql: true,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: true,
+            };
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-05-22T00:00:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'customers',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 100,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 1000,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'customer_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            async executeReadOnly(input) {
+                return relationshipSqlResult(input);
+            }
+        }
+        const result = await runLocalScan({
+            project,
+            adapters: [scopedAdapter],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector: new FakeClassConnector(),
+            jobId: 'scan-prototype-connector-scope',
+            now: () => new Date('2026-05-22T00:00:00.000Z'),
+        });
+        expect(result.report.relationships.accepted).toBe(1);
+        expect(result.report.warnings).toEqual([]);
+    });
+    it('threads scan relationship settings into relationship-only local scans', async () => {
+        project.config.scan.enrichment = { mode: 'deterministic' };
+        project.config.scan.relationships = {
+            ...project.config.scan.relationships,
+            llmProposals: false,
+            maxLlmTablesPerBatch: 7,
+        };
+        const generateObject = vi.fn(async () => ({ pkCandidates: [], fkCandidates: [] }));
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: true,
+                readOnlySql: true,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: true,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:30:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'customers',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: null,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: null,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'customer_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async executeReadOnly(input) {
+                return relationshipSqlResult(input);
+            },
+        };
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector,
+            enrichmentProviders: {
+                llmRuntime: {
+                    ...deterministicLlmRuntime(),
+                    generateObject: generateObject,
+                },
+                embedding: {
+                    dimensions: 8,
+                    maxBatchSize: 64,
+                    async embedBatch() {
+                        return [];
+                    },
+                },
+            },
+            jobId: 'scan-relationships-llm-disabled-1',
+            now: () => new Date('2026-04-29T09:30:00.000Z'),
+        });
+        expect(result.report.relationships.accepted).toBe(1);
+        expect(result.report.enrichment.llmRelationshipValidation).toBe('skipped');
+        expect(generateObject).not.toHaveBeenCalled();
+    });
+    it('accepts no-declared-constraint relationships and writes relationship artifacts', async () => {
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: true,
+                readOnlySql: true,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: true,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-05-07T09:00:00.000Z',
+                    scope: {},
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: null,
+                            name: 'accounts',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 2,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: null,
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 3,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                                {
+                                    name: 'account_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async executeReadOnly(input) {
+                return relationshipSqlResult(input);
+            },
+        };
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector,
+            jobId: 'scan-relationship-discovery',
+            now: () => new Date('2026-05-07T09:12:00.000Z'),
+        });
+        expect(result.report.relationships).toEqual({ accepted: 1, review: 0, rejected: 0, skipped: 0 });
+        const enrichmentRoot = `raw-sources/warehouse/live-database/${result.report.syncId}/enrichment`;
+        expect(result.report.artifactPaths.enrichmentArtifacts).toEqual([
+            `${enrichmentRoot}/relationships.json`,
+            `${enrichmentRoot}/relationship-profile.json`,
+            `${enrichmentRoot}/relationship-diagnostics.json`,
+        ]);
+        const diagnostics = JSON.parse((await project.fileStore.readFile(`${enrichmentRoot}/relationship-diagnostics.json`)).content);
+        expect(diagnostics.summary).toEqual({ accepted: 1, review: 0, rejected: 0, skipped: 0 });
+        expect(diagnostics.noAcceptedReason).toBeNull();
+        const manifestPath = result.report.artifactPaths.manifestShards[0];
+        if (!manifestPath) {
+            throw new Error('Expected manifest shard path');
+        }
+        const manifest = YAML.parse((await project.fileStore.readFile(manifestPath)).content);
+        expect(manifest.tables.orders.joins).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                to: 'accounts',
+                on: 'orders.account_id = accounts.id',
+                source: 'inferred',
+            }),
+        ]));
+    });
+    it('runs enriched relationship discovery without scan enrichment backend', async () => {
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: true,
+                readOnlySql: true,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: true,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-05-07T09:00:00.000Z',
+                    scope: {},
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: null,
+                            name: 'accounts',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 2,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: null,
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 3,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                                {
+                                    name: 'account_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async executeReadOnly(input) {
+                return relationshipSqlResult(input);
+            },
+        };
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'enriched',
+            connector,
+            jobId: 'scan-providerless-enriched-relationship-discovery',
+            now: () => new Date('2026-05-07T09:14:00.000Z'),
+        });
+        expect(result.report.mode).toBe('enriched');
+        expect(result.report.enrichment).toEqual({
+            dataDictionary: 'skipped',
+            tableDescriptions: 'skipped',
+            columnDescriptions: 'skipped',
+            embeddings: 'skipped',
+            deterministicRelationships: 'completed',
+            llmRelationshipValidation: 'skipped',
+            statisticalValidation: 'completed',
+        });
+        expect(result.report.relationships).toEqual({ accepted: 1, review: 0, rejected: 0, skipped: 0 });
+        expect(result.report.warnings).toContainEqual({
+            code: 'scan_enrichment_backend_not_configured',
+            message: 'Skipping description and embedding enrichment because scan.enrichment.mode is not configured; relationship discovery still ran.',
+            recoverable: true,
+            metadata: {
+                skippedStages: ['descriptions', 'embeddings'],
+                relationshipDetection: true,
+            },
+        });
+        const enrichmentRoot = `raw-sources/warehouse/live-database/${result.report.syncId}/enrichment`;
+        expect(result.report.artifactPaths.enrichmentArtifacts).toEqual(expect.arrayContaining([
+            `${enrichmentRoot}/relationships.json`,
+            `${enrichmentRoot}/relationship-profile.json`,
+            `${enrichmentRoot}/relationship-diagnostics.json`,
+        ]));
+        const manifestPath = result.report.artifactPaths.manifestShards[0];
+        if (!manifestPath) {
+            throw new Error('Expected manifest shard path');
+        }
+        const manifest = YAML.parse((await project.fileStore.readFile(manifestPath)).content);
+        expect(manifest.tables.orders.joins).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                to: 'accounts',
+                on: 'orders.account_id = accounts.id',
+                source: 'inferred',
+            }),
+        ]));
+    });
+    it('redacts credential-like warning messages before persisting local scan reports', async () => {
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: false,
+                columnSampling: false,
+                columnStats: true,
+                readOnlySql: true,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: true,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:00:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'customers',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 100,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: null,
+                            estimatedRows: 1000,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'customer_id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: false,
+                                    comment: null,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async executeReadOnly(input) {
+                return relationshipSqlResult(input, { throwOnCoverage: true });
+            },
+        };
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const result = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'relationships',
+            detectRelationships: true,
+            connector,
+            jobId: 'scan-redacted-warning-1',
+            now: () => new Date('2026-04-29T09:14:00.000Z'),
+        });
+        expect(result.report.warnings[0]?.message).toContain('postgres://reader:<redacted>@example.test/db');
+        expect(result.report.warnings[0]?.message).not.toContain('postgres://reader:secret@example.test/db');
+        const reportPath = result.report.artifactPaths.reportPath;
+        if (!reportPath) {
+            throw new Error('Expected local scan report path');
+        }
+        const persistedReport = await readFile(join(project.projectDir, reportPath), 'utf-8');
+        expect(persistedReport).toContain('postgres://reader:<redacted>@example.test/db');
+        expect(persistedReport).not.toContain('postgres://reader:secret@example.test/db'); // pragma: allowlist secret
+    });
+    it('runs enriched scans when deterministic standalone enrichment is configured without embeddings', async () => {
+        await writeFile(join(project.projectDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: postgres',
+            '    url: env:DATABASE_URL',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            'scan:',
+            '  enrichment:',
+            '    mode: deterministic',
+            '',
+        ].join('\n'), 'utf-8');
+        project = await loadKtxProject({ projectDir: project.projectDir });
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: true,
+                columnSampling: true,
+                columnStats: false,
+                readOnlySql: false,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: false,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:00:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: 'Orders',
+                            estimatedRows: 1,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: 'Order id',
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async sampleTable() {
+                return { headers: ['id'], rows: [[1]], totalRows: 1 };
+            },
+            async sampleColumn() {
+                return { values: ['1'], nullCount: 0, distinctCount: 1 };
+            },
+        };
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            mode: 'enriched',
+            connector,
+            jobId: 'scan-enriched-1',
+            now: () => new Date('2026-04-29T09:15:00.000Z'),
+        });
+        expect(result.report.mode).toBe('enriched');
+        expect(result.report.enrichment.tableDescriptions).toBe('completed');
+        expect(result.report.enrichment.columnDescriptions).toBe('completed');
+        expect(result.report.enrichment.embeddings).toBe('skipped');
+        expect(result.report.artifactPaths.enrichmentArtifacts).toEqual([
+            'raw-sources/warehouse/live-database/2026-04-29-091500-scan-enriched-1/enrichment/descriptions.json',
+            'raw-sources/warehouse/live-database/2026-04-29-091500-scan-enriched-1/enrichment/relationships.json',
+            'raw-sources/warehouse/live-database/2026-04-29-091500-scan-enriched-1/enrichment/relationship-profile.json',
+            'raw-sources/warehouse/live-database/2026-04-29-091500-scan-enriched-1/enrichment/relationship-diagnostics.json',
+        ]);
+        expect(result.report.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+        expect(result.report.manifestShardsWritten).toBe(1);
+        await expect(readFile(join(project.projectDir, 'raw-sources/warehouse/live-database/2026-04-29-091500-scan-enriched-1/enrichment/descriptions.json'), 'utf-8')).resolves.toContain('Deterministic description');
+        const manifestRaw = await readFile(join(project.projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8');
+        expect(manifestRaw).toContain('ai: |-');
+        expect(manifestRaw).toContain('Deterministic description');
+    });
+    it('persists structural artifacts and a recoverable warning when standalone enrichment execution fails', async () => {
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: true,
+                columnSampling: true,
+                columnStats: false,
+                readOnlySql: false,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: false,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:00:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: 'Orders',
+                            estimatedRows: 1,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: 'Order id',
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async sampleTable() {
+                return { headers: ['id'], rows: [[1]], totalRows: 1 };
+            },
+            async sampleColumn() {
+                return { values: ['1'], nullCount: 0, distinctCount: 1 };
+            },
+        };
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            mode: 'enriched',
+            connector,
+            enrichmentProviders: {
+                llmRuntime: deterministicLlmRuntime(),
+                embedding: {
+                    dimensions: 8,
+                    maxBatchSize: 64,
+                    async embedBatch() {
+                        throw new Error('embedding service timed out');
+                    },
+                },
+            },
+            jobId: 'scan-enrichment-fails-1',
+            now: () => new Date('2026-04-29T09:18:00.000Z'),
+        });
+        expect(result.report.mode).toBe('enriched');
+        expect(result.report.enrichment).toEqual({
+            dataDictionary: 'failed',
+            tableDescriptions: 'failed',
+            columnDescriptions: 'failed',
+            embeddings: 'failed',
+            deterministicRelationships: 'failed',
+            llmRelationshipValidation: 'failed',
+            statisticalValidation: 'failed',
+        });
+        expect(result.report.warnings).toEqual([
+            {
+                code: 'enrichment_failed',
+                message: 'KTX scan enrichment failed after structural scan completed: embedding service timed out',
+                recoverable: true,
+                metadata: {
+                    mode: 'enriched',
+                    detectRelationships: false,
+                },
+            },
+        ]);
+        expect(result.report.artifactPaths.enrichmentArtifacts).toEqual([]);
+        expect(result.report.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+        const manifestRaw = await readFile(join(project.projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8');
+        expect(manifestRaw).toContain('orders:');
+        expect(manifestRaw).toContain('table: public.orders');
+        expect(manifestRaw).not.toContain('ai: Generated description');
+        const reportPath = result.report.artifactPaths.reportPath;
+        if (!reportPath) {
+            throw new Error('Expected local scan report path');
+        }
+        const persistedReport = await readFile(join(project.projectDir, reportPath), 'utf-8');
+        expect(persistedReport).toContain('"code": "enrichment_failed"');
+        expect(persistedReport).toContain('embedding service timed out');
+    });
+    it('resumes completed local enrichment stages when an enriched scan run is retried', async () => {
+        let embeddingAttempts = 0;
+        const connector = {
+            id: 'test:warehouse',
+            driver: 'postgres',
+            capabilities: {
+                structuralIntrospection: true,
+                tableSampling: true,
+                columnSampling: true,
+                columnStats: true,
+                readOnlySql: false,
+                nestedAnalysis: false,
+                eventStreamDiscovery: false,
+                formalForeignKeys: false,
+                estimatedRowCounts: false,
+            },
+            async introspect() {
+                return {
+                    connectionId: 'warehouse',
+                    driver: 'postgres',
+                    extractedAt: '2026-04-29T09:21:00.000Z',
+                    scope: { schemas: ['public'] },
+                    metadata: {},
+                    tables: [
+                        {
+                            catalog: null,
+                            db: 'public',
+                            name: 'orders',
+                            kind: 'table',
+                            comment: 'Orders',
+                            estimatedRows: 1,
+                            foreignKeys: [],
+                            columns: [
+                                {
+                                    name: 'id',
+                                    nativeType: 'integer',
+                                    normalizedType: 'integer',
+                                    dimensionType: 'number',
+                                    nullable: false,
+                                    primaryKey: true,
+                                    comment: 'Order id',
+                                },
+                            ],
+                        },
+                    ],
+                };
+            },
+            async sampleTable() {
+                return { headers: ['id'], rows: [[1]], totalRows: 1 };
+            },
+            async sampleColumn() {
+                return { values: ['1'], nullCount: 0, distinctCount: 1 };
+            },
+        };
+        const llmRuntime = deterministicLlmRuntime();
+        const adapter = fetchOnlyAdapter({ snapshot: await connector.introspect() });
+        const first = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'enriched',
+            connector,
+            enrichmentProviders: {
+                llmRuntime,
+                embedding: {
+                    dimensions: 8,
+                    maxBatchSize: 64,
+                    async embedBatch() {
+                        embeddingAttempts += 1;
+                        throw new Error('embedding service timed out once');
+                    },
+                },
+            },
+            jobId: 'scan-enrichment-resume-1',
+            now: () => new Date('2026-04-29T09:21:00.000Z'),
+        });
+        expect(first.report.enrichmentState).toEqual({
+            resumedStages: [],
+            completedStages: ['descriptions'],
+            failedStages: ['embeddings'],
+        });
+        expect(first.report.enrichment.embeddings).toBe('failed');
+        const generateObject = vi.spyOn(llmRuntime, 'generateObject');
+        const retry = await runLocalScan({
+            project,
+            adapters: [adapter],
+            connectionId: 'warehouse',
+            mode: 'enriched',
+            connector,
+            enrichmentProviders: {
+                llmRuntime,
+                embedding: {
+                    dimensions: 8,
+                    maxBatchSize: 64,
+                    async embedBatch(texts) {
+                        embeddingAttempts += 1;
+                        return texts.map(() => [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]);
+                    },
+                },
+            },
+            jobId: 'scan-enrichment-resume-1',
+            now: () => new Date('2026-04-29T09:22:00.000Z'),
+        });
+        expect(retry.syncId).toBe(first.syncId);
+        expect(retry.report.enrichmentState).toEqual({
+            resumedStages: ['descriptions'],
+            completedStages: ['descriptions', 'embeddings', 'relationships'],
+            failedStages: [],
+        });
+        expect(retry.report.enrichment.embeddings).toBe('completed');
+        expect(generateObject).toHaveBeenCalledWith(expect.objectContaining({ role: 'candidateExtraction' }));
+        expect(embeddingAttempts).toBe(2);
+        const reportPath = retry.report.artifactPaths.reportPath;
+        if (!reportPath) {
+            throw new Error('Expected local scan report path');
+        }
+        const persistedReport = await readFile(join(project.projectDir, reportPath), 'utf-8');
+        expect(persistedReport).toContain('"resumedStages": [');
+        expect(persistedReport).toContain('"descriptions"');
+    });
+    it('accepts sqlite as a native standalone scan driver when the host supplies a live-database adapter', async () => {
+        await writeFile(join(project.projectDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: sqlite',
+            '    path: warehouse.db',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            '',
+        ].join('\n'), 'utf-8');
+        project = await loadKtxProject({ projectDir: project.projectDir });
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-run-sqlite',
+            now: () => new Date('2026-04-29T11:00:00.000Z'),
+        });
+        expect(result.report.driver).toBe('sqlite');
+        expect(result.report.artifactPaths.reportPath).toBe('raw-sources/warehouse/live-database/2026-04-29-110000-scan-run-sqlite/scan-report.json');
+    });
+    it('accepts mysql as a native standalone scan driver when the host supplies a live-database adapter', async () => {
+        await writeFile(join(project.projectDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: mysql',
+            '    url: env:MYSQL_URL',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            '',
+        ].join('\n'), 'utf-8');
+        project = await loadKtxProject({ projectDir: project.projectDir });
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-run-mysql',
+            now: () => new Date('2026-04-29T13:00:00.000Z'),
+        });
+        expect(result.report.driver).toBe('mysql');
+        expect(result.report.artifactPaths.reportPath).toBe('raw-sources/warehouse/live-database/2026-04-29-130000-scan-run-mysql/scan-report.json');
+    });
+    it('accepts clickhouse as a native standalone scan driver when the host supplies a live-database adapter', async () => {
+        await writeFile(join(project.projectDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: clickhouse',
+            '    host: env:CLICKHOUSE_HOST',
+            '    database: analytics',
+            '    username: reader',
+            '    password: env:CLICKHOUSE_PASSWORD',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            '',
+        ].join('\n'), 'utf-8');
+        project = await loadKtxProject({ projectDir: project.projectDir });
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-run-clickhouse',
+            now: () => new Date('2026-04-29T15:00:00.000Z'),
+        });
+        expect(result.report.driver).toBe('clickhouse');
+        expect(result.report.artifactPaths.reportPath).toBe('raw-sources/warehouse/live-database/2026-04-29-150000-scan-run-clickhouse/scan-report.json');
+    });
+    it('accepts sqlserver as a native standalone scan driver when the host supplies a live-database adapter', async () => {
+        await writeFile(join(project.projectDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: sqlserver',
+            '    host: env:SQLSERVER_HOST',
+            '    database: analytics',
+            '    username: reader',
+            '    schema: dbo',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            '',
+        ].join('\n'), 'utf-8');
+        project = await loadKtxProject({ projectDir: project.projectDir });
+        const result = await runLocalScan({
+            project,
+            adapters: [fetchOnlyAdapter()],
+            connectionId: 'warehouse',
+            jobId: 'scan-run-sqlserver',
+            now: () => new Date('2026-04-29T16:00:00.000Z'),
+        });
+        expect(result.report.driver).toBe('sqlserver');
+        expect(result.report.artifactPaths.reportPath).toBe('raw-sources/warehouse/live-database/2026-04-29-160000-scan-run-sqlserver/scan-report.json');
+    });
+});
+describe('resolveEnabledTables', () => {
+    it('returns null when no enabled_tables field', () => {
+        expect(resolveEnabledTables({ driver: 'postgres' })).toBeNull();
+    });
+    it('returns null for empty array', () => {
+        expect(resolveEnabledTables({ driver: 'postgres', enabled_tables: [] })).toBeNull();
+    });
+    it('returns a canonical set of enabled table refs', () => {
+        const result = resolveEnabledTables({
+            driver: 'postgres',
+            enabled_tables: ['public.users', 'public.orders'],
+        });
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(2);
+        expect(result.has(tableRefKey({ catalog: null, db: 'public', name: 'users' }))).toBe(true);
+        expect(result.has(tableRefKey({ catalog: null, db: 'public', name: 'orders' }))).toBe(true);
+    });
+    it('returns null for undefined connection', () => {
+        expect(resolveEnabledTables(undefined)).toBeNull();
+    });
+});