@memberjunction/db-auto-doc 5.13.0 → 5.15.0

package/dist/core/AnalysisEngine.d.ts

@@ -24,6 +24,38 @@ export declare class AnalysisEngine {
      * Initialize timing for guardrails and set current run
      */
     startAnalysis(run: AnalysisRun): void;
+    /**
+     * Lock interim ground truth: FKs with confidence ≥ threshold become immutable.
+     * Call this AFTER the iterative analysis completes but BEFORE the pruning pass.
+     */
+    lockInterimGroundTruth(state: DatabaseDocumentation, confidenceThreshold?: number): {
+        locked: number;
+        unlocked: number;
+    };
+    /**
+     * Lock high-confidence PK candidates as interim ground truth.
+     */
+    lockInterimPKGroundTruth(state: DatabaseDocumentation, confidenceThreshold?: number): {
+        locked: number;
+        unlocked: number;
+    };
+    /**
+     * Two-pass PK pruning using a potentially stronger model.
+     */
+    prunePrimaryKeys(state: DatabaseDocumentation, run: AnalysisRun): Promise<{
+        removed: number;
+        kept: number;
+    }>;
+    /**
+   * Two-pass FK pruning using a potentially stronger model.
+   * Pass 1: Per-table — evaluate each table's unlocked FKs, propose removals.
+   * Pass 2: Holistic — review all proposed removals at once for final decision.
+   * Locked FKs (interim ground truth) are never touched.
+   */
+    pruneForeignKeys(state: DatabaseDocumentation, run: AnalysisRun): Promise<{
+        removed: number;
+        kept: number;
+    }>;
     /**
      * Process a single dependency level
      */
@@ -39,6 +71,12 @@ export declare class AnalysisEngine {
      * Build context for table analysis
      */
     private buildTableContext;
+    /**
+     * Build FK candidate stats from the discovery phase for this table.
+     * Provides the LLM with cross-table relationship evidence (value overlap,
+     * cardinality ratio) to make better FK decisions.
+     */
+    private buildFKCandidateStats;
     /**
      * Build ground truth context for a table from config
      */
@@ -91,6 +129,12 @@ export declare class AnalysisEngine {
      * For now, this method is disabled to prevent brittle regex-based FK detection.
      */
     private extractAndFeedbackFKInsights;
+    /**
+     * Process PK proposal from LLM. The LLM can propose a PK, but ALL proposed columns
+     * must pass deterministic eligibility: zero nulls, zero blanks, 100% unique values.
+     * If any column fails, the entire proposal is rejected.
+     */
+    private processPKInsightFromLLM;
     /**
      * Process structured FK insights from LLM and create feedback to discovery phase
      *

package/dist/core/AnalysisEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalysisEngine.d.ts","sourceRoot":"","sources":["../../src/core/AnalysisEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,gBAAgB,EAAqC,MAAM,mBAAmB,CAAC;AAC5H,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAiD,MAAM,sBAAsB,CAAC;AAUxH,OAAO,EAAE,eAAe,EAAuC,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKhE,qBAAa,cAAc;IAUvB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,gBAAgB;IAZ1B,OAAO,CAAC,qBAAqB,CAAwB;IACrD,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAc;IAEjC,OAAO,CAAC,UAAU,CAA4D;gBAGpE,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,YAAY,EAC1B,gBAAgB,EAAE,gBAAgB,EAC1C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI;IA8BxE;;OAEG;IACI,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAM5C;;OAEG;IACU,YAAY,CACvB,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC;QAAE,QAAQ,EAAE,sBAAsB,EAAE,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC;IAgC9E;;OAEG;YACW,YAAY;IAqK1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2DzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA+B/B;;OAEG;YACW,mBAAmB;IAuEjC;;;OAGG;IACU,iCAAiC,CAC5C,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,EAAE,GAClB,OAAO,CAAC,OAAO,CAAC;IAwEnB;;;OAGG;IACU,6BAA6B,CACxC,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,OAAO,CAAC;IA6FnB;;;OAGG;IACU,6BAA6B,CACxC,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,OAAO,CAAC;IA+EnB;;OAEG;IACI,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO;IAWhF;;OAEG;IACU,sBAAsB,CACjC,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,sBAAsB,EAAE,GACjC,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,4BAA4B;IAWpC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAgJhC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAoE/B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAiE3B"}
+{"version":3,"file":"AnalysisEngine.d.ts","sourceRoot":"","sources":["../../src/core/AnalysisEngine.ts"],"names":[],"mappings":"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"}

package/dist/core/AnalysisEngine.js

@@ -2,6 +2,7 @@
  * Main analysis orchestrator
  * Coordinates the entire documentation generation workflow
  */
+import { ensureArray } from "../utils/ensureArray.js";
 import { BackpropagationEngine } from './BackpropagationEngine.js';
 import { ConvergenceDetector } from './ConvergenceDetector.js';
 import { GuardrailsManager } from './GuardrailsManager.js';
@@ -34,6 +35,293 @@ export class AnalysisEngine {
         this.currentRun = run;
         this.guardrailsManager.startPhase('analysis');
     }
+    /**
+     * Lock interim ground truth: FKs with confidence ≥ threshold become immutable.
+     * Call this AFTER the iterative analysis completes but BEFORE the pruning pass.
+     */
+    lockInterimGroundTruth(state, confidenceThreshold = 90) {
+        const discoveryPhase = state.phases.keyDetection;
+        if (!discoveryPhase)
+            return { locked: 0, unlocked: 0 };
+        let locked = 0;
+        let unlocked = 0;
+        for (const fk of discoveryPhase.discovered.foreignKeys) {
+            if (fk.status === 'rejected')
+                continue;
+            if (fk.confidence >= confidenceThreshold) {
+                fk.status = 'confirmed';
+                locked++;
+            }
+            else {
+                unlocked++;
+            }
+        }
+        console.log(`[AnalysisEngine] Interim ground truth locked: ${locked} FKs at ≥${confidenceThreshold}% confidence, ${unlocked} unlocked for pruning`);
+        this.onProgress('Interim ground truth locked', { locked, unlocked, threshold: confidenceThreshold });
+        return { locked, unlocked };
+    }
+    /**
+     * Lock high-confidence PK candidates as interim ground truth.
+     */
+    lockInterimPKGroundTruth(state, confidenceThreshold = 90) {
+        const discoveryPhase = state.phases.keyDetection;
+        if (!discoveryPhase)
+            return { locked: 0, unlocked: 0 };
+        let locked = 0;
+        let unlocked = 0;
+        for (const pk of discoveryPhase.discovered.primaryKeys) {
+            if (pk.status === 'rejected')
+                continue;
+            if (pk.confidence >= confidenceThreshold) {
+                pk.status = 'confirmed';
+                locked++;
+            }
+            else {
+                unlocked++;
+            }
+        }
+        console.log(`[AnalysisEngine] Interim PK ground truth locked: ${locked} PKs at >=${confidenceThreshold}% confidence, ${unlocked} unlocked for pruning`);
+        this.onProgress('Interim PK ground truth locked', { locked, unlocked, threshold: confidenceThreshold });
+        return { locked, unlocked };
+    }
+    /**
+     * Two-pass PK pruning using a potentially stronger model.
+     */
+    async prunePrimaryKeys(state, run) {
+        const discoveryPhase = state.phases.keyDetection;
+        if (!discoveryPhase)
+            return { removed: 0, kept: 0 };
+        const override = this.config.ai.modelOverrides?.['pkPruning'] ?? this.config.ai.modelOverrides?.['fkPruning'];
+        const effectiveModel = override?.model ?? this.config.ai.model;
+        const allTables = state.schemas.flatMap(s => s.tables.map(t => {
+            const pk = discoveryPhase.discovered.primaryKeys.find(p => p.schemaName === s.name && p.tableName === t.name && p.status === 'confirmed');
+            return { schema: s.name, name: t.name, description: t.description || '', pk: pk ? pk.columnNames.join(', ') : '' };
+        }));
+        const allPKs = discoveryPhase.discovered.primaryKeys.filter(pk => pk.status !== 'rejected');
+        const pksByTable = new Map();
+        for (const pk of allPKs) {
+            const key = `${pk.schemaName}.${pk.tableName}`;
+            if (!pksByTable.has(key))
+                pksByTable.set(key, []);
+            pksByTable.get(key).push(pk);
+        }
+        this.onProgress('PK pruning pass 1: per-table analysis', { tables: pksByTable.size, model: effectiveModel });
+        const allProposals = [];
+        for (const [tableKey, tablePKs] of pksByTable.entries()) {
+            const hasUnlocked = tablePKs.some(pk => pk.status !== 'confirmed');
+            if (!hasUnlocked)
+                continue;
+            const [schemaName, tableName] = tableKey.split('.');
+            const table = this.stateManager.findTable(state, schemaName, tableName);
+            const candidates = tablePKs.map(pk => ({ columns: pk.columnNames, confidence: pk.confidence, locked: pk.status === 'confirmed' }));
+            const context = { sourceSchema: schemaName, sourceTable: tableName, tableDescription: table?.description || '', allTables, candidates, seedContext: state.seedContext ?? this.config.seedContext };
+            const result = await this.promptEngine.executePrompt('pk-pruning-table', context, { responseFormat: 'JSON', temperature: override?.temperature ?? 0.05, maxTokens: override?.maxTokens ?? this.config.ai.maxTokens, modelOverride: override?.model, effortLevelOverride: override?.effortLevel });
+            if (!result.success || !result.result) {
+                console.log(`[AnalysisEngine] PK pruning failed for ${tableKey}: ${result.errorMessage}`);
+                continue;
+            }
+            try {
+                for (const proposal of ensureArray(result.result, "PK pruning per-table")) {
+                    if (proposal.action === 'remove' && proposal.index >= 1 && proposal.index <= tablePKs.length) {
+                        const pk = tablePKs[proposal.index - 1];
+                        if (pk.status === 'confirmed') {
+                            console.log(`[AnalysisEngine] BLOCKED removal of locked PK: ${tableKey} [${pk.columnNames.join(', ')}]`);
+                            continue;
+                        }
+                        allProposals.push({ pk, reasoning: proposal.reasoning, sourceSchema: pk.schemaName, sourceTable: pk.tableName, columns: pk.columnNames, confidence: pk.confidence });
+                    }
+                }
+            }
+            catch (pruneErr) {
+                console.log(`[AnalysisEngine] PK pruning error for ${tableKey}: ${pruneErr.message}`);
+            }
+        }
+        this.onProgress('PK pruning pass 1 complete', { proposals: allProposals.length });
+        if (allProposals.length === 0)
+            return { removed: 0, kept: allPKs.length };
+        this.onProgress('PK pruning pass 2: holistic review', { proposals: allProposals.length, model: effectiveModel });
+        const holisticContext = { allTables, proposals: allProposals.map(p => ({ sourceSchema: p.sourceSchema, sourceTable: p.sourceTable, columns: p.columns, confidence: p.confidence, reasoning: p.reasoning })), seedContext: state.seedContext ?? this.config.seedContext };
+        const holisticResult = await this.promptEngine.executePrompt('pk-pruning-holistic', holisticContext, { responseFormat: 'JSON', temperature: override?.temperature ?? 0.05, maxTokens: override?.maxTokens ?? this.config.ai.maxTokens, modelOverride: override?.model, effortLevelOverride: override?.effortLevel });
+        let removed = 0;
+        if (holisticResult.success && holisticResult.result) {
+            for (const decision of ensureArray(holisticResult.result, "holistic pruning")) {
+                if (decision.action === 'remove' && decision.index >= 1 && decision.index <= allProposals.length) {
+                    const proposal = allProposals[decision.index - 1];
+                    proposal.pk.status = 'rejected';
+                    removed++;
+                    console.log(`[AnalysisEngine] Pruned PK: ${proposal.sourceSchema}.${proposal.sourceTable} [${proposal.columns.join(', ')}] - ${decision.reasoning}`);
+                }
+            }
+        }
+        else {
+            console.log(`[AnalysisEngine] Holistic PK pruning failed: ${holisticResult.errorMessage}. Applying pass 1 proposals.`);
+            for (const proposal of allProposals) {
+                proposal.pk.status = 'rejected';
+                removed++;
+            }
+        }
+        const kept = allPKs.length - removed;
+        console.log(`[AnalysisEngine] PK pruning complete: ${removed} removed, ${kept} kept (model: ${effectiveModel})`);
+        this.onProgress('PK pruning complete', { removed, kept, model: effectiveModel });
+        this.stateManager.updateSummary(state);
+        await this.stateManager.save(state);
+        return { removed, kept };
+    }
+    /**
+   * Two-pass FK pruning using a potentially stronger model.
+   * Pass 1: Per-table — evaluate each table's unlocked FKs, propose removals.
+   * Pass 2: Holistic — review all proposed removals at once for final decision.
+   * Locked FKs (interim ground truth) are never touched.
+   */
+    async pruneForeignKeys(state, run) {
+        const discoveryPhase = state.phases.keyDetection;
+        if (!discoveryPhase)
+            return { removed: 0, kept: 0 };
+        const override = this.config.ai.modelOverrides?.['fkPruning'];
+        const effectiveModel = override?.model ?? this.config.ai.model;
+        // Build table info for context
+        const allTables = state.schemas.flatMap(s => s.tables.map(t => {
+            const pk = discoveryPhase.discovered.primaryKeys.find(p => p.schemaName === s.name && p.tableName === t.name);
+            return {
+                schema: s.name,
+                name: t.name,
+                description: t.description || '',
+                pk: pk ? pk.columnNames.join(', ') : ''
+            };
+        }));
+        // Group non-rejected FKs by source table
+        const allFKs = discoveryPhase.discovered.foreignKeys.filter(fk => fk.status !== 'rejected');
+        const fksByTable = new Map();
+        for (const fk of allFKs) {
+            const key = `${fk.schemaName}.${fk.sourceTable}`;
+            if (!fksByTable.has(key))
+                fksByTable.set(key, []);
+            fksByTable.get(key).push(fk);
+        }
+        // ==================== PASS 1: Per-table pruning proposals ====================
+        this.onProgress('FK pruning pass 1: per-table analysis', { tables: fksByTable.size, model: effectiveModel });
+        const allProposals = [];
+        let tableIdx = 0;
+        for (const [tableKey, tableFKs] of fksByTable.entries()) {
+            tableIdx++;
+            // Skip tables where ALL FKs are locked
+            const hasUnlocked = tableFKs.some(fk => fk.status !== 'confirmed');
+            if (!hasUnlocked)
+                continue;
+            if (tableIdx % 10 === 1) {
+                this.onProgress(`FK pruning: table ${tableIdx}/${fksByTable.size}`);
+            }
+            const [schemaName, tableName] = tableKey.split('.');
+            const table = this.stateManager.findTable(state, schemaName, tableName);
+            const candidates = tableFKs.map(fk => ({
+                sourceColumn: fk.sourceColumn,
+                targetSchema: fk.targetSchema,
+                targetTable: fk.targetTable,
+                targetColumn: fk.targetColumn,
+                confidence: fk.confidence,
+                locked: fk.status === 'confirmed'
+            }));
+            const context = {
+                sourceSchema: schemaName,
+                sourceTable: tableName,
+                tableDescription: table?.description || '',
+                allTables,
+                candidates,
+                seedContext: state.seedContext ?? this.config.seedContext
+            };
+            const result = await this.promptEngine.executePrompt('fk-pruning-table', context, {
+                responseFormat: 'JSON',
+                temperature: override?.temperature ?? 0.05,
+                maxTokens: override?.maxTokens ?? this.config.ai.maxTokens,
+                modelOverride: override?.model,
+                effortLevelOverride: override?.effortLevel
+            });
+            if (!result.success || !result.result) {
+                console.log(`[AnalysisEngine] FK pruning failed for ${tableKey}: ${result.errorMessage}`);
+                continue;
+            }
+            try {
+                for (const proposal of ensureArray(result.result, "FK pruning per-table")) {
+                    if (proposal.action === 'remove' && proposal.index >= 1 && proposal.index <= tableFKs.length) {
+                        const fk = tableFKs[proposal.index - 1];
+                        if (fk.status === 'confirmed') {
+                            console.log(`[AnalysisEngine] BLOCKED removal of locked FK: ${tableKey}.${fk.sourceColumn} -> ${fk.targetTable}.${fk.targetColumn}`);
+                            continue;
+                        }
+                        allProposals.push({
+                            fk,
+                            reasoning: proposal.reasoning,
+                            sourceSchema: fk.schemaName,
+                            sourceTable: fk.sourceTable,
+                            sourceColumn: fk.sourceColumn,
+                            targetSchema: fk.targetSchema,
+                            targetTable: fk.targetTable,
+                            targetColumn: fk.targetColumn,
+                            confidence: fk.confidence
+                        });
+                    }
+                }
+            }
+            catch (pruneErr) {
+                console.log(`[AnalysisEngine] FK pruning error for ${tableKey}: ${pruneErr.message}`);
+            }
+            console.log(`[AnalysisEngine] FK pruning ${tableKey}: ${result.result.length} removals proposed`);
+        }
+        console.log(`[AnalysisEngine] Pass 1 complete: ${allProposals.length} total removals proposed`);
+        this.onProgress('FK pruning pass 1 complete', { proposals: allProposals.length });
+        if (allProposals.length === 0) {
+            return { removed: 0, kept: allFKs.length };
+        }
+        // ==================== PASS 2: Holistic review of all proposals ====================
+        this.onProgress('FK pruning pass 2: holistic review', { proposals: allProposals.length, model: effectiveModel });
+        const holisticContext = {
+            allTables,
+            proposals: allProposals.map(p => ({
+                sourceSchema: p.sourceSchema,
+                sourceTable: p.sourceTable,
+                sourceColumn: p.sourceColumn,
+                targetSchema: p.targetSchema,
+                targetTable: p.targetTable,
+                targetColumn: p.targetColumn,
+                confidence: p.confidence,
+                reasoning: p.reasoning
+            })),
+            seedContext: state.seedContext ?? this.config.seedContext
+        };
+        const holisticResult = await this.promptEngine.executePrompt('fk-pruning-holistic', holisticContext, {
+            responseFormat: 'JSON',
+            temperature: override?.temperature ?? 0.05,
+            maxTokens: override?.maxTokens ?? this.config.ai.maxTokens,
+            modelOverride: override?.model,
+            effortLevelOverride: override?.effortLevel
+        });
+        let removed = 0;
+        if (holisticResult.success && holisticResult.result) {
+            for (const decision of ensureArray(holisticResult.result, "holistic pruning")) {
+                if (decision.action === 'remove' && decision.index >= 1 && decision.index <= allProposals.length) {
+                    const proposal = allProposals[decision.index - 1];
+                    proposal.fk.status = 'rejected';
+                    removed++;
+                    console.log(`[AnalysisEngine] Pruned FK: ${proposal.sourceSchema}.${proposal.sourceTable}.${proposal.sourceColumn} -> ${proposal.targetSchema}.${proposal.targetTable}.${proposal.targetColumn} — ${decision.reasoning}`);
+                }
+            }
+        }
+        else {
+            console.log(`[AnalysisEngine] Holistic pruning failed: ${holisticResult.errorMessage}. Falling back to pass 1 proposals.`);
+            // Fallback: apply all pass 1 proposals directly
+            for (const proposal of allProposals) {
+                proposal.fk.status = 'rejected';
+                removed++;
+            }
+        }
+        const kept = allFKs.length - removed;
+        console.log(`[AnalysisEngine] FK pruning complete: ${removed} removed, ${kept} kept (model: ${effectiveModel})`);
+        this.onProgress('FK pruning complete', { removed, kept, model: effectiveModel });
+        // Save state
+        this.stateManager.updateSummary(state);
+        await this.stateManager.save(state);
+        return { removed, kept };
+    }
     /**
      * Process a single dependency level
      */
@@ -124,6 +412,10 @@ export class AnalysisEngine {
             if (state.phases.keyDetection && result.result.foreignKeys) {
                 this.processFKInsightsFromLLM(state, tableNode.schema, tableNode.table, result.result.foreignKeys);
             }
+            // Process PK proposal from LLM — verify eligibility deterministically
+            if (state.phases.keyDetection && result.result.primaryKey) {
+                this.processPKInsightFromLLM(state, tableNode.schema, tableNode.table, result.result.primaryKey);
+            }
             // Update inferred business domain
             if (result.result.inferredBusinessDomain) {
                 // Could store this in table metadata if needed
@@ -184,6 +476,8 @@ export class AnalysisEngine {
         }
         // Build ground truth context if available
         const groundTruthContext = this.buildGroundTruthContext(tableNode.schema, tableNode.table);
+        // Build FK candidate stats from discovery phase for LLM context
+        const fkCandidateStats = this.buildFKCandidateStats(state, tableNode.schema, tableNode.table);
         return {
             schema: tableNode.schema,
             table: tableNode.table,
@@ -207,9 +501,33 @@ export class AnalysisEngine {
             userNotes: table.userNotes,
             seedContext: state.seedContext ?? this.config.seedContext,
             allTables,
-            groundTruth: groundTruthContext
+            groundTruth: groundTruthContext,
+            fkCandidateStats
         };
     }
+    /**
+     * Build FK candidate stats from the discovery phase for this table.
+     * Provides the LLM with cross-table relationship evidence (value overlap,
+     * cardinality ratio) to make better FK decisions.
+     */
+    buildFKCandidateStats(state, schemaName, tableName) {
+        const discoveryPhase = state.phases.keyDetection;
+        if (!discoveryPhase)
+            return [];
+        return discoveryPhase.discovered.foreignKeys
+            .filter(fk => fk.schemaName === schemaName &&
+            fk.sourceTable === tableName &&
+            fk.status !== 'rejected')
+            .map(fk => ({
+            sourceColumn: fk.sourceColumn,
+            targetSchema: fk.targetSchema,
+            targetTable: fk.targetTable,
+            targetColumn: fk.targetColumn,
+            valueOverlap: fk.evidence.valueOverlap,
+            cardinalityRatio: fk.evidence.cardinalityRatio,
+            confidence: fk.confidence
+        }));
+    }
     /**
      * Build ground truth context for a table from config
      */
@@ -539,6 +857,114 @@ export class AnalysisEngine {
         console.log(`[AnalysisEngine] extractAndFeedbackFKInsights disabled - awaiting structured FK output from LLM`);
         return;
     }
+    /**
+     * Process PK proposal from LLM. The LLM can propose a PK, but ALL proposed columns
+     * must pass deterministic eligibility: zero nulls, zero blanks, 100% unique values.
+     * If any column fails, the entire proposal is rejected.
+     */
+    processPKInsightFromLLM(state, schemaName, tableName, pkProposal) {
+        const discoveryPhase = state.phases.keyDetection;
+        if (!discoveryPhase || !pkProposal || !pkProposal.columns || pkProposal.columns.length === 0)
+            return;
+        const columns = pkProposal.columns;
+        const confidence = Math.round(pkProposal.confidence * 100);
+        // Check if we already have a confirmed PK for this table
+        const existingConfirmedPK = discoveryPhase.discovered.primaryKeys.find(pk => pk.schemaName === schemaName &&
+            pk.tableName === tableName &&
+            pk.status === 'confirmed');
+        if (existingConfirmedPK) {
+            // Already have a confirmed PK — check if LLM agrees
+            const sameColumns = existingConfirmedPK.columnNames.length === columns.length &&
+                existingConfirmedPK.columnNames.every(c => columns.some(pc => pc.toLowerCase() === c.toLowerCase()));
+            if (sameColumns) {
+                // LLM agrees with existing PK — boost confidence
+                existingConfirmedPK.confidence = Math.min(existingConfirmedPK.confidence + 10, 100);
+                existingConfirmedPK.validatedByLLM = true;
+                console.log(`[AnalysisEngine] LLM confirmed existing PK: ${schemaName}.${tableName} (${columns.join(', ')}), confidence: ${existingConfirmedPK.confidence}`);
+            }
+            else {
+                // LLM disagrees — log but don't override a confirmed PK
+                console.log(`[AnalysisEngine] LLM proposed different PK for ${schemaName}.${tableName}: [${columns.join(', ')}] vs confirmed [${existingConfirmedPK.columnNames.join(', ')}] — keeping confirmed`);
+            }
+            return;
+        }
+        // Check if an existing candidate matches
+        const existingCandidate = discoveryPhase.discovered.primaryKeys.find(pk => pk.schemaName === schemaName &&
+            pk.tableName === tableName &&
+            pk.columnNames.length === columns.length &&
+            pk.columnNames.every(c => columns.some(pc => pc.toLowerCase() === c.toLowerCase())));
+        if (existingCandidate) {
+            // LLM confirms a stats candidate — promote and boost
+            existingCandidate.validatedByLLM = true;
+            existingCandidate.status = 'confirmed';
+            existingCandidate.confidence = Math.min(existingCandidate.confidence + 20, 100);
+            console.log(`[AnalysisEngine] LLM confirmed PK candidate: ${schemaName}.${tableName} (${columns.join(', ')}), confidence: ${existingCandidate.confidence}`);
+            // Update column flags
+            for (const colName of columns) {
+                const column = this.findColumnInState(state, schemaName, tableName, colName);
+                if (column)
+                    column.isPrimaryKey = true;
+            }
+            return;
+        }
+        // New PK proposal — verify ALL columns are PK-eligible deterministically
+        const table = this.stateManager.findTable(state, schemaName, tableName);
+        if (!table)
+            return;
+        for (const colName of columns) {
+            const column = table.columns.find(c => c.name.toLowerCase() === colName.toLowerCase());
+            if (!column) {
+                console.log(`[AnalysisEngine] LLM PK rejected: ${schemaName}.${tableName} — column "${colName}" not found`);
+                return;
+            }
+            // Check PK eligibility from stats
+            const stats = column.statistics;
+            if (!stats) {
+                console.log(`[AnalysisEngine] LLM PK rejected: ${schemaName}.${tableName}.${colName} — no statistics available`);
+                return;
+            }
+            // Safety: prefer pre-computed uniquenessRatio if available (totalRows can be 0 due to field naming bug)
+            const uniqueness = stats.uniquenessRatio != null && stats.uniquenessRatio > 0
+                ? stats.uniquenessRatio
+                : (stats.totalRows > 0 ? stats.distinctCount / stats.totalRows : 0);
+            const hasNulls = (stats.nullCount || 0) > 0;
+            if (hasNulls) {
+                console.log(`[AnalysisEngine] LLM PK rejected: ${schemaName}.${tableName}.${colName} — has ${stats.nullCount} nulls`);
+                return;
+            }
+            if (uniqueness < 1.0) {
+                console.log(`[AnalysisEngine] LLM PK rejected: ${schemaName}.${tableName}.${colName} — uniqueness ${(uniqueness * 100).toFixed(1)}% (must be 100%)`);
+                return;
+            }
+        }
+        // All columns pass — create new PK candidate
+        const newPK = {
+            schemaName,
+            tableName,
+            columnNames: columns,
+            confidence,
+            evidence: {
+                uniqueness: 1.0,
+                nullCount: 0,
+                totalRows: table.rowCount || 0,
+                dataPattern: columns.length > 1 ? 'composite' : 'unknown',
+                namingScore: 0.5,
+                dataTypeScore: 0.8,
+                warnings: ['Created from LLM proposal — passed deterministic eligibility']
+            },
+            discoveredInIteration: 1,
+            validatedByLLM: true,
+            status: 'confirmed'
+        };
+        discoveryPhase.discovered.primaryKeys.push(newPK);
+        // Update column flags
+        for (const colName of columns) {
+            const column = this.findColumnInState(state, schemaName, tableName, colName);
+            if (column)
+                column.isPrimaryKey = true;
+        }
+        console.log(`[AnalysisEngine] Created PK from LLM: ${schemaName}.${tableName} (${columns.join(', ')}) confidence: ${confidence}`);
+    }
     /**
      * Process structured FK insights from LLM and create feedback to discovery phase
      *