@duckcodeailabs/dql-agent 1.9.5 → 1.10.0

package/dist/metadata/catalog.js

@@ -13,6 +13,7 @@ import { dirname, join } from 'node:path';
 import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from 'node:zlib';
 import { buildManifest, buildManifestKnowledgeGraph, loadDomainPackageRegistry, loadManifestKnowledgeSkills, loadProjectConfig, parseContractRef, resolveDataLexManifestPath, resolveDbtManifestPath, resolveSemanticLayerWithDiagnostics, extractColumnLineage, normalizeDqlArtifactReference, composeEffectiveTrust, } from '@duckcodeailabs/dql-core';
 import { buildKGFromManifest, buildKGFromSemanticLayer } from '../kg/build.js';
+import { domainContextSearchDomains } from '../domain-context.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';
@@ -20,11 +21,11 @@ import { grainMatches, requestedGrainFromPlan, } from './grain-gate.js';
 import { certifiedFitAllowsTier1, certifiedTerminationVerdict, evaluateCertifiedBlockFit, } from './block-fit.js';
 import { retrieveScopedHints } from '../hints/retrieval.js';
 import { buildFtsMatch } from '../memory/fts-query.js';
-import { envEmbeddingProvider } from '../embeddings/provider.js';
+import { cosineSimilarity, envEmbeddingProvider, HashedTokenEmbeddingProvider, } from '../embeddings/provider.js';
 import { matchExampleParaphrase } from './example-match.js';
 import { loadSkills, selectRelevantSkills } from '../skills/loader.js';
 import { buildMeaningEvidencePackage, } from './meaning-evidence.js';
-export { toAgentRetrievalEvidence } from './meaning-evidence.js';
+export { applyContextPackCompatibility, toAgentRetrievalEvidence } from './meaning-evidence.js';
 const require = createRequire(import.meta.url);
 let databaseCtor = null;
 function loadDatabase() {
@@ -93,26 +94,36 @@ const OBJECT_PRIORITY = {
 };
 const COLUMN_OBJECT_TYPES = new Set(['dbt_column', 'warehouse_column', 'runtime_column', 'runtime_value']);
 // v3 removes the legacy persisted plaintext runtime-value cache (SEC-003).
-const METADATA_INDEX_VERSION = 'metadata-index-v4-content-addressed-skills';
+const METADATA_INDEX_VERSION = 'metadata-index-v5-qualified-vector-lanes';
+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', `${fingerprint}.sqlite`);
+    return join(projectRoot, '.dql', 'cache', 'snapshots', `${METADATA_INDEX_VERSION}-${fingerprint}.sqlite`);
 }
-export function activeMetadataSnapshotPath(projectRoot) {
+function readActiveMetadataSnapshotPointer(projectRoot) {
     const pointerPath = join(projectRoot, '.dql', 'cache', 'active-snapshot.json');
     if (!existsSync(pointerPath))
         return null;
     try {
         const parsed = JSON.parse(readFileSync(pointerPath, 'utf8'));
-        const path = typeof parsed.snapshotPath === 'string' ? parsed.snapshotPath : '';
-        return path && existsSync(path) ? path : null;
+        const snapshotId = typeof parsed.snapshotId === 'string' ? parsed.snapshotId : '';
+        const snapshotPath = typeof parsed.snapshotPath === 'string' ? parsed.snapshotPath : '';
+        const indexSchemaVersion = typeof parsed.indexSchemaVersion === 'string'
+            ? parsed.indexSchemaVersion
+            : undefined;
+        if (!snapshotId || !snapshotPath || !existsSync(snapshotPath))
+            return null;
+        return { snapshotId, snapshotPath, indexSchemaVersion };
     }
     catch {
         return null;
     }
 }
+export function activeMetadataSnapshotPath(projectRoot) {
+    return readActiveMetadataSnapshotPointer(projectRoot)?.snapshotPath ?? null;
+}
 /** Read the prepared catalog identity without rebuilding the metadata snapshot. */
 export function currentMetadataFingerprint(projectRoot) {
     if (!existsSync(defaultMetadataPath(projectRoot)))
@@ -150,6 +161,47 @@ export function openActiveKnowledgeSnapshot(projectRoot) {
     const path = activeMetadataSnapshotPath(projectRoot) ?? defaultMetadataPath(projectRoot);
     return new MetadataCatalog(path, { readOnly: path !== defaultMetadataPath(projectRoot) });
 }
+const activeKnowledgeSnapshotLeases = new Map();
+/**
+ * Acquire one exact immutable SQLite file for a request lifetime. The active
+ * pointer is read once; later activations cannot redirect this lease to a
+ * different catalog. Callers must release in `finally`.
+ *
+ * Acceptance: CTX-002, CTX-005.
+ */
+export function acquireActiveKnowledgeSnapshot(projectRoot) {
+    const pointer = readActiveMetadataSnapshotPointer(projectRoot);
+    const path = pointer?.snapshotPath ?? defaultMetadataPath(projectRoot);
+    const catalog = new MetadataCatalog(path, { readOnly: Boolean(pointer) });
+    const catalogFingerprint = catalog.state('fingerprint') ?? 'metadata-unavailable';
+    if (pointer && pointer.snapshotId !== catalogFingerprint) {
+        catalog.close();
+        throw new Error(`Active metadata snapshot pointer mismatch (pointer ${pointer.snapshotId}, catalog ${catalogFingerprint}).`);
+    }
+    activeKnowledgeSnapshotLeases.set(path, (activeKnowledgeSnapshotLeases.get(path) ?? 0) + 1);
+    let released = false;
+    return Object.freeze({
+        snapshotId: catalogFingerprint,
+        path,
+        catalog,
+        release() {
+            if (released)
+                return;
+            released = true;
+            catalog.close();
+            const remaining = (activeKnowledgeSnapshotLeases.get(path) ?? 1) - 1;
+            if (remaining > 0)
+                activeKnowledgeSnapshotLeases.set(path, remaining);
+            else
+                activeKnowledgeSnapshotLeases.delete(path);
+        },
+    });
+}
+export function activeKnowledgeSnapshotLeaseCount(path) {
+    if (path)
+        return activeKnowledgeSnapshotLeases.get(path) ?? 0;
+    return Array.from(activeKnowledgeSnapshotLeases.values()).reduce((sum, count) => sum + count, 0);
+}
 export function readIndexedDomainKnowledge(projectRoot, domainId) {
     const catalog = openActiveKnowledgeSnapshot(projectRoot);
     try {
@@ -295,6 +347,92 @@ export function upsertMetadataSnapshot(projectRoot, snapshot) {
         catalog.close();
     }
 }
+/**
+ * Run exact, BM25/lexical, vector, and graph candidate generation as
+ * independent lanes over one acquired snapshot. Domain/import eligibility is
+ * applied in SQL or before graph admission, never as a post-ranking boost.
+ *
+ * Acceptance: CTX-005, AGT-009, AGT-010.
+ */
+export async function retrieveMetadataSnapshotCandidates(catalog, input) {
+    const limit = Math.max(1, input.limit ?? 80);
+    const domains = domainContextSearchDomains(input.domainContext);
+    const isEligible = (object) => (object.objectType !== 'skill'
+        && (!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),
+        provider: input.embeddingProvider,
+    });
+    const vectorObjects = vector.candidates.filter(isEligible);
+    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 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('graph', graphObjects, () => 'one-hop neighbor of an eligible exact/lexical/vector seed'),
+    ];
+    const selected = mergeObjects([...exactObjects, ...lexicalObjects, ...vectorObjects, ...graphObjects])
+        .slice(0, limit * 2);
+    return {
+        snapshotId: catalog.state('fingerprint') ?? 'metadata-unavailable',
+        selected,
+        lanes,
+    };
+}
+function retrievalLane(lane, objects, reason) {
+    return {
+        lane,
+        candidates: objects.map((object, index) => ({
+            objectKey: object.objectKey,
+            objectType: object.objectType,
+            name: object.name,
+            rank: index + 1,
+            score: Number((object.score ?? (1 / (index + 1))).toFixed(6)),
+            reason: reason(object),
+        })),
+    };
+}
+function explicitMetadataIdentities(question) {
+    const identities = [];
+    for (const match of question.matchAll(/@(metric|dimension|measure|entity|model|block|term)\(([^)]+)\)/gi)) {
+        const identity = match[2]?.trim();
+        if (identity)
+            identities.push(identity);
+    }
+    for (const match of question.matchAll(/\b(?:semantic|dql|dbt|skill):[a-z0-9_.:-]+/gi)) {
+        identities.push(match[0]);
+    }
+    return Array.from(new Set(identities));
+}
 export async function buildLocalContextPack(projectRoot, request) {
     let prepared = false;
     if (request.preparedMetadataFingerprint) {
@@ -311,8 +449,9 @@ export async function buildLocalContextPack(projectRoot, request) {
     // Static governed knowledge is read from the immutable content-addressed
     // snapshot selected at request start. Mutable run history, runtime schema,
     // and context packs stay in the working catalog and never alter that view.
-    const snapshotPath = activeMetadataSnapshotPath(projectRoot) ?? defaultMetadataPath(projectRoot);
-    const catalog = openActiveKnowledgeSnapshot(projectRoot);
+    const snapshotLease = acquireActiveKnowledgeSnapshot(projectRoot);
+    const snapshotPath = snapshotLease.path;
+    const catalog = snapshotLease.catalog;
     const runtimeCatalog = openMetadataCatalog(projectRoot);
     try {
         const mode = request.mode ?? 'question';
@@ -400,11 +539,14 @@ export async function buildLocalContextPack(projectRoot, request) {
         // Leaving it in generic FTS results would bypass status/domain/area/exclusion
         // eligibility simply because a word in its body matched the question.
         const retrievalObjects = (rows) => scopeObjects(rows).filter((row) => row.objectType !== 'skill');
-        const searchRows = retrievalObjects(mergeObjects(searchQueries.flatMap((query) => catalog.searchObjects({
-            query,
+        const snapshotRetrieval = await retrieveMetadataSnapshotCandidates(catalog, {
+            question: request.question,
+            searchQueries,
             objectTypes: request.objectTypes,
+            domainContext: effectiveDomainContext,
             limit: Math.max(request.limit ?? 80, 20),
-        }))));
+        });
+        const searchRows = retrievalObjects(snapshotRetrieval.selected);
         const schemaShapeCandidates = schemaShapeCandidateObjects(catalog, questionPlan, request, mergeObjects([...runtimeObjects, ...runtimeValueObjects]));
         const schemaShapeObjects = schemaShapeCandidates.map((candidate) => candidate.object);
         const exactCandidate = request.focusObjectKey ? catalog.getObject(request.focusObjectKey) : null;
@@ -550,6 +692,7 @@ export async function buildLocalContextPack(projectRoot, request) {
             hintConflicts: hintResult.conflicts,
             retrievalDiagnostics: {
                 strategy: usedFullCatalog ? 'full_catalog' : 'sqlite_fts',
+                lanes: snapshotRetrieval.lanes,
                 focusedModelAreaId: focusedArea?.id,
                 modelAreaSource: focusedArea?.source,
                 selectedObjects: objects.length,
@@ -588,7 +731,7 @@ export async function buildLocalContextPack(projectRoot, request) {
         return { ...payload, id };
     }
     finally {
-        catalog.close();
+        snapshotLease.release();
         runtimeCatalog.close();
     }
 }
@@ -611,7 +754,10 @@ function buildKnowledgeLens(catalog, context, selectedSkills) {
         modelAreaId: context?.modelAreaId,
         purpose: context?.purpose,
         skillRefs,
-        snapshotId: context?.snapshotId ?? catalog.state('fingerprint') ?? 'metadata-unavailable',
+        // The immutable search snapshot is authoritative. A caller-provided
+        // envelope may have been resolved against an earlier manifest signature;
+        // it cannot relabel the catalog that actually supplied evidence.
+        snapshotId: catalog.state('fingerprint') ?? 'metadata-unavailable',
         capsuleFingerprint: stringValue(capsule?.payload?.fingerprint)
             ?? stringValue(capsule?.payload?.sourceFingerprint),
         skillFingerprints: Object.keys(skillFingerprints).length > 0 ? skillFingerprints : undefined,
@@ -1036,6 +1182,15 @@ export class MetadataCatalog {
         tokenize = 'porter unicode61'
       );
 
+      CREATE TABLE IF NOT EXISTS metadata_vector_index (
+        object_key    TEXT PRIMARY KEY,
+        provider_id  TEXT NOT NULL,
+        dimensions   INTEGER NOT NULL,
+        vector       BLOB NOT NULL,
+        text_hash    TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_metadata_vector_provider ON metadata_vector_index(provider_id);
+
       CREATE TABLE IF NOT EXISTS metadata_edges (
         edge_type    TEXT NOT NULL,
         from_key     TEXT NOT NULL,
@@ -1192,6 +1347,10 @@ export class MetadataCatalog {
         const insertFts = this.db.prepare(`
       INSERT INTO metadata_fts (object_key, name, full_name, description, domain, owner, payload)
       VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+        const insertVector = this.db.prepare(`
+      INSERT INTO metadata_vector_index (object_key, provider_id, dimensions, vector, text_hash)
+      VALUES (?, ?, ?, ?, ?)
     `);
         const insertEdge = this.db.prepare(`
       INSERT OR IGNORE INTO metadata_edges (
@@ -1226,6 +1385,7 @@ export class MetadataCatalog {
         const txn = this.db.transaction(() => {
             this.db.prepare('DELETE FROM metadata_edges').run();
             this.db.prepare('DELETE FROM metadata_fts').run();
+            this.db.prepare('DELETE FROM metadata_vector_index').run();
             this.db.prepare('DELETE FROM metadata_objects').run();
             this.db.prepare('DELETE FROM metadata_diagnostics').run();
             this.db.prepare('DELETE FROM metadata_source_fingerprints').run();
@@ -1235,6 +1395,11 @@ export class MetadataCatalog {
                 const payload = object.payload ?? {};
                 insertObject.run(object.objectKey, object.objectType, object.name, object.fullName ?? null, object.domain ?? null, object.owner ?? null, object.status ?? null, object.description ?? null, object.sourcePath ?? null, object.sourceSystem ?? null, JSON.stringify(payload), object.updatedAt ?? now);
                 insertFts.run(object.objectKey, object.name, object.fullName ?? '', object.description ?? '', object.domain ?? '', object.owner ?? '', searchableMetadataPayload(payload));
+                if (isVectorIndexObject(object)) {
+                    const vectorText = metadataVectorText(object);
+                    const vector = DEFAULT_VECTOR_PROVIDER.embedOne(vectorText);
+                    insertVector.run(object.objectKey, DEFAULT_VECTOR_PROVIDER.id, vector.length, encodeFloat32Vector(vector), sha256(vectorText));
+                }
             }
             for (const edge of snapshot.edges) {
                 insertEdge.run(edge.edgeType, edge.fromKey, edge.toKey, edge.confidence ?? 1, JSON.stringify(edge.payload ?? {}), now);
@@ -1262,6 +1427,8 @@ export class MetadataCatalog {
             setState.run('compile_conflicts_json', JSON.stringify(snapshot.compileConflicts ?? []));
             setState.run('manifest_generated_at', snapshot.manifest.generatedAt);
             setState.run('index_version', METADATA_INDEX_VERSION);
+            setState.run('vector_provider', DEFAULT_VECTOR_PROVIDER.id);
+            setState.run('vector_dimensions', String(DEFAULT_VECTOR_PROVIDER.dimensions));
         });
         txn();
     }
@@ -1303,6 +1470,9 @@ export class MetadataCatalog {
         const insertFts = this.db.prepare(`
       INSERT INTO metadata_fts (object_key, name, full_name, description, domain, owner, payload)
       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        const insertVector = this.db.prepare(`
+      INSERT INTO metadata_vector_index (object_key, provider_id, dimensions, vector, text_hash)
+      VALUES (?, ?, ?, ?, ?)`);
         const insertEdge = this.db.prepare(`
       INSERT OR IGNORE INTO metadata_edges (edge_type, from_key, to_key, confidence, payload_json, created_at)
       VALUES (?, ?, ?, ?, ?, ?)`);
@@ -1324,15 +1494,18 @@ export class MetadataCatalog {
       INSERT OR REPLACE INTO skill_bodies (body_hash, encoding, compressed_body, original_length)
       VALUES (?, 'br', ?, ?)`);
         const deleteFtsForSource = this.db.prepare('DELETE FROM metadata_fts WHERE object_key IN (SELECT object_key FROM metadata_objects WHERE COALESCE(source_path, source_system) = ?)');
+        const deleteVectorsForSource = this.db.prepare('DELETE FROM metadata_vector_index WHERE object_key IN (SELECT object_key FROM metadata_objects WHERE COALESCE(source_path, source_system) = ?)');
         const deleteObjectsForSource = this.db.prepare('DELETE FROM metadata_objects WHERE COALESCE(source_path, source_system) = ?');
         const txn = this.db.transaction(() => {
             // Drop changed + removed sources' rows, and ALL sourceless rows (never
             // fingerprinted, so always refreshed).
             for (const source of [...changedSources, ...removedSources]) {
                 deleteFtsForSource.run(source);
+                deleteVectorsForSource.run(source);
                 deleteObjectsForSource.run(source);
             }
             this.db.prepare('DELETE FROM metadata_fts WHERE object_key IN (SELECT object_key FROM metadata_objects WHERE source_path IS NULL AND source_system IS NULL)').run();
+            this.db.prepare('DELETE FROM metadata_vector_index WHERE object_key IN (SELECT object_key FROM metadata_objects WHERE source_path IS NULL AND source_system IS NULL)').run();
             this.db.prepare('DELETE FROM metadata_objects WHERE source_path IS NULL AND source_system IS NULL').run();
             // Re-insert only objects from changed sources or sourceless; unchanged
             // sources' rows are left untouched.
@@ -1343,6 +1516,11 @@ export class MetadataCatalog {
                 const payload = object.payload ?? {};
                 insertObject.run(object.objectKey, object.objectType, object.name, object.fullName ?? null, object.domain ?? null, object.owner ?? null, object.status ?? null, object.description ?? null, object.sourcePath ?? null, object.sourceSystem ?? null, JSON.stringify(payload), object.updatedAt ?? now);
                 insertFts.run(object.objectKey, object.name, object.fullName ?? '', object.description ?? '', object.domain ?? '', object.owner ?? '', searchableMetadataPayload(payload));
+                if (isVectorIndexObject(object)) {
+                    const vectorText = metadataVectorText(object);
+                    const vector = DEFAULT_VECTOR_PROVIDER.embedOne(vectorText);
+                    insertVector.run(object.objectKey, DEFAULT_VECTOR_PROVIDER.id, vector.length, encodeFloat32Vector(vector), sha256(vectorText));
+                }
             }
             // Cross-source tables: rebuild fully.
             this.db.prepare('DELETE FROM metadata_edges').run();
@@ -1378,12 +1556,14 @@ export class MetadataCatalog {
             setState.run('compile_conflicts_json', JSON.stringify(snapshot.compileConflicts ?? []));
             setState.run('manifest_generated_at', snapshot.manifest.generatedAt);
             setState.run('index_version', METADATA_INDEX_VERSION);
+            setState.run('vector_provider', DEFAULT_VECTOR_PROVIDER.id);
+            setState.run('vector_dimensions', String(DEFAULT_VECTOR_PROVIDER.dimensions));
         });
         txn();
         return { mode: 'incremental', changedSources: changedSources.size };
     }
     searchObjects(options) {
-        const { query, objectTypes, domain, limit = 40 } = options;
+        const { query, objectTypes, domain, domains, limit = 40 } = options;
         const match = buildFtsMatch(query, { prefix: true });
         if (!match.or)
             return this.listObjects({ objectTypes, domain, limit });
@@ -1397,6 +1577,10 @@ export class MetadataCatalog {
             filters.push('o.domain = ?');
             extraParams.push(domain);
         }
+        else if (domains?.length) {
+            filters.push(`(o.domain IS NULL OR o.domain IN (${domains.map(() => '?').join(', ')}))`);
+            extraParams.push(...domains);
+        }
         const whereExtra = filters.length > 0 ? ` AND ${filters.join(' AND ')}` : '';
         const runMatch = (matchExpr) => this.db.prepare(`
       SELECT o.*,
@@ -1429,6 +1613,106 @@ export class MetadataCatalog {
             snippet: row.snip ?? undefined,
         }));
     }
+    /** Replace the snapshot vector lane with an explicitly configured provider. */
+    async rebuildVectorIndex(provider, batchSize = 96) {
+        const objects = [];
+        this.scanObjects({ batchSize: 500 }, (rows) => {
+            objects.push(...rows.filter(isVectorIndexObject));
+        });
+        const encoded = [];
+        let dimensions = 0;
+        for (let offset = 0; offset < objects.length; offset += Math.max(1, batchSize)) {
+            const batch = objects.slice(offset, offset + Math.max(1, batchSize));
+            const texts = batch.map(metadataVectorText);
+            const vectors = await provider.embed(texts);
+            if (vectors.length !== batch.length) {
+                throw new Error(`Embedding provider ${provider.id} returned ${vectors.length} vectors for ${batch.length} objects.`);
+            }
+            for (let index = 0; index < batch.length; index += 1) {
+                const vector = vectors[index] ?? [];
+                if (vector.length === 0)
+                    throw new Error(`Embedding provider ${provider.id} returned an empty vector.`);
+                if (dimensions === 0)
+                    dimensions = vector.length;
+                if (vector.length !== dimensions) {
+                    throw new Error(`Embedding provider ${provider.id} changed dimensions from ${dimensions} to ${vector.length}.`);
+                }
+                encoded.push({
+                    objectKey: batch[index].objectKey,
+                    dimensions,
+                    vector: encodeFloat32Vector(vector),
+                    textHash: sha256(texts[index]),
+                });
+            }
+        }
+        const insert = this.db.prepare(`
+      INSERT INTO metadata_vector_index (object_key, provider_id, dimensions, vector, text_hash)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const setState = this.db.prepare('INSERT OR REPLACE INTO metadata_state (key, value) VALUES (?, ?)');
+        this.db.transaction(() => {
+            this.db.prepare('DELETE FROM metadata_vector_index').run();
+            for (const item of encoded) {
+                insert.run(item.objectKey, provider.id, item.dimensions, item.vector, item.textHash);
+            }
+            setState.run('vector_provider', provider.id);
+            setState.run('vector_dimensions', String(dimensions));
+        })();
+    }
+    /** Independent vector candidate generation over all eligible snapshot cards. */
+    async searchVectorObjects(options) {
+        const indexedProviderId = this.state('vector_provider') ?? DEFAULT_VECTOR_PROVIDER.id;
+        const indexedDimensions = Number(this.state('vector_dimensions') ?? DEFAULT_VECTOR_PROVIDER.dimensions);
+        const provider = options.provider ?? DEFAULT_VECTOR_PROVIDER;
+        if (provider.id !== indexedProviderId) {
+            return {
+                providerId: indexedProviderId,
+                dimensions: indexedDimensions,
+                candidates: [],
+                unavailableReason: `requested provider ${provider.id} does not match snapshot vector provider ${indexedProviderId}`,
+            };
+        }
+        const [queryVector] = provider === DEFAULT_VECTOR_PROVIDER
+            ? [DEFAULT_VECTOR_PROVIDER.embedOne(options.query)]
+            : await provider.embed([options.query]);
+        if (!queryVector || queryVector.length !== indexedDimensions) {
+            return {
+                providerId: indexedProviderId,
+                dimensions: indexedDimensions,
+                candidates: [],
+                unavailableReason: `query vector dimensions do not match snapshot index (${queryVector?.length ?? 0} vs ${indexedDimensions})`,
+            };
+        }
+        const filters = ['v.provider_id = ?'];
+        const params = [indexedProviderId];
+        if (options.objectTypes?.length) {
+            filters.push(`o.object_type IN (${options.objectTypes.map(() => '?').join(', ')})`);
+            params.push(...options.objectTypes);
+        }
+        if (options.domains?.length) {
+            filters.push(`(o.domain IS NULL OR o.domain IN (${options.domains.map(() => '?').join(', ')}))`);
+            params.push(...options.domains);
+        }
+        const rows = this.db.prepare(`
+      SELECT o.*, v.vector AS vector_blob
+      FROM metadata_vector_index AS v
+      JOIN metadata_objects AS o ON o.object_key = v.object_key
+      WHERE ${filters.join(' AND ')}
+      ORDER BY o.object_key
+    `).all(...params);
+        const candidates = rows
+            .map((row) => {
+            const cosine = cosineSimilarity(queryVector, decodeFloat32Vector(row.vector_blob));
+            return { ...rowToObject(row), score: Number(((cosine + 1) / 2).toFixed(6)) };
+        })
+            // A cosine of zero maps to 0.5 and is not evidence. Requiring positive
+            // separation prevents hash collisions/unrelated cards from flooding the
+            // downstream bounded context while retaining independent vector recall.
+            .filter((row) => (row.score ?? 0) > 0.55)
+            .sort((left, right) => (right.score ?? 0) - (left.score ?? 0) || left.objectKey.localeCompare(right.objectKey))
+            .slice(0, Math.max(1, options.limit ?? 40));
+        return { providerId: indexedProviderId, dimensions: indexedDimensions, candidates };
+    }
     listObjects(options = {}) {
         const filters = [];
         const params = [];
@@ -1556,13 +1840,49 @@ export class MetadataCatalog {
         return rows;
     }
     findObjectByIdentity(identity) {
+        return this.resolveIdentity(identity).object ?? null;
+    }
+    /** Resolve exact/qualified/native/alias identities without first-match wins. */
+    resolveIdentity(identity) {
+        const normalized = identity.trim();
+        if (!normalized)
+            return { identity, status: 'missing', candidates: [] };
+        const exact = this.db.prepare(`
+      SELECT * FROM metadata_objects WHERE object_key = ?
+    `).get(normalized);
+        if (exact) {
+            const object = rowToObject(exact);
+            return { identity, status: 'resolved', matchedBy: 'object_key', object, candidates: [object] };
+        }
         const rows = this.db.prepare(`
-      SELECT * FROM metadata_objects
-      WHERE object_key = ? OR full_name = ?
-      ORDER BY CASE WHEN object_key = ? THEN 0 ELSE 1 END, object_key
-      LIMIT 2
-    `).all(identity, identity, identity);
-        return rows.length === 1 ? rowToObject(rows[0]) : rows[0] ? rowToObject(rows[0]) : null;
+      SELECT DISTINCT o.*
+      FROM metadata_objects AS o
+      WHERE o.full_name = ?
+         OR json_extract(o.payload_json, '$.sourceNativeId') = ?
+         OR EXISTS (
+           SELECT 1
+           FROM json_each(COALESCE(json_extract(o.payload_json, '$.aliases'), '[]')) AS alias
+           WHERE alias.value = ?
+         )
+      ORDER BY o.object_key
+      LIMIT 21
+    `).all(normalized, normalized, normalized);
+        const candidates = rows.map(rowToObject);
+        if (candidates.length === 0)
+            return { identity, status: 'missing', candidates: [] };
+        if (candidates.length > 1)
+            return { identity, status: 'ambiguous', candidates };
+        const object = candidates[0];
+        const payload = object.payload ?? {};
+        const aliases = metadataStringArray(payload.aliases);
+        const matchedBy = object.fullName === normalized
+            ? 'qualified_id'
+            : stringValue(payload.sourceNativeId) === normalized
+                ? 'source_native_id'
+                : aliases.includes(normalized)
+                    ? 'alias'
+                    : 'qualified_id';
+        return { identity, status: 'resolved', matchedBy, object, candidates };
     }
     edgesForKeys(keys, hops = 1) {
         let frontier = new Set(keys.filter(Boolean));
@@ -1944,11 +2264,11 @@ function objectFromKGNode(node) {
         reviewCadence: node.reviewCadence,
         pattern: node.pattern,
         grain: node.grain,
-        entities: node.entities ?? [],
+        entities: node.entities ?? node.payload?.entities ?? [],
         declaredOutputs: node.declaredOutputs ?? [],
         outputs: node.outputs ?? [],
         outputContract: node.outputContract ?? [],
-        dimensions: node.dimensions ?? [],
+        dimensions: node.dimensions ?? node.payload?.dimensions ?? [],
         allowedFilters: node.allowedFilters ?? [],
         parameterPolicy: node.parameterPolicy ?? [],
         parameters: node.parameters ?? [],
@@ -3190,7 +3510,7 @@ async function planContextPackRoute(input) {
             plan: input.questionPlan,
             block: object,
             exactExampleMatch: hasExactExampleQuestion(input.request.question, object),
-            definitionLookup: intent === 'definition_lookup',
+            definitionLookup: intent === 'definition_lookup' && objectNameInQuestion(input.request.question, object),
         }),
         applicabilityScore: applicabilityByKey.get(object.objectKey)?.score ?? 0,
     }))
@@ -3238,7 +3558,7 @@ async function planContextPackRoute(input) {
         : undefined;
     const exactExampleMatch = exact ? hasExactExampleQuestion(input.request.question, exact) : false;
     const directCertifiedBypass = Boolean(exact && (exactExampleMatch
-        || intent === 'definition_lookup'
+        || (intent === 'definition_lookup' && objectNameInQuestion(input.request.question, exact))
         || objectNameInQuestion(input.request.question, exact)));
     const blockFitObject = exact
         ?? (contextApplicability ? input.objects.find((object) => object.objectKey === contextApplicability.objectKey) : undefined);
@@ -3248,7 +3568,8 @@ async function planContextPackRoute(input) {
             plan: input.questionPlan,
             block: blockFitObject,
             exactExampleMatch: exact ? exactExampleMatch : false,
-            definitionLookup: Boolean(exact && intent === 'definition_lookup'),
+            definitionLookup: Boolean(exact && intent === 'definition_lookup'
+                && objectNameInQuestion(input.request.question, blockFitObject)),
         })
         : undefined;
     const blockFit = rawBlockFit && blockFitObject
@@ -3635,8 +3956,14 @@ function isGeneratedMetadataIntent(intent) {
 function findExactCertifiedObject(question, intent, objects) {
     const candidates = objects.filter((object) => isCertifiedMetadataObject(object));
     if (intent === 'definition_lookup') {
-        return candidates.find((object) => object.objectType === 'dql_term' || object.objectType === 'business_view')
-            ?? candidates.find((object) => object.objectType === 'dql_block' && objectNameInQuestion(question, object));
+        // A definition-shaped sentence is not itself evidence of a match. Small
+        // catalogs often return every certified term; selecting the first one made
+        // unrelated questions (for example weather) look governed. Prefer an
+        // explicitly named/example block, then require the term/view name itself.
+        return candidates.find((object) => object.objectType === 'dql_block'
+            && (hasExactExampleQuestion(question, object) || objectNameInQuestion(question, object)))
+            ?? candidates.find((object) => (object.objectType === 'dql_term' || object.objectType === 'business_view')
+                && objectNameInQuestion(question, object));
     }
     const namedExact = candidates.find((object) => object.objectType === 'dql_block' &&
         objectNameInQuestion(question, object) &&
@@ -5555,6 +5882,32 @@ function searchableMetadataPayload(payload) {
     visit(payload, 0);
     return tokens.join(' ');
 }
+const VECTOR_EXCLUDED_OBJECT_TYPES = new Set([
+    ...COLUMN_OBJECT_TYPES,
+    'skill',
+    'runtime_value',
+]);
+function isVectorIndexObject(object) {
+    return !VECTOR_EXCLUDED_OBJECT_TYPES.has(object.objectType);
+}
+function metadataVectorText(object) {
+    return [
+        object.name,
+        object.fullName ?? '',
+        object.description ?? '',
+        object.domain ?? '',
+        object.owner ?? '',
+        searchableMetadataPayload(object.payload ?? {}),
+    ].filter(Boolean).join('\n').slice(0, 16_000);
+}
+function encodeFloat32Vector(vector) {
+    const values = Float32Array.from(vector);
+    return Buffer.from(values.buffer, values.byteOffset, values.byteLength);
+}
+function decodeFloat32Vector(blob) {
+    const bytes = blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength);
+    return new Float32Array(bytes);
+}
 function rowToObject(row) {
     return {
         objectKey: row.object_key,