@duckcodeailabs/dql-agent 1.9.5 → 1.10.1

package/dist/metadata/catalog.js

@@ -11,20 +11,21 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { createRequire } from 'node:module';
 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 { buildBlockBusinessFingerprint, buildBlockSqlFingerprints } from './block-fingerprints.js';
+import { buildManifest, buildManifestKnowledgeGraph, loadDomainPackageRegistry, loadManifestKnowledgeSkills, loadProjectConfig, parseContractRef, resolveDataLexManifestPath, resolveDbtManifestPath, resolveSemanticLayerWithDiagnostics, extractColumnLineage, normalizeDqlArtifactReference, composeEffectiveTrust, normalizeMetricCapabilityContract, } 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';
 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,
@@ -689,6 +835,7 @@ export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer, skil
     addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges, diagnostics);
     addBlockDependencyEdges(manifest, edges);
     addBlockOutputLineageObjects(manifest, objects, edges);
+    addCertifiedBlockAnalyticalCapabilities(objects);
     // Manifest v3 is the unified DQL runtime. DataLex is migration input only;
     // retaining it here would reintroduce a second analytical source of truth.
     if (manifest.manifestVersion !== 3) {
@@ -732,6 +879,171 @@ export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer, skil
     snapshot.fingerprint = fingerprintSnapshot(snapshot);
     return snapshot;
 }
+/**
+ * Upgrade only fully declared certified blocks into RFC 0005 capabilities.
+ * Local/display-name matching is intentionally insufficient: every reusable
+ * metric, grain, dimension/filter, and output role must bind exactly to the
+ * already-normalized semantic capability in this immutable snapshot.
+ *
+ * Acceptance: CONTRACT-002, AGT-018.
+ */
+function addCertifiedBlockAnalyticalCapabilities(objects) {
+    const semanticCapabilities = [...objects.values()].flatMap((object) => {
+        if (object.objectType !== "semantic_metric")
+            return [];
+        const capability = normalizeMetricCapabilityContract(object.payload?.analyticalCapability);
+        if (!capability)
+            return [];
+        const payload = object.payload ?? {};
+        return [
+            {
+                object,
+                capability,
+                exactRefs: new Set(uniqueNonBlank([
+                    capability.metricId,
+                    object.objectKey,
+                    object.fullName,
+                    stringValue(payload.qualifiedId),
+                    stringValue(payload.sourceNativeId),
+                    ...metadataStringArray(payload.aliases),
+                ])),
+            },
+        ];
+    });
+    for (const block of objects.values()) {
+        if (block.objectType !== "dql_block" || block.status !== "certified")
+            continue;
+        const payload = block.payload ?? {};
+        const metricRefs = uniqueNonBlank([
+            ...metadataStringArray(payload.metricRefs),
+        ]);
+        if (metricRefs.length !== 1)
+            continue;
+        const metrics = semanticCapabilities.filter((candidate) => candidate.exactRefs.has(metricRefs[0]));
+        if (metrics.length !== 1)
+            continue;
+        const semantic = metrics[0];
+        const grain = stringValue(payload.grain);
+        if (!grain || !semantic.capability.resultGrainIds.includes(grain))
+            continue;
+        const groupedRefs = uniqueNonBlank([
+            ...metadataStringArray(payload.dimensions),
+            ...metadataStringArray(payload.dimensionsRef),
+        ]);
+        const filterRefs = uniqueNonBlank(metadataStringArray(payload.allowedFilters));
+        const declaredRefs = new Set([...groupedRefs, ...filterRefs]);
+        const capabilityDimensionIds = new Set(semantic.capability.dimensions.map((item) => item.dimensionId));
+        const capabilityTimeIds = new Set(semantic.capability.timeDimensions.map((item) => item.dimensionId));
+        if ([...declaredRefs].some((id) => !capabilityDimensionIds.has(id) && !capabilityTimeIds.has(id)))
+            continue;
+        const dimensions = semantic.capability.dimensions.flatMap((dimension) => {
+            if (!declaredRefs.has(dimension.dimensionId))
+                return [];
+            const roles = dimension.supportedRoles.filter((role) => (role === "filter" && filterRefs.includes(dimension.dimensionId)) ||
+                (role === "group_by" &&
+                    groupedRefs.includes(dimension.dimensionId)) ||
+                (role === "display" &&
+                    groupedRefs.includes(dimension.dimensionId)) ||
+                (role === "rank_entity" &&
+                    payload.pattern === "ranking" &&
+                    groupedRefs.includes(dimension.dimensionId)));
+            return roles.length > 0
+                ? [{ ...dimension, supportedRoles: roles }]
+                : [];
+        });
+        if ([...declaredRefs].some((id) => capabilityDimensionIds.has(id) &&
+            !dimensions.some((dimension) => dimension.dimensionId === id)))
+            continue;
+        const timeDimensions = semantic.capability.timeDimensions.filter((dimension) => declaredRefs.has(dimension.dimensionId));
+        const outputs = analyticalBlockOutputs(payload.outputContract);
+        if (!outputs ||
+            outputs.ids.length === 0 ||
+            !outputs.kinds.includes("metric_value"))
+            continue;
+        const operations = [];
+        if (filterRefs.length > 0)
+            operations.push("filter");
+        if (groupedRefs.some((id) => capabilityDimensionIds.has(id)))
+            operations.push("group");
+        if (payload.pattern === "trend")
+            operations.push("trend");
+        if (payload.pattern === "ranking" && outputs.kinds.includes("rank"))
+            operations.push("rank");
+        if (outputs.kinds.includes("delta") ||
+            outputs.kinds.includes("percent_delta"))
+            operations.push("compare");
+        const blockId = stringValue(payload.qualifiedId) ?? block.objectKey;
+        const fingerprint = stringValue(recordPayload(payload.businessFingerprint)?.hash) ??
+            sha256(stableStringify({
+                blockId,
+                metricRefs,
+                grain,
+                groupedRefs,
+                filterRefs,
+                outputs,
+            }));
+        const capability = {
+            ...semantic.capability,
+            defaultResultGrainId: grain,
+            resultGrainIds: uniqueNonBlank([
+                grain,
+                ...dimensions.map((dimension) => dimension.entityId),
+            ]),
+            dimensions,
+            timeDimensions,
+            operations: [...new Set(operations)],
+            supportedOutputKinds: outputs.kinds,
+            declaredOutputIds: outputs.ids,
+            executionCapabilities: [
+                { route: "certified", adapterId: block.objectKey },
+            ],
+            sourceFingerprint: fingerprint.startsWith("sha256:")
+                ? fingerprint
+                : `sha256:${fingerprint}`,
+        };
+        const normalized = normalizeMetricCapabilityContract(capability);
+        if (!normalized)
+            continue;
+        objects.set(block.objectKey, {
+            ...block,
+            payload: { ...payload, analyticalCapability: normalized },
+        });
+    }
+}
+function analyticalBlockOutputs(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    const ids = [];
+    const kinds = [];
+    for (const item of value) {
+        const output = recordPayload(item);
+        const id = stringValue(output?.name);
+        const role = stringValue(output?.role)?.toLowerCase();
+        if (!id || !role)
+            return undefined;
+        const kind = role === "metric" || role === "measure" || role === "value"
+            ? "metric_value"
+            : role === "dimension" || role === "grain"
+                ? "dimension"
+                : role === "rank"
+                    ? "rank"
+                    : role === "delta"
+                        ? "delta"
+                        : role === "percent_delta"
+                            ? "percent_delta"
+                            : undefined;
+        if (!kind)
+            return undefined;
+        ids.push(id);
+        kinds.push(kind);
+    }
+    return { ids: uniqueNonBlank(ids), kinds: [...new Set(kinds)] };
+}
+function recordPayload(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
 /**
  * Manifest graph v2 intentionally omits verbose objects and edges. Snapshot
  * construction rematerializes that compiler graph once, then persists the
@@ -836,8 +1148,16 @@ function addManifestKnowledgeGraph(manifest, objects, edges) {
             sourceSystem: 'DQL compiled cross-domain policy',
             payload: compactObject(route),
         });
-        addMetadataEdge(edges, 'cross_domain_route', keyByGraphId.get(`domain::${route.providerDomainId}`) ?? `domain:${route.providerDomainId}`, objectKey, { state: route.state, reasonCodes: route.reasonCodes });
-        addMetadataEdge(edges, 'cross_domain_route', objectKey, keyByGraphId.get(`domain::${route.consumerDomainId}`) ?? `domain:${route.consumerDomainId}`, { state: route.state, reasonCodes: route.reasonCodes });
+        addMetadataEdge(edges, "cross_domain_route", keyByGraphId.get(`domain::${route.providerDomainId}`) ??
+            `domain:${route.providerDomainId}`, objectKey, {
+            state: route.state,
+            reasonCodes: route.reasonCodes,
+        });
+        addMetadataEdge(edges, "cross_domain_route", objectKey, keyByGraphId.get(`domain::${route.consumerDomainId}`) ??
+            `domain:${route.consumerDomainId}`, {
+            state: route.state,
+            reasonCodes: route.reasonCodes,
+        });
     }
     for (const edge of graph.edges ?? []) {
         const fromKey = keyByGraphId.get(edge.from) ?? edge.from;
@@ -1036,6 +1356,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 +1521,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 +1559,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 +1569,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 +1601,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 +1644,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 +1668,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 +1690,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 +1730,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 +1751,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 +1787,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 +2014,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 +2438,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 ?? [],
@@ -2087,7 +2581,8 @@ function addSkillObjects(skills, objects, edges) {
             domain: skill.domain,
             domains: skill.domains ?? [],
             modelAreaRefs: skill.modelAreaRefs ?? [],
-            status: skill.status ?? 'active',
+            status: skill.status ?? "active",
+            analyticalPolicy: skill.analyticalPolicy,
             bodyHash,
         }));
         const objectKey = `skill:${identity}`;
@@ -2122,6 +2617,7 @@ function addSkillObjects(skills, objects, edges) {
                 examples: skill.examples ?? [],
                 sourceRefs: skill.sourceRefs ?? [],
                 vocabulary: skill.vocabulary,
+                analyticalPolicy: skill.analyticalPolicy,
                 bodyHash,
                 sourceFingerprint,
                 isStarter: skill.isStarter,
@@ -3190,7 +3686,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 +3734,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 +3744,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 +4132,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 +6058,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,
@@ -5907,13 +6436,22 @@ function skillFromMetadataObject(object) {
         examples: stringArrayPayload(payload.examples),
         sourceRefs: stringArrayPayload(payload.sourceRefs),
         vocabulary: stringRecordPayload(payload.vocabulary),
-        body: '',
-        sourcePath: object.sourcePath ?? '',
+        analyticalPolicy: skillAnalyticalPolicyPayload(payload.analyticalPolicy),
+        body: "",
+        sourcePath: object.sourcePath ?? "",
         isStarter: payload.isStarter === true,
     };
 }
 function localContextSkillFromParsed(skill, object) {
     const guidance = skill.body.slice(0, 4_000);
+    const sourceHash = stringPayload(object.payload?.sourceFingerprint);
+    const policy = skill.analyticalPolicy && sourceHash
+        ? {
+            policyId: `${skill.qualifiedId ?? skill.id}#analytical`,
+            sourceHash,
+            ...skill.analyticalPolicy,
+        }
+        : undefined;
     return {
         objectKey: object.objectKey,
         id: skill.id,
@@ -5933,6 +6471,7 @@ function localContextSkillFromParsed(skill, object) {
         requiredFilters: [...(skill.requiredFilters ?? [])],
         clarifyWhen: [...(skill.clarifyWhen ?? [])],
         vocabulary: { ...skill.vocabulary },
+        ...(policy ? { analyticalPolicy: policy } : {}),
         guidance,
         guidanceTruncated: guidance.length < skill.body.length,
         sourceRefs: [...(skill.sourceRefs ?? [])],
@@ -5940,6 +6479,38 @@ function localContextSkillFromParsed(skill, object) {
         sourcePath: object.sourcePath,
     };
 }
+function skillAnalyticalPolicyPayload(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const completenessPolicy = stringPayload(record.completenessPolicy);
+    const comparisonAlignment = stringPayload(record.comparisonAlignment);
+    const defaultRankingPeriod = stringPayload(record.defaultRankingPeriod);
+    const policy = {
+        metricIds: stringArrayPayload(record.metricIds),
+        timeRole: stringPayload(record.timeRole),
+        calendarId: stringPayload(record.calendarId),
+        timezone: stringPayload(record.timezone),
+        completenessPolicy: completenessPolicy === "partial_current" ||
+            completenessPolicy === "latest_complete" ||
+            completenessPolicy === "closed_period"
+            ? completenessPolicy
+            : undefined,
+        comparisonAlignment: comparisonAlignment === "elapsed_period" ||
+            comparisonAlignment === "calendar_period" ||
+            comparisonAlignment === "fiscal_period"
+            ? comparisonAlignment
+            : undefined,
+        defaultRankingPeriod: defaultRankingPeriod === "current" ||
+            defaultRankingPeriod === "comparison"
+            ? defaultRankingPeriod
+            : undefined,
+        narrativeGuidance: stringArrayPayload(record.narrativeGuidance),
+    };
+    return Object.values(policy).some((item) => Array.isArray(item) ? item.length > 0 : Boolean(item))
+        ? policy
+        : undefined;
+}
 function stringPayload(value) {
     return typeof value === 'string' && value.trim() ? value : undefined;
 }