@duckcodeailabs/dql-agent 1.6.31 → 1.6.32

package/dist/metadata/catalog.js

@@ -10,12 +10,14 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { buildManifest, loadProjectConfig, parseContractRef, resolveDataLexManifestPath, resolveDbtManifestPath, resolveSemanticLayerWithDiagnostics, } from '@duckcodeailabs/dql-core';
+import { buildManifest, loadProjectConfig, parseContractRef, resolveDataLexManifestPath, resolveDbtManifestPath, resolveSemanticLayerWithDiagnostics, extractColumnLineage, normalizeDqlArtifactReference, composeEffectiveTrust, } from '@duckcodeailabs/dql-core';
 import { buildKGFromManifest, buildKGFromSemanticLayer } from '../kg/build.js';
 import { buildBlockBusinessFingerprint, buildBlockSqlFingerprints } from './block-fingerprints.js';
 import { buildAnalysisQuestionPlan, certifiedApplicabilityForObject, scoreAllowedSqlRelationWithAnalysisPlan, scoreMetadataObjectWithAnalysisPlan, sortAllowedSqlContextForAnalysisPlan, } from './analysis-planner.js';
 import { extractSimpleSelectShape, sourceSqlShapeColumns } from './sql-shape.js';
+import { buildRuntimeValueIndex, normalizeValueIndexText, } from '../grounding/value-index.js';
 import { grainMatches, requestedGrainFromPlan, } from './grain-gate.js';
+import { certifiedFitAllowsTier1, evaluateCertifiedBlockFit, } from './block-fit.js';
 import { retrieveScopedHints } from '../hints/retrieval.js';
 const require = createRequire(import.meta.url);
 let databaseCtor = null;
@@ -23,8 +25,11 @@ function loadDatabase() {
     databaseCtor ??= require('better-sqlite3');
     return databaseCtor;
 }
+const SCHEMA_SHAPE_CACHE_LIMIT = 64;
+const schemaShapeCandidateCache = new Map();
 const OBJECT_PRIORITY = {
     dql_block: 1,
+    dql_block_output: 1.5,
     semantic_metric: 2,
     dql_term: 3,
     business_view: 4,
@@ -36,11 +41,14 @@ const OBJECT_PRIORITY = {
     dbt_source: 10,
     dbt_column: 11,
     warehouse_table: 12,
+    warehouse_column: 12.5,
+    runtime_value: 12.2,
     notebook: 13,
     dashboard: 14,
     app: 15,
     domain: 16,
 };
+const COLUMN_OBJECT_TYPES = new Set(['dbt_column', 'warehouse_column', 'runtime_column', 'runtime_value']);
 export function defaultMetadataPath(projectRoot) {
     return join(projectRoot, '.dql', 'cache', 'metadata.sqlite');
 }
@@ -104,8 +112,54 @@ export async function buildLocalContextPack(projectRoot, request) {
         const mode = request.mode ?? 'question';
         const followUp = normalizeFollowUpContext(request.followUp);
         const questionPlan = buildAnalysisQuestionPlan(request.question, followUp ?? undefined);
+        // ── Conversation-aware context reuse ──────────────────────────────────
+        // The prior turn's pack is fuel: a filter/limit-only REFINEMENT re-stamps it
+        // (skipping FTS fan-out, both ranking passes, route planning, and the
+        // fit-confirm LLM); CONTINUATION/RETURN seed its objects into ranking as
+        // candidates only; a SHIFT ignores it. A metadata fingerprint mismatch
+        // always disqualifies reuse.
+        const reusePolicy = request.reusePolicy ?? 'seed';
+        const priorPack = reusePolicy !== 'off'
+            && request.priorContextPackId
+            && request.conversationTopicRelation
+            && request.conversationTopicRelation !== 'shift'
+            ? catalog.getContextPack(request.priorContextPackId)
+            : null;
+        const priorPackFresh = Boolean(priorPack && priorPack.freshness.fingerprint === catalog.state('fingerprint'));
+        if (priorPack
+            && priorPackFresh
+            && request.conversationTopicRelation === 'refinement'
+            && isFilterOnlyRefinement(priorPack.questionPlan, questionPlan)) {
+            // Route commitment: the prior route decision was already fit-validated for
+            // this grain/measures/dimensions; only filters/limit/timeframe changed.
+            const reusedPayload = {
+                ...priorPack,
+                question: request.question,
+                questionPlan,
+                followUp: followUp ?? undefined,
+                retrievalDiagnostics: {
+                    ...priorPack.retrievalDiagnostics,
+                    strategy: 'reused_pack_refinement',
+                },
+                freshness: {
+                    catalogPath: defaultMetadataPath(projectRoot),
+                    builtAt: catalog.state('built_at'),
+                    fingerprint: catalog.state('fingerprint'),
+                },
+            };
+            delete reusedPayload.id;
+            const reusedId = catalog.insertContextPack(reusedPayload);
+            return { ...reusedPayload, id: reusedId };
+        }
+        const priorSeedObjects = priorPack && priorPackFresh
+            && (request.conversationTopicRelation === 'continuation'
+                || request.conversationTopicRelation === 'refinement'
+                || request.conversationTopicRelation === 'return')
+            ? priorPack.objects.slice(0, 24)
+            : [];
         const runtimeSnapshot = request.runtimeSchemaSnapshot ?? catalog.latestRuntimeSchemaSnapshot();
         const runtimeObjects = runtimeSnapshot ? runtimeSchemaObjects(runtimeSnapshot) : [];
+        const runtimeValueObjects = runtimeValueMatchObjects(catalog.searchRuntimeValues(metadataValueSearchTerms(request.question, questionPlan, followUp), 32));
         const selectedObjects = selectedContextObjects(request.selectedContext);
         const followUpObjects = followUpContextObjects(followUp);
         const followUpSourceObjects = catalog.getObjectsByKeys(followUpSourceObjectKeys(followUp));
@@ -118,38 +172,56 @@ export async function buildLocalContextPack(projectRoot, request) {
             objectTypes: request.objectTypes,
             limit: Math.max(request.limit ?? 80, 20),
         })));
-        const schemaShapeCandidates = schemaShapeCandidateObjects(catalog, questionPlan, request, runtimeObjects);
+        const schemaShapeCandidates = schemaShapeCandidateObjects(catalog, questionPlan, request, mergeObjects([...runtimeObjects, ...runtimeValueObjects]));
         const schemaShapeObjects = schemaShapeCandidates.map((candidate) => candidate.object);
         const exact = request.focusObjectKey ? catalog.getObject(request.focusObjectKey) : null;
         const ranked = rankMetadataObjects({
             rows: mergeObjects(exact
-                ? [exact, ...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...selectedObjects]
-                : [...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...selectedObjects]),
+                ? [exact, ...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects, ...priorSeedObjects]
+                : [...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects, ...priorSeedObjects]),
             question: searchQueries.join(' '),
             questionPlan,
             limit: request.limit ?? 80,
         });
-        const selected = mergeObjects([...followUpSourceObjects, ...followUpObjects, ...ranked.selected]);
+        // Advisory 'contextual' carry: the prior turn's block competes on rank (it is
+        // already in the candidate rows above) but is never FORCED into selection or
+        // allowed to become the derived focus of a possibly-new-topic question.
+        const selected = followUp?.kind === 'contextual'
+            ? ranked.selected
+            : mergeObjects([...followUpSourceObjects, ...followUpObjects, ...ranked.selected]);
         const focusObjectKey = request.focusObjectKey ?? selected[0]?.objectKey ?? null;
         const edgeWalk = catalog.edgesForKeys(selected.map((row) => row.objectKey), 3);
         const edgeObjectKeys = Array.from(new Set(edgeWalk.flatMap((edge) => [edge.fromKey, edge.toKey])));
         const graphObjects = catalog.getObjectsByKeys(edgeObjectKeys);
         const rankedObjects = rankMetadataObjects({
-            rows: mergeObjects([...followUpSourceObjects, ...followUpObjects, ...selected, ...graphObjects, ...schemaShapeObjects, ...runtimeObjects, ...selectedObjects]),
+            rows: mergeObjects([...followUpSourceObjects, ...followUpObjects, ...selected, ...graphObjects, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects]),
             question: searchQueries.join(' '),
             questionPlan,
             limit: request.limit ?? 120,
         }).selected;
         const sqlParentObjects = sqlParentObjectsForSelectedColumns(rankedObjects, mergeObjects([...graphObjects, ...runtimeObjects]), questionPlan);
-        const objects = mergeObjects([...rankedObjects, ...sqlParentObjects]);
+        // Deep-research over a SMALL catalog: skip top-k pruning and hand the model the
+        // entire relation set ("send everything, let the agent decide"). Only when the
+        // whole catalog fits comfortably in context — otherwise we keep ranked selection.
+        const fullCatalogObjects = request.strictness === 'exploratory'
+            ? collectFullCatalogObjects(catalog)
+            : undefined;
+        const usedFullCatalog = Boolean(fullCatalogObjects);
+        const objects = fullCatalogObjects
+            ? mergeObjects([...rankedObjects, ...sqlParentObjects, ...fullCatalogObjects])
+            : mergeObjects([...rankedObjects, ...sqlParentObjects]);
         const objectKeys = objects.map((row) => row.objectKey);
+        const contextEdges = mergeMetadataEdges([
+            ...edgeWalk,
+            ...catalog.edgesForKeys(objectKeys, 2),
+        ]);
         const queryRuns = catalog.queryRunsForObjectKeys(objectKeys, 20);
         const diagnostics = catalog.diagnostics();
         const warnings = buildWarnings(diagnostics, objects);
         const trustLabel = deriveTrust(objects);
-        const citations = buildCitations(objects, edgeWalk);
-        const evidenceSummaries = buildEvidenceSummaries(objects, edgeWalk, queryRuns, diagnostics);
-        const allowedSqlContext = sortAllowedSqlContextForAnalysisPlan(buildAllowedSqlContext(objects, edgeWalk), questionPlan);
+        const citations = buildCitations(objects, contextEdges);
+        const evidenceSummaries = buildEvidenceSummaries(objects, contextEdges, queryRuns, diagnostics);
+        const allowedSqlContext = sortAllowedSqlContextForAnalysisPlan(buildAllowedSqlContext(objects, contextEdges), questionPlan);
         const selectedRelations = allowedSqlContext.relations.slice(0, 24).map((relation, index) => {
             const scored = scoreAllowedSqlRelationWithAnalysisPlan(relation, questionPlan);
             return {
@@ -162,7 +234,7 @@ export async function buildLocalContextPack(projectRoot, request) {
                 rank: index + 1,
             };
         });
-        const selectedJoinPaths = buildSelectedJoinPaths(allowedSqlContext);
+        const selectedJoinPaths = buildSelectedJoinPaths(allowedSqlContext, contextEdges);
         const evidenceRoles = buildEvidenceRoles(objects, queryRuns);
         const reranked = rankMetadataObjects({
             rows: mergeObjects([...searchRows, ...schemaShapeObjects, ...objects]),
@@ -172,7 +244,7 @@ export async function buildLocalContextPack(projectRoot, request) {
         });
         const conflicts = buildCandidateConflicts(reranked.ranked);
         const compileConflicts = catalog.compileConflicts();
-        const routeDecision = planContextPackRoute({
+        const routeDecision = withMetadataTrustLabelInfo(await planContextPackRoute({
             request,
             objects,
             allowedSqlContext,
@@ -182,6 +254,12 @@ export async function buildLocalContextPack(projectRoot, request) {
             questionPlan,
             compileConflicts,
             rankedObjects: reranked.ranked,
+        }));
+        const certifiedCandidateFits = buildCertifiedCandidateFitDiagnostics({
+            request,
+            objects,
+            questionPlan,
+            routeDecision,
         });
         // Approved scoped correction hints — folded in AFTER certified routing so
         // they never override a certified answer. On the `certified` route we still
@@ -199,8 +277,9 @@ export async function buildLocalContextPack(projectRoot, request) {
             mode,
             questionPlan,
             trustLabel,
+            trustLabelInfo: metadataTrustLabelInfo(trustLabel),
             objects,
-            edges: edgeWalk,
+            edges: contextEdges,
             queryRuns,
             citations,
             evidenceSummaries,
@@ -213,7 +292,7 @@ export async function buildLocalContextPack(projectRoot, request) {
             appliedHints: hintResult.applied,
             hintConflicts: hintResult.conflicts,
             retrievalDiagnostics: {
-                strategy: 'sqlite_fts',
+                strategy: usedFullCatalog ? 'full_catalog' : 'sqlite_fts',
                 selectedObjects: objects.length,
                 selectedEvidence: reranked.ranked.slice(0, 20).map((item) => ({
                     objectKey: item.row.objectKey,
@@ -234,6 +313,7 @@ export async function buildLocalContextPack(projectRoot, request) {
                     columns: candidate.relation.columns.slice(0, 16).map((column) => column.name),
                 })),
                 topRejected: reranked.rejected,
+                certifiedCandidateFits,
                 candidateConflicts: conflicts,
             },
             freshness: {
@@ -310,6 +390,7 @@ export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer) {
     addDbtDagObjects(manifest, objects, edges, diagnostics);
     addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges, diagnostics);
     addBlockDependencyEdges(manifest, edges);
+    addBlockOutputLineageObjects(manifest, objects, edges);
     addDataLexManifestObjects(projectRoot, manifest, objects, edges, diagnostics);
     const nodeKeyMap = new Map();
     for (const node of [...manifestGraph.nodes, ...semanticGraph.nodes]) {
@@ -429,6 +510,30 @@ export class MetadataCatalog {
       );
       CREATE INDEX IF NOT EXISTS idx_runtime_schema_snapshots_captured ON runtime_schema_snapshots(captured_at DESC);
 
+      CREATE TABLE IF NOT EXISTS runtime_value_index (
+        value_key        TEXT PRIMARY KEY,
+        relation         TEXT NOT NULL,
+        schema_name      TEXT,
+        table_name       TEXT,
+        column_name      TEXT NOT NULL,
+        column_type      TEXT,
+        value            TEXT NOT NULL,
+        normalized_value TEXT NOT NULL,
+        source           TEXT,
+        captured_at      TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_runtime_value_index_relation ON runtime_value_index(relation, column_name);
+      CREATE INDEX IF NOT EXISTS idx_runtime_value_index_captured ON runtime_value_index(captured_at DESC);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS runtime_value_fts USING fts5(
+        value_key UNINDEXED,
+        relation,
+        column_name,
+        value,
+        normalized_value,
+        tokenize = 'porter unicode61'
+      );
+
       CREATE TABLE IF NOT EXISTS metadata_state (
         key   TEXT PRIMARY KEY,
         value TEXT NOT NULL
@@ -713,13 +818,56 @@ export class MetadataCatalog {
             tables: normalizeRuntimeSchemaTables(snapshot.tables).slice(0, 500),
         };
         const id = `schema_${Date.parse(capturedAt) || Date.now()}`;
-        this.db.prepare(`
+        const valueEntries = buildRuntimeValueIndex(cleanSnapshot);
+        const insertSnapshot = this.db.prepare(`
       INSERT OR REPLACE INTO runtime_schema_snapshots (
         id, source, payload_json, captured_at
       ) VALUES (?, ?, ?, ?)
-    `).run(id, cleanSnapshot.source ?? null, JSON.stringify(cleanSnapshot), capturedAt);
+    `);
+        const insertValue = this.db.prepare(`
+      INSERT OR REPLACE INTO runtime_value_index (
+        value_key, relation, schema_name, table_name, column_name, column_type,
+        value, normalized_value, source, captured_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const insertValueFts = this.db.prepare(`
+      INSERT INTO runtime_value_fts (value_key, relation, column_name, value, normalized_value)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const setState = this.db.prepare(`
+      INSERT OR REPLACE INTO metadata_state (key, value) VALUES (?, ?)
+    `);
+        const txn = this.db.transaction(() => {
+            insertSnapshot.run(id, cleanSnapshot.source ?? null, JSON.stringify(cleanSnapshot), capturedAt);
+            this.db.prepare('DELETE FROM runtime_value_fts').run();
+            this.db.prepare('DELETE FROM runtime_value_index').run();
+            for (const entry of valueEntries) {
+                insertValue.run(entry.valueKey, entry.relation, entry.schema ?? null, entry.tableName ?? null, entry.columnName, entry.columnType ?? null, entry.value, entry.normalizedValue, entry.source ?? null, entry.capturedAt);
+                insertValueFts.run(entry.valueKey, entry.relation, entry.columnName, entry.value, entry.normalizedValue);
+            }
+            setState.run('runtime_value_index_count', String(valueEntries.length));
+            setState.run('runtime_value_index_captured_at', capturedAt);
+        });
+        txn();
         return cleanSnapshot;
     }
+    searchRuntimeValues(terms, limit = 40) {
+        const cleanTerms = uniqueStrings(terms.map(normalizeValueIndexText).filter(Boolean)).slice(0, 8);
+        const query = sanitizeFtsQuery(cleanTerms.join(' '));
+        if (!query)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT v.*,
+             bm25(runtime_value_fts) AS rank
+      FROM runtime_value_fts
+      JOIN runtime_value_index AS v ON v.value_key = runtime_value_fts.value_key
+      WHERE runtime_value_fts MATCH ?
+      ORDER BY rank
+      LIMIT ?
+    `).all(query, Math.max(1, limit));
+        return rows.map((row) => rowToRuntimeValueMatch(row, cleanTerms))
+            .sort((a, b) => b.score - a.score || a.relation.localeCompare(b.relation) || a.columnName.localeCompare(b.columnName));
+    }
     latestRuntimeSchemaSnapshot() {
         const row = this.db.prepare(`
       SELECT payload_json
@@ -821,20 +969,35 @@ function loadAgentSemanticLayer(projectRoot) {
                 ? { provider: 'dql', path: config.semanticLayer.path }
                 : undefined;
         const configured = resolveSemanticLayerWithDiagnostics(semanticConfig, projectRoot).layer;
-        if (configured)
+        // An EMPTY configured layer (e.g. `provider: 'dql'` pointing at a folder
+        // with no definitions — the scaffold default) must not shadow a real dbt
+        // MetricFlow semantic layer: that starves the catalog of every
+        // semantic_metric object and the governed-metric answer tier can never
+        // fire. Mirror the runtime's resolveProjectSemanticConfig preference:
+        // substance wins over configuration.
+        if (configured && semanticLayerHasContent(configured))
             return configured;
         if (config.dbt?.projectDir) {
-            return resolveSemanticLayerWithDiagnostics({
+            const dbtLayer = resolveSemanticLayerWithDiagnostics({
                 provider: 'dbt',
                 projectPath: config.dbt.projectDir,
-            }, projectRoot).layer ?? undefined;
+            }, projectRoot).layer;
+            if (dbtLayer && semanticLayerHasContent(dbtLayer))
+                return dbtLayer;
         }
+        return configured ?? undefined;
     }
     catch {
         return undefined;
     }
     return undefined;
 }
+/** True when the layer defines ANY semantics — metrics, dimensions, or measures. */
+function semanticLayerHasContent(layer) {
+    return layer.listMetrics().length > 0
+        || layer.listDimensions().length > 0
+        || layer.listMeasures().length > 0;
+}
 function manifestDiagnosticToMetadataDiagnostic(diagnostic) {
     return {
         kind: diagnostic.kind,
@@ -860,6 +1023,8 @@ function objectFromKGNode(node) {
         grain: node.grain,
         entities: node.entities ?? [],
         declaredOutputs: node.declaredOutputs ?? [],
+        outputs: node.outputs ?? [],
+        outputContract: node.outputContract ?? [],
         dimensions: node.dimensions ?? [],
         allowedFilters: node.allowedFilters ?? [],
         parameterPolicy: node.parameterPolicy ?? [],
@@ -964,6 +1129,7 @@ function addDbtDagObjects(manifest, objects, edges, diagnostics) {
                 materialized: model.materialized,
                 dependsOn: model.dependsOn,
                 columns: model.columns ?? [],
+                columnCompleteness: 'partial',
             }),
         };
         objects.set(objectKey, mergeObject(objects.get(objectKey), object));
@@ -982,6 +1148,7 @@ function addDbtDagObjects(manifest, objects, edges, diagnostics) {
                     uniqueId: model.uniqueId,
                     type: column.type,
                     relation,
+                    columnCompleteness: 'partial',
                 }),
             }));
             const edge = {
@@ -1029,18 +1196,30 @@ function addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges,
         });
         return;
     }
+    const catalogColumns = loadRawDbtCatalogColumns(join(dirname(manifestPath), 'catalog.json'));
+    const entries = [];
     for (const [uniqueId, node] of Object.entries(raw.nodes ?? {})) {
         if (node.resource_type !== 'model')
             continue;
         const name = rawDbtName(node);
         if (!name)
             continue;
-        addRawDbtCatalogObject({
+        const database = stringValue(node.database);
+        const schema = stringValue(node.schema);
+        const entry = {
             uniqueId,
             name,
             node,
             objectKey: `dbt:model:${name}`,
             objectType: 'dbt_model',
+            relation: [database, schema, name].filter(Boolean).join('.'),
+            database,
+            schema,
+            catalogColumns: catalogColumns.get(uniqueId),
+        };
+        entries.push(entry);
+        addRawDbtCatalogObject({
+            ...entry,
             objects,
             edges,
         });
@@ -1049,23 +1228,42 @@ function addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges,
         const name = rawDbtName(source);
         if (!name)
             continue;
-        addRawDbtCatalogObject({
+        const database = stringValue(source.database);
+        const schema = stringValue(source.schema);
+        const entry = {
             uniqueId,
             name,
             node: source,
             objectKey: `dbt:source:${name}`,
             objectType: 'dbt_source',
+            relation: [database, schema, name].filter(Boolean).join('.'),
+            database,
+            schema,
+            catalogColumns: catalogColumns.get(uniqueId),
+        };
+        entries.push(entry);
+        addRawDbtCatalogObject({
+            ...entry,
             objects,
             edges,
         });
     }
+    const relationLookup = buildRawDbtRelationLookup(entries);
+    for (const entry of entries) {
+        if (entry.objectType !== 'dbt_model')
+            continue;
+        addRawDbtCompiledColumnLineage(entry, relationLookup, objects, edges);
+    }
 }
 function addRawDbtCatalogObject(input) {
     const existing = input.objects.get(input.objectKey);
-    const database = stringValue(input.node.database);
-    const schema = stringValue(input.node.schema);
-    const relation = [database, schema, input.name].filter(Boolean).join('.');
-    const columns = rawDbtColumns(input.node.columns);
+    const database = input.database ?? stringValue(input.node.database);
+    const schema = input.schema ?? stringValue(input.node.schema);
+    const relation = input.relation || [database, schema, input.name].filter(Boolean).join('.');
+    const columns = input.catalogColumns && input.catalogColumns.length > 0
+        ? input.catalogColumns
+        : rawDbtColumns(input.node.columns);
+    const columnCompleteness = input.catalogColumns && input.catalogColumns.length > 0 ? 'complete' : 'partial';
     input.objects.set(input.objectKey, mergeObject(existing, {
         objectKey: input.objectKey,
         objectType: input.objectType,
@@ -1085,6 +1283,7 @@ function addRawDbtCatalogObject(input) {
             dependsOn: rawDbtDependsOn(input.node),
             tags: metadataStringArray(input.node.tags),
             catalogOnly: existing ? undefined : true,
+            columnCompleteness,
             columns,
         }),
     }));
@@ -1106,6 +1305,7 @@ function addRawDbtCatalogObject(input) {
                 uniqueId: input.uniqueId,
                 type: column.type,
                 relation,
+                columnCompleteness: 'partial',
                 catalogOnly: existingColumn ? undefined : true,
             }),
         }));
@@ -1127,6 +1327,124 @@ function addRawDbtCatalogObject(input) {
         });
     }
 }
+function addRawDbtCompiledColumnLineage(entry, relationLookup, objects, edges) {
+    const sql = rawDbtCompiledSql(entry.node);
+    if (!sql)
+        return;
+    const lineage = extractColumnLineage(sql);
+    if (!lineage.parsed || lineage.columns.length === 0)
+        return;
+    for (const column of lineage.columns) {
+        if (!column.name || column.name === '*' || column.name.endsWith('.*'))
+            continue;
+        const outputKey = ensureDbtLineageOutputColumnObject(entry, column, objects);
+        for (const source of column.sources) {
+            if (!source.column || source.column === '*')
+                continue;
+            const targetKey = ensureDbtLineageSourceColumnObject(source, relationLookup, objects);
+            putEdge(edges, {
+                edgeType: 'derives_from',
+                fromKey: outputKey,
+                toKey: targetKey,
+                confidence: column.unresolved ? 0.55 : 0.88,
+                payload: compactObject({
+                    source: 'dbt compiled SQL column lineage',
+                    model: entry.name,
+                    output: column.name,
+                    table: source.table,
+                    column: source.column,
+                    isAggregate: column.isAggregate,
+                    aggregateFn: column.aggregateFn,
+                }),
+            });
+        }
+    }
+}
+function ensureDbtLineageOutputColumnObject(entry, column, objects) {
+    const columnKey = `dbt:column:${entry.name}.${column.name}`;
+    const existing = objects.get(columnKey);
+    objects.set(columnKey, mergeObject(existing, {
+        objectKey: columnKey,
+        objectType: 'dbt_column',
+        name: column.name,
+        fullName: `${entry.name}.${column.name}`,
+        status: existing?.status ?? 'dbt_compiled_lineage',
+        sourcePath: existing?.sourcePath ?? stringValue(entry.node.original_file_path) ?? stringValue(entry.node.path),
+        sourceSystem: existing?.sourceSystem ?? 'dbt compiled SQL lineage',
+        payload: compactObject({
+            ...(existing?.payload ?? {}),
+            model: entry.name,
+            uniqueId: entry.uniqueId,
+            relation: entry.relation,
+            compiledSqlLineage: true,
+            isAggregate: column.isAggregate,
+            aggregateFn: column.aggregateFn,
+            lineageSources: column.sources,
+        }),
+    }));
+    return columnKey;
+}
+function ensureDbtLineageSourceColumnObject(source, relationLookup, objects) {
+    const dbtSource = resolveRawDbtRelationForTable(source.table, relationLookup);
+    if (dbtSource) {
+        const columnKey = `dbt:column:${dbtSource.name}.${source.column}`;
+        const existing = objects.get(columnKey);
+        if (existing)
+            return columnKey;
+        objects.set(columnKey, {
+            objectKey: columnKey,
+            objectType: 'dbt_column',
+            name: source.column,
+            fullName: `${dbtSource.name}.${source.column}`,
+            status: 'dbt_compiled_lineage',
+            sourceSystem: 'dbt compiled SQL lineage',
+            payload: compactObject({
+                model: dbtSource.name,
+                uniqueId: dbtSource.uniqueId,
+                relation: dbtSource.relation,
+                inferredFromCompiledSql: true,
+            }),
+        });
+        return columnKey;
+    }
+    return ensureWarehouseLineageSourceColumnObject(source, objects, 'dbt compiled SQL lineage');
+}
+function buildRawDbtRelationLookup(entries) {
+    const lookup = new Map();
+    const add = (key, entry) => {
+        if (!key)
+            return;
+        const normalized = normalizeRelationKey(key);
+        if (!normalized)
+            return;
+        const existing = lookup.get(normalized);
+        if (existing)
+            existing.add(entry);
+        else
+            lookup.set(normalized, new Set([entry]));
+    };
+    for (const entry of entries) {
+        add(entry.uniqueId, entry);
+        add(entry.name, entry);
+        add(entry.relation, entry);
+        for (const key of dbtModelLookupKeys(entry.name, entry.schema, entry.database)) {
+            add(key, entry);
+        }
+    }
+    return lookup;
+}
+function resolveRawDbtRelationForTable(tableRef, relationLookup) {
+    for (const key of tableReferenceLookupKeys(tableRef)) {
+        const matches = relationLookup.get(key);
+        if (matches?.size === 1)
+            return [...matches][0];
+    }
+    return undefined;
+}
+function rawDbtCompiledSql(node) {
+    return stringValue(node.compiled_code)
+        ?? stringValue(node.compiled_sql);
+}
 function rawDbtName(node) {
     return stringValue(node.alias) ?? stringValue(node.identifier) ?? stringValue(node.name);
 }
@@ -1140,6 +1458,41 @@ function rawDbtDependsOn(node) {
         : null;
     return metadataStringArray(dependsOn?.nodes);
 }
+function loadRawDbtCatalogColumns(catalogPath) {
+    const out = new Map();
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(catalogPath, 'utf-8'));
+    }
+    catch {
+        return out;
+    }
+    for (const entries of [raw.nodes ?? {}, raw.sources ?? {}]) {
+        for (const [uniqueId, node] of Object.entries(entries)) {
+            const columns = rawDbtCatalogColumns(node.columns);
+            if (columns.length > 0)
+                out.set(uniqueId, columns);
+        }
+    }
+    return out;
+}
+function rawDbtCatalogColumns(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    return Object.entries(value).flatMap(([key, entry]) => {
+        if (!entry || typeof entry !== 'object')
+            return [];
+        const record = entry;
+        const name = stringValue(record.name) ?? stringValue(record.column_name) ?? key;
+        if (!name)
+            return [];
+        return [{
+                name,
+                type: stringValue(record.type) ?? stringValue(record.data_type),
+                description: stringValue(record.comment) ?? stringValue(record.description),
+            }];
+    });
+}
 function rawDbtColumns(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return [];
@@ -1163,6 +1516,9 @@ function addManifestBlockDetails(manifest, objects) {
         const existing = objects.get(objectKey);
         if (!existing)
             continue;
+        const contractOutputNames = block.declaredOutputs
+            ?? block.outputContract?.map((output) => output.name).filter(Boolean)
+            ?? block.outputs?.map((output) => output.name).filter(Boolean);
         objects.set(objectKey, mergeObject(existing, {
             ...existing,
             payload: compactObject({
@@ -1173,6 +1529,9 @@ function addManifestBlockDetails(manifest, objects) {
                 refDependencies: block.refDependencies,
                 metricRefs: block.metricRefs,
                 dimensionRefs: block.dimensionRefs,
+                declaredOutputs: block.declaredOutputs,
+                outputs: block.outputs,
+                outputContract: block.outputContract,
                 dimensions: block.dimensions,
                 chartType: block.chartType,
                 blockType: block.blockType,
@@ -1187,7 +1546,7 @@ function addManifestBlockDetails(manifest, objects) {
                     grain: block.grain,
                     entities: block.entities,
                     terms: block.termRefs,
-                    outputs: block.declaredOutputs,
+                    outputs: contractOutputNames,
                     dimensions: block.dimensions,
                     filters: block.allowedFilters,
                     sources: [...(block.tableDependencies ?? []), ...(block.rawTableRefs ?? [])],
@@ -1226,6 +1585,9 @@ function addDataLexManifestObjects(projectRoot, manifest, objects, edges, diagno
     }
     const latestContractKeyById = new Map();
     const contractKeyByVersionedRef = new Map();
+    // entity (by name and domain.entity) -> physical binding ref, so relationships
+    // can be resolved to concrete relations for grain-safe join hints.
+    const entityBindingRef = new Map();
     for (const domain of raw.domains) {
         if (!domain?.name)
             continue;
@@ -1279,6 +1641,11 @@ function addDataLexManifestObjects(projectRoot, manifest, objects, edges, diagno
             if (!entity?.name)
                 continue;
             const entityKey = `datalex:entity:${domain.name}.${entity.name}`;
+            if (entity.binding?.ref) {
+                const boundKey = objectKeyForDataLexBinding(entity.binding);
+                entityBindingRef.set(entity.name.toLowerCase(), boundKey);
+                entityBindingRef.set(`${domain.name}.${entity.name}`.toLowerCase(), boundKey);
+            }
             objects.set(entityKey, mergeObject(objects.get(entityKey), {
                 objectKey: entityKey,
                 objectType: 'datalex_entity',
@@ -1350,6 +1717,33 @@ function addDataLexManifestObjects(projectRoot, manifest, objects, edges, diagno
             }
         }
     }
+    // Typed cross-entity relationships → grain-safe join edges between the entities'
+    // physical relations. buildSelectedJoinPaths turns these into `datalex`-sourced
+    // join paths that outrank name-heuristic guesses.
+    const resolveEntityRef = (endpoint) => entityBindingRef.get(`${endpoint.domain ?? ''}.${endpoint.entity}`.toLowerCase())
+        ?? entityBindingRef.get(endpoint.entity.toLowerCase());
+    for (const relationship of raw.relationships ?? []) {
+        if (!relationship?.from?.entity || !relationship?.to?.entity)
+            continue;
+        const fromRef = resolveEntityRef(relationship.from);
+        const toRef = resolveEntityRef(relationship.to);
+        if (!fromRef || !toRef || fromRef.toLowerCase() === toRef.toLowerCase())
+            continue;
+        putEdge(edges, {
+            edgeType: 'datalex_join',
+            fromKey: fromRef,
+            toKey: toRef,
+            confidence: relationship.identifying ? 0.97 : 0.9,
+            payload: compactObject({
+                source: 'datalex relationship',
+                name: relationship.name,
+                fromColumn: relationship.from.column,
+                toColumn: relationship.to.column,
+                cardinality: relationship.cardinality,
+                verb: relationship.verb,
+            }),
+        });
+    }
     for (const block of Object.values(manifest.blocks ?? {})) {
         if (!block.datalexContract)
             continue;
@@ -1406,6 +1800,112 @@ function addBlockDependencyEdges(manifest, edges) {
         }
     }
 }
+function addBlockOutputLineageObjects(manifest, objects, edges) {
+    const dbtLookup = buildDbtModelLookup(manifest);
+    for (const block of Object.values(manifest.blocks ?? {})) {
+        if (!isCertifiedManifestBlock(block))
+            continue;
+        if (!Array.isArray(block.outputs) || block.outputs.length === 0)
+            continue;
+        const blockKey = `dql:block:${block.name}`;
+        for (const output of block.outputs) {
+            const outputName = typeof output.name === 'string' ? output.name.trim() : '';
+            if (!outputName)
+                continue;
+            const outputKey = blockOutputObjectKey(block.name, outputName);
+            objects.set(outputKey, mergeObject(objects.get(outputKey), {
+                objectKey: outputKey,
+                objectType: 'dql_block_output',
+                name: outputName,
+                fullName: `${block.name}.${outputName}`,
+                domain: block.domain,
+                owner: block.owner,
+                status: block.status,
+                description: `${outputName} output column from DQL block ${block.name}.`,
+                sourcePath: block.filePath,
+                sourceSystem: 'DQL block column lineage',
+                payload: compactObject({
+                    block: block.name,
+                    output: outputName,
+                    isAggregate: output.isAggregate,
+                    aggregateFn: output.aggregateFn,
+                    unresolved: output.unresolved,
+                    sources: output.sources ?? [],
+                }),
+            }));
+            putEdge(edges, {
+                edgeType: 'contains',
+                fromKey: blockKey,
+                toKey: outputKey,
+                confidence: 1,
+                payload: { source: 'dql block output lineage', output: outputName },
+            });
+            for (const source of output.sources ?? []) {
+                const targetKey = ensureLineageSourceColumnObject(source, dbtLookup, objects);
+                putEdge(edges, {
+                    edgeType: 'derives_from',
+                    fromKey: outputKey,
+                    toKey: targetKey,
+                    confidence: output.unresolved ? 0.55 : 0.92,
+                    payload: {
+                        source: 'dql block output column lineage',
+                        block: block.name,
+                        output: outputName,
+                        table: source.table,
+                        column: source.column,
+                        aggregateFn: output.aggregateFn,
+                    },
+                });
+            }
+        }
+    }
+}
+function isCertifiedManifestBlock(block) {
+    return block.status === 'certified'
+        || block.status === 'approved';
+}
+function ensureLineageSourceColumnObject(source, dbtLookup, objects) {
+    const dbtModelKey = resolveDbtModelKeyForTable(source.table, dbtLookup);
+    if (dbtModelKey) {
+        const modelName = dbtModelKey.split(':').at(-1) ?? source.table;
+        const columnKey = `dbt:column:${modelName}.${source.column}`;
+        if (objects.has(columnKey))
+            return columnKey;
+    }
+    return ensureWarehouseLineageSourceColumnObject(source, objects, 'DQL block column lineage');
+}
+function ensureWarehouseLineageSourceColumnObject(source, objects, sourceSystem) {
+    const tableKey = `warehouse:table:${source.table}`;
+    if (!objects.has(tableKey)) {
+        objects.set(tableKey, {
+            objectKey: tableKey,
+            objectType: 'warehouse_table',
+            name: source.table.split('.').at(-1) ?? source.table,
+            fullName: source.table,
+            status: 'referenced',
+            sourceSystem,
+            payload: compactObject({ relation: source.table }),
+        });
+    }
+    const columnKey = `warehouse:column:${source.table}.${source.column}`;
+    objects.set(columnKey, mergeObject(objects.get(columnKey), {
+        objectKey: columnKey,
+        objectType: 'warehouse_column',
+        name: source.column,
+        fullName: `${source.table}.${source.column}`,
+        status: 'referenced',
+        sourceSystem,
+        payload: compactObject({
+            relation: source.table,
+            table: source.table,
+            column: source.column,
+        }),
+    }));
+    return columnKey;
+}
+function blockOutputObjectKey(blockName, outputName) {
+    return `dql:block_output:${blockName}.${outputName}`;
+}
 function putEdge(edges, edge) {
     edges.set(`${edge.edgeType}\u0000${edge.fromKey}\u0000${edge.toKey}`, edge);
 }
@@ -1525,7 +2025,7 @@ function firstNonEmpty(...values) {
 function lowerOrUndef(value) {
     return value ? value.trim().toLowerCase() : undefined;
 }
-function planContextPackRoute(input) {
+async function planContextPackRoute(input) {
     const intent = input.request.intent ?? input.questionPlan.routeIntent ?? classifyMetadataIntent(input.request.question, input.request.followUp);
     // Conflict route (additive, evaluated first): if the question's top governed
     // candidates include BOTH sides of a compile-time trust conflict, refuse to
@@ -1533,7 +2033,7 @@ function planContextPackRoute(input) {
     // prompt. Only fires when both conflicting sides are actually among the
     // selected candidates for THIS question, so non-conflicting asks are
     // unaffected even when a conflict exists elsewhere in the project.
-    const routeConflict = pickRouteConflict(input.compileConflicts ?? [], input.rankedObjects ?? [], input.objects);
+    const routeConflict = pickRouteConflict(input.compileConflicts ?? [], input.rankedObjects ?? [], input.objects, input.request.question);
     if (routeConflict) {
         const selectedEvidenceForConflict = input.evidenceRoles.slice(0, 16);
         return {
@@ -1566,6 +2066,30 @@ function planContextPackRoute(input) {
         .filter((item) => item.kind === 'context_only')
         .sort((a, b) => b.score - a.score)[0];
     const exactExampleMatch = exact ? hasExactExampleQuestion(input.request.question, exact) : false;
+    const directCertifiedBypass = Boolean(exact && (exactExampleMatch
+        || intent === 'definition_lookup'
+        || intent === 'exact_certified_lookup'
+        || objectNameInQuestion(input.request.question, exact)));
+    const blockFitObject = exact
+        ?? (contextApplicability ? input.objects.find((object) => object.objectKey === contextApplicability.objectKey) : undefined);
+    const rawBlockFit = blockFitObject
+        ? evaluateCertifiedBlockFit({
+            question: input.request.question,
+            plan: input.questionPlan,
+            block: blockFitObject,
+            exactExampleMatch: exact ? exactExampleMatch : false,
+            definitionLookup: Boolean(exact && intent === 'definition_lookup'),
+        })
+        : undefined;
+    const blockFit = rawBlockFit && blockFitObject
+        ? await confirmMediumCertifiedFit({
+            request: input.request,
+            questionPlan: input.questionPlan,
+            block: blockFitObject,
+            fit: rawBlockFit,
+            directCertifiedBypass,
+        })
+        : rawBlockFit;
     const missingContext = buildMissingContext(input.request, intent, input.objects, input.allowedSqlContext);
     const selectedEvidence = input.evidenceRoles.slice(0, 16);
     // Grain / contract gate (refinement of the existing certified→generated
@@ -1596,7 +2120,9 @@ function planContextPackRoute(input) {
         input.allowedSqlContext.sourceBlockSql.length > 0 ||
         input.objects.some((object) => object.objectType.startsWith('semantic_'));
     const grainGateDemotes = Boolean(grainGate && !grainGate.allow && canGenerateFromContext);
-    if (!grainGateDemotes && exact && (certifiedApplicability?.kind === 'exact_answer'
+    const blockFitDemotes = Boolean(blockFit && !certifiedFitAllowsTier1(blockFit) && !directCertifiedBypass && canGenerateFromContext);
+    const certifiedFitPassed = !blockFit || certifiedFitAllowsTier1(blockFit) || directCertifiedBypass;
+    if (!grainGateDemotes && !blockFitDemotes && certifiedFitPassed && exact && (certifiedApplicability?.kind === 'exact_answer'
         || certifiedApplicability?.kind === 'safe_parameterized'
         || intent === 'exact_certified_lookup'
         || intent === 'definition_lookup'
@@ -1608,6 +2134,7 @@ function planContextPackRoute(input) {
             reason: `Certified ${exact.objectType.replace(/_/g, ' ')} "${exact.name}" exactly matches the requested artifact, definition, or direct KPI grain.`,
             routeReason: grainGateInfo?.reason,
             grainGate: grainGateInfo,
+            blockFit,
             trustLabel: 'certified',
             reviewStatus: 'certified',
             exactObjectKey: exact.objectKey,
@@ -1627,6 +2154,25 @@ function planContextPackRoute(input) {
             reason: `Certified block "${exact.name}" is close but answers a different grain than the question, so it is context only and SQL is generated for the requested grain.`,
             routeReason: grainGate.reason,
             grainGate: grainGateInfo,
+            blockFit,
+            trustLabel: input.trustLabel === 'certified' ? 'mixed' : input.trustLabel,
+            reviewStatus: 'draft_ready',
+            certifiedApplicability: certifiedApplicability
+                ? { ...certifiedApplicability, kind: 'context_only' }
+                : contextApplicability,
+            selectedEvidence,
+            missingContext,
+            followUps: buildMetadataFollowUps(isGeneratedMetadataIntent(intent) ? intent : 'ad_hoc_ranking', input.allowedSqlContext),
+        };
+    }
+    if (blockFitDemotes && exact && blockFit) {
+        return {
+            route: 'generated_sql',
+            intent: isGeneratedMetadataIntent(intent) ? intent : 'ad_hoc_ranking',
+            reason: `Certified block "${exact.name}" is relevant but does not satisfy the requested answer shape, so it is context only and SQL is generated for the requested result.`,
+            routeReason: blockFit.reasons.join('; '),
+            grainGate: grainGateInfo,
+            blockFit,
             trustLabel: input.trustLabel === 'certified' ? 'mixed' : input.trustLabel,
             reviewStatus: 'draft_ready',
             certifiedApplicability: certifiedApplicability
@@ -1668,15 +2214,17 @@ function planContextPackRoute(input) {
             route: 'generated_sql',
             intent,
             reason: 'The question asks for a different grain, ranking, breakdown, comparison, entity drilldown, or diagnostic analysis, so certified artifacts are context only.',
+            routeReason: blockFit && !certifiedFitAllowsTier1(blockFit) ? blockFit.reasons.join('; ') : undefined,
             trustLabel: input.trustLabel === 'certified' ? 'mixed' : input.trustLabel,
             reviewStatus: 'draft_ready',
             certifiedApplicability: contextApplicability,
+            blockFit,
             selectedEvidence,
             missingContext,
             followUps: buildMetadataFollowUps(intent, input.allowedSqlContext),
         };
     }
-    if (exact) {
+    if (exact && certifiedFitPassed) {
         return {
             route: 'certified',
             intent: 'exact_certified_lookup',
@@ -1685,17 +2233,93 @@ function planContextPackRoute(input) {
             reviewStatus: 'certified',
             exactObjectKey: exact.objectKey,
             certifiedApplicability,
+            blockFit,
             selectedEvidence,
             missingContext: [],
             followUps: buildMetadataFollowUps('exact_certified_lookup', input.allowedSqlContext),
         };
     }
+    if (exact && blockFit && !certifiedFitAllowsTier1(blockFit)) {
+        return clarifyDecision(intent, input.trustLabel === 'certified' ? 'mixed' : input.trustLabel, selectedEvidence, [{
+                kind: 'metadata',
+                severity: 'blocking',
+                message: `The closest certified block "${exact.name}" does not exactly answer this question (${blockFit.reasons.join('; ')}), and there is not enough SQL context to safely generate the requested answer.`,
+            }]);
+    }
     return clarifyDecision(intent, input.trustLabel, selectedEvidence, missingContext.length > 0 ? missingContext : [{
             kind: 'metadata',
             severity: 'blocking',
             message: 'The local metadata matched some context, but not enough to choose a safe metric, table, or grain.',
         }]);
 }
+const CERTIFIED_FIT_CONFIRM_TIMEOUT_MS = 2500;
+async function confirmMediumCertifiedFit(input) {
+    const confirmer = input.request.confirmCertifiedFit;
+    if (!confirmer || input.directCertifiedBypass)
+        return input.fit;
+    if (input.fit.confidence !== 'medium')
+        return input.fit;
+    if (input.fit.kind !== 'exact' && input.fit.kind !== 'trim_safe')
+        return input.fit;
+    try {
+        const result = await withTimeout(confirmer({
+            question: input.request.question,
+            questionPlan: input.questionPlan,
+            block: input.block,
+            fit: input.fit,
+        }), CERTIFIED_FIT_CONFIRM_TIMEOUT_MS, 'certified fit confirmation timed out');
+        const reason = cleanConfirmationReason(result.reason);
+        if (result.allow && result.confidence !== 'low') {
+            return {
+                ...input.fit,
+                confidence: 'high',
+                reasons: [
+                    ...input.fit.reasons,
+                    `fit confirmation accepted this certified block${reason ? `: ${reason}` : ''}`,
+                ],
+            };
+        }
+        return {
+            ...input.fit,
+            kind: 'context_only',
+            confidence: 'high',
+            reasons: [
+                ...input.fit.reasons,
+                `fit confirmation rejected this certified block as a direct answer${reason ? `: ${reason}` : ''}`,
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ...input.fit,
+            reasons: [
+                ...input.fit.reasons,
+                `fit confirmation unavailable; kept review-required (${message})`,
+            ],
+        };
+    }
+}
+async function withTimeout(promise, ms, message) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error(message)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function cleanConfirmationReason(value) {
+    return typeof value === 'string'
+        ? value.replace(/\s+/g, ' ').trim().slice(0, 240)
+        : '';
+}
 function certifiedApplicabilities(objects, questionPlan) {
     const items = objects
         .filter((object) => object.objectType === 'dql_block' && isCertifiedMetadataObject(object))
@@ -1704,6 +2328,56 @@ function certifiedApplicabilities(objects, questionPlan) {
         .sort((a, b) => b.score - a.score);
     return new Map(items.map((item) => [item.objectKey, item]));
 }
+function buildCertifiedCandidateFitDiagnostics(input) {
+    return input.objects
+        .filter((object) => object.objectType === 'dql_block' && isCertifiedMetadataObject(object))
+        .map((object) => {
+        const applicability = certifiedApplicabilityForObject(object, input.questionPlan);
+        const fit = evaluateCertifiedBlockFit({
+            question: input.request.question,
+            plan: input.questionPlan,
+            block: object,
+            exactExampleMatch: hasExactExampleQuestion(input.request.question, object),
+            definitionLookup: input.routeDecision.intent === 'definition_lookup',
+        });
+        return {
+            objectKey: object.objectKey,
+            name: object.name,
+            applicabilityKind: applicability.kind,
+            applicabilityScore: applicability.score,
+            action: certifiedCandidateFitAction(object.objectKey, applicability, fit, input.routeDecision),
+            fit,
+        };
+    })
+        .filter((item) => item.applicabilityKind !== 'not_applicable' ||
+        item.fit.kind !== 'not_applicable' ||
+        item.action === 'certified_answer')
+        .sort((a, b) => certifiedCandidateActionRank(a.action) - certifiedCandidateActionRank(b.action) ||
+        b.applicabilityScore - a.applicabilityScore ||
+        a.name.localeCompare(b.name))
+        .slice(0, 12);
+}
+function certifiedCandidateFitAction(objectKey, applicability, fit, routeDecision) {
+    if (routeDecision.route === 'certified' && routeDecision.exactObjectKey === objectKey)
+        return 'certified_answer';
+    if (routeDecision.certifiedApplicability?.objectKey === objectKey && routeDecision.route !== 'certified')
+        return 'context_only';
+    if (!certifiedFitAllowsTier1(fit) || applicability.kind === 'context_only')
+        return 'rejected_for_fit';
+    return 'eligible_not_selected';
+}
+function certifiedCandidateActionRank(action) {
+    switch (action) {
+        case 'certified_answer':
+            return 0;
+        case 'context_only':
+            return 1;
+        case 'rejected_for_fit':
+            return 2;
+        case 'eligible_not_selected':
+            return 3;
+    }
+}
 function clarifyDecision(intent, trustLabel, selectedEvidence, missingContext) {
     return {
         route: 'clarify',
@@ -1994,14 +2668,18 @@ function buildEvidenceRoles(objects, queryRuns) {
 function evidenceRoleForObject(object) {
     if (object.objectType === 'dql_block' && isCertifiedMetadataObject(object))
         return 'certified_context';
+    if (object.objectType === 'dql_block_output')
+        return 'certified_context';
     if (object.objectType === 'semantic_metric')
         return 'semantic_metric';
     if (object.objectType === 'dql_term' || object.objectType === 'business_view')
         return 'business_context';
     if (object.objectType === 'dbt_model' || object.objectType === 'dbt_source' || object.objectType === 'dbt_column')
         return 'dbt_model';
-    if (object.objectType === 'warehouse_table')
+    if (object.objectType === 'warehouse_table' || object.objectType === 'warehouse_column')
         return 'warehouse_schema';
+    if (object.objectType === 'runtime_value')
+        return 'value_match';
     if (object.objectType === 'runtime_table' || object.objectType === 'runtime_column')
         return 'runtime_schema';
     if (object.objectType === 'selected_context')
@@ -2017,6 +2695,8 @@ function evidenceReasonForObject(object) {
         return 'Semantic definition can ground metric and dimension meaning.';
     if (object.objectType.startsWith('dbt_'))
         return 'dbt metadata supplies physical model and column context.';
+    if (object.objectType === 'runtime_value')
+        return 'Observed runtime value matched a literal in the question.';
     if (object.objectType === 'runtime_table' || object.objectType === 'runtime_column')
         return 'Runtime schema supplies executable table and column context.';
     return reasonForObject(object);
@@ -2027,7 +2707,7 @@ function sqlParentObjectsForSelectedColumns(selectedObjects, candidateObjects, q
     for (const object of candidateObjects) {
         if (!isSqlParentObject(object) || selectedKeys.has(object.objectKey))
             continue;
-        const relation = metadataRelationFromObject(object);
+        const relation = metadataObjectToAllowedSqlRelation(object);
         const key = relation ? normalizeRelationKey(relation.relation) : '';
         if (!relation || !key)
             continue;
@@ -2039,7 +2719,7 @@ function sqlParentObjectsForSelectedColumns(selectedObjects, candidateObjects, q
     for (const object of selectedObjects) {
         if (!isSqlColumnObject(object))
             continue;
-        const relation = metadataRelationFromObject(object);
+        const relation = metadataObjectToAllowedSqlRelation(object);
         const key = relation ? normalizeRelationKey(relation.relation) : '';
         if (!key)
             continue;
@@ -2062,8 +2742,52 @@ function schemaShapeCandidateObjects(catalog, questionPlan, request, runtimeObje
     if (!questionPlan.needsGeneratedSql)
         return [];
     const candidates = new Map();
+    for (const candidate of cachedCatalogSchemaShapeCandidates(catalog, questionPlan, request)) {
+        candidates.set(candidate.object.objectKey, candidate);
+    }
+    const considerObject = (object) => {
+        const relation = metadataObjectToAllowedSqlRelation(object);
+        if (!relation || relation.columns.length === 0)
+            return;
+        const shape = schemaShapeMatchForQuestion(relation, questionPlan);
+        if (shape.score <= 0)
+            return;
+        const relationScore = scoreAllowedSqlRelationWithAnalysisPlan(relation, questionPlan);
+        const objectScore = scoreMetadataObjectWithAnalysisPlan(object, questionPlan);
+        const score = Number((shape.score + relationScore.score + objectScore.score).toFixed(3));
+        if (score < schemaShapeMinimumScore(questionPlan))
+            return;
+        candidates.set(object.objectKey, {
+            object,
+            relation,
+            score,
+            reasons: [
+                ...shape.reasons,
+                ...relationScore.reasons.filter((reason) => /analysis terms|metric terms|dimension terms|columns match|inspected\/projected columns/i.test(reason)).slice(0, 3),
+            ],
+        });
+        trimSchemaShapeCandidateMap(candidates, 64);
+    };
+    for (const object of mergeObjects(runtimeObjects.filter(isSqlParentObject))) {
+        considerObject(object);
+    }
+    return Array.from(candidates.values())
+        .sort((a, b) => b.score - a.score || a.relation.relation.localeCompare(b.relation.relation))
+        .slice(0, 24);
+}
+function cachedCatalogSchemaShapeCandidates(catalog, questionPlan, request) {
+    const cacheKey = schemaShapeCacheKey(catalog, questionPlan);
+    if (cacheKey) {
+        const cached = schemaShapeCandidateCache.get(cacheKey);
+        if (cached) {
+            schemaShapeCandidateCache.delete(cacheKey);
+            schemaShapeCandidateCache.set(cacheKey, cached);
+            return cached;
+        }
+    }
+    const candidates = new Map();
     const considerObject = (object) => {
-        const relation = metadataRelationFromObject(object);
+        const relation = metadataObjectToAllowedSqlRelation(object);
         if (!relation || relation.columns.length === 0)
             return;
         const shape = schemaShapeMatchForQuestion(relation, questionPlan);
@@ -2092,12 +2816,25 @@ function schemaShapeCandidateObjects(catalog, questionPlan, request, runtimeObje
         for (const object of objects)
             considerObject(object);
     });
-    for (const object of mergeObjects(runtimeObjects.filter(isSqlParentObject))) {
-        considerObject(object);
-    }
-    return Array.from(candidates.values())
+    const result = Array.from(candidates.values())
         .sort((a, b) => b.score - a.score || a.relation.relation.localeCompare(b.relation.relation))
         .slice(0, 24);
+    if (cacheKey) {
+        schemaShapeCandidateCache.set(cacheKey, result);
+        while (schemaShapeCandidateCache.size > SCHEMA_SHAPE_CACHE_LIMIT) {
+            const oldest = schemaShapeCandidateCache.keys().next().value;
+            if (!oldest)
+                break;
+            schemaShapeCandidateCache.delete(oldest);
+        }
+    }
+    return result;
+}
+function schemaShapeCacheKey(catalog, questionPlan) {
+    const fingerprint = catalog.state('fingerprint');
+    if (!fingerprint)
+        return null;
+    return `${fingerprint}:${sha256(stableStringify(questionPlan))}`;
 }
 function schemaShapeScanBatchSize(request) {
     if (request.strictness === 'exploratory')
@@ -2269,6 +3006,32 @@ function isSqlParentObject(object) {
         object.objectType === 'warehouse_table' ||
         object.objectType === 'runtime_table';
 }
+const FULL_CATALOG_RELATION_TYPES = ['dbt_model', 'dbt_source', 'warehouse_table', 'runtime_table'];
+const FULL_CATALOG_COLUMN_TYPES = ['dbt_column', 'warehouse_column', 'runtime_column'];
+/** Deep mode over a catalog this small hands the model everything instead of top-k. */
+const FULL_CATALOG_MAX_RELATIONS = 40;
+const FULL_CATALOG_MAX_COLUMNS = 2000;
+/**
+ * When the whole catalog is small enough to fit in context, return every relation
+ * and column object so deep-research mode can reason over the complete schema.
+ * Returns undefined when the catalog exceeds the small-catalog budget, so ranked
+ * top-k selection stays in force for large warehouses.
+ */
+function collectFullCatalogObjects(catalog) {
+    const relations = catalog.listObjects({
+        objectTypes: FULL_CATALOG_RELATION_TYPES,
+        limit: FULL_CATALOG_MAX_RELATIONS + 1,
+    });
+    if (relations.length === 0 || relations.length > FULL_CATALOG_MAX_RELATIONS)
+        return undefined;
+    const columns = catalog.listObjects({
+        objectTypes: FULL_CATALOG_COLUMN_TYPES,
+        limit: FULL_CATALOG_MAX_COLUMNS + 1,
+    });
+    if (columns.length > FULL_CATALOG_MAX_COLUMNS)
+        return undefined;
+    return mergeObjects([...relations, ...columns]);
+}
 function buildAllowedSqlContext(objects, edges) {
     const byRelation = new Map();
     const objectsByKey = new Map(objects.map((object) => [object.objectKey, object]));
@@ -2281,18 +3044,20 @@ function buildAllowedSqlContext(objects, edges) {
             byRelation.set(key, { ...relation, columns: dedupeRuntimeColumns(relation.columns).slice(0, 120) });
             return;
         }
+        const columnCompleteness = mergeRelationCompletenessForCatalog(existing, relation);
         byRelation.set(key, {
             ...existing,
             objectKey: existing.objectKey ?? relation.objectKey,
             source: mergeRelationSources(existing.source, relation.source),
-            columns: dedupeRuntimeColumns([...existing.columns, ...relation.columns]).slice(0, 120),
+            columnCompleteness,
+            columns: mergeRelationColumns(existing, relation).slice(0, 120),
         });
     };
     for (const object of objects) {
         if (object.objectType === 'warehouse_table' && !warehouseTableHasTrustedReference(object, objectsByKey)) {
             continue;
         }
-        const relation = metadataRelationFromObject(object);
+        const relation = metadataObjectToAllowedSqlRelation(object);
         if (relation)
             addRelation(relation);
         if (object.objectType === 'dql_block' && !isCertifiedMetadataObject(object)) {
@@ -2304,6 +3069,7 @@ function buildAllowedSqlContext(objects, edges) {
                 name: table.split('.').at(-1) ?? table,
                 objectKey: object.objectKey,
                 source: 'certified block dependency',
+                columnCompleteness: 'partial',
                 columns: [],
             });
         }
@@ -2313,6 +3079,7 @@ function buildAllowedSqlContext(objects, edges) {
                 name: table.split('.').at(-1) ?? table,
                 objectKey: object.objectKey,
                 source: 'certified block SQL reference',
+                columnCompleteness: 'partial',
                 columns: [],
             });
         }
@@ -2324,6 +3091,7 @@ function buildAllowedSqlContext(objects, edges) {
                 name: shape.relation.split('.').at(-1) ?? shape.relation,
                 objectKey: object.objectKey,
                 source: 'certified source SQL shape',
+                columnCompleteness: 'partial',
                 columns: sourceSqlShapeColumns(sourceSql),
             });
         }
@@ -2333,11 +3101,12 @@ function buildAllowedSqlContext(objects, edges) {
             continue;
         const from = objectsByKey.get(edge.fromKey);
         const to = objectsByKey.get(edge.toKey);
-        const fromRelation = from ? metadataRelationFromObject(from) : null;
-        const toRelation = to ? metadataRelationFromObject(to) : null;
+        const fromRelation = from ? metadataObjectToAllowedSqlRelation(from) : null;
+        const toRelation = to ? metadataObjectToAllowedSqlRelation(to) : null;
         if (fromRelation && toRelation)
-            addRelation({ ...fromRelation, columns: toRelation.columns, source: 'dbt mapped warehouse table' });
+            addRelation({ ...fromRelation, columns: toRelation.columns, columnCompleteness: toRelation.columnCompleteness, source: 'dbt mapped warehouse table' });
     }
+    applyLineageColumnAliases(byRelation, objectsByKey, edges);
     return {
         relations: coalesceRelationAliases(Array.from(byRelation.values()))
             .sort((a, b) => a.relation.localeCompare(b.relation)),
@@ -2358,6 +3127,79 @@ function buildAllowedSqlContext(objects, edges) {
         })),
     };
 }
+function applyLineageColumnAliases(byRelation, objectsByKey, edges) {
+    const aliasesByRelationAndColumn = new Map();
+    for (const edge of edges) {
+        if (edge.edgeType !== 'derives_from')
+            continue;
+        const from = objectsByKey.get(edge.fromKey);
+        const to = objectsByKey.get(edge.toKey);
+        if (!from || !to)
+            continue;
+        const targetRelation = metadataObjectToAllowedSqlRelation(to);
+        if (!targetRelation)
+            continue;
+        const alias = semanticAliasFromLineageOutput(from);
+        if (!alias || namesEqualForCatalog(alias, to.name))
+            continue;
+        const relationKey = normalizeRelationKey(targetRelation.relation);
+        const columnKey = normalizeColumnKeyForCatalog(to.name);
+        if (!relationKey || !columnKey)
+            continue;
+        const mapKey = `${relationKey}\u0000${columnKey}`;
+        const existing = aliasesByRelationAndColumn.get(mapKey) ?? new Set();
+        existing.add(alias);
+        aliasesByRelationAndColumn.set(mapKey, existing);
+    }
+    if (aliasesByRelationAndColumn.size === 0)
+        return;
+    for (const [relationKey, relation] of byRelation) {
+        const columns = relation.columns.map((column) => {
+            const aliases = aliasesByRelationAndColumn.get(`${relationKey}\u0000${normalizeColumnKeyForCatalog(column.name)}`);
+            if (!aliases?.size)
+                return column;
+            const aliasText = Array.from(aliases).sort().slice(0, 8).join(', ');
+            const suffix = `Governed aliases from lineage: ${aliasText}.`;
+            const description = column.description
+                ? column.description.includes(suffix)
+                    ? column.description
+                    : `${column.description} ${suffix}`
+                : suffix;
+            return { ...column, description };
+        });
+        byRelation.set(relationKey, { ...relation, columns });
+    }
+}
+function semanticAliasFromLineageOutput(object) {
+    const candidates = [
+        typeof object.payload?.output === 'string' ? object.payload.output : undefined,
+        object.name,
+        object.fullName?.split('.').at(-1),
+    ];
+    for (const candidate of candidates) {
+        const alias = normalizeLineageAlias(candidate);
+        if (alias)
+            return alias;
+    }
+    return undefined;
+}
+function normalizeLineageAlias(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.replace(/["`]/g, '').replace(/\s+/g, ' ').trim();
+    if (!normalized || normalized === '*' || normalized === '?')
+        return undefined;
+    if (normalized.length > 64)
+        return undefined;
+    return normalized;
+}
+function normalizeColumnKeyForCatalog(value) {
+    return value.replace(/["`]/g, '').trim().toLowerCase();
+}
+function namesEqualForCatalog(left, right) {
+    return normalizeColumnKeyForCatalog(left).replace(/[_\s]+/g, '') ===
+        normalizeColumnKeyForCatalog(right).replace(/[_\s]+/g, '');
+}
 // Pull the first natural-language example question off a block payload so the
 // certified block can serve as a question→SQL few-shot exemplar.
 function firstExampleQuestion(examples) {
@@ -2374,12 +3216,66 @@ function firstExampleQuestion(examples) {
     }
     return undefined;
 }
-function buildSelectedJoinPaths(allowedSqlContext) {
+function buildSelectedJoinPaths(allowedSqlContext, edges) {
     const relations = allowedSqlContext.relations
         .filter((relation) => relation.columns.some((column) => isJoinKeyColumnForCatalog(column.name)))
         .slice(0, 16);
     const joins = [];
     const seen = new Set();
+    const lookup = buildSelectedRelationLookup(relations);
+    const pushJoin = (join) => {
+        const key = catalogJoinDedupeKey(join.leftRelation, join.leftColumn, join.rightRelation, join.rightColumn);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        joins.push(join);
+    };
+    for (const edge of edges) {
+        if (edge.edgeType !== 'depends_on')
+            continue;
+        const left = lookupRelationForCatalogEdge(edge.fromKey, lookup);
+        const right = lookupRelationForCatalogEdge(edge.toKey, lookup);
+        if (!left || !right || normalizeRelationKey(left.relation) === normalizeRelationKey(right.relation))
+            continue;
+        const join = pickCatalogJoinColumns(left, right);
+        if (!join)
+            continue;
+        pushJoin({
+            leftRelation: left.relation,
+            leftColumn: join.leftColumn,
+            rightRelation: right.relation,
+            rightColumn: join.rightColumn,
+            reason: `dbt lineage: ${left.name} depends_on ${right.name}; ${catalogJoinReason(join.leftColumn, join.rightColumn, join.confidence)}`,
+            confidence: Math.max(join.confidence, 0.98),
+            source: 'dbt_lineage',
+        });
+    }
+    // DataLex modeled relationships: grain-safe joins on the declared canonical
+    // columns (verified to exist on both relations), ranked above name heuristics.
+    const datalexLookup = buildSelectedRelationLookup(allowedSqlContext.relations);
+    for (const edge of edges) {
+        if (edge.edgeType !== 'datalex_join')
+            continue;
+        const left = lookupRelationForCatalogEdge(edge.fromKey, datalexLookup);
+        const right = lookupRelationForCatalogEdge(edge.toKey, datalexLookup);
+        if (!left || !right || normalizeRelationKey(left.relation) === normalizeRelationKey(right.relation))
+            continue;
+        const payload = (edge.payload ?? {});
+        const guessed = pickCatalogJoinColumns(left, right);
+        const leftColumn = relationHasColumn(left, payload.fromColumn) ? payload.fromColumn : guessed?.leftColumn;
+        const rightColumn = relationHasColumn(right, payload.toColumn) ? payload.toColumn : guessed?.rightColumn;
+        if (!leftColumn || !rightColumn)
+            continue;
+        pushJoin({
+            leftRelation: left.relation,
+            leftColumn,
+            rightRelation: right.relation,
+            rightColumn,
+            reason: `DataLex relationship${payload.name ? ` ${payload.name}` : ''}${payload.cardinality ? ` (${payload.cardinality})` : ''}`,
+            confidence: edge.confidence ?? 0.9,
+            source: 'datalex',
+        });
+    }
     for (let leftIndex = 0; leftIndex < relations.length; leftIndex += 1) {
         for (let rightIndex = leftIndex + 1; rightIndex < relations.length; rightIndex += 1) {
             const left = relations[leftIndex];
@@ -2387,29 +3283,122 @@ function buildSelectedJoinPaths(allowedSqlContext) {
             const join = pickCatalogJoinColumns(left, right);
             if (!join)
                 continue;
-            const key = [
-                normalizeRelationKey(left.relation),
-                join.leftColumn.toLowerCase(),
-                normalizeRelationKey(right.relation),
-                join.rightColumn.toLowerCase(),
-            ].join('|');
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            joins.push({
-                leftRelation: left.relation,
-                leftColumn: join.leftColumn,
-                rightRelation: right.relation,
-                rightColumn: join.rightColumn,
+            const oriented = orientCatalogJoinPath(left, right, join);
+            pushJoin({
+                leftRelation: oriented.leftRelation.relation,
+                leftColumn: oriented.leftColumn,
+                rightRelation: oriented.rightRelation.relation,
+                rightColumn: oriented.rightColumn,
                 reason: catalogJoinReason(join.leftColumn, join.rightColumn, join.confidence),
                 confidence: join.confidence,
+                source: 'metadata_guess',
             });
         }
     }
     return joins
-        .sort((a, b) => b.confidence - a.confidence || a.leftRelation.localeCompare(b.leftRelation))
+        .sort((a, b) => joinSourceRank(a.source) - joinSourceRank(b.source) || b.confidence - a.confidence || a.leftRelation.localeCompare(b.leftRelation))
         .slice(0, 12);
 }
+function buildSelectedRelationLookup(relations) {
+    const byObjectKey = new Map();
+    const byLookupKey = new Map();
+    const addLookup = (key, relation) => {
+        const normalized = normalizeRelationKey(key ?? '');
+        if (!normalized)
+            return;
+        const existing = byLookupKey.get(normalized) ?? [];
+        if (!existing.some((candidate) => normalizeRelationKey(candidate.relation) === normalizeRelationKey(relation.relation))) {
+            existing.push(relation);
+        }
+        byLookupKey.set(normalized, existing);
+    };
+    for (const relation of relations) {
+        if (relation.objectKey)
+            byObjectKey.set(relation.objectKey, relation);
+        addLookup(relation.relation, relation);
+        addLookup(relation.name, relation);
+        addLookup(relationTailKey(relation.relation), relation);
+    }
+    return { byObjectKey, byLookupKey };
+}
+function lookupRelationForCatalogEdge(edgeKey, lookup) {
+    const exact = lookup.byObjectKey.get(edgeKey);
+    if (exact)
+        return exact;
+    const tail = edgeKey.split(':').at(-1);
+    const candidates = [
+        edgeKey,
+        tail,
+        tail ? relationTailKey(tail) : undefined,
+    ];
+    for (const candidate of candidates) {
+        const normalized = normalizeRelationKey(candidate ?? '');
+        if (!normalized)
+            continue;
+        const matches = lookup.byLookupKey.get(normalized);
+        if (matches?.length === 1)
+            return matches[0];
+    }
+    return undefined;
+}
+function catalogJoinDedupeKey(leftRelation, leftColumn, rightRelation, rightColumn) {
+    return [
+        `${normalizeRelationKey(leftRelation)}.${normalizeColumnKeyForCatalog(leftColumn)}`,
+        `${normalizeRelationKey(rightRelation)}.${normalizeColumnKeyForCatalog(rightColumn)}`,
+    ].sort().join('|');
+}
+/** Map a DataLex physical binding to the metadata object key of its relation. */
+function objectKeyForDataLexBinding(binding) {
+    switch (binding.kind) {
+        case 'dbt_model': return `dbt:model:${binding.ref}`;
+        case 'dbt_source': return `dbt:source:${binding.ref}`;
+        default: return `warehouse:table:${binding.ref}`;
+    }
+}
+function relationHasColumn(relation, column) {
+    if (!column)
+        return false;
+    const target = normalizeColumnKeyForCatalog(column);
+    return relation.columns.some((entry) => normalizeColumnKeyForCatalog(entry.name) === target);
+}
+function joinSourceRank(source) {
+    switch (source) {
+        case 'dbt_lineage': return 0;
+        case 'datalex': return 1;
+        case 'kg_path': return 2;
+        case 'metadata_guess': return 3;
+        default: return 4;
+    }
+}
+function orientCatalogJoinPath(left, right, join) {
+    if (catalogRelationFactScore(right) > catalogRelationFactScore(left)) {
+        return {
+            leftRelation: right,
+            leftColumn: join.rightColumn,
+            rightRelation: left,
+            rightColumn: join.leftColumn,
+        };
+    }
+    return {
+        leftRelation: left,
+        leftColumn: join.leftColumn,
+        rightRelation: right,
+        rightColumn: join.rightColumn,
+    };
+}
+function catalogRelationFactScore(relation) {
+    const text = normalizeRelationKey([relation.name, relation.relation].join(' ')).replace(/[._-]+/g, ' ');
+    let score = 0;
+    if (/\b(fct|fact)\b/i.test(text))
+        score += 20;
+    if (/\b(order items?|orders?|events?|transactions?|performance|activity|usage|revenue|sales|payments?|line items?|stats?)\b/i.test(text))
+        score += 8;
+    if (/\b(dim|dimension)\b/i.test(text))
+        score -= 18;
+    if (/\b(customers?|products?|players?|accounts?|users?|segments?|regions?)\b/i.test(text))
+        score -= 4;
+    return score;
+}
 function pickCatalogJoinColumns(left, right) {
     const candidates = [];
     const leftColumns = left.columns.filter((column) => isJoinKeyColumnForCatalog(column.name)).slice(0, 32);
@@ -2515,7 +3504,8 @@ function coalesceRelationAliases(relations) {
             ...target,
             objectKey: target.objectKey ?? relation.objectKey,
             source: mergeRelationSources(target.source, relation.source),
-            columns: dedupeRuntimeColumns([...target.columns, ...relation.columns]).slice(0, 120),
+            columnCompleteness: mergeRelationCompletenessForCatalog(target, relation),
+            columns: mergeRelationColumns(target, relation).slice(0, 120),
         });
         skipped.add(relationKey);
     }
@@ -2523,6 +3513,31 @@ function coalesceRelationAliases(relations) {
         .filter(([key]) => !skipped.has(key))
         .map(([, relation]) => relation);
 }
+function mergeRelationColumns(existing, incoming) {
+    const existingIsSourceShape = relationSourceIncludes(existing.source, 'certified source SQL shape');
+    const incomingIsSourceShape = relationSourceIncludes(incoming.source, 'certified source SQL shape');
+    if (existingIsSourceShape && !incomingIsSourceShape) {
+        return dedupeRuntimeColumns([...incoming.columns, ...existing.columns]);
+    }
+    if (!existingIsSourceShape && incomingIsSourceShape) {
+        return dedupeRuntimeColumns([...existing.columns, ...incoming.columns]);
+    }
+    return dedupeRuntimeColumns([...existing.columns, ...incoming.columns]);
+}
+function mergeRelationCompletenessForCatalog(existing, incoming) {
+    if (relationCompletenessValue(existing) === 'complete' || relationCompletenessValue(incoming) === 'complete') {
+        return 'complete';
+    }
+    return 'partial';
+}
+function relationCompletenessValue(relation) {
+    if (relation.columnCompleteness)
+        return relation.columnCompleteness;
+    return relation.columns.length === 0 ? 'partial' : 'complete';
+}
+function relationSourceIncludes(source, value) {
+    return Boolean(source && source.split(/\s+\+\s+/).some((part) => part.trim() === value));
+}
 function relationTailKey(relation) {
     const parts = normalizeRelationKey(relation).split('.').filter(Boolean);
     return parts.at(-1) ?? '';
@@ -2547,8 +3562,26 @@ function warehouseTableHasTrustedReference(object, objectsByKey) {
         return block ? isCertifiedMetadataObject(block) : false;
     });
 }
-function metadataRelationFromObject(object) {
-    if (object.objectType === 'dbt_column' || object.objectType === 'runtime_column') {
+export function metadataObjectToAllowedSqlRelation(object) {
+    if (object.objectType === 'runtime_value') {
+        const relation = metadataPayloadString(object, 'relation');
+        const columnName = metadataPayloadString(object, 'column');
+        if (!relation || !columnName)
+            return null;
+        return {
+            relation,
+            name: relation.split('.').at(-1) ?? relation,
+            objectKey: object.objectKey,
+            source: 'runtime value index',
+            columnCompleteness: 'partial',
+            columns: [{
+                    name: columnName,
+                    type: metadataPayloadString(object, 'type'),
+                    sampleValues: metadataStringArray(object.payload?.sampleValues),
+                }],
+        };
+    }
+    if (object.objectType === 'dbt_column' || object.objectType === 'runtime_column' || object.objectType === 'warehouse_column') {
         const relation = metadataPayloadString(object, 'relation');
         if (!relation)
             return null;
@@ -2556,7 +3589,12 @@ function metadataRelationFromObject(object) {
             relation,
             name: relation.split('.').at(-1) ?? relation,
             objectKey: object.objectKey,
-            source: object.objectType === 'runtime_column' ? 'runtime schema snapshot' : 'dbt manifest',
+            source: object.objectType === 'runtime_column'
+                ? 'runtime schema snapshot'
+                : object.objectType === 'warehouse_column'
+                    ? 'DQL block column lineage'
+                    : 'dbt manifest',
+            columnCompleteness: 'partial',
             columns: [{
                     name: object.name,
                     type: metadataPayloadString(object, 'type') ?? metadataPayloadString(object, 'data_type'),
@@ -2573,9 +3611,21 @@ function metadataRelationFromObject(object) {
         name: relation.split('.').at(-1) ?? object.name,
         objectKey: object.objectKey,
         source: object.objectType === 'runtime_table' ? 'runtime schema snapshot' : object.sourceSystem ?? 'local metadata catalog',
+        columnCompleteness: relationColumnCompletenessFromObject(object),
         columns: metadataRuntimeColumns(object.payload?.columns),
     };
 }
+function relationColumnCompletenessFromObject(object) {
+    if (object.objectType === 'runtime_table')
+        return 'complete';
+    if (object.payload?.columnCompleteness === 'complete' || object.payload?.catalogColumnCompleteness === 'complete')
+        return 'complete';
+    if (object.payload?.columnCompleteness === 'partial' || object.payload?.catalogColumnCompleteness === 'partial')
+        return 'partial';
+    if (object.objectType === 'warehouse_table')
+        return 'partial';
+    return 'partial';
+}
 function runtimeSchemaObjects(snapshot) {
     const capturedAt = snapshot.capturedAt ?? new Date().toISOString();
     return normalizeRuntimeSchemaTables(snapshot.tables).flatMap((table) => {
@@ -2592,6 +3642,7 @@ function runtimeSchemaObjects(snapshot) {
             payload: compactObject({
                 relation,
                 schema: table.schema,
+                columnCompleteness: 'complete',
                 columns: table.columns,
             }),
             updatedAt: capturedAt,
@@ -2607,6 +3658,7 @@ function runtimeSchemaObjects(snapshot) {
             payload: compactObject({
                 relation,
                 type: column.type,
+                columnCompleteness: 'partial',
                 sampleValues: column.sampleValues,
             }),
             updatedAt: capturedAt,
@@ -2614,6 +3666,30 @@ function runtimeSchemaObjects(snapshot) {
         return [tableObject, ...columns];
     });
 }
+function runtimeValueMatchObjects(matches) {
+    return matches.map((match) => ({
+        objectKey: match.valueKey,
+        objectType: 'runtime_value',
+        name: `${match.columnName} = ${match.value}`,
+        fullName: `${match.relation}.${match.columnName}:${match.value}`,
+        description: `Observed value "${match.value}" in ${match.relation}.${match.columnName}.`,
+        status: 'runtime_observed',
+        sourceSystem: match.source ?? 'runtime value index',
+        score: match.score,
+        payload: compactObject({
+            relation: match.relation,
+            schema: match.schema,
+            table: match.tableName,
+            column: match.columnName,
+            type: match.columnType,
+            value: match.value,
+            normalizedValue: match.normalizedValue,
+            sampleValues: [match.value],
+            capturedAt: match.capturedAt,
+        }),
+        updatedAt: match.capturedAt,
+    }));
+}
 function selectedContextObjects(value) {
     const root = value && typeof value === 'object' ? value : null;
     if (!root)
@@ -2643,7 +3719,13 @@ function normalizeFollowUpContext(value) {
     if (!value || typeof value !== 'object')
         return null;
     const record = value;
-    const kind = record.kind === 'drilldown' ? 'drilldown' : record.kind === 'generic' ? 'generic' : null;
+    const kind = record.kind === 'drilldown'
+        ? 'drilldown'
+        : record.kind === 'generic'
+            ? 'generic'
+            : record.kind === 'contextual'
+                ? 'contextual'
+                : null;
     if (!kind)
         return null;
     return {
@@ -2653,8 +3735,77 @@ function normalizeFollowUpContext(value) {
         sourceAnswer: stringValue(record.sourceAnswer),
         filters: metadataStringArray(record.filters),
         dimensions: metadataStringArray(record.dimensions),
+        priorResultColumns: metadataStringArray(record.priorResultColumns),
+        priorResultValues: metadataStringRecordArray(record.priorResultValues),
+        priorResultRef: normalizePriorResultRef(record.priorResultRef),
+        priorDqlArtifact: normalizePriorDqlArtifact(record.priorDqlArtifact),
+        priorLimit: typeof record.priorLimit === 'number' ? record.priorLimit : undefined,
+        priorMeasures: metadataStringArray(record.priorMeasures),
+    };
+}
+function normalizePriorResultRef(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const id = stringValue(record.id);
+    const columns = metadataStringArray(record.columns) ?? [];
+    if (!id || columns.length === 0)
+        return undefined;
+    const rowCount = typeof record.rowCount === 'number' && Number.isFinite(record.rowCount)
+        ? record.rowCount
+        : undefined;
+    const sourceSql = stringValue(record.sourceSql);
+    return {
+        id,
+        question: stringValue(record.question),
+        columns: columns.slice(0, 32),
+        rowCount,
+        sourceSql: sourceSql ? sourceSql.slice(0, 1200) : undefined,
     };
 }
+function normalizePriorDqlArtifact(value) {
+    const artifact = normalizeDqlArtifactReference(value);
+    if (!artifact)
+        return undefined;
+    return {
+        ...artifact,
+        source: artifact.source.slice(0, 3000),
+        metrics: artifact.metrics?.slice(0, 32),
+        dimensions: artifact.dimensions?.slice(0, 32),
+        filters: artifact.filters
+            ?.filter((filter) => filter.values.length > 0)
+            .slice(0, 12)
+            .map((filter) => ({ ...filter, values: filter.values.slice(0, 12) })),
+        orderBy: artifact.orderBy?.slice(0, 12),
+    };
+}
+/**
+ * Deterministic route-commitment gate: true only when the new plan differs from
+ * the prior one in FILTERS / TOP-N / TIMEFRAME alone. Any change to measures,
+ * dimensions, grain, required outputs, or mode disqualifies reuse — those change
+ * which artifacts/relations can answer, so the full pipeline must re-run.
+ */
+export function isFilterOnlyRefinement(prior, next) {
+    if (prior.mode !== next.mode)
+        return false;
+    const priorShape = prior.requestedShape;
+    const nextShape = next.requestedShape;
+    return setEqual(priorShape.measures, nextShape.measures)
+        && setEqual(priorShape.dimensions, nextShape.dimensions)
+        && setEqual(priorShape.requiredOutputs, nextShape.requiredOutputs)
+        && (priorShape.grain ?? '') === (nextShape.grain ?? '')
+        && setEqual(prior.entities.map((entity) => entity.text.toLowerCase()), next.entities.map((entity) => entity.text.toLowerCase()));
+}
+function setEqual(a, b) {
+    const setA = new Set(a.map((value) => value.toLowerCase()));
+    const setB = new Set(b.map((value) => value.toLowerCase()));
+    if (setA.size !== setB.size)
+        return false;
+    for (const value of setA)
+        if (!setB.has(value))
+            return false;
+    return true;
+}
 function followUpSourceObjectKeys(followUp) {
     if (!followUp?.sourceBlockName)
         return [];
@@ -2670,11 +3821,22 @@ function followUpContextObjects(followUp) {
         followUp.sourceAnswer ?? '',
         ...(followUp.filters ?? []),
         ...(followUp.dimensions ?? []),
+        ...(followUp.priorResultColumns ?? []),
+        followUp.priorResultRef?.id ? `result:${followUp.priorResultRef.id}` : '',
+        followUp.priorResultRef?.question ?? '',
+        ...(followUp.priorResultRef?.columns ?? []),
+        followUp.priorResultRef?.sourceSql ? followUp.priorResultRef.sourceSql.slice(0, 600) : '',
+        ...dqlArtifactSearchTerms(followUp.priorDqlArtifact, { includeSource: true }),
+        ...Object.entries(followUp.priorResultValues ?? {}).flatMap(([key, values]) => [key, ...values]),
     ].join(' ');
     return [{
             objectKey: `selected:followup:${sha256(stableStringify(followUp)).slice(0, 16)}`,
             objectType: 'selected_context',
-            name: followUp.kind === 'drilldown' ? 'Follow-up drilldown request' : 'Follow-up request',
+            name: followUp.kind === 'drilldown'
+                ? 'Follow-up drilldown request'
+                : followUp.kind === 'contextual'
+                    ? 'Conversation context (advisory)'
+                    : 'Follow-up request',
             description: text.trim() || undefined,
             status: 'transient_context',
             sourceSystem: 'agent follow-up context',
@@ -2685,20 +3847,112 @@ function followUpContextObjects(followUp) {
                 sourceAnswer: followUp.sourceAnswer,
                 filters: followUp.filters,
                 dimensions: followUp.dimensions,
+                priorResultColumns: followUp.priorResultColumns,
+                priorResultValues: followUp.priorResultValues,
+                priorResultRef: followUp.priorResultRef,
+                priorDqlArtifact: followUp.priorDqlArtifact,
+                priorLimit: followUp.priorLimit,
+                priorMeasures: followUp.priorMeasures,
             }),
         }];
 }
+function metadataValueSearchTerms(question, questionPlan, followUp) {
+    const terms = [
+        ...questionPlan.entities.map((entity) => entity.text),
+        ...questionPlan.filterTerms,
+        ...(followUp?.filters ?? []),
+        ...Object.values(followUp?.priorResultValues ?? {}).flat(),
+    ];
+    for (const match of question.matchAll(/["']([^"']{2,120})["']/g))
+        terms.push(match[1]);
+    for (const match of question.matchAll(/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/g))
+        terms.push(match[0]);
+    for (const match of question.matchAll(/\b[A-Z][a-z0-9]+(?:\s+[A-Z][a-z0-9]+){1,4}\b/g))
+        terms.push(match[0]);
+    for (const match of question.matchAll(/\b(?:for|named|called|only|where|customer|user|account|product|region|segment|category|status)\s+([A-Za-z0-9@._-]+(?:\s+[A-Za-z0-9@._-]+){0,4})/gi)) {
+        terms.push(match[1]);
+    }
+    return uniqueStrings(terms
+        .map(cleanMetadataValueSearchTerm)
+        .filter((term) => term.length >= 2 && !METADATA_VALUE_STOP_TERMS.has(term.toLowerCase()))).slice(0, 10);
+}
+function cleanMetadataValueSearchTerm(term) {
+    return term
+        .replace(/[?.,;:]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^(?:account|category|customer|member|named|called|only|product|region|segment|sku|status|subscriber|user|where)\s+/i, '')
+        .replace(/\s+\b(?:last|next|this)\b.*$/i, '')
+        .replace(/\s+\b(?:daily|weekly|monthly|quarterly|yearly)\b.*$/i, '')
+        .trim();
+}
+const METADATA_VALUE_STOP_TERMS = new Set([
+    'account',
+    'category',
+    'customer',
+    'last month',
+    'last quarter',
+    'last week',
+    'last year',
+    'member',
+    'product',
+    'region',
+    'segment',
+    'sku',
+    'status',
+    'this month',
+    'this quarter',
+    'this week',
+    'this year',
+    'user',
+]);
 function buildFollowUpSearchQuery(question, followUp) {
     if (!followUp)
         return question;
+    // Contextual carry is advisory: enrich retrieval softly (prior question, columns,
+    // measures) but never with concrete dimension VALUES or the block name — those pull
+    // ranking hard toward the old topic when the user may be switching subjects. The
+    // question-plan's own raw queries still run alongside this one either way.
+    if (followUp.kind === 'contextual') {
+        return [
+            question,
+            followUp.sourceQuestion ?? '',
+            ...(followUp.priorResultColumns ?? []),
+            followUp.priorResultRef?.question ?? '',
+            ...(followUp.priorResultRef?.columns ?? []),
+            ...(followUp.priorMeasures ?? []),
+            ...dqlArtifactSearchTerms(followUp.priorDqlArtifact, { includeSource: false }),
+        ].filter(Boolean).join(' ');
+    }
     return [
         question,
         followUp.sourceBlockName ?? '',
         followUp.sourceQuestion ?? '',
         ...(followUp.filters ?? []),
         ...(followUp.dimensions ?? []),
+        ...(followUp.priorResultColumns ?? []),
+        followUp.priorResultRef?.question ?? '',
+        ...(followUp.priorResultRef?.columns ?? []),
+        followUp.priorResultRef?.sourceSql ? followUp.priorResultRef.sourceSql.slice(0, 600) : '',
+        ...dqlArtifactSearchTerms(followUp.priorDqlArtifact, { includeSource: true }),
+        ...Object.entries(followUp.priorResultValues ?? {}).flatMap(([key, values]) => [key, ...values]),
     ].filter(Boolean).join(' ');
 }
+function dqlArtifactSearchTerms(artifact, options) {
+    if (!artifact)
+        return [];
+    return [
+        artifact.name ?? '',
+        artifact.sourcePath ?? '',
+        ...(artifact.metrics ?? []),
+        ...(artifact.dimensions ?? []),
+        ...(artifact.filters ?? []).flatMap((filter) => [filter.dimension, filter.operator, ...filter.values]),
+        artifact.timeDimension ? `${artifact.timeDimension.name} ${artifact.timeDimension.granularity}` : '',
+        ...(artifact.orderBy ?? []).map((order) => `${order.name} ${order.direction}`),
+        typeof artifact.limit === 'number' ? `limit ${artifact.limit}` : '',
+        options.includeSource ? artifact.source.slice(0, 900) : '',
+    ].filter(Boolean);
+}
 function uniqueMetadataSearchQueries(values) {
     const seen = new Set();
     const out = [];
@@ -2797,6 +4051,29 @@ function metadataStringArray(value) {
         return [];
     return value.filter((item) => typeof item === 'string' && item.trim().length > 0).map((item) => item.trim());
 }
+function uniqueStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const normalized = value.toLowerCase();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(value);
+    }
+    return out;
+}
+function metadataStringRecordArray(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const values = metadataStringArray(raw).slice(0, 24);
+        if (key.trim() && values.length > 0)
+            out[key.trim()] = values;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function metadataPayloadString(object, key) {
     return stringValue(object.payload?.[key]);
 }
@@ -2967,6 +4244,25 @@ function rowToQueryRun(row) {
         createdAt: row.created_at,
     };
 }
+function rowToRuntimeValueMatch(row, terms) {
+    const normalized = row.normalized_value;
+    const exactBoost = terms.some((term) => term === normalized) ? 1 : 0;
+    const containsBoost = terms.some((term) => normalized.includes(term) || term.includes(normalized)) ? 0.5 : 0;
+    const rankScore = row.rank ? 1 / (1 + Math.max(0, row.rank)) : 1;
+    return {
+        valueKey: row.value_key,
+        relation: row.relation,
+        schema: row.schema_name ?? undefined,
+        tableName: row.table_name ?? undefined,
+        columnName: row.column_name,
+        columnType: row.column_type ?? undefined,
+        value: row.value,
+        normalizedValue: row.normalized_value,
+        source: row.source ?? undefined,
+        capturedAt: row.captured_at,
+        score: Number((rankScore + exactBoost + containsBoost).toFixed(3)),
+    };
+}
 function safeJson(raw, fallback) {
     if (!raw)
         return fallback;
@@ -2994,22 +4290,61 @@ function rankMetadataObjects(args) {
     })
         .sort((a, b) => b.score - a.score || objectPriority(a.row) - objectPriority(b.row) || a.row.name.localeCompare(b.row.name))
         .map((item, index) => ({ ...item, rank: index + 1 }));
-    const cutoff = ranked[Math.max(0, args.limit - 1)];
+    const selectedRanked = selectRankedMetadataObjects(ranked, args.limit);
+    const selectedKeys = new Set(selectedRanked.map((item) => item.row.objectKey));
+    const rejectedRanked = ranked.filter((item) => !selectedKeys.has(item.row.objectKey));
+    const cutoff = selectedRanked.at(-1);
     return {
-        selected: ranked.slice(0, args.limit).map((item) => item.row),
+        selected: selectedRanked.map((item) => item.row),
         ranked,
-        rejected: ranked.slice(args.limit).slice(0, 24).map((item) => ({
+        rejected: rejectedRanked.slice(0, 24).map((item) => ({
             objectKey: item.row.objectKey,
             objectType: item.row.objectType,
             name: item.row.name,
             reason: cutoff
-                ? `Lower retrieval score than selected context window (cutoff ${cutoff.score.toFixed(1)}); ${item.reason}`
+                ? `Outside balanced context window (cutoff ${cutoff.score.toFixed(1)}); ${item.reason}`
                 : item.reason,
             score: item.score,
             rejectedRank: item.rank,
         })),
     };
 }
+function selectRankedMetadataObjects(ranked, limit) {
+    if (ranked.length <= limit)
+        return ranked;
+    const columnCount = ranked.filter((item) => COLUMN_OBJECT_TYPES.has(item.row.objectType)).length;
+    const nonColumnCount = ranked.length - columnCount;
+    if (columnCount === 0 || nonColumnCount === 0)
+        return ranked.slice(0, limit);
+    const columnCap = Math.max(4, Math.floor(limit * 0.35));
+    const selected = [];
+    const deferredColumns = [];
+    let selectedColumns = 0;
+    for (const item of ranked) {
+        if (selected.length >= limit)
+            break;
+        if (COLUMN_OBJECT_TYPES.has(item.row.objectType)) {
+            if (selectedColumns >= columnCap) {
+                deferredColumns.push(item);
+                continue;
+            }
+            selectedColumns += 1;
+        }
+        selected.push(item);
+    }
+    if (selected.length < limit) {
+        const selectedKeys = new Set(selected.map((item) => item.row.objectKey));
+        for (const item of [...deferredColumns, ...ranked]) {
+            if (selected.length >= limit)
+                break;
+            if (selectedKeys.has(item.row.objectKey))
+                continue;
+            selected.push(item);
+            selectedKeys.add(item.row.objectKey);
+        }
+    }
+    return selected.sort((a, b) => a.rank - b.rank);
+}
 function scoreMetadataObject(row, terms) {
     let score = row.score ? row.score * 10 : 0;
     score += Math.max(0, 44 - objectPriority(row) * 2);
@@ -3023,6 +4358,8 @@ function scoreMetadataObject(row, terms) {
         score -= 16;
     if (row.objectType === 'semantic_metric')
         score += 10;
+    if (row.objectType === 'runtime_value')
+        score += 14;
     if (row.objectType === 'dbt_model' || row.objectType === 'dbt_column')
         score += 4;
     score += scoreText([
@@ -3045,6 +4382,8 @@ function priorityTier(row) {
         return 'certified_block';
     if (row.objectType === 'semantic_metric')
         return 'semantic_metric';
+    if (row.objectType === 'runtime_value')
+        return 'value_match';
     if (row.objectType === 'dql_term' || row.objectType === 'business_view')
         return 'business_context';
     if (row.objectType.startsWith('dbt_') || row.objectType === 'warehouse_table')
@@ -3066,11 +4405,15 @@ function selectionReason(row, score, plannerReasons = []) {
 function reasonForObject(row) {
     if (row.objectType === 'dql_block' && row.status === 'certified')
         return 'Certified reusable answer candidate';
+    if (row.objectType === 'dql_block_output')
+        return 'Certified block output column lineage';
     if (row.objectType === 'semantic_metric')
         return 'Semantic metric matched the question';
+    if (row.objectType === 'runtime_value')
+        return 'Observed runtime value matched the question literal';
     if (row.objectType === 'dql_term' || row.objectType === 'business_view')
         return 'DQL business context';
-    if (row.objectType.startsWith('dbt_') || row.objectType === 'warehouse_table')
+    if (row.objectType.startsWith('dbt_') || row.objectType === 'warehouse_table' || row.objectType === 'warehouse_column')
         return 'dbt or warehouse metadata supplies physical context';
     if (row.objectType === 'app' || row.objectType === 'dashboard')
         return 'Published consumption context';
@@ -3084,6 +4427,13 @@ function mergeObjects(rows) {
     }
     return Array.from(byKey.values());
 }
+function mergeMetadataEdges(rows) {
+    const byKey = new Map();
+    for (const row of rows) {
+        putEdge(byKey, row);
+    }
+    return Array.from(byKey.values());
+}
 function deriveTrust(objects) {
     if (objects.length === 0)
         return 'unknown';
@@ -3096,6 +4446,26 @@ function deriveTrust(objects) {
         return 'draft';
     return statuses.some((status) => status === 'certified') ? 'mixed' : 'unknown';
 }
+function withMetadataTrustLabelInfo(decision) {
+    return {
+        ...decision,
+        trustLabelInfo: metadataTrustLabelInfo(decision.trustLabel),
+    };
+}
+function metadataTrustLabelInfo(label) {
+    switch (label) {
+        case 'certified':
+            return composeEffectiveTrust({ id: 'certified' });
+        case 'conflict':
+            return composeEffectiveTrust({ id: 'conflict' });
+        case 'draft':
+            return composeEffectiveTrust({ id: 'ai_generated' });
+        case 'mixed':
+            return composeEffectiveTrust({ id: 'ai_generated', existingQualifier: 'mixed context' });
+        case 'unknown':
+            return composeEffectiveTrust({ id: 'insufficient_context' });
+    }
+}
 function buildCitations(objects, edges) {
     const citations = objects.slice(0, 24).map((row) => ({
         objectKey: row.objectKey,
@@ -3205,7 +4575,7 @@ function isGovernedCandidate(row) {
  * route scoped to questions the conflicting pair actually answers — a conflict
  * elsewhere in the project never hijacks an unrelated question.
  */
-function pickRouteConflict(compileConflicts, rankedObjects, fallbackObjects) {
+function pickRouteConflict(compileConflicts, rankedObjects, fallbackObjects, question) {
     if (compileConflicts.length === 0)
         return undefined;
     // Names of the top candidate objects for this question (bounded — only the
@@ -3220,6 +4590,8 @@ function pickRouteConflict(compileConflicts, rankedObjects, fallbackObjects) {
             topNames.add(norm);
     }
     for (const conflict of compileConflicts) {
+        if (!conflictMatchesQuestion(conflict, question))
+            continue;
         const sideNames = conflict.sides.map((side) => normalizeConflictName(side.name)).filter(Boolean);
         if (sideNames.length < 2)
             continue;
@@ -3243,6 +4615,14 @@ function pickRouteConflict(compileConflicts, rankedObjects, fallbackObjects) {
     }
     return undefined;
 }
+function conflictMatchesQuestion(conflict, question) {
+    const questionTokens = new Set(tokenize(question.replace(/_/g, ' ')));
+    const conceptTokens = tokenize(conflict.concept.replace(/_/g, ' '));
+    if (conceptTokens.length > 0 && conceptTokens.every((token) => questionTokens.has(token)))
+        return true;
+    const sideHits = conflict.sides.filter((side) => tokenize(side.name).some((token) => questionTokens.has(token))).length;
+    return sideHits >= 2;
+}
 function normalizeConflictName(value) {
     return (value ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
 }
@@ -3267,7 +4647,7 @@ function sanitizeFtsQuery(raw) {
         .map((term) => term.replace(/[^\p{L}\p{N}_]/gu, ''))
         .filter((term) => term.length > 1 && !STOP_WORDS.has(term.toLowerCase()))
         .slice(0, 48)
-        .map((term) => `"${term}"`)
+        .map((term) => `"${term}"*`)
         .join(' OR ');
 }
 //# sourceMappingURL=catalog.js.map