@duckcodeailabs/dql-agent 1.9.5 → 1.10.1

package/dist/kg/build.js

@@ -8,8 +8,9 @@
  *
  * The output is intentionally flat — caller passes it to `KGStore.rebuild()`.
  */
-import { trustLabelIdForStatus } from '@duckcodeailabs/dql-core';
-import { buildBlockBusinessFingerprint, buildBlockSqlFingerprints } from '../metadata/block-fingerprints.js';
+import { createHash } from "node:crypto";
+import { trustLabelIdForStatus } from "@duckcodeailabs/dql-core";
+import { buildBlockBusinessFingerprint, buildBlockSqlFingerprints, } from "../metadata/block-fingerprints.js";
 export function buildKGFromManifest(manifest) {
     const nodes = [];
     const edges = [];
@@ -86,6 +87,19 @@ export function buildKGFromManifest(manifest) {
                 sources: [...(block.tableDependencies ?? []), ...(block.rawTableRefs ?? [])],
                 sourceSystems: block.sourceSystems,
             }),
+            payload: {
+                qualifiedId: `${block.domain ?? 'global'}::block::${block.name}`,
+                localId: block.name,
+                aliases: [block.name],
+                metricRefs: [
+                    ...new Set([
+                        ...(block.metricRef ? [block.metricRef] : []),
+                        ...(block.metricsRef ?? []),
+                        ...(block.metricRefs ?? []),
+                    ]),
+                ],
+                dimensionsRef: block.dimensionsRef ?? [],
+            },
             datalexContract: block.datalexContract,
             businessRules: block.businessRules ?? block.invariants,
             caveats: block.caveats,
@@ -595,6 +609,8 @@ export function buildKGFromSemanticLayer(layer) {
     if (!layer)
         return { nodes, edges };
     const semanticMeasures = layer.listMeasures();
+    const semanticDimensions = layer.listDimensions();
+    const semanticModels = layer.listSemanticModels();
     const measuresByName = new Map();
     for (const measure of semanticMeasures) {
         for (const key of [measure.name, qualifiedSemanticName(measure.cube, measure.name)]) {
@@ -605,6 +621,27 @@ export function buildKGFromSemanticLayer(layer) {
         }
     }
     for (const metric of layer.listMetrics()) {
+        const model = semanticModels.find((candidate) => candidate.name === metric.cube);
+        const availableDimensions = semanticDimensions.filter((dimension) => !metric.cube || dimension.cube === metric.cube);
+        // MetricFlow may deduplicate same-named domain dimensions in its flattened
+        // registry. The semantic model retains the authoritative per-model shape,
+        // so use it to recover dimensions/time even when listDimensions() only
+        // exposes another model's copy of the shared concept.
+        const modelDimensionNames = Array.from(new Set([
+            ...(model?.dimensions ?? []),
+            ...(model?.timeDimensions ?? []),
+            ...availableDimensions.map((dimension) => dimension.name),
+        ]));
+        const qualifiedDimensions = modelDimensionNames.map((name) => {
+            const dimension = availableDimensions.find((candidate) => candidate.name === name);
+            return stringValue(semanticIdentityPayload('dimension', dimension ?? {
+                name,
+                domain: metric.domain ?? model?.domain,
+                cube: metric.cube,
+            }).qualifiedId) ?? qualifiedSemanticName(metric.cube, name);
+        });
+        const hasTimeDimension = (model?.timeDimensions.length ?? 0) > 0
+            || availableDimensions.some((dimension) => dimension.isTimeDimension || dimension.type === 'date');
         const backingCandidates = semanticMetricBackingMeasureNames(metric)
             .flatMap((name) => measuresByName.get(name) ?? [])
             .filter((measure, index, values) => values.indexOf(measure) === index);
@@ -623,6 +660,12 @@ export function buildKGFromSemanticLayer(layer) {
         const nonAdditiveDimensions = backingMeasures
             .map((measure) => measure.nonAdditiveDimension)
             .filter((value) => Boolean(value));
+        const analyticalCapability = buildSemanticMetricCapability({
+            layer,
+            metric,
+            model,
+            backingMeasures,
+        });
         const nodeId = `metric:${qualifiedSemanticName(metric.cube, metric.name)}`;
         nodes.push({
             nodeId,
@@ -643,6 +686,7 @@ export function buildKGFromSemanticLayer(layer) {
                 nonAdditiveDimensions.length > 0 ? 'non-additive: semantic runtime required' : '',
             ].filter(Boolean).join('\n') || undefined,
             payload: {
+                ...semanticIdentityPayload('metric', metric),
                 metricType: metric.metricType,
                 aggregation: metric.aggregation,
                 table: metric.table,
@@ -651,6 +695,12 @@ export function buildKGFromSemanticLayer(layer) {
                 backingMeasureNames: backingMeasures.map((measure) => measure.name),
                 nonAdditiveMeasures,
                 nonAdditiveDimensions,
+                dimensions: qualifiedDimensions,
+                entities: model?.entities ?? [],
+                timeGrains: hasTimeDimension
+                    ? ["day", "week", "month", "quarter", "year"]
+                    : [],
+                analyticalCapability,
             },
             sourceTier: 'semantic_layer',
             certification: certificationFromStatus(metric.status),
@@ -662,7 +712,6 @@ export function buildKGFromSemanticLayer(layer) {
         if (metric.cube)
             edges.push({ src: nodeId, dst: `semantic_model:${metric.cube}`, kind: 'depends_on' });
     }
-    const semanticDimensions = layer.listDimensions();
     // PERF-001: dbt fallback semantics may expose every physical column as a
     // synthetic dimension. At enterprise scale the model nodes already retain
     // their bounded column lists; duplicating 300k dimensions into KG + FTS is
@@ -681,12 +730,30 @@ export function buildKGFromSemanticLayer(layer) {
             tags: dimension.tags ?? [],
             ...businessMetadataFromRaw(dimension.source?.extra?.raw),
             llmContext: [
-                dimension.label ? `label: ${dimension.label}` : '',
-                dimension.type ? `type: ${dimension.type}` : '',
-                dimension.table ? `table: ${dimension.table}` : '',
-                dimension.sql ? `sql: ${dimension.sql}` : '',
-            ].filter(Boolean).join('\n') || undefined,
-            sourceTier: 'semantic_layer',
+                dimension.label ? `label: ${dimension.label}` : "",
+                dimension.type ? `type: ${dimension.type}` : "",
+                dimension.table ? `table: ${dimension.table}` : "",
+                dimension.sql ? `sql: ${dimension.sql}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n") || undefined,
+            payload: {
+                ...semanticIdentityPayload("dimension", dimension),
+                table: dimension.table,
+                expression: dimension.expr ?? dimension.sql,
+                dimensionType: dimension.type,
+                entityLink: dimension.entityLink,
+                qualifiedName: dimension.qualifiedName,
+                isTimeDimension: dimension.isTimeDimension,
+                ...(isTimeDimension(dimension)
+                    ? {
+                        granularities: dimension.granularities,
+                        primaryTime: dimension.primaryTime,
+                        timeRole: authoredTimeRole(dimension),
+                    }
+                    : {}),
+            },
+            sourceTier: "semantic_layer",
             certification: certificationFromStatus(dimension.status),
             provenance: dimension.source?.provider === 'dbt'
                 ? `dbt ${dimension.source.objectType}`
@@ -717,6 +784,7 @@ export function buildKGFromSemanticLayer(layer) {
                 measure.nonAdditiveDimension ? `non-additive dimension: ${JSON.stringify(measure.nonAdditiveDimension)}` : '',
             ].filter(Boolean).join('\n') || undefined,
             payload: {
+                ...semanticIdentityPayload('measure', measure),
                 aggregation: measure.agg,
                 table: measure.table,
                 expression: measure.expr,
@@ -751,6 +819,7 @@ export function buildKGFromSemanticLayer(layer) {
                 entity.table ? `table: ${entity.table}` : '',
                 entity.expr ? `expr: ${entity.expr}` : '',
             ].filter(Boolean).join('\n') || undefined,
+            payload: semanticIdentityPayload('entity', entity),
             sourceTier: 'semantic_layer',
             certification: certificationFromStatus(semanticObjectStatus(entity)),
             provenance: entity.source?.provider === 'dbt'
@@ -782,6 +851,7 @@ export function buildKGFromSemanticLayer(layer) {
                 model.dimensions.length ? `dimensions: ${model.dimensions.join(', ')}` : '',
                 model.timeDimensions.length ? `time_dimensions: ${model.timeDimensions.join(', ')}` : '',
             ].filter(Boolean).join('\n') || undefined,
+            payload: semanticIdentityPayload('model', model),
             sourceTier: 'semantic_layer',
             certification: certificationFromStatus(semanticObjectStatus(model)),
             provenance: model.source?.provider === 'dbt'
@@ -811,6 +881,7 @@ export function buildKGFromSemanticLayer(layer) {
                 query.timeDimension ? `time_dimension: ${query.timeDimension}` : '',
                 query.granularity ? `granularity: ${query.granularity}` : '',
             ].filter(Boolean).join('\n') || undefined,
+            payload: semanticIdentityPayload('saved_query', query),
             sourceTier: 'semantic_layer',
             certification: certificationFromStatus(semanticObjectStatus(query)),
             provenance: query.source?.provider === 'dbt'
@@ -825,6 +896,211 @@ export function buildKGFromSemanticLayer(layer) {
     }
     return { nodes, edges };
 }
+/**
+ * Project one semantic metric into the execution-neutral capability contract.
+ * Every admitted fact comes from the semantic registry itself. An incomplete
+ * model is intentionally left without a capability instead of being completed
+ * from names or descriptions.
+ *
+ * Acceptance: CONTRACT-002, AGT-018.
+ */
+function buildSemanticMetricCapability(input) {
+    const { layer, metric, model, backingMeasures } = input;
+    if (!model || !metric.cube || model.name !== metric.cube)
+        return undefined;
+    const cube = typeof layer.getCube === "function"
+        ? layer.getCube(metric.cube)
+        : undefined;
+    const registryDimensions = layer
+        .listDimensions()
+        .filter((dimension) => dimension.cube === metric.cube);
+    const cubeDimensions = cube
+        ? [...cube.dimensions, ...cube.timeDimensions]
+        : [];
+    const dimensionsByName = new Map();
+    for (const dimension of [...registryDimensions, ...cubeDimensions]) {
+        if (!dimensionsByName.has(dimension.name))
+            dimensionsByName.set(dimension.name, dimension);
+    }
+    const declaredDimensionNames = [
+        ...new Set([...model.dimensions, ...model.timeDimensions]),
+    ];
+    if (declaredDimensionNames.some((name) => !dimensionsByName.has(name)))
+        return undefined;
+    const metricIdentity = semanticIdentityPayload("metric", metric);
+    const metricId = stringValue(metricIdentity.qualifiedId);
+    const modelId = stringValue(semanticIdentityPayload("model", model).qualifiedId);
+    if (!metricId || !modelId)
+        return undefined;
+    const scopedEntities = layer
+        .listEntities()
+        .filter((entity) => entity.cube === metric.cube && model.entities.includes(entity.name));
+    const primaryEntities = scopedEntities.filter((entity) => entity.type === "primary");
+    if (primaryEntities.length > 1)
+        return undefined;
+    const primaryEntity = primaryEntities[0];
+    const primaryEntityId = primaryEntity
+        ? stringValue(semanticIdentityPayload("entity", primaryEntity).qualifiedId)
+        : modelId;
+    if (!primaryEntityId)
+        return undefined;
+    const entityIds = new Map(scopedEntities.flatMap((entity) => {
+        const id = stringValue(semanticIdentityPayload("entity", entity).qualifiedId);
+        return id ? [[entity.name, id]] : [];
+    }));
+    const timeNameSet = new Set(model.timeDimensions);
+    const normalDimensions = [];
+    const timeDimensions = [];
+    const explicitDefaultNames = new Set([
+        metric.aggTimeDimension,
+        cube?.defaultTimeDimension,
+        ...backingMeasures.map((measure) => measure.aggTimeDimension),
+        ...[...dimensionsByName.values()]
+            .filter((dimension) => isTimeDimension(dimension) && dimension.primaryTime)
+            .map((dimension) => dimension.name),
+    ].filter((value) => Boolean(value?.trim())));
+    for (const name of declaredDimensionNames) {
+        const dimension = dimensionsByName.get(name);
+        const dimensionId = stringValue(semanticIdentityPayload("dimension", dimension).qualifiedId);
+        if (!dimensionId)
+            return undefined;
+        const entityId = dimension.entityLink
+            ? entityIds.get(dimension.entityLink)
+            : primaryEntityId;
+        if (!entityId)
+            return undefined;
+        const timeDimension = timeNameSet.has(name) || isTimeDimension(dimension);
+        if (timeDimension) {
+            const supportedGrains = isTimeDimension(dimension)
+                ? [...new Set(dimension.granularities ?? [])]
+                : [];
+            if (supportedGrains.length === 0)
+                return undefined;
+            const defaultFor = explicitDefaultNames.has(name) ||
+                (explicitDefaultNames.size === 0 && model.timeDimensions.length === 1)
+                ? ["scalar", "trend", "comparison"]
+                : undefined;
+            timeDimensions.push({
+                dimensionId,
+                role: authoredTimeRole(dimension) ?? dimensionId,
+                supportedGrains,
+                ...(defaultFor ? { defaultFor: [...defaultFor] } : {}),
+            });
+            continue;
+        }
+        // Dimensions declared on the metric's own semantic model remain at the
+        // model's primary grain. Cross-model dimensions require a separately
+        // normalized, governed relationship path and are not admitted here.
+        if (entityId !== primaryEntityId)
+            return undefined;
+        normalDimensions.push({
+            dimensionId,
+            entityId,
+            supportedRoles: ["group_by", "filter", "display", "rank_entity"],
+        });
+    }
+    const nonAdditiveDimensionIds = backingMeasures.flatMap((measure) => {
+        const raw = measure.nonAdditiveDimension?.name;
+        if (typeof raw !== "string")
+            return [];
+        const dimension = dimensionsByName.get(raw);
+        const id = dimension &&
+            stringValue(semanticIdentityPayload("dimension", dimension).qualifiedId);
+        return id ? [id] : [];
+    });
+    const aggregation = metric.aggregation ?? metric.type ?? metric.metricType;
+    if (!aggregation)
+        return undefined;
+    const completenessPolicy = authoredCompletenessPolicy(metric);
+    const measureIds = backingMeasures.flatMap((measure) => {
+        const id = stringValue(semanticIdentityPayload("measure", measure).qualifiedId);
+        return id ? [id] : [];
+    });
+    const additive = ["sum", "count"].includes(aggregation.toLowerCase());
+    const capabilityWithoutFingerprint = {
+        metricId,
+        semanticModelId: modelId,
+        measureIds: measureIds.length > 0 ? [...new Set(measureIds)] : [metricId],
+        primaryEntityId,
+        defaultResultGrainId: primaryEntityId,
+        resultGrainIds: [
+            ...new Set([
+                primaryEntityId,
+                ...normalDimensions.map((dimension) => dimension.entityId),
+            ]),
+        ],
+        aggregation,
+        additivity: {
+            entities: additive ? "additive" : "non_additive",
+            time: nonAdditiveDimensionIds.length > 0
+                ? "semi_additive"
+                : additive
+                    ? "additive"
+                    : "non_additive",
+            ...(nonAdditiveDimensionIds.length > 0
+                ? { nonAdditiveDimensionIds: [...new Set(nonAdditiveDimensionIds)] }
+                : {}),
+        },
+        dimensions: normalDimensions,
+        timeDimensions,
+        ...(completenessPolicy
+            ? { freshness: { defaultCompletenessPolicy: completenessPolicy } }
+            : {}),
+        // The current native semantic adapter supports filtering, grouping,
+        // time-series grouping, ordering, and limiting. Multi-period arithmetic is
+        // withheld until the AC3 executable graph ships.
+        operations: ["filter", "group", "trend", "rank"],
+        supportedOutputKinds: ["dimension", "metric_value", "rank"],
+        executionCapabilities: [
+            {
+                route: "semantic",
+                adapterId: metric.source?.provider === "dbt" ? "metricflow" : "semantic-native",
+            },
+        ],
+    };
+    return {
+        ...capabilityWithoutFingerprint,
+        sourceFingerprint: `sha256:${createHash("sha256").update(stableJson(capabilityWithoutFingerprint)).digest("hex")}`,
+    };
+}
+function isTimeDimension(dimension) {
+    return Boolean(dimension.isTimeDimension ||
+        dimension.source?.objectType === "time_dimension");
+}
+function authoredTimeRole(dimension) {
+    const raw = recordValue(dimension.source?.extra?.raw);
+    const meta = recordValue(raw.meta);
+    const dql = recordValue(meta.dql);
+    return (stringValue(dql.time_role) ??
+        stringValue(dql.timeRole) ??
+        stringValue(meta.time_role) ??
+        stringValue(meta.timeRole));
+}
+function authoredCompletenessPolicy(metric) {
+    const raw = recordValue(metric.source?.extra?.raw);
+    const meta = recordValue(raw.meta);
+    const dql = recordValue(meta.dql);
+    const value = stringValue(dql.completeness_policy) ??
+        stringValue(dql.completenessPolicy) ??
+        stringValue(meta.completeness_policy) ??
+        stringValue(meta.completenessPolicy);
+    return value === "partial_current" ||
+        value === "latest_complete" ||
+        value === "closed_period"
+        ? value
+        : undefined;
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+        .join(",")}}`;
+}
 function semanticMetricBackingMeasureNames(metric) {
     const names = new Set([metric.name, qualifiedSemanticName(metric.cube, metric.name)]);
     const add = (value) => {
@@ -846,6 +1122,50 @@ function semanticMetricBackingMeasureNames(metric) {
 function qualifiedSemanticName(cube, name) {
     return cube ? `${cube}.${name}` : name;
 }
+/**
+ * Canonical semantic registry identity carried into the immutable search
+ * snapshot. A source-authored `meta.concept_id` wins; otherwise DQL derives a
+ * deterministic domain-qualified ID while preserving native dbt IDs as exact
+ * aliases. This is additive: legacy object keys remain stable during rollout.
+ *
+ * Acceptance: ID-001, CTX-005, AGT-013.
+ */
+function semanticIdentityPayload(kind, item) {
+    const raw = recordValue(item.source?.extra?.raw);
+    const meta = recordValue(raw.meta);
+    const dqlMeta = recordValue(meta.dql);
+    const authoredConceptId = stringValue(meta.concept_id)
+        ?? stringValue(meta.conceptId)
+        ?? stringValue(dqlMeta.concept_id)
+        ?? stringValue(dqlMeta.conceptId);
+    const domain = normalizeSemanticIdentityPart(item.domain ?? item.cube ?? 'uncategorized');
+    const localName = normalizeSemanticIdentityPart(item.name);
+    const qualifiedId = authoredConceptId
+        ?? (kind === 'metric'
+            ? `semantic:${domain}:${localName}`
+            : `semantic:${domain}:${kind}:${localName}`);
+    const sourceNativeId = stringValue(item.source?.objectId);
+    const aliases = Array.from(new Set([
+        item.name,
+        item.label,
+        item.cube ? qualifiedSemanticName(item.cube, item.name) : undefined,
+        sourceNativeId,
+    ].filter((value) => Boolean(value?.trim()))));
+    return {
+        qualifiedId,
+        localId: item.name,
+        sourceNativeId,
+        aliases,
+    };
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function normalizeSemanticIdentityPart(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '_').replace(/^_+|_+$/g, '') || 'unknown';
+}
 function semanticSourcePath(extra) {
     const path = extra?.path ?? (extra?.raw && typeof extra.raw === 'object' ? extra.raw.original_file_path : undefined);
     return typeof path === 'string' ? path : undefined;