@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/metadata/catalog.js

@@ -1,3 +1,4 @@
+import { applyRerank } from '../agentic/rerank.js';
 /**
  * Project-local metadata catalog for OSS agentic analytics.
  *
@@ -27,6 +28,7 @@ import { projectEmbeddingProvider } from '../embeddings/project-embeddings.js';
 import { matchExampleParaphrase } from './example-match.js';
 import { loadSkills, selectRelevantSkills } from '../skills/loader.js';
 import { buildMeaningEvidencePackage, } from './meaning-evidence.js';
+import { fuseContextCandidates, retrieveContextLanes } from '../analytical-orchestration.js';
 import { hasGeneratedAppSourceOrigin, isExplicitlyReusableAppSource, } from '../app-source-policy.js';
 export { applyContextPackCompatibility, toAgentRetrievalEvidence } from './meaning-evidence.js';
 const require = createRequire(import.meta.url);
@@ -105,8 +107,20 @@ const DEFAULT_VECTOR_PROVIDER = new HashedTokenEmbeddingProvider();
 export function defaultMetadataPath(projectRoot) {
     return join(projectRoot, '.dql', 'cache', 'metadata.sqlite');
 }
-export function metadataSnapshotPath(projectRoot, fingerprint) {
-    return join(projectRoot, '.dql', 'cache', 'snapshots', `${METADATA_INDEX_VERSION}-${fingerprint}.sqlite`);
+/**
+ * Snapshots are immutable and addressed by content fingerprint, so
+ * `exportSnapshot` refuses to overwrite an existing file. The embedded VECTORS
+ * are part of what a snapshot contains but are NOT part of the content
+ * fingerprint, so two different encodings of identical content would otherwise
+ * collide on one path — and switching `ai.embeddings` would silently keep
+ * serving the hashed vectors forever. Qualify the filename with the provider so
+ * they are the distinct artifacts they actually are.
+ */
+export function metadataSnapshotPath(projectRoot, fingerprint, vectorProviderId) {
+    const suffix = vectorProviderId && !vectorProviderId.startsWith('hashed-token')
+        ? `-${vectorProviderId.replace(/[^a-z0-9]+/gi, '_').slice(0, 48)}`
+        : '';
+    return join(projectRoot, '.dql', 'cache', 'snapshots', `${METADATA_INDEX_VERSION}-${fingerprint}${suffix}.sqlite`);
 }
 function readActiveMetadataSnapshotPointer(projectRoot) {
     const pointerPath = join(projectRoot, '.dql', 'cache', 'active-snapshot.json');
@@ -143,7 +157,7 @@ export function currentMetadataFingerprint(projectRoot) {
     }
 }
 function activateMetadataSnapshot(projectRoot, fingerprint, catalog) {
-    const snapshotPath = metadataSnapshotPath(projectRoot, fingerprint);
+    const snapshotPath = metadataSnapshotPath(projectRoot, fingerprint, catalog.state('vector_provider') ?? undefined);
     catalog.exportSnapshot(snapshotPath);
     const cacheDir = join(projectRoot, '.dql', 'cache');
     const pointerPath = join(cacheDir, 'active-snapshot.json');
@@ -314,15 +328,22 @@ export async function awaitVectorIndexUpgrade(projectRoot) {
  * runs or if it fails. Best-effort by design: an unreachable Ollama must not
  * break indexing or answering.
  */
-export async function upgradeVectorIndexForProject(projectRoot, provider) {
+/** How long a cold re-embed may hold up indexing before we ship the hashed index. */
+const VECTOR_UPGRADE_BUDGET_MS = 8_000;
+/**
+ * Re-embed an ALREADY-OPEN catalog. Split out from `upgradeVectorIndexForProject`
+ * so `ensureMetadataCatalogFresh` can upgrade the same catalog handle it is about
+ * to export — the vectors have to be in place BEFORE `activateMetadataSnapshot`,
+ * because retrieval reads the exported snapshot, not this working database.
+ */
+async function upgradeVectorIndexOnCatalog(catalog, provider) {
     if (provider.id.startsWith('hashed-token')) {
         return { upgraded: false, providerId: provider.id, reason: 'project uses the offline hashed embedder' };
     }
-    const catalog = openMetadataCatalog(projectRoot);
+    if (catalog.state('vector_provider') === provider.id) {
+        return { upgraded: false, providerId: provider.id, reason: 'index already embedded with this provider' };
+    }
     try {
-        if (catalog.state('vector_provider') === provider.id) {
-            return { upgraded: false, providerId: provider.id, reason: 'index already embedded with this provider' };
-        }
         await catalog.rebuildVectorIndex(provider);
         return { upgraded: true, providerId: provider.id };
     }
@@ -333,6 +354,22 @@ export async function upgradeVectorIndexForProject(projectRoot, provider) {
             reason: error instanceof Error ? error.message : String(error),
         };
     }
+}
+export async function upgradeVectorIndexForProject(projectRoot, provider) {
+    const catalog = openMetadataCatalog(projectRoot);
+    try {
+        const result = await upgradeVectorIndexOnCatalog(catalog, provider);
+        // Re-export so the ACTIVE snapshot carries the new vectors. Without this the
+        // upgrade only ever touched the mutable working database, which the answer
+        // path never reads — so `POST /api/settings/embeddings/reindex` reported
+        // success while retrieval kept serving the hashed index.
+        if (result.upgraded) {
+            const fingerprint = catalog.state('fingerprint');
+            if (fingerprint)
+                activateMetadataSnapshot(projectRoot, fingerprint, catalog);
+        }
+        return result;
+    }
     finally {
         catalog.close();
     }
@@ -348,7 +385,30 @@ export async function ensureMetadataCatalogFresh(projectRoot, options = {}) {
     try {
         const existing = catalog.state('fingerprint');
         const compatibleIndex = catalog.state('index_version') === METADATA_INDEX_VERSION;
+        // The snapshot write embeds with the sync hashed provider (better-sqlite3
+        // transactions cannot await), so a configured Ollama/OpenAI embedder can only
+        // be applied afterwards — and it must land BEFORE the export, since retrieval
+        // reads the exported snapshot. `searchVectorObjects` returns ZERO candidates
+        // when the requested provider id does not match the indexed one, so skipping
+        // this makes configuring a real embedder strictly worse than not configuring
+        // one: an empty vector lane instead of a weak one.
+        const vectorProvider = options.embeddingProvider ?? projectEmbeddingProvider(projectRoot);
+        const upgradeVectors = async () => {
+            const upgrade = upgradeVectorIndexOnCatalog(catalog, vectorProvider);
+            pendingVectorUpgrades.set(projectRoot, upgrade.then(() => undefined, () => undefined));
+            // Never let a cold or unreachable embedder block indexing: the hashed index
+            // is already in place, so timing out simply ships it and the next refresh
+            // retries.
+            await Promise.race([
+                upgrade,
+                new Promise((resolve) => setTimeout(resolve, VECTOR_UPGRADE_BUDGET_MS)),
+            ]);
+        };
         if (!options.force && compatibleIndex && existing === snapshot.fingerprint) {
+            // The project content is unchanged but the CONFIGURED EMBEDDER may not be.
+            // Without this, switching `ai.embeddings` never takes effect until an
+            // unrelated dbt change happens to move the fingerprint.
+            await upgradeVectors();
             const snapshotPath = activateMetadataSnapshot(projectRoot, snapshot.fingerprint, catalog);
             return {
                 path: defaultMetadataPath(projectRoot),
@@ -369,6 +429,7 @@ export async function ensureMetadataCatalogFresh(projectRoot, options = {}) {
         else {
             catalog.rebuildIncremental(snapshot);
         }
+        await upgradeVectors();
         const snapshotPath = activateMetadataSnapshot(projectRoot, snapshot.fingerprint, catalog);
         return {
             path: defaultMetadataPath(projectRoot),
@@ -417,57 +478,148 @@ export async function retrieveMetadataSnapshotCandidates(catalog, input) {
         && (!input.objectTypes?.length || input.objectTypes.includes(object.objectType))
         && (domains.length === 0 || !object.domain || domains.includes(object.domain)));
     const explicitIdentities = explicitMetadataIdentities(input.question);
-    const exactObjects = explicitIdentities.flatMap((identity) => {
-        const resolution = catalog.resolveIdentity(identity);
-        return resolution.status === 'resolved' && resolution.object && isEligible(resolution.object)
-            ? [resolution.object]
-            : [];
-    });
     const queries = uniqueMetadataSearchQueries(input.searchQueries?.length
         ? input.searchQueries
         : [input.question]);
-    const lexicalObjects = mergeObjects(queries.flatMap((query) => catalog.searchObjects({
-        query,
-        objectTypes: input.objectTypes,
-        domains: domains.length > 0 ? domains : undefined,
-        limit,
-    }))).filter(isEligible).slice(0, limit);
-    const vector = await catalog.searchVectorObjects({
-        query: input.question,
-        objectTypes: input.objectTypes,
-        domains: domains.length > 0 ? domains : undefined,
-        limit: Math.min(limit, 24),
-        // Fall back to the PROJECT's configured embedder rather than the hashed
-        // default, so a project that turned on a real one actually queries with it.
-        // searchVectorObjects still refuses (with a reason) if the index was built
-        // by a different provider, which keeps a half-migrated index from silently
-        // returning nonsense.
-        provider: input.embeddingProvider
-            ?? (input.projectRoot ? projectEmbeddingProvider(input.projectRoot) : undefined),
-    });
-    const vectorObjects = vector.candidates.filter(isEligible);
+    // Context lanes are genuinely independent and bounded. Their fan-out is
+    // deliberately before graph expansion: graph admission depends on the
+    // successful seed lanes, while an embedding failure must not block lexical
+    // or exact retrieval (CTX-007/PERF-003).
+    let vector;
+    let exactObjects = [];
+    let lexicalObjects = [];
+    let vectorObjects = [];
+    const laneCards = await retrieveContextLanes({
+        exact: async () => {
+            exactObjects = explicitIdentities.flatMap((identity) => {
+                const resolution = catalog.resolveIdentity(identity);
+                return resolution.status === 'resolved' && resolution.object && isEligible(resolution.object)
+                    ? [resolution.object]
+                    : [];
+            });
+            return exactObjects.map((object) => ({
+                id: object.objectKey,
+                lane: 'exact',
+                relevance: 1,
+                summary: object.name,
+            }));
+        },
+        lexical: async () => {
+            lexicalObjects = mergeObjects(queries.flatMap((query) => catalog.searchObjects({
+                query,
+                objectTypes: input.objectTypes,
+                domains: domains.length > 0 ? domains : undefined,
+                limit,
+            }))).filter(isEligible).slice(0, limit);
+            return lexicalObjects.map((object) => ({
+                id: object.objectKey,
+                lane: 'lexical',
+                relevance: object.score ?? 0,
+                summary: object.name,
+            }));
+        },
+        vector: async () => {
+            vector = await catalog.searchVectorObjects({
+                query: input.question,
+                objectTypes: input.objectTypes,
+                domains: domains.length > 0 ? domains : undefined,
+                limit: Math.min(limit, 24),
+                provider: input.embeddingProvider
+                    ?? (input.projectRoot ? projectEmbeddingProvider(input.projectRoot) : undefined),
+            });
+            vectorObjects = vector.candidates.filter(isEligible);
+            return vectorObjects.map((object) => ({
+                id: object.objectKey,
+                lane: 'vector',
+                relevance: object.score ?? 0,
+                summary: object.name,
+            }));
+        },
+    }, Math.min(limit * 2, 100));
     const seedKeys = mergeObjects([...exactObjects, ...lexicalObjects.slice(0, 12), ...vectorObjects.slice(0, 12)])
         .map((object) => object.objectKey);
-    const graphEdges = catalog.edgesForKeys(seedKeys, 1);
-    const graphObjects = catalog.getObjectsByKeys(Array.from(new Set(graphEdges.flatMap((edge) => [edge.fromKey, edge.toKey])))).filter((object) => isEligible(object) && !seedKeys.includes(object.objectKey)).slice(0, Math.min(limit, 24));
+    const graphStartedAt = Date.now();
+    let graphError;
+    let graphEdges = [];
+    try {
+        graphEdges = catalog.edgesForKeys(seedKeys, 1);
+    }
+    catch (error) {
+        graphError = error instanceof Error ? error.message : String(error);
+    }
+    let graphObjects = [];
+    if (!graphError) {
+        try {
+            graphObjects = catalog.getObjectsByKeys(Array.from(new Set(graphEdges.flatMap((edge) => [edge.fromKey, edge.toKey])))).filter((object) => isEligible(object) && !seedKeys.includes(object.objectKey)).slice(0, Math.min(limit, 24));
+        }
+        catch (error) {
+            // Graph expansion is advisory. Preserve exact/lexical/vector candidates
+            // and expose the typed graph failure in the lane diagnostics.
+            graphError = error instanceof Error ? error.message : String(error);
+            graphObjects = [];
+        }
+    }
     const lanes = [
         retrievalLane('exact', exactObjects, (object) => explicitIdentities.includes(object.objectKey)
             ? 'exact object-key reference'
             : 'resolved qualified/native/alias reference'),
         retrievalLane('lexical', lexicalObjects, () => 'BM25/lexical candidate from the immutable snapshot'),
         {
-            ...retrievalLane('vector', vectorObjects, () => `independent vector candidate from ${vector.providerId}`),
-            provider: vector.providerId,
-            unavailableReason: vector.unavailableReason,
+            ...retrievalLane('vector', vectorObjects, () => `independent vector candidate from ${vector?.providerId ?? 'unavailable'}`),
+            ...(vector?.providerId ? { provider: vector.providerId } : {}),
+            ...(vector?.unavailableReason ? { unavailableReason: vector.unavailableReason } : {}),
         },
         retrievalLane('graph', graphObjects, () => 'one-hop neighbor of an eligible exact/lexical/vector seed'),
     ];
-    const selected = mergeObjects([...exactObjects, ...lexicalObjects, ...vectorObjects, ...graphObjects])
-        .slice(0, limit * 2);
+    const allLaneCards = {
+        exact: exactObjects.map((object) => ({
+            id: object.objectKey,
+            lane: 'exact',
+            relevance: 1,
+            summary: object.name,
+        })),
+        lexical: lexicalObjects.map((object) => ({
+            id: object.objectKey,
+            lane: 'lexical',
+            relevance: object.score ?? 0,
+            summary: object.name,
+        })),
+        vector: vectorObjects.map((object) => ({
+            id: object.objectKey,
+            lane: 'vector',
+            relevance: object.score ?? 0,
+            summary: object.name,
+        })),
+        graph: graphObjects.map((object) => ({
+            id: object.objectKey,
+            lane: 'graph',
+            relevance: object.score ?? 0,
+            summary: object.name,
+        })),
+    };
+    const fused = fuseContextCandidates(allLaneCards, Math.min(limit * 2, 100));
+    const objectsByKey = new Map(mergeObjects([...exactObjects, ...lexicalObjects, ...vectorObjects, ...graphObjects])
+        .map((object) => [object.objectKey, object]));
+    const selected = fused.candidates
+        .map((candidate) => objectsByKey.get(candidate.id))
+        .filter((object) => Boolean(object));
     return {
         snapshotId: catalog.state('fingerprint') ?? 'metadata-unavailable',
         selected,
         lanes,
+        fusion: {
+            selectedKeys: fused.diagnostics.selectedIds,
+            truncated: fused.diagnostics.truncated,
+            lanes: {
+                ...laneCards.diagnostics.lanes,
+                graph: {
+                    returned: graphObjects.length,
+                    durationMs: Date.now() - graphStartedAt,
+                    status: graphError ? 'error' : graphObjects.length > 0 ? 'ok' : 'empty',
+                    ...(graphError ? { error: graphError } : {}),
+                },
+            },
+        },
     };
 }
 function retrievalLane(lane, objects, reason) {
@@ -614,7 +766,17 @@ export async function buildLocalContextPack(projectRoot, request) {
         const runtimeValueObjects = runtimeValueMatchObjects(runtimeCatalog.searchRuntimeValues(metadataValueSearchTerms(request.question, questionPlan, followUp), 32));
         const selectedObjects = selectedContextObjects(request.selectedContext);
         const followUpObjects = followUpContextObjects(followUp);
-        const followUpSourceObjects = catalog.getObjectsByKeys(followUpSourceObjectKeys(followUp));
+        let graphError;
+        let followUpSourceObjects = [];
+        try {
+            followUpSourceObjects = catalog.getObjectsByKeys(followUpSourceObjectKeys(followUp));
+        }
+        catch (error) {
+            // A stale follow-up source reference is advisory context. Keep the
+            // successful exact/lexical/vector lanes and surface a typed graph lane
+            // diagnostic instead of failing the entire context pack (CTX-007).
+            graphError = error instanceof Error ? error.message : String(error);
+        }
         const areaObjects = filterMetadataObjectsByDomainContext(catalog.listAllObjects({ objectTypes: ['model_area'] }), request.domainContext);
         const focusedArea = resolveFocusedModelArea(request.domainContext, request.question, areaObjects);
         const effectiveDomainContext = focusedArea && request.domainContext
@@ -655,9 +817,20 @@ export async function buildLocalContextPack(projectRoot, request) {
             ? 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 = retrievalObjects(catalog.getObjectsByKeys(edgeObjectKeys));
+        let edgeWalk = [];
+        let graphObjects = [];
+        try {
+            edgeWalk = catalog.edgesForKeys(selected.map((row) => row.objectKey), 3);
+            const edgeObjectKeys = Array.from(new Set(edgeWalk.flatMap((edge) => [edge.fromKey, edge.toKey])));
+            graphObjects = retrievalObjects(catalog.getObjectsByKeys(edgeObjectKeys));
+        }
+        catch (error) {
+            // The graph is an enrichment lane. A stale/corrupt graph must not discard
+            // successful snapshot, runtime, or semantic candidates (CTX-007).
+            graphError = error instanceof Error ? error.message : String(error);
+            edgeWalk = [];
+            graphObjects = [];
+        }
         const rankedObjects = rankMetadataObjects({
             rows: retrievalObjects(mergeObjects([...followUpSourceObjects, ...followUpObjects, ...selected, ...graphObjects, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects])),
             question: searchQueries.join(' '),
@@ -665,7 +838,27 @@ export async function buildLocalContextPack(projectRoot, request) {
             modelAreaId: focusedArea?.id,
             limit: request.limit ?? 120,
         }).selected;
-        const sqlParentObjects = sqlParentObjectsForSelectedColumns(rankedObjects, mergeObjects([...graphObjects, ...runtimeObjects]), questionPlan);
+        // Reorder by what the QUESTION needs. RRF and the additive score rank by
+        // overlap, distance, and type weight — none of which read the question — so
+        // the object that answers it can sit behind ten near-synonyms and be cut by
+        // a top-N that never considered the ask. Advisory: the reranker may only
+        // reorder ids retrieval already returned, and any failure leaves this list
+        // exactly as it was.
+        const rerankedObjects = request.rerankCandidates
+            ? applyRerank(rankedObjects, (object) => object.objectKey, await request.rerankCandidates(searchQueries.join(' '), rankedObjects.slice(0, 40).map((object) => ({
+                id: object.objectKey,
+                summary: [
+                    object.name,
+                    object.objectType,
+                    object.description?.slice(0, 160),
+                ].filter(Boolean).join(' — '),
+            }))).catch(() => undefined))
+            : rankedObjects;
+        if (process.env.DQL_ORCHESTRATOR_TRACE && request.rerankCandidates) {
+            const moved = rerankedObjects.findIndex((object, position) => object.objectKey !== rankedObjects[position]?.objectKey);
+            console.warn(`[dql] rerank: ${moved < 0 ? 'no change' : `reordered from position ${moved}`} over ${Math.min(40, rankedObjects.length)} candidates`);
+        }
+        const sqlParentObjects = sqlParentObjectsForSelectedColumns(rerankedObjects, mergeObjects([...graphObjects, ...runtimeObjects]), questionPlan);
         // 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.
@@ -689,17 +882,27 @@ export async function buildLocalContextPack(projectRoot, request) {
             limit: 8,
         }).selected;
         const objects = fullCatalogObjects
-            ? mergeObjects([...rankedObjects, ...sqlParentObjects, ...fullCatalogObjects, ...selectedSkillObjects, ...routeObjects])
-            : mergeObjects([...rankedObjects, ...sqlParentObjects, ...selectedSkillObjects, ...routeObjects]);
+            ? mergeObjects([...rerankedObjects, ...sqlParentObjects, ...fullCatalogObjects, ...selectedSkillObjects, ...routeObjects])
+            : mergeObjects([...rerankedObjects, ...sqlParentObjects, ...selectedSkillObjects, ...routeObjects]);
         const objectKeys = objects.map((row) => row.objectKey);
         const allowedObjectKeys = new Set(objectKeys);
-        const contextEdges = mergeMetadataEdges([
-            ...edgeWalk,
-            ...catalog.edgesForKeys(objectKeys, 2),
-        ]).filter((edge) => allowedObjectKeys.has(edge.fromKey) && allowedObjectKeys.has(edge.toKey));
+        let contextEdges = mergeMetadataEdges(edgeWalk)
+            .filter((edge) => allowedObjectKeys.has(edge.fromKey) && allowedObjectKeys.has(edge.toKey));
+        try {
+            contextEdges = mergeMetadataEdges([
+                ...contextEdges,
+                ...catalog.edgesForKeys(objectKeys, 2),
+            ]).filter((edge) => allowedObjectKeys.has(edge.fromKey) && allowedObjectKeys.has(edge.toKey));
+        }
+        catch (error) {
+            graphError ??= error instanceof Error ? error.message : String(error);
+        }
         const queryRuns = runtimeCatalog.queryRunsForObjectKeys(objectKeys, 20);
         const diagnostics = catalog.diagnostics();
-        const warnings = buildWarnings(diagnostics, objects);
+        const warnings = [
+            ...buildWarnings(diagnostics, objects),
+            ...(graphError ? [`Graph/context enrichment lane unavailable: ${graphError}`] : []),
+        ];
         const trustLabel = deriveTrust(objects);
         const citations = buildCitations(objects, contextEdges);
         const evidenceSummaries = buildEvidenceSummaries(objects, contextEdges, queryRuns, diagnostics);
@@ -796,6 +999,29 @@ export async function buildLocalContextPack(projectRoot, request) {
             retrievalDiagnostics: {
                 strategy: usedFullCatalog ? 'full_catalog' : 'sqlite_fts',
                 lanes: snapshotRetrieval.lanes,
+                ...(snapshotRetrieval.fusion ? {
+                    fusion: {
+                        ...snapshotRetrieval.fusion,
+                        ...(graphError ? {
+                            lanes: {
+                                ...(snapshotRetrieval.fusion.lanes ?? {}),
+                                graph: {
+                                    ...(snapshotRetrieval.fusion.lanes?.graph ?? { returned: 0 }),
+                                    status: 'error',
+                                    error: graphError,
+                                },
+                            },
+                        } : {}),
+                    },
+                } : graphError ? {
+                    fusion: {
+                        selectedKeys: selected.map((object) => object.objectKey),
+                        truncated: false,
+                        lanes: {
+                            graph: { returned: 0, status: 'error', error: graphError },
+                        },
+                    },
+                } : {}),
                 focusedModelAreaId: focusedArea?.id,
                 modelAreaSource: focusedArea?.source,
                 selectedObjects: objects.length,
@@ -1325,6 +1551,19 @@ function addManifestKnowledgeGraph(manifest, objects, edges) {
         const displayName = knowledgeDisplayName(item.kind, item.localId, itemPayload);
         const objectKey = knowledgeMetadataKey(item.kind, displayName, item.id, item.source.system);
         keyByGraphId.set(item.id, objectKey);
+        // The registry emits an UNRESOLVED ALIAS beside the entity-qualified node
+        // for the same semantic member: `semantic::metric.jaffle_shop.revenue`
+        // (note the empty entity segment) beside `semantic:order_item:revenue`.
+        // The alias carries no aggregation, grain, or prose — its description is
+        // the raw dbt unique_id — so it can never be proven compatible, yet it
+        // competes for bounded retrieval and clarification slots with the node that
+        // can. 18 of 37 metrics in the commerce fixture were these.
+        //
+        // Skipping it is a no-op for meaning: it holds nothing the qualified node
+        // does not. The graph-id mapping above is still recorded so edges keep
+        // resolving. Anything carrying real payload is indexed as before.
+        if (isUnresolvedSemanticAlias(item.kind, item.id, itemPayload))
+            continue;
         const description = stringValue(itemPayload?.description)
             ?? stringValue(itemPayload?.businessContext)
             ?? itemAliases?.find((alias) => alias !== item.localId);
@@ -1410,6 +1649,32 @@ function addMetadataEdge(edges, edgeType, fromKey, toKey, payload) {
     if (!edges.has(key))
         edges.set(key, { edgeType, fromKey, toKey, confidence: 1, payload: compactObject(payload) });
 }
+/**
+ * True for the registry's payload-less alias of a semantic member.
+ *
+ * A qualified semantic identity is `semantic:<entity>:<member>`. When the
+ * owning entity could not be resolved the registry still emits the node with an
+ * EMPTY entity segment — `semantic::metric.jaffle_shop.revenue` — carrying only
+ * the source's native id. Requiring an entity segment is the same
+ * entity-qualified identity rule the semantic catalog is built on.
+ *
+ * Anything holding real meaning (an aggregation, a label, an expression, or
+ * LLM context) is NOT an alias and is kept, even unqualified.
+ */
+function isUnresolvedSemanticAlias(kind, qualifiedId, payload) {
+    if (!['metric', 'measure', 'dimension'].includes(kind))
+        return false;
+    if (!/^semantic::/.test(qualifiedId))
+        return false;
+    const record = payload ?? {};
+    return !record.aggregation
+        && !record.llmContext
+        && !record.label
+        && !record.expression
+        && !record.formula
+        && !record.dimensions
+        && !record.entities;
+}
 function knowledgeMetadataKey(kind, localId, qualifiedId, sourceSystem) {
     switch (kind) {
         case 'block': return `dql:block:${localId}`;
@@ -6637,11 +6902,56 @@ const VECTOR_EXCLUDED_OBJECT_TYPES = new Set([
     'skill',
     'runtime_value',
 ]);
+/**
+ * A DOCUMENTED column earns a vector, even though columns are excluded as a class.
+ *
+ * Excluding every column left a question phrased in column vocabulary ("which
+ * field holds the customer's tier?") with no semantic recall path at all — the
+ * lexical lane is the only thing that could ever find it, and that is exactly
+ * the case where the user's words and the schema's words differ.
+ *
+ * The exclusion existed for volume, and that concern is real: columns outnumber
+ * models by 10-50x and `searchVectorObjects` is an O(n) scan in JS. A DESCRIPTION
+ * is the natural bound — it means someone documented the column on purpose, which
+ * is both a quality signal and a small fraction of any real warehouse. An
+ * undocumented column has nothing to embed but its name, which the lexical lane
+ * already matches better than a vector would.
+ */
+function isDocumentedColumnObject(object) {
+    return COLUMN_OBJECT_TYPES.has(object.objectType)
+        && object.objectType !== 'runtime_value'
+        && (object.description?.trim().length ?? 0) > 0;
+}
+/**
+ * A skill is written vocabulary — the words a team uses for a task — which is
+ * exactly what a vector is for. Excluding the type wholesale meant a question
+ * phrased in the team's language could only ever be found by keyword. Bounded
+ * the same way as columns: it must actually be documented, so an empty skill
+ * stub does not earn an embedding.
+ */
+function isDocumentedSkillObject(object) {
+    return object.objectType === 'skill' && (object.description?.trim().length ?? 0) > 0;
+}
 function isVectorIndexObject(object) {
+    if (isDocumentedColumnObject(object))
+        return true;
+    if (isDocumentedSkillObject(object))
+        return true;
     return !VECTOR_EXCLUDED_OBJECT_TYPES.has(object.objectType);
 }
 function metadataVectorText(object) {
+    // A bare column name is a naked token: `status` on its own is equally close to
+    // every status-ish thing in the warehouse. Lead with the parent-qualified name
+    // and the type so the vector carries WHICH table's status this is.
+    const columnPrefix = isDocumentedColumnObject(object)
+        ? [
+            `${object.fullName ?? object.name} column`,
+            stringValue((object.payload ?? {}).type) ?? '',
+            stringValue((object.payload ?? {}).relation) ?? '',
+        ].filter(Boolean).join(' ')
+        : '';
     return [
+        columnPrefix,
         object.name,
         object.fullName ?? '',
         object.description ?? '',