@duckcodeailabs/dql-cli 1.8.7 → 1.8.8

package/dist/local-runtime.js

@@ -1186,7 +1186,8 @@ export async function startLocalServer(opts) {
                 ? { preferredExecutionId: routeDecision.meaningResolution.recommendedExecutionId }
                 : {}),
             executeCertifiedBlock: executeCertifiedBlockForAgent,
-            executeGeneratedSql: executeGeneratedSqlForAgent,
+            executeGeneratedSql: (sql, artifact) => executeGeneratedArtifactForAgent(request.question, sql, artifact),
+            executeDqlArtifact: (artifact) => executeArtifactReferenceForAgent(artifact, request.question),
             getSchemaContext: getSchemaContextForAgent,
         }, (turn) => {
             if (turn.kind === 'thinking')
@@ -1296,51 +1297,53 @@ export async function startLocalServer(opts) {
             },
         ];
     }
+    function generatedSqlArtifactContract(question, sql, seed) {
+        const parameterized = parameterizeSqlForDqlImport(sql);
+        const artifactName = seed?.name
+            ?? seed?.source.match(/\bblock\s+"([^"]+)"/i)?.[1]
+            ?? deriveGeneratedDraftSlug(question);
+        const domain = seed?.source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1] ?? 'uncategorized';
+        const source = candidateToDqlSource({
+            name: artifactName,
+            domain,
+            description: question,
+            owner: '',
+            tags: ['ai-generated', 'review-required'],
+            terms: [],
+            pattern: '',
+            grain: '',
+            entities: [],
+            outputs: [],
+            dimensions: [],
+            allowedFilters: parameterized.allowedFilters,
+            parameterPolicy: parameterized.parameterPolicy,
+            filterBindings: parameterized.filterBindings,
+            parameterDecisions: parameterized.parameterDecisions,
+            sourceSystems: [],
+            replacementFor: [],
+            reviewCadence: 'monthly',
+            sql: parameterized.sql,
+            llmContext: `Review-required DQL generated for: ${question}`,
+        });
+        return {
+            ...(seed ?? { kind: 'sql_block' }),
+            kind: 'sql_block',
+            name: artifactName,
+            source,
+        };
+    }
     /**
-     * PRD-001 / AGT-002 / AGT-006 / EXP-002 — every answer surface receives the
-     * same executable DQL artifact. Generated SQL is parameterized before the
-     * artifact leaves the runtime; it remains compiled evidence, not the primary
-     * user-facing object. Saving later persists this exact source without another
-     * model call.
+     * AGT-010 / API-003 / UI-011 — attach the exact artifact already used for
+     * execution. Post-execution translation is forbidden because it creates a
+     * second query contract whose Apply result can differ from the displayed Ask
+     * result.
      */
     function attachExecutableDqlArtifactContract(governedAnswer, question) {
         const originalSql = governedAnswer.proposedSql?.trim() || governedAnswer.sql?.trim();
-        let artifact = governedAnswer.dqlArtifact;
-        if ((!artifact || artifact.kind === 'sql_block') && originalSql) {
-            const parameterized = parameterizeSqlForDqlImport(originalSql);
-            const artifactName = artifact?.name
-                ?? artifact?.source.match(/\bblock\s+"([^"]+)"/i)?.[1]
-                ?? deriveGeneratedDraftSlug(question);
-            const domain = artifact?.source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1] ?? 'uncategorized';
-            const source = candidateToDqlSource({
-                name: artifactName,
-                domain,
-                description: question,
-                owner: '',
-                tags: ['ai-generated', 'review-required'],
-                terms: [],
-                pattern: '',
-                grain: '',
-                entities: [],
-                outputs: [],
-                dimensions: [],
-                allowedFilters: parameterized.allowedFilters,
-                parameterPolicy: parameterized.parameterPolicy,
-                filterBindings: parameterized.filterBindings,
-                parameterDecisions: parameterized.parameterDecisions,
-                sourceSystems: [],
-                replacementFor: [],
-                reviewCadence: 'monthly',
-                sql: parameterized.sql,
-                llmContext: `Review-required DQL generated for: ${question}`,
-            });
-            artifact = {
-                ...(artifact ?? { kind: 'sql_block' }),
-                kind: 'sql_block',
-                name: artifactName,
-                source,
-            };
-        }
+        const executedArtifact = normalizeDqlArtifactReference(governedAnswer.result?.dqlArtifact);
+        let artifact = executedArtifact ?? governedAnswer.dqlArtifact;
+        if (!artifact && originalSql)
+            artifact = generatedSqlArtifactContract(question, originalSql);
         if (!artifact?.source)
             return;
         const invocation = prepareBlockInvocation({
@@ -1357,8 +1360,11 @@ export async function startLocalServer(opts) {
             ...(Object.keys(invocation.values).length > 0 ? { parameterValues: invocation.values } : {}),
             persistence: artifact.sourcePath ? 'saved' : 'transient',
             trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
-            ...(originalSql ? { compiledSql: originalSql } : {}),
+            ...(governedAnswer.result?.sql ? { compiledSql: governedAnswer.result.sql } : originalSql ? { compiledSql: originalSql } : {}),
+            ...(governedAnswer.result?.executionReceipt ? { executionReceipt: governedAnswer.result.executionReceipt } : {}),
         };
+        if (governedAnswer.result)
+            delete governedAnswer.result.dqlArtifact;
     }
     const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit }) => {
         let governedAnswer;
@@ -2593,22 +2599,27 @@ export async function startLocalServer(opts) {
             throw new Error(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`);
         }
         const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
+        const executionSql = invocationInput?.rowLimit
+            ? buildAgentPreviewSql(prepared.sql, invocationInput.rowLimit)
+            : prepared.sql;
         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 rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
+        const rawResult = 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);
         return {
             columns: normalized.columns,
             rows: normalized.rows,
             rowCount: normalized.rowCount,
             executionTime: normalized.executionTime,
             chartConfig: plan?.chartConfig ?? (metadata.chartType ? { chart: metadata.chartType } : undefined),
-            sql: prepared.sql,
+            sql: executionSql,
             ...(metadata.name ? { blockName: metadata.name } : {}),
             ...(metadata.path ? { blockPath: metadata.path } : {}),
             parameters: invocation.resolvedParameters,
             auditId: invocation.auditId,
+            executionReceipt,
         };
     };
     const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false) => {
@@ -2621,12 +2632,29 @@ export async function startLocalServer(opts) {
             throw new Error(`Block "${block.name}" is not certified and cannot be rerun as a certified answer.`);
         }
         const source = readFileSync(join(projectRoot, block.filePath), 'utf-8');
-        return executeDqlArtifactSourceForAgent(source, {
+        const result = await executeDqlArtifactSourceForAgent(source, {
             name: block.name,
             path: block.filePath,
             domain: block.domain,
             chartType: block.chartType,
         }, invocationInput);
+        return {
+            ...result,
+            dqlArtifact: {
+                kind: 'certified_block',
+                name: block.name,
+                source,
+                sourcePath: block.filePath,
+                persistence: 'saved',
+                trustState: 'certified',
+                compiledSql: result.sql,
+                executionReceipt: result.executionReceipt,
+                ...(invocationInput?.rowLimit ? { limit: invocationInput.rowLimit } : {}),
+                ...(invocationInput?.parameters && Object.keys(invocationInput.parameters).length > 0
+                    ? { parameterValues: invocationInput.parameters }
+                    : {}),
+            },
+        };
     };
     const executeCertifiedBlockForAgent = async (node, invocationInput) => {
         if (node.kind !== 'block') {
@@ -2634,26 +2662,41 @@ export async function startLocalServer(opts) {
         }
         return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput);
     };
-    const executeGeneratedSqlForAgent = async (sql) => {
-        const activeConnection = requireActiveConnection();
-        const boundedSql = buildAgentPreviewSql(sql);
-        const semantic = prepareSemanticSql(boundedSql, semanticLayer);
-        if (semantic.unresolvedRefs.length > 0) {
-            throw new Error(`Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`);
-        }
-        const prepared = prepareLocalExecution(semantic.sql, activeConnection, projectRoot, projectConfig);
-        const app = loadRuntimeApp(projectRoot, activePersonaAppId());
-        assertAppAccess({ app, domain: app?.domain, level: 'execute' });
-        const rawResult = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
-        const normalized = normalizeQueryResult(rawResult, semantic.semanticRefs);
+    // Secondary agent surfaces use this compatibility callback. Delegate to the
+    // same artifact-first path as Ask so research/app/notebook execution cannot
+    // silently reintroduce a raw-SQL result followed by a different DQL artifact.
+    const executeGeneratedSqlForAgent = async (sql, artifact) => executeGeneratedArtifactForAgent(artifact?.name ?? 'AI-generated query', sql, artifact);
+    const executeArtifactReferenceForAgent = async (artifact, question) => {
+        const invocation = prepareBlockInvocation({
+            source: artifact.source,
+            parameters: artifact.parameterValues,
+            question,
+            surface: 'ask_ai',
+        });
+        const result = await executeDqlArtifactSourceForAgent(artifact.source, {
+            name: artifact.name,
+            path: artifact.sourcePath,
+            domain: artifact.source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1],
+        }, {
+            question,
+            parameters: invocation.values,
+            rowLimit: artifact.limit ?? 200,
+        });
         return {
-            columns: normalized.columns,
-            rows: normalized.rows,
-            rowCount: normalized.rowCount,
-            executionTime: normalized.executionTime,
-            sql: prepared.sql,
+            ...result,
+            dqlArtifact: {
+                ...artifact,
+                ...(invocation.parameters.length > 0 ? { parameters: invocation.parameters } : {}),
+                ...(Object.keys(invocation.values).length > 0 ? { parameterValues: invocation.values } : {}),
+                compiledSql: result.sql,
+                executionReceipt: result.executionReceipt,
+            },
         };
     };
+    const executeGeneratedArtifactForAgent = async (question, sql, seed) => {
+        const artifact = generatedSqlArtifactContract(question, sql, seed);
+        return executeArtifactReferenceForAgent({ ...artifact, limit: seed?.limit ?? artifact.limit ?? 200 }, question);
+    };
     /**
      * EXP-001: execution host for the deliberately narrow non-governed lane.
      * It does not reinterpret dbt lineage or shared names as relationship proof.
@@ -2681,7 +2724,7 @@ export async function startLocalServer(opts) {
         if (!analysis.parsed) {
             return { proofs: [], sql: boundedSql, repairs, error: 'DQL could not parse the exploratory SQL to validate its join predicates.' };
         }
-        const probeableJoins = probeableExploratoryJoins(analysis.joins, analysis.ctes);
+        const probeableJoins = probeableExploratoryJoins(analysis.joins, analysis.ctes, analysis.derivedRelations);
         // A normal customer → order → order-item → product question needs three
         // joins. Keep the lane bounded, but do not reject this common dbt-star path
         // solely because the old two-join demo limit was too small. CTE-internal
@@ -2754,7 +2797,7 @@ export async function startLocalServer(opts) {
                     return { proofs, sql: boundedSql, repairs, error: contradiction };
                 }
             }
-            const result = await executeGeneratedSqlForAgent(boundedSql);
+            const result = await executeGeneratedArtifactForAgent(question, boundedSql);
             return { result, proofs, sql: boundedSql, repairs };
         }
         catch (error) {
@@ -10520,13 +10563,17 @@ export async function startLocalServer(opts) {
                     domain = block.domain;
                     chartType = block.chartType;
                 }
-                else if (sourcePath) {
+                else if (!source.trim() && sourcePath) {
                     const filePath = safeJoin(projectRoot, sourcePath);
                     if (filePath && existsSync(filePath) && !statSync(filePath).isDirectory())
                         source = readFileSync(filePath, 'utf-8');
                 }
                 if (!source.trim())
                     throw new Error('Provide an executable DQL artifact or block name.');
+                const expectedReceipt = requestedArtifact?.executionReceipt;
+                if (expectedReceipt && expectedReceipt.sourceFingerprint !== executionFingerprint(source)) {
+                    throw new Error('DQL artifact source changed after the answer was produced. Refresh the answer before applying it.');
+                }
                 const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
                     ? body.parameters
                     : requestedArtifact?.parameterValues ?? {};
@@ -10538,7 +10585,15 @@ export async function startLocalServer(opts) {
                 }, {
                     parameters,
                     question: typeof body.question === 'string' ? body.question : undefined,
+                    rowLimit: requestedArtifact?.limit,
                 });
+                const actualReceipt = result.executionReceipt;
+                if (expectedReceipt && actualReceipt) {
+                    if (expectedReceipt.parameterFingerprint === actualReceipt.parameterFingerprint
+                        && expectedReceipt.compiledSqlFingerprint !== actualReceipt.compiledSqlFingerprint) {
+                        throw new Error('DQL artifact execution changed while its source and inputs were unchanged. Refresh the answer before applying it.');
+                    }
+                }
                 const contract = prepareBlockInvocation({
                     source,
                     parameters,
@@ -10560,6 +10615,8 @@ export async function startLocalServer(opts) {
                         persistence: sourcePath ? 'saved' : 'transient',
                         trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
                         compiledSql: result.sql,
+                        executionReceipt: result.executionReceipt,
+                        ...(requestedArtifact?.limit ? { limit: requestedArtifact.limit } : {}),
                     },
                 }));
             }
@@ -12424,6 +12481,37 @@ function titleFromSlug(value) {
 function stableShortHash(value) {
     return createHash('sha1').update(value).digest('hex').slice(0, 10);
 }
+function createDqlArtifactExecutionReceipt(source, compiledSql, parameters, result) {
+    return {
+        sourceFingerprint: executionFingerprint(source),
+        compiledSqlFingerprint: executionFingerprint(compiledSql),
+        parameterFingerprint: executionFingerprint(stableExecutionValue(parameters)),
+        resultFingerprint: executionFingerprint(stableExecutionValue({
+            columns: result.columns,
+            rows: result.rows,
+            rowCount: result.rowCount,
+        })),
+    };
+}
+function executionFingerprint(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function stableExecutionValue(value) {
+    const seen = new WeakSet();
+    return JSON.stringify(value, (_key, item) => {
+        if (!item || typeof item !== 'object') {
+            if (typeof item === 'bigint')
+                return item.toString();
+            return item;
+        }
+        if (seen.has(item))
+            return '[Circular]';
+        seen.add(item);
+        if (Array.isArray(item))
+            return item;
+        return Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right)));
+    });
+}
 function renderCompostingPrBody(candidates) {
     const lines = [
         '# Semantic Composting Changeset',
@@ -13113,15 +13201,18 @@ const AGENT_PREVIEW_FORBIDDEN_SQL = [
     'update',
     'vacuum',
 ];
-export function buildAgentPreviewSql(sql) {
+export function buildAgentPreviewSql(sql, rowLimit = 200) {
     const trimmed = sql.trim();
     if (!trimmed)
         throw new Error('Generated SQL preview is empty.');
+    const boundedRowLimit = Number.isFinite(rowLimit)
+        ? Math.max(1, Math.min(10_000, Math.floor(rowLimit)))
+        : 200;
     const withoutTrailingSemicolon = trimmed.replace(/;\s*$/, '').trim();
     const readOnlyError = readOnlySqlValidationError(withoutTrailingSemicolon, 'Generated SQL preview');
     if (readOnlyError)
         throw new Error(readOnlyError);
-    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
+    return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT ${boundedRowLimit}`;
 }
 /**
  * EXP-001 preflight for model-authored exploratory SQL.
@@ -13421,20 +13512,21 @@ SELECT
   (SELECT COALESCE(MAX(key_count), 0) FROM right_key_counts) AS max_right_rows_per_key`;
 }
 /**
- * CTE names are query-internal derived relations, not warehouse tables. A join
- * whose endpoint is a CTE (e.g. `WITH joy_items AS (…) … JOIN joy_items`) must
- * be excluded from declared-path enforcement and from join probes — probing
- * `FROM "joy_items"` throws a DuckDB catalog error for a table that was never
- * supposed to exist. The physical joins INSIDE the CTE are still present in
- * the parsed join list and get validated/probed on their own.
+ * CTE names and nested SELECT aliases are query-internal derived relations, not
+ * warehouse tables. A join whose endpoint is `joy_items` or generated
+ * `subq_2` must be excluded from declared-path enforcement and join probes —
+ * probing it as `FROM "subq_2"` asks Snowflake for an object that only exists
+ * inside the statement. Physical joins inside the derived relation remain in
+ * the parsed join list and are validated/probed on their own.
  */
-export function probeableExploratoryJoins(joins, ctes) {
-    const cteNames = new Set(ctes.map((name) => name.split('.').at(-1)?.toLowerCase() ?? name.toLowerCase()));
-    if (cteNames.size === 0)
+export function probeableExploratoryJoins(joins, ctes, derivedRelations = []) {
+    const internalNames = new Set([...ctes, ...derivedRelations]
+        .map((name) => name.replace(/["`\[\]]/g, '').split('.').at(-1)?.toLowerCase() ?? name.toLowerCase()));
+    if (internalNames.size === 0)
         return joins;
     return joins.filter((join) => ![join.leftRelation, join.rightRelation].some((relation) => {
         const bare = relation?.replace(/["`\[\]]/g, '').split('.').at(-1)?.toLowerCase();
-        return Boolean(bare && cteNames.has(bare));
+        return Boolean(bare && internalNames.has(bare));
     }));
 }
 function declaredExploratoryRelationMatches(sqlRelation, declaredRelation) {