@duckcodeailabs/dql-agent 1.8.1 → 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,12 +158,43 @@ 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';
     }
     if (code === 'ambiguous_filter')
         return 'ambiguous';
+    if (code === 'misbound_filter')
+        return 'grounding_gap';
     return 'model_declined';
 }
 /**
@@ -179,14 +210,34 @@ function refusalCodeForAnalyticalPolicy(code, hasExploratoryCandidate = false) {
     return 'policy_blocked';
 }
 /**
- * The governed guard is intentionally strict. Only the two outcomes that mean
+ * The governed guard is intentionally strict. Only outcomes that mean
  * "this repository has not modeled this join yet" may be handed to a host's
  * exploratory lane. All other decisions are explicit governance/safety
  * 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;
-    if (decision.safe || (reason !== 'unbound_relation' && reason !== 'unplanned_join' && reason !== 'relationship_not_certified')) {
+    const missingPathWithoutUnsafeProof = reason === 'unsafe_relationship' && decision.relationshipIds.length === 0;
+    if (decision.safe || (!missingPathWithoutUnsafeProof
+        && reason !== 'unbound_relation'
+        && reason !== 'unplanned_join'
+        && reason !== 'relationship_not_certified')) {
         return undefined;
     }
     // `unplanned_join` can also mean the model ignored an existing certified
@@ -201,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',
@@ -914,9 +966,10 @@ async function runAnswerLoop(input) {
                 // generation, which can express the breakdown.
                 const wantedBreakdown = questionPlan.requestedShape.dimensions.length > 0
                     || questionPlan.dimensionTerms.length > 0;
+                const requiredGroupingCount = requestedGroupingDimensions(questionPlan).length;
                 const dropsBreakdown = Boolean(composed)
                     && wantedBreakdown
-                    && composed.dimensions.length === 0
+                    && composed.dimensions.length < Math.max(1, requiredGroupingCount)
                     && !composed.timeDimension;
                 if (composed && !dropsBreakdown) {
                     semanticBridgeAnswer = composed;
@@ -1047,6 +1100,14 @@ async function runAnswerLoop(input) {
             });
         }
         catch (err) {
+            // A request-level cancellation/deadline is orchestration state, not an
+            // upstream-provider outage. Preserve the AbortSignal reason so the run
+            // engine can report a bounded deadline (or explicit user cancellation)
+            // instead of the misleading generic "Provider error" label.
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? err;
+            if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+                throw err;
             const text = `Provider error: ${err.message}`;
             return {
                 kind: 'no_answer',
@@ -1119,6 +1180,7 @@ async function runAnswerLoop(input) {
             intent,
             initial: { raw: proposed, parsed },
             contextLedger,
+            followUp: input.followUp,
             executeGeneratedSql: input.executeGeneratedSql,
             signal: input.signal,
             reasoningEffort: input.reasoningEffort,
@@ -1177,7 +1239,8 @@ async function runAnswerLoop(input) {
         || (input.contextPack?.allowedSqlContext?.relations.length ?? 0) > 0
         || (input.contextPack?.allowedSqlContext?.sourceBlockSql.length ?? 0) > 0
         || contextBlocks.length > 0;
-    if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext && analyticalPlan?.safe !== false) {
+    if (!parsed.sql && !governedMetricAnswer && wantsGeneratedData && hasGeneratableContext
+        && (analyticalPlan?.safe !== false || analyticalPlanAllowsDbtExploration(analyticalPlan))) {
         try {
             proposed = await generateProposalWithOptionalTools({
                 provider,
@@ -1192,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.
         }
     }
@@ -1205,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).';
@@ -1219,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,
@@ -1280,16 +1357,66 @@ async function runAnswerLoop(input) {
         intent,
         filterValues: input.followUp?.filters,
         trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+        memberBindings: input.followUp?.memberBindings,
     });
-    contextValidation = initialValidation.ok
-        ? { ok: true, warnings: initialValidation.warnings }
-        : {
+    const rankedGrainGap = missingRankedGrainOutput(questionPlan, parsed.sql, semanticBridgeAnswer?.dimensions);
+    contextValidation = initialValidation.ok && rankedGrainGap
+        ? {
             ok: false,
-            code: initialValidation.code,
-            error: initialValidation.error,
+            code: 'insufficient_context',
+            error: 'Generated SQL omits the ranked grouping dimension ' + rankedGrainGap + '. Include every requested ranking dimension in SELECT and GROUP BY before execution.',
             warnings: initialValidation.warnings,
-            offending: initialValidation.offending,
-        };
+        }
+        : initialValidation.ok
+            ? { ok: true, warnings: initialValidation.warnings }
+            : {
+                ok: false,
+                code: initialValidation.code,
+                error: initialValidation.error,
+                warnings: initialValidation.warnings,
+                offending: initialValidation.offending,
+            };
+    // A canonical member value that resolves to exactly one inspected column is
+    // compiler-owned request state, not creative SQL. If the proposal omitted
+    // that predicate entirely, inject it deterministically before spending the
+    // bounded AI validation repair. Misbound or ambiguous predicates are never
+    // rewritten here; they continue through the guarded correction/refusal path.
+    if (!contextValidation.ok
+        && contextValidation.code === 'misbound_filter'
+        && !contextValidation.offending?.relation
+        && !contextValidation.offending?.column
+        && input.followUp?.memberBindings?.length) {
+        const injected = injectUniqueResolvedMemberBindings(parsed.sql, input.followUp.memberBindings, schemaContext);
+        if (injected) {
+            parsed.sql = injected.sql;
+            const rebound = contextLedger.validateSql(parsed.sql, {
+                question,
+                intent,
+                filterValues: input.followUp?.filters,
+                trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                memberBindings: input.followUp.memberBindings,
+            });
+            const reboundGrainGap = rebound.ok
+                ? missingRankedGrainOutput(questionPlan, parsed.sql, semanticBridgeAnswer?.dimensions)
+                : undefined;
+            contextValidation = rebound.ok && !reboundGrainGap
+                ? { ok: true, warnings: [...rebound.warnings, ...injected.notes] }
+                : rebound.ok
+                    ? {
+                        ok: false,
+                        code: 'insufficient_context',
+                        error: 'Generated SQL omits the ranked grouping dimension ' + reboundGrainGap + '. Include every requested ranking dimension in SELECT and GROUP BY before execution.',
+                        warnings: [...rebound.warnings, ...injected.notes],
+                    }
+                    : {
+                        ok: false,
+                        code: rebound.code,
+                        error: rebound.error,
+                        warnings: [...rebound.warnings, ...injected.notes],
+                        offending: rebound.offending,
+                    };
+        }
+    }
     // Semantic compilation owns metric meaning, but a later dimensional join can
     // still make a compiled bare expression ambiguous at the warehouse binder.
     // Revoke governed trust for an invalid composition so the bounded repair lane
@@ -1305,9 +1432,12 @@ async function runAnswerLoop(input) {
     //      stands instead of guessing a measure.
     //   2) Otherwise fall back to a CLEAN governed-metric definition (direct or exact
     //      leaf-measure; no fuzzy family guess that could answer the wrong measure).
-    if (!contextValidation.ok && semanticMetricRoute && semanticMetricMatch) {
+    if (!contextValidation.ok && semanticMetricRoute && semanticMetricMatch && !rankedGrainGap) {
         const grounded = contextLedger.validateRuntimeGrounding(parsed.sql);
-        if (grounded?.ok) {
+        // Runtime grounding proves that relations and columns exist; it cannot prove
+        // that a resolved business member was bound to the right dimension. Never
+        // let this recovery lane bypass AGT-012's typed member invariant.
+        if (grounded?.ok && !(input.followUp?.memberBindings?.length)) {
             contextValidation = { ok: true, warnings: grounded.warnings };
         }
         else if (scalarGovernedMetricRecoveryAllowed) {
@@ -1346,28 +1476,43 @@ async function runAnswerLoop(input) {
                     intent,
                     filterValues: input.followUp?.filters,
                     trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                    memberBindings: input.followUp?.memberBindings,
                 });
-                contextValidation = revalidated.ok
+                const regroundedGrainGap = revalidated.ok
+                    ? missingRankedGrainOutput(questionPlan, parsed.sql, semanticBridgeAnswer?.dimensions)
+                    : undefined;
+                contextValidation = revalidated.ok && regroundedGrainGap
                     ? {
-                        ok: true,
-                        warnings: [
-                            ...revalidated.warnings,
-                            ...merged.notes.map((note) => `Re-grounded metadata context before repair: ${note}`),
-                        ],
-                    }
-                    : {
                         ok: false,
-                        code: revalidated.code,
-                        error: revalidated.error,
-                        warnings: [
-                            ...revalidated.warnings,
-                            ...merged.notes.map((note) => `Re-grounded metadata context before repair: ${note}`),
-                        ],
-                        offending: revalidated.offending,
-                    };
+                        code: 'insufficient_context',
+                        error: 'Generated SQL omits the ranked grouping dimension ' + regroundedGrainGap + '. Include every requested ranking dimension in SELECT and GROUP BY before execution.',
+                        warnings: revalidated.warnings,
+                    }
+                    : revalidated.ok
+                        ? {
+                            ok: true,
+                            warnings: [
+                                ...revalidated.warnings,
+                                ...merged.notes.map((note) => `Re-grounded metadata context before repair: ${note}`),
+                            ],
+                        }
+                        : {
+                            ok: false,
+                            code: revalidated.code,
+                            error: revalidated.error,
+                            warnings: [
+                                ...revalidated.warnings,
+                                ...merged.notes.map((note) => `Re-grounded metadata context before repair: ${note}`),
+                            ],
+                            offending: revalidated.offending,
+                        };
             }
         }
-        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.
         }
     }
@@ -1378,14 +1523,18 @@ async function runAnswerLoop(input) {
     // provider get the same single chance; any provider failure keeps the honest
     // refusal below. This mirrors the engine-level repair loop, applied to the
     // context-validation gate that previously refused on first failure.
-    if (!contextValidation.ok && !governedMetricAnswer && canUseLaneRepair(repairBudgetState, 'reground')) {
-        recordLaneRepair(repairBudgetState, 'reground');
+    if (!contextValidation.ok && !governedMetricAnswer && canUseLaneRepair(repairBudgetState, 'validation')) {
+        recordLaneRepair(repairBudgetState, 'validation');
         try {
             const failedSql = parsed.sql ?? '';
             const repairPrompt = [
                 `Your SQL was rejected before execution: ${contextValidation.error}`,
                 formatOffendingValidationToken(contextValidation.offending),
                 formatValidationWarningsForPrompt(contextValidation.warnings),
+                renderRequestedShapeForRepair(questionPlan),
+                'For every required grouping alias, select the best matching inspected business column, project it with that exact alias, and include the same expression in GROUP BY.',
+                'When the warehouse uses a different physical name (for example a location field for a requested region), keep the inspected physical column and alias it to the requested business name. Do not silently drop the grouping.',
+                'Preserve every requested dimension and measure that was already correct; change only what the validation error requires.',
                 'Correct it using ONLY the relations and columns from the inspected context above.',
                 'If a needed column lives on a different relation, JOIN that relation using the suggested join paths.',
                 'If the requested column does not exist anywhere in the inspected context, return the closest answerable SQL and say what is missing.',
@@ -1400,8 +1549,12 @@ async function runAnswerLoop(input) {
                     intent,
                     filterValues: input.followUp?.filters,
                     trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                    memberBindings: input.followUp?.memberBindings,
                 });
-                if (revalidated.ok) {
+                const repairedGrainGap = revalidated.ok
+                    ? missingRankedGrainOutput(questionPlan, reparsed.sql, semanticBridgeAnswer?.dimensions)
+                    : undefined;
+                if (revalidated.ok && !repairedGrainGap) {
                     const repairedSql = reparsed.sql;
                     parsed.sql = repairedSql;
                     parsed.text = reparsed.text || parsed.text;
@@ -1414,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.
         }
     }
@@ -1434,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,
@@ -1468,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,
@@ -1493,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,
@@ -1522,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.']
@@ -1603,6 +1774,7 @@ async function runAnswerLoop(input) {
                         intent,
                         filterValues: input.followUp?.filters,
                         trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                        memberBindings: input.followUp?.memberBindings,
                     });
                     if (localRepairValidation.ok) {
                         repairAttempts = 1;
@@ -1646,6 +1818,7 @@ async function runAnswerLoop(input) {
                             intent,
                             filterValues: input.followUp?.filters,
                             trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+                            memberBindings: input.followUp?.memberBindings,
                         });
                         if (repairedValidation.ok) {
                             repairAttempts += 1;
@@ -2180,6 +2353,27 @@ function renderAnalyticalPlanPrompt(plan) {
     if (!plan || plan.entities.length < 2)
         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.',
+            ].join('\n');
+        }
         return [
             'DQL ANALYTICAL POLICY DECISION: BLOCKED.',
             plan.message ?? 'No certified analytical relationship path is available.',
@@ -2197,6 +2391,21 @@ function renderAnalyticalPlanPrompt(plan) {
         'Use only these relationships and exact key pairs. dbt DAG lineage and same-named columns are not join authorization. Any different join must be refused.',
     ].join('\n');
 }
+/**
+ * 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')
+        return true;
+    return plan.code === 'unsafe_relationship' && plan.relationshipIds.length === 0;
+}
 // Metric-anchored generation (Tier 2.5): a governed metric matched the question but
 // the semantic layer couldn't compose the exact shape. Reuse the metric's CERTIFIED
 // definition as the measure rather than reinventing it, so the number stays consistent
@@ -2693,6 +2902,12 @@ function renderFollowUpContext(followUp) {
         followUp.dimensions?.length ? `requested dimensions: ${followUp.dimensions.join(', ')}` : '',
         followUp.priorResultColumns?.length ? `prior result columns: ${followUp.priorResultColumns.join(', ')}` : '',
         followUp.priorResultValues ? `prior result values: ${formatPriorResultValues(followUp.priorResultValues)}` : '',
+        followUp.memberBindings?.length
+            ? `required member bindings: ${followUp.memberBindings.map((binding) => `${binding.dimension} = ${binding.values.join(' | ')} (${binding.confidence})`).join('; ')}`
+            : '',
+        followUp.memberBindings?.length
+            ? 'binding enforcement: apply every required member value only to a column representing its named dimension. Never substitute another dimension; if the named dimension is unavailable, report that gap.'
+            : '',
         followUp.priorResultRef ? renderPriorResultReference(followUp.priorResultRef) : '',
         followUp.priorDqlArtifact ? renderPriorDqlArtifactReference(followUp.priorDqlArtifact) : '',
         followUp.priorLimit ? `prior result limit: ${followUp.priorLimit}` : '',
@@ -3033,14 +3248,243 @@ function escapeDqlArtifactTripleString(value) {
 function generatedResultShapeIsPartial(resultShape) {
     return resultShape.missingOutputs.length >= 2;
 }
+/**
+ * A ranked query without its ranked entity is a different answer, even when the
+ * aggregate executes. Catch this before execution so the bounded validation
+ * correction can restore the requested grain instead of presenting a region-only
+ * total for a top-product question.
+ */
+export function missingRankedGrainOutput(questionPlan, sql, governedSemanticDimensions = []) {
+    const grain = questionPlan.requestedShape.grain;
+    if (!grain || questionPlan.requestedShape.topN?.scope !== 'per_group')
+        return undefined;
+    const shape = extractSimpleSelectShape(sql);
+    if (!shape)
+        return undefined;
+    const columns = shape.selectExpressions
+        .map(selectExpressionOutputName)
+        .filter((column) => Boolean(column));
+    const requiredGroupingDimensions = rankedGroupingDimensions(questionPlan);
+    const literalGap = requiredGroupingDimensions.find((dimension) => !columns.some((output) => outputConceptMatches(output, dimension)));
+    if (!literalGap)
+        return undefined;
+    // A bounded Lane-2 meaning selection may map a user's business word to a
+    // differently named governed dimension (for example "region" to
+    // `location_name`). Trust that mapping only when the semantic compiler
+    // projected every selected governed dimension and the selection covers the
+    // complete grouping cardinality. Arbitrary generated aliases never receive
+    // this exception.
+    const projectedGovernedDimensions = governedSemanticDimensions.filter((dimension) => columns.some((output) => outputConceptMatches(output, dimension)));
+    if (projectedGovernedDimensions.length >= requiredGroupingDimensions.length)
+        return undefined;
+    return literalGap;
+}
+function requestedGroupingDimensions(questionPlan) {
+    const grain = questionPlan.requestedShape.grain;
+    const dimensions = [
+        ...(grain ? [grain] : []),
+        ...questionPlan.requestedShape.dimensions,
+    ].filter((dimension) => {
+        const isGrain = Boolean(grain) && conceptsEquivalent(dimension, grain);
+        if (isGrain && !isCompoundMeasurePhrase(dimension, questionPlan.requestedShape.measures))
+            return true;
+        return !isMeasurePhrase(dimension, questionPlan.requestedShape.measures);
+    });
+    const seen = new Set();
+    return dimensions.filter((dimension) => {
+        const key = normalizedConceptTokens(dimension).join('_');
+        if (!key || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function rankedGroupingDimensions(questionPlan) {
+    const grain = questionPlan.requestedShape.grain;
+    if (!grain || questionPlan.requestedShape.topN?.scope !== 'per_group')
+        return [];
+    return requestedGroupingDimensions(questionPlan);
+}
+function renderRequestedShapeForRepair(questionPlan) {
+    return 'Required answer contract: ' + JSON.stringify({
+        grain: questionPlan.requestedShape.grain,
+        dimensions: questionPlan.requestedShape.dimensions,
+        measures: questionPlan.requestedShape.measures,
+        requiredOutputs: questionPlan.requestedShape.requiredOutputs,
+        requiredGroupingAliases: rankedGroupingDimensions(questionPlan),
+        topN: questionPlan.requestedShape.topN,
+    });
+}
+function outputConceptMatches(output, concept) {
+    const outputTokens = normalizedConceptTokens(output);
+    const conceptTokens = normalizedConceptTokens(concept);
+    return conceptTokens.length > 0 && conceptTokens.every((token) => outputTokens.includes(token));
+}
+function isCompoundMeasurePhrase(concept, measures) {
+    const conceptTokens = normalizedConceptTokens(concept);
+    return measures.some((measure) => {
+        const measureTokens = normalizedConceptTokens(measure);
+        return measureTokens.length > 0
+            && conceptTokens.length > measureTokens.length
+            && measureTokens.every((token) => conceptTokens.includes(token));
+    });
+}
+function isMeasurePhrase(concept, measures) {
+    const conceptTokens = normalizedConceptTokens(concept);
+    return measures.some((measure) => {
+        const measureTokens = normalizedConceptTokens(measure);
+        return measureTokens.length > 0
+            && conceptTokens.length >= measureTokens.length
+            && measureTokens.every((token) => conceptTokens.includes(token));
+    });
+}
+function conceptsEquivalent(left, right) {
+    const leftTokens = normalizedConceptTokens(left);
+    const rightTokens = normalizedConceptTokens(right);
+    return leftTokens.length === rightTokens.length
+        && leftTokens.every((token, index) => token === rightTokens[index]);
+}
+function normalizedConceptTokens(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token && token !== 'name' && token !== 'label')
+        .map((token) => token.endsWith('s') && token.length > 3 ? token.slice(0, -1) : token);
+}
 function trustedFollowUpFilterValues(followUp) {
     const filters = new Set((followUp?.filters ?? []).map((value) => value.trim()).filter(Boolean));
-    if (!filters.size || !followUp?.priorResultValues)
+    const boundValues = (followUp?.memberBindings ?? [])
+        .flatMap((binding) => binding.values)
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const priorValues = Object.values(followUp?.priorResultValues ?? {}).flat().map((value) => value.trim()).filter(Boolean);
+    const trustedCandidates = uniqueDrilldownStrings([...boundValues, ...priorValues]);
+    if (!trustedCandidates.length)
         return undefined;
-    const priorValues = Object.values(followUp.priorResultValues).flat().map((value) => value.trim()).filter(Boolean);
-    const trusted = priorValues.filter((value) => filters.has(value));
+    // Typed bindings were resolved by the deterministic member resolver and are
+    // trusted even if a legacy caller omitted the mirrored flat `filters` array.
+    const trusted = trustedCandidates.filter((value) => boundValues.includes(value) || filters.has(value));
     return trusted.length > 0 ? uniqueDrilldownStrings(trusted) : undefined;
 }
+function injectUniqueResolvedMemberBindings(sql, bindings, schemaContext) {
+    if (!/^\s*select\b/i.test(sql) || /;\s*\S/.test(sql))
+        return undefined;
+    const relationAliases = sqlRelationAliases(sql);
+    const predicates = [];
+    const notes = [];
+    for (const binding of bindings) {
+        const values = Array.from(new Set(binding.values.map((value) => value.trim()).filter(Boolean)));
+        if (values.length === 0)
+            continue;
+        // Do not add a second interpretation when the proposal already contains a
+        // canonical bound value. The validator will determine whether it is on the
+        // correct dimension and reject a misbinding.
+        if (values.some((value) => sql.toLowerCase().includes(sqlStringLiteral(value).toLowerCase())))
+            continue;
+        const candidates = schemaContext.flatMap((table) => table.columns.flatMap((column) => {
+            if (!outputConceptMatches(column.name, binding.dimension))
+                return [];
+            if (values.some((value) => /[\p{L}]/u.test(value)) && isJoinKeyColumn(column.name))
+                return [];
+            const samples = new Set((column.sampleValues ?? []).map(normalizeValueIndexText));
+            // The typed binding is already canonical request state. Samples may
+            // strengthen the match when this turn has them, but snapshot scoping must
+            // not erase a prior governed value. A conflicting non-empty sample set is
+            // rejected; an absent sample set may proceed only through the unique
+            // dimension-column + existing-query-path proof below.
+            if (samples.size > 0 && !values.every((value) => samples.has(normalizeValueIndexText(value))))
+                return [];
+            const alias = findSqlAliasForRelation(table.relation, relationAliases);
+            if (!alias || !safeSqlIdentifier(alias) || !safeSqlIdentifier(column.name))
+                return [];
+            return [{ alias, column: column.name }];
+        }));
+        const uniqueCandidates = Array.from(new Map(candidates.map((candidate) => [
+            `${candidate.alias.toLowerCase()}.${candidate.column.toLowerCase()}`,
+            candidate,
+        ])).values());
+        if (uniqueCandidates.length !== 1)
+            return undefined;
+        const candidate = uniqueCandidates[0];
+        const qualifiedColumn = `${candidate.alias}.${candidate.column}`;
+        const predicate = values.length === 1
+            ? `${qualifiedColumn} = ${sqlStringLiteral(values[0])}`
+            : `${qualifiedColumn} IN (${values.map(sqlStringLiteral).join(', ')})`;
+        predicates.push(predicate);
+        notes.push(`Applied the resolved ${binding.dimension} member binding deterministically on ${qualifiedColumn}.`);
+    }
+    if (predicates.length === 0)
+        return undefined;
+    const clauseIndex = firstTopLevelSqlClauseIndex(sql, ['group by', 'having', 'qualify', 'order by', 'limit']);
+    const head = clauseIndex >= 0 ? sql.slice(0, clauseIndex).trimEnd() : sql.trimEnd();
+    const tail = clauseIndex >= 0 ? ` ${sql.slice(clauseIndex).trimStart()}` : '';
+    const joiner = /\bwhere\b/i.test(head) ? ' AND ' : ' WHERE ';
+    return { sql: `${head}${joiner}${predicates.join(' AND ')}${tail}`, notes };
+}
+function sqlRelationAliases(sql) {
+    const matches = [];
+    const pattern = /\b(?:from|join)\s+((?:["`]?\w+["`]?\s*\.\s*)*["`]?\w+["`]?)\s*(?:as\s+)?([A-Za-z_][\w$]*)?/gi;
+    for (const match of sql.matchAll(pattern)) {
+        const relation = (match[1] ?? '').replace(/["`\s]/g, '');
+        if (!relation)
+            continue;
+        const implicitAlias = relation.split('.').pop() ?? relation;
+        const candidateAlias = match[2] && !SQL_CLAUSE_WORDS.has(match[2].toLowerCase()) ? match[2] : implicitAlias;
+        matches.push({ relation, alias: candidateAlias });
+    }
+    return matches;
+}
+const SQL_CLAUSE_WORDS = new Set(['where', 'join', 'left', 'right', 'inner', 'outer', 'full', 'cross', 'group', 'having', 'qualify', 'order', 'limit', 'on']);
+function findSqlAliasForRelation(relation, aliases) {
+    const normalized = relation.replace(/["`\s]/g, '').toLowerCase();
+    const short = normalized.split('.').pop();
+    return aliases.find((candidate) => {
+        const candidateNormalized = candidate.relation.toLowerCase();
+        return candidateNormalized === normalized || candidateNormalized.split('.').pop() === short;
+    })?.alias;
+}
+function firstTopLevelSqlClauseIndex(sql, clauses) {
+    let depth = 0;
+    let quote;
+    for (let index = 0; index < sql.length; index += 1) {
+        const char = sql[index];
+        if (quote) {
+            if (char === quote) {
+                if (quote === "'" && sql[index + 1] === "'")
+                    index += 1;
+                else
+                    quote = undefined;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"' || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === '(') {
+            depth += 1;
+            continue;
+        }
+        if (char === ')') {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (depth !== 0)
+            continue;
+        const rest = sql.slice(index).toLowerCase();
+        if (clauses.some((clause) => rest.startsWith(clause) && (!rest[clause.length] || /\s/.test(rest[clause.length]))))
+            return index;
+    }
+    return -1;
+}
+function safeSqlIdentifier(value) {
+    return /^[A-Za-z_][\w$]*$/.test(value);
+}
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
 function buildCandidateJoinPaths(schemaContext) {
     const tables = [...schemaContext]
         .filter((table) => table.columns.some((column) => isJoinKeyColumn(column.name)))
@@ -3972,6 +4416,9 @@ async function scoreDeepGeneratedProposalCandidate(input, candidate) {
         const validation = input.contextLedger.validateSql(parsed.sql, {
             question: input.question,
             intent: input.intent,
+            filterValues: input.followUp?.filters,
+            trustedFilterValues: trustedFollowUpFilterValues(input.followUp),
+            memberBindings: input.followUp?.memberBindings,
         });
         validationOk = validation.ok;
         if (validation.ok) {
@@ -4692,13 +5139,13 @@ function cascadeBudgetEvidenceRouteSteps(trace) {
     if (!trace)
         return [];
     const { usage, limits } = trace;
-    const used = usage.laneRegroundAttemptsUsed + usage.laneExecutionAttemptsUsed + usage.engineEscalationsUsed;
+    const used = usage.laneRegroundAttemptsUsed + usage.laneValidationAttemptsUsed + usage.laneExecutionAttemptsUsed + usage.engineEscalationsUsed;
     if (used === 0)
         return [];
     return [{
             tool: 'cascade_budget',
             status: 'checked',
-            label: `Repair budget used: re-ground ${usage.laneRegroundAttemptsUsed}/${limits.lane.reground}, execution ${usage.laneExecutionAttemptsUsed}/${limits.lane.execution}`,
+            label: `Repair budget used: re-ground ${usage.laneRegroundAttemptsUsed}/${limits.lane.reground}, validation ${usage.laneValidationAttemptsUsed}/${limits.lane.validation}, execution ${usage.laneExecutionAttemptsUsed}/${limits.lane.execution}`,
             detail: `engine escalations ${usage.engineEscalationsUsed}/${limits.engineEscalations}`,
         }];
 }