@duckcodeailabs/dql-cli 1.13.4 → 1.13.5

package/dist/local-runtime.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { execFileSync, execSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { gzip } from "node:zlib";
@@ -15,7 +16,7 @@ import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, pla
 import { resolveNpmInvocation } from './npm-runtime.js';
 import { ensureDqlGitignore, isGovernedSourceFile, isLegacyBroadDqlIgnore, } from './git-contract.js';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, hasStandaloneSemanticRef, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, resolveRepoSource, getDialect, Parser, NodeKind, blockParameterDefinitions, buildLineageGraph, buildManifest, collectInputFiles, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, domainFolderSlug, previewModelingChange, previewModelingChanges, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, normalizeAnalyticalFailureV1, relationshipValidationProofFingerprint, renderSemanticBlockSource, discoverDbtDomains, collectDbtRelationshipTests, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, semanticDimensionReference, modelAreaLocalId, DEFAULT_MODEL_AREA_ID, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, resolveRepoSource, getDialect, Parser, NodeKind, blockParameterDefinitions, buildLineageGraph, buildManifest, collectInputFiles, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, domainFolderSlug, previewModelingChange, previewModelingChanges, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, normalizeAnalyticalFailureV1, normalizeAnalyticalRepairCapabilityV1, relationshipValidationProofFingerprint, renderSemanticBlockSource, discoverDbtDomains, collectDbtRelationshipTests, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, buildSqlAnalyticalSignature, buildGeneratedAnalyticalSqlSignature, buildSqlOutputExpressionSignature, semanticDimensionReference, semanticExecutionFingerprint, modelAreaLocalId, DEFAULT_MODEL_AREA_ID, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
@@ -24,7 +25,7 @@ import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from '
 import { resolveRetrievalHealthStatus } from './retrieval-health.js';
 import { createDqlAgentProviderRunner, resolveAgentFollowUpContext } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, previewSkillChange, buildContextAuthoringProposal, contextAuthoringDependencyClosure, FileContextAuthoringProposalStore, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildAggregationSafetyProof, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, normalizeWarehouseSqlFailure, parseProposal, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, previewSkillChange, buildContextAuthoringProposal, contextAuthoringDependencyClosure, FileContextAuthoringProposalStore, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, createAgentRunBudget, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, assertProviderPayloadAllowed, createProviderDispatchEgressReceipt, prepareProviderWireEnvelopeForDispatch, markProviderMetadataArray, createProviderEgressReceipt, redactProviderResultRows, composeVerifiedAnalyticalNarrative, DEFAULT_ASK_ROW_EGRESS_POLICY, ZERO_ROW_EGRESS_POLICY, resolveProviderResultRowEgressPolicy, } from '@duckcodeailabs/dql-agent';
 import { addSqlResultFilter, dashboardFilterableResultColumns, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization, } from './apps-api.js';
@@ -291,6 +292,12 @@ export function parseAgentRunRequestBody(body) {
     const workspaceContext = agentRunRecord(record.workspaceContext) ?? agentRunRecord(record.context);
     const signals = agentRunRecord(record.signals);
     const requestedMode = parseAgentRunRequestedMode(record.requestedMode) ?? parseAgentRunRequestedMode(record.mode);
+    if (record.researchResultRowsOptIn !== undefined && typeof record.researchResultRowsOptIn !== 'boolean') {
+        return { error: 'researchResultRowsOptIn must be a boolean.' };
+    }
+    if (record.researchResultRowsOptIn === true && requestedMode !== 'research') {
+        return { error: 'researchResultRowsOptIn is accepted only for an explicitly requested Research run.' };
+    }
     const audience = record.audience === 'stakeholder' || record.audience === 'analyst'
         ? record.audience
         : undefined;
@@ -306,29 +313,47 @@ export function parseAgentRunRequestBody(body) {
             selectedObject,
             executionTarget,
             workspaceContext,
-            conversationContext: agentRunRecord(record.conversationContext),
+            conversationContext: sanitizeClientConversationContext(agentRunRecord(record.conversationContext)),
             history: parseAgentRunHistory(record.history),
             threadId: agentRunString(record.threadId),
             runId: agentRunString(record.runId),
             reasoningEffort: parseAgentRunReasoningEffort(record.reasoningEffort),
             analysisDepth: parseAgentRunAnalysisDepth(record.analysisDepth) ?? parseAgentRunAnalysisDepth(record.depth),
             thinkingMode: coerceThinkingMode(record.thinkingMode),
+            researchResultRowsOptIn: requestedMode === 'research' && record.researchResultRowsOptIn === true,
         },
     };
 }
+const CLIENT_PLAN_AUTHORITY_KEYS = new Set([
+    'priorResolvedAnalyticalPlan',
+    'resolvedAnalyticalPlan',
+    'analyticalFrame',
+]);
+/**
+ * Browser/embedding context is useful retrieval and history input, but it is
+ * not a plan-authority channel. Remove plan-shaped fields recursively at HTTP
+ * ingress; server-retained thread context is added afterwards from local state.
+ */
+function sanitizeClientConversationContext(context) {
+    if (!context)
+        return undefined;
+    const sanitize = (value) => {
+        if (Array.isArray(value))
+            return value.map(sanitize);
+        const record = agentRunRecord(value);
+        if (!record)
+            return value;
+        return Object.fromEntries(Object.entries(record).flatMap(([key, nested]) => CLIENT_PLAN_AUTHORITY_KEYS.has(key) ? [] : [[key, sanitize(nested)]]));
+    };
+    return sanitize(context);
+}
 const AGENT_LOOKUP_DEADLINE_MS = 45_000;
 const AGENT_RESEARCH_DEADLINE_MS = 120_000;
-/** Env-tunable run deadline (e.g. slow subscription-CLI providers), clamped to sane bounds. */
-function resolveAgentDeadlineMs(envKey, fallback, env = process.env) {
-    const configured = Number(env[envKey]);
-    if (!Number.isFinite(configured) || configured <= 0)
-        return fallback;
-    return Math.max(15_000, Math.min(600_000, Math.floor(configured)));
-}
 /**
  * PERF-002: one wall-clock budget follows the request through routing, provider
  * calls, repair, and execution. Ordinary Ask never inherits Research's budget
- * merely because it spans two tables; explicit/deep investigation does.
+ * because of question wording, depth, provider, or relational shape; only an
+ * explicit `requestedMode: research` activates the Research budget.
  */
 /** Resolve governed display formats for result columns from the semantic layer (best-effort, cached per call). */
 function agentColumnDisplayFormats(projectRoot, columns) {
@@ -346,91 +371,63 @@ function agentColumnDisplayFormats(projectRoot, columns) {
     catch { /* formatting is presentation-only; never fail an answer over it */ }
     return formats;
 }
-/** Subscription CLI providers spawn a cold external process per LLM call (2-15s
- * startup each) across a multi-call loop, so the API-sized 45s default made even
- * simple questions "reach the bounded execution deadline" on office laptops with
- * no env override. The defaults must fit the transport's physics. */
-const AGENT_CLI_LOOKUP_DEADLINE_MS = 150_000;
-const AGENT_CLI_RESEARCH_DEADLINE_MS = 300_000;
-/** High reasoning effort makes every LLM call materially slower, so the same
- * multi-step build that fits a budget at medium effort overruns it at high. The
- * budget must scale with effort or "High · thorough" reliably times out. */
-function reasoningEffortBudgetMultiplier(effort) {
-    return effort === 'high' ? 1.8 : effort === 'low' ? 0.9 : 1;
+export function agentRunDeadlineMs(request, env = process.env, activeProviderId) {
+    void env;
+    void activeProviderId;
+    return request.requestedMode === 'research'
+        ? AGENT_RESEARCH_DEADLINE_MS
+        : AGENT_LOOKUP_DEADLINE_MS;
 }
 /**
- * A ranking/breakdown/filtered question needs LLM SQL generation (the grain
- * dimension usually lives on a joined model the semantic layer can't compose),
- * and that multi-call build does NOT fit the bare lookup budget on a slow or
- * high-effort provider — it dead-ends at the deadline. It is not "research", but
- * it needs research-sized time to finish. Detected from the requested SHAPE (a
- * top-N, a member filter, a breakdown dimension, or a time window) rather than a
- * recognized metric word, since office questions like "top bcm customers from
- * the south region" name no metric the planner knows yet. A bare scalar
- * ("total revenue") has none of these and stays on the short budget.
+ * Decide how a settled answer gets its business-facing prose.
+ *
+ * This deliberately does NOT read `requestedMode`. Gating narration on
+ * `requestedMode === 'research'` meant every ordinary Ask — which the UI sends
+ * as `'auto'` — skipped synthesis entirely and shipped the answer loop's
+ * deterministic fact-join as the primary answer: the reported `column: value`
+ * dump. Narration is owed to any run that actually produced values.
+ *
+ * Certification, a DQL artifact, and the exploratory candidate are no longer
+ * vetoes. EXP-001's grain concern is real, but the answer to "the model might
+ * relabel an entity-level measure" is to VERIFY the claims against the fact set
+ * (`verified_facts`) and pass the grain statement in as a caveat — not to refuse
+ * to write a sentence.
  */
-function isAnalyticalBuildQuestion(plan) {
-    if (!plan.needsGeneratedSql)
-        return false;
-    return plan.requestedShape.dimensions.length > 0
-        || plan.dimensionTerms.length > 0
-        || plan.requestedShape.filters.length > 0
-        || plan.timeTerms.length > 0
-        || Boolean(plan.requestedShape.topN);
-}
-export function agentRunDeadlineMs(request, env = process.env, activeProviderId) {
-    const cliProvider = activeProviderId === 'claude-code' || activeProviderId === 'codex';
-    const lookupDeadline = resolveAgentDeadlineMs('DQL_AGENT_LOOKUP_DEADLINE_MS', cliProvider ? AGENT_CLI_LOOKUP_DEADLINE_MS : AGENT_LOOKUP_DEADLINE_MS, env);
-    const researchDeadline = resolveAgentDeadlineMs('DQL_AGENT_RESEARCH_DEADLINE_MS', cliProvider ? AGENT_CLI_RESEARCH_DEADLINE_MS : AGENT_RESEARCH_DEADLINE_MS, env);
-    // The "Thinking" control sends a thinkingMode; explicit reasoningEffort/
-    // analysisDepth (CLI flags) take precedence but the mode is the common case.
-    // The deadline MUST see the resolved values — "High" both slows every call
-    // AND means deep — or picking High reliably times out at the lookup budget.
-    const resolvedMode = request.thinkingMode ? resolveThinkingMode(request.thinkingMode) : {};
-    const effectiveEffort = request.reasoningEffort ?? resolvedMode.reasoningEffort;
-    const effectiveDepth = request.analysisDepth ?? resolvedMode.analysisDepth;
-    // The budget is a CEILING, not a target — a fast answer returns immediately;
-    // the larger tiers only matter when the build genuinely needs the time.
-    const scale = (ms) => Math.min(600_000, Math.round(ms * reasoningEffortBudgetMultiplier(effectiveEffort)));
-    if (request.requestedMode === 'research' || effectiveDepth === 'deep') {
-        return scale(researchDeadline);
-    }
-    // A structured clarification chip displays a compact metric/path label, but
-    // the engine restores and executes the original analytical question. Budget
-    // from that same original question as well. Otherwise a complex ranking or
-    // cross-model request can incorrectly inherit the 45s scalar-lookup budget
-    // merely because the selected label is short, then time out after the user
-    // already supplied the exact governed meaning.
-    const deadlineQuestion = request.selectedEvidenceId
-        ? request.clarificationSourceQuestion?.trim() || request.question
-        : request.question;
-    const plan = buildAnalysisQuestionPlan(deadlineQuestion);
-    if (plan.needsResearchWorkspace || isAnalyticalBuildQuestion(plan)) {
-        return scale(researchDeadline);
-    }
-    return scale(lookupDeadline);
-}
-export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
+export function planAgentRunNarration(governedAnswer, context) {
+    // A refusal is not narrated. It owes the user a reason or a clarifying
+    // question, which is the clarification lane's job, not the narrator's.
     if (governedAnswer.kind === 'no_answer')
-        return false;
-    // The executed rows are the presentation boundary: certified, semantic,
-    // DQL-first, and exploratory routes all deserve a separate stakeholder-facing
-    // explanation grounded in those values. Trust and query mechanics stay in the
-    // artifact/inspector instead of leaking into the primary answer.
+        return { mode: 'skip', reason: 'no_answer' };
+    if (!context.providerAvailable)
+        return { mode: 'skip', reason: 'no_provider' };
+    const maxRows = Math.max(0, context.rowEgress.maxNarrationRows);
+    // The fact set is the strongest grounding available: every sentence can be
+    // tied back to a fact id and rejected when it is not.
+    if (governedAnswer.analyticalFacts)
+        return { mode: 'verified_facts', maxRows };
     if (governedAnswer.result)
-        return true;
-    if (governedAnswer.kind === 'certified' || governedAnswer.certification === 'certified')
-        return false;
-    // EXP-001: exploratory prose is part of the trust boundary. A free-form
-    // synthesis pass can accidentally relabel an entity-level lifetime measure
-    // as a child-level allocation or total repeated values. Keep the host's
-    // deterministic grain statement instead.
-    if (governedAnswer.exploratoryCandidate)
-        return false;
-    const finalText = (governedAnswer.answer ?? governedAnswer.text ?? '').trim();
-    if (governedAnswer.dqlArtifact && finalText)
-        return false;
-    return true;
+        return { mode: 'preview_grounded', maxRows };
+    return { mode: 'skip', reason: 'nothing_to_narrate' };
+}
+/**
+ * Boolean view of {@link planAgentRunNarration}, kept for callers and tests that
+ * only need "does this run narrate at all".
+ */
+export function shouldSynthesizeAgentRunAnswer(governedAnswer, requestedMode = 'ask') {
+    return planAgentRunNarration(governedAnswer, {
+        requestedMode,
+        providerAvailable: true,
+        rowEgress: DEFAULT_ASK_ROW_EGRESS_POLICY,
+    }).mode !== 'skip';
+}
+/**
+ * AGT-010 — the semantic route label is descriptive, while the exact
+ * route-specific aggregation proof is authoritative for governed trust.
+ * Missing proof remains blocked for legacy or malformed results.
+ */
+export function semanticAnswerHasPassedAggregationProof(governedAnswer) {
+    return governedAnswer.route?.tier === 'semantic_metric'
+        && governedAnswer.aggregationSafetyProof?.status === 'safe';
 }
 export function agentAnswerHasExecutionFailure(governedAnswer) {
     return typeof governedAnswer.executionError === 'string'
@@ -544,6 +541,194 @@ export function warehouseFailureFromAgentRun(run) {
     }
     return undefined;
 }
+const AUTOMATIC_ASK_REPAIR_FAILURE_CODES = new Set([
+    'COLUMN_NOT_FOUND',
+    'RELATION_NOT_FOUND',
+    'AMBIGUOUS_COLUMN',
+    'DIALECT_ERROR',
+]);
+/** Validate the immutable custom wrapper before any automatic repair is offered. */
+export function validAskRepairDqlWrapper(source) {
+    try {
+        const program = new Parser(source, '<ask-repair-capability>').parse();
+        if (program.statements.length !== 1)
+            return false;
+        const block = program.statements[0];
+        return block.kind === NodeKind.BlockDecl
+            && block.blockType === 'custom'
+            && Boolean(extractBlockStudioSql(source)?.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/** Build retained automatic-repair authority from analytical failure state only. */
+export function analyticalRepairCapabilityForAgentRun(run, resolvedTargetFingerprint) {
+    if (run.status !== 'blocked')
+        return undefined;
+    const failedRun = analyticalFailedRunFromAgentRun(run);
+    const failure = failedRun?.failure;
+    const dqlArtifact = run.artifacts.flatMap((artifact) => {
+        const payload = agentRunRecord(artifact.payload);
+        const candidate = normalizeDqlArtifactReference(payload?.dqlArtifact);
+        return candidate?.kind === 'sql_block' && candidate.source?.trim() ? [candidate] : [];
+    })[0];
+    const dqlSource = dqlArtifact?.source?.trim();
+    const sql = dqlArtifact?.compiledSql?.trim() || repairableSqlFromAgentRun(run);
+    const target = run.executionTarget;
+    const planFingerprint = failure?.planFingerprint?.trim();
+    const hash = (value) => `sha256:${createHash('sha256').update(stableExecutionValue(value)).digest('hex')}`;
+    const sourceArtifact = run.artifacts.find((artifact) => {
+        const payload = agentRunRecord(artifact.payload);
+        return Boolean(normalizeDqlArtifactReference(payload?.dqlArtifact)?.source?.trim());
+    });
+    const retainedPlanFingerprint = sourceArtifact
+        ? agentRunString(agentRunRecord(agentRunRecord(sourceArtifact.payload)?.resolvedAnalyticalPlan)?.fingerprint)
+        : undefined;
+    const sourceFingerprint = sourceArtifact && dqlArtifact
+        ? hash({
+            runId: run.id,
+            artifactId: sourceArtifact.id,
+            dqlArtifact: {
+                kind: dqlArtifact.kind,
+                name: dqlArtifact.name,
+                source: dqlArtifact.source?.trim(),
+                parameterValues: dqlArtifact.parameterValues ?? {},
+                trustState: dqlArtifact.trustState,
+                persistence: dqlArtifact.persistence,
+            },
+        })
+        : undefined;
+    const manualActions = (failure?.safeActions ?? []).flatMap((action) => {
+        if (action === 'edit_dql' || action === 'open_sql_notebook' || action === 'refresh_snapshot'
+            || action === 'retry_same_plan' || action === 'change_authorized_connection' || action === 'request_access') {
+            return [action];
+        }
+        return [];
+    });
+    const ineligibilityReason = !failure
+        ? 'missing_failure_authority'
+        : failure.phase !== 'execution' || !AUTOMATIC_ASK_REPAIR_FAILURE_CODES.has(failure.code)
+            ? 'failure_not_eligible'
+            : !dqlSource
+                ? 'missing_dql_wrapper'
+                : !validAskRepairDqlWrapper(dqlSource)
+                    ? 'invalid_dql_wrapper'
+                    : !sql
+                        ? 'missing_compiled_sql'
+                        : !planFingerprint || !retainedPlanFingerprint || retainedPlanFingerprint !== planFingerprint
+                            ? 'missing_plan_fingerprint'
+                            : !sourceFingerprint
+                                ? 'missing_dql_wrapper'
+                                : !target || !resolvedTargetFingerprint
+                                    ? 'missing_execution_target'
+                                    : undefined;
+    const eligible = ineligibilityReason === undefined;
+    return {
+        version: 1,
+        automatic: {
+            eligible,
+            action: eligible ? 'repair_embedded_sql' : 'none',
+            correctionCode: eligible ? 'SQL_EXECUTION_REPAIR' : 'MANUAL_REVIEW_REQUIRED',
+            attemptsRemaining: eligible ? 1 : 0,
+        },
+        failureFingerprint: hash(failure ?? { unavailable: 'analytical_failure', runId: run.id }),
+        sourceFingerprint: sourceFingerprint ?? hash({ unavailable: 'source', runId: run.id }),
+        planFingerprint: retainedPlanFingerprint ?? planFingerprint ?? hash({ unavailable: 'plan', runId: run.id }),
+        dqlFingerprint: dqlSource ? hash(dqlSource) : hash({ unavailable: 'dql', runId: run.id }),
+        sqlFingerprint: sql ? hash(sql) : hash({ unavailable: 'sql', runId: run.id }),
+        targetFingerprint: resolvedTargetFingerprint ?? hash({ unavailable: 'target', runId: run.id }),
+        routeLocked: true,
+        targetLocked: true,
+        sourceImmutable: true,
+        manualActions: Array.from(new Set(manualActions)),
+        ...(ineligibilityReason ? { ineligibilityReason } : {}),
+    };
+}
+function attachAnalyticalRepairCapability(run, resolvedTargetFingerprint) {
+    const capability = analyticalRepairCapabilityForAgentRun(run, resolvedTargetFingerprint);
+    if (!capability)
+        return run;
+    run.repairCapability = capability;
+    if (run.diagnosticReceipt)
+        run.diagnosticReceipt = { ...run.diagnosticReceipt, repairCapability: capability };
+    run.artifacts = run.artifacts.map((artifact) => {
+        const payload = agentRunRecord(artifact.payload);
+        if (!payload)
+            return artifact;
+        const diagnostic = agentRunRecord(payload.diagnosticReceipt);
+        return {
+            ...artifact,
+            payload: {
+                ...payload,
+                repairCapability: capability,
+                ...(diagnostic ? { diagnosticReceipt: { ...diagnostic, repairCapability: capability } } : {}),
+            },
+        };
+    });
+    return run;
+}
+export function targetGenerationFingerprint(connection, connectionName) {
+    const identity = {
+        driver: connection.driver,
+        connectionName: connectionName ?? null,
+        host: connection.host ?? null,
+        port: connection.port ?? null,
+        username: connection.username ?? null,
+        authMethod: connection.authMethod ?? null,
+        authenticator: connection.authenticator ?? null,
+        profile: connection.profile ?? null,
+        ssl: connection.ssl ?? null,
+        account: connection.account ?? null,
+        database: connection.database ?? null,
+        schema: connection.schema ?? null,
+        warehouse: connection.warehouse ?? null,
+        role: connection.role ?? null,
+        catalog: connection.catalog ?? null,
+        httpPath: connection.httpPath ?? null,
+        filepath: connection.filepath ?? null,
+        projectId: connection.projectId ?? null,
+        region: connection.region ?? null,
+        workgroup: connection.workgroup ?? null,
+        location: connection.location ?? null,
+        outputLocation: connection.outputLocation ?? null,
+        accessUrl: connection.accessUrl ?? null,
+        application: connection.application ?? null,
+        queryTag: connection.queryTag ?? null,
+        workloadIdentityProvider: connection.workloadIdentityProvider ?? null,
+        workloadIdentityAzureClientId: connection.workloadIdentityAzureClientId ?? null,
+        workloadIdentityImpersonationPath: connection.workloadIdentityImpersonationPath ?? null,
+        oauthAuthorizationUrl: connection.oauthAuthorizationUrl ?? null,
+        oauthClientId: connection.oauthClientId ?? null,
+        oauthRedirectUri: connection.oauthRedirectUri ?? null,
+        oauthScope: connection.oauthScope ?? null,
+        oauthTokenRequestUrl: connection.oauthTokenRequestUrl ?? null,
+        keyFilename: connection.keyFilename ?? null,
+        privateKeyPath: connection.privateKeyPath ?? null,
+        accessKeyId: connection.accessKeyId ?? null,
+        proxyHost: connection.proxyHost ?? null,
+        proxyPort: connection.proxyPort ?? null,
+        proxyProtocol: connection.proxyProtocol ?? null,
+        proxyUser: connection.proxyUser ?? null,
+        noProxy: connection.noProxy ?? null,
+        credentialCacheDir: connection.credentialCacheDir ?? null,
+        moduleSearchPaths: connection.moduleSearchPaths ?? null,
+        clientRequestMFAToken: connection.clientRequestMFAToken ?? null,
+        clientStoreTemporaryCredential: connection.clientStoreTemporaryCredential ?? null,
+        clientSessionKeepAlive: connection.clientSessionKeepAlive ?? null,
+        clientSessionKeepAliveHeartbeatFrequency: connection.clientSessionKeepAliveHeartbeatFrequency ?? null,
+        keepAlive: connection.keepAlive ?? null,
+        passcodeInPassword: connection.passcodeInPassword ?? null,
+        browserActionTimeout: connection.browserActionTimeout ?? null,
+        timeout: connection.timeout ?? null,
+        waitTimeout: connection.waitTimeout ?? null,
+        byteLimit: connection.byteLimit ?? null,
+    };
+    return executionFingerprint(stableExecutionValue(identity));
+}
+function normalizeSqlForComparison(sql) {
+    return sql.trim().replace(/;\s*$/, '').replace(/\s+/g, ' ');
+}
 /**
  * Retain planning and retrieval evidence for a successful derived repair while
  * deliberately dropping the source failure and any result-bound facts. This
@@ -656,7 +841,7 @@ async function conversationContextFromThread(store, threadId, clientContext, que
         });
     }
     return {
-        ...(clientContext ?? {}),
+        ...(sanitizeClientConversationContext(clientContext) ?? {}),
         conversationStateVersion: 1,
         threadId,
         ...(serverSnapshot ? { conversationEnvelope: serverSnapshot } : {}),
@@ -783,7 +968,9 @@ export function conversationTurnInputFromRun(run) {
         ?? run.artifacts.find((candidate) => candidate.kind === 'research_run')
         ?? run.artifacts[0];
     const payload = agentRunRecord(artifact?.payload);
-    const result = agentRunRecord(payload?.result);
+    // A blocked run may retain diagnostic artifacts, but their result-shaped
+    // payload is never accepted conversation evidence or prose authority.
+    const result = run.status === 'blocked' ? undefined : agentRunRecord(payload?.result);
     const columns = conversationResultColumns(result?.columns);
     // The visual preview stays tiny, but member resolution needs a wider bounded
     // value window. Deriving dimensions from only the eight preview rows caused a
@@ -924,6 +1111,230 @@ function apiErrorCode(error, fallback) {
 function apiErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * Slowest provider dispatch we assume before any have been observed, and the
+ * settle time reserved after the last one. A subscription-CLI provider costs
+ * roughly 10-15s per call, so these keep the first admission decision honest.
+ */
+const ASSUMED_PROVIDER_DISPATCH_MS = 12_000;
+const DISPATCH_SETTLE_MARGIN_MS = 4_000;
+export class RunScopedProviderDispatchEvidence {
+    policy;
+    runBudget;
+    rowEgress;
+    receipts = [];
+    phaseCounts = new Map();
+    currentRoute;
+    /** Wall-clock start of the previous dispatch, used to learn this provider's cost. */
+    lastDispatchStartedAtMs;
+    observedDispatchDurations = [];
+    /**
+     * How long the NEXT dispatch is likely to take, learned from this run.
+     *
+     * Counting dispatches is not a time budget. A provider costing ~13s a call
+     * will burn a 45s deadline in three calls and get killed mid-flight, so the
+     * run ends with nothing — strictly worse than stopping early and answering
+     * from what it already has.
+     */
+    expectedDispatchMs() {
+        if (this.observedDispatchDurations.length === 0)
+            return ASSUMED_PROVIDER_DISPATCH_MS;
+        const sorted = [...this.observedDispatchDurations].sort((left, right) => left - right);
+        // The slowest observed call is the honest predictor: an optimistic median
+        // still admits a dispatch that the deadline then kills.
+        return sorted[sorted.length - 1];
+    }
+    /** True when the remaining wall clock cannot fit another provider call. */
+    cannotFitAnotherDispatch() {
+        if (!this.runBudget)
+            return false;
+        return this.runBudget.remainingMs() < this.expectedDispatchMs() + DISPATCH_SETTLE_MARGIN_MS;
+    }
+    /**
+     * The run budget's own clock when there is one, so dispatch cost is measured
+     * against the same timeline the deadline is enforced on (and stays injectable
+     * for deterministic tests).
+     */
+    nowMs() {
+        return this.runBudget ? this.runBudget.elapsedMs() : Date.now();
+    }
+    recordDispatchStart() {
+        const now = this.nowMs();
+        if (this.lastDispatchStartedAtMs !== undefined) {
+            this.observedDispatchDurations.push(Math.max(0, now - this.lastDispatchStartedAtMs));
+        }
+        this.lastDispatchStartedAtMs = now;
+    }
+    constructor(policy, runBudget, rowEgress = ZERO_ROW_EGRESS_POLICY) {
+        this.policy = policy;
+        this.runBudget = runBudget;
+        this.rowEgress = rowEgress;
+        this.currentRoute = runBudget?.mode === 'research' ? 'research' : 'generated_answer';
+    }
+    setRoute(route) {
+        if (route)
+            this.currentRoute = route;
+    }
+    mayStartToolCall() {
+        return !this.runBudget || this.runBudget.mayStartDiscovery(this.currentRoute);
+    }
+    observe(event, context) {
+        const softRoute = context.dispatchPhase === 'meaning_resolution' ? 'clarify' : this.currentRoute;
+        // Admission control BEFORE the phase targets: starting a call that the hard
+        // deadline will kill mid-flight wastes the remaining budget and ends the run
+        // with nothing. Stopping here lets the caller answer from what it has.
+        // Narration is exempt: it is the step that produces the answer, and it is
+        // separately bounded by its own soft target below.
+        if (context.dispatchPhase !== 'narration' && this.cannotFitAnotherDispatch()) {
+            throw Object.assign(new Error(`Only ${Math.round((this.runBudget?.remainingMs() ?? 0) / 1_000)}s of the run deadline remain, which is not enough for another ~${Math.round(this.expectedDispatchMs() / 1_000)}s provider call. Answering from what has already been gathered.`), { code: 'RUN_DEADLINE_INSUFFICIENT' });
+        }
+        if (context.dispatchPhase === 'narration') {
+            if (this.runBudget && !this.runBudget.mayStartNarration()) {
+                throw Object.assign(new Error(`The ${Math.round(this.runBudget.narrationSoftTargetMs() / 1_000)}-second narration target elapsed before the answer could be written.`), { code: 'RUN_SOFT_TARGET_EXCEEDED' });
+            }
+        }
+        else if (this.runBudget && !this.runBudget.mayStartDiscovery(softRoute)) {
+            throw Object.assign(new Error(`The ${Math.round(this.runBudget.softTargetMs(softRoute) / 1_000)}-second soft target elapsed before this provider dispatch could start.`), { code: 'RUN_SOFT_TARGET_EXCEEDED' });
+        }
+        this.recordDispatchStart();
+        if (this.receipts.length >= this.policy.total) {
+            throw Object.assign(new Error(`Run-wide provider dispatch budget exhausted after ${this.policy.total} physical attempts.`), { code: 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED' });
+        }
+        const phaseCount = this.phaseCounts.get(context.dispatchPhase) ?? 0;
+        const phaseLimit = context.dispatchPhase === 'meaning_resolution'
+            ? this.policy.meaningResolution
+            : context.dispatchPhase === 'repair'
+                ? this.policy.repair
+                : context.dispatchPhase === 'narration'
+                    ? this.policy.narration
+                    : this.policy.generationGroup;
+        // Planning and generation share one ledger because they compete for the
+        // same "work out the query" budget. Narration does not: it is the step that
+        // turns a settled result into an answer, and starving it produces a run
+        // that computed the right numbers and then could not say them.
+        const generationGroupCount = this.receipts.filter((receipt) => receipt.dispatchPhase === 'planning'
+            || receipt.dispatchPhase === 'generation').length;
+        if (phaseCount >= phaseLimit || ((context.dispatchPhase === 'planning' || context.dispatchPhase === 'generation')
+            && generationGroupCount >= this.policy.generationGroup)) {
+            throw Object.assign(new Error(`Provider dispatch budget exhausted for ${context.dispatchPhase} after ${phaseLimit} physical attempts.`), { code: 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED' });
+        }
+        const envelope = prepareProviderWireEnvelopeForDispatch(event.provider, event.envelope);
+        const projectedRowCount = context.serializedResultShape?.resultRowCount ?? 0;
+        const projectedCumulativeRowCount = context.cumulativeResultRowCount ?? projectedRowCount;
+        // Ordinary Ask narration reads its ceiling from the resolved project policy;
+        // Research keeps its own explicit opt-in limits.
+        const permittedRowLimit = context.purpose === 'answer_narration'
+            ? this.rowEgress.maxNarrationRows
+            : context.optIn && context.purpose === 'research_narration'
+                ? 20
+                : context.optIn && context.purpose === 'research_tool'
+                    ? 200
+                    : 0;
+        if (projectedRowCount > permittedRowLimit || projectedCumulativeRowCount > permittedRowLimit) {
+            throw Object.assign(new Error(permittedRowLimit === 0
+                ? 'Provider egress blocked result rows without explicit Research run consent.'
+                : `Provider egress blocked result rows beyond the cumulative Research limit of ${permittedRowLimit}.`), { code: permittedRowLimit === 0 ? 'PROVIDER_RESULT_ROWS_BLOCKED' : 'PROVIDER_RESULT_ROWS_LIMIT_EXCEEDED' });
+        }
+        assertProviderPayloadAllowed(envelope, {
+            allowResultRows: false,
+            maxResultRows: 0,
+            purpose: context.purpose,
+        });
+        const rowCount = projectedRowCount;
+        this.receipts.push(createProviderDispatchEgressReceipt({
+            purpose: context.purpose,
+            dispatchPhase: context.dispatchPhase,
+            provider: event.provider,
+            ...(event.model ? { model: event.model } : {}),
+            operation: event.operation,
+            attemptIndex: event.attemptIndex,
+            options: event.options,
+            permittedCategories: rowCount > 0
+                ? ['instructions', 'question', 'schema_metadata', 'governed_context', 'result_rows']
+                : ['instructions', 'question', 'schema_metadata', 'governed_context'],
+            optIn: context.optIn && rowCount > 0,
+            envelope,
+            ...(context.serializedResultShape ? { serializedResultShape: context.serializedResultShape } : {}),
+            ...(typeof context.cumulativeResultRowCount === 'number'
+                ? { cumulativeResultRowCount: context.cumulativeResultRowCount }
+                : {}),
+        }));
+        this.phaseCounts.set(context.dispatchPhase, phaseCount + 1);
+        return envelope;
+    }
+    snapshot(fallbackReason = 'none') {
+        return {
+            providerEgressReceipts: [...this.receipts],
+            providerRoundTrips: this.receipts.length,
+            toolCalls: 0,
+            sqlExecutions: 0,
+            repairs: 0,
+            fallbackReason,
+        };
+    }
+}
+const agentRunProviderEvidenceContext = new AsyncLocalStorage();
+function mergeRunScopedProviderDispatchEvidence(run, evidence) {
+    const providerEgressReceipts = [...evidence.providerEgressReceipts];
+    const elapsed = Math.max(0, Date.parse(run.completedAt) - Date.parse(run.startedAt));
+    const telemetry = {
+        version: 1,
+        stageDurationsMs: {
+            ...(run.telemetry?.stageDurationsMs ?? {}),
+            total: Number.isFinite(elapsed) ? Math.min(86_400_000, elapsed) : 0,
+        },
+        providerRoundTrips: evidence.providerRoundTrips,
+        toolCalls: run.telemetry?.toolCalls ?? evidence.toolCalls,
+        sqlExecutions: run.telemetry?.sqlExecutions ?? evidence.sqlExecutions,
+        repairs: run.telemetry?.repairs ?? evidence.repairs,
+        egressReceipts: providerEgressReceipts.length,
+        ...(run.telemetry?.warehouseDurationMs !== undefined
+            ? { warehouseDurationMs: run.telemetry.warehouseDurationMs }
+            : {}),
+        ...(run.telemetry?.fallbackReason
+            ? { fallbackReason: run.telemetry.fallbackReason }
+            : evidence.fallbackReason !== 'none'
+                ? { fallbackReason: evidence.fallbackReason }
+                : {}),
+    };
+    const diagnosticReceipt = run.diagnosticReceipt
+        ? { ...run.diagnosticReceipt, providerEgressReceipts }
+        : undefined;
+    const diagnosticReceiptV2 = {
+        version: 2,
+        runId: run.id,
+        route: run.route,
+        status: run.status,
+        telemetry,
+        providerEgressReceiptFingerprints: providerEgressReceipts.map((receipt) => executionFingerprint(stableExecutionValue(receipt))),
+        ...(run.diagnosticReceiptV2?.repairCapabilityFingerprint
+            ? { repairCapabilityFingerprint: run.diagnosticReceiptV2.repairCapabilityFingerprint }
+            : {}),
+    };
+    const artifacts = run.artifacts.map((artifact) => {
+        if (!artifact.payload || typeof artifact.payload !== 'object' || Array.isArray(artifact.payload))
+            return artifact;
+        const payload = artifact.payload;
+        if (!('diagnosticReceipt' in payload) && !('diagnosticReceiptV2' in payload))
+            return artifact;
+        return {
+            ...artifact,
+            payload: {
+                ...payload,
+                ...(diagnosticReceipt ? { diagnosticReceipt } : {}),
+                diagnosticReceiptV2,
+            },
+        };
+    });
+    return {
+        ...run,
+        artifacts,
+        providerEgressReceipts,
+        telemetry,
+        ...(diagnosticReceipt ? { diagnosticReceipt } : {}),
+        diagnosticReceiptV2,
+    };
+}
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
@@ -945,6 +1356,11 @@ export async function startLocalServer(opts) {
     if (gitRoot)
         ensureLocalRuntimeGitignore(projectRoot);
     let projectConfig = loadProjectConfig(projectRoot);
+    const analyticalExecutionService = new ExecutionService({
+        executor,
+        projectRoot,
+        projectConfig: () => projectConfig,
+    });
     recordAgentRuntimeVersion(projectRoot, runtimeVersion);
     // A clone carries governed Hint Graph files in Git, never the rebuildable
     // `.dql/cache` database. Materialize that projection as soon as the Notebook
@@ -1566,23 +1982,81 @@ export async function startLocalServer(opts) {
     };
     // Provider-backed narration for stakeholder stories. Reuses the same provider
     // adapter as the planner; narrateResult always returns (deterministic fallback).
-    const narrateForAgentRun = async (input) => narrateResult(input, {
-        complete: async ({ system, user, signal }) => {
-            const provider = await createBlockStudioAssistProvider(projectRoot);
-            if (!provider)
-                throw new Error('No AI provider configured for narration.');
-            return provider.generate([{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 600, temperature: 0.2, signal });
-        },
-    });
+    const narrateForAgentRun = async (input, allowProviderResultRows = false) => {
+        // Without caller consent, keep narration deterministic and make no physical
+        // provider dispatch. With consent, serialize only the bounded, redacted
+        // sample the transport receipt will account for — bounded by the project's
+        // own egress policy, so an admin kill-switch is not silently bypassed here.
+        if (!allowProviderResultRows || !input.result)
+            return narrateResult(input);
+        const narrationRowEgress = resolveProviderResultRowEgressPolicy({
+            projectSetting: projectConfig?.agent?.providerResultRowEgress,
+        });
+        if (narrationRowEgress.maxNarrationRows === 0)
+            return narrateResult(input);
+        const safeResult = {
+            ...input.result,
+            rows: redactProviderResultRows(input.result.rows, narrationRowEgress.maxNarrationRows),
+        };
+        const safeInput = {
+            ...input,
+            result: safeResult,
+        };
+        return narrateResult(safeInput, {
+            complete: async ({ system, user, signal }) => {
+                const provider = await createBlockStudioAssistProvider(projectRoot);
+                if (!provider)
+                    throw new Error('No AI provider configured for narration.');
+                return provider.generate([{ role: 'system', content: system }, { role: 'user', content: user }], {
+                    maxTokens: 600,
+                    temperature: 0.2,
+                    signal,
+                    maxProviderDispatches: 2,
+                    ...(agentRunProviderEvidenceContext.getStore() ? {
+                        // This lane narrates App/notebook results, not Research. It used to
+                        // declare `research_narration` to clear the row check, which made
+                        // receipt analytics conflate two different lanes.
+                        onProviderDispatch: (event) => agentRunProviderEvidenceContext.getStore().observe(event, {
+                            purpose: 'answer_narration',
+                            dispatchPhase: 'narration',
+                            optIn: true,
+                            serializedResultShape: {
+                                resultRowCount: safeResult.rows.length,
+                                columnCount: safeResult.columns.length,
+                            },
+                            cumulativeResultRowCount: safeResult.rows.length,
+                        }),
+                    } : {}),
+                });
+            },
+        });
+    };
     async function runGovernedAgentAnswerForRun(request, repair, route = 'generated_answer', onProgress, routeDecision) {
         const governed = resolveGovernedAnswerRunner(projectRoot);
-        const resolvedProvider = governed?.provider ?? null;
-        const runner = governed?.runner ?? null;
+        let resolvedProvider = governed?.provider ?? null;
+        let runner = governed?.runner ?? null;
+        const exactProviderFreePlan = routeDecision?.resolvedAnalyticalPlan?.mode === 'authoritative'
+            && (routeDecision.resolvedAnalyticalPlan.capability === 'certified_execution'
+                || routeDecision.resolvedAnalyticalPlan.capability === 'semantic_execution');
+        if ((!resolvedProvider || !runner) && exactProviderFreePlan) {
+            const deterministicProvider = {
+                name: 'ollama',
+                available: async () => true,
+                generate: async () => {
+                    throw Object.assign(new Error('Exact certified/semantic execution must not dispatch a provider.'), {
+                        code: 'EXACT_ROUTE_PROVIDER_DISPATCH_FORBIDDEN',
+                    });
+                },
+            };
+            resolvedProvider = 'ollama';
+            runner = createDqlAgentProviderRunner('ollama', deterministicProvider);
+        }
         if (!resolvedProvider || !runner) {
             throw new Error('No AI provider is configured. Configure a subscription (Claude Code / Codex), OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
         }
         let governedAnswer;
         let providerError;
+        let providerDispatchEvidence;
         const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
         // The chat composer sends a `thinkingMode` (auto/low/medium/high); resolve it
         // into the effort+depth bundle it stands for. An explicit `reasoningEffort` /
@@ -1642,6 +2116,9 @@ export async function startLocalServer(opts) {
         const semanticTableMapping = semanticLayer && semanticConnection
             ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer, projectRoot, semanticConnectionName)
             : undefined;
+        const generatedProposalTargetIdentity = semanticConnection
+            ? await observeWarehouseTargetIdentity(executor, semanticConnection)
+            : undefined;
         const requestedDomain = normalizeAgentRunDomain(agentRunWorkspaceValue(request, 'domain'));
         const requestedPurpose = agentRunWorkspaceValue(request, 'purpose');
         const requestedModelAreaId = agentRunWorkspaceValue(request, 'modelAreaId');
@@ -1659,6 +2136,9 @@ export async function startLocalServer(opts) {
             : undefined;
         await runner.run({
             provider: resolvedProvider,
+            ...(agentRunProviderEvidenceContext.getStore()
+                ? { providerDispatchEvidenceSink: agentRunProviderEvidenceContext.getStore() }
+                : {}),
             messages: [
                 // No-thread fallback path: bound the raw client history so follow-ups
                 // cannot inflate every provider call (8 turns × 4k chars).
@@ -1678,6 +2158,8 @@ export async function startLocalServer(opts) {
             },
             reasoningEffort,
             ...(analysisDepth ? { analysisDepth } : {}),
+            allowProviderSemanticMemberSelection: route === 'research',
+            researchResultRowsOptIn: route === 'research' && request.researchResultRowsOptIn === true,
             projectRoot,
             preparedContextPack: preparedAgentContextPacks.get(request),
             domainContext,
@@ -1799,9 +2281,20 @@ export async function startLocalServer(opts) {
                             : projectConfig.dbt?.projectDir;
                         throw new SemanticRuntimeRequiredError(await explainMissingSemanticRuntime(projectRoot, dbtProjectPath));
                     }
-                    compiledSemanticQueries.set(executionFingerprint(compiled.sql), compiled);
+                    // The semantic bridge freezes the compiler output after trimming
+                    // transport-only surrounding whitespace. Bind the compiler receipt
+                    // and execution lookup to that exact consumed SQL identity.
+                    const governedCompiledSql = compiled.sql.trim();
+                    compiledSemanticQueries.set(executionFingerprint(governedCompiledSql), compiled);
+                    const aggregationCompilerReceipt = buildSemanticAggregationCompilerReceipt({
+                        semanticLayer: semanticLayer,
+                        metricNames: compiled.effectiveRequest.metrics,
+                        compiledSql: governedCompiledSql,
+                        plan: routeDecision?.resolvedAnalyticalPlan,
+                        targetFingerprint: targetBinding?.executionTarget.identityFingerprint,
+                    });
                     return {
-                        sql: compiled.sql,
+                        sql: governedCompiledSql,
                         engine: compiled.engine,
                         selection: {
                             ...selection,
@@ -1814,7 +2307,9 @@ export async function startLocalServer(opts) {
                         trace: {
                             ...compiled.semanticTrace,
                             ...(targetBinding ? { targetBinding } : {}),
+                            ...(aggregationCompilerReceipt ? { aggregationCompilerReceipt } : {}),
                         },
+                        ...(aggregationCompilerReceipt ? { aggregationCompilerReceipt } : {}),
                     };
                 },
             } : {}),
@@ -1827,6 +2322,9 @@ export async function startLocalServer(opts) {
             ...(routeDecision?.resolvedAnalyticalPlan
                 ? { resolvedAnalyticalPlan: routeDecision.resolvedAnalyticalPlan }
                 : {}),
+            ...(generatedProposalTargetIdentity?.identityFingerprint
+                ? { generatedProposalTargetFingerprint: generatedProposalTargetIdentity.identityFingerprint }
+                : {}),
             analyticalReferenceInstant: new Date().toISOString(),
             executeCertifiedBlock: (node, invocation) => executeCertifiedBlockForAgent(node, invocation, semanticConnection, semanticConnectionName),
             executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact, semanticConnection, semanticConnectionName),
@@ -1843,10 +2341,11 @@ export async function startLocalServer(opts) {
             }
             if (turn.kind === 'error') {
                 providerError = turn.message;
+                providerDispatchEvidence = turn.dispatchEvidence;
             }
         }, runSignal);
         if (!governedAnswer) {
-            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
+            throw Object.assign(new Error(providerError ?? 'The AI provider did not return a governed answer.'), ...(providerDispatchEvidence ? [{ providerDispatchEvidence }] : []));
         }
         return governedAnswer;
     }
@@ -2073,7 +2572,11 @@ export async function startLocalServer(opts) {
             surface: 'ask_ai',
         });
         const certified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
-        const semantic = governedAnswer.route?.tier === 'semantic_metric';
+        // A semantic route is governed only when its route-specific aggregation
+        // proof passed. The route label is not authority: treating a blocked or
+        // missing proof as governed caused the CLI to persist a successful badge
+        // even though the answer artifact recorded insufficient context.
+        const semantic = semanticAnswerHasPassedAggregationProof(governedAnswer);
         governedAnswer.dqlArtifact = {
             ...artifact,
             ...(invocation.parameters.length > 0 ? { parameters: invocation.parameters } : {}),
@@ -2082,11 +2585,19 @@ export async function startLocalServer(opts) {
             trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
             ...(governedAnswer.result?.sql ? { compiledSql: governedAnswer.result.sql } : originalSql ? { compiledSql: originalSql } : {}),
             ...(governedAnswer.result?.executionReceipt ? { executionReceipt: governedAnswer.result.executionReceipt } : {}),
+            ...(governedAnswer.result?.executableArtifact ? {
+                executableArtifact: {
+                    ...governedAnswer.result.executableArtifact,
+                    kind: artifact.kind,
+                    trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
+                },
+            } : {}),
         };
         if (governedAnswer.result)
             delete governedAnswer.result.dqlArtifact;
     }
     const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit }) => {
+        const runStartedAtMs = Date.now();
         let governedAnswer;
         try {
             governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route, (message) => emit({ type: 'executor.started', message, route }), routeDecision);
@@ -2222,39 +2733,67 @@ export async function startLocalServer(opts) {
             // Deadline/cancellation propagates to the engine, which renders the
             // graceful "bounded execution deadline" outcome — never a provider error.
             rethrowIfCancelled(error, request.signal);
-            const message = formatAgentRunInfrastructureError(error, 'AI answer provider');
+            const dispatchEvidence = providerDispatchTerminalEvidence(error);
+            const dispatchBudgetExhausted = Boolean((error && typeof error === 'object'
+                && error.code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED')
+                || dispatchEvidence?.fallbackReason === 'orchestration_budget_exhausted');
+            const message = dispatchBudgetExhausted
+                ? 'Ask reached its internal provider-dispatch limit before it froze one executable analytical plan. Nothing was run. Narrow the metric or dimension and retry; this is an orchestration-budget diagnostic, not a provider outage.'
+                : formatAgentRunInfrastructureError(error, 'AI answer provider');
             return {
                 summary: message,
                 status: 'blocked',
                 trustState: 'blocked',
                 stopReason: 'blocked',
-                artifacts: [agentRunArtifact('answer', 'AI answer provider failed', {
+                artifacts: [agentRunArtifact('answer', dispatchBudgetExhausted ? 'Internal orchestration budget exhausted' : 'AI answer provider failed', {
                         kind: 'no_answer',
-                        refusalCode: 'provider_error',
+                        refusalCode: dispatchBudgetExhausted ? 'orchestration_budget_exhausted' : 'provider_error',
                         text: message,
                         answer: message,
                         ...(routeDecision?.resolvedAnalyticalPlan
                             ? { resolvedAnalyticalPlan: routeDecision.resolvedAnalyticalPlan }
                             : {}),
                         providerFailure: {
-                            code: 'AI_PROVIDER_FAILURE',
+                            code: dispatchBudgetExhausted ? 'orchestration_budget_exhausted' : 'AI_PROVIDER_FAILURE',
                             message,
-                            recoverable: true,
+                            recoverable: !dispatchBudgetExhausted,
                         },
                     }, undefined, 'blocked')],
                 evaluations: [
                     agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
-                    agentRunEvaluation('ai-provider', 'AI provider', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
+                    agentRunEvaluation(dispatchBudgetExhausted ? 'orchestration-budget' : 'ai-provider', dispatchBudgetExhausted ? 'Internal orchestration budget' : 'AI provider', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
                 ],
                 nextActions: [
-                    { id: 'retry-ask-after-provider', label: 'Retry after provider setup', route: 'generated_answer' },
-                    { id: 'research-without-answer', label: 'Research with available metadata', route: 'research', artifactKind: 'research_run' },
+                    ...(dispatchBudgetExhausted
+                        ? [{ id: 'narrow-and-retry-ask', label: 'Narrow the metric or dimension and retry', route: 'generated_answer' }]
+                        : [
+                            { id: 'retry-ask-after-provider', label: 'Retry after provider setup', route: 'generated_answer' },
+                            { id: 'research-without-answer', label: 'Research with available metadata', route: 'research', artifactKind: 'research_run' },
+                        ]),
                 ],
+                ...(dispatchEvidence?.providerEgressReceipts.length
+                    ? { providerEgressReceipts: dispatchEvidence.providerEgressReceipts }
+                    : {}),
+                telemetry: {
+                    version: 1,
+                    stageDurationsMs: { total: Date.now() - runStartedAtMs },
+                    providerRoundTrips: dispatchEvidence?.providerRoundTrips ?? 0,
+                    toolCalls: dispatchEvidence?.toolCalls ?? 0,
+                    sqlExecutions: dispatchEvidence?.sqlExecutions ?? 0,
+                    repairs: Math.max(attempt, dispatchEvidence?.repairs ?? 0),
+                    egressReceipts: dispatchEvidence?.providerEgressReceipts.length ?? 0,
+                    fallbackReason: dispatchBudgetExhausted
+                        ? 'provider_dispatch_budget_exhausted'
+                        : dispatchEvidence?.fallbackReason ?? 'provider_error',
+                },
             };
         }
         const answeredRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
-        const isSemantic = governedAnswer.route?.tier === 'semantic_metric';
+        const semanticRouteClaimed = governedAnswer.route?.tier === 'semantic_metric';
+        const semanticAggregationProofPassed = semanticAnswerHasPassedAggregationProof(governedAnswer);
+        const semanticAggregationBlocked = semanticRouteClaimed && !semanticAggregationProofPassed;
+        const isSemantic = semanticRouteClaimed && semanticAggregationProofPassed;
         const requestedNotebookDataset = findMentionedNotebookDataset(request.question, datasetWorkspace.list());
         const governedAssetMissesLocalSource = Boolean(requestedNotebookDataset && (isCertified
             || isSemantic
@@ -2271,7 +2810,8 @@ export async function startLocalServer(opts) {
         // governance boundary, not an ambiguous user question and not a repairable
         // retrieval miss. Keep the precise policy detail visible, but never burn two
         // more provider calls retrying the same incompatible candidate.
-        const isPolicyBlocked = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'policy_blocked';
+        const isPolicyBlocked = (governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'policy_blocked')
+            || semanticAggregationBlocked;
         const isTerminalFailure = isProviderError || isExecutionFailure || isAnalyticalFailure || isPolicyBlocked;
         // The model tried to compose a governed query and declined despite having usable
         // context (e.g. it wasn't confident about a multi-table join). The answer loop
@@ -2290,48 +2830,137 @@ export async function startLocalServer(opts) {
         // reply ran context-free and was clarified again: the reported clarify loop.
         const resolvedRoute = needsClarification ? 'clarify' : answeredRoute;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
-        const runnableSql = governedAnswer.kind === 'no_answer' || isExecutionFailure || (isExploratory && !governedAnswer.result)
+        const runnableSql = governedAnswer.kind === 'no_answer'
+            || isExecutionFailure
+            || semanticAggregationBlocked
+            || (isExploratory && !governedAnswer.result)
             ? undefined
             : sql;
-        // Render executed rows deterministically for ordinary lookups. A second LLM
-        // call is reserved for an explicit research route; certified, semantic, and
-        // generated lookup answers must not pay another provider round-trip merely
-        // to restate values the host already has.
+        // Narrate any run that actually produced values. This used to be gated on
+        // `requestedMode === 'research'`, and because the UI sends ordinary Ask as
+        // `'auto'`, every normal question skipped synthesis and shipped the answer
+        // loop's deterministic fact-join as the primary answer — the reported
+        // `column: value` dump. A model that never sees the result cannot describe
+        // it, so a bounded, redacted row sample goes with the request unless a
+        // project admin has switched row egress off.
         let synthesizedAnswer;
-        if (shouldSynthesizeAgentRunAnswer(governedAnswer)) {
+        const providerEgressReceipts = [
+            ...(governedAnswer.providerEgressReceipts ?? []),
+        ];
+        let narrationDurationMs = 0;
+        const researchRowsOptIn = route === 'research' && request.researchResultRowsOptIn === true;
+        const rowEgress = resolveProviderResultRowEgressPolicy({
+            projectSetting: projectConfig?.agent?.providerResultRowEgress,
+            researchOptIn: researchRowsOptIn,
+        });
+        // `createBlockStudioAssistProvider` returns null when no AI provider is
+        // configured; a narration failure must never take the governed answer down.
+        const narrationProvider = await createBlockStudioAssistProvider(projectRoot).catch(() => null);
+        const narrationPlan = planAgentRunNarration(governedAnswer, {
+            requestedMode: request.requestedMode,
+            providerAvailable: Boolean(narrationProvider),
+            rowEgress,
+        });
+        const narrationMaxRows = narrationPlan.mode === 'skip' ? 0 : narrationPlan.maxRows;
+        const preview = agentResultToSynthesisPreview(governedAnswer.result);
+        const providerPreview = preview
+            ? { ...preview, rows: redactProviderResultRows(preview.rows, narrationMaxRows) }
+            : undefined;
+        let narrationSource;
+        let narrationValidationFailures = [];
+        if (narrationPlan.mode !== 'skip' && narrationProvider) {
+            const narrationStartedAtMs = Date.now();
+            const draft = governedAnswer.answer ?? governedAnswer.text;
+            const observeNarrationDispatch = (event) => agentRunProviderEvidenceContext.getStore().observe(event, {
+                purpose: 'answer_narration',
+                dispatchPhase: 'narration',
+                optIn: narrationMaxRows > 0,
+                serializedResultShape: {
+                    resultRowCount: providerPreview?.rows.length ?? 0,
+                    columnCount: providerPreview?.columns.length ?? 0,
+                },
+            });
+            const narrationDispatchOptions = () => ({
+                maxTokens: 350,
+                temperature: 0.3,
+                maxProviderDispatches: 2,
+                ...(agentRunProviderEvidenceContext.getStore()
+                    ? { onProviderDispatch: observeNarrationDispatch }
+                    : {}),
+            });
             try {
-                const provider = route === 'research'
-                    ? await createBlockStudioAssistProvider(projectRoot)
-                    : null;
-                const preview = agentResultToSynthesisPreview(governedAnswer.result);
-                const draft = governedAnswer.answer ?? governedAnswer.text;
-                const result = await synthesizeAnswer({
-                    question: request.question,
-                    category: routeDecision?.category,
-                    // The primary Ask reply is always business-facing. Analysts keep
-                    // the full DQL, SQL, lineage, gates, and grain in the inspector.
-                    audience: 'stakeholder',
-                    resultPreview: preview,
-                    sql: sql,
-                    draftText: draft,
-                    gaps: businessNarrativeGaps(governedAnswer.validationWarnings),
-                    rankingDirection: governedAnswer.contextPack?.questionPlan.requestedShape.rankingDirection,
-                    // Governed display contract: metric/measure displayFormat metadata
-                    // beats column-name guessing, so $ and decimals stay consistent
-                    // between the narration and the table for names like total_bcm.
-                    ...(preview ? { columnFormats: agentColumnDisplayFormats(projectRoot, preview.columns) } : {}),
-                }, provider
-                    ? {
-                        complete: ({ system, user, signal, onDelta }) => streamOrGenerate(provider, [{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 350, temperature: 0.3, signal }, onDelta ?? (() => { })),
-                    }
-                    : {});
-                if (result.text)
-                    synthesizedAnswer = result.text;
+                const frame = governedAnswer.resolvedAnalyticalPlan?.analyticalFrame;
+                if (narrationPlan.mode === 'verified_facts' && governedAnswer.analyticalFacts && frame) {
+                    // The fact set is the grounding contract: the model drafts, and every
+                    // claim is resolved against a fact id before it can reach the user.
+                    const composed = await composeVerifiedAnalyticalNarrative({
+                        frame,
+                        factSet: governedAnswer.analyticalFacts,
+                        question: request.question,
+                        maxRows: narrationPlan.maxRows,
+                        complete: async ({ system, user }) => streamOrGenerate(narrationProvider, [{ role: 'system', content: system }, { role: 'user', content: user }], narrationDispatchOptions(), () => { }),
+                    });
+                    narrationSource = composed.source;
+                    narrationValidationFailures = composed.validationFailures;
+                    synthesizedAnswer = composed.source === 'llm'
+                        ? composed.narrative.text
+                        // A verification failure is not silent: the deterministic join is a
+                        // fallback, and the reader is told so rather than handed a dump that
+                        // looks like it was written on purpose.
+                        : `_Verified narration was unavailable, so this is the deterministic result record._\n\n${composed.narrative.text}`;
+                }
+                else {
+                    const result = await synthesizeAnswer({
+                        question: request.question,
+                        category: routeDecision?.category,
+                        // The primary Ask reply is always business-facing. Analysts keep
+                        // the full DQL, SQL, lineage, gates, and grain in the inspector.
+                        audience: 'stakeholder',
+                        resultPreview: providerPreview ?? preview,
+                        sql: sql,
+                        draftText: draft,
+                        gaps: businessNarrativeGaps(governedAnswer.validationWarnings),
+                        rankingDirection: governedAnswer.contextPack?.questionPlan.requestedShape.rankingDirection,
+                        // Governed display contract: metric/measure displayFormat metadata
+                        // beats column-name guessing, so $ and decimals stay consistent
+                        // between the narration and the table for names like total_bcm.
+                        ...(preview ? { columnFormats: agentColumnDisplayFormats(projectRoot, preview.columns) } : {}),
+                    }, {
+                        complete: ({ system, user, signal, onDelta }) => streamOrGenerate(narrationProvider, [{ role: 'system', content: system }, { role: 'user', content: user }], { ...narrationDispatchOptions(), signal }, onDelta ?? (() => { })),
+                    });
+                    narrationSource = result.source;
+                    if (result.text)
+                        synthesizedAnswer = result.text;
+                }
             }
             catch {
-                // Keep the governed draft on any synthesis failure.
+                // Keep the governed draft on any narration failure.
                 synthesizedAnswer = undefined;
             }
+            finally {
+                narrationDurationMs = Date.now() - narrationStartedAtMs;
+            }
+        }
+        // Every run accounts for its narration egress, including the runs that did
+        // not narrate — "no receipt" must never be ambiguous between "no rows left
+        // the host" and "nobody looked".
+        {
+            const narrated = narrationSource !== undefined;
+            const rowsSent = narrated ? providerPreview?.rows.length ?? 0 : 0;
+            providerEgressReceipts.push(createProviderEgressReceipt({
+                purpose: 'answer_narration',
+                provider: narrated ? narrationProvider?.name ?? 'none' : 'none',
+                permittedCategories: rowsSent > 0
+                    ? ['instructions', 'question', 'governed_context', 'result_rows']
+                    : ['instructions', 'question', 'governed_context'],
+                optIn: rowsSent > 0,
+                redactionPolicyId: rowEgress.policyId,
+                payload: narrated
+                    ? { question: request.question, resultPreview: rowsSent > 0 ? providerPreview : undefined }
+                    : { resultRows: 0, providerDisabled: !narrationProvider },
+                resultRowCount: rowsSent,
+                columnCount: narrated ? providerPreview?.columns.length ?? 0 : 0,
+            }));
         }
         // A grounding/modeling gap is a REFUSAL. It was computed above but never
         // reached this ternary, so it fell through to `needs_review` — the same
@@ -2415,9 +3044,21 @@ export async function startLocalServer(opts) {
                                 artifactKind: 'sql_cell',
                             }] : []),
                     ];
+        const runDispatchEvidence = agentRunProviderEvidenceContext.getStore()?.snapshot(governedAnswer.refusalCode ?? 'none');
+        const finalProviderEgressReceipts = runDispatchEvidence?.providerEgressReceipts
+            ?? providerEgressReceipts;
+        const finalTelemetry = agentRunTelemetryForAnswer(governedAnswer, finalProviderEgressReceipts, Date.now() - runStartedAtMs, narrationDurationMs, attempt);
+        if (runDispatchEvidence) {
+            finalTelemetry.providerRoundTrips = runDispatchEvidence.providerRoundTrips;
+            finalTelemetry.egressReceipts = finalProviderEgressReceipts.length;
+        }
         return {
             resolvedRoute,
-            answerRefusalCode: governedAnswer.kind === 'no_answer' ? governedAnswer.refusalCode : undefined,
+            answerRefusalCode: governedAnswer.kind === 'no_answer'
+                ? governedAnswer.refusalCode
+                : semanticAggregationBlocked
+                    ? 'policy_blocked'
+                    : undefined,
             answerTier: governedAnswer.route?.tier,
             summary: isTerminalFailure
                 ? analyticalFailureSummary(governedAnswer.analyticalFailure)
@@ -2477,7 +3118,9 @@ export async function startLocalServer(opts) {
                         : needsClarification
                             ? 'The answer loop needs more context before producing a governed answer.'
                             : isPolicyBlocked
-                                ? `DQL blocked the generated path under its relationship policy: ${governedAnswer.refusalDetails?.message ?? 'the relationship is not authorized for this analysis.'}`
+                                ? semanticAggregationBlocked
+                                    ? `DQL blocked semantic execution because its exact aggregation proof did not pass: ${governedAnswer.aggregationSafetyProof?.issueCodes.join(', ') || 'required proof evidence is missing.'}`
+                                    : `DQL blocked the generated path under its relationship policy: ${governedAnswer.refusalDetails?.message ?? 'the relationship is not authorized for this analysis.'}`
                                 : isExploratory
                                     ? 'The answer used bounded DBT/schema evidence because no certified modeled relationship path covered the request. It is review-required and was not certified.'
                                     : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
@@ -2503,10 +3146,13 @@ export async function startLocalServer(opts) {
                     },
                 ] : []),
                 ...(isPolicyBlocked ? [
-                    agentRunEvaluation('relationship-policy', 'Relationship policy', false, 'warning', governedAnswer.refusalDetails?.message
-                        ?? 'The selected relationship is not authorized for this analysis.', {
+                    agentRunEvaluation(semanticAggregationBlocked ? 'aggregation-safety-proof' : 'relationship-policy', semanticAggregationBlocked ? 'Aggregation safety proof' : 'Relationship policy', false, semanticAggregationBlocked ? 'blocking' : 'warning', semanticAggregationBlocked
+                        ? `Semantic execution was refused because the exact aggregation proof did not pass: ${governedAnswer.aggregationSafetyProof?.issueCodes.join(', ') || 'required proof evidence is missing.'}`
+                        : governedAnswer.refusalDetails?.message
+                            ?? 'The selected relationship is not authorized for this analysis.', {
                         refusalCode: governedAnswer.refusalCode,
                         refusalDetails: governedAnswer.refusalDetails,
+                        aggregationSafetyProof: governedAnswer.aggregationSafetyProof,
                         validationWarnings: governedAnswer.validationWarnings,
                         route: governedAnswer.route,
                     }),
@@ -2516,6 +3162,8 @@ export async function startLocalServer(opts) {
                 ] : []),
             ],
             nextActions,
+            providerEgressReceipts: finalProviderEgressReceipts,
+            telemetry: finalTelemetry,
         };
     };
     const conversationRunExecutor = async ({ request, routeDecision, emitAnswerDelta }) => {
@@ -2549,13 +3197,28 @@ export async function startLocalServer(opts) {
                         ...(request.history ?? []).slice(-6).map((message) => ({ role: message.role, content: message.text })),
                         { role: 'user', content: request.question },
                     ];
-                    text = (await provider.generate(messages, { maxTokens: 320, temperature: 0.6 })).trim();
+                    text = (await provider.generate(messages, {
+                        maxTokens: 320,
+                        temperature: 0.6,
+                        maxProviderDispatches: 2,
+                        ...(agentRunProviderEvidenceContext.getStore() ? {
+                            onProviderDispatch: (event) => agentRunProviderEvidenceContext.getStore().observe(event, {
+                                purpose: 'answer_generation',
+                                dispatchPhase: 'generation',
+                                optIn: false,
+                            }),
+                        } : {}),
+                    })).trim();
                     // Perceived-latency: surface the reply as one delta for surfaces wired to stream.
                     if (text)
                         emitAnswerDelta?.(text);
                 }
             }
-            catch {
+            catch (error) {
+                if (error && typeof error === 'object'
+                    && error.code === 'PROVIDER_DISPATCH_BUDGET_EXHAUSTED') {
+                    throw error;
+                }
                 // Provider unavailable / errored — fall through to the deterministic reply.
                 text = undefined;
             }
@@ -3094,7 +3757,7 @@ export async function startLocalServer(opts) {
                     result: researchResultData,
                     evidence: plan.sources,
                     reviewRequired: true,
-                })
+                }, request.researchResultRowsOptIn === true)
                 : undefined;
             const summary = needsClarification
                 ? 'Needs clarification before running deeper research.'
@@ -3609,7 +4272,19 @@ export async function startLocalServer(opts) {
             return provider.generate([
                 { role: 'system', content: system },
                 { role: 'user', content: user },
-            ], { maxTokens: 700, temperature: 0.1, signal });
+            ], {
+                maxTokens: 700,
+                temperature: 0.1,
+                signal,
+                maxProviderDispatches: 2,
+                ...(agentRunProviderEvidenceContext.getStore() ? {
+                    onProviderDispatch: (event) => agentRunProviderEvidenceContext.getStore().observe(event, {
+                        purpose: 'answer_generation',
+                        dispatchPhase: 'planning',
+                        optIn: false,
+                    }),
+                } : {}),
+            });
         },
         getCatalogContext: buildRankedAgentRunCatalogContext,
     });
@@ -3633,6 +4308,14 @@ export async function startLocalServer(opts) {
                 // instead of leaving the UI in "Generating and validating SQL" for a
                 // minute or more.
                 signal: boundedAgentMeaningSignal(signal),
+                maxProviderDispatches: 1,
+                ...(agentRunProviderEvidenceContext.getStore() ? {
+                    onProviderDispatch: (event) => agentRunProviderEvidenceContext.getStore().observe(event, {
+                        purpose: 'answer_generation',
+                        dispatchPhase: 'meaning_resolution',
+                        optIn: false,
+                    }),
+                } : {}),
             });
         },
         getEvidence: buildAgentRunEvidence,
@@ -3649,6 +4332,8 @@ export async function startLocalServer(opts) {
     // A run may outlive its streaming browser connection, so cancellation is
     // server-owned and keyed by run id rather than relying on fetch abort alone.
     const activeAgentRunControllers = new Map();
+    const activeAnalyticalRepairReservations = new Set();
+    const consumedAnalyticalRepairCapabilities = new Set();
     // Server-side conversation threads: persisted multi-turn state (survives refresh).
     // Lazy so a failed native-sqlite load never blocks the runtime; conversation
     // persistence degrades to the per-request context instead.
@@ -3739,14 +4424,21 @@ export async function startLocalServer(opts) {
                         snapshotCells.push({ cellId, status: 'idle', executionCount: 0, executedAt });
                         continue;
                     }
-                    const prepared = prepareLocalExecution(executableSql, activeConnection, projectRoot, projectConfig);
                     assertAppAccess({ app, domain: resolved.domain ?? app.domain, level: 'execute' });
-                    const rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), prepared.connection);
-                    const result = normalizeQueryResult(rawResult);
+                    const execution = await analyticalExecutionService.execute({
+                        sql: executableSql,
+                        subject: 'App notebook query',
+                        connection: activeConnection,
+                        sqlParams: plan?.sqlParams,
+                        variables: plan?.variables,
+                    });
+                    const result = execution.result;
                     snapshotCells.push({
                         cellId,
                         status: 'success',
                         result,
+                        compiledSqlFingerprint: execution.compiledSqlFingerprint,
+                        resultFingerprint: execution.resultFingerprint,
                         executionCount: 1,
                         executedAt,
                     });
@@ -3835,44 +4527,81 @@ export async function startLocalServer(opts) {
             const semanticError = semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message;
             throw analyticalError(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`, { origin: 'dql_compilation', stage: 'compile' });
         }
-        const preparation = await prepareAnalyticalExecutionSql({
+        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
+        const sourceDomain = metadata.domain ?? source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
+        assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
+        const pinnedSemanticCompile = semanticCompose?.sql
+            ? compiledSemanticQueries.get(executionFingerprint(semanticCompose.sql))
+            : undefined;
+        const semanticExecutionHolder = { value: null };
+        const execution = await analyticalExecutionService.execute({
             sql: semanticCompose?.sql ?? plan.sql,
             subject: 'DQL artifact query',
-            executor,
             connection: activeConnection,
-            projectRoot,
-            projectConfig,
             // Preserve the existing contract: previewed Ask artifacts are explicitly
             // read-only and bounded; saved/manual DQL execution keeps its compiler-
             // governed behavior when no preview bound was requested.
             enforceReadOnly: invocationInput?.rowLimit !== undefined,
             rowLimit: invocationInput?.rowLimit,
+            sqlParams: plan?.sqlParams,
+            variables: { ...(plan?.variables ?? {}), ...invocation.values },
+            executePrepared: async (preparation) => {
+                if (pinnedSemanticCompile) {
+                    const semanticExecution = await executeTargetBoundSemanticQuery({
+                        executor,
+                        connection: activeConnection,
+                        projectRoot,
+                        plannedAdapter: pinnedSemanticCompile.engine,
+                        metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
+                            ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                            : undefined,
+                        compile: async () => pinnedSemanticCompile,
+                        prepareSql: () => ({ sql: preparation.executedSql, connection: preparation.connection }),
+                        rowBound: invocationInput?.rowLimit ?? pinnedSemanticCompile.effectiveRequest.limit,
+                    });
+                    if (semanticExecution) {
+                        semanticExecutionHolder.value = semanticExecution;
+                        return semanticExecution.result;
+                    }
+                }
+                return executor.executeQuery(preparation.executedSql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), preparation.connection);
+            },
         });
-        const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
+        const semanticExecution = semanticExecutionHolder.value;
+        const { preparation, result: normalized } = execution;
         const executionSql = preparation.executedSql;
-        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
-        const sourceDomain = metadata.domain ?? source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
-        assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
-        const pinnedSemanticCompile = semanticCompose?.sql
-            ? compiledSemanticQueries.get(executionFingerprint(semanticCompose.sql))
-            : undefined;
-        const semanticExecution = pinnedSemanticCompile
-            ? await executeTargetBoundSemanticQuery({
-                executor,
-                connection: activeConnection,
-                projectRoot,
-                plannedAdapter: pinnedSemanticCompile.engine,
-                metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
-                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
-                    : undefined,
-                compile: async () => pinnedSemanticCompile,
-                prepareSql: () => ({ sql: executionSql, connection: prepared.connection }),
-                rowBound: invocationInput?.rowLimit ?? pinnedSemanticCompile.effectiveRequest.limit,
-            })
-            : null;
-        const rawResult = semanticExecution?.result ?? await executor.executeQuery(executionSql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
-        const normalized = normalizeQueryResult(rawResult);
         const executionReceipt = createDqlArtifactExecutionReceipt(source, executionSql, invocation.values, normalized);
+        const executableArtifact = {
+            version: 1,
+            kind: precompiledSemanticQuery || semanticCompose?.sql ? 'semantic_block' : 'sql_block',
+            dqlFingerprint: executionFingerprint(source),
+            sourceFingerprint: executionFingerprint(stableExecutionValue({
+                name: metadata.name ?? null,
+                path: metadata.path ?? null,
+                domain: sourceDomain ?? null,
+            })),
+            compiledSqlFingerprint: executionFingerprint(semanticCompose?.sql ?? plan?.sql ?? preparation.sourceSql),
+            normalizedSqlFingerprint: executionFingerprint(preparation.decodedSql),
+            parameterFingerprint: executionReceipt.parameterFingerprint,
+            provenanceFingerprint: executionFingerprint(stableExecutionValue(invocation.resolvedParameters.map((parameter) => ({
+                name: parameter.name,
+                source: parameter.source,
+            })))),
+            targetFingerprint: targetGenerationFingerprint(activeConnection, executionConnectionName),
+            snapshotFingerprint: executionFingerprint(projectSnapshot().snapshotId),
+            planFingerprint: executionFingerprint(stableExecutionValue({
+                sqlFingerprint: executionFingerprint(semanticCompose?.sql ?? plan?.sql ?? preparation.sourceSql),
+                parameterCount: plan?.sqlParams?.length ?? 0,
+                variableNames: Object.keys(plan?.variables ?? {}).sort(),
+                chartConfig: plan?.chartConfig ?? null,
+            })),
+            semanticAdapter: pinnedSemanticCompile?.engine ?? 'native',
+            previewPolicy: invocationInput?.rowLimit === undefined
+                ? { mode: 'compiler_governed' }
+                : { mode: 'read_only_bounded', rowLimit: invocationInput.rowLimit },
+            trustState: 'review_required',
+            receipt: executionReceipt,
+        };
         return {
             columns: normalized.columns,
             rows: normalized.rows,
@@ -3885,6 +4614,7 @@ export async function startLocalServer(opts) {
             parameters: invocation.resolvedParameters,
             auditId: invocation.auditId,
             executionReceipt,
+            executableArtifact,
             ...(semanticExecution ? {
                 semanticExecutionReceipt: semanticExecution.executionReceipt,
                 semanticTargetBinding: semanticExecution.targetBinding,
@@ -3919,6 +4649,9 @@ export async function startLocalServer(opts) {
                 trustState: 'certified',
                 compiledSql: result.sql,
                 executionReceipt: result.executionReceipt,
+                ...(result.executableArtifact ? {
+                    executableArtifact: { ...result.executableArtifact, kind: 'certified_block', trustState: 'certified' },
+                } : {}),
                 ...(invocationInput?.rowLimit ? { limit: invocationInput.rowLimit } : {}),
                 ...(invocationInput?.parameters && Object.keys(invocationInput.parameters).length > 0
                     ? { parameterValues: invocationInput.parameters }
@@ -3960,6 +4693,7 @@ export async function startLocalServer(opts) {
                 ...(Object.keys(invocation.values).length > 0 ? { parameterValues: invocation.values } : {}),
                 compiledSql: result.sql,
                 executionReceipt: result.executionReceipt,
+                ...(result.executableArtifact ? { executableArtifact: result.executableArtifact } : {}),
             },
         };
     };
@@ -4036,7 +4770,7 @@ export async function startLocalServer(opts) {
      * string, so the only remaining reasons to differ are the connection and the
      * governance gates, both of which report themselves honestly.
      */
-    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection, bindings) => {
+    const executeGeneratedSqlDirect = async (question, sql, seed, executionConnection, bindings, executionConnectionName) => {
         const activeConnection = requireActiveConnection(executionConnection);
         const rowBound = clampAnalyticalRowBound(seed?.limit ?? 200);
         const trimmed = sql.trim().replace(/;\s*$/, '').trim();
@@ -4058,18 +4792,6 @@ export async function startLocalServer(opts) {
         if (semantic.unresolvedRefs.length > 0) {
             throw analyticalError(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`, { origin: 'dql_compilation', stage: 'compile', code: 'semantic_ref' });
         }
-        const preparation = await prepareAnalyticalExecutionSql({
-            sql: semantic.sql,
-            subject: 'Generated SQL',
-            executor,
-            connection: activeConnection,
-            projectRoot,
-            projectConfig,
-            enforceReadOnly: true,
-            rowLimit: rowBound,
-        });
-        const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
-        const bounded = preparation.rowBound;
         const app = loadRuntimeApp(projectRoot, activePersonaAppId());
         // Generated SQL is governed as 'uncategorized' unless its seed declares a
         // domain — the same value `generatedSqlArtifactContract` stamps into the
@@ -4080,25 +4802,43 @@ export async function startLocalServer(opts) {
         assertAppAccess({ app, domain: sourceDomain, level: 'execute' });
         // A semantic query the loop already compiled (MetricFlow / dbt Cloud) must
         // execute through its pinned target binding, not as loose SQL.
-        const pinnedSemanticCompile = compiledSemanticQueries.get(executionFingerprint(prepared.sql))
-            ?? compiledSemanticQueries.get(executionFingerprint(trimmed));
-        const semanticExecution = pinnedSemanticCompile
-            ? await executeTargetBoundSemanticQuery({
-                executor,
-                connection: activeConnection,
-                projectRoot,
-                plannedAdapter: pinnedSemanticCompile.engine,
-                metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
-                    ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
-                    : undefined,
-                compile: async () => pinnedSemanticCompile,
-                prepareSql: () => ({ sql: bounded.sql, connection: prepared.connection }),
-                rowBound,
-            })
-            : null;
-        const rawResult = semanticExecution?.result
-            ?? await executor.executeQuery(preparation.executedSql, bindings?.sqlParams ?? [], runtimeVariables(bindings?.variables ?? {}), preparation.connection);
-        const normalized = normalizeQueryResult(rawResult, semantic.semanticRefs);
+        const semanticExecutionHolder = { value: null };
+        const execution = await analyticalExecutionService.execute({
+            sql: semantic.sql,
+            subject: 'Generated SQL',
+            connection: activeConnection,
+            enforceReadOnly: true,
+            rowLimit: rowBound,
+            sqlParams: bindings?.sqlParams,
+            variables: bindings?.variables,
+            semanticRefs: semantic.semanticRefs,
+            executePrepared: async (preparation) => {
+                const pinnedSemanticCompile = compiledSemanticQueries.get(executionFingerprint(preparation.preparedSql))
+                    ?? compiledSemanticQueries.get(executionFingerprint(trimmed));
+                if (pinnedSemanticCompile) {
+                    const semanticExecution = await executeTargetBoundSemanticQuery({
+                        executor,
+                        connection: activeConnection,
+                        projectRoot,
+                        plannedAdapter: pinnedSemanticCompile.engine,
+                        metricFlow: pinnedSemanticCompile.engine === 'metricflow-cli'
+                            ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                            : undefined,
+                        compile: async () => pinnedSemanticCompile,
+                        prepareSql: () => ({ sql: preparation.executedSql, connection: preparation.connection }),
+                        rowBound,
+                    });
+                    if (semanticExecution) {
+                        semanticExecutionHolder.value = semanticExecution;
+                        return semanticExecution.result;
+                    }
+                }
+                return executor.executeQuery(preparation.executedSql, bindings?.sqlParams ?? [], runtimeVariables(bindings?.variables ?? {}), preparation.connection);
+            },
+        });
+        const semanticExecution = semanticExecutionHolder.value;
+        const { preparation, result: normalized } = execution;
+        const bounded = preparation.rowBound;
         // The authoritative bound. `buildRowBoundedSql` may legitimately decline to
         // touch the statement, and only one of 15 drivers honours a maxRows hint, so
         // the host is the only layer correctness may depend on.
@@ -4106,6 +4846,38 @@ export async function startLocalServer(opts) {
         const rows = truncated ? normalized.rows.slice(0, rowBound) : normalized.rows;
         const warnings = [];
         const artifact = buildVerifiedGeneratedArtifact(question, trimmed, bounded.sql, seed, warnings, normalized.columns, activeConnection.driver);
+        const receiptSource = artifact?.source ?? trimmed;
+        const executionBindings = bindings && ((bindings.sqlParams?.length ?? 0) > 0 || Object.keys(bindings.variables ?? {}).length > 0)
+            ? { sqlParams: bindings.sqlParams ?? [], variables: bindings.variables ?? {} }
+            : {};
+        const executionReceipt = createDqlArtifactExecutionReceipt(receiptSource, bounded.sql, executionBindings, { columns: normalized.columns, rows, rowCount: rows.length });
+        const executableArtifact = {
+            version: 1,
+            kind: 'sql_block',
+            dqlFingerprint: executionFingerprint(receiptSource),
+            sourceFingerprint: executionFingerprint(stableExecutionValue({
+                name: artifact?.name ?? seed?.name ?? null,
+                path: artifact?.sourcePath ?? seed?.sourcePath ?? null,
+            })),
+            compiledSqlFingerprint: executionFingerprint(semantic.sql),
+            normalizedSqlFingerprint: executionFingerprint(preparation.decodedSql),
+            parameterFingerprint: executionReceipt.parameterFingerprint,
+            provenanceFingerprint: executionFingerprint(stableExecutionValue({
+                sqlParamCount: bindings?.sqlParams?.length ?? 0,
+                variableNames: Object.keys(bindings?.variables ?? {}).sort(),
+            })),
+            targetFingerprint: targetGenerationFingerprint(activeConnection, executionConnectionName),
+            snapshotFingerprint: executionFingerprint(projectSnapshot().snapshotId),
+            planFingerprint: executionFingerprint(stableExecutionValue({
+                compiledSqlFingerprint: executionFingerprint(semantic.sql),
+                executedSqlFingerprint: executionFingerprint(bounded.sql),
+                rowBound,
+            })),
+            semanticAdapter: semanticExecution?.targetBinding.adapterId ?? 'native',
+            previewPolicy: { mode: 'read_only_bounded', rowLimit: rowBound },
+            trustState: 'review_required',
+            receipt: executionReceipt,
+        };
         return {
             columns: normalized.columns,
             rows,
@@ -4113,9 +4885,10 @@ export async function startLocalServer(opts) {
             executionTime: normalized.executionTime,
             sql: bounded.sql,
             ...(truncated ? { truncated: true } : {}),
-            ...(artifact ? { dqlArtifact: { ...artifact, limit: rowBound } } : {}),
+            ...(artifact ? { dqlArtifact: { ...artifact, limit: rowBound, executionReceipt, executableArtifact } } : {}),
             ...(warnings.length > 0 ? { validationWarnings: warnings } : {}),
-            executionReceipt: createDqlArtifactExecutionReceipt(artifact?.source ?? trimmed, bounded.sql, {}, { columns: normalized.columns, rows, rowCount: rows.length }),
+            executionReceipt,
+            executableArtifact,
         };
     };
     const executeGeneratedArtifactForAgent = async (question, sql, seed, executionConnection, executionConnectionName) => {
@@ -4125,7 +4898,7 @@ export async function startLocalServer(opts) {
         if (seed && seed.kind !== 'sql_block') {
             return executeArtifactReferenceForAgent({ ...seed, limit: seed.limit ?? 200 }, question, executionConnection, executionConnectionName);
         }
-        return executeGeneratedSqlDirect(question, sql, seed, executionConnection);
+        return executeGeneratedSqlDirect(question, sql, seed, executionConnection, undefined, executionConnectionName);
     };
     /**
      * EXP-001: execution host for the deliberately narrow non-governed lane.
@@ -4432,12 +5205,33 @@ export async function startLocalServer(opts) {
      * conversation, writes a DQL file, changes targets, or promotes trust.
      */
     const executeBoundedSqlRepair = async (input) => {
+        let sourceSql = input.sourceSql;
+        let rewrites = [];
+        if (internalRelationIdsInSql(sourceSql).length > 0) {
+            const normalizedSource = await prepareAnalyticalExecutionSql({
+                sql: sourceSql,
+                subject: 'Repair source SQL',
+                executor,
+                connection: input.targetConnection,
+                projectRoot,
+                projectConfig,
+                enforceReadOnly: true,
+            });
+            sourceSql = normalizedSource.decodedSql;
+            rewrites = normalizedSource.rewrites;
+        }
+        const sourceSignature = buildSqlAnalyticalSignature(sourceSql, input.targetConnection.driver);
+        if (!sourceSignature) {
+            throw boundedRepairError('DQL could not prove an immutable analytical signature for the source SQL. Repair it manually.', 409);
+        }
         let result;
-        let repairedSql = input.sourceSql;
+        let repairedSql = sourceSql;
         let repairMode = 'deterministic';
         let firstFailure;
+        const providerEgressReceipts = [];
+        let providerRoundTrips = 0;
         try {
-            result = await executeGeneratedSqlDirect(input.question, input.sourceSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables });
+            result = await executeGeneratedSqlDirect(input.question, sourceSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables }, input.targetConnectionName);
         }
         catch (error) {
             firstFailure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
@@ -4458,50 +5252,89 @@ export async function startLocalServer(opts) {
                 const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
                 throw boundedRepairError(failure.redactedMessage, 422, failure);
             }
-            const boundedSchema = schemaContext.slice(0, 16).map((table) => ({
+            const boundedSchema = markProviderMetadataArray(schemaContext.slice(0, 16).map((table) => ({
                 relation: table.relation,
-                columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
-            }));
+                columns: markProviderMetadataArray(table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type }))),
+            })));
             // CTX-008: a repair that re-derives joins from column names can undo a
             // join the original query got right. Give it the authored key pairs.
-            const governedJoins = governedJoinFactsForRelations(schemaContext.slice(0, 16).map((table) => table.relation));
+            const governedJoins = markProviderMetadataArray(governedJoinFactsForRelations(schemaContext.slice(0, 16).map((table) => table.relation)));
+            const repairPayload = {
+                question: input.question,
+                driver: input.targetConnection.driver,
+                failure: firstFailure.redactedMessage,
+                sql: sourceSql,
+                parameters: input.sqlParams ? markProviderMetadataArray(input.sqlParams.map((parameter) => ({
+                    name: parameter.name,
+                    placeholder: `$${parameter.position}`,
+                }))) : undefined,
+                schema: boundedSchema,
+                ...(governedJoins.length ? { governedJoins } : {}),
+            };
+            const repairMessages = [
+                {
+                    role: 'system',
+                    content: [
+                        'Repair one failed read-only analytical SQL statement.',
+                        'Return exactly one JSON object in a ```json fence with keys summary, sql, viz, outputs.',
+                        'Preserve the requested grain, filters, output columns, and aggregation semantics.',
+                        input.sqlParams?.length
+                            ? 'Preserve every positional parameter placeholder exactly; do not add, remove, or renumber placeholders.'
+                            : '',
+                        'Use only relations and columns present in the supplied schema context.',
+                        'When governedJoins is present, join on those exact key pairs rather than inferring a join from column names.',
+                        'Never emit internal DQL relation identities such as source::, model::, seed::, or snapshot::.',
+                        'Do not add writes, DDL, multiple statements, or commentary outside the JSON fence.',
+                    ].join(' '),
+                },
+                {
+                    role: 'user',
+                    content: JSON.stringify(repairPayload),
+                },
+            ];
+            const repairEnvelope = prepareProviderWireEnvelopeForDispatch(provider.name, { messages: repairMessages });
+            assertProviderPayloadAllowed(repairEnvelope, {
+                allowResultRows: false,
+                maxResultRows: 0,
+                purpose: 'repair_sql',
+            });
             let raw;
             try {
-                raw = await provider.generate([
-                    {
-                        role: 'system',
-                        content: [
-                            'Repair one failed read-only analytical SQL statement.',
-                            'Return exactly one JSON object in a ```json fence with keys summary, sql, viz, outputs.',
-                            'Preserve the requested grain, filters, output columns, and aggregation semantics.',
-                            input.sqlParams?.length
-                                ? 'Preserve every positional parameter placeholder exactly; do not add, remove, or renumber placeholders.'
-                                : '',
-                            'Use only relations and columns present in the supplied schema context.',
-                            'When governedJoins is present, join on those exact key pairs rather than inferring a join from column names.',
-                            'Never emit internal DQL relation identities such as source::, model::, seed::, or snapshot::.',
-                            'Do not add writes, DDL, multiple statements, or commentary outside the JSON fence.',
-                        ].join(' '),
-                    },
-                    {
-                        role: 'user',
-                        content: JSON.stringify({
-                            question: input.question,
-                            driver: input.targetConnection.driver,
-                            failure: firstFailure.redactedMessage,
-                            sql: input.sourceSql,
-                            parameters: input.sqlParams?.map((parameter) => ({
-                                name: parameter.name,
-                                placeholder: `$${parameter.position}`,
-                            })),
-                            schema: boundedSchema,
-                            ...(governedJoins.length ? { governedJoins } : {}),
-                        }),
+                raw = await provider.generate(repairEnvelope.messages, {
+                    maxTokens: 1200,
+                    temperature: 0,
+                    maxProviderDispatches: 2,
+                    onProviderDispatch: (event) => {
+                        const envelope = prepareProviderWireEnvelopeForDispatch(provider.name, event.envelope);
+                        assertProviderPayloadAllowed(envelope, {
+                            allowResultRows: false,
+                            maxResultRows: 0,
+                            purpose: 'repair_sql',
+                        });
+                        providerRoundTrips += 1;
+                        providerEgressReceipts.push(createProviderDispatchEgressReceipt({
+                            purpose: 'repair_sql',
+                            dispatchPhase: 'repair',
+                            provider: provider.name,
+                            permittedCategories: ['instructions', 'question', 'schema_metadata', 'governed_context'],
+                            optIn: false,
+                            envelope,
+                        }));
+                        return envelope;
                     },
-                ], { maxTokens: 1200, temperature: 0 });
+                });
             }
             catch {
-                throw boundedRepairError('The AI provider could not complete this repair. Check Provider Settings and retry.', 502);
+                throw Object.assign(boundedRepairError('The AI provider could not complete this repair. Check Provider Settings and retry.', 502), {
+                    providerDispatchEvidence: {
+                        providerEgressReceipts: [...providerEgressReceipts],
+                        providerRoundTrips,
+                        toolCalls: 0,
+                        sqlExecutions: 0,
+                        repairs: 1,
+                        fallbackReason: 'repair_provider_error',
+                    },
+                });
             }
             const proposal = parseProposal(raw);
             if (!proposal.sql?.trim()) {
@@ -4512,9 +5345,17 @@ export async function startLocalServer(opts) {
             if (requiredPlaceholders.some((placeholder) => !new RegExp(`${placeholder.replace('$', '\\$')}\\b`).test(repairedSql))) {
                 throw boundedRepairError('The repair changed this cell\'s parameter contract, so DQL stopped it before execution.', 422);
             }
+            const repairedSignature = buildSqlAnalyticalSignature(repairedSql, input.targetConnection.driver);
+            if (!repairedSignature || stableExecutionValue(repairedSignature) !== stableExecutionValue(sourceSignature)) {
+                throw boundedRepairError('The provider repair changed or could not prove the immutable analytical plan, so DQL stopped before execution.', 409);
+            }
+            const aggregationProof = buildAggregationSafetyProof(repairedSql, undefined, input.targetConnection.driver);
+            if (aggregationProof.status !== 'safe') {
+                throw boundedRepairError(`The repaired SQL lacks complete aggregation-safety evidence (${aggregationProof.issueCodes.join(', ')}). Repair it manually.`, 409);
+            }
             repairMode = 'ai';
             try {
-                result = await executeGeneratedSqlDirect(input.question, repairedSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables });
+                result = await executeGeneratedSqlDirect(input.question, repairedSql, undefined, input.targetConnection, { sqlParams: input.sqlParams, variables: input.variables }, input.targetConnectionName);
             }
             catch (error) {
                 const failure = normalizeWarehouseSqlFailure(error, input.targetConnection.driver);
@@ -4524,7 +5365,6 @@ export async function startLocalServer(opts) {
         // Keep preview-only row bounds out of editable notebook source. The one
         // deterministic source rewrite we do persist is decoding internal graph
         // identities, because those can never execute as warehouse SQL.
-        let rewrites = [];
         if (internalRelationIdsInSql(repairedSql).length > 0) {
             const normalizedSource = await prepareAnalyticalExecutionSql({
                 sql: repairedSql,
@@ -4536,9 +5376,9 @@ export async function startLocalServer(opts) {
                 enforceReadOnly: true,
             });
             repairedSql = normalizedSource.decodedSql;
-            rewrites = normalizedSource.rewrites;
+            rewrites.push(...normalizedSource.rewrites);
         }
-        return { result, repairedSql, repairMode, firstFailure, rewrites };
+        return { result, repairedSql, repairMode, firstFailure, providerEgressReceipts, providerRoundTrips, rewrites };
     };
     /**
      * Repair a DQL wrapper that cannot compile far enough to expose executable
@@ -4551,6 +5391,8 @@ export async function startLocalServer(opts) {
         if (!provider) {
             throw boundedRepairError('Configure an available AI provider in Settings to repair this DQL draft.', 409);
         }
+        const providerEgressReceipts = [];
+        let providerRoundTrips = 0;
         let schemaContext;
         try {
             // Include source identifiers in retrieval so a terse cell title still
@@ -4596,10 +5438,41 @@ export async function startLocalServer(opts) {
                         ...(governedJoins.length ? { governedJoins } : {}),
                     }),
                 },
-            ], { maxTokens: 2400, temperature: 0 });
+            ], {
+                maxTokens: 2400,
+                temperature: 0,
+                maxProviderDispatches: 2,
+                onProviderDispatch: (event) => {
+                    const envelope = prepareProviderWireEnvelopeForDispatch(provider.name, event.envelope);
+                    assertProviderPayloadAllowed(envelope, {
+                        allowResultRows: false,
+                        maxResultRows: 0,
+                        purpose: 'repair_sql',
+                    });
+                    providerRoundTrips += 1;
+                    providerEgressReceipts.push(createProviderDispatchEgressReceipt({
+                        purpose: 'repair_sql',
+                        dispatchPhase: 'repair',
+                        provider: provider.name,
+                        permittedCategories: ['instructions', 'question', 'schema_metadata', 'governed_context'],
+                        optIn: false,
+                        envelope,
+                    }));
+                    return envelope;
+                },
+            });
         }
         catch {
-            throw boundedRepairError('The AI provider could not complete this DQL repair. Check Provider Settings and retry.', 502);
+            throw Object.assign(boundedRepairError('The AI provider could not complete this DQL repair. Check Provider Settings and retry.', 502), {
+                providerDispatchEvidence: {
+                    providerEgressReceipts: [...providerEgressReceipts],
+                    providerRoundTrips,
+                    toolCalls: 0,
+                    sqlExecutions: 0,
+                    repairs: 1,
+                    fallbackReason: 'repair_provider_error',
+                },
+            });
         }
         let repairedSource;
         try {
@@ -4703,6 +5576,8 @@ export async function startLocalServer(opts) {
             repairedSql: plan.sql,
             repairedSource,
             repairMode: 'ai',
+            providerEgressReceipts,
+            providerRoundTrips,
             rewrites: [],
             sqlParams: plan.sqlParams,
             variables: { ...plan.variables, ...invocation.values },
@@ -5701,11 +6576,18 @@ export async function startLocalServer(opts) {
             tableMapping,
             semanticSql: semanticCompose?.sql ?? undefined,
         });
-        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan?.sql ?? executableSql, activeConnection, projectRoot, projectConfig);
-        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
+        const execution = await analyticalExecutionService.execute({
+            sql: semanticCompose?.sql ?? plan?.sql ?? executableSql,
+            subject: 'Block Studio preview query',
+            connection: activeConnection,
+            sqlParams: plan?.sqlParams,
+            variables: { ...(plan?.variables ?? {}), ...invocation.values },
+        });
         return {
-            sql: prepared.sql,
-            result: normalizeQueryResult(result),
+            sql: execution.preparation.executedSql,
+            result: execution.result,
+            compiledSqlFingerprint: execution.compiledSqlFingerprint,
+            resultFingerprint: execution.resultFingerprint,
             chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
             invocation,
             tests: plan?.tests ?? [],
@@ -5756,12 +6638,14 @@ export async function startLocalServer(opts) {
         if (tests.length === 0) {
             return { passed: 0, failed: 0, skipped: 0, duration: Date.now() - start, assertions: [], runAt: new Date() };
         }
-        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
-        const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams ?? [], runtimeVariables(plan.variables ?? {}), prepared.connection);
-        const rows = Array.isArray(rawResult?.rows) ? rawResult.rows : [];
-        const columns = Array.isArray(rawResult?.columns)
-            ? rawResult.columns.map((column) => typeof column === 'string' ? column : column?.name ?? String(column))
-            : [];
+        const execution = await analyticalExecutionService.execute({
+            sql: semanticCompose?.sql ?? plan.sql,
+            subject: 'Block Studio certification test query',
+            connection: activeConnection,
+            sqlParams: plan.sqlParams,
+            variables: plan.variables,
+        });
+        const { rows, columns } = execution.result;
         return evaluateBlockStudioTests(tests, rows, columns, start);
     };
     const saveDqlGenerationDraft = (importId, candidate) => saveDqlGenerationDraftForProject(projectRoot, importId, candidate);
@@ -7243,23 +8127,81 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'Agent run not found.' }));
                     return;
                 }
+                const capability = normalizeAnalyticalRepairCapabilityV1(sourceRun.repairCapability);
+                if (!capability?.automatic.eligible || capability.automatic.attemptsRemaining < 1) {
+                    const manualActions = capability?.manualActions?.length
+                        ? capability.manualActions
+                        : ['edit_dql', 'open_sql_notebook'];
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        code: 'REPAIR_CAPABILITY_REQUIRED',
+                        error: 'This run does not retain eligible automatic execution-repair authority.',
+                        manualActions,
+                        ...(capability?.ineligibilityReason ? { ineligibilityReason: capability.ineligibilityReason } : {}),
+                    }));
+                    return;
+                }
+                // Rebind every server-issued capability identity to the currently
+                // persisted immutable source run before checking idempotence or reserving
+                // an attempt. A copied/stale capability must never authorize provider or
+                // SQL work against a mutated plan, failure, or source artifact.
+                const canonicalCapability = analyticalRepairCapabilityForAgentRun(sourceRun, capability.targetFingerprint);
+                const bindingMatches = canonicalCapability
+                    && canonicalCapability.automatic.eligible
+                    && canonicalCapability.planFingerprint === capability.planFingerprint
+                    && canonicalCapability.failureFingerprint === capability.failureFingerprint
+                    && canonicalCapability.sourceFingerprint === capability.sourceFingerprint;
+                if (!bindingMatches) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        code: 'REPAIR_CAPABILITY_REQUIRED',
+                        error: 'The persisted source plan, failure, or artifact no longer matches its server-issued repair capability.',
+                        manualActions: capability.manualActions,
+                    }));
+                    return;
+                }
                 const derivedRunId = `${sourceRun.id}:repair:1`;
+                if (activeAnalyticalRepairReservations.has(derivedRunId)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        code: 'REPAIR_IN_PROGRESS',
+                        error: 'The single permitted repair attempt is already in progress.',
+                        manualActions: capability.manualActions,
+                    }));
+                    return;
+                }
                 const existing = await agentRunStore.get(derivedRunId);
                 if (existing) {
-                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ run: existing }));
+                    const succeeded = existing.status === 'needs_review' && existing.trustState === 'review_required';
+                    res.writeHead(succeeded ? 200 : 409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(succeeded
+                        ? { run: existing }
+                        : {
+                            code: 'REPAIR_ATTEMPT_EXHAUSTED',
+                            error: 'The single permitted repair attempt was already consumed and did not complete successfully.',
+                            manualActions: capability.manualActions,
+                            run: existing,
+                        }));
                     return;
                 }
-                const sourceSql = repairableSqlFromAgentRun(sourceRun);
                 const sourceDqlArtifact = repairableDqlArtifactFromAgentRun(sourceRun);
                 const retainedFailure = warehouseFailureFromAgentRun(sourceRun);
-                if ((!sourceSql && !sourceDqlArtifact) || !analyticalFailureAllowsDeterministicRetry(retainedFailure)) {
+                if (!sourceDqlArtifact || !validAskRepairDqlWrapper(sourceDqlArtifact.source)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        code: 'REPAIR_CAPABILITY_REQUIRED',
+                        error: 'The retained DQL wrapper is unavailable or invalid. Keep it editable and repair it manually.',
+                        manualActions: capability.manualActions,
+                    }));
+                    return;
+                }
+                const capabilityHash = (value) => `sha256:${createHash('sha256').update(stableExecutionValue(value)).digest('hex')}`;
+                if (capability.dqlFingerprint !== capabilityHash(sourceDqlArtifact.source.trim())) {
                     res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
-                        error: sourceSql || sourceDqlArtifact
-                            ? 'This failure requires authorized access or a policy change and cannot be repaired by AI.'
-                            : 'This run has no retained SQL statement or editable DQL artifact to repair.',
-                        ...(retainedFailure ? { warehouseFailure: retainedFailure } : {}),
+                        code: 'REPAIR_CAPABILITY_REQUIRED',
+                        error: 'The retained DQL source no longer matches its immutable repair capability.',
+                        manualActions: capability.manualActions,
                     }));
                     return;
                 }
@@ -7282,32 +8224,250 @@ export async function startLocalServer(opts) {
                     : sourceRun.executionTarget?.target === 'local'
                         ? 'local'
                         : projectConfig.defaultConnectionName;
+                const resolvedTargetFingerprint = targetGenerationFingerprint(targetConnection, targetConnectionName);
+                if (resolvedTargetFingerprint !== capability.targetFingerprint) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        code: 'REPAIR_TARGET_DRIFT',
+                        error: 'The named execution target now resolves to a different connection generation. Automatic repair was not attempted.',
+                        manualActions: capability.manualActions,
+                    }));
+                    return;
+                }
+                if (consumedAnalyticalRepairCapabilities.has(derivedRunId)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        code: 'REPAIR_ATTEMPT_EXHAUSTED',
+                        error: 'The single permitted repair attempt has already been consumed.',
+                        manualActions: capability.manualActions,
+                    }));
+                    return;
+                }
+                activeAnalyticalRepairReservations.add(derivedRunId);
+                consumedAnalyticalRepairCapabilities.add(derivedRunId);
+                const releaseRepairReservation = () => { activeAnalyticalRepairReservations.delete(derivedRunId); };
+                res.once('finish', releaseRepairReservation);
+                res.once('close', releaseRepairReservation);
+                const repairStartedAt = new Date().toISOString();
+                const repairStartedAtMs = Date.now();
+                const sourceFailureForReservation = analyticalFailedRunFromAgentRun(sourceRun)?.failure;
+                const reservationEvent = {
+                    id: `${derivedRunId}:repair`,
+                    runId: derivedRunId,
+                    type: 'repair.attempted',
+                    at: repairStartedAt,
+                    message: 'Reserved the single bounded repair attempt.',
+                    route: 'generated_answer',
+                };
+                const reservedRun = {
+                    id: derivedRunId,
+                    question: sourceRun.question,
+                    requestedMode: sourceRun.requestedMode,
+                    route: 'generated_answer',
+                    status: 'blocked',
+                    trustState: 'blocked',
+                    stopReason: 'blocked',
+                    startedAt: repairStartedAt,
+                    completedAt: repairStartedAt,
+                    selectedObject: sourceRun.selectedObject,
+                    executionTarget: sourceRun.executionTarget,
+                    routeDecision: sourceRun.routeDecision,
+                    plan: sourceRun.plan,
+                    steps: [],
+                    summary: 'The single repair attempt was reserved but has not completed successfully.',
+                    artifacts: [],
+                    evaluations: [],
+                    events: [reservationEvent],
+                    nextActions: sourceRun.nextActions,
+                    repairAttempts: 1,
+                    lifecycle: {
+                        version: 1,
+                        state: 'terminal',
+                        phase: 'repair.attempted',
+                        revision: 1,
+                        eventCursor: 1,
+                        startedAt: repairStartedAt,
+                        updatedAt: repairStartedAt,
+                        completedAt: repairStartedAt,
+                    },
+                    derivation: {
+                        version: 1,
+                        kind: 'analytical_repair',
+                        sourceRunId: sourceRun.id,
+                        ...(sourceFailureForReservation?.failureId ? { sourceFailureId: sourceFailureForReservation.failureId } : {}),
+                        attempt: 1,
+                    },
+                };
+                try {
+                    await agentRunStore.save(reservedRun);
+                }
+                catch (error) {
+                    releaseRepairReservation();
+                    throw error;
+                }
                 let repaired;
                 try {
-                    // Prefer the editable DQL contract even when the failed run also
-                    // retained compiled SQL. This keeps parameters, visualization, tests,
-                    // and the corrected wrapper attached to the repaired Ask result.
-                    repaired = sourceDqlArtifact
-                        ? await executeBoundedDqlRepair({
-                            question: sourceRun.question,
-                            source: sourceDqlArtifact.source,
-                            failure: retainedFailure?.redactedMessage
-                                ?? sourceRun.diagnosticReceipt?.failure?.message
-                                ?? sourceRun.summary,
-                            targetConnection,
-                            targetConnectionName,
-                            parameters: sourceDqlArtifact.parameterValues,
-                            artifactName: sourceDqlArtifact.name,
-                        })
-                        : await executeBoundedSqlRepair({
-                            question: sourceRun.question,
-                            sourceSql: sourceSql,
-                            targetConnection,
-                            targetConnectionName,
-                        });
+                    // Compile the immutable original wrapper first. A provider receives only
+                    // this embedded SQL, never the DQL wrapper or its surrounding fields.
+                    const invocation = prepareBlockInvocation({
+                        source: sourceDqlArtifact.source,
+                        parameters: sourceDqlArtifact.parameterValues,
+                        question: sourceRun.question,
+                        surface: 'ask_ai',
+                    });
+                    if (invocation.errors.length || invocation.unresolvedParameters.length) {
+                        throw boundedRepairError(invocation.errors.join(' ') || `Provide required parameters before retrying: ${invocation.unresolvedParameters.join(', ')}.`, 409);
+                    }
+                    const originalPlan = buildExecutionPlan({
+                        id: 'ask-execution-repair-source',
+                        type: 'dql',
+                        source: sourceDqlArtifact.source,
+                        title: sourceDqlArtifact.name,
+                    }, {
+                        semanticLayer,
+                        driver: targetConnection.driver,
+                        parameters: invocation.values,
+                    });
+                    if (!originalPlan?.sql?.trim())
+                        throw boundedRepairError('The original DQL wrapper did not compile to SQL.', 409);
+                    if (capability.sqlFingerprint !== capabilityHash(originalPlan.sql.trim())) {
+                        throw boundedRepairError('The original compiled SQL no longer matches its immutable repair capability.', 409);
+                    }
+                    const sqlRepair = await executeBoundedSqlRepair({
+                        question: sourceRun.question,
+                        sourceSql: originalPlan.sql,
+                        targetConnection,
+                        targetConnectionName,
+                        sqlParams: originalPlan.sqlParams,
+                        variables: { ...originalPlan.variables, ...invocation.values },
+                    });
+                    const embeddedSql = restoreNotebookDqlParameterInterpolations(sqlRepair.repairedSql, originalPlan.sqlParams);
+                    const repairedSource = replaceNotebookDqlQueryForRepair(sourceDqlArtifact.source, embeddedSql);
+                    if (!repairedSource)
+                        throw boundedRepairError('DQL could not reinsert the repaired SQL into the immutable wrapper.', 422);
+                    const repairedInvocation = prepareBlockInvocation({
+                        source: repairedSource,
+                        parameters: sourceDqlArtifact.parameterValues,
+                        question: sourceRun.question,
+                        surface: 'ask_ai',
+                    });
+                    if (repairedInvocation.errors.length || repairedInvocation.unresolvedParameters.length) {
+                        throw boundedRepairError('The SQL-only repair did not preserve a compilable DQL wrapper.', 422);
+                    }
+                    const repairedPlan = buildExecutionPlan({
+                        id: 'ask-execution-repair-derived',
+                        type: 'dql',
+                        source: repairedSource,
+                        title: sourceDqlArtifact.name,
+                    }, {
+                        semanticLayer,
+                        driver: targetConnection.driver,
+                        parameters: repairedInvocation.values,
+                    });
+                    if (!repairedPlan?.sql?.trim() || normalizeSqlForComparison(repairedPlan.sql) !== normalizeSqlForComparison(sqlRepair.repairedSql)) {
+                        throw boundedRepairError('The repaired wrapper recompiled to different SQL, so DQL stopped before publishing it.', 422);
+                    }
+                    const repairedExecutionReceipt = createDqlArtifactExecutionReceipt(repairedSource, sqlRepair.result.sql ?? repairedPlan.sql, repairedInvocation.values, sqlRepair.result);
+                    const repairedExecutableArtifact = sqlRepair.result.executableArtifact
+                        ? {
+                            ...sqlRepair.result.executableArtifact,
+                            kind: 'sql_block',
+                            dqlFingerprint: executionFingerprint(repairedSource),
+                            sourceFingerprint: executionFingerprint(stableExecutionValue({
+                                name: sourceDqlArtifact.name ?? null,
+                                path: sourceDqlArtifact.sourcePath ?? null,
+                            })),
+                            compiledSqlFingerprint: executionFingerprint(repairedPlan.sql),
+                            normalizedSqlFingerprint: executionFingerprint(sqlRepair.repairedSql),
+                            parameterFingerprint: repairedExecutionReceipt.parameterFingerprint,
+                            provenanceFingerprint: executionFingerprint(stableExecutionValue(repairedInvocation.resolvedParameters.map((parameter) => ({
+                                name: parameter.name,
+                                source: parameter.source,
+                            })))),
+                            planFingerprint: executionFingerprint(stableExecutionValue({
+                                compiledSqlFingerprint: executionFingerprint(repairedPlan.sql),
+                                parameterCount: repairedPlan.sqlParams?.length ?? 0,
+                                variableNames: Object.keys(repairedPlan.variables ?? {}).sort(),
+                            })),
+                            trustState: 'review_required',
+                            receipt: repairedExecutionReceipt,
+                        }
+                        : undefined;
+                    const repairedArtifact = {
+                        ...sourceDqlArtifact,
+                        source: repairedSource,
+                        compiledSql: repairedPlan.sql,
+                        trustState: 'review_required',
+                        persistence: 'transient',
+                        executionReceipt: repairedExecutionReceipt,
+                        ...(repairedExecutableArtifact ? { executableArtifact: repairedExecutableArtifact } : {}),
+                        ...(repairedInvocation.parameters.length ? { parameters: repairedInvocation.parameters } : {}),
+                        ...(Object.keys(repairedInvocation.values).length ? { parameterValues: repairedInvocation.values } : {}),
+                    };
+                    repaired = {
+                        ...sqlRepair,
+                        result: {
+                            ...sqlRepair.result,
+                            executionReceipt: repairedExecutionReceipt,
+                            ...(repairedExecutableArtifact ? { executableArtifact: repairedExecutableArtifact } : {}),
+                            dqlArtifact: repairedArtifact,
+                        },
+                        repairedSql: repairedPlan.sql,
+                        repairedSource,
+                        sqlParams: repairedPlan.sqlParams,
+                        variables: { ...repairedPlan.variables, ...repairedInvocation.values },
+                    };
                 }
                 catch (error) {
                     const repairError = error;
+                    const dispatchEvidence = providerDispatchTerminalEvidence(error);
+                    const failedAt = new Date().toISOString();
+                    const failedTelemetry = {
+                        version: 1,
+                        stageDurationsMs: { repair: Date.now() - repairStartedAtMs, total: Date.now() - repairStartedAtMs },
+                        providerRoundTrips: dispatchEvidence?.providerRoundTrips ?? 0,
+                        toolCalls: dispatchEvidence?.toolCalls ?? 0,
+                        sqlExecutions: dispatchEvidence?.sqlExecutions ?? 0,
+                        repairs: Math.max(1, dispatchEvidence?.repairs ?? 0),
+                        egressReceipts: dispatchEvidence?.providerEgressReceipts.length ?? 0,
+                        fallbackReason: dispatchEvidence?.fallbackReason ?? 'repair_failed',
+                    };
+                    const failedReceipts = dispatchEvidence?.providerEgressReceipts ?? [];
+                    await agentRunStore.save({
+                        ...reservedRun,
+                        completedAt: failedAt,
+                        summary: repairError.message,
+                        lifecycle: reservedRun.lifecycle ? {
+                            ...reservedRun.lifecycle,
+                            phase: 'run.failed',
+                            updatedAt: failedAt,
+                            completedAt: failedAt,
+                        } : undefined,
+                        events: [
+                            reservationEvent,
+                            {
+                                id: `${derivedRunId}:failed`,
+                                runId: derivedRunId,
+                                type: 'run.failed',
+                                at: failedAt,
+                                message: repairError.message,
+                                route: 'generated_answer',
+                                status: 'blocked',
+                                trustState: 'blocked',
+                            },
+                        ],
+                        telemetry: failedTelemetry,
+                        ...(failedReceipts.length ? { providerEgressReceipts: failedReceipts } : {}),
+                        diagnosticReceiptV2: {
+                            version: 2,
+                            runId: derivedRunId,
+                            route: 'generated_answer',
+                            status: 'blocked',
+                            telemetry: failedTelemetry,
+                            providerEgressReceiptFingerprints: failedReceipts.map((receipt) => executionFingerprint(stableExecutionValue(receipt))),
+                            repairCapabilityFingerprint: executionFingerprint(stableExecutionValue(capability)),
+                        },
+                    });
                     res.writeHead(repairError.status ?? 500, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         error: repairError.message,
@@ -7315,27 +8475,39 @@ export async function startLocalServer(opts) {
                     }));
                     return;
                 }
-                const { result, repairedSql, repairMode, firstFailure } = repaired;
+                const { result, repairedSql, repairMode, firstFailure, providerEgressReceipts, providerRoundTrips } = repaired;
                 const completedAt = new Date().toISOString();
-                const preview = agentResultToSynthesisPreview(result);
-                const synthesis = await synthesizeAnswer({
-                    question: sourceRun.question,
-                    audience: 'stakeholder',
-                    resultPreview: preview,
-                    sql: repairedSql,
-                    draftText: `The repaired query returned ${result.rowCount} row${result.rowCount === 1 ? '' : 's'}.`,
-                    ...(preview ? { columnFormats: agentColumnDisplayFormats(projectRoot, preview.columns) } : {}),
-                });
+                // Repair never grants a second answer/narration call and never sends rows
+                // to a provider. Present the validated contract deterministically.
+                const presentationText = `The repaired query returned ${result.rowCount} row${result.rowCount === 1 ? '' : 's'}. Review the derived SQL before reuse.`;
                 const sourceFailure = analyticalFailedRunFromAgentRun(sourceRun)?.failure;
                 const presentationContext = repairPresentationContextFromAgentRun(sourceRun);
                 const executionResultFingerprint = result.executionReceipt?.resultFingerprint;
+                const repairTotalDurationMs = Date.now() - repairStartedAtMs;
+                const repairTelemetry = {
+                    version: 1,
+                    stageDurationsMs: {
+                        retrieval: 0,
+                        meaning: 0,
+                        repair: repairTotalDurationMs,
+                        ...(typeof result.executionTime === 'number' ? { execution: result.executionTime } : {}),
+                        narration: 0,
+                        total: repairTotalDurationMs,
+                    },
+                    providerRoundTrips,
+                    toolCalls: 0,
+                    sqlExecutions: firstFailure ? 2 : 1,
+                    repairs: 1,
+                    egressReceipts: providerEgressReceipts.length,
+                    ...(typeof result.executionTime === 'number' ? { warehouseDurationMs: result.executionTime } : {}),
+                };
                 const artifact = agentRunArtifact('answer', 'Repaired analytical answer', {
                     kind: 'uncertified',
                     certification: 'analyst_review_required',
                     reviewStatus: 'analyst_review_required',
                     trustLabel: 'AI-generated · review required',
-                    answer: synthesis.text,
-                    text: synthesis.text,
+                    answer: presentationText,
+                    text: presentationText,
                     ...presentationContext,
                     result,
                     proposedSql: repairedSql,
@@ -7356,10 +8528,11 @@ export async function startLocalServer(opts) {
                             rowCount: result.rowCount,
                             ...(executionResultFingerprint ? { resultFingerprint: executionResultFingerprint } : {}),
                         },
+                        providerEgressReceipts,
                     },
                     previousAttempt: {
                         sourceRunId: sourceRun.id,
-                        ...(sourceSql ? { sql: sourceSql } : {}),
+                        sql: repairableSqlFromAgentRun(sourceRun),
                         ...(sourceDqlArtifact?.source ? { dql: sourceDqlArtifact.source } : {}),
                         failure: retainedFailure ?? firstFailure,
                     },
@@ -7386,7 +8559,7 @@ export async function startLocalServer(opts) {
                     artifacts: [artifact],
                 };
                 const events = [
-                    { id: `${derivedRunId}:repair`, runId: derivedRunId, type: 'repair.attempted', at: completedAt, message: 'Started one bounded query repair.', route: 'generated_answer' },
+                    { id: `${derivedRunId}:repair`, runId: derivedRunId, type: 'repair.attempted', at: repairStartedAt, message: 'Started one bounded query repair.', route: 'generated_answer' },
                     { id: `${derivedRunId}:artifact`, runId: derivedRunId, type: 'artifact.created', at: completedAt, message: 'Created the repaired result artifact.', route: 'generated_answer', trustState: 'review_required' },
                     { id: `${derivedRunId}:complete`, runId: derivedRunId, type: 'run.completed', at: completedAt, message: 'The repaired query executed successfully.', route: 'generated_answer', status: 'needs_review', trustState: 'review_required' },
                 ];
@@ -7398,15 +8571,15 @@ export async function startLocalServer(opts) {
                     status: 'needs_review',
                     trustState: 'review_required',
                     stopReason: 'generated_review_required',
-                    startedAt: completedAt,
+                    startedAt: repairStartedAt,
                     completedAt,
                     selectedObject: sourceRun.selectedObject,
                     executionTarget: sourceRun.executionTarget,
                     routeDecision: sourceRun.routeDecision,
                     plan: sourceRun.plan,
                     steps: [repairStep],
-                    summary: synthesis.text,
-                    answer: synthesis.text,
+                    summary: presentationText,
+                    answer: presentationText,
                     answerKind: 'governed',
                     artifacts: [artifact],
                     evaluations: [evaluation],
@@ -7419,7 +8592,7 @@ export async function startLocalServer(opts) {
                         phase: 'run.completed',
                         revision: 1,
                         eventCursor: events.length,
-                        startedAt: completedAt,
+                        startedAt: repairStartedAt,
                         updatedAt: completedAt,
                         completedAt,
                     },
@@ -7432,7 +8605,19 @@ export async function startLocalServer(opts) {
                         steps: [repairStep],
                         artifacts: [artifact],
                         evaluations: [evaluation],
+                        providerEgressReceipts,
                     },
+                    diagnosticReceiptV2: {
+                        version: 2,
+                        runId: derivedRunId,
+                        route: 'generated_answer',
+                        status: 'needs_review',
+                        telemetry: repairTelemetry,
+                        providerEgressReceiptFingerprints: providerEgressReceipts.map((receipt) => executionFingerprint(stableExecutionValue(receipt))),
+                        repairCapabilityFingerprint: executionFingerprint(stableExecutionValue(capability)),
+                    },
+                    telemetry: repairTelemetry,
+                    providerEgressReceipts,
                     derivation: {
                         version: 1,
                         kind: 'analytical_repair',
@@ -7578,21 +8763,59 @@ export async function startLocalServer(opts) {
                     let runError;
                     try {
                         const executeRun = async (operationSignal, report) => {
-                            parsed.request.signal = AbortSignal.any([
+                            const ingressSignal = AbortSignal.any([
                                 runController.signal,
                                 ...(operationSignal ? [operationSignal] : []),
-                                AbortSignal.timeout(agentRunDeadlineMs(parsed.request, process.env, getActiveProvider(projectRoot))),
                             ]);
+                            parsed.request.runBudget = createAgentRunBudget({
+                                requestedMode: parsed.request.requestedMode,
+                                inheritedSignal: ingressSignal,
+                            });
+                            parsed.request.signal = parsed.request.runBudget.hardSignal;
+                            // Ordinary Ask needs room to think, write, and recover: meaning (1)
+                            // + planning/generation (3) + narration (2) + one repair. The old
+                            // `total: 2` left nothing for narration once generation had run,
+                            // which is why the answer arrived as a deterministic fact-join.
+                            const runProviderEvidence = new RunScopedProviderDispatchEvidence(parsed.request.requestedMode === 'research'
+                                ? { total: 14, meaningResolution: 1, generationGroup: 11, narration: 2, repair: 1 }
+                                : { total: 6, meaningResolution: 1, generationGroup: 3, narration: 2, repair: 1 }, parsed.request.runBudget, resolveProviderResultRowEgressPolicy({
+                                projectSetting: projectConfig?.agent?.providerResultRowEgress,
+                                researchOptIn: parsed.request.requestedMode === 'research'
+                                    && parsed.request.researchResultRowsOptIn === true,
+                            }));
                             report?.({ phase: 'reasoning', progress: 8, message: 'Grounding the request and selecting the governed route.' });
                             try {
-                                const run = await agentRunEngine.run(parsed.request, (event) => {
+                                const engineRun = await agentRunProviderEvidenceContext.run(runProviderEvidence, () => agentRunEngine.run(parsed.request, (event) => {
+                                    runProviderEvidence.setRoute(event.route);
                                     if (wantsStream)
                                         writeStream('agent-run-event', event);
                                     report?.({ phase: event.type, progress: 45, message: event.message });
                                 }, (delta) => {
                                     if (wantsStream)
                                         writeStream('agent-run-answer-delta', { runId: parsed.request.runId, delta });
-                                });
+                                }));
+                                const rawRun = mergeRunScopedProviderDispatchEvidence(engineRun, runProviderEvidence.snapshot(engineRun.telemetry?.fallbackReason ?? engineRun.stopReason));
+                                let resolvedTargetFingerprint;
+                                try {
+                                    const resolvedTarget = await resolveAgentRunExecutionConnection({
+                                        question: rawRun.question,
+                                        executionTarget: rawRun.executionTarget,
+                                    });
+                                    const resolvedTargetName = rawRun.executionTarget?.target === 'connection'
+                                        ? rawRun.executionTarget.connectionName
+                                        : rawRun.executionTarget?.target === 'local'
+                                            ? 'local'
+                                            : projectConfig.defaultConnectionName;
+                                    resolvedTargetFingerprint = targetGenerationFingerprint(resolvedTarget, resolvedTargetName);
+                                }
+                                catch {
+                                    // Missing target-generation evidence keeps automatic repair
+                                    // ineligible; the failed run itself remains fully inspectable.
+                                }
+                                const run = attachAnalyticalRepairCapability(rawRun, resolvedTargetFingerprint);
+                                // The engine persists before the host can validate the DQL wrapper;
+                                // replace that row with the server-owned capability atomically.
+                                await agentRunStore.save(run);
                                 completedRun = run;
                                 recordConversationTurn(conversationStore, parsed.request.threadId, run);
                                 return { runId: run.id, threadId: parsed.request.threadId, status: run.status };
@@ -9658,13 +10881,22 @@ export async function startLocalServer(opts) {
                                     });
                                     if (!composed)
                                         throw new Error('The governed semantic query could not be composed.');
-                                    const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
                                     let normalizedResult;
                                     let repair;
                                     let executedSql = composed.sql;
+                                    let executionFingerprints;
                                     try {
-                                        const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
-                                        normalizedResult = normalizeQueryResult(result);
+                                        const execution = await analyticalExecutionService.execute({
+                                            sql: composed.sql,
+                                            subject: 'App tile semantic query',
+                                            connection: targetConnection,
+                                        });
+                                        normalizedResult = execution.result;
+                                        executedSql = execution.preparation.executedSql;
+                                        executionFingerprints = {
+                                            compiledSqlFingerprint: execution.compiledSqlFingerprint,
+                                            resultFingerprint: execution.resultFingerprint,
+                                        };
                                     }
                                     catch (executionError) {
                                         const repaired = await repairFailedAppTileExecution({
@@ -9706,6 +10938,7 @@ export async function startLocalServer(opts) {
                                         title: item.title ?? item.semantic.id,
                                         viz: item.viz,
                                         result: normalizedResult,
+                                        ...(executionFingerprints ?? {}),
                                         trustState: 'review_required',
                                         citation: { kind: repair ? 'semantic_query_repaired' : 'semantic_query', name: item.semantic.id },
                                         ...(repair ? { repair } : {}),
@@ -9839,8 +11072,13 @@ export async function startLocalServer(opts) {
                                     tileId: item.i,
                                     tileFilterBindings: item.filterBindings,
                                 });
-                                const prepared = prepareLocalExecution(blockFilterApplication.sql, blockTargetConnection, projectRoot, projectConfig);
-                                const result = await executor.executeQuery(prepared.sql, blockFilterApplication.sqlParams, runtimeVariables({ ...blockFilterApplication.variables, ...blockInvocation.values }), prepared.connection);
+                                const execution = await analyticalExecutionService.execute({
+                                    sql: blockFilterApplication.sql,
+                                    subject: 'App tile block query',
+                                    connection: blockTargetConnection,
+                                    sqlParams: blockFilterApplication.sqlParams,
+                                    variables: { ...blockFilterApplication.variables, ...blockInvocation.values },
+                                });
                                 tiles.push({
                                     tileId: item.i,
                                     status: 'ok',
@@ -9850,7 +11088,9 @@ export async function startLocalServer(opts) {
                                     title: item.title ?? block.name,
                                     viz: item.viz,
                                     chartConfig: mergeDashboardChartConfig(blockPlan?.chartConfig, item),
-                                    result: normalizeQueryResult(result),
+                                    result: execution.result,
+                                    compiledSqlFingerprint: execution.compiledSqlFingerprint,
+                                    resultFingerprint: execution.resultFingerprint,
                                     filters: {
                                         applied: blockFilterApplication.appliedFilters,
                                         skipped: blockFilterApplication.skippedFilters,
@@ -14761,20 +16001,18 @@ export async function startLocalServer(opts) {
                         }));
                         return;
                     }
-                    const preparation = await prepareAnalyticalExecutionSql({
+                    const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
+                    const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
+                    assertAppAccess({ app, domain, level: 'execute' });
+                    const execution = await analyticalExecutionService.execute({
                         sql: semantic.sql,
                         subject: 'Notebook query',
-                        executor,
                         connection: executionConnection,
-                        projectRoot,
-                        projectConfig,
+                        sqlParams: Array.isArray(body.sqlParams) ? body.sqlParams : [],
+                        variables: body.variables && typeof body.variables === 'object' ? body.variables : {},
+                        semanticRefs: semantic.semanticRefs,
                     });
-                    const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
-                    const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
-                    const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
-                    assertAppAccess({ app, domain, level: 'execute' });
-                    const result = await executor.executeQuery(prepared.sql, Array.isArray(body.sqlParams) ? body.sqlParams : [], runtimeVariables(body.variables && typeof body.variables === 'object' ? body.variables : {}), prepared.connection);
-                    const normalized = normalizeQueryResult(result, semantic.semanticRefs);
+                    const { preparation, result: normalized } = execution;
                     if (execContext?.notebookPath) {
                         recordNotebookQueryRun(projectRoot, {
                             notebookPath: execContext.notebookPath,
@@ -15448,7 +16686,7 @@ export async function startLocalServer(opts) {
                     const invocation = prepareBlockInvocation({ source, surface: 'ask_ai' });
                     if (invocation.errors.length > 0)
                         throw new Error(invocation.errors.join(' '));
-                    const { executionReceipt: _receipt, compiledSql: _compiled, ...unexecuted } = artifact;
+                    const { executionReceipt: _receipt, executableArtifact: _executable, compiledSql: _compiled, ...unexecuted } = artifact;
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
                         artifact: {
@@ -15564,6 +16802,13 @@ export async function startLocalServer(opts) {
                             trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
                             compiledSql: result.sql,
                             executionReceipt: result.executionReceipt,
+                            ...(result.executableArtifact ? {
+                                executableArtifact: {
+                                    ...result.executableArtifact,
+                                    kind: certified ? 'certified_block' : semantic ? 'semantic_block' : 'sql_block',
+                                    trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
+                                },
+                            } : {}),
                             ...(requestedArtifact?.limit ? { limit: requestedArtifact.limit } : {}),
                         },
                     }));
@@ -15686,37 +16931,43 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ cellType: cell.type, result: null }));
                         return;
                     }
-                    const preparation = await prepareAnalyticalExecutionSql({
+                    const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
+                    assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
+                    const semanticExecutionHolder = { value: null };
+                    const execution = await analyticalExecutionService.execute({
                         sql: executableSql,
                         subject: cell.type === 'dql' ? 'DQL query' : 'Notebook query',
-                        executor,
                         connection: cellConnection,
-                        projectRoot,
-                        projectConfig,
+                        sqlParams: plan?.sqlParams,
+                        variables: { ...(plan?.variables ?? {}), ...(invocation?.values ?? {}) },
+                        executePrepared: semanticCompose?.compiled
+                            ? async (preparation) => {
+                                const semanticExecution = await executeTargetBoundSemanticQuery({
+                                    executor,
+                                    connection: cellConnection,
+                                    projectRoot,
+                                    plannedAdapter: semanticCompose.compiled.engine,
+                                    metricFlow: semanticCompose.compiled.engine === 'metricflow-cli'
+                                        ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
+                                        : undefined,
+                                    // Compilation already produced the exact pinned adapter result
+                                    // used by the plan. The gateway validates target identity before
+                                    // accepting that result for preflight and execution.
+                                    compile: async () => semanticCompose.compiled,
+                                    prepareSql: () => ({ sql: preparation.executedSql, connection: preparation.connection }),
+                                    rowBound: semanticCompose.compiled.effectiveRequest.limit,
+                                });
+                                if (semanticExecution) {
+                                    semanticExecutionHolder.value = semanticExecution;
+                                    return semanticExecution.result;
+                                }
+                                return executor.executeQuery(preparation.executedSql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...(invocation?.values ?? {}) }), preparation.connection);
+                            }
+                            : undefined,
                     });
+                    const { preparation, result: normalized } = execution;
                     const decodedSql = preparation.decodedSql;
-                    const prepared = { sql: preparation.preparedSql, connection: preparation.connection };
-                    const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
-                    assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
-                    const semanticExecution = semanticCompose?.compiled
-                        ? await executeTargetBoundSemanticQuery({
-                            executor,
-                            connection: cellConnection,
-                            projectRoot,
-                            plannedAdapter: semanticCompose.compiled.engine,
-                            metricFlow: semanticCompose.compiled.engine === 'metricflow-cli'
-                                ? resolveMetricFlowTargetMetadata(projectRoot, projectConfig)
-                                : undefined,
-                            // Compilation already produced the exact pinned adapter result
-                            // used by the plan. The gateway validates target identity before
-                            // accepting that result for preflight and execution.
-                            compile: async () => semanticCompose.compiled,
-                            prepareSql: () => ({ sql: prepared.sql, connection: prepared.connection }),
-                            rowBound: semanticCompose.compiled.effectiveRequest.limit,
-                        })
-                        : null;
-                    const rawResult = semanticExecution?.result ?? await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...(invocation?.values ?? {}) }), prepared.connection);
-                    const normalized = normalizeQueryResult(rawResult);
+                    const semanticExecution = semanticExecutionHolder.value;
                     // Enforce the block's declared invariants against the result set. This
                     // is additive: blocks without invariants produce `null` and the
                     // response is unchanged. The agent surface (`query_via_block`) reads
@@ -15967,6 +17218,26 @@ table: ${table}${tagList}
         });
     });
 }
+function providerDispatchTerminalEvidence(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const candidate = value.providerDispatchEvidence;
+    if (!candidate || typeof candidate !== 'object')
+        return undefined;
+    const evidence = candidate;
+    if (!Array.isArray(evidence.providerEgressReceipts)
+        || !Number.isInteger(evidence.providerRoundTrips)
+        || (evidence.providerRoundTrips ?? -1) < 0)
+        return undefined;
+    return {
+        providerEgressReceipts: evidence.providerEgressReceipts,
+        providerRoundTrips: evidence.providerRoundTrips,
+        toolCalls: Number.isInteger(evidence.toolCalls) && (evidence.toolCalls ?? -1) >= 0 ? evidence.toolCalls : 0,
+        sqlExecutions: Number.isInteger(evidence.sqlExecutions) && (evidence.sqlExecutions ?? -1) >= 0 ? evidence.sqlExecutions : 0,
+        repairs: Number.isInteger(evidence.repairs) && (evidence.repairs ?? -1) >= 0 ? evidence.repairs : 0,
+        fallbackReason: typeof evidence.fallbackReason === 'string' ? evidence.fallbackReason : 'provider_error',
+    };
+}
 async function validateModelingRelationship(relationship, manifest, execute, quoteIdentifier = quoteSqlIdentifier) {
     const fromEntity = manifest.modeling?.entities[relationship.from];
     const toEntity = manifest.modeling?.entities[relationship.to];
@@ -18651,9 +19922,104 @@ function createDqlArtifactExecutionReceipt(source, compiledSql, parameters, resu
         })),
     };
 }
+function agentRunTelemetryForAnswer(answer, egressReceipts, totalDurationMs, narrationDurationMs, engineRepairAttempts) {
+    const timings = new Map((answer.evidence?.timings ?? []).map((timing) => [timing.phase, timing.durationMs]));
+    const toolCalls = answer.evidence?.toolCalls ?? [];
+    const toolDurationMs = toolCalls.reduce((sum, call) => sum + Math.max(0, call.durationMs ?? 0), 0);
+    const warehouseDurationMs = answer.evidence?.execution?.executionTime ?? answer.result?.executionTime;
+    const counters = answer.evidence?.runtimeCounters;
+    const stageDurationsMs = {
+        ...(timings.has('project_state') ? { snapshot: timings.get('project_state') } : {}),
+        ...(timings.has('context_retrieval') ? { retrieval: timings.get('context_retrieval') } : {}),
+        ...(timings.has('runtime_schema') ? { schema: timings.get('runtime_schema') } : {}),
+        ...(timings.has('source_search') ? { meaning: timings.get('source_search') } : {}),
+        ...(timings.has('answer_resolution') ? { provider: timings.get('answer_resolution') } : {}),
+        ...(toolCalls.length > 0 ? { tools: toolDurationMs } : {}),
+        ...(typeof warehouseDurationMs === 'number' ? { execution: Math.max(0, warehouseDurationMs) } : {}),
+        ...(narrationDurationMs > 0 ? { narration: narrationDurationMs } : {}),
+        total: Math.max(0, totalDurationMs),
+    };
+    return {
+        version: 1,
+        stageDurationsMs,
+        providerRoundTrips: counters?.providerRoundTrips ?? 0,
+        toolCalls: counters?.toolCalls ?? toolCalls.length,
+        sqlExecutions: counters?.sqlExecutions ?? 0,
+        repairs: Math.max(engineRepairAttempts, counters?.repairs ?? 0),
+        egressReceipts: egressReceipts.length,
+        ...(typeof warehouseDurationMs === 'number' ? { warehouseDurationMs: Math.max(0, warehouseDurationMs) } : {}),
+        ...(answer.refusalCode ? { fallbackReason: answer.refusalCode } : {}),
+    };
+}
 function executionFingerprint(value) {
     return createHash('sha256').update(value).digest('hex');
 }
+function buildSemanticAggregationCompilerReceipt(input) {
+    const plan = input.plan;
+    const metricId = plan?.analyticalFrame?.metricConceptIds[0];
+    if (input.metricNames.length !== 1 || !plan || !metricId || !plan.executionId
+        || !plan.selectedCapabilityFingerprint || !input.targetFingerprint)
+        return undefined;
+    const metric = input.semanticLayer.getMetric(input.metricNames[0]);
+    if (!metric || (metric.aggregation ?? metric.metricType)?.toLowerCase() !== 'ratio')
+        return undefined;
+    const refName = (value) => {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const name = value.name;
+        return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+    };
+    const numeratorName = refName(metric.typeParams?.numerator);
+    const denominatorName = refName(metric.typeParams?.denominator);
+    if (!numeratorName || !denominatorName || !metric.sql.trim())
+        return undefined;
+    const measures = [numeratorName, denominatorName].map((name) => {
+        const matches = input.semanticLayer.listMeasures().filter((measure) => measure.name === name
+            && (!metric.cube || !measure.cube || measure.cube === metric.cube));
+        return matches.length === 1 ? matches[0] : undefined;
+    });
+    if (measures.some((measure) => !measure))
+        return undefined;
+    const relations = Array.from(new Set(measures.map((measure) => measure.table.trim()).filter(Boolean)));
+    if (relations.length !== 1)
+        return undefined;
+    const outputAlias = metricId.split(/[:.]/).at(-1);
+    if (!outputAlias)
+        return undefined;
+    const orderedMeasureIds = measures.map((measure) => `semantic:${measure.domain || 'uncategorized'}:measure:${measure.cube ? `${measure.cube}.` : ''}${measure.name}`);
+    const compiledSqlFingerprint = semanticExecutionFingerprint(input.compiledSql);
+    const compiledOutputExpression = buildSqlOutputExpressionSignature(input.compiledSql, outputAlias);
+    if (!compiledOutputExpression)
+        return undefined;
+    const compiledExpressionFingerprint = semanticExecutionFingerprint(compiledOutputExpression.canonicalExpression);
+    const compiledSignature = buildGeneratedAnalyticalSqlSignature(input.compiledSql);
+    if (!compiledSignature)
+        return undefined;
+    const body = {
+        version: 1,
+        executionId: plan.executionId,
+        capabilityFingerprint: plan.selectedCapabilityFingerprint,
+        metricId,
+        metricExpressionSql: metric.sql,
+        operator: 'ratio',
+        orderedMeasureIds,
+        physicalRelation: relations[0],
+        relationAliases: Array.from(new Set([metric.cube, ...measures.map((measure) => measure.cube)].filter((value) => Boolean(value)))),
+        outputAlias,
+        dimensionIds: [...new Set(plan.analyticalFrame?.dimensions.map((dimension) => dimension.dimensionId) ?? [])].sort(),
+        relationshipPathIds: [...plan.relationshipPathIds].sort(),
+        relationshipProofFingerprints: [...new Set(plan.relationshipProofs?.map((proof) => proof.authorityFingerprint) ?? [])].sort(),
+        orderBy: compiledSignature.orderBy,
+        compiledSqlFingerprint,
+        compiledExpressionFingerprint,
+        planFingerprint: plan.fingerprint,
+        snapshotId: plan.snapshotId,
+        targetFingerprint: input.targetFingerprint,
+    };
+    return { ...body, receiptFingerprint: semanticExecutionFingerprint(body) };
+}
 /**
  * Older clients normalized executable DQL with trim(), while the receipt was
  * correctly created from the original renderer output ending in one newline.
@@ -19071,6 +20437,43 @@ export function prepareLocalExecution(sql, connection, projectRoot, projectConfi
         connection: normalizedConnection,
     };
 }
+/**
+ * The single connector boundary for Ask, Notebook, and artifact execution.
+ * Callers compile their route-specific source first; this service owns target
+ * preparation, parameters, execution, and result normalization after that.
+ */
+export class ExecutionService {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    async execute(input) {
+        const preparation = await prepareAnalyticalExecutionSql({
+            sql: input.sql,
+            subject: input.subject,
+            executor: this.host.executor,
+            connection: input.connection,
+            projectRoot: this.host.projectRoot,
+            projectConfig: this.host.projectConfig(),
+            enforceReadOnly: input.enforceReadOnly,
+            rowLimit: input.rowLimit,
+        });
+        const raw = input.executePrepared
+            ? await input.executePrepared(preparation)
+            : await this.host.executor.executeQuery(preparation.executedSql, input.sqlParams ?? [], runtimeVariables(input.variables ?? {}), preparation.connection);
+        const result = normalizeQueryResult(raw, input.semanticRefs);
+        return {
+            preparation,
+            result,
+            compiledSqlFingerprint: executionFingerprint(preparation.executedSql),
+            resultFingerprint: executionFingerprint(stableExecutionValue({
+                columns: result.columns,
+                rows: result.rows,
+                rowCount: result.rowCount,
+            })),
+        };
+    }
+}
 /**
  * One host-owned SQL preparation boundary shared by Ask and Notebook.
  *