@x12i/memorix-hippox 1.0.1 → 1.2.0

package/dist/join-discovery.js

@@ -0,0 +1,697 @@
+import { resolveDefaultListDescriptorForEntity } from '@x12i/memorix-retrieval';
+import { listEntityRelations } from '@x12i/memorix-mongo';
+import { loadHippoxConfig } from './config.js';
+import { countObjectTypeDocuments, readObjectTypeDocuments, resolveObjectTypeCollection, } from './collection-resolver.js';
+import { isDateLike, readPath } from './paths.js';
+const ID_SUFFIX_RE = /(?:Id|_id|Ref|_ref)$/i;
+const DEFAULT_DATA_ROOT = 'data';
+const discoveryCache = new Map();
+export function clearJoinDiscoveryCache() {
+    discoveryCache.clear();
+}
+export async function discoverJoinCandidates(options) {
+    const config = loadHippoxConfig(options.processEnv);
+    const input = options.input;
+    const sourceObjectType = input.sourceObjectType?.trim();
+    const targetObjectType = input.targetObjectType?.trim();
+    if (!sourceObjectType || !targetObjectType) {
+        throw new Error('sourceObjectType and targetObjectType are required');
+    }
+    const sampleLimit = Math.min(input.sampleLimit ?? config.discoverySampleLimit, config.discoverySampleLimit);
+    const direction = input.direction ?? 'downstream';
+    const cacheKey = [
+        sourceObjectType,
+        targetObjectType,
+        input.sourceContentType ?? '',
+        input.targetContentType ?? '',
+        direction,
+        String(sampleLimit),
+    ].join('|');
+    const cached = discoveryCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.result;
+    }
+    await assertObjectTypeExists(options.retrieval, sourceObjectType);
+    await assertObjectTypeExists(options.retrieval, targetObjectType);
+    const sourceBinding = await resolveObjectTypeCollection(options.retrieval, sourceObjectType, input.sourceContentType);
+    const targetBinding = await resolveObjectTypeCollection(options.retrieval, targetObjectType, input.targetContentType);
+    const [sourceCount, targetCount] = await Promise.all([
+        countObjectTypeDocuments(options.retrieval, sourceBinding),
+        countObjectTypeDocuments(options.retrieval, targetBinding),
+    ]);
+    const warnings = [];
+    if (sourceCount === 0 && targetCount === 0) {
+        const empty = buildEmptyResult({
+            sourceObjectType,
+            targetObjectType,
+            sourceContentType: sourceBinding.contentType,
+            targetContentType: targetBinding.contentType,
+            sampleLimit,
+            sourceRecordCount: sourceCount,
+            targetRecordCount: targetCount,
+            warnings: [{ code: 'no_sample_data', message: 'Both collections are empty.' }],
+        });
+        cacheResult(cacheKey, empty, config.discoveryCacheTtlMs);
+        return empty;
+    }
+    const driveFromSource = sourceCount <= targetCount;
+    const smallerCount = driveFromSource ? sourceCount : targetCount;
+    const sampleSize = Math.min(sampleLimit, Math.max(smallerCount, 0));
+    const [sourceDocs, targetDocs, seeds, existingLinks] = await Promise.all([
+        sourceCount > 0
+            ? readObjectTypeDocuments(options.retrieval, sourceBinding, { limit: sampleSize })
+            : Promise.resolve([]),
+        targetCount > 0
+            ? readObjectTypeDocuments(options.retrieval, targetBinding, { limit: sampleSize })
+            : Promise.resolve([]),
+        loadDiscoverySeeds(options.retrieval, sourceObjectType, targetObjectType),
+        options.store?.findLinksForObjectTypePair(sourceObjectType, targetObjectType)
+            ?? Promise.resolve({ approved: undefined, simulated: undefined }),
+    ]);
+    const sourceDataRoot = await resolveDataRoot(options.retrieval, sourceObjectType, sourceBinding.contentType);
+    const targetDataRoot = await resolveDataRoot(options.retrieval, targetObjectType, targetBinding.contentType);
+    const approvedJoin = existingLinks.approved?.join[0];
+    const simulatedJoin = existingLinks.simulated?.join[0];
+    const mergedSeeds = {
+        schemaPairs: seeds.schemaPairs,
+        approvedJoin: approvedJoin
+            ? {
+                sourcePath: normalizeDocumentPath(approvedJoin.sourcePath, sourceDataRoot),
+                targetPath: normalizeDocumentPath(approvedJoin.targetPath, targetDataRoot),
+                operator: approvedJoin.operator ?? 'eq',
+            }
+            : undefined,
+        simulatedJoin: simulatedJoin
+            ? {
+                sourcePath: normalizeDocumentPath(simulatedJoin.sourcePath, sourceDataRoot),
+                targetPath: normalizeDocumentPath(simulatedJoin.targetPath, targetDataRoot),
+                operator: simulatedJoin.operator ?? 'eq',
+            }
+            : undefined,
+    };
+    const sourceInventory = buildFieldInventory(sourceDocs, sourceDataRoot, config);
+    const targetInventory = buildFieldInventory(targetDocs, targetDataRoot, config);
+    applySchemaSeeds(sourceInventory, targetInventory, mergedSeeds.schemaPairs, config.discoveryMinCoverage);
+    markApprovedFields(sourceInventory, targetInventory, mergedSeeds);
+    if (sourceInventory.length === 0 && targetInventory.length === 0) {
+        warnings.push({
+            code: 'no_joinable_fields',
+            message: 'No scalar join-safe fields were discovered in sampled documents.',
+        });
+    }
+    const nameTargetType = direction === 'downstream' ? targetObjectType : sourceObjectType;
+    const pairProbes = probeJoinPairs({
+        sourceFields: sourceInventory,
+        targetFields: targetInventory,
+        targetObjectType: nameTargetType,
+        sourceObjectType,
+        seeds: mergedSeeds,
+        distinctCap: config.discoveryDistinctCap,
+        maxPairs: config.discoveryMaxPairs,
+        minCoverage: config.discoveryMinCoverage,
+    });
+    const sourceFields = rankSourceFields(sourceInventory, pairProbes, nameTargetType, mergedSeeds);
+    const targetFields = rankTargetFields(targetInventory, pairProbes, sourceObjectType, mergedSeeds);
+    const joinCandidates = rankJoinCandidates({
+        probes: pairProbes,
+        minPairScore: config.discoveryMinPairScore,
+        maxCandidates: config.discoveryMaxCandidates,
+        approvedJoin: mergedSeeds.approvedJoin,
+    });
+    if (sourceCount > sampleLimit || targetCount > sampleLimit) {
+        warnings.push({
+            code: 'sampled_mode',
+            message: `Discovery used sampling with limit ${sampleLimit}.`,
+        });
+    }
+    const recommendedJoin = joinCandidates.length > 0 && joinCandidates[0].score >= config.discoveryMinPairScore
+        ? {
+            sourcePath: joinCandidates[0].sourcePath,
+            targetPath: joinCandidates[0].targetPath,
+            operator: joinCandidates[0].operator,
+        }
+        : null;
+    const result = {
+        sourceObjectType,
+        targetObjectType,
+        sourceContentType: sourceBinding.contentType,
+        targetContentType: targetBinding.contentType,
+        mode: 'sampled',
+        sampleLimit,
+        sourceRecordCount: sourceCount,
+        targetRecordCount: targetCount,
+        sourceFields,
+        targetFields,
+        joinCandidates,
+        recommendedJoin,
+        warnings,
+    };
+    cacheResult(cacheKey, result, config.discoveryCacheTtlMs);
+    return result;
+}
+function cacheResult(key, result, ttlMs) {
+    if (ttlMs <= 0)
+        return;
+    discoveryCache.set(key, { expiresAt: Date.now() + ttlMs, result });
+}
+function buildEmptyResult(params) {
+    return {
+        sourceObjectType: params.sourceObjectType,
+        targetObjectType: params.targetObjectType,
+        sourceContentType: params.sourceContentType,
+        targetContentType: params.targetContentType,
+        mode: 'sampled',
+        sampleLimit: params.sampleLimit,
+        sourceRecordCount: params.sourceRecordCount,
+        targetRecordCount: params.targetRecordCount,
+        sourceFields: [],
+        targetFields: [],
+        joinCandidates: [],
+        recommendedJoin: null,
+        warnings: params.warnings,
+    };
+}
+async function assertObjectTypeExists(retrieval, objectType) {
+    try {
+        await resolveDefaultListDescriptorForEntity(retrieval, objectType);
+    }
+    catch {
+        throw new Error(`Object type not found: ${objectType}`);
+    }
+}
+async function resolveDataRoot(retrieval, objectType, contentTypeKey) {
+    try {
+        const { entity } = await resolveDefaultListDescriptorForEntity(retrieval, objectType);
+        const ct = entity.contentTypes?.[contentTypeKey];
+        if (ct && typeof ct.dataRoot === 'string')
+            return ct.dataRoot;
+        if (entity.defaults?.dataRoot)
+            return entity.defaults.dataRoot;
+    }
+    catch {
+        // fall through
+    }
+    return DEFAULT_DATA_ROOT;
+}
+async function loadDiscoverySeeds(retrieval, sourceObjectType, targetObjectType) {
+    const relations = await listEntityRelations(retrieval, sourceObjectType);
+    const schemaPairs = relations
+        .filter((rel) => rel.targetEntity === targetObjectType)
+        .map((rel) => ({
+        sourcePath: rel.sourcePath,
+        targetPath: rel.targetPath,
+    }));
+    return { schemaPairs };
+}
+function normalizeDocumentPath(path, dataRoot) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return trimmed;
+    if (trimmed.startsWith(`${dataRoot}.`) || trimmed === dataRoot)
+        return trimmed;
+    if (trimmed.startsWith('data.'))
+        return trimmed;
+    return `${dataRoot}.${trimmed}`;
+}
+function buildFieldInventory(docs, dataRoot, config) {
+    const accumulators = new Map();
+    const sampleCount = docs.length;
+    for (const doc of docs) {
+        const payload = readPath(doc, dataRoot);
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            continue;
+        collectScalarPaths(payload, dataRoot, accumulators);
+    }
+    const paths = [...accumulators.keys()];
+    for (const doc of docs) {
+        for (const path of paths) {
+            const value = readPath(doc, path);
+            touchFieldObservation(accumulators.get(path), value);
+        }
+    }
+    const out = [];
+    for (const acc of accumulators.values()) {
+        const coverage = sampleCount > 0 ? acc.presentCount / sampleCount : 0;
+        if (coverage < config.discoveryMinCoverage && !acc.schemaSeeded)
+            continue;
+        const inferredType = mergeInferredTypes(acc.types);
+        if (!isJoinSafeType(inferredType) && !acc.schemaSeeded)
+            continue;
+        const nonNullCount = acc.presentCount;
+        const distinctValueCount = acc.distinctValues.size;
+        out.push({
+            path: acc.path,
+            inferredType,
+            coverage,
+            distinctValueCount,
+            uniqueness: nonNullCount > 0 ? distinctValueCount / nonNullCount : 0,
+            nonNullCount,
+            distinctValues: acc.distinctValues,
+            schemaSeeded: acc.schemaSeeded,
+            approvedSource: acc.approvedSource,
+            approvedTarget: acc.approvedTarget,
+        });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function collectScalarPaths(obj, prefix, accumulators) {
+    for (const [key, value] of Object.entries(obj)) {
+        const path = `${prefix}.${key}`;
+        if (value === null || value === undefined) {
+            ensureField(accumulators, path);
+            continue;
+        }
+        if (Array.isArray(value))
+            continue;
+        if (typeof value === 'object' && !(value instanceof Date)) {
+            collectScalarPaths(value, path, accumulators);
+            continue;
+        }
+        ensureField(accumulators, path);
+        const acc = accumulators.get(path);
+        acc.types.add(classifyValue(value));
+    }
+}
+function ensureField(accumulators, path) {
+    if (!accumulators.has(path)) {
+        accumulators.set(path, {
+            path,
+            presentCount: 0,
+            types: new Set(),
+            distinctValues: new Set(),
+            schemaSeeded: false,
+            approvedSource: false,
+            approvedTarget: false,
+        });
+    }
+}
+function touchFieldObservation(acc, value) {
+    if (value === null || value === undefined)
+        return;
+    if (!isScalarJoinable(value))
+        return;
+    acc.presentCount += 1;
+    acc.types.add(classifyValue(value));
+    const normalized = normalizeScalarValue(value);
+    if (normalized !== null && acc.distinctValues.size < 500) {
+        acc.distinctValues.add(normalized);
+    }
+}
+export function isScalarJoinable(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return true;
+    if (value instanceof Date)
+        return true;
+    return false;
+}
+export function normalizeScalarValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length ? trimmed : null;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    return null;
+}
+export function classifyValue(value) {
+    if (value === null || value === undefined)
+        return 'mixed';
+    if (typeof value === 'string')
+        return isDateLike(value) ? 'date' : 'string';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (value instanceof Date)
+        return 'date';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'object')
+        return 'object';
+    return 'mixed';
+}
+function mergeInferredTypes(types) {
+    const filtered = [...types].filter((t) => t !== 'mixed');
+    if (filtered.length === 0)
+        return 'mixed';
+    const unique = new Set(filtered);
+    if (unique.size === 1)
+        return [...unique][0];
+    if (unique.has('string') && (unique.has('number') || unique.has('boolean')))
+        return 'mixed';
+    return 'mixed';
+}
+function isJoinSafeType(type) {
+    return type === 'string' || type === 'number' || type === 'boolean' || type === 'date';
+}
+function applySchemaSeeds(sourceFields, targetFields, schemaPairs, minCoverage) {
+    for (const pair of schemaPairs) {
+        ensureInventoryField(sourceFields, pair.sourcePath, minCoverage, true);
+        ensureInventoryField(targetFields, pair.targetPath, minCoverage, true);
+    }
+}
+function ensureInventoryField(fields, path, minCoverage, schemaSeeded) {
+    const existing = fields.find((f) => f.path === path);
+    if (existing) {
+        existing.schemaSeeded = schemaSeeded;
+        return;
+    }
+    fields.push({
+        path,
+        inferredType: 'string',
+        coverage: minCoverage,
+        distinctValueCount: 0,
+        uniqueness: 0,
+        nonNullCount: 0,
+        distinctValues: new Set(),
+        schemaSeeded,
+        approvedSource: false,
+        approvedTarget: false,
+    });
+}
+function markApprovedFields(sourceFields, targetFields, seeds) {
+    if (seeds.approvedJoin) {
+        const source = sourceFields.find((f) => f.path === seeds.approvedJoin.sourcePath);
+        const target = targetFields.find((f) => f.path === seeds.approvedJoin.targetPath);
+        if (source)
+            source.approvedSource = true;
+        if (target)
+            target.approvedTarget = true;
+    }
+}
+function probeJoinPairs(params) {
+    const { sourceFields, targetFields, sourceObjectType, targetObjectType, seeds, distinctCap, maxPairs, minCoverage, } = params;
+    let sourceCandidates = [...sourceFields];
+    let targetCandidates = [...targetFields];
+    if (sourceCandidates.length * targetCandidates.length > maxPairs) {
+        const k = Math.max(2, Math.floor(Math.sqrt(maxPairs)));
+        sourceCandidates = prefilterFields(sourceCandidates, 'source', targetObjectType, seeds, k);
+        targetCandidates = prefilterFields(targetCandidates, 'target', sourceObjectType, seeds, k);
+    }
+    const targetValueSets = new Map();
+    for (const field of targetCandidates) {
+        targetValueSets.set(field.path, field.distinctValues);
+    }
+    const probes = [];
+    for (const source of sourceCandidates) {
+        const sourceValues = [...source.distinctValues].slice(0, distinctCap);
+        if (sourceValues.length === 0 && !source.schemaSeeded && source.coverage < 0.2)
+            continue;
+        for (const target of targetCandidates) {
+            const targetValues = targetValueSets.get(target.path) ?? new Set();
+            const valueHitRate = computeValueHitRate(sourceValues, targetValues);
+            const schemaRelationBoost = seeds.schemaPairs.some((p) => p.sourcePath === source.path && p.targetPath === target.path)
+                ? 1
+                : 0;
+            const approvedLinkBoost = seeds.approvedJoin?.sourcePath === source.path && seeds.approvedJoin?.targetPath === target.path
+                ? 1
+                : seeds.simulatedJoin?.sourcePath === source.path && seeds.simulatedJoin?.targetPath === target.path
+                    ? 0.5
+                    : 0;
+            probes.push({
+                sourcePath: source.path,
+                targetPath: target.path,
+                valueHitRate,
+                sourceCoverage: source.coverage,
+                targetCoverage: target.coverage,
+                targetUniqueness: target.uniqueness,
+                nameSimilarity: computeNameSimilarity(source.path, target.path, targetObjectType),
+                schemaRelationBoost,
+                approvedLinkBoost,
+                sourceType: source.inferredType,
+                targetType: target.inferredType,
+            });
+        }
+    }
+    return probes.filter((probe) => {
+        if (probe.schemaRelationBoost > 0 || probe.approvedLinkBoost > 0)
+            return true;
+        if (probe.sourceCoverage < minCoverage)
+            return false;
+        if (probe.sourceCoverage < 0.2)
+            return false;
+        return true;
+    });
+}
+function prefilterFields(fields, side, otherObjectType, seeds, limit) {
+    const scored = fields.map((field) => {
+        let score = field.coverage * 0.4;
+        score += side === 'source'
+            ? sourceNameHintScore(field.path, otherObjectType) * 0.3
+            : targetNameHintScore(field.path, otherObjectType) * 0.3;
+        if (field.schemaSeeded)
+            score += 0.2;
+        if (field.approvedSource || field.approvedTarget)
+            score += 0.1;
+        if (side === 'target')
+            score += field.uniqueness * 0.2;
+        return { field, score };
+    });
+    scored.sort((a, b) => b.score - a.score || a.field.path.localeCompare(b.field.path));
+    return scored.slice(0, limit).map((row) => row.field);
+}
+export function computeValueHitRate(sourceValues, targetValues) {
+    if (sourceValues.length === 0 || targetValues.size === 0)
+        return 0;
+    let hits = 0;
+    for (const value of sourceValues) {
+        if (targetValues.has(value))
+            hits += 1;
+    }
+    return hits / sourceValues.length;
+}
+export function computeNameSimilarity(sourcePath, targetPath, targetObjectType) {
+    const sourceLeaf = leafName(sourcePath).toLowerCase();
+    const targetLeaf = leafName(targetPath).toLowerCase();
+    const targetType = targetObjectType.toLowerCase();
+    const targetStem = entityStem(targetType);
+    if (sourceLeaf === targetLeaf)
+        return 1;
+    if (sourceLeaf === `${targetType}id` || sourceLeaf === `${targetType}_id`)
+        return 0.95;
+    if (sourceLeaf === `${targetStem}id` || sourceLeaf === `${targetStem}_id`)
+        return 0.95;
+    if (sourceLeaf.endsWith('id') && (sourceLeaf.includes(targetType) || sourceLeaf.includes(targetStem))) {
+        return 0.85;
+    }
+    if (targetLeaf === 'id' || targetLeaf.endsWith('id'))
+        return 0.7;
+    if (ID_SUFFIX_RE.test(leafName(sourcePath)) || ID_SUFFIX_RE.test(leafName(targetPath)))
+        return 0.55;
+    return 0;
+}
+function leafName(path) {
+    const segments = path.split('.');
+    return segments[segments.length - 1] ?? path;
+}
+function entityStem(name) {
+    const lower = name.toLowerCase();
+    return lower.endsWith('s') && lower.length > 1 ? lower.slice(0, -1) : lower;
+}
+export function sourceNameHintScore(path, targetObjectType) {
+    const leaf = leafName(path);
+    const lower = leaf.toLowerCase();
+    const target = targetObjectType.toLowerCase();
+    const targetStem = entityStem(target);
+    if (lower === `${target}id` || lower === `${target}_id`)
+        return 1;
+    if (lower === `${targetStem}id` || lower === `${targetStem}_id`)
+        return 0.95;
+    if (lower.endsWith('id') && (lower.includes(target) || lower.includes(targetStem)))
+        return 0.85;
+    if (ID_SUFFIX_RE.test(leaf))
+        return 0.55;
+    return 0;
+}
+export function targetNameHintScore(path, sourceObjectType) {
+    const leaf = leafName(path);
+    const lower = leaf.toLowerCase();
+    if (lower === 'id')
+        return 1;
+    if (lower.endsWith('id'))
+        return 0.75;
+    const sourceLeaf = sourceObjectType.toLowerCase();
+    if (lower.includes(sourceLeaf))
+        return 0.5;
+    return 0;
+}
+export function computePairScore(probe) {
+    let score = 0.55 * probe.valueHitRate
+        + 0.15 * Math.min(probe.sourceCoverage, probe.targetCoverage)
+        + 0.15 * probe.targetUniqueness
+        + 0.10 * probe.nameSimilarity
+        + probe.schemaRelationBoost * 0.15
+        + probe.approvedLinkBoost * 0.20;
+    if (typesMismatch(probe.sourceType, probe.targetType)) {
+        score *= 0.3;
+    }
+    if (probe.targetUniqueness < 0.5) {
+        score *= 0.6;
+    }
+    return clamp01(score);
+}
+function typesMismatch(sourceType, targetType) {
+    if (sourceType === targetType)
+        return false;
+    if ((sourceType === 'string' && targetType === 'number')
+        || (sourceType === 'number' && targetType === 'string')) {
+        return true;
+    }
+    return sourceType !== 'mixed' && targetType !== 'mixed' && sourceType !== targetType;
+}
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+function rankSourceFields(inventory, probes, targetObjectType, seeds) {
+    const bestHitBySource = new Map();
+    for (const probe of probes) {
+        const current = bestHitBySource.get(probe.sourcePath) ?? 0;
+        bestHitBySource.set(probe.sourcePath, Math.max(current, probe.valueHitRate));
+    }
+    const scored = inventory.map((field) => {
+        const bestHit = bestHitBySource.get(field.path) ?? 0;
+        const score = clamp01(0.50 * bestHit
+            + 0.15 * field.coverage
+            + 0.15 * sourceNameHintScore(field.path, targetObjectType)
+            + (field.schemaSeeded ? 0.10 : 0)
+            + (field.approvedSource ? 0.10 : 0));
+        const reasons = buildSourceReasons(field, bestHit, targetObjectType, seeds);
+        return { field, score, reasons };
+    });
+    scored.sort((a, b) => b.score - a.score || a.field.path.localeCompare(b.field.path));
+    return scored.map((row, index) => ({
+        path: row.field.path,
+        inferredType: row.field.inferredType,
+        rank: index + 1,
+        score: row.score,
+        coverage: row.field.coverage,
+        distinctValueCount: row.field.distinctValueCount,
+        reasons: row.reasons,
+    }));
+}
+function rankTargetFields(inventory, probes, sourceObjectType, seeds) {
+    const bestHitByTarget = new Map();
+    for (const probe of probes) {
+        const current = bestHitByTarget.get(probe.targetPath) ?? 0;
+        bestHitByTarget.set(probe.targetPath, Math.max(current, probe.valueHitRate));
+    }
+    const scored = inventory.map((field) => {
+        const bestHit = bestHitByTarget.get(field.path) ?? 0;
+        const score = clamp01(0.45 * bestHit
+            + 0.25 * field.uniqueness
+            + 0.10 * field.coverage
+            + 0.10 * targetNameHintScore(field.path, sourceObjectType)
+            + (field.schemaSeeded ? 0.10 : 0));
+        const reasons = buildTargetReasons(field, bestHit, seeds);
+        return { field, score, reasons };
+    });
+    scored.sort((a, b) => b.score - a.score || a.field.path.localeCompare(b.field.path));
+    return scored.map((row, index) => ({
+        path: row.field.path,
+        inferredType: row.field.inferredType,
+        rank: index + 1,
+        score: row.score,
+        coverage: row.field.coverage,
+        distinctValueCount: row.field.distinctValueCount,
+        uniqueness: row.field.uniqueness,
+        reasons: row.reasons,
+    }));
+}
+function buildSourceReasons(field, bestHit, targetObjectType, seeds) {
+    const reasons = [];
+    if (bestHit >= 0.5)
+        reasons.push('high_value_hit_rate');
+    if (sourceNameHintScore(field.path, targetObjectType) >= 0.55) {
+        reasons.push('name_contains_target_type');
+    }
+    if (field.approvedSource)
+        reasons.push('approved_link_history');
+    if (field.schemaSeeded)
+        reasons.push('schema_relation');
+    if (seeds.schemaPairs.some((pair) => pair.sourcePath === field.path)
+        && !reasons.includes('schema_relation')) {
+        reasons.push('schema_relation');
+    }
+    return reasons;
+}
+function buildTargetReasons(field, bestHit, seeds) {
+    const reasons = [];
+    if (leafName(field.path).toLowerCase() === 'id')
+        reasons.push('primary_identifier');
+    if (bestHit >= 0.5)
+        reasons.push('high_value_hit_rate');
+    if (field.uniqueness >= 0.95)
+        reasons.push('near_unique_values');
+    if (field.schemaSeeded)
+        reasons.push('schema_relation');
+    if (seeds.approvedJoin?.targetPath === field.path
+        && !reasons.includes('approved_link_history')) {
+        reasons.push('approved_link_history');
+    }
+    return reasons;
+}
+function rankJoinCandidates(params) {
+    const candidates = params.probes
+        .map((probe) => {
+        const score = computePairScore(probe);
+        return { probe, score };
+    })
+        .filter((row) => row.score >= params.minPairScore)
+        .sort((a, b) => {
+        if (params.approvedJoin) {
+            const aApproved = a.probe.sourcePath === params.approvedJoin.sourcePath
+                && a.probe.targetPath === params.approvedJoin.targetPath;
+            const bApproved = b.probe.sourcePath === params.approvedJoin.sourcePath
+                && b.probe.targetPath === params.approvedJoin.targetPath;
+            if (aApproved !== bApproved)
+                return aApproved ? -1 : 1;
+        }
+        return b.score - a.score
+            || a.probe.sourcePath.localeCompare(b.probe.sourcePath)
+            || a.probe.targetPath.localeCompare(b.probe.targetPath);
+    })
+        .slice(0, params.maxCandidates);
+    return candidates.map((row, index) => ({
+        rank: index + 1,
+        score: row.score,
+        sourcePath: row.probe.sourcePath,
+        targetPath: row.probe.targetPath,
+        operator: 'eq',
+        signals: {
+            valueHitRate: row.probe.valueHitRate,
+            sourceCoverage: row.probe.sourceCoverage,
+            targetUniqueness: row.probe.targetUniqueness,
+            nameSimilarity: row.probe.nameSimilarity,
+            schemaRelationBoost: row.probe.schemaRelationBoost,
+            approvedLinkBoost: row.probe.approvedLinkBoost >= 1 ? 1 : row.probe.approvedLinkBoost,
+        },
+        summary: buildCandidateSummary(row.probe),
+    }));
+}
+function buildCandidateSummary(probe) {
+    const hitPct = Math.round(probe.valueHitRate * 100);
+    if (probe.approvedLinkBoost >= 1) {
+        return 'Previously approved Hippox link for this object-type pair.';
+    }
+    if (probe.valueHitRate >= 0.5) {
+        const uniquenessNote = probe.targetUniqueness >= 0.95
+            ? 'target values are unique.'
+            : 'target values may not be unique.';
+        return `${hitPct}% of sampled source values appear in target field; ${uniquenessNote}`;
+    }
+    if (probe.schemaRelationBoost > 0) {
+        return 'Declared in Memorix schema relations for this object-type pair.';
+    }
+    return `${hitPct}% value overlap between sampled source and target fields.`;
+}
+//# sourceMappingURL=join-discovery.js.map