@duckcodeailabs/dql-agent 1.8.2 → 1.8.3

package/dist/answer-loop.js

@@ -26,7 +26,7 @@ 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';
@@ -158,6 +158,35 @@ 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':
+        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 +216,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 +252,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',
@@ -1209,7 +1255,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 +1273,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 +1293,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,
@@ -1448,7 +1508,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 +1567,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 +1591,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 +1628,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,
@@ -1582,8 +1657,12 @@ async function runAnswerLoop(input) {
         ? evaluateDbtFirstGeneratedSql(parsed.sql, input.manifest, input.domainContext?.purpose, input.domainContext)
         : 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 +1690,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 +2354,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 +2394,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')