@duckcodeailabs/dql-agent 1.8.2 → 1.8.4

package/dist/answer-loop.js

@@ -26,10 +26,10 @@ import { createContextLedger } from './grounding/context-ledger.js';
 import { validateAnswerResultShape } from './answer-shape.js';
 import { fanoutWarningsForSql } from './metadata/grain-ledger.js';
 import { evaluateDbtFirstGeneratedSql } from './metadata/dbt-first-safety.js';
-import { planAnalyticalPath } from './metadata/analytical-policy.js';
+import { planAnalyticalPath, humanizeAnalyticalEntityId, analyticalPolicyUserFacingReason, } from './metadata/analytical-policy.js';
 import { planCertifiedAdaptation } from './metadata/block-adapt.js';
 import { compactSqlSnippet, extractSimpleSelectShape, selectExpressionOutputName, } from './metadata/sql-shape.js';
-import { composeSemanticQueryForQuestion, composeSemanticQueryFromMembers, } from './semantic-bridge/compose.js';
+import { composeSemanticQueryForQuestion, composeSemanticQueryFromCompiledMembers, composeSemanticQueryFromMembers, } from './semantic-bridge/compose.js';
 import { runAgenticToolLoop } from './agentic/tool-loop.js';
 import { buildSemanticStageTools } from './agentic/toolset.js';
 import { deriveAgenticTrust } from './agentic/answer-contract.js';
@@ -125,6 +125,93 @@ export function resolveAgentFilterValueBindings(value, schemaContext) {
         && normalizeValueIndexText(candidate.canonicalValue) === normalizeValueIndexText(best.canonicalValue))
         .map(({ distance: _distance, ...binding }) => binding);
 }
+/**
+ * AGT-005/AGT-012 — turn bounded value-index evidence into typed question
+ * state before route compatibility is evaluated. The value index, never an
+ * LLM or a metadata-token match, owns the canonical warehouse member. A value
+ * that matches multiple dimensions is intentionally left unbound so the
+ * certified lane cannot silently run with the wrong parameter.
+ */
+function questionPlanWithResolvedMemberBindings(plan, schemaContext) {
+    const existing = plan.requestedShape.memberBindings ?? [];
+    const existingValues = new Set(existing.flatMap((binding) => binding.values.map(normalizeValueIndexText)));
+    const candidates = Array.from(new Set([
+        ...(plan.valueMentions ?? []).map((mention) => mention.text.trim()),
+        ...(plan.requestedShape.filters ?? []).map((value) => value.trim()),
+    ].filter(Boolean)));
+    const resolved = candidates.flatMap((value) => {
+        if (existingValues.has(normalizeValueIndexText(value)))
+            return [];
+        const bindings = resolveAgentFilterValueBindings(value, schemaContext);
+        const dimensions = Array.from(new Set(bindings.map((binding) => binding.column.trim()).filter(Boolean)));
+        const canonicalValues = Array.from(new Set(bindings.map((binding) => binding.canonicalValue.trim()).filter(Boolean)));
+        if (dimensions.length !== 1 || canonicalValues.length !== 1)
+            return [];
+        const binding = bindings[0];
+        return [{
+                dimension: dimensions[0],
+                values: [canonicalValues[0]],
+                source: 'question',
+                confidence: binding.match === 'fuzzy' ? 'unique_partial' : 'exact',
+            }];
+    });
+    if (resolved.length === 0)
+        return plan;
+    const byIdentity = new Map();
+    for (const binding of [...existing, ...resolved]) {
+        const key = `${normalizeValueIndexText(binding.dimension)}\0${binding.values.map(normalizeValueIndexText).join('\0')}`;
+        if (!byIdentity.has(key))
+            byIdentity.set(key, binding);
+    }
+    return {
+        ...plan,
+        requestedShape: {
+            ...plan.requestedShape,
+            memberBindings: Array.from(byIdentity.values()),
+        },
+    };
+}
+/**
+ * Map typed member bindings to a block's declared parameter contract. The
+ * mapping is identifier-based (parameter name, semantic field, or declared
+ * filter binding) and must select exactly one parameter. Structural SQL is
+ * never accepted as a value.
+ */
+function certifiedInvocationInputs(block, plan) {
+    const definitions = block.parameters ?? [];
+    if (definitions.length === 0)
+        return {};
+    const parameters = {};
+    const parameterSources = {};
+    const declaredFilterBindings = new Map((block.filterBindings ?? []).map((entry) => [entry.filter, entry.binding]));
+    const topN = plan.requestedShape.topN?.n;
+    if (topN) {
+        const limitCandidates = definitions.filter((definition) => definition.name === 'top_n' || definition.binding?.kind === 'limit');
+        if (limitCandidates.length === 1) {
+            parameters[limitCandidates[0].name] = topN;
+            parameterSources[limitCandidates[0].name] = 'question';
+        }
+    }
+    for (const member of plan.requestedShape.memberBindings ?? []) {
+        const candidates = definitions.filter((definition) => {
+            if (Object.prototype.hasOwnProperty.call(parameters, definition.name))
+                return false;
+            const target = definition.binding?.kind === 'semantic_filter'
+                ? definition.binding.field
+                : declaredFilterBindings.get(definition.name) ?? definition.name;
+            return outputConceptMatches(target, member.dimension);
+        });
+        if (candidates.length !== 1)
+            continue;
+        const definition = candidates[0];
+        const values = Array.from(new Set(member.values.map((value) => value.trim()).filter(Boolean)));
+        if (values.length === 0 || (!definition.type.endsWith('[]') && values.length !== 1))
+            continue;
+        parameters[definition.name] = definition.type.endsWith('[]') ? values : values[0];
+        parameterSources[definition.name] = member.source === 'prior_result' ? 'prior_result' : 'question';
+    }
+    return Object.keys(parameters).length > 0 ? { parameters, parameterSources } : {};
+}
 function damerauLevenshteinDistance(left, right) {
     const rows = left.length + 1;
     const columns = right.length + 1;
@@ -158,6 +245,41 @@ const BUSINESS_CONTEXT_KINDS = ['term', 'business_view', 'domain', 'skill', 'rel
 const ARTIFACT_KINDS = [...EXECUTABLE_ARTIFACT_KINDS, ...BUSINESS_CONTEXT_KINDS];
 const SEMANTIC_KINDS = ['metric', 'dimension', 'measure', 'entity', 'semantic_model', 'saved_query'];
 const MANIFEST_KINDS = ['dbt_model', 'dbt_source'];
+/**
+ * Business-language explanation for a failed SQL context validation. The chat
+ * surface shows THIS; the validator's machine message (relation ids, repair
+ * tool guidance) belongs in refusalDetails/validationWarnings only.
+ */
+function renderContextValidationRefusalForUser(code, machineError, memberBindings) {
+    switch (code) {
+        case 'unknown_relation':
+            return 'I drafted a query, but it uses a table that was not part of the metadata retrieved for this question, so I did not run it. Ask again (retrieval usually finds it on a follow-up), name the table or metric explicitly, or re-sync the dbt metadata.';
+        case 'unknown_column':
+            return 'I drafted a query, but it references a column that is not in the inspected metadata for those tables, so I did not run it. Name the exact field you mean, or re-sync the dbt metadata if the column is new.';
+        case 'misbound_filter': {
+            const binding = memberBindings?.[0];
+            const target = binding ? `${humanizeAnalyticalEntityId(binding.dimension)} "${binding.values[0] ?? ''}"` : 'the requested value';
+            return `I need to filter this answer to ${target}, but the query I drafted did not apply that filter to a matching column, so I did not run it. Tell me which column identifies ${binding ? humanizeAnalyticalEntityId(binding.dimension) : 'that value'}, or rephrase with the exact field name.`;
+        }
+        case 'ambiguous_filter':
+            return 'The value you asked about matches more than one column in the inspected data, so I did not guess. Tell me which field it belongs to and I will run it.';
+        case 'missing_baseline':
+            return 'This comparison needs a baseline period or value that the drafted query did not include. Say what to compare against (for example, the prior month) and I will run it.';
+        case 'unsafe_sql':
+            return 'The drafted query used a statement type that is not allowed in this governed preview, so I did not run it.';
+        case 'insufficient_context':
+            if (/could not be parsed|parse error|syntax/i.test(machineError)) {
+                return 'I drafted a query, but its SQL syntax did not match the connected warehouse, so I did not run it. The failed draft is available in Inspect; retrying will generate a warehouse-specific query.';
+            }
+            return machineError.trim().length > 0 && !/inspect_metadata_context/i.test(machineError)
+                ? `I could not prepare a governed query yet: ${machineError.replace(/\s*Use inspect_metadata_context[^.]*\.\s*$/i, '').trim()}`
+                : 'I could not prepare a governed query from the retrieved metadata. Name the specific metric or table and how to break it down, and I can generate a review-required draft.';
+        default:
+            return machineError.trim().length > 0 && !/inspect_metadata_context/i.test(machineError)
+                ? `I could not prepare a governed query yet: ${machineError.replace(/\s*Use inspect_metadata_context[^.]*\.\s*$/i, '').trim()}`
+                : 'I could not prepare a governed query from the retrieved metadata. Name the specific metric or table and how to break it down, and I can generate a review-required draft.';
+    }
+}
 function refusalCodeForValidation(code) {
     if (code === 'unknown_relation' || code === 'unknown_column' || code === 'insufficient_context' || code === 'missing_baseline') {
         return 'grounding_gap';
@@ -187,6 +309,22 @@ function refusalCodeForAnalyticalPolicy(code, hasExploratoryCandidate = false) {
  * denials and must remain terminal in this loop.
  */
 function exploratoryCandidateFromDbtFirstGuard(sql, decision) {
+    // The policy service's disposition is authoritative: a declared draft path
+    // re-bound to this SQL's actual joins enters the bounded lane directly.
+    if (decision.disposition === 'exploratory_candidate') {
+        return {
+            kind: 'dbt_grounded_exploration',
+            reason: 'relationship_not_certified',
+            sql,
+            message: decision.technicalDetail ?? decision.message
+                ?? 'This query follows a declared but uncertified DQL relationship path.',
+            userFacingReason: decision.userFacingReason,
+            modeledEntityIds: decision.entities,
+            relationshipIds: decision.relationshipIds,
+            exploratoryPath: decision.exploratoryPath,
+            executionStatus: 'not_executed',
+        };
+    }
     const reason = decision.code;
     const missingPathWithoutUnsafeProof = reason === 'unsafe_relationship' && decision.relationshipIds.length === 0;
     if (decision.safe || (!missingPathWithoutUnsafeProof
@@ -207,6 +345,7 @@ function exploratoryCandidateFromDbtFirstGuard(sql, decision) {
         sql,
         message: decision.message
             ?? 'This query is grounded in dbt metadata but has no certified DQL relationship path yet.',
+        userFacingReason: decision.userFacingReason,
         modeledEntityIds: decision.entities,
         relationshipIds: decision.relationshipIds,
         executionStatus: 'not_executed',
@@ -452,9 +591,10 @@ async function runAnswerLoop(input) {
     const considered = mergeHits(artifactHits, semanticHits, manifestHits, kg.search({ query: question, domain, limit: 10 })).slice(0, 30);
     const schemaContext = schemaContextWithAllowedSqlContext(schemaContextWithinQuestionScope(input.schemaContext ?? [], input.contextPack, scopedContextPack), scopedContextPack);
     const catalogRoute = input.contextPack?.routeDecision;
-    const questionPlan = input.contextPack?.questionPlan?.requestedShape
+    const baseQuestionPlan = input.contextPack?.questionPlan?.requestedShape
         ? input.contextPack.questionPlan
         : buildAnalysisQuestionPlan(question, input.followUp);
+    const questionPlan = questionPlanWithResolvedMemberBindings(baseQuestionPlan, schemaContext);
     // Retrieval may surface a high-trust block because its source tables and
     // vocabulary overlap the question even when its output contract does not.
     // Keep such candidates in the audit trail, but do not put their SQL or a stale
@@ -500,7 +640,15 @@ async function runAnswerLoop(input) {
             kg,
         })
         : null;
-    const shouldTryCertifiedRoute = shouldUseCertifiedRoute(catalogRoute, intent);
+    const explicitlyRequestedCertifiedBlock = effectiveBlockHints.some((hint) => {
+        const node = kg.getNode(`block:${hint}`);
+        return Boolean(node
+            && node.status === 'certified'
+            && objectNameInQuestion(question, node)
+            && /\b(run|use|open|show|execute|certified|saved|block)\b/i.test(question));
+    });
+    const shouldTryCertifiedRoute = shouldUseCertifiedRoute(catalogRoute, intent)
+        || explicitlyRequestedCertifiedBlock;
     const catalogCertifiedHit = shouldTryCertifiedRoute
         ? certifiedHitFromContextPack(input.contextPack, kg)
         : null;
@@ -567,7 +715,10 @@ async function runAnswerLoop(input) {
         let executionError;
         if (artifactHit.node.kind === 'block' && input.executeCertifiedBlock) {
             try {
-                result = await input.executeCertifiedBlock(artifactHit.node, { question });
+                result = await input.executeCertifiedBlock(artifactHit.node, {
+                    question,
+                    ...certifiedInvocationInputs(artifactHit.node, questionPlan),
+                });
                 result = trimResultToRequestedTopN(result, questionPlan);
             }
             catch (err) {
@@ -882,6 +1033,8 @@ async function runAnswerLoop(input) {
     let governedMetricAnswer = false;
     const semanticBridgeToolCalls = [];
     let semanticBridgeAnswer;
+    let semanticRuntimeFailure;
+    let semanticRuntimeCompiledAnswer = false;
     if (input.semanticLayer && semanticMetricMatch) {
         semanticBridgeAnswer = composeSemanticQueryForQuestion({
             semanticLayer: input.semanticLayer,
@@ -893,6 +1046,44 @@ async function runAnswerLoop(input) {
             ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
             ...(input.semanticTableMapping ? { tableMapping: input.semanticTableMapping } : {}),
         });
+        // Exact scalar metrics need no AI member selection. If the native compiler
+        // cannot express a derived/ratio/cumulative metric, hand the identifier to
+        // the host's shared dbt Cloud/MetricFlow adapter immediately.
+        if (!semanticBridgeAnswer
+            && input.semanticQueryCompiler
+            && questionPlan.requestedShape.dimensions.length === 0
+            && questionPlan.dimensionTerms.length === 0
+            && questionPlan.requestedShape.filters.length === 0
+            && questionPlan.timeTerms.length === 0) {
+            const matchedName = input.semanticLayer.listMetrics().find((metric) => metric.name === semanticMetricMatch.metric.name
+                || metric.name.endsWith(`.${semanticMetricMatch.metric.name}`)
+                || semanticMetricMatch.metric.name.endsWith(`.${metric.name}`))?.name;
+            if (matchedName) {
+                const selection = { metrics: [matchedName], dimensions: [] };
+                try {
+                    const compiled = await input.semanticQueryCompiler(selection);
+                    semanticBridgeAnswer = composeSemanticQueryFromCompiledMembers({
+                        semanticLayer: input.semanticLayer,
+                        question,
+                        selection,
+                        sql: compiled.sql,
+                    });
+                    if (semanticBridgeAnswer) {
+                        semanticRuntimeCompiledAnswer = compiled.engine !== 'native';
+                        semanticBridgeToolCalls.push({
+                            name: 'compile_semantic_query',
+                            status: 'checked',
+                            inputSummary: `metric: ${matchedName}`,
+                            outputSummary: `Compiled through ${compiled.engine}`,
+                            order: semanticBridgeToolCalls.length + 1,
+                        });
+                    }
+                }
+                catch (error) {
+                    semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
+                }
+            }
+        }
         // Lane-2 LLM fallback: the deterministic token matcher missed, but a metric
         // matched so the semantic layer IS relevant. Spend ONE call to have the model
         // pick members (the query_semantic_model contract); the compiler still owns the
@@ -907,13 +1098,37 @@ async function runAnswerLoop(input) {
                 reasoningEffort: input.reasoningEffort,
             });
             if (selection) {
-                const composed = composeSemanticQueryFromMembers({
+                let composed = composeSemanticQueryFromMembers({
                     semanticLayer: input.semanticLayer,
                     question,
                     selection,
                     ...(input.semanticDriver ? { driver: input.semanticDriver } : {}),
                     ...(input.semanticTableMapping ? { tableMapping: input.semanticTableMapping } : {}),
                 });
+                if (!composed && input.semanticQueryCompiler) {
+                    try {
+                        const compiled = await input.semanticQueryCompiler(selection);
+                        composed = composeSemanticQueryFromCompiledMembers({
+                            semanticLayer: input.semanticLayer,
+                            question,
+                            selection,
+                            sql: compiled.sql,
+                        });
+                        if (composed) {
+                            semanticRuntimeCompiledAnswer = compiled.engine !== 'native';
+                            semanticBridgeToolCalls.push({
+                                name: 'compile_semantic_query',
+                                status: 'checked',
+                                inputSummary: `metrics: ${selection.metrics.join(', ')}${selection.dimensions?.length ? `; by ${selection.dimensions.join(', ')}` : ''}`,
+                                outputSummary: `Compiled through ${compiled.engine}`,
+                                order: semanticBridgeToolCalls.length + 1,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        semanticRuntimeFailure = error instanceof Error ? error.message : String(error);
+                    }
+                }
                 // Coverage guard: if the question asked for a breakdown but the LLM
                 // selection produced none, the governed answer would silently DROP the
                 // requested grouping (governed-but-wrong). Fall through to Lane-3
@@ -938,6 +1153,36 @@ async function runAnswerLoop(input) {
             }
         }
     }
+    if (!semanticBridgeAnswer && semanticRuntimeFailure) {
+        const text = `The governed semantic metric was found, but its semantic runtime could not compile the request: ${semanticRuntimeFailure}`;
+        return {
+            kind: 'no_answer',
+            sourceTier: 'no_answer',
+            certification: 'analyst_review_required',
+            reviewStatus: 'none',
+            confidence: 0,
+            text,
+            answer: text,
+            refusalCode: 'modeling_gap',
+            refusalDetails: { code: 'semantic_runtime_required', message: text },
+            citations: [],
+            memoryContext: input.memoryContext,
+            evidence: buildNoAnswerEvidence({
+                question,
+                reason: text,
+                artifactHits,
+                businessHits,
+                semanticHits,
+                manifestHits,
+                considered,
+                memoryContext: input.memoryContext ?? [],
+                toolCalls: semanticBridgeToolCalls,
+            }),
+            contextPack: input.contextPack,
+            considered,
+            providerUsed: provider.name,
+        };
+    }
     const metricFirst = semanticMetricMatch
         ? buildGovernedMetricFirstSql({
             metric: semanticMetricMatch.metric,
@@ -954,6 +1199,7 @@ async function runAnswerLoop(input) {
     let contextLedger = createContextLedger({
         contextPack: input.contextPack,
         schemaContext,
+        dialect: input.semanticDriver,
     });
     // W2.2 — certified-block adaptation lane. When a certified block is context-only
     // ONLY because the question adds exactly one filter whose value maps to a column
@@ -996,6 +1242,7 @@ async function runAnswerLoop(input) {
             kg,
             driver: input.semanticDriver,
             tableMapping: input.semanticTableMapping,
+            semanticQueryCompiler: input.semanticQueryCompiler,
             onCompiled: (record) => compiledSemanticRecords.push(record),
         }),
     ];
@@ -1110,6 +1357,7 @@ async function runAnswerLoop(input) {
             if (trust.tier === 'semantic_metric' && trust.compiled) {
                 governedMetricAnswer = true;
                 const compiled = trust.compiled;
+                semanticRuntimeCompiledAnswer = compiled.engine === 'metricflow-cli' || compiled.engine === 'dbt-cloud';
                 const governedNote = `Answered from governed semantic metric${compiled.metrics.length === 1 ? '' : 's'} ${compiled.metrics.join(', ')}${compiled.dimensions.length > 0 ? ` by ${compiled.dimensions.join(', ')}` : ''} (compiled via the semantic layer). Reusable block certification remains a separate review.`;
                 parsed = { ...parsed, text: parsed.text ? `${parsed.text}\n\n${governedNote}` : governedNote };
                 proposalToolCalls.push({
@@ -1209,7 +1457,12 @@ async function runAnswerLoop(input) {
             });
             parsed = parseProposal(proposed);
         }
-        catch {
+        catch (err) {
+            // Deadline/cancellation must surface as itself, never as a policy refusal.
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? err;
+            if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+                throw err;
             // keep the original decline; fall through to the honest no_answer.
         }
     }
@@ -1222,9 +1475,15 @@ async function runAnswerLoop(input) {
         // consistent, actionable message so the same question yields the same outcome
         // every run and every surface — instead of passing through the model's varying
         // text. A genuinely context-less ask keeps the plain honest message.
+        // The user-facing text is BUSINESS language; the machine policy detail
+        // (qualified ids, codes) lives only in refusalDetails + validationWarnings.
         const declinedDespiteContext = wantsGeneratedData && hasGeneratableContext;
+        const policyDetail = analyticalPlan?.safe === false
+            ? analyticalPlan.technicalDetail ?? analyticalPlan.message ?? 'DQL could not prove a safe analytical relationship path.'
+            : undefined;
         const text = analyticalPlan?.safe === false
-            ? analyticalPlan.message ?? 'DQL could not prove a safe analytical relationship path.'
+            ? analyticalPlan.userFacingReason
+                ?? analyticalPolicyUserFacingReason(analyticalPlan.code ?? 'unsafe_relationship', analyticalPlan.entities)
             : declinedDespiteContext
                 ? 'I could not compose a governed query for this from the available tables and metrics. This usually needs a clearer join path or an explicit metric and grouping — name the specific measure and how to break it down, and I can generate a review-required draft.'
                 : parsed.text || 'No answer (the model declined to propose SQL).';
@@ -1236,14 +1495,17 @@ async function runAnswerLoop(input) {
             confidence: 0.1,
             text,
             refusalCode: analyticalPlan?.safe === false
-                ? refusalCodeForAnalyticalPolicy(analyticalPlan.code)
+                ? analyticalPlan.disposition === 'exploratory_candidate'
+                    ? 'modeling_gap'
+                    : refusalCodeForAnalyticalPolicy(analyticalPlan.code, analyticalPlanAllowsDbtExploration(analyticalPlan))
                 : 'model_declined',
             refusalDetails: {
                 code: analyticalPlan?.safe === false
                     ? analyticalPlan.code ?? 'unsafe_relationship'
                     : 'model_declined',
-                message: text,
+                message: policyDetail ?? text,
             },
+            validationWarnings: policyDetail ? [`Analytical policy detail: ${policyDetail}`] : undefined,
             answer: text,
             citations: [],
             memoryContext: input.memoryContext,
@@ -1292,13 +1554,19 @@ async function runAnswerLoop(input) {
         && questionPlan.requestedShape.filters.length === 0
         && !questionPlan.requestedShape.topN;
     let contextValidation;
-    const initialValidation = contextLedger.validateSql(parsed.sql, {
-        question,
-        intent,
-        filterValues: input.followUp?.filters,
-        trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
-        memberBindings: input.followUp?.memberBindings,
-    });
+    // dbt Cloud/MetricFlow SQL has already been compiled against the selected
+    // semantic environment. A thin local retrieval pack cannot safely reject it
+    // and replace it with a guessed leaf-measure SQL. Warehouse execution remains
+    // the final binder/runtime check.
+    const initialValidation = semanticRuntimeCompiledAnswer
+        ? { ok: true, warnings: ['SQL compiled by the configured semantic runtime.'] }
+        : contextLedger.validateSql(parsed.sql, {
+            question,
+            intent,
+            filterValues: input.followUp?.filters,
+            trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+            memberBindings: input.followUp?.memberBindings,
+        });
     const rankedGrainGap = missingRankedGrainOutput(questionPlan, parsed.sql, semanticBridgeAnswer?.dimensions);
     contextValidation = initialValidation.ok && rankedGrainGap
         ? {
@@ -1448,7 +1716,11 @@ async function runAnswerLoop(input) {
                         };
             }
         }
-        catch {
+        catch (err) {
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? err;
+            if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+                throw err;
             // Re-grounding is best-effort; the bounded self-repair below still runs.
         }
     }
@@ -1503,7 +1775,11 @@ async function runAnswerLoop(input) {
                 }
             }
         }
-        catch {
+        catch (err) {
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? err;
+            if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+                throw err;
             // Repair is best-effort — the refusal below stays the honest fallback.
         }
     }
@@ -1523,7 +1799,10 @@ async function runAnswerLoop(input) {
         }
     }
     if (!contextValidation.ok) {
-        const text = `I could not safely prepare this review-required DQL artifact from the inspected context. The SQL preview failed validation: ${contextValidation.error}`;
+        // Business-language chat text; the validator's machine message (with
+        // relation ids and tool guidance for the repair prompt) stays in
+        // refusalDetails + validationWarnings for the Inspect surface.
+        const text = renderContextValidationRefusalForUser(contextValidation.code, contextValidation.error, input.followUp?.memberBindings);
         const analysisPlan = buildAnalysisPlan({
             question,
             intent,
@@ -1557,7 +1836,11 @@ async function runAnswerLoop(input) {
             trustLabel: input.contextPack?.trustLabel,
             sourceCertifiedBlock: followUpSourceBlock?.name ?? input.followUp?.sourceBlockName,
             contextPackId: input.contextPack?.id,
-            validationWarnings: [...contextValidation.warnings, ...deepCandidateNotes],
+            validationWarnings: [
+                ...contextValidation.warnings,
+                `SQL context validation detail: ${contextValidation.error}`,
+                ...deepCandidateNotes,
+            ],
             selectedEvidence: input.contextPack?.evidenceRoles?.slice(0, 12),
             citations: [],
             memoryContext: input.memoryContext,
@@ -1579,11 +1862,15 @@ async function runAnswerLoop(input) {
         };
     }
     const dbtFirstJoinSafety = input.manifest
-        ? evaluateDbtFirstGeneratedSql(parsed.sql, input.manifest, input.domainContext?.purpose, input.domainContext)
+        ? evaluateDbtFirstGeneratedSql(parsed.sql, input.manifest, input.domainContext?.purpose, input.domainContext, input.semanticDriver)
         : undefined;
     if (dbtFirstJoinSafety && !dbtFirstJoinSafety.safe) {
-        const text = dbtFirstJoinSafety.message
+        // Business-language text for the chat surface; the machine policy message
+        // stays in refusalDetails + validationWarnings for Inspect.
+        const policyDetail = dbtFirstJoinSafety.technicalDetail ?? dbtFirstJoinSafety.message
             ?? 'DQL could not prove this generated join from certified analytical relationships.';
+        const text = dbtFirstJoinSafety.userFacingReason
+            ?? analyticalPolicyUserFacingReason(dbtFirstJoinSafety.code ?? 'unsafe_relationship', dbtFirstJoinSafety.entities);
         const exploratoryCandidate = exploratoryCandidateFromDbtFirstGuard(parsed.sql, dbtFirstJoinSafety);
         const analysisPlan = buildAnalysisPlan({
             question,
@@ -1611,13 +1898,16 @@ async function runAnswerLoop(input) {
             proposedSql: parsed.sql,
             sql: parsed.sql,
             ...(exploratoryCandidate ? { exploratoryCandidate } : {}),
-            refusalCode: refusalCodeForAnalyticalPolicy(dbtFirstJoinSafety.code, Boolean(exploratoryCandidate)),
+            refusalCode: dbtFirstJoinSafety.disposition === 'exploratory_candidate'
+                ? 'modeling_gap'
+                : refusalCodeForAnalyticalPolicy(dbtFirstJoinSafety.code, Boolean(exploratoryCandidate)),
             refusalDetails: {
                 code: dbtFirstJoinSafety.code ?? 'unsafe_relationship',
-                message: text,
+                message: policyDetail,
             },
             validationWarnings: [
                 ...contextValidation.warnings,
+                `Analytical policy detail: ${policyDetail}`,
                 `DQL v3 relationship guard: ${dbtFirstJoinSafety.code ?? 'unsafe relationship'}.`,
                 ...(exploratoryCandidate
                     ? ['A bounded DBT-grounded exploratory route may validate this missing modeled relationship; governed SQL was not executed.']
@@ -2272,10 +2562,21 @@ function renderAnalyticalPlanPrompt(plan) {
         return undefined;
     if (!plan.safe) {
         if (analyticalPlanAllowsDbtExploration(plan)) {
+            const declaredPath = plan.exploratoryPath?.edges.length
+                ? [
+                    'DECLARED (UNCERTIFIED) DRAFT JOIN PATH — suggestion only, NOT authorization:',
+                    ...plan.exploratoryPath.edges.map((edge, index) => [
+                        `${index + 1}. ${edge.fromEntity} (${edge.fromRelation ?? 'bound dbt model'}) -> ${edge.toEntity} (${edge.toRelation ?? 'bound dbt model'})`,
+                        `   relationship=${edge.relationshipId}; keys=${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}; cardinality=${edge.cardinality}; fanout=${edge.fanout}; status=${edge.lifecycle}`,
+                    ].join('\n')),
+                    'Prefer these declared relations and exact key pairs over inferring joins from column names. The result remains analyst-review-required.',
+                ]
+                : [];
             return [
                 'DQL GOVERNED RELATIONSHIP COVERAGE: MISSING.',
                 plan.message ?? 'No certified analytical relationship path is available.',
                 `Policy code: ${plan.code ?? 'unsafe_relationship'}.`,
+                ...declaredPath,
                 'This is not authorization for governed SQL. You MAY propose one bounded, read-only DBT-grounded exploratory SELECT/WITH using only the inspected relations and columns supplied below.',
                 'Use explicit aliases and equality join keys visible in the inspected schema. Preserve the requested member bindings exactly. Do not introduce an uninspected relation, a cross-domain path, an attribution/allocation rule, or more than four joins.',
                 'The host will independently parse, bound, probe, validate, and execute the candidate as analyst-review-required. If the inspected evidence cannot express the request, return no SQL.',
@@ -2301,8 +2602,12 @@ function renderAnalyticalPlanPrompt(plan) {
 /**
  * Missing modeling may enter the narrow EXP-001 host-validated lane. Explicit
  * unsafe, cross-domain, attribution, expiry, purpose, and proof failures never do.
+ * The planner's `disposition` is authoritative; the code checks remain only for
+ * plans produced by older manifests/paths that predate the disposition contract.
  */
 function analyticalPlanAllowsDbtExploration(plan) {
+    if (plan.disposition === 'exploratory_candidate')
+        return true;
     if (plan.safe)
         return false;
     if (plan.code === 'unbound_relation' || plan.code === 'relationship_not_certified')
@@ -3065,6 +3370,15 @@ function applyParsedProposalMetadata(target, source) {
 function buildCertifiedBlockDqlArtifact(block, result) {
     if (block.kind !== 'block')
         return undefined;
+    const parameters = block.parameters ?? [];
+    const parameterValues = Object.fromEntries((result?.parameters ?? []).map((entry) => [entry.name, entry.value]));
+    const parameterContract = renderCertifiedParameterContract(block);
+    const artifactRuntime = {
+        ...(parameters.length > 0 ? { parameters } : {}),
+        ...(Object.keys(parameterValues).length > 0 ? { parameterValues } : {}),
+        persistence: 'saved',
+        trustState: 'certified',
+    };
     const sql = block.sql?.trim() ?? result?.sql?.trim() ?? block.examples?.find((example) => example.sql?.trim())?.sql?.trim();
     if (!sql) {
         // The block answered but its SQL was not inlined in the index (navigation /
@@ -3080,6 +3394,7 @@ function buildCertifiedBlockDqlArtifact(block, result) {
             source: `// Certified DQL block "${escapeDqlArtifactString(block.name)}"`
                 + `${block.sourcePath ? `\n// source: ${block.sourcePath}` : ''}`
                 + `\n// SQL is not inlined in the index — open the source file to view or edit the query.`,
+            ...artifactRuntime,
         };
     }
     const domain = block.domain ?? 'misc';
@@ -3089,7 +3404,7 @@ function buildCertifiedBlockDqlArtifact(block, result) {
     domain = "${escapeDqlArtifactString(domain)}"
     type = "custom"
     status = "certified"${block.owner ? `\n    owner = "${escapeDqlArtifactString(block.owner)}"` : ''}
-    description = """${escapeDqlArtifactTripleString(description)}"""${sourcePathComment}
+    description = """${escapeDqlArtifactTripleString(description)}"""${sourcePathComment}${parameterContract}
 
     query = """
         ${sql.replace(/"""/g, '\\"\\"\\"').split('\n').join('\n        ')}
@@ -3101,8 +3416,51 @@ function buildCertifiedBlockDqlArtifact(block, result) {
         name: block.name,
         sourcePath: block.sourcePath,
         source,
+        compiledSql: result?.sql ?? sql,
+        ...artifactRuntime,
     };
 }
+function renderCertifiedParameterContract(block) {
+    const parameters = block.parameters ?? [];
+    if (parameters.length === 0)
+        return '';
+    const lines = ['\n\n    params {'];
+    for (const parameter of parameters) {
+        const defaultValue = parameter.default === undefined ? '' : ` = ${renderCertifiedDqlParameterValue(parameter.default)}`;
+        lines.push(`      ${parameter.name}: ${parameter.type}${defaultValue}`);
+    }
+    lines.push('    }', '    parameterPolicy {');
+    for (const parameter of parameters)
+        lines.push(`      ${parameter.name} = "${parameter.policy}"`);
+    lines.push('    }');
+    const explicitBindings = new Map((block.filterBindings ?? []).map((entry) => [entry.filter, entry.binding]));
+    const bindings = parameters.flatMap((parameter) => {
+        const explicit = explicitBindings.get(parameter.name);
+        if (explicit)
+            return [{ name: parameter.name, value: explicit }];
+        if (parameter.binding?.kind === 'semantic_filter')
+            return [{ name: parameter.name, value: parameter.binding.field }];
+        if (parameter.binding?.kind === 'limit')
+            return [{ name: parameter.name, value: 'limit' }];
+        return [];
+    });
+    if (bindings.length > 0) {
+        lines.push('    filterBindings {');
+        for (const binding of bindings)
+            lines.push(`      ${binding.name} = "${escapeDqlArtifactString(binding.value)}"`);
+        lines.push('    }');
+    }
+    return lines.join('\n');
+}
+function renderCertifiedDqlParameterValue(value) {
+    if (Array.isArray(value))
+        return `[${value.map(renderCertifiedDqlParameterValue).join(', ')}]`;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    return `"${escapeDqlArtifactString(String(value ?? ''))}"`;
+}
 function buildGeneratedSqlDqlArtifact(input) {
     const sql = input.sql?.trim();
     if (!sql)