@kaelio/ktx 0.0.0 → 0.1.0-rc.1

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

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+import { generateKtxObject } from '../llm/index.js';
+import { normalizeKtxRelationshipName, } from './relationship-candidates.js';
+const relationshipLlmProposalSchema = z.object({
+    pkCandidates: z.array(z.object({
+        table: z.string(),
+        column: z.string(),
+        confidence: z.number(),
+        rationale: z.string(),
+    })),
+    fkCandidates: z.array(z.object({
+        fromTable: z.string(),
+        fromColumn: z.string(),
+        toTable: z.string(),
+        toColumn: z.string(),
+        confidence: z.number(),
+        rationale: z.string(),
+    })),
+});
+const DEFAULT_SETTINGS = {
+    maxTablesPerBatch: 40,
+    maxColumnsPerTable: 80,
+    maxSampleValuesPerColumn: 5,
+    minConfidence: 0.55,
+};
+function mergeSettings(settings) {
+    return { ...DEFAULT_SETTINGS, ...settings };
+}
+function clampConfidence(value) {
+    return Number(Math.max(0, Math.min(1, value)).toFixed(3));
+}
+function findTable(schema, name) {
+    const normalized = name.toLowerCase();
+    return schema.tables.find((table) => table.ref.name.toLowerCase() === normalized) ?? null;
+}
+function findColumn(table, name) {
+    const normalized = name.toLowerCase();
+    return table.columns.find((column) => column.name.toLowerCase() === normalized) ?? null;
+}
+function profileKey(table, column) {
+    return `${table.name}.${column.name}`;
+}
+function profileForColumn(profile, table, column) {
+    return profile.columns[profileKey(table.ref, column)] ?? null;
+}
+function rowCountForTable(profile, table) {
+    return profile.tables.find((item) => item.table.name.toLowerCase() === table.ref.name.toLowerCase())?.rowCount ?? null;
+}
+function buildEvidencePacket(schema, profile, settings) {
+    return {
+        connectionId: schema.connectionId,
+        sqlAvailable: profile.sqlAvailable,
+        tables: schema.tables
+            .filter((table) => table.enabled)
+            .slice(0, settings.maxTablesPerBatch)
+            .map((table) => ({
+            name: table.ref.name,
+            catalog: table.ref.catalog,
+            db: table.ref.db,
+            rowCount: rowCountForTable(profile, table),
+            columns: table.columns.slice(0, settings.maxColumnsPerTable).map((column) => {
+                const columnProfile = profileForColumn(profile, table, column);
+                return {
+                    name: column.name,
+                    nativeType: column.nativeType,
+                    normalizedType: column.normalizedType,
+                    dimensionType: column.dimensionType,
+                    nullable: column.nullable,
+                    declaredPrimaryKey: column.primaryKey,
+                    profile: columnProfile
+                        ? {
+                            rowCount: columnProfile.rowCount,
+                            nullCount: columnProfile.nullCount,
+                            distinctCount: columnProfile.distinctCount,
+                            uniquenessRatio: columnProfile.uniquenessRatio,
+                            nullRate: columnProfile.nullRate,
+                            sampleValues: columnProfile.sampleValues.slice(0, settings.maxSampleValuesPerColumn),
+                        }
+                        : null,
+                };
+            }),
+        })),
+    };
+}
+function pkProposalKey(table, column) {
+    return `${table.toLowerCase()}.${column.toLowerCase()}`;
+}
+function endpoint(table, column) {
+    return {
+        tableId: table.id,
+        columnIds: [column.id],
+        table: table.ref,
+        columns: [column.name],
+    };
+}
+function relationshipId(fromTable, fromColumn, toTable, toColumn) {
+    return `${fromTable.id}:(${fromColumn.id})->${toTable.id}:(${toColumn.id})`;
+}
+function invalidReferenceWarning(message, metadata) {
+    return {
+        code: 'relationship_llm_invalid_reference',
+        message,
+        recoverable: true,
+        metadata,
+    };
+}
+function mapValidProposals(schema, output, settings) {
+    const warnings = [];
+    const pkProposals = new Set(output.pkCandidates.map((item) => pkProposalKey(item.table, item.column)));
+    const candidates = [];
+    for (const item of output.fkCandidates) {
+        if (item.confidence < settings.minConfidence) {
+            continue;
+        }
+        const fromTable = findTable(schema, item.fromTable);
+        const toTable = findTable(schema, item.toTable);
+        const fromColumn = fromTable ? findColumn(fromTable, item.fromColumn) : null;
+        const toColumn = toTable ? findColumn(toTable, item.toColumn) : null;
+        if (!fromTable || !toTable || !fromColumn || !toColumn) {
+            warnings.push(invalidReferenceWarning('KTX relationship LLM proposal referenced a table or column that is not in the schema.', {
+                proposal: item,
+            }));
+            continue;
+        }
+        const pkProposalExists = pkProposals.has(pkProposalKey(toTable.ref.name, toColumn.name));
+        candidates.push({
+            id: relationshipId(fromTable, fromColumn, toTable, toColumn),
+            from: endpoint(fromTable, fromColumn),
+            to: endpoint(toTable, toColumn),
+            source: 'llm_proposal',
+            status: 'review',
+            relationshipType: 'many_to_one',
+            confidence: clampConfidence(item.confidence),
+            evidence: {
+                sourceColumnBase: normalizeKtxRelationshipName(fromColumn.name).singular,
+                targetTableBase: normalizeKtxRelationshipName(toTable.ref.name).singular,
+                targetColumnBase: normalizeKtxRelationshipName(toColumn.name).singular,
+                targetKeyScore: pkProposalExists ? 0.88 : 0.68,
+                nameScore: 0.45,
+                reasons: pkProposalExists ? ['llm_proposal', 'llm_pk_proposal'] : ['llm_proposal'],
+                llmConfidence: clampConfidence(item.confidence),
+                llmRationale: item.rationale,
+            },
+        });
+    }
+    return { candidates, warnings };
+}
+function generationFailureWarning(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: 'relationship_llm_proposal_failed',
+        message: `KTX relationship LLM proposal failed: ${message}`,
+        recoverable: true,
+    };
+}
+export async function proposeKtxRelationshipCandidatesWithLlm(input) {
+    if (!input.llmRuntime) {
+        return { candidates: [], warnings: [], llmCalls: 0, summary: 'skipped' };
+    }
+    const settings = mergeSettings(input.settings);
+    const evidence = buildEvidencePacket(input.schema, input.profile, settings);
+    const system = [
+        'You are helping KTX review possible SQL relationships before validation.',
+        'Use only the compact schema evidence. Propose likely primary keys and foreign keys for later SQL validation.',
+        'Return structured output only; never assume a join is accepted.',
+    ].join('\n');
+    const prompt = JSON.stringify(evidence);
+    try {
+        const generated = await generateKtxObject({
+            runtime: input.llmRuntime,
+            role: 'candidateExtraction',
+            system,
+            prompt,
+            schema: relationshipLlmProposalSchema,
+        });
+        const output = relationshipLlmProposalSchema.parse(generated);
+        const mapped = mapValidProposals(input.schema, output, settings);
+        return {
+            candidates: mapped.candidates,
+            warnings: mapped.warnings,
+            llmCalls: 1,
+            summary: 'completed',
+        };
+    }
+    catch (error) {
+        return {
+            candidates: [],
+            warnings: [generationFailureWarning(error)],
+            llmCalls: 1,
+            summary: 'failed',
+        };
+    }
+}

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

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

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

@@ -0,0 +1,197 @@
+import { describe, expect, it, vi } from 'vitest';
+import { proposeKtxRelationshipCandidatesWithLlm } from './relationship-llm-proposal.js';
+function llmRuntime(output) {
+    return {
+        generateText: vi.fn(),
+        generateObject: vi.fn(async () => output),
+        runAgentLoop: vi.fn(),
+    };
+}
+function column(tableId, name, overrides = {}) {
+    const tableRef = overrides.tableRef ?? { catalog: null, db: null, name: tableId };
+    return {
+        id: `${tableId}.${name}`,
+        tableId,
+        tableRef,
+        name,
+        nativeType: overrides.nativeType ?? 'INTEGER',
+        normalizedType: overrides.normalizedType ?? 'integer',
+        dimensionType: overrides.dimensionType ?? 'number',
+        nullable: overrides.nullable ?? true,
+        primaryKey: overrides.primaryKey ?? false,
+        parentColumnId: null,
+        descriptions: {},
+        embedding: null,
+        sampleValues: null,
+        cardinality: null,
+        ...overrides,
+    };
+}
+function table(name, columns) {
+    const ref = { catalog: null, db: null, name };
+    return {
+        id: name,
+        ref,
+        enabled: true,
+        descriptions: {},
+        columns: columns.map((item) => ({ ...item, tableId: name, tableRef: ref })),
+    };
+}
+function schema() {
+    return {
+        connectionId: 'warehouse',
+        relationships: [],
+        tables: [
+            table('customers', [
+                column('customers', 'id', { nullable: false }),
+                column('customers', 'email', { nativeType: 'TEXT', normalizedType: 'text', dimensionType: 'string' }),
+            ]),
+            table('orders', [
+                column('orders', 'id', { nullable: false }),
+                column('orders', 'buyer_ref'),
+            ]),
+        ],
+    };
+}
+function profile() {
+    return {
+        connectionId: 'warehouse',
+        driver: 'sqlite',
+        sqlAvailable: true,
+        queryCount: 4,
+        warnings: [],
+        tables: [
+            { table: { catalog: null, db: null, name: 'customers' }, rowCount: 2 },
+            { table: { catalog: null, db: null, name: 'orders' }, rowCount: 2 },
+        ],
+        columns: {
+            'customers.id': {
+                table: { catalog: null, db: null, name: 'customers' },
+                column: 'id',
+                nativeType: 'INTEGER',
+                normalizedType: 'integer',
+                rowCount: 2,
+                nullCount: 0,
+                distinctCount: 2,
+                uniquenessRatio: 1,
+                nullRate: 0,
+                sampleValues: ['1', '2'],
+                minTextLength: 1,
+                maxTextLength: 1,
+            },
+            'orders.buyer_ref': {
+                table: { catalog: null, db: null, name: 'orders' },
+                column: 'buyer_ref',
+                nativeType: 'INTEGER',
+                normalizedType: 'integer',
+                rowCount: 2,
+                nullCount: 0,
+                distinctCount: 2,
+                uniquenessRatio: 1,
+                nullRate: 0,
+                sampleValues: ['1', '2'],
+                minTextLength: 1,
+                maxTextLength: 1,
+            },
+        },
+    };
+}
+describe('relationship LLM proposals', () => {
+    it('maps valid structured FK proposals into review candidates with rationale evidence', async () => {
+        const runtime = llmRuntime({
+            pkCandidates: [{ table: 'customers', column: 'id', confidence: 0.94, rationale: 'Unique customer identifier.' }],
+            fkCandidates: [
+                {
+                    fromTable: 'orders',
+                    fromColumn: 'buyer_ref',
+                    toTable: 'customers',
+                    toColumn: 'id',
+                    confidence: 0.88,
+                    rationale: 'Buyer reference values match customer identifiers.',
+                },
+            ],
+        });
+        const result = await proposeKtxRelationshipCandidatesWithLlm({
+            connectionId: 'warehouse',
+            schema: schema(),
+            profile: profile(),
+            llmRuntime: runtime,
+        });
+        expect(result.summary).toBe('completed');
+        expect(result.llmCalls).toBe(1);
+        expect(result.warnings).toEqual([]);
+        expect(result.candidates).toHaveLength(1);
+        expect(result.candidates[0]).toMatchObject({
+            from: { tableId: 'orders', columnIds: ['orders.buyer_ref'], columns: ['buyer_ref'] },
+            to: { tableId: 'customers', columnIds: ['customers.id'], columns: ['id'] },
+            source: 'llm_proposal',
+            status: 'review',
+            evidence: {
+                llmConfidence: 0.88,
+                llmRationale: 'Buyer reference values match customer identifiers.',
+                reasons: ['llm_proposal', 'llm_pk_proposal'],
+            },
+        });
+        expect(runtime.generateObject).toHaveBeenCalledWith(expect.objectContaining({
+            role: 'candidateExtraction',
+            system: expect.stringContaining('You are helping KTX review possible SQL relationships'),
+            prompt: expect.stringContaining('"tables"'),
+        }));
+        const call = vi.mocked(runtime.generateObject).mock.calls[0]?.[0];
+        expect(call?.prompt).not.toContain('You are helping KTX review possible SQL relationships');
+    });
+    it('skips when no runtime is configured', async () => {
+        const result = await proposeKtxRelationshipCandidatesWithLlm({
+            connectionId: 'warehouse',
+            schema: schema(),
+            profile: profile(),
+            llmRuntime: null,
+        });
+        expect(result).toMatchObject({ candidates: [], llmCalls: 0, summary: 'skipped' });
+        expect(result.warnings).toEqual([]);
+    });
+    it('returns recoverable warnings for invalid references and generation failures', async () => {
+        const invalidReference = await proposeKtxRelationshipCandidatesWithLlm({
+            connectionId: 'warehouse',
+            schema: schema(),
+            profile: profile(),
+            llmRuntime: llmRuntime({
+                pkCandidates: [],
+                fkCandidates: [
+                    {
+                        fromTable: 'orders',
+                        fromColumn: 'missing_column',
+                        toTable: 'customers',
+                        toColumn: 'id',
+                        confidence: 0.7,
+                        rationale: 'Invalid source column.',
+                    },
+                ],
+            }),
+        });
+        expect(invalidReference.candidates).toEqual([]);
+        expect(invalidReference.summary).toBe('completed');
+        expect(invalidReference.warnings[0]).toMatchObject({
+            code: 'relationship_llm_invalid_reference',
+            recoverable: true,
+        });
+        const failed = await proposeKtxRelationshipCandidatesWithLlm({
+            connectionId: 'warehouse',
+            schema: schema(),
+            profile: profile(),
+            llmRuntime: {
+                generateText: vi.fn(),
+                generateObject: vi.fn(async () => {
+                    throw new Error('model unavailable');
+                }),
+                runAgentLoop: vi.fn(),
+            },
+        });
+        expect(failed).toMatchObject({ candidates: [], llmCalls: 1, summary: 'failed' });
+        expect(failed.warnings[0]).toMatchObject({
+            code: 'relationship_llm_proposal_failed',
+            message: 'KTX relationship LLM proposal failed: model unavailable',
+            recoverable: true,
+        });
+    });
+});

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

@@ -0,0 +1,15 @@
+import type { KtxEnrichedColumn, KtxEnrichedTable } from './enrichment-types.js';
+export interface KtxRelationshipLocalityCandidateTable {
+    table: KtxEnrichedTable;
+    score: number;
+    tokenScore: number;
+    embeddingScore: number;
+    reasons: string[];
+}
+export interface LocalKtxRelationshipCandidateTablesInput {
+    childTable: KtxEnrichedTable;
+    childColumn: KtxEnrichedColumn;
+    parentTables: readonly KtxEnrichedTable[];
+    maxParentTables?: number;
+}
+export declare function localCandidateTables(input: LocalKtxRelationshipCandidateTablesInput): KtxRelationshipLocalityCandidateTable[];

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

@@ -0,0 +1,129 @@
+import { normalizeKtxRelationshipName, tokenizeKtxRelationshipName } from './relationship-name-similarity.js';
+const DEFAULT_MAX_PARENT_TABLES = 20;
+const RELATIONSHIP_SUFFIX_TOKENS = new Set(['id', 'ids', 'key', 'keys', 'code', 'codes', 'uuid', 'uuids']);
+const normalizedTokenVariantsCache = new Map();
+function roundedScore(value) {
+    return Number(Math.max(0, Math.min(1, value)).toFixed(3));
+}
+function normalizedTokenVariants(name) {
+    const cached = normalizedTokenVariantsCache.get(name);
+    if (cached) {
+        return cached;
+    }
+    const normalized = normalizeKtxRelationshipName(name);
+    const variants = Array.from(new Set([
+        ...normalized.tokens,
+        ...tokenizeKtxRelationshipName(normalized.singular),
+        ...tokenizeKtxRelationshipName(normalized.plural),
+    ])).filter(Boolean);
+    normalizedTokenVariantsCache.set(name, variants);
+    return variants;
+}
+function childColumnLocalityTokens(column) {
+    const tokens = normalizedTokenVariants(column.name);
+    const withoutSuffix = tokens.filter((token) => !RELATIONSHIP_SUFFIX_TOKENS.has(token));
+    return withoutSuffix.length > 0 ? withoutSuffix : tokens;
+}
+function uniqueTokens(values) {
+    return Array.from(new Set(values.filter((value) => value.length > 0)));
+}
+function jaccard(left, right) {
+    if (left.length === 0 || right.length === 0) {
+        return 0;
+    }
+    const leftSet = new Set(left);
+    const rightSet = new Set(right);
+    const intersectionSize = Array.from(leftSet).filter((token) => rightSet.has(token)).length;
+    const unionSize = new Set([...leftSet, ...rightSet]).size;
+    return unionSize === 0 ? 0 : intersectionSize / unionSize;
+}
+function cosineSimilarity(left, right) {
+    if (!left || !right || left.length === 0 || left.length !== right.length) {
+        return 0;
+    }
+    let dot = 0;
+    let leftMagnitude = 0;
+    let rightMagnitude = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        const leftValue = left[index] ?? 0;
+        const rightValue = right[index] ?? 0;
+        dot += leftValue * rightValue;
+        leftMagnitude += leftValue * leftValue;
+        rightMagnitude += rightValue * rightValue;
+    }
+    if (leftMagnitude === 0 || rightMagnitude === 0) {
+        return 0;
+    }
+    return dot / (Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude));
+}
+function parentEmbeddingScore(childColumn, parentTable) {
+    if (!Array.isArray(childColumn.embedding) || childColumn.embedding.length === 0) {
+        return 0;
+    }
+    let best = 0;
+    for (const parentColumn of parentTable.columns) {
+        best = Math.max(best, cosineSimilarity(childColumn.embedding, parentColumn.embedding));
+    }
+    return best;
+}
+function tableTokenScore(input) {
+    const parentTokens = normalizedTokenVariants(input.parentTable.ref.name);
+    const columnOnlyScore = jaccard(input.childColumnTokens, parentTokens);
+    if (parentTokens.length === 0) {
+        return 0;
+    }
+    if (input.parentTable.id === input.childTableId) {
+        return columnOnlyScore;
+    }
+    const columnAndTableScore = jaccard(uniqueTokens([...input.childTableTokens, ...input.childColumnTokens]), parentTokens);
+    return Math.max(columnOnlyScore, columnAndTableScore * 0.6);
+}
+function localityScore(input) {
+    const tokenScore = roundedScore(tableTokenScore(input));
+    const embeddingScore = roundedScore(parentEmbeddingScore(input.childColumn, input.parentTable));
+    const score = embeddingScore > 0
+        ? roundedScore(Math.max(tokenScore, tokenScore * 0.8 + embeddingScore * 0.2, embeddingScore * 0.65))
+        : tokenScore;
+    const reasons = [];
+    if (tokenScore > 0) {
+        reasons.push('column_table_token_overlap');
+    }
+    if (embeddingScore > 0) {
+        reasons.push('embedding_similarity');
+    }
+    if (reasons.length === 0) {
+        reasons.push('locality_tie_breaker');
+    }
+    return {
+        score,
+        tokenScore,
+        embeddingScore,
+        reasons,
+    };
+}
+export function localCandidateTables(input) {
+    const limit = input.maxParentTables ?? DEFAULT_MAX_PARENT_TABLES;
+    if (!Number.isFinite(limit) || limit <= 0) {
+        return [];
+    }
+    const childTableTokens = normalizedTokenVariants(input.childTable.ref.name);
+    const childColumnTokens = childColumnLocalityTokens(input.childColumn);
+    return input.parentTables
+        .map((table) => ({
+        table,
+        ...localityScore({
+            childTable: input.childTable,
+            childTableId: input.childTable.id,
+            childTableTokens,
+            childColumn: input.childColumn,
+            childColumnTokens,
+            parentTable: table,
+        }),
+    }))
+        .sort((left, right) => right.score - left.score ||
+        right.tokenScore - left.tokenScore ||
+        right.embeddingScore - left.embeddingScore ||
+        left.table.ref.name.localeCompare(right.table.ref.name) ||
+        left.table.id.localeCompare(right.table.id))
+        .slice(0, Math.floor(limit));
+}

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

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

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

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import { localCandidateTables } from './relationship-locality.js';
+function column(tableId, id, name, options = {}) {
+    const tableRef = options.tableRef ?? { catalog: null, db: 'public', name: tableId };
+    return {
+        id,
+        tableId,
+        tableRef,
+        name,
+        nativeType: options.nativeType ?? 'INTEGER',
+        normalizedType: options.normalizedType ?? 'integer',
+        dimensionType: options.dimensionType ?? 'number',
+        nullable: options.nullable ?? true,
+        primaryKey: options.primaryKey ?? false,
+        parentColumnId: options.parentColumnId ?? null,
+        descriptions: options.descriptions ?? {},
+        embedding: options.embedding ?? null,
+        sampleValues: options.sampleValues ?? null,
+        cardinality: options.cardinality ?? null,
+    };
+}
+function table(id, name, columns) {
+    const ref = { catalog: null, db: 'public', name };
+    return {
+        id,
+        ref,
+        enabled: true,
+        descriptions: {},
+        columns: columns.map((item) => ({ ...item, tableId: id, tableRef: ref })),
+    };
+}
+describe('relationship locality', () => {
+    it('ranks the referenced parent table ahead of the child table for id-like source columns', () => {
+        const artists = table('artist-id', 'Artist', [column('artist-id', 'artist-pk', 'ArtistId')]);
+        const albums = table('album-id', 'Album', [
+            column('album-id', 'album-pk', 'AlbumId'),
+            column('album-id', 'artist-fk', 'ArtistId'),
+        ]);
+        const unrelated = table('invoice-id', 'Invoice', [column('invoice-id', 'invoice-pk', 'InvoiceId')]);
+        const ranked = localCandidateTables({
+            childTable: albums,
+            childColumn: albums.columns[1],
+            parentTables: [albums, unrelated, artists],
+            maxParentTables: 1,
+        });
+        expect(ranked.map((item) => item.table.ref.name)).toEqual(['Artist']);
+        expect(ranked[0]).toMatchObject({
+            score: expect.any(Number),
+            tokenScore: expect.any(Number),
+            embeddingScore: 0,
+            reasons: expect.arrayContaining(['column_table_token_overlap']),
+        });
+    });
+    it('uses singular and plural variants so plan_code can rank stg_plans', () => {
+        const plans = table('plans-id', 'stg_plans', [column('plans-id', 'plan-code', 'plan_code')]);
+        const segments = table('segments-id', 'mart_account_segments', [
+            column('segments-id', 'current-plan-code', 'current_plan_code', {
+                nativeType: 'TEXT',
+                normalizedType: 'text',
+                dimensionType: 'string',
+            }),
+        ]);
+        const accounts = table('accounts-id', 'accounts', [column('accounts-id', 'account-id', 'id')]);
+        const ranked = localCandidateTables({
+            childTable: segments,
+            childColumn: segments.columns[0],
+            parentTables: [accounts, segments, plans],
+            maxParentTables: 1,
+        });
+        expect(ranked.map((item) => item.table.ref.name)).toEqual(['stg_plans']);
+        expect(ranked[0]?.tokenScore).toBeGreaterThan(0);
+    });
+    it('returns all tables when the schema is smaller than the default locality cap', () => {
+        const accounts = table('accounts-id', 'accounts', [column('accounts-id', 'account-id', 'id')]);
+        const invoices = table('invoices-id', 'invoices', [
+            column('invoices-id', 'invoice-id', 'id'),
+            column('invoices-id', 'account-id', 'account_id'),
+        ]);
+        const ranked = localCandidateTables({
+            childTable: invoices,
+            childColumn: invoices.columns[1],
+            parentTables: [invoices, accounts],
+        });
+        expect(ranked.map((item) => item.table.ref.name).sort()).toEqual(['accounts', 'invoices']);
+    });
+    it('supports an explicit zero cap for deterministic tests', () => {
+        const accounts = table('accounts-id', 'accounts', [column('accounts-id', 'account-id', 'id')]);
+        const invoices = table('invoices-id', 'invoices', [
+            column('invoices-id', 'invoice-id', 'id'),
+            column('invoices-id', 'account-id', 'account_id'),
+        ]);
+        const ranked = localCandidateTables({
+            childTable: invoices,
+            childColumn: invoices.columns[1],
+            parentTables: [invoices, accounts],
+            maxParentTables: 0,
+        });
+        expect(ranked).toEqual([]);
+    });
+    it('uses parent-column embeddings when token locality is weak', () => {
+        const customers = table('customers-id', 'customers', [
+            column('customers-id', 'customers-id-col', 'id', { embedding: [1, 0, 0] }),
+            column('customers-id', 'customers-name-col', 'name', {
+                nativeType: 'TEXT',
+                normalizedType: 'text',
+                dimensionType: 'string',
+                embedding: [0, 1, 0],
+            }),
+        ]);
+        const orders = table('orders-id', 'orders', [
+            column('orders-id', 'orders-id-col', 'id', { embedding: [0, 0, 1] }),
+            column('orders-id', 'buyer-ref-col', 'buyer_ref', { embedding: [0.995, 0.005, 0] }),
+        ]);
+        const invoices = table('invoices-id', 'invoices', [column('invoices-id', 'invoice-id', 'id')]);
+        const ranked = localCandidateTables({
+            childTable: orders,
+            childColumn: orders.columns[1],
+            parentTables: [invoices, customers],
+            maxParentTables: 1,
+        });
+        expect(ranked.map((item) => item.table.ref.name)).toEqual(['customers']);
+        expect(ranked[0]).toMatchObject({
+            embeddingScore: expect.any(Number),
+            reasons: expect.arrayContaining(['embedding_similarity']),
+        });
+        expect(ranked[0].embeddingScore).toBeGreaterThan(0.99);
+    });
+});

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

@@ -0,0 +1,13 @@
+export interface KtxRelationshipNormalizedName {
+    raw: string;
+    normalized: string;
+    singular: string;
+    plural: string;
+    tokens: string[];
+}
+export type KtxRelationshipTokenInput = string | readonly string[] | KtxRelationshipNormalizedName;
+export declare function singularizeKtxRelationshipToken(value: string): string;
+export declare function pluralizeKtxRelationshipToken(value: string): string;
+export declare function tokenizeKtxRelationshipName(name: string): string[];
+export declare function normalizeKtxRelationshipName(name: string): KtxRelationshipNormalizedName;
+export declare function tokenSimilarity(leftInput: KtxRelationshipTokenInput, rightInput: KtxRelationshipTokenInput): number;