@duckcodeailabs/dql-cli 1.10.2 → 1.10.3

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckcodeailabs/dql-cli",
-  "version": "1.10.2",
+  "version": "1.10.3",
   "description": "Public CLI for parsing, formatting, testing, and certifying DQL blocks",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,15 +25,15 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.104.2",
-    "@duckcodeailabs/dql-agent": "^1.10.2",
-    "@duckcodeailabs/dql-compiler": "^1.10.2",
-    "@duckcodeailabs/dql-connectors": "^1.10.2",
-    "@duckcodeailabs/dql-core": "^1.10.2",
-    "@duckcodeailabs/dql-governance": "^1.10.2",
-    "@duckcodeailabs/dql-mcp": "^1.10.2",
-    "@duckcodeailabs/dql-notebook": "^1.10.2",
-    "@duckcodeailabs/dql-project": "^1.10.2",
-    "@duckcodeailabs/dql-slack": "^1.10.2",
+    "@duckcodeailabs/dql-agent": "^1.10.3",
+    "@duckcodeailabs/dql-compiler": "^1.10.3",
+    "@duckcodeailabs/dql-connectors": "^1.10.3",
+    "@duckcodeailabs/dql-core": "^1.10.3",
+    "@duckcodeailabs/dql-governance": "^1.10.3",
+    "@duckcodeailabs/dql-mcp": "^1.10.3",
+    "@duckcodeailabs/dql-notebook": "^1.10.3",
+    "@duckcodeailabs/dql-project": "^1.10.3",
+    "@duckcodeailabs/dql-slack": "^1.10.3",
     "isomorphic-git": "^1.27.0",
     "js-yaml": "^4.1.0",
     "node-cron": "^3.0.3",

package/dist/semantic-runtime.d.ts

@@ -55,6 +55,50 @@ export interface SemanticRuntimeQueryRequest {
     savedQuery?: string;
     engine?: 'native' | 'metricflow' | SemanticRuntimeAdapterId;
 }
+export type SemanticRuntimeBindingRole = 'dimension' | 'time_dimension' | 'filter' | 'order_by';
+export interface SemanticRuntimeBinding {
+    role: SemanticRuntimeBindingRole;
+    /** Stable DQL/model-scoped identity shown to the analyst. */
+    authoringReference: string;
+    /** Exact dunder-qualified member sent to MetricFlow or dbt Cloud. */
+    runtimeReference: string;
+    /** Metric-relative entity path selected ahead of the member's own qualified name. */
+    entityPath: string[];
+    status: 'resolved' | 'ambiguous';
+}
+export interface SemanticRuntimePathCandidate {
+    /** Stable evidence identity used by Ask clarification and retry. */
+    id: string;
+    label: string;
+    description: string;
+    authoringReference: string;
+    runtimeReference: string;
+    entityPath: string[];
+    /** DQL-safe reference that preserves the model identity and the selected path. */
+    selectionReference: string;
+}
+export interface SemanticRuntimeTraceStep {
+    id: 'resolve_members' | 'bind_entity_paths' | 'compile_semantic_query' | 'execute_query';
+    label: string;
+    status: 'completed' | 'failed' | 'not_started';
+    detail: string;
+}
+export interface SemanticRuntimeTrace {
+    version: 1;
+    adapter: SemanticRuntimeAdapterId;
+    status: 'compiled' | 'ambiguous' | 'failed';
+    authoringRequest: SemanticRuntimeQueryRequest;
+    runtimeRequest?: SemanticRuntimeQueryRequest;
+    bindings: SemanticRuntimeBinding[];
+    warnings: string[];
+    steps: SemanticRuntimeTraceStep[];
+    failure?: {
+        code: 'SEMANTIC_PATH_AMBIGUOUS' | 'SEMANTIC_COMPILATION_FAILED';
+        phase: 'path_binding' | 'compilation';
+        message: string;
+        candidates?: SemanticRuntimePathCandidate[];
+    };
+}
 export interface SemanticRuntimeCompileContext {
     projectRoot: string;
     projectConfig: SemanticRuntimeProjectConfig;
@@ -78,6 +122,8 @@ export interface SemanticRuntimeCompileResult extends ComposeQueryResult {
      * for native compilation (which speaks bare names). Diagnostic only.
      */
     runtimeRequest?: SemanticRuntimeQueryRequest;
+    /** Auditable authoring → runtime bindings and compiler phases. */
+    semanticTrace: SemanticRuntimeTrace;
     /** Non-fatal advisories (e.g. a time grain clamped up to the column's base). */
     warnings?: string[];
 }
@@ -90,6 +136,26 @@ export declare class SemanticRuntimeCompilationError extends Error {
     readonly adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
     constructor(adapter: Exclude<SemanticRuntimeAdapterId, 'native'>, error: unknown);
 }
+export declare class SemanticRuntimePathAmbiguityError extends Error {
+    readonly code = "SEMANTIC_PATH_AMBIGUOUS";
+    readonly adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
+    readonly details: {
+        authoringReference: string;
+        runtimeReference: string;
+        candidates: SemanticRuntimePathCandidate[];
+    };
+    readonly semanticTrace: SemanticRuntimeTrace;
+    constructor(input: {
+        adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
+        authoringRequest: SemanticRuntimeQueryRequest;
+        runtimeRequest: SemanticRuntimeQueryRequest;
+        bindings: SemanticRuntimeBinding[];
+        warnings: string[];
+        authoringReference: string;
+        runtimeReference: string;
+        candidates: SemanticRuntimePathCandidate[];
+    });
+}
 /**
  * API-004 / AGT-001: MetricFlow requires `metric_time` whenever an input metric uses a time offset.
  * dbt stores that requirement in the metric definition, so normalize it once at
@@ -127,7 +193,27 @@ export declare function explainMissingSemanticRuntime(projectRoot: string, dbtPr
 export declare function qualifyForMetricFlow(request: SemanticRuntimeQueryRequest, semanticLayer: SemanticLayer): {
     request: SemanticRuntimeQueryRequest;
     warnings: string[];
+    bindings: SemanticRuntimeBinding[];
+};
+export declare function parseSemanticDimensionSelection(value: string): {
+    reference: string;
+    entityPath?: string[];
 };
+export declare function formatSemanticDimensionSelection(reference: string, entityPath: string[]): string;
+export declare function applySemanticPathSelection(request: SemanticRuntimeQueryRequest, authoringReference: string, entityPath: string[]): SemanticRuntimeQueryRequest;
+export declare function encodeSemanticPathEvidenceId(authoringReference: string, entityPath: string[]): string;
+export declare function decodeSemanticPathEvidenceId(value: string | undefined): {
+    authoringReference: string;
+    entityPath: string[];
+} | undefined;
+export declare function semanticPathAmbiguityFromError(input: {
+    adapter: Exclude<SemanticRuntimeAdapterId, 'native'>;
+    error: unknown;
+    authoringRequest: SemanticRuntimeQueryRequest;
+    runtimeRequest: SemanticRuntimeQueryRequest;
+    bindings: SemanticRuntimeBinding[];
+    warnings: string[];
+}): SemanticRuntimePathAmbiguityError | undefined;
 export declare function compileSemanticRuntimeQuery(request: SemanticRuntimeQueryRequest, context: SemanticRuntimeCompileContext): Promise<SemanticRuntimeCompileResult | null>;
 /**
  * AGT-013/AGT-014/SEC-004: planning selects one adapter. Compilation may not
@@ -161,5 +247,6 @@ export declare function describeRuntimeCompatibility(projectRoot: string, semant
 export declare function listRuntimeCompatibleDimensions(projectRoot: string, semanticLayer: SemanticLayer, metrics: string[], projectConfig?: SemanticRuntimeProjectConfig): Promise<Array<ReturnType<SemanticLayer['listDimensions']>[number]>>;
 export declare function semanticMetricExecutionCapability(metricName: string, semanticLayer: SemanticLayer, provider: string, runtime: SemanticRuntimeStatus): SemanticMetricExecutionCapability;
 export declare function isSemanticRuntimeError(error: unknown): boolean;
-export declare function semanticRuntimeErrorCode(error: unknown): 'SEMANTIC_RUNTIME_REQUIRED' | 'SEMANTIC_COMPILATION_FAILED' | undefined;
+export declare function semanticRuntimeErrorCode(error: unknown): 'SEMANTIC_RUNTIME_REQUIRED' | 'SEMANTIC_COMPILATION_FAILED' | 'SEMANTIC_PATH_AMBIGUOUS' | undefined;
+export declare function semanticRuntimeErrorDetails(error: unknown): unknown;
 //# sourceMappingURL=semantic-runtime.d.ts.map

package/dist/semantic-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-runtime.d.ts","sourceRoot":"","sources":["../src/semantic-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"semantic-runtime.d.ts","sourceRoot":"","sources":["../src/semantic-runtime.ts"],"names":[],"mappings":"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"}

package/dist/semantic-runtime.js

@@ -21,6 +21,54 @@ export class SemanticRuntimeCompilationError extends Error {
         this.adapter = adapter;
     }
 }
+export class SemanticRuntimePathAmbiguityError extends Error {
+    code = 'SEMANTIC_PATH_AMBIGUOUS';
+    adapter;
+    details;
+    semanticTrace;
+    constructor(input) {
+        const choices = input.candidates.map((candidate) => candidate.label).join(' or ');
+        const message = `The semantic dimension "${input.authoringReference}" is reachable through more than one governed entity path (${choices}). Choose the intended path before DQL compiles or executes the query.`;
+        super(message);
+        this.name = 'SemanticRuntimePathAmbiguityError';
+        this.adapter = input.adapter;
+        this.details = {
+            authoringReference: input.authoringReference,
+            runtimeReference: input.runtimeReference,
+            candidates: input.candidates,
+        };
+        this.semanticTrace = {
+            version: 1,
+            adapter: input.adapter,
+            status: 'ambiguous',
+            authoringRequest: input.authoringRequest,
+            runtimeRequest: input.runtimeRequest,
+            bindings: [
+                ...input.bindings.filter((binding) => binding.runtimeReference !== input.runtimeReference),
+                {
+                    role: inferSemanticBindingRole(input.authoringRequest, input.authoringReference),
+                    authoringReference: input.authoringReference,
+                    runtimeReference: input.runtimeReference,
+                    entityPath: [],
+                    status: 'ambiguous',
+                },
+            ],
+            warnings: input.warnings,
+            steps: [
+                { id: 'resolve_members', label: 'Resolve governed semantic members', status: 'completed', detail: 'Metric and dimension identities resolved from the pinned semantic snapshot.' },
+                { id: 'bind_entity_paths', label: 'Bind metric-relative entity paths', status: 'failed', detail: message },
+                { id: 'compile_semantic_query', label: 'Compile with the selected semantic adapter', status: 'not_started', detail: 'Compilation is gated until one entity path is selected.' },
+                { id: 'execute_query', label: 'Execute the compiled warehouse query', status: 'not_started', detail: 'Nothing was executed.' },
+            ],
+            failure: {
+                code: 'SEMANTIC_PATH_AMBIGUOUS',
+                phase: 'path_binding',
+                message,
+                candidates: input.candidates,
+            },
+        };
+    }
+}
 const cloudProbeCache = new Map();
 const OFFSET_PARAMETER_KEYS = new Set(['offsetwindow', 'offsettograin']);
 const METRIC_DEPENDENCY_KEYS = new Set([
@@ -328,25 +376,57 @@ export function qualifyForMetricFlow(request, semanticLayer) {
             dim.source?.objectId,
             dim.qualifiedName,
         ]) {
-            if (reference)
-                qualifiedByReference.set(reference.toLowerCase(), dim.qualifiedName);
+            if (reference) {
+                qualifiedByReference.set(reference.toLowerCase(), {
+                    runtimeReference: dim.qualifiedName,
+                    entityPath: dim.entityPath ?? [],
+                });
+            }
         }
     }
-    const qualify = (name) => {
+    const bindings = [];
+    const qualify = (name, role) => {
         if (!name)
             return name;
-        if (name === 'metric_time' || name.includes('__'))
-            return name; // already qualified / reserved
-        const exact = semanticLayer.resolveDimension(name, request.metrics);
-        return qualifiedByReference.get(name.toLowerCase())
-            ?? exact?.qualifiedName
-            ?? name;
+        const selection = parseSemanticDimensionSelection(name);
+        const authoringReference = selection.reference;
+        let runtimeReference;
+        let entityPath = selection.entityPath ?? [];
+        if (authoringReference === 'metric_time' || (authoringReference.includes('__') && !selection.entityPath)) {
+            runtimeReference = authoringReference;
+        }
+        else {
+            const exact = semanticLayer.resolveDimension(authoringReference, request.metrics);
+            const compatibleBinding = qualifiedByReference.get(authoringReference.toLowerCase());
+            const baseRuntimeReference = compatibleBinding?.runtimeReference
+                ?? exact?.qualifiedName
+                ?? authoringReference;
+            if (selection.entityPath?.length) {
+                const prefix = `${selection.entityPath.join('__')}__`;
+                runtimeReference = baseRuntimeReference.startsWith(prefix)
+                    ? baseRuntimeReference
+                    : `${prefix}${baseRuntimeReference}`;
+            }
+            else {
+                runtimeReference = baseRuntimeReference;
+                entityPath = compatibleBinding?.entityPath ?? [];
+            }
+        }
+        bindings.push({
+            role,
+            authoringReference,
+            runtimeReference,
+            entityPath,
+            status: 'resolved',
+        });
+        return runtimeReference;
     };
     const timeDimension = request.timeDimension
         ? (() => {
-            const name = qualify(request.timeDimension.name);
+            const selection = parseSemanticDimensionSelection(request.timeDimension.name);
+            const name = qualify(request.timeDimension.name, 'time_dimension');
             let granularity = request.timeDimension.granularity;
-            const td = semanticLayer.getTimeDimension(request.timeDimension.name);
+            const td = semanticLayer.getTimeDimension(selection.reference);
             if (td?.granularities?.length && !td.granularities.includes(granularity)) {
                 const clamped = td.granularities[0];
                 warnings.push(`Time grain "${granularity}" is finer than ${request.timeDimension.name}'s base grain; using "${clamped}".`);
@@ -357,15 +437,148 @@ export function qualifyForMetricFlow(request, semanticLayer) {
         : undefined;
     return {
         warnings,
+        bindings,
         request: {
             ...request,
-            dimensions: request.dimensions.map((d) => qualify(d) ?? d),
-            ...(request.filters ? { filters: request.filters.map((f) => f.dimension ? { ...f, dimension: qualify(f.dimension) } : f) } : {}),
-            ...(request.orderBy ? { orderBy: request.orderBy.map((o) => ({ ...o, name: qualify(o.name) ?? o.name })) } : {}),
+            dimensions: request.dimensions.map((d) => qualify(d, 'dimension') ?? d),
+            ...(request.filters ? { filters: request.filters.map((f) => f.dimension ? { ...f, dimension: qualify(f.dimension, 'filter') } : f) } : {}),
+            ...(request.orderBy ? { orderBy: request.orderBy.map((o) => ({ ...o, name: qualify(o.name, 'order_by') ?? o.name })) } : {}),
             ...(timeDimension ? { timeDimension } : {}),
         },
     };
 }
+const SEMANTIC_PATH_SELECTION = /^(.*?)@via\(([^)]+)\)$/;
+export function parseSemanticDimensionSelection(value) {
+    const match = value.trim().match(SEMANTIC_PATH_SELECTION);
+    if (!match)
+        return { reference: value };
+    const entityPath = match[2]
+        .split('>')
+        .map((part) => part.trim())
+        .filter((part) => /^[A-Za-z0-9_]+$/.test(part));
+    return entityPath.length > 0
+        ? { reference: match[1].trim(), entityPath }
+        : { reference: match[1].trim() };
+}
+export function formatSemanticDimensionSelection(reference, entityPath) {
+    return entityPath.length > 0 ? `${reference}@via(${entityPath.join('>')})` : reference;
+}
+export function applySemanticPathSelection(request, authoringReference, entityPath) {
+    const bind = (value) => {
+        const parsed = parseSemanticDimensionSelection(value);
+        const selectedReference = parsed.reference.toLowerCase();
+        const requestedReference = authoringReference.toLowerCase();
+        const sameReference = selectedReference === requestedReference
+            || ((!selectedReference.includes('.') || !requestedReference.includes('.'))
+                && selectedReference.split('.').pop() === requestedReference.split('.').pop());
+        return sameReference ? formatSemanticDimensionSelection(parsed.reference, entityPath) : value;
+    };
+    return {
+        ...request,
+        dimensions: request.dimensions.map(bind),
+        ...(request.filters ? { filters: request.filters.map((filter) => filter.dimension ? { ...filter, dimension: bind(filter.dimension) } : filter) } : {}),
+        ...(request.orderBy ? { orderBy: request.orderBy.map((order) => ({ ...order, name: bind(order.name) })) } : {}),
+        ...(request.timeDimension ? { timeDimension: { ...request.timeDimension, name: bind(request.timeDimension.name) } } : {}),
+    };
+}
+export function encodeSemanticPathEvidenceId(authoringReference, entityPath) {
+    return `semantic-path:${encodeURIComponent(authoringReference)}:${encodeURIComponent(entityPath.join('>'))}`;
+}
+export function decodeSemanticPathEvidenceId(value) {
+    if (!value?.startsWith('semantic-path:'))
+        return undefined;
+    const [, encodedReference, encodedPath] = value.split(':');
+    if (!encodedReference || !encodedPath)
+        return undefined;
+    try {
+        const entityPath = decodeURIComponent(encodedPath).split('>').filter(Boolean);
+        return entityPath.length > 0
+            ? { authoringReference: decodeURIComponent(encodedReference), entityPath }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function inferSemanticBindingRole(request, authoringReference) {
+    const matches = (value) => parseSemanticDimensionSelection(value ?? '').reference.toLowerCase() === authoringReference.toLowerCase();
+    if (matches(request.timeDimension?.name))
+        return 'time_dimension';
+    if (request.filters?.some((filter) => matches(filter.dimension)))
+        return 'filter';
+    if (request.orderBy?.some((order) => matches(order.name)))
+        return 'order_by';
+    return 'dimension';
+}
+function semanticTraceForSuccess(input) {
+    return {
+        version: 1,
+        adapter: input.adapter,
+        status: 'compiled',
+        authoringRequest: input.authoringRequest,
+        ...(input.runtimeRequest ? { runtimeRequest: input.runtimeRequest } : {}),
+        bindings: input.bindings,
+        warnings: input.warnings,
+        steps: [
+            { id: 'resolve_members', label: 'Resolve governed semantic members', status: 'completed', detail: 'Metric and dimension identities resolved from the pinned semantic snapshot.' },
+            { id: 'bind_entity_paths', label: 'Bind metric-relative entity paths', status: 'completed', detail: input.bindings.length > 0 ? `${input.bindings.length} runtime member binding(s) resolved.` : 'No dimension path binding was required.' },
+            { id: 'compile_semantic_query', label: 'Compile with the selected semantic adapter', status: 'completed', detail: `Compiled through ${input.adapter}.` },
+            { id: 'execute_query', label: 'Execute the compiled warehouse query', status: 'not_started', detail: 'Execution is owned by the authorized host after compilation.' },
+        ],
+    };
+}
+export function semanticPathAmbiguityFromError(input) {
+    const message = input.error instanceof Error ? input.error.message : String(input.error);
+    if (!/ambiguous and can(?:not|'t) be resolved/i.test(message))
+        return undefined;
+    const parsedCandidates = [];
+    const candidatePattern = /(?:TimeDimension|Dimension)\(\s*['"]([^'"]+)['"][^)]*?entity_path=\[([^\]]*)\]/g;
+    for (const match of message.matchAll(candidatePattern)) {
+        const entityPath = Array.from(match[2].matchAll(/['"]([^'"]+)['"]/g), (item) => item[1]).filter(Boolean);
+        if (entityPath.length > 0)
+            parsedCandidates.push({ baseRuntimeReference: match[1], entityPath });
+    }
+    if (parsedCandidates.length < 2)
+        return undefined;
+    const runtimeReference = parsedCandidates[0].baseRuntimeReference;
+    const matchingBinding = input.bindings.find((binding) => binding.runtimeReference === runtimeReference);
+    const authoringReference = matchingBinding?.authoringReference
+        ?? input.authoringRequest.timeDimension?.name
+        ?? input.authoringRequest.dimensions[0]
+        ?? runtimeReference;
+    const candidates = parsedCandidates.map((candidate) => {
+        const runtimeName = `${candidate.entityPath.join('__')}__${candidate.baseRuntimeReference}`;
+        return {
+            id: encodeSemanticPathEvidenceId(authoringReference, candidate.entityPath),
+            label: `Use ${authoringReference} via ${candidate.entityPath.join(' → ')}`,
+            description: `Bind the governed member to ${runtimeName}. No SQL will run until this path is selected.`,
+            authoringReference,
+            runtimeReference: runtimeName,
+            entityPath: candidate.entityPath,
+            selectionReference: formatSemanticDimensionSelection(authoringReference, candidate.entityPath),
+        };
+    });
+    return new SemanticRuntimePathAmbiguityError({
+        adapter: input.adapter,
+        authoringRequest: input.authoringRequest,
+        runtimeRequest: input.runtimeRequest,
+        bindings: input.bindings,
+        warnings: input.warnings,
+        authoringReference,
+        runtimeReference,
+        candidates,
+    });
+}
+function semanticRequestWithoutPathSelectors(request) {
+    const strip = (value) => parseSemanticDimensionSelection(value).reference;
+    return {
+        ...request,
+        dimensions: request.dimensions.map(strip),
+        ...(request.filters ? { filters: request.filters.map((filter) => filter.dimension ? { ...filter, dimension: strip(filter.dimension) } : filter) } : {}),
+        ...(request.orderBy ? { orderBy: request.orderBy.map((order) => ({ ...order, name: strip(order.name) })) } : {}),
+        ...(request.timeDimension ? { timeDimension: { ...request.timeDimension, name: strip(request.timeDimension.name) } } : {}),
+    };
+}
 export async function compileSemanticRuntimeQuery(request, context) {
     const effectiveRequest = normalizeSemanticRuntimeQueryRequest(request, context.semanticLayer);
     const status = await getSemanticRuntimeStatus(context.projectRoot, { probeConfiguredCloud: true });
@@ -375,7 +588,7 @@ export async function compileSemanticRuntimeQuery(request, context) {
     const routeLockedToFullRuntime = candidates.length === 1 && candidates[0] !== 'native';
     // Qualify dimension references to MetricFlow entity-qualified names ONCE, at
     // this boundary, for the full-runtime engines. Native keeps the bare request.
-    const { request: runtimeRequest, warnings: qualifyWarnings } = qualifyForMetricFlow(effectiveRequest, context.semanticLayer);
+    const { request: runtimeRequest, warnings: qualifyWarnings, bindings, } = qualifyForMetricFlow(effectiveRequest, context.semanticLayer);
     let lastRuntimeError;
     for (const adapter of candidates) {
         if (adapter === 'dbt-cloud') {
@@ -384,12 +597,37 @@ export async function compileSemanticRuntimeQuery(request, context) {
                 continue;
             try {
                 const result = await compileDbtCloudSemanticQuery(getEffectiveDbtCloudSemanticSettings(context.projectRoot), runtimeRequest);
-                return { sql: result.sql, joins: [], tables: [], engine: 'dbt-cloud', effectiveRequest, runtimeRequest, warnings: qualifyWarnings };
+                return {
+                    sql: result.sql,
+                    joins: [],
+                    tables: [],
+                    engine: 'dbt-cloud',
+                    effectiveRequest,
+                    runtimeRequest,
+                    semanticTrace: semanticTraceForSuccess({
+                        adapter: 'dbt-cloud',
+                        authoringRequest: effectiveRequest,
+                        runtimeRequest,
+                        bindings,
+                        warnings: qualifyWarnings,
+                    }),
+                    warnings: qualifyWarnings,
+                };
             }
             catch (error) {
                 lastRuntimeError = error instanceof Error ? error : new Error(String(error));
                 if (isSemanticRuntimeError(error))
                     throw error;
+                const ambiguity = semanticPathAmbiguityFromError({
+                    adapter: 'dbt-cloud',
+                    error,
+                    authoringRequest: effectiveRequest,
+                    runtimeRequest,
+                    bindings,
+                    warnings: qualifyWarnings,
+                });
+                if (ambiguity)
+                    throw ambiguity;
                 throw new SemanticRuntimeCompilationError('dbt-cloud', error);
             }
         }
@@ -412,27 +650,68 @@ export async function compileSemanticRuntimeQuery(request, context) {
                     limit: runtimeRequest.limit,
                     savedQuery: runtimeRequest.savedQuery,
                 });
-                return { sql: compiled.sql, joins: [], tables: [], engine: 'metricflow-cli', effectiveRequest, runtimeRequest, warnings: qualifyWarnings };
+                return {
+                    sql: compiled.sql,
+                    joins: [],
+                    tables: [],
+                    engine: 'metricflow-cli',
+                    effectiveRequest,
+                    runtimeRequest,
+                    semanticTrace: semanticTraceForSuccess({
+                        adapter: 'metricflow-cli',
+                        authoringRequest: effectiveRequest,
+                        runtimeRequest,
+                        bindings,
+                        warnings: qualifyWarnings,
+                    }),
+                    warnings: qualifyWarnings,
+                };
             }
             catch (error) {
                 lastRuntimeError = error instanceof Error ? error : new Error(String(error));
                 if (isSemanticRuntimeError(error))
                     throw error;
+                const ambiguity = semanticPathAmbiguityFromError({
+                    adapter: 'metricflow-cli',
+                    error,
+                    authoringRequest: effectiveRequest,
+                    runtimeRequest,
+                    bindings,
+                    warnings: qualifyWarnings,
+                });
+                if (ambiguity)
+                    throw ambiguity;
                 throw new SemanticRuntimeCompilationError('metricflow-cli', error);
             }
         }
+        const nativeRequest = semanticRequestWithoutPathSelectors(effectiveRequest);
         const composed = context.semanticLayer.composeQuery({
-            metrics: effectiveRequest.metrics,
-            dimensions: effectiveRequest.dimensions,
-            filters: effectiveRequest.filters,
-            limit: effectiveRequest.limit,
-            timeDimension: effectiveRequest.timeDimension,
-            orderBy: effectiveRequest.orderBy,
+            metrics: nativeRequest.metrics,
+            dimensions: nativeRequest.dimensions,
+            filters: nativeRequest.filters,
+            limit: nativeRequest.limit,
+            timeDimension: nativeRequest.timeDimension,
+            orderBy: nativeRequest.orderBy,
             driver: context.driver,
             tableMapping: context.tableMapping,
         });
-        if (composed)
-            return { ...composed, engine: 'native', effectiveRequest };
+        if (composed) {
+            return {
+                ...composed,
+                engine: 'native',
+                effectiveRequest,
+                semanticTrace: semanticTraceForSuccess({
+                    adapter: 'native',
+                    authoringRequest: effectiveRequest,
+                    bindings: bindings.map((binding) => ({
+                        ...binding,
+                        runtimeReference: parseSemanticDimensionSelection(binding.authoringReference).reference,
+                        entityPath: [],
+                    })),
+                    warnings: [],
+                }),
+            };
+        }
     }
     if (fullRuntimeRequested || routeLockedToFullRuntime) {
         throw lastRuntimeError ?? new SemanticRuntimeRequiredError(status.setup ?? 'The requested semantic runtime is unavailable.');
@@ -627,9 +906,12 @@ function selectActiveAdapter(preference, cloudReady, cliReady) {
 export function isSemanticRuntimeError(error) {
     return error instanceof SemanticRuntimeRequiredError
         || error instanceof SemanticRuntimeCompilationError
+        || error instanceof SemanticRuntimePathAmbiguityError
         || error instanceof MetricFlowUnavailableError;
 }
 export function semanticRuntimeErrorCode(error) {
+    if (error instanceof SemanticRuntimePathAmbiguityError)
+        return error.code;
     if (error instanceof SemanticRuntimeCompilationError)
         return error.code;
     if (error instanceof SemanticRuntimeRequiredError || error instanceof MetricFlowUnavailableError) {
@@ -637,4 +919,19 @@ export function semanticRuntimeErrorCode(error) {
     }
     return undefined;
 }
+export function semanticRuntimeErrorDetails(error) {
+    if (error instanceof SemanticRuntimePathAmbiguityError) {
+        return {
+            ...error.details,
+            semanticTrace: error.semanticTrace,
+        };
+    }
+    if (error instanceof SemanticRuntimeCompilationError) {
+        return {
+            adapter: error.adapter,
+            phase: 'compilation',
+        };
+    }
+    return undefined;
+}
 //# sourceMappingURL=semantic-runtime.js.map