@duckcodeailabs/dql-agent 1.10.0 → 1.10.2

package/dist/metadata/catalog.js

@@ -11,10 +11,10 @@ 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 { domainContextSearchDomains } from '../domain-context.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';
@@ -835,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) {
@@ -878,6 +879,205 @@ 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) {
+    // Existing certified blocks can carry the pre-ID-001 domain-scoped member
+    // identities. Canonicalize those aliases only when exactly one semantic
+    // object owns them; repeated leaf aliases intentionally fail closed.
+    const semanticIdentityTargets = new Map();
+    for (const object of objects.values()) {
+        if (!object.objectType.startsWith('semantic_'))
+            continue;
+        const payload = object.payload ?? {};
+        const canonicalIdentity = object.fullName ?? object.name;
+        for (const identity of uniqueNonBlank([
+            canonicalIdentity,
+            stringValue(payload.qualifiedId),
+            stringValue(payload.registryQualifiedId),
+            stringValue(payload.sourceNativeId),
+            ...metadataStringArray(payload.aliases),
+        ])) {
+            const targets = semanticIdentityTargets.get(identity) ?? new Set();
+            targets.add(canonicalIdentity);
+            semanticIdentityTargets.set(identity, targets);
+        }
+    }
+    const canonicalizeSemanticRef = (identity) => {
+        const targets = semanticIdentityTargets.get(identity);
+        if (!targets)
+            return identity;
+        return targets.size === 1 ? [...targets][0] : undefined;
+    };
+    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 authoredGrain = stringValue(payload.grain);
+        const grain = authoredGrain ? canonicalizeSemanticRef(authoredGrain) : undefined;
+        if (!grain || !semantic.capability.resultGrainIds.includes(grain))
+            continue;
+        const authoredGroupedRefs = uniqueNonBlank([
+            ...metadataStringArray(payload.dimensions),
+            ...metadataStringArray(payload.dimensionsRef),
+        ]);
+        const authoredFilterRefs = uniqueNonBlank(metadataStringArray(payload.allowedFilters));
+        const groupedRefs = authoredGroupedRefs.map(canonicalizeSemanticRef);
+        const filterRefs = authoredFilterRefs.map(canonicalizeSemanticRef);
+        if (groupedRefs.some((ref) => !ref) || filterRefs.some((ref) => !ref))
+            continue;
+        const canonicalGroupedRefs = groupedRefs.filter((ref) => Boolean(ref));
+        const canonicalFilterRefs = filterRefs.filter((ref) => Boolean(ref));
+        const declaredRefs = new Set([...canonicalGroupedRefs, ...canonicalFilterRefs]);
+        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" && canonicalFilterRefs.includes(dimension.dimensionId)) ||
+                (role === "group_by" &&
+                    canonicalGroupedRefs.includes(dimension.dimensionId)) ||
+                (role === "display" &&
+                    canonicalGroupedRefs.includes(dimension.dimensionId)) ||
+                (role === "rank_entity" &&
+                    payload.pattern === "ranking" &&
+                    canonicalGroupedRefs.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 (canonicalFilterRefs.length > 0)
+            operations.push("filter");
+        if (canonicalGroupedRefs.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: canonicalGroupedRefs,
+                filterRefs: canonicalFilterRefs,
+                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
@@ -982,8 +1182,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;
@@ -2356,6 +2564,9 @@ function isQualifiedDqlModelingNode(node) {
 }
 function qualifiedIdentityFromKGNode(node) {
     const payload = node.payload ?? {};
+    const registryIdentity = stringValue(payload.registryQualifiedId);
+    if (registryIdentity)
+        return registryIdentity;
     const explicit = stringValue(payload.qualifiedId);
     if (explicit)
         return explicit;
@@ -2407,7 +2618,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}`;
@@ -2442,6 +2654,7 @@ function addSkillObjects(skills, objects, edges) {
                 examples: skill.examples ?? [],
                 sourceRefs: skill.sourceRefs ?? [],
                 vocabulary: skill.vocabulary,
+                analyticalPolicy: skill.analyticalPolicy,
                 bodyHash,
                 sourceFingerprint,
                 isStarter: skill.isStarter,
@@ -6260,13 +6473,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,
@@ -6286,6 +6508,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 ?? [])],
@@ -6293,6 +6516,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;
 }