@memberjunction/db-auto-doc 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/core/AnalysisEngine.d.ts

@@ -2,8 +2,11 @@
  * Main analysis orchestrator
  * Coordinates the entire documentation generation workflow
  */
-import { DatabaseDocumentation, AnalysisRun, SchemaDefinition } from '../types/state.js';
+import { DatabaseDocumentation, AnalysisRun, SchemaDefinition, TableDefinition } from '../types/state.js';
+import type { BaseAutoDocDriver } from "../drivers/BaseAutoDocDriver.js";
 import { TableNode, BackpropagationTrigger } from '../types/analysis.js';
+import { KeyVerifier } from '../discovery/JoinProbe.js';
+import { ColumnDescriptionPromptResult } from '../types/prompts.js';
 import { DBAutoDocConfig } from '../types/config.js';
 import { PromptEngine } from '../prompts/PromptEngine.js';
 import { StateManager } from '../state/StateManager.js';
@@ -13,6 +16,8 @@ export declare class AnalysisEngine {
     private promptEngine;
     private stateManager;
     private iterationTracker;
+    /** Database access for checks the LLM's proposals must pass (composite PK uniqueness). Optional: without it, composite PK proposals are rejected. */
+    private driver?;
     private backpropagationEngine;
     private convergenceDetector;
     private guardrailsManager;
@@ -20,7 +25,22 @@ export declare class AnalysisEngine {
     private startTime;
     private currentRun?;
     private onProgress;
-    constructor(config: DBAutoDocConfig, promptEngine: PromptEngine, stateManager: StateManager, iterationTracker: IterationTracker, onProgress?: (message: string, data?: Record<string, unknown>) => void);
+    /**
+     * Verifies a proposed key against the data before it is confirmed. Optional: when
+     * absent, LLM-proposed FKs are still emitted but stamped `Unprobed` rather than
+     * silently presented as though someone had checked them.
+     */
+    private keyVerifier;
+    /**
+     * Supply the probe used to verify LLM-proposed foreign keys. Injected rather than
+     * constructed here because the engine has no driver of its own; the orchestrator owns
+     * the connection and passes ONE verifier so the per-run probe budget is shared with
+     * the organic-key path instead of each path getting its own allowance.
+     */
+    SetKeyVerifier(verifier: KeyVerifier | null): void;
+    constructor(config: DBAutoDocConfig, promptEngine: PromptEngine, stateManager: StateManager, iterationTracker: IterationTracker, onProgress?: (message: string, data?: Record<string, unknown>) => void, 
+    /** Database access for checks the LLM's proposals must pass (composite PK uniqueness). Optional: without it, composite PK proposals are rejected. */
+    driver?: BaseAutoDocDriver);
     /**
      * Initialize timing for guardrails and set current run
      */
@@ -99,6 +119,8 @@ export declare class AnalysisEngine {
      * Build context for table analysis
      */
     private buildTableContext;
+    /** The table's existing indexes as prompt lines, or undefined when there are none to show. */
+    private indexHintLines;
     /**
      * Build FK candidate stats from the discovery phase for this table.
      * Provides the LLM with cross-table relationship evidence (value overlap,
@@ -109,7 +131,7 @@ export declare class AnalysisEngine {
      * Persist enum/value-list verdicts from LLM response onto ColumnDefinition.
      * Keeps the highest-confidence verdict across multiple iterations.
      */
-    private persistEnumVerdicts;
+    protected persistEnumVerdicts(table: TableDefinition, columnDescriptions: ColumnDescriptionPromptResult[] | undefined, modelUsed: string): void;
     /**
      * Sanitize LLM-returned enum values: trim whitespace, drop empties and null sentinels.
      */
@@ -177,9 +199,10 @@ export declare class AnalysisEngine {
      */
     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.
+     * Process PK proposal from LLM. The LLM can propose a PK, but it must pass deterministic
+     * eligibility: every column exists and has no nulls, and the key is unique — a single column
+     * by its own statistics, a composite key as a combination (checked in the database).
+     * If any check fails, the entire proposal is rejected.
      */
     private processPKInsightFromLLM;
     /**
@@ -188,6 +211,16 @@ export declare class AnalysisEngine {
      * Uses the foreignKeys array from table-analysis prompt response instead of brittle regex parsing.
      * Per architectural decision: use LLM for language understanding, deterministic code for processing.
      */
+    /**
+     * Probe an LLM-proposed foreign key.
+     *
+     * Returns `Unprobed` rather than throwing for every reason a probe can fail to run —
+     * no verifier injected, no such table or column in the analysed state, or the driver
+     * reporting that it could not evaluate the join. `Refuted` is reserved for a probe
+     * that RAN and measured containment below the floor, because only that is evidence
+     * the key is wrong.
+     */
+    private verifyProposedFK;
     private processFKInsightsFromLLM;
     /**
      * Find a column in the state schemas

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

@@ -1 +1 @@
-{"version":3,"file":"AnalysisEngine.d.ts","sourceRoot":"","sources":["../../src/core/AnalysisEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AnalysisEngine.d.ts","sourceRoot":"","sources":["../../src/core/AnalysisEngine.ts"],"names":[],"mappings":"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"}

package/dist/core/AnalysisEngine.js

@@ -3,17 +3,39 @@
  * Coordinates the entire documentation generation workflow
  */
 import { EnsureArray } from "../utils/ensureArray.js";
+import { CheckPKProposal } from "./PKProposalGate.js";
+import { BuildIndexHints, FormatIndexHint, IsUniquelyIndexed } from "../utils/index-hints.js";
+import { SeedContextExcerpt } from "../utils/seed-context.js";
 import { EnumCandidateGate } from '../discovery/EnumCandidateGate.js';
+import { StampFor } from '../discovery/JoinProbe.js';
 import { BackpropagationEngine } from './BackpropagationEngine.js';
 import { ConvergenceDetector } from './ConvergenceDetector.js';
 import { GuardrailsManager } from './GuardrailsManager.js';
 export class AnalysisEngine {
-    constructor(config, promptEngine, stateManager, iterationTracker, onProgress) {
+    /**
+     * Supply the probe used to verify LLM-proposed foreign keys. Injected rather than
+     * constructed here because the engine has no driver of its own; the orchestrator owns
+     * the connection and passes ONE verifier so the per-run probe budget is shared with
+     * the organic-key path instead of each path getting its own allowance.
+     */
+    SetKeyVerifier(verifier) {
+        this.keyVerifier = verifier;
+    }
+    constructor(config, promptEngine, stateManager, iterationTracker, onProgress, 
+    /** Database access for checks the LLM's proposals must pass (composite PK uniqueness). Optional: without it, composite PK proposals are rejected. */
+    driver) {
         this.config = config;
         this.promptEngine = promptEngine;
         this.stateManager = stateManager;
         this.iterationTracker = iterationTracker;
+        this.driver = driver;
         this.startTime = 0;
+        /**
+         * Verifies a proposed key against the data before it is confirmed. Optional: when
+         * absent, LLM-proposed FKs are still emitted but stamped `Unprobed` rather than
+         * silently presented as though someone had checked them.
+         */
+        this.keyVerifier = null;
         this.onProgress = onProgress || (() => { });
         this.backpropagationEngine = new BackpropagationEngine(promptEngine, stateManager, iterationTracker, config.analysis.backpropagation.maxDepth, config);
         this.convergenceDetector = new ConvergenceDetector(config.analysis.convergence, stateManager, iterationTracker);
@@ -128,7 +150,7 @@ export class AnalysisEngine {
             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 context = { sourceSchema: schemaName, sourceTable: tableName, tableDescription: table?.description || '', allTables, candidates, existingIndexes: this.indexHintLines(table), seedContext: state.seedContext ?? this.config.seedContext, seedExcerpt: SeedContextExcerpt(state.seedContext ?? this.config.seedContext, [tableName]) };
             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}`);
@@ -154,7 +176,7 @@ export class AnalysisEngine {
         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 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, seedExcerpt: SeedContextExcerpt(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) {
@@ -237,7 +259,8 @@ export class AnalysisEngine {
                 targetTable: fk.targetTable,
                 targetColumn: fk.targetColumn,
                 confidence: fk.confidence,
-                locked: fk.status === 'confirmed'
+                locked: fk.status === 'confirmed',
+                targetUniquelyIndexed: IsUniquelyIndexed(this.stateManager.findTable(state, fk.targetSchema, fk.targetTable), fk.targetColumn)
             }));
             const context = {
                 sourceSchema: schemaName,
@@ -245,7 +268,9 @@ export class AnalysisEngine {
                 tableDescription: table?.description || '',
                 allTables,
                 candidates,
-                seedContext: state.seedContext ?? this.config.seedContext
+                existingIndexes: this.indexHintLines(table),
+                seedContext: state.seedContext ?? this.config.seedContext,
+                seedExcerpt: SeedContextExcerpt(state.seedContext ?? this.config.seedContext, [tableName])
             };
             const result = await this.promptEngine.executePrompt('fk-pruning-table', context, {
                 responseFormat: 'JSON',
@@ -304,7 +329,8 @@ export class AnalysisEngine {
                 confidence: p.confidence,
                 reasoning: p.reasoning
             })),
-            seedContext: state.seedContext ?? this.config.seedContext
+            seedContext: state.seedContext ?? this.config.seedContext,
+            seedExcerpt: SeedContextExcerpt(state.seedContext ?? this.config.seedContext, [])
         };
         const holisticResult = await this.promptEngine.executePrompt('fk-pruning-holistic', holisticContext, {
             responseFormat: 'JSON',
@@ -438,11 +464,11 @@ export class AnalysisEngine {
             this.persistEnumVerdicts(table, result.result.columnDescriptions, run.modelUsed);
             // Process structured FK insights from LLM and feed back to discovery phase
             if (state.phases.keyDetection && result.result.foreignKeys) {
-                this.processFKInsightsFromLLM(state, tableNode.schema, tableNode.table, result.result.foreignKeys);
+                await 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);
+                await this.processPKInsightFromLLM(state, tableNode.schema, tableNode.table, result.result.primaryKey);
             }
             // Update inferred business domain
             if (result.result.inferredBusinessDomain) {
@@ -535,9 +561,15 @@ export class AnalysisEngine {
             allTables,
             groundTruth: groundTruthContext,
             fkCandidateStats,
-            enumCandidates: enumCandidates.length > 0 ? enumCandidates : undefined
+            enumCandidates: enumCandidates.length > 0 ? enumCandidates : undefined,
+            existingIndexes: this.indexHintLines(table)
         };
     }
+    /** The table's existing indexes as prompt lines, or undefined when there are none to show. */
+    indexHintLines(table) {
+        const lines = BuildIndexHints(table).map(FormatIndexHint);
+        return lines.length > 0 ? lines : undefined;
+    }
     /**
      * Build FK candidate stats from the discovery phase for this table.
      * Provides the LLM with cross-table relationship evidence (value overlap,
@@ -580,11 +612,16 @@ export class AnalysisEngine {
             // If sanitization drops all values below 2, skip the verdict
             if (sanitizedValues.length < 2 && vl.isEnum)
                 continue;
+            // The prompt asks for a verdict only on enum candidates; enforce that here, and keep only
+            // values observed in the column, so a verdict on a non-candidate or an invented value is dropped.
+            const keptValues = this.enumCandidateGate.FilterVerdictValues(column, table.rowCount, sanitizedValues);
+            if (keptValues === null && vl.isEnum)
+                continue;
             const newVerdict = {
                 isEnum: vl.isEnum,
                 type: vl.type,
                 confidence: vl.confidence,
-                values: sanitizedValues,
+                values: keptValues ?? sanitizedValues,
                 reasoning: vl.reasoning,
                 source: 'llm',
                 cardinalityAtDecision: column.statistics
@@ -967,11 +1004,12 @@ export class AnalysisEngine {
         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.
+     * Process PK proposal from LLM. The LLM can propose a PK, but it must pass deterministic
+     * eligibility: every column exists and has no nulls, and the key is unique — a single column
+     * by its own statistics, a composite key as a combination (checked in the database).
+     * If any check fails, the entire proposal is rejected.
      */
-    processPKInsightFromLLM(state, schemaName, tableName, pkProposal) {
+    async processPKInsightFromLLM(state, schemaName, tableName, pkProposal) {
         const discoveryPhase = state.phases.keyDetection;
         if (!discoveryPhase || !pkProposal || !pkProposal.columns || pkProposal.columns.length === 0)
             return;
@@ -1016,47 +1054,29 @@ export class AnalysisEngine {
             }
             return;
         }
-        // New PK proposal — verify ALL columns are PK-eligible deterministically
+        // New PK proposal — verify it 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;
-            }
+        const sampleSize = this.config.analysis.relationshipDiscovery?.sampling?.maxRowsPerTable ?? 1000;
+        const driver = this.driver;
+        const verdict = await CheckPKProposal(table, columns, driver ? (cols) => driver.checkColumnCombinationUniqueness(schemaName, tableName, cols, sampleSize) : undefined);
+        if (!verdict.Eligible) {
+            console.log(`[AnalysisEngine] LLM PK rejected: ${schemaName}.${tableName} ${verdict.Reason}`);
+            return;
         }
+        const pkColumns = verdict.Columns ?? columns;
         // All columns pass — create new PK candidate
         const newPK = {
             schemaName,
             tableName,
-            columnNames: columns,
+            columnNames: pkColumns,
             confidence,
             evidence: {
                 uniqueness: 1.0,
                 nullCount: 0,
                 totalRows: table.rowCount || 0,
-                dataPattern: columns.length > 1 ? 'composite' : 'unknown',
+                dataPattern: pkColumns.length > 1 ? 'composite' : 'unknown',
                 namingScore: 0.5,
                 dataTypeScore: 0.8,
                 warnings: ['Created from LLM proposal — passed deterministic eligibility']
@@ -1067,12 +1087,12 @@ export class AnalysisEngine {
         };
         discoveryPhase.discovered.primaryKeys.push(newPK);
         // Update column flags
-        for (const colName of columns) {
+        for (const colName of pkColumns) {
             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}`);
+        console.log(`[AnalysisEngine] Created PK from LLM: ${schemaName}.${tableName} (${pkColumns.join(', ')}) confidence: ${confidence}`);
     }
     /**
      * Process structured FK insights from LLM and create feedback to discovery phase
@@ -1080,7 +1100,39 @@ export class AnalysisEngine {
      * Uses the foreignKeys array from table-analysis prompt response instead of brittle regex parsing.
      * Per architectural decision: use LLM for language understanding, deterministic code for processing.
      */
-    processFKInsightsFromLLM(state, schemaName, tableName, foreignKeys) {
+    /**
+     * Probe an LLM-proposed foreign key.
+     *
+     * Returns `Unprobed` rather than throwing for every reason a probe can fail to run —
+     * no verifier injected, no such table or column in the analysed state, or the driver
+     * reporting that it could not evaluate the join. `Refuted` is reserved for a probe
+     * that RAN and measured containment below the floor, because only that is evidence
+     * the key is wrong.
+     */
+    async verifyProposedFK(childSchema, childTable, childColumn, parentSchema, parentTable, parentColumn) {
+        const now = new Date().toISOString();
+        if (!this.keyVerifier) {
+            return {
+                Status: 'Unprobed',
+                Containment: null,
+                Reason: 'no key verifier configured for this run',
+                ProbedAt: now
+            };
+        }
+        if (!parentColumn || !parentTable || !parentSchema) {
+            return {
+                Status: 'Unprobed',
+                Containment: null,
+                Reason: 'LLM did not name a complete target column',
+                ProbedAt: now
+            };
+        }
+        return this.keyVerifier.Verify({
+            Child: { Schema: childSchema, Table: childTable, Column: childColumn },
+            Parent: { Schema: parentSchema, Table: parentTable, Column: parentColumn }
+        });
+    }
+    async processFKInsightsFromLLM(state, schemaName, tableName, foreignKeys) {
         const discoveryPhase = state.phases.keyDetection;
         if (!discoveryPhase || !foreignKeys || foreignKeys.length === 0)
             return;
@@ -1122,6 +1174,38 @@ export class AnalysisEngine {
                 console.log(`[AnalysisEngine] Rejecting LLM FK suggestion for confirmed PK: ${schemaName}.${tableName}.${columnName} -> ${referencesSchema}.${referencesTable}.${referencesColumn}`);
                 continue;
             }
+            // ── Verify the proposed join before anything is confirmed ────────────────
+            //
+            // This is the gate that was missing. The statistical path (FKDetector) probes
+            // and rejects below 75% containment at its GATE 6; this path never probed at
+            // all — it wrote a literal `valueOverlap: 0` placeholder, set
+            // `status: 'confirmed'`, and stamped `column.isForeignKey = true`. The
+            // additionalSchemaInfo generator then emits from BOTH
+            // `discovered.foreignKeys` (gated on confidence + status, never on overlap)
+            // and `column.foreignKeyReferences` (gated on nothing at all), so an
+            // LLM-proposed key reached the output through two independent unchecked doors.
+            //
+            // The shape this catches: a connector schema whose parent key is namespaced
+            // `<product>:<id>` while children store the bare id. "A foreign key points at
+            // the parent's primary key" is correct almost everywhere and unfalsifiable
+            // from schema shape, so the LLM proposes it for every child table and every
+            // one of them matches zero rows.
+            const probe = await this.verifyProposedFK(schemaName, tableName, columnName, referencesSchema, referencesTable, referencesColumn);
+            if (probe.Status === 'Refuted') {
+                // Measured, not assumed: the probe ran and the join matches (near) nothing.
+                // Dropping it here is the only place it can be dropped — once the column is
+                // stamped, the introspected-FK path emits it with no gate to fail. It runs
+                // before the PK block below, so a refuted proposal is not evidence against a
+                // PK candidate either.
+                console.log(`[AnalysisEngine] Rejecting LLM FK — probe refuted: ${schemaName}.${tableName}.${columnName} -> ${referencesSchema}.${referencesTable}.${referencesColumn} (${probe.Reason})`);
+                this.onProgress(`Rejected LLM-proposed FK ${schemaName}.${tableName}.${columnName} → ${referencesTable}.${referencesColumn}: ${probe.Reason}`, { refutedKey: `${schemaName}.${tableName}.${columnName}` });
+                continue;
+            }
+            // Verified or Unprobed both proceed. Unprobed proceeds deliberately: refusing
+            // whenever the probe cannot run turns a permissions or timeout problem into
+            // total key loss with no signal. It proceeds STAMPED, so a consumer can tell a
+            // checked key from an unchecked one.
+            const verificationStamp = StampFor('LLM', probe);
             if (existingPK && existingPK.status !== 'confirmed') {
                 // PK exists but isn't confirmed — LLM suggesting it's an FK is evidence
                 // that the PK detection was wrong. Reject the PK.
@@ -1140,6 +1224,7 @@ export class AnalysisEngine {
                 existingFK.validatedByLLM = true;
                 existingFK.status = 'confirmed';
                 existingFK.confidence = Math.min(existingFK.confidence + 20, 100);
+                existingFK.verification = verificationStamp;
                 feedback.type = 'confidence_change';
                 feedback.newConfidence = existingFK.confidence;
                 feedback.affectedCandidates.push(`FK:${schemaName}.${tableName}.${columnName}`);
@@ -1169,17 +1254,26 @@ export class AnalysisEngine {
                     confidence: Math.round(confidence * 100),
                     evidence: {
                         namingMatch: 0.9,
-                        valueOverlap: 0,
+                        // Real measurements where the probe ran. These were hardcoded 0 / 0 / 0,
+                        // which is indistinguishable from a probe that ran and found nothing —
+                        // the exact conflation that let a schema of zero-match keys be emitted
+                        // with the same apparent confidence as a correct one.
+                        valueOverlap: probe.Containment ? probe.Containment.Containment : 0,
                         cardinalityRatio: 0,
                         dataTypeMatch: true,
                         nullPercentage: 0,
-                        sampleSize: 0,
-                        orphanCount: 0,
-                        warnings: ['Created from structured LLM output']
+                        sampleSize: probe.Containment ? probe.Containment.SampledValues : 0,
+                        orphanCount: probe.Containment
+                            ? probe.Containment.SampledValues - probe.Containment.MatchedValues
+                            : 0,
+                        warnings: probe.Status === 'Unprobed'
+                            ? ['Created from structured LLM output', `Join NOT verified: ${probe.Reason}`]
+                            : ['Created from structured LLM output', `Join verified: ${probe.Reason}`]
                     },
                     discoveredInIteration: 1,
                     validatedByLLM: true,
-                    status: 'confirmed'
+                    status: 'confirmed',
+                    verification: verificationStamp
                 };
                 discoveryPhase.discovered.foreignKeys.push(newFK);
                 feedback.newConfidence = newFK.confidence;