@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,190 @@
+import { exportLocalRelationshipFeedbackLabels, } from './relationship-feedback-export.js';
+const DEFAULT_ACCEPT_THRESHOLDS = [0.95, 0.9, 0.85, 0.8, 0.75];
+const DEFAULT_REVIEW_THRESHOLDS = [0.65, 0.6, 0.55, 0.5, 0.45];
+function resolveInput(input) {
+    return {
+        acceptThresholds: [...(input.acceptThresholds ?? DEFAULT_ACCEPT_THRESHOLDS)].sort((left, right) => right - left),
+        reviewThresholds: [...(input.reviewThresholds ?? DEFAULT_REVIEW_THRESHOLDS)].sort((left, right) => right - left),
+        minTotalLabels: input.minTotalLabels ?? 20,
+        minAcceptedLabels: input.minAcceptedLabels ?? 5,
+        minRejectedLabels: input.minRejectedLabels ?? 5,
+        minAcceptedBandPrecision: input.minAcceptedBandPrecision ?? 0.9,
+        minAcceptedOrReviewRecall: input.minAcceptedOrReviewRecall ?? 0.8,
+        minRejectedBandPrecision: input.minRejectedBandPrecision ?? 0.8,
+    };
+}
+function roundMetric(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function ratio(numerator, denominator) {
+    return denominator === 0 ? null : roundMetric(numerator / denominator);
+}
+function prediction(score, acceptThreshold, reviewThreshold) {
+    if (score >= acceptThreshold) {
+        return 'accepted';
+    }
+    if (score >= reviewThreshold) {
+        return 'review';
+    }
+    return 'rejected';
+}
+function isMetricAtLeast(value, minimum) {
+    return value !== null && value >= minimum;
+}
+function thresholdCandidate(labels, acceptThreshold, reviewThreshold, gates) {
+    const scored = labels.filter((label) => label.score !== null);
+    const acceptedLabels = scored.filter((label) => label.decision === 'accepted');
+    const rejectedLabels = scored.filter((label) => label.decision === 'rejected');
+    const predictions = scored.map((label) => ({
+        label,
+        predictedStatus: prediction(label.score, acceptThreshold, reviewThreshold),
+    }));
+    const predictedAccepted = predictions.filter((item) => item.predictedStatus === 'accepted');
+    const predictedReview = predictions.filter((item) => item.predictedStatus === 'review');
+    const predictedRejected = predictions.filter((item) => item.predictedStatus === 'rejected');
+    const acceptedBandPrecision = ratio(predictedAccepted.filter((item) => item.label.decision === 'accepted').length, predictedAccepted.length);
+    const acceptedOrReviewRecall = ratio(predictions.filter((item) => item.label.decision === 'accepted' && item.predictedStatus !== 'rejected').length, acceptedLabels.length);
+    const rejectedBandPrecision = ratio(predictedRejected.filter((item) => item.label.decision === 'rejected').length, predictedRejected.length);
+    return {
+        acceptThreshold,
+        reviewThreshold,
+        eligible: predictedAccepted.length > 0 &&
+            predictedRejected.length > 0 &&
+            isMetricAtLeast(acceptedBandPrecision, gates.minAcceptedBandPrecision) &&
+            isMetricAtLeast(acceptedOrReviewRecall, gates.minAcceptedOrReviewRecall) &&
+            isMetricAtLeast(rejectedBandPrecision, gates.minRejectedBandPrecision),
+        predictedAccepted: predictedAccepted.length,
+        predictedReview: predictedReview.length,
+        predictedRejected: predictedRejected.length,
+        acceptedBandPrecision,
+        acceptedRecall: ratio(predictedAccepted.filter((item) => item.label.decision === 'accepted').length, acceptedLabels.length),
+        acceptedOrReviewRecall,
+        rejectedBandPrecision,
+        rejectedRecall: ratio(predictions.filter((item) => item.label.decision === 'rejected' && item.predictedStatus !== 'accepted').length, rejectedLabels.length),
+        falseAcceptedRejectedLabels: predictedAccepted.filter((item) => item.label.decision === 'rejected').length,
+        falseRejectedAcceptedLabels: predictedRejected.filter((item) => item.label.decision === 'accepted').length,
+    };
+}
+function metricRank(value) {
+    return value ?? -1;
+}
+function sortCandidates(candidates) {
+    return [...candidates].sort((left, right) => Number(right.eligible) - Number(left.eligible) ||
+        metricRank(right.acceptedBandPrecision) - metricRank(left.acceptedBandPrecision) ||
+        metricRank(right.acceptedOrReviewRecall) - metricRank(left.acceptedOrReviewRecall) ||
+        metricRank(right.rejectedBandPrecision) - metricRank(left.rejectedBandPrecision) ||
+        right.acceptThreshold - left.acceptThreshold ||
+        right.reviewThreshold - left.reviewThreshold);
+}
+function labelGateReasons(labels, gates) {
+    const scored = labels.filter((label) => label.score !== null);
+    const accepted = scored.filter((label) => label.decision === 'accepted');
+    const rejected = scored.filter((label) => label.decision === 'rejected');
+    const reasons = [];
+    if (scored.length < gates.minTotalLabels) {
+        reasons.push(`Need at least ${gates.minTotalLabels} scored labels; found ${scored.length}.`);
+    }
+    if (accepted.length < gates.minAcceptedLabels) {
+        reasons.push(`Need at least ${gates.minAcceptedLabels} accepted labels; found ${accepted.length}.`);
+    }
+    if (rejected.length < gates.minRejectedLabels) {
+        reasons.push(`Need at least ${gates.minRejectedLabels} rejected labels; found ${rejected.length}.`);
+    }
+    return reasons;
+}
+export function buildKtxRelationshipThresholdAdviceReport(feedback, input = {}) {
+    const gates = resolveInput(input);
+    const scored = feedback.labels.filter((label) => label.score !== null);
+    const acceptedLabels = scored.filter((label) => label.decision === 'accepted');
+    const rejectedLabels = scored.filter((label) => label.decision === 'rejected');
+    const candidates = sortCandidates(gates.acceptThresholds.flatMap((acceptThreshold) => gates.reviewThresholds.flatMap((reviewThreshold) => acceptThreshold > reviewThreshold
+        ? [thresholdCandidate(feedback.labels, acceptThreshold, reviewThreshold, gates)]
+        : [])));
+    const labelReasons = labelGateReasons(feedback.labels, gates);
+    const eligibleCandidates = candidates.filter((candidate) => candidate.eligible);
+    const status = labelReasons.length > 0 ? 'insufficient_labels' : eligibleCandidates.length > 0 ? 'ready' : 'no_eligible_thresholds';
+    const reasons = status === 'insufficient_labels'
+        ? labelReasons
+        : status === 'no_eligible_thresholds'
+            ? ['No threshold candidate met the precision and recall gates.']
+            : [];
+    return {
+        generatedAt: feedback.generatedAt,
+        filters: feedback.filters,
+        status,
+        gates: {
+            minTotalLabels: gates.minTotalLabels,
+            minAcceptedLabels: gates.minAcceptedLabels,
+            minRejectedLabels: gates.minRejectedLabels,
+            minAcceptedBandPrecision: gates.minAcceptedBandPrecision,
+            minAcceptedOrReviewRecall: gates.minAcceptedOrReviewRecall,
+            minRejectedBandPrecision: gates.minRejectedBandPrecision,
+        },
+        summary: {
+            totalLabels: feedback.labels.length,
+            scoredLabels: scored.length,
+            unscoredLabels: feedback.labels.length - scored.length,
+            acceptedLabels: acceptedLabels.length,
+            rejectedLabels: rejectedLabels.length,
+            evaluatedCandidates: candidates.length,
+            eligibleCandidates: eligibleCandidates.length,
+        },
+        recommended: status === 'ready' ? eligibleCandidates[0] ?? null : null,
+        candidates,
+        reasons,
+        warnings: [...feedback.warnings],
+    };
+}
+export async function adviseLocalRelationshipFeedbackThresholds(project, input = {}) {
+    const exporter = input.exportLocalRelationshipFeedbackLabels ?? exportLocalRelationshipFeedbackLabels;
+    const feedback = await exporter(project, {
+        connectionId: input.connectionId,
+        decision: 'all',
+    });
+    return buildKtxRelationshipThresholdAdviceReport(feedback, input);
+}
+function formatMetric(value) {
+    return value === null ? 'n/a' : value.toFixed(3);
+}
+function candidateLine(candidate) {
+    return [
+        `accept=${candidate.acceptThreshold.toFixed(2)}`,
+        `review=${candidate.reviewThreshold.toFixed(2)}`,
+        `eligible=${candidate.eligible ? 'yes' : 'no'}`,
+        `acceptedPrecision=${formatMetric(candidate.acceptedBandPrecision)}`,
+        `acceptedRecall=${formatMetric(candidate.acceptedRecall)}`,
+        `acceptedOrReviewRecall=${formatMetric(candidate.acceptedOrReviewRecall)}`,
+        `rejectedPrecision=${formatMetric(candidate.rejectedBandPrecision)}`,
+        `rejectedRecall=${formatMetric(candidate.rejectedRecall)}`,
+        `falseAcceptedRejected=${candidate.falseAcceptedRejectedLabels}`,
+        `falseRejectedAccepted=${candidate.falseRejectedAcceptedLabels}`,
+    ].join(' ');
+}
+export function formatKtxRelationshipThresholdAdviceMarkdown(report) {
+    const lines = [
+        'KTX relationship threshold advice',
+        `Generated: ${report.generatedAt}`,
+        `Filter connection: ${report.filters.connectionId ?? 'all'}`,
+        `Status: ${report.status}`,
+        `Labels: total=${report.summary.totalLabels} scored=${report.summary.scoredLabels} accepted=${report.summary.acceptedLabels} rejected=${report.summary.rejectedLabels}`,
+        `Gates: minTotal=${report.gates.minTotalLabels} minAccepted=${report.gates.minAcceptedLabels} minRejected=${report.gates.minRejectedLabels} acceptedPrecision=${report.gates.minAcceptedBandPrecision.toFixed(3)} acceptedOrReviewRecall=${report.gates.minAcceptedOrReviewRecall.toFixed(3)} rejectedPrecision=${report.gates.minRejectedBandPrecision.toFixed(3)}`,
+        `Evaluated candidates: ${report.summary.evaluatedCandidates}`,
+        `Eligible candidates: ${report.summary.eligibleCandidates}`,
+        `Recommended: ${report.recommended
+            ? `accept=${report.recommended.acceptThreshold.toFixed(2)} review=${report.recommended.reviewThreshold.toFixed(2)}`
+            : 'none'}`,
+    ];
+    if (report.reasons.length > 0) {
+        lines.push('', 'Reasons', ...report.reasons.map((reason) => `  - ${reason}`));
+    }
+    if (report.candidates.length > 0) {
+        lines.push('', 'Top candidates', ...report.candidates.slice(0, 5).map((candidate) => `  - ${candidateLine(candidate)}`));
+    }
+    if (report.warnings.length > 0) {
+        lines.push('', 'Warnings');
+        for (const warning of report.warnings.slice(0, 5)) {
+            lines.push(`  - ${warning.path}: ${warning.message}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}

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

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

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

@@ -0,0 +1,205 @@
+import { describe, expect, it, vi } from 'vitest';
+import { adviseLocalRelationshipFeedbackThresholds, buildKtxRelationshipThresholdAdviceReport, formatKtxRelationshipThresholdAdviceMarkdown, } from './relationship-threshold-advice.js';
+function label(input) {
+    return {
+        schemaVersion: 1,
+        previousStatus: 'review',
+        connectionId: 'warehouse',
+        runId: 'scan-run-a',
+        syncId: 'sync-a',
+        decidedAt: '2026-05-07T12:00:00.000Z',
+        reviewer: 'Andrey',
+        note: null,
+        relationshipType: 'many_to_one',
+        source: 'deterministic_name',
+        confidence: input.score ?? 0,
+        pkScore: input.pkScore ?? null,
+        fkScore: input.fkScore ?? input.score,
+        fromTable: 'public.orders',
+        fromColumns: ['customer_id'],
+        toTable: 'public.customers',
+        toColumns: ['id'],
+        reasons: [],
+        artifactPath: 'raw-sources/warehouse/live-database/sync-a/enrichment/relationship-review-decisions.json',
+        ...input,
+    };
+}
+function feedback(labels) {
+    return {
+        generatedAt: '2026-05-07T13:00:00.000Z',
+        filters: { connectionId: null, decision: 'all' },
+        summary: {
+            total: labels.length,
+            accepted: labels.filter((item) => item.decision === 'accepted').length,
+            rejected: labels.filter((item) => item.decision === 'rejected').length,
+            connections: new Set(labels.map((item) => item.connectionId)).size,
+            runs: new Set(labels.map((item) => `${item.connectionId}:${item.runId}`)).size,
+        },
+        labels,
+        warnings: [],
+    };
+}
+describe('relationship threshold advice', () => {
+    it('selects the highest-quality threshold candidate when enough labels exist', () => {
+        const report = buildKtxRelationshipThresholdAdviceReport(feedback([
+            label({
+                candidateId: 'orders:orders.customer_id->customers:customers.id',
+                decision: 'accepted',
+                score: 0.91,
+                pkScore: 0.97,
+                fkScore: 0.91,
+            }),
+            label({
+                candidateId: 'orders:orders.account_id->accounts:accounts.id',
+                decision: 'accepted',
+                score: 0.61,
+                pkScore: 0.88,
+                fkScore: 0.61,
+            }),
+            label({
+                candidateId: 'orders:orders.note_id->notes:notes.id',
+                decision: 'rejected',
+                score: 0.21,
+                pkScore: 0.4,
+                fkScore: 0.21,
+            }),
+            label({
+                candidateId: 'orders:orders.region_id->regions:regions.id',
+                decision: 'rejected',
+                score: 0.88,
+                pkScore: 0.9,
+                fkScore: 0.88,
+            }),
+        ]), {
+            acceptThresholds: [0.9, 0.85],
+            reviewThresholds: [0.55],
+            minTotalLabels: 4,
+            minAcceptedLabels: 2,
+            minRejectedLabels: 2,
+            minAcceptedBandPrecision: 0.75,
+            minAcceptedOrReviewRecall: 0.75,
+            minRejectedBandPrecision: 0.75,
+        });
+        expect(report.status).toBe('ready');
+        expect(report.summary).toMatchObject({
+            totalLabels: 4,
+            scoredLabels: 4,
+            acceptedLabels: 2,
+            rejectedLabels: 2,
+            eligibleCandidates: 1,
+        });
+        expect(report.recommended).toMatchObject({
+            acceptThreshold: 0.9,
+            reviewThreshold: 0.55,
+            eligible: true,
+            acceptedBandPrecision: 1,
+            acceptedRecall: 0.5,
+            acceptedOrReviewRecall: 1,
+            rejectedBandPrecision: 1,
+            rejectedRecall: 1,
+            falseAcceptedRejectedLabels: 0,
+            falseRejectedAcceptedLabels: 0,
+        });
+        expect(report.candidates.map((candidate) => [candidate.acceptThreshold, candidate.reviewThreshold, candidate.eligible])).toEqual([
+            [0.9, 0.55, true],
+            [0.85, 0.55, false],
+        ]);
+    });
+    it('reports insufficient labels without hiding evaluated candidates', () => {
+        const report = buildKtxRelationshipThresholdAdviceReport(feedback([
+            label({ candidateId: 'orders:orders.customer_id->customers:customers.id', decision: 'accepted', score: 0.91 }),
+            label({ candidateId: 'orders:orders.note_id->notes:notes.id', decision: 'rejected', score: 0.21 }),
+        ]), {
+            acceptThresholds: [0.9],
+            reviewThresholds: [0.55],
+            minTotalLabels: 10,
+            minAcceptedLabels: 5,
+            minRejectedLabels: 5,
+        });
+        expect(report.status).toBe('insufficient_labels');
+        expect(report.recommended).toBeNull();
+        expect(report.summary).toMatchObject({
+            totalLabels: 2,
+            scoredLabels: 2,
+            acceptedLabels: 1,
+            rejectedLabels: 1,
+            eligibleCandidates: 1,
+        });
+        expect(report.reasons).toEqual([
+            'Need at least 10 scored labels; found 2.',
+            'Need at least 5 accepted labels; found 1.',
+            'Need at least 5 rejected labels; found 1.',
+        ]);
+        expect(report.candidates).toHaveLength(1);
+    });
+    it('reports no eligible thresholds when label counts pass but quality gates fail', () => {
+        const report = buildKtxRelationshipThresholdAdviceReport(feedback([
+            label({ candidateId: 'a', decision: 'accepted', score: 0.92 }),
+            label({ candidateId: 'b', decision: 'accepted', score: 0.58 }),
+            label({ candidateId: 'c', decision: 'rejected', score: 0.91 }),
+            label({ candidateId: 'd', decision: 'rejected', score: 0.2 }),
+        ]), {
+            acceptThresholds: [0.9],
+            reviewThresholds: [0.55],
+            minTotalLabels: 4,
+            minAcceptedLabels: 2,
+            minRejectedLabels: 2,
+            minAcceptedBandPrecision: 0.9,
+        });
+        expect(report.status).toBe('no_eligible_thresholds');
+        expect(report.recommended).toBeNull();
+        expect(report.reasons).toEqual(['No threshold candidate met the precision and recall gates.']);
+        expect(report.candidates[0]).toMatchObject({
+            acceptThreshold: 0.9,
+            reviewThreshold: 0.55,
+            eligible: false,
+            acceptedBandPrecision: 0.5,
+        });
+    });
+    it('wraps the feedback exporter and preserves warnings', async () => {
+        const project = { projectDir: '/tmp/ktx-project' };
+        const exportLocalRelationshipFeedbackLabels = vi.fn(async () => ({
+            ...feedback([]),
+            warnings: [
+                {
+                    path: 'raw-sources/broken/live-database/sync/enrichment/relationship-review-decisions.json',
+                    message: 'Unexpected token',
+                },
+            ],
+        }));
+        const report = await adviseLocalRelationshipFeedbackThresholds(project, {
+            connectionId: 'warehouse',
+            exportLocalRelationshipFeedbackLabels,
+            minTotalLabels: 1,
+        });
+        expect(exportLocalRelationshipFeedbackLabels).toHaveBeenCalledWith(project, {
+            connectionId: 'warehouse',
+            decision: 'all',
+        });
+        expect(report.warnings).toEqual([
+            {
+                path: 'raw-sources/broken/live-database/sync/enrichment/relationship-review-decisions.json',
+                message: 'Unexpected token',
+            },
+        ]);
+    });
+    it('formats a stable human-readable report', () => {
+        const report = buildKtxRelationshipThresholdAdviceReport(feedback([
+            label({ candidateId: 'orders:orders.customer_id->customers:customers.id', decision: 'accepted', score: 0.91 }),
+            label({ candidateId: 'orders:orders.account_id->accounts:accounts.id', decision: 'accepted', score: 0.61 }),
+            label({ candidateId: 'orders:orders.note_id->notes:notes.id', decision: 'rejected', score: 0.21 }),
+            label({ candidateId: 'orders:orders.region_id->regions:regions.id', decision: 'rejected', score: 0.88 }),
+        ]), {
+            acceptThresholds: [0.9],
+            reviewThresholds: [0.55],
+            minTotalLabels: 4,
+            minAcceptedLabels: 2,
+            minRejectedLabels: 2,
+            minAcceptedBandPrecision: 0.75,
+        });
+        expect(formatKtxRelationshipThresholdAdviceMarkdown(report)).toContain('KTX relationship threshold advice');
+        expect(formatKtxRelationshipThresholdAdviceMarkdown(report)).toContain('Status: ready');
+        expect(formatKtxRelationshipThresholdAdviceMarkdown(report)).toContain('Recommended: accept=0.90 review=0.55');
+        expect(formatKtxRelationshipThresholdAdviceMarkdown(report)).toContain('acceptedPrecision=1.000');
+    });
+});

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

@@ -0,0 +1,44 @@
+import { type KtxRelationshipValidationBudget } from './relationship-budget.js';
+import type { KtxRelationshipDiscoveryCandidate } from './relationship-candidates.js';
+import { type KtxRelationshipProfileArtifact, type KtxRelationshipReadOnlyExecutor } from './relationship-profiling.js';
+import type { KtxConnectionDriver, KtxScanContext } from './types.js';
+export type KtxValidatedRelationshipStatus = 'accepted' | 'review' | 'rejected';
+export interface KtxRelationshipValidationSettings {
+    acceptThreshold: number;
+    reviewThreshold: number;
+    minTargetUniqueness: number;
+    minSourceCoverage: number;
+    maxViolationRatio: number;
+    maxDistinctSourceValues: number;
+    concurrency: number;
+    validationBudget?: KtxRelationshipValidationBudget;
+}
+export interface KtxRelationshipValidationEvidence {
+    targetUniqueness: number;
+    sourceCoverage: number;
+    violationCount: number;
+    violationRatio: number;
+    sourceNullRate: number;
+    targetNullRate: number;
+    childDistinct: number;
+    parentDistinct: number;
+    overlap: number;
+    checkedValues: number;
+    reasons: string[];
+}
+export interface KtxValidatedRelationshipDiscoveryCandidate extends Omit<KtxRelationshipDiscoveryCandidate, 'status'> {
+    status: KtxValidatedRelationshipStatus;
+    score: number;
+    validation: KtxRelationshipValidationEvidence;
+}
+export interface ValidateKtxRelationshipDiscoveryCandidatesInput {
+    connectionId: string;
+    driver: KtxConnectionDriver;
+    candidates: readonly KtxRelationshipDiscoveryCandidate[];
+    profiles: KtxRelationshipProfileArtifact;
+    executor: KtxRelationshipReadOnlyExecutor | null;
+    ctx: KtxScanContext;
+    tableCount?: number;
+    settings?: Partial<KtxRelationshipValidationSettings>;
+}
+export declare function validateKtxRelationshipDiscoveryCandidates(input: ValidateKtxRelationshipDiscoveryCandidatesInput): Promise<KtxValidatedRelationshipDiscoveryCandidate[]>;

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

@@ -0,0 +1,240 @@
+import { applyKtxRelationshipValidationBudget } from './relationship-budget.js';
+import { formatKtxRelationshipTableRef, quoteKtxRelationshipIdentifier, } from './relationship-profiling.js';
+const DEFAULT_SETTINGS = {
+    acceptThreshold: 0.85,
+    reviewThreshold: 0.55,
+    minTargetUniqueness: 0.9,
+    minSourceCoverage: 0.9,
+    maxViolationRatio: 0.01,
+    maxDistinctSourceValues: 10000,
+    concurrency: 4,
+};
+function mergeSettings(settings) {
+    return { ...DEFAULT_SETTINGS, ...settings };
+}
+function profileKey(table, column) {
+    return `${table}.${column}`;
+}
+function singleRelationshipColumn(endpointValue) {
+    const column = endpointValue.columns[0];
+    if (!column) {
+        throw new Error(`Expected relationship endpoint ${endpointValue.table.name} to contain one column`);
+    }
+    return column;
+}
+function headerIndex(result, header) {
+    return result.headers.findIndex((candidate) => candidate.toLowerCase() === header.toLowerCase());
+}
+function firstRow(result) {
+    return result.rows[0] ?? [];
+}
+function numberAt(result, header) {
+    const value = firstRow(result)[headerIndex(result, header)];
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'bigint') {
+        return Number(value);
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        return Number(value);
+    }
+    return 0;
+}
+function limitSql(driver, limit) {
+    if (driver === 'sqlserver') {
+        return '';
+    }
+    return ` LIMIT ${Math.max(1, Math.floor(limit))}`;
+}
+function topSql(driver, limit) {
+    if (driver === 'sqlserver') {
+        return ` TOP (${Math.max(1, Math.floor(limit))})`;
+    }
+    return '';
+}
+function buildCoverageSql(input) {
+    const childTable = formatKtxRelationshipTableRef(input.driver, { catalog: null, db: null, name: input.childTable });
+    const parentTable = formatKtxRelationshipTableRef(input.driver, { catalog: null, db: null, name: input.parentTable });
+    const childColumn = quoteKtxRelationshipIdentifier(input.driver, input.childColumn);
+    const parentColumn = quoteKtxRelationshipIdentifier(input.driver, input.parentColumn);
+    const limit = limitSql(input.driver, input.maxDistinctSourceValues);
+    const top = topSql(input.driver, input.maxDistinctSourceValues);
+    return [
+        'WITH child_values AS (',
+        `SELECT DISTINCT${top} ${childColumn} AS value FROM ${childTable} WHERE ${childColumn} IS NOT NULL${limit}`,
+        '), parent_values AS (',
+        `SELECT DISTINCT ${parentColumn} AS value FROM ${parentTable} WHERE ${parentColumn} IS NOT NULL`,
+        ')',
+        'SELECT',
+        '(SELECT COUNT(*) FROM child_values) AS child_distinct,',
+        '(SELECT COUNT(*) FROM parent_values) AS parent_distinct,',
+        'SUM(CASE WHEN parent_values.value IS NOT NULL THEN 1 ELSE 0 END) AS overlap,',
+        'SUM(CASE WHEN parent_values.value IS NULL THEN 1 ELSE 0 END) AS violation_count',
+        'FROM child_values',
+        'LEFT JOIN parent_values ON child_values.value = parent_values.value',
+    ].join(' ');
+}
+function score(input) {
+    const violationScore = Math.max(0, 1 - input.violationRatio);
+    return Number(Math.min(1, 0.2 * input.candidateConfidence +
+        0.3 * input.targetUniqueness +
+        0.4 * input.sourceCoverage +
+        0.1 * violationScore).toFixed(3));
+}
+function statusFor(input) {
+    if (input.reasons.includes('low_target_uniqueness') ||
+        input.reasons.includes('low_source_coverage') ||
+        input.reasons.includes('excessive_violations')) {
+        return 'rejected';
+    }
+    if (input.score >= input.settings.acceptThreshold &&
+        !input.reasons.includes('low_target_uniqueness') &&
+        !input.reasons.includes('low_source_coverage') &&
+        !input.reasons.includes('excessive_violations')) {
+        return 'accepted';
+    }
+    if (input.score >= input.settings.reviewThreshold) {
+        return 'review';
+    }
+    return 'rejected';
+}
+async function mapWithConcurrency(inputs, concurrency, mapOne) {
+    const safeConcurrency = Math.max(1, Math.floor(concurrency));
+    const outputs = new Array(inputs.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < inputs.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            outputs[index] = await mapOne(inputs[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(safeConcurrency, inputs.length) }, () => worker()));
+    return outputs;
+}
+function reviewWithoutValidation(candidate, profiles, reason) {
+    const sourceColumn = singleRelationshipColumn(candidate.from);
+    const targetColumn = singleRelationshipColumn(candidate.to);
+    const sourceProfile = profiles.columns[profileKey(candidate.from.table.name, sourceColumn)];
+    const targetProfile = profiles.columns[profileKey(candidate.to.table.name, targetColumn)];
+    return {
+        ...candidate,
+        status: 'review',
+        score: Number((candidate.confidence * 0.6).toFixed(3)),
+        validation: {
+            targetUniqueness: targetProfile?.uniquenessRatio ?? 0,
+            sourceCoverage: 0,
+            violationCount: 0,
+            violationRatio: 1,
+            sourceNullRate: sourceProfile?.nullRate ?? 0,
+            targetNullRate: targetProfile?.nullRate ?? 0,
+            childDistinct: sourceProfile?.distinctCount ?? 0,
+            parentDistinct: targetProfile?.distinctCount ?? 0,
+            overlap: 0,
+            checkedValues: 0,
+            reasons: [reason],
+        },
+    };
+}
+export async function validateKtxRelationshipDiscoveryCandidates(input) {
+    const settings = mergeSettings(input.settings);
+    if (!input.executor || !input.profiles.sqlAvailable) {
+        return input.candidates.map((candidate) => reviewWithoutValidation(candidate, input.profiles, 'validation_unavailable'));
+    }
+    const executor = input.executor;
+    async function validateCandidate(candidate) {
+        const sourceColumn = singleRelationshipColumn(candidate.from);
+        const targetColumn = singleRelationshipColumn(candidate.to);
+        const sourceProfile = input.profiles.columns[profileKey(candidate.from.table.name, sourceColumn)];
+        const targetProfile = input.profiles.columns[profileKey(candidate.to.table.name, targetColumn)];
+        if (!sourceProfile || !targetProfile) {
+            return reviewWithoutValidation(candidate, input.profiles, 'profile_unavailable');
+        }
+        const result = await executor.executeReadOnly({
+            connectionId: input.connectionId,
+            sql: buildCoverageSql({
+                driver: input.driver,
+                childTable: candidate.from.table.name,
+                childColumn: sourceColumn,
+                parentTable: candidate.to.table.name,
+                parentColumn: targetColumn,
+                maxDistinctSourceValues: settings.maxDistinctSourceValues,
+            }),
+            maxRows: 1,
+        }, input.ctx);
+        const childDistinct = numberAt(result, 'child_distinct');
+        const parentDistinct = numberAt(result, 'parent_distinct');
+        const overlap = numberAt(result, 'overlap');
+        const violationCount = numberAt(result, 'violation_count');
+        const sourceCoverage = childDistinct === 0 ? 0 : overlap / childDistinct;
+        const violationRatio = childDistinct === 0 ? 1 : violationCount / childDistinct;
+        const targetUniqueness = targetProfile.uniquenessRatio;
+        const reasons = [];
+        if (targetUniqueness < settings.minTargetUniqueness) {
+            reasons.push('low_target_uniqueness');
+        }
+        if (sourceCoverage < settings.minSourceCoverage) {
+            reasons.push('low_source_coverage');
+        }
+        if (violationRatio > settings.maxViolationRatio) {
+            reasons.push('excessive_violations');
+        }
+        if (reasons.length === 0) {
+            reasons.push('validation_passed');
+        }
+        const candidateScore = score({
+            candidateConfidence: candidate.confidence,
+            targetUniqueness,
+            sourceCoverage,
+            violationRatio,
+        });
+        const candidateStatus = statusFor({ score: candidateScore, reasons, settings });
+        if (candidate.source === 'llm_proposal' && candidateStatus === 'rejected') {
+            reasons.push('llm_proposed_but_validation_failed');
+        }
+        return {
+            ...candidate,
+            status: candidateStatus,
+            score: candidateScore,
+            validation: {
+                targetUniqueness,
+                sourceCoverage,
+                violationCount,
+                violationRatio,
+                sourceNullRate: sourceProfile.nullRate,
+                targetNullRate: targetProfile.nullRate,
+                childDistinct,
+                parentDistinct,
+                overlap,
+                checkedValues: childDistinct,
+                reasons,
+            },
+        };
+    }
+    const budgeted = applyKtxRelationshipValidationBudget({
+        candidates: input.candidates,
+        tableCount: input.tableCount ?? 0,
+        budget: settings.validationBudget ?? (input.tableCount === undefined ? 'all' : undefined),
+        score: (candidate) => candidate.confidence,
+    });
+    const validated = await mapWithConcurrency(budgeted.toValidate.map((entry) => entry.candidate), settings.concurrency, validateCandidate);
+    const byOriginalIndex = new Map();
+    for (let index = 0; index < budgeted.toValidate.length; index += 1) {
+        const originalIndex = budgeted.toValidate[index]?.originalIndex;
+        const candidate = validated[index];
+        if (originalIndex !== undefined && candidate) {
+            byOriginalIndex.set(originalIndex, candidate);
+        }
+    }
+    for (const entry of budgeted.deferred) {
+        byOriginalIndex.set(entry.originalIndex, reviewWithoutValidation(entry.candidate, input.profiles, 'validation_unattempted'));
+    }
+    return input.candidates.map((_, index) => {
+        const candidate = byOriginalIndex.get(index);
+        if (!candidate) {
+            throw new Error(`Missing relationship validation result for candidate at index ${index}`);
+        }
+        return candidate;
+    });
+}