@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/scan/orchestrator.test.js

@@ -0,0 +1,335 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createKtxConnectorCapabilities, KtxScanOrchestrator, } from './index.js';
+function snapshot() {
+    return {
+        connectionId: 'warehouse',
+        driver: 'postgres',
+        extractedAt: '2026-04-29T00:00:00.000Z',
+        scope: { schemas: ['public'] },
+        metadata: { source: 'test' },
+        tables: [
+            {
+                catalog: null,
+                db: 'public',
+                name: 'orders',
+                kind: 'table',
+                comment: 'Orders table',
+                estimatedRows: null,
+                columns: [
+                    {
+                        name: 'id',
+                        nativeType: 'integer',
+                        normalizedType: 'integer',
+                        dimensionType: 'number',
+                        nullable: false,
+                        primaryKey: true,
+                        comment: 'Order id',
+                    },
+                ],
+                foreignKeys: [],
+            },
+        ],
+    };
+}
+function connector(capabilities = createKtxConnectorCapabilities({ tableSampling: true, columnSampling: true })) {
+    return {
+        id: 'connector-1',
+        driver: 'postgres',
+        capabilities,
+        introspect: vi.fn(async () => snapshot()),
+    };
+}
+function context() {
+    return {
+        runId: 'scan-run-1',
+        logger: {
+            debug: vi.fn(),
+            info: vi.fn(),
+            warn: vi.fn(),
+            error: vi.fn(),
+        },
+    };
+}
+const input = {
+    connectionId: 'warehouse',
+    driver: 'postgres',
+    mode: 'structural',
+};
+describe('KtxScanOrchestrator', () => {
+    it('runs structural scans through connector introspection and structural host callback', async () => {
+        const scanConnector = connector();
+        const scanContext = context();
+        const runStructural = vi.fn(async (scanSnapshot) => ({
+            result: { synced: true },
+            diffSummary: { tablesAdded: scanSnapshot.tables.length, columnsAdded: 1 },
+            structuralSyncStats: { tablesCreated: 1, columnsCreated: 1 },
+            artifactPaths: { manifestShards: ['semantic-layer/warehouse/_schema/public.yaml'] },
+        }));
+        const result = await new KtxScanOrchestrator({
+            now: () => new Date('2026-04-29T00:10:00.000Z'),
+            syncIdFactory: () => 'sync-1',
+        }).run({
+            connector: scanConnector,
+            input,
+            trigger: 'schema_scan',
+            context: scanContext,
+            runStructural,
+        });
+        expect(scanConnector.introspect).toHaveBeenCalledWith(input, scanContext);
+        expect(runStructural).toHaveBeenCalledWith(snapshot(), scanContext);
+        expect(result.snapshot.connectionId).toBe('warehouse');
+        expect(result.structural.result).toEqual({ synced: true });
+        expect(result.enrichment).toBeNull();
+        expect(result.report).toMatchObject({
+            connectionId: 'warehouse',
+            driver: 'postgres',
+            syncId: 'sync-1',
+            runId: 'scan-run-1',
+            trigger: 'schema_scan',
+            mode: 'structural',
+            dryRun: false,
+            diffSummary: {
+                tablesAdded: 1,
+                columnsAdded: 1,
+            },
+            structuralSyncStats: {
+                tablesCreated: 1,
+                columnsCreated: 1,
+            },
+            manifestShardsWritten: 1,
+            artifactPaths: {
+                manifestShards: ['semantic-layer/warehouse/_schema/public.yaml'],
+            },
+            enrichment: {
+                dataDictionary: 'skipped',
+                columnDescriptions: 'skipped',
+                tableDescriptions: 'skipped',
+                embeddings: 'skipped',
+                deterministicRelationships: 'skipped',
+                llmRelationshipValidation: 'skipped',
+                statisticalValidation: 'skipped',
+            },
+            enrichmentState: {
+                resumedStages: [],
+                completedStages: [],
+                failedStages: [],
+            },
+            createdAt: '2026-04-29T00:10:00.000Z',
+        });
+    });
+    it('runs enriched scans through structural and enrichment host callbacks', async () => {
+        const scanConnector = connector(createKtxConnectorCapabilities({
+            tableSampling: true,
+            columnSampling: true,
+            columnStats: true,
+            readOnlySql: true,
+        }));
+        const scanContext = context();
+        const result = await new KtxScanOrchestrator({ syncIdFactory: () => 'sync-2' }).run({
+            connector: scanConnector,
+            input: { ...input, mode: 'enriched', detectRelationships: true },
+            trigger: 'schema_scan',
+            context: scanContext,
+            runStructural: vi.fn(async () => ({
+                result: { schemaId: 'schema-1' },
+                structuralSyncStats: { tablesCreated: 1 },
+            })),
+            runEnrichment: vi.fn(async () => ({
+                result: { enriched: true },
+                enrichment: {
+                    dataDictionary: 'completed',
+                    columnDescriptions: 'completed',
+                    tableDescriptions: 'completed',
+                    embeddings: 'completed',
+                    deterministicRelationships: 'completed',
+                    statisticalValidation: 'completed',
+                },
+                relationships: { accepted: 2, rejected: 1 },
+            })),
+        });
+        expect(result.enrichment?.result).toEqual({ enriched: true });
+        expect(result.report.enrichment.columnDescriptions).toBe('completed');
+        expect(result.report.relationships).toEqual({ accepted: 2, review: 0, rejected: 1, skipped: 0 });
+        expect(result.report.capabilityGaps).toEqual([]);
+        expect(result.report.warnings).toEqual([]);
+    });
+    it('reports host enrichment state summaries from enriched scan phases', async () => {
+        const scanConnector = connector(createKtxConnectorCapabilities({
+            tableSampling: true,
+            columnSampling: true,
+            columnStats: true,
+            readOnlySql: true,
+        }));
+        const enrichmentState = {
+            resumedStages: ['relationships', 'descriptions', 'descriptions'],
+            completedStages: ['embeddings', 'descriptions', 'relationships'],
+            failedStages: [],
+        };
+        const result = await new KtxScanOrchestrator({ syncIdFactory: () => 'sync-state' }).run({
+            connector: scanConnector,
+            input: { ...input, mode: 'enriched', detectRelationships: true },
+            trigger: 'schema_scan',
+            context: context(),
+            runStructural: vi.fn(async () => ({ result: { synced: true } })),
+            runEnrichment: vi.fn(async () => ({
+                result: { enriched: true },
+                enrichmentState,
+            })),
+        });
+        expect(result.report.enrichmentState).toEqual({
+            resumedStages: ['descriptions', 'relationships'],
+            completedStages: ['descriptions', 'embeddings', 'relationships'],
+            failedStages: [],
+        });
+    });
+    it('records recoverable warnings for missing optional capabilities during enriched scans', async () => {
+        const result = await new KtxScanOrchestrator({ syncIdFactory: () => 'sync-3' }).run({
+            connector: connector(createKtxConnectorCapabilities()),
+            input: { ...input, mode: 'enriched', detectRelationships: true },
+            trigger: 'schema_scan',
+            context: context(),
+            runStructural: vi.fn(async () => ({ result: {} })),
+            runEnrichment: vi.fn(async () => ({ result: {} })),
+        });
+        expect(result.report.capabilityGaps).toEqual(['tableSampling', 'columnSampling', 'columnStats', 'readOnlySql']);
+        expect(result.report.warnings.map((warning) => warning.code)).toEqual([
+            'connector_capability_missing',
+            'connector_capability_missing',
+            'connector_capability_missing',
+            'connector_capability_missing',
+        ]);
+        expect(result.report.warnings.every((warning) => warning.recoverable)).toBe(true);
+    });
+    it('redacts structural and enrichment warning metadata before returning reports', async () => {
+        const result = await new KtxScanOrchestrator({ syncIdFactory: () => 'sync-redacted' }).run({
+            connector: connector(createKtxConnectorCapabilities({
+                tableSampling: true,
+                columnSampling: true,
+                columnStats: true,
+                readOnlySql: true,
+            })),
+            input: { ...input, mode: 'enriched' },
+            trigger: 'schema_scan',
+            context: context(),
+            runStructural: vi.fn(async () => ({
+                result: {},
+                warnings: [
+                    {
+                        code: 'sampling_failed',
+                        message: 'structural warning',
+                        recoverable: true,
+                        metadata: {
+                            url: 'postgres://reader:secret@example.test/db', // pragma: allowlist secret
+                            table: 'orders',
+                        },
+                    },
+                ],
+            })),
+            runEnrichment: vi.fn(async () => ({
+                result: {},
+                warnings: [
+                    {
+                        code: 'embedding_unavailable',
+                        message: 'enrichment warning',
+                        recoverable: true,
+                        metadata: {
+                            nested: {
+                                api_key: 'sk_test_123', // pragma: allowlist secret
+                                schema: 'public',
+                            },
+                        },
+                    },
+                ],
+            })),
+        });
+        expect(result.report.warnings).toEqual([
+            {
+                code: 'sampling_failed',
+                message: 'structural warning',
+                recoverable: true,
+                metadata: {
+                    url: '<redacted>',
+                    table: 'orders',
+                },
+            },
+            {
+                code: 'embedding_unavailable',
+                message: 'enrichment warning',
+                recoverable: true,
+                metadata: {
+                    nested: {
+                        api_key: '<redacted>',
+                        schema: 'public',
+                    },
+                },
+            },
+        ]);
+    });
+    it('keeps structural results when the enrichment phase fails after structural sync', async () => {
+        const scanConnector = connector(createKtxConnectorCapabilities({
+            tableSampling: true,
+            columnSampling: true,
+            columnStats: true,
+            readOnlySql: true,
+        }));
+        const runStructural = vi.fn(async () => ({
+            result: { synced: true },
+            artifactPaths: {
+                rawSourcesDir: 'raw-sources/warehouse/live-database/sync-failed-enrichment',
+                manifestShards: ['semantic-layer/warehouse/_schema/public.yaml'],
+            },
+            manifestShardsWritten: 1,
+        }));
+        const runEnrichment = vi.fn(async () => {
+            throw new Error('AI Gateway timed out');
+        });
+        const result = await new KtxScanOrchestrator({
+            now: () => new Date('2026-04-29T18:00:00.000Z'),
+            syncIdFactory: () => 'sync-failed-enrichment',
+        }).run({
+            connector: scanConnector,
+            input: { ...input, mode: 'enriched', detectRelationships: true },
+            trigger: 'schema_scan',
+            context: context(),
+            runStructural,
+            runEnrichment,
+        });
+        expect(result.structural.result).toEqual({ synced: true });
+        expect(result.enrichment).toBeNull();
+        expect(result.report.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+        expect(result.report.manifestShardsWritten).toBe(1);
+        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: AI Gateway timed out',
+                recoverable: true,
+                metadata: {
+                    mode: 'enriched',
+                    detectRelationships: true,
+                },
+            },
+        ]);
+    });
+    it('marks dry-run reports without changing host callback behavior', async () => {
+        const runStructural = vi.fn(async () => ({ result: { planned: true }, manifestShardsWritten: 0 }));
+        const result = await new KtxScanOrchestrator({ syncIdFactory: () => 'sync-4' }).run({
+            connector: connector(),
+            input: { ...input, dryRun: true },
+            trigger: 'cli',
+            context: context(),
+            runStructural,
+        });
+        expect(runStructural).toHaveBeenCalledTimes(1);
+        expect(result.report.dryRun).toBe(true);
+        expect(result.report.trigger).toBe('cli');
+    });
+});

package/node_modules/@ktx/context/dist/scan/relationship-artifacts.d.ts

@@ -0,0 +1,20 @@
+import type { KtxLocalProject } from '../project/index.js';
+import type { KtxRelationshipArtifact, KtxRelationshipDiagnosticsArtifact } from './relationship-diagnostics.js';
+import type { KtxRelationshipProfileArtifact } from './relationship-profiling.js';
+import type { KtxScanReport } from './types.js';
+export type KtxRelationshipArtifactStatus = 'accepted' | 'review' | 'rejected' | 'skipped' | 'all';
+export interface ReadLocalScanRelationshipArtifactsResult {
+    runId: string;
+    connectionId: string;
+    syncId: string;
+    report: KtxScanReport;
+    relationships: KtxRelationshipArtifact;
+    diagnostics: KtxRelationshipDiagnosticsArtifact | null;
+    profile: KtxRelationshipProfileArtifact | null;
+    paths: {
+        relationships: string;
+        diagnostics: string | null;
+        profile: string | null;
+    };
+}
+export declare function readLocalScanRelationshipArtifacts(project: KtxLocalProject, runId: string): Promise<ReadLocalScanRelationshipArtifactsResult | null>;

package/node_modules/@ktx/context/dist/scan/relationship-artifacts.js

@@ -0,0 +1,45 @@
+import { getLocalScanReport } from './local-scan.js';
+function findArtifactPath(report, fileName) {
+    return report.artifactPaths.enrichmentArtifacts.find((path) => path.endsWith(`/enrichment/${fileName}`)) ?? null;
+}
+async function readJsonArtifact(project, path) {
+    const raw = await project.fileStore.readFile(path);
+    return JSON.parse(raw.content);
+}
+async function readOptionalJsonArtifact(project, path) {
+    if (!path) {
+        return null;
+    }
+    try {
+        return await readJsonArtifact(project, path);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readLocalScanRelationshipArtifacts(project, runId) {
+    const report = await getLocalScanReport(project, runId);
+    if (!report) {
+        return null;
+    }
+    const relationshipsPath = findArtifactPath(report, 'relationships.json');
+    if (!relationshipsPath) {
+        throw new Error(`Scan report "${runId}" does not reference relationships.json`);
+    }
+    const diagnosticsPath = findArtifactPath(report, 'relationship-diagnostics.json');
+    const profilePath = findArtifactPath(report, 'relationship-profile.json');
+    return {
+        runId,
+        connectionId: report.connectionId,
+        syncId: report.syncId,
+        report,
+        relationships: await readJsonArtifact(project, relationshipsPath),
+        diagnostics: await readOptionalJsonArtifact(project, diagnosticsPath),
+        profile: await readOptionalJsonArtifact(project, profilePath),
+        paths: {
+            relationships: relationshipsPath,
+            diagnostics: diagnosticsPath,
+            profile: profilePath,
+        },
+    };
+}

package/node_modules/@ktx/context/dist/scan/relationship-artifacts.test.d.ts

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

package/node_modules/@ktx/context/dist/scan/relationship-artifacts.test.js

@@ -0,0 +1,270 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { runLocalStageOnlyIngest } from '../ingest/index.js';
+import { initKtxProject, loadKtxProject } from '../project/index.js';
+import { describe, expect, it } from 'vitest';
+import { readLocalScanRelationshipArtifacts } from './relationship-artifacts.js';
+async function writeProjectFile(projectDir, relativePath, content) {
+    const absolutePath = join(projectDir, relativePath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, 'utf-8');
+}
+async function writeWarehouseConfig(projectDir) {
+    await writeFile(join(projectDir, 'ktx.yaml'), [
+        'project: warehouse',
+        'connections:',
+        '  warehouse:',
+        '    driver: sqlite',
+        '    path: warehouse.db',
+        '    readonly: true',
+        'ingest:',
+        '  adapters:',
+        '    - live-database',
+        '',
+    ].join('\n'), 'utf-8');
+}
+function liveDatabaseAdapter() {
+    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'), '{"connectionId":"warehouse"}\n', 'utf-8');
+            await writeFile(join(stagedDir, 'foreign-keys.json'), '{"foreignKeys":[]}\n', 'utf-8');
+            await writeFile(join(stagedDir, 'tables', 'orders.json'), '{"name":"orders","db":"public","columns":[{"name":"id","type":"integer","nullable":false,"primaryKey":true}]}\n', 'utf-8');
+        },
+        async detect(stagedDir) {
+            await writeFile(join(stagedDir, 'connection.json'), '{"connectionId":"warehouse"}\n', 'utf-8');
+            return true;
+        },
+        async chunk() {
+            return {
+                workUnits: [
+                    {
+                        unitKey: 'live-database-public-orders',
+                        rawFiles: ['tables/orders.json'],
+                        dependencyPaths: ['connection.json', 'foreign-keys.json'],
+                        peerFileIndex: [],
+                    },
+                ],
+            };
+        },
+    };
+}
+async function createLiveDatabaseRun(projectDir, runId) {
+    await initKtxProject({ projectDir, projectName: 'warehouse' });
+    await writeWarehouseConfig(projectDir);
+    const project = await loadKtxProject({ projectDir });
+    await runLocalStageOnlyIngest({
+        project,
+        adapters: [liveDatabaseAdapter()],
+        adapter: 'live-database',
+        connectionId: 'warehouse',
+        jobId: runId,
+        now: () => new Date('2026-05-07T10:00:00.000Z'),
+    });
+    return project;
+}
+function scanReport(enrichmentArtifacts, syncId = '2026-05-07-100000-scan-run-review') {
+    return {
+        connectionId: 'warehouse',
+        driver: 'sqlite',
+        syncId,
+        runId: 'scan-run-review',
+        trigger: 'cli',
+        mode: 'relationships',
+        dryRun: false,
+        artifactPaths: {
+            rawSourcesDir: `raw-sources/warehouse/live-database/${syncId}`,
+            reportPath: `raw-sources/warehouse/live-database/${syncId}/scan-report.json`,
+            manifestShards: [],
+            enrichmentArtifacts,
+        },
+        diffSummary: {
+            tablesAdded: 0,
+            tablesModified: 0,
+            tablesDeleted: 0,
+            tablesUnchanged: 2,
+            columnsAdded: 0,
+            columnsModified: 0,
+            columnsDeleted: 0,
+        },
+        manifestShardsWritten: 0,
+        structuralSyncStats: {
+            tablesCreated: 0,
+            tablesUpdated: 0,
+            tablesDeleted: 0,
+            columnsCreated: 0,
+            columnsUpdated: 0,
+            columnsDeleted: 0,
+        },
+        enrichment: {
+            dataDictionary: 'skipped',
+            tableDescriptions: 'skipped',
+            columnDescriptions: 'skipped',
+            embeddings: 'skipped',
+            deterministicRelationships: 'completed',
+            llmRelationshipValidation: 'skipped',
+            statisticalValidation: 'skipped',
+        },
+        capabilityGaps: [],
+        warnings: [],
+        relationships: { accepted: 0, review: 1, rejected: 1, skipped: 0 },
+        enrichmentState: {
+            resumedStages: [],
+            completedStages: ['relationships'],
+            failedStages: [],
+        },
+        createdAt: '2026-05-07T10:00:00.000Z',
+    };
+}
+const relationshipArtifact = {
+    connectionId: 'warehouse',
+    accepted: [],
+    review: [
+        {
+            id: 'orders:orders.customer_id->customers:customers.id',
+            status: 'review',
+            source: 'deterministic_name',
+            from: {
+                tableId: 'orders',
+                columnIds: ['orders.customer_id'],
+                table: { catalog: null, db: 'public', name: 'orders' },
+                columns: ['customer_id'],
+            },
+            to: {
+                tableId: 'customers',
+                columnIds: ['customers.id'],
+                table: { catalog: null, db: 'public', name: 'customers' },
+                columns: ['id'],
+            },
+            relationshipType: 'many_to_one',
+            confidence: 0.62,
+            pkScore: 0.91,
+            fkScore: 0.62,
+            score: 0.62,
+            evidence: { sources: ['table_suffix'] },
+            validation: { status: 'unavailable' },
+            graph: { reasons: ['validation_unavailable_review_only'] },
+            reasons: ['validation_unavailable_review_only', 'fk_score_review'],
+        },
+    ],
+    rejected: [
+        {
+            id: 'orders:orders.note_id->notes:notes.id',
+            status: 'rejected',
+            source: 'deterministic_name',
+            from: {
+                tableId: 'orders',
+                columnIds: ['orders.note_id'],
+                table: { catalog: null, db: 'public', name: 'orders' },
+                columns: ['note_id'],
+            },
+            to: {
+                tableId: 'notes',
+                columnIds: ['notes.id'],
+                table: { catalog: null, db: 'public', name: 'notes' },
+                columns: ['id'],
+            },
+            relationshipType: 'many_to_one',
+            confidence: 0.2,
+            pkScore: 0.4,
+            fkScore: 0.2,
+            score: 0.2,
+            evidence: { sources: ['exact_column_match'] },
+            validation: { status: 'failed' },
+            graph: { reasons: ['low_source_coverage'] },
+            reasons: ['low_source_coverage'],
+        },
+    ],
+    skipped: [],
+};
+const diagnosticsArtifact = {
+    connectionId: 'warehouse',
+    generatedAt: '2026-05-07T10:00:00.000Z',
+    summary: { accepted: 0, review: 1, rejected: 1, skipped: 0 },
+    noAcceptedReason: 'relationship candidates require review before manifest writes',
+    candidateCountsBySource: { deterministic_name: 2 },
+    validation: { available: false, sqlAvailable: false, queryCount: 0 },
+    thresholds: { acceptThreshold: 0.85, reviewThreshold: 0.55 },
+    policy: {
+        validationRequiredForManifest: true,
+        maxCandidatesPerColumn: 25,
+        profileSampleRows: 10000,
+        validationConcurrency: 4,
+    },
+    warnings: [],
+    profileWarnings: ['KTX scan connector cannot run read-only SQL relationship validation'],
+};
+const profileArtifact = {
+    connectionId: 'warehouse',
+    driver: 'sqlite',
+    sqlAvailable: false,
+    tables: [],
+    columns: {},
+    queryCount: 0,
+    warnings: ['KTX scan connector cannot run read-only SQL relationship validation'],
+};
+describe('local scan relationship artifact reader', () => {
+    it('loads relationship, diagnostics, and profile artifacts for a scan run', async () => {
+        const projectDir = await mkdtemp(join(tmpdir(), 'ktx-relationship-artifacts-'));
+        try {
+            const project = await createLiveDatabaseRun(projectDir, 'scan-run-review');
+            const syncId = '2026-05-07-100000-scan-run-review';
+            const report = scanReport([
+                `raw-sources/warehouse/live-database/${syncId}/enrichment/relationships.json`,
+                `raw-sources/warehouse/live-database/${syncId}/enrichment/relationship-profile.json`,
+                `raw-sources/warehouse/live-database/${syncId}/enrichment/relationship-diagnostics.json`,
+            ], syncId);
+            await writeProjectFile(projectDir, report.artifactPaths.reportPath ?? '', `${JSON.stringify(report, null, 2)}\n`);
+            await writeProjectFile(projectDir, `raw-sources/warehouse/live-database/${syncId}/enrichment/relationships.json`, `${JSON.stringify(relationshipArtifact, null, 2)}\n`);
+            await writeProjectFile(projectDir, `raw-sources/warehouse/live-database/${syncId}/enrichment/relationship-diagnostics.json`, `${JSON.stringify(diagnosticsArtifact, null, 2)}\n`);
+            await writeProjectFile(projectDir, `raw-sources/warehouse/live-database/${syncId}/enrichment/relationship-profile.json`, `${JSON.stringify(profileArtifact, null, 2)}\n`);
+            const result = await readLocalScanRelationshipArtifacts(project, 'scan-run-review');
+            expect(result).toMatchObject({
+                runId: 'scan-run-review',
+                connectionId: 'warehouse',
+                syncId,
+                paths: {
+                    relationships: `raw-sources/warehouse/live-database/${syncId}/enrichment/relationships.json`,
+                    diagnostics: `raw-sources/warehouse/live-database/${syncId}/enrichment/relationship-diagnostics.json`,
+                    profile: `raw-sources/warehouse/live-database/${syncId}/enrichment/relationship-profile.json`,
+                },
+            });
+            expect(result?.relationships.review[0]).toMatchObject({
+                id: 'orders:orders.customer_id->customers:customers.id',
+                status: 'review',
+                reasons: ['validation_unavailable_review_only', 'fk_score_review'],
+            });
+            expect(result?.diagnostics?.noAcceptedReason).toBe('relationship candidates require review before manifest writes');
+            expect(result?.profile?.sqlAvailable).toBe(false);
+        }
+        finally {
+            await rm(projectDir, { recursive: true, force: true });
+        }
+    });
+    it('returns null when the scan run has no report', async () => {
+        const projectDir = await mkdtemp(join(tmpdir(), 'ktx-relationship-artifacts-missing-run-'));
+        try {
+            await initKtxProject({ projectDir, projectName: 'warehouse' });
+            const project = await loadKtxProject({ projectDir });
+            await expect(readLocalScanRelationshipArtifacts(project, 'missing-run')).resolves.toBeNull();
+        }
+        finally {
+            await rm(projectDir, { recursive: true, force: true });
+        }
+    });
+    it('throws a focused error when a scan report does not reference relationships.json', async () => {
+        const projectDir = await mkdtemp(join(tmpdir(), 'ktx-relationship-artifacts-missing-artifact-'));
+        try {
+            const project = await createLiveDatabaseRun(projectDir, 'scan-run-review');
+            const report = scanReport([]);
+            await writeProjectFile(projectDir, report.artifactPaths.reportPath ?? '', `${JSON.stringify(report, null, 2)}\n`);
+            await expect(readLocalScanRelationshipArtifacts(project, 'scan-run-review')).rejects.toThrow('Scan report "scan-run-review" does not reference relationships.json');
+        }
+        finally {
+            await rm(projectDir, { recursive: true, force: true });
+        }
+    });
+});