@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/agentic/analyst-loop.d.ts

@@ -0,0 +1,91 @@
+import type { AdmittedIdentifier } from './identifier-ledger.js';
+/**
+ * The analyst loop — explore, then compose, with provenance enforced.
+ *
+ * This is the handler the strangler seam has been holding a slot for. It runs
+ * the governed tools, harvests every identifier a tool actually returned, and
+ * refuses to execute SQL naming anything it did not observe. A violation comes
+ * back as a CORRECTION with the nearest observed name and one bounded retry —
+ * not a refusal, which is what the legacy pipeline turned it into.
+ *
+ * It is deliberately small. The legacy loop earned its 10k lines by owning
+ * retrieval, certified matching, semantic compilation, narration, and trust
+ * labelling; re-implementing any of that here would fork behaviour that already
+ * works. This owns exactly one thing the old path cannot do: notice that a
+ * proposed identifier was never observed, and say which real one was meant.
+ */
+import type { AgentAnswer, AnswerLoopInput } from '../answer-loop.js';
+import type { AgentToolDefinition } from '../providers/types.js';
+import type { AnalystTurnPlan } from './turn-plan.js';
+/** One observable step, so the wait is legible instead of a spinner. */
+export interface AnalystStep {
+    kind: 'plan' | 'tool' | 'observe' | 'verify' | 'answer';
+    label: string;
+    detail?: string;
+}
+export interface AnalystLoopDeps {
+    /** Extract relations/columns from candidate SQL. Injected so the loop does not fork a parser. */
+    extractReferences: (sql: string) => {
+        relations: string[];
+        columns: string[];
+    };
+    /** Turn raw model output into SQL. Injected for the same reason. */
+    parseSql: (raw: string) => string | undefined;
+    /** Tools the model may call. Already surface-filtered by the host. */
+    tools: AgentToolDefinition[];
+    /**
+     * Run the deterministic safety verifiers over candidate SQL and return a
+     * correction, or `undefined` when it passes.
+     *
+     * The verifiers keep their logic — aggregation safety, grain, relationship
+     * proof — but a failure becomes an OBSERVATION the loop can act on instead of
+     * a terminal refusal. That inversion is the point: the legacy path turned
+     * "this would double-count" into "nothing was executed", which is true and
+     * useless. Telling the model that joining those tables fans out is something
+     * it can fix.
+     */
+    verifySql?: (sql: string) => string | undefined;
+    maxIterations: number;
+    /** Physical provider sends available to this text/native tool loop. */
+    maxProviderDispatches?: number;
+    /**
+     * Optional structured planning call. Absent, the loop runs exactly as before
+     * and the trace falls back to a fixed label.
+     */
+    planTurn?: (question: string, toolNames: string[]) => Promise<AnalystTurnPlan | undefined>;
+    onStep?: (step: AnalystStep) => void;
+}
+export interface AnalystOutcome {
+    sql?: string;
+    /** Identifiers the run proved, for the audit trail. */
+    admitted: string[];
+    /** The same admissions with their evidence, for minting an authorization. */
+    admittedEntries: AdmittedIdentifier[];
+    /** Corrections fed back to the model, in order. */
+    corrections: string[];
+    /** Why the loop stopped. */
+    stop: 'composed' | 'no_sql' | 'unverified' | 'budget_exhausted';
+    /** Typed terminal detail: this never grants an execution fallback. */
+    terminal?: 'no_final_sql' | 'tool_budget_exhausted' | 'provider_dispatch_budget_exhausted' | 'unverified_identifiers' | 'missing_execution_binding' | 'tool_loop_error';
+}
+/**
+ * Run explore-then-compose and return verified SQL.
+ *
+ * Returns `stop: 'unverified'` rather than throwing when the repair budget is
+ * spent: the caller decides whether an unverified draft is still worth showing
+ * as review-required, and that is a governance choice, not this loop's.
+ */
+export declare function runAnalystLoop(input: AnswerLoopInput, deps: AnalystLoopDeps): Promise<AnalystOutcome>;
+/**
+ * Wrap the loop as a lane handler, falling back to the legacy answer loop.
+ *
+ * The legacy loop still produces the ANSWER — trust labels, citations,
+ * narration, execution. This only decides whether the SQL that reaches it was
+ * built from observed identifiers. Handing verified SQL to a path that already
+ * knows how to govern it is a much smaller change than replacing that path.
+ */
+export declare function createAnalystLaneHandler(deps: {
+    legacy: (input: AnswerLoopInput) => Promise<AgentAnswer>;
+    buildDeps: (input: AnswerLoopInput) => AnalystLoopDeps | undefined;
+}): (input: AnswerLoopInput) => Promise<AgentAnswer>;
+//# sourceMappingURL=analyst-loop.d.ts.map

package/dist/agentic/analyst-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyst-loop.d.ts","sourceRoot":"","sources":["../../src/agentic/analyst-loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKtD,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC/E,oEAAoE;IACpE,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9C,sEAAsE;IACtE,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;IAC3F,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,eAAe,EAAE,kBAAkB,EAAE,CAAC;IACtC,mDAAmD;IACnD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4BAA4B;IAC5B,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,kBAAkB,CAAC;IAChE,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,GACrB,uBAAuB,GACvB,oCAAoC,GACpC,wBAAwB,GACxB,2BAA2B,GAC3B,iBAAiB,CAAC;CACvB;AAWD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,cAAc,CAAC,CAmIzB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACzD,SAAS,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,eAAe,GAAG,SAAS,CAAC;CACpE,IACe,OAAO,eAAe,KAAG,OAAO,CAAC,WAAW,CAAC,CAoG5D"}

package/dist/agentic/analyst-loop.js

@@ -0,0 +1,311 @@
+import { createAgenticSqlExecutionCapability } from './sql-authorization.js';
+import { runAgenticToolLoopDetailed } from './tool-loop.js';
+import { IdentifierLedger } from './identifier-ledger.js';
+import { ANALYST_TOOL_POLICY, adjudicateProposedSql, withLedgerHarvest } from './ledger-tools.js';
+function budgetTerminalForToolLoop(stop) {
+    return stop === 'tool_budget_exhausted' || stop === 'provider_dispatch_budget_exhausted'
+        ? stop
+        : undefined;
+}
+/**
+ * Run explore-then-compose and return verified SQL.
+ *
+ * Returns `stop: 'unverified'` rather than throwing when the repair budget is
+ * spent: the caller decides whether an unverified draft is still worth showing
+ * as review-required, and that is a governance choice, not this loop's.
+ */
+export async function runAnalystLoop(input, deps) {
+    const ledger = new IdentifierLedger();
+    const corrections = [];
+    // Seed from the context pack. These are retrieved, not observed, so they enter
+    // at the weakest tier — enough to let correct SQL through without pretending a
+    // catalog row proves a column exists in the warehouse.
+    for (const object of input.contextPack?.allowedSqlContext?.relations ?? []) {
+        ledger.admit('catalog', [object.relation, object.name], 'context_pack');
+        ledger.admit('catalog', (object.columns ?? []).map((column) => column.name), 'context_pack');
+    }
+    const tools = withLedgerHarvest(deps.tools, ledger, (event) => {
+        deps.onStep?.({
+            kind: 'observe',
+            label: `${event.tool} returned ${event.admitted} identifier${event.admitted === 1 ? '' : 's'}`,
+        });
+    });
+    const messages = [
+        { role: 'system', content: ANALYST_TOOL_POLICY },
+        { role: 'user', content: input.question },
+    ];
+    // One structured planning call before acting. It is optional by design:
+    // `planAnalystTurn` swallows its own failures, so a slow or unparseable plan
+    // costs a bounded wait and nothing else. What it buys is a trace that names
+    // what the agent is about to verify instead of a fixed string.
+    const turnPlan = deps.planTurn
+        ? await deps.planTurn(input.question, tools.map((tool) => tool.name))
+        : undefined;
+    if (turnPlan) {
+        deps.onStep?.({ kind: 'plan', label: turnPlan.restatement });
+        for (const item of turnPlan.mustEstablish) {
+            deps.onStep?.({ kind: 'plan', label: `Must establish: ${item}` });
+        }
+        // Carry the plan into the loop so it steers the run rather than only
+        // describing it — otherwise the trace would promise work the model never
+        // agreed to do.
+        messages.push({
+            role: 'assistant',
+            content: `Before answering I must establish, using tools:\n${turnPlan.mustEstablish.map((item) => `- ${item}`).join('\n')}${turnPlan.openingTool ? `\nStarting with ${turnPlan.openingTool}.` : ''}`,
+        });
+    }
+    else {
+        deps.onStep?.({ kind: 'plan', label: 'Establishing what exists before writing SQL' });
+    }
+    const initial = await runAgenticToolLoopDetailed(input.provider, messages, tools, {
+        ...(input.signal ? { signal: input.signal } : {}),
+        maxToolCalls: deps.maxIterations,
+        ...(deps.maxProviderDispatches !== undefined ? { maxProviderDispatches: deps.maxProviderDispatches } : {}),
+    });
+    let raw = initial.text;
+    const initialBudgetTerminal = budgetTerminalForToolLoop(initial.stop);
+    if (initialBudgetTerminal) {
+        return {
+            admitted: ledger.entries().map((e) => e.identifier),
+            admittedEntries: ledger.entries(),
+            corrections,
+            stop: 'budget_exhausted',
+            terminal: initialBudgetTerminal,
+        };
+    }
+    let sql = deps.parseSql(raw);
+    if (!sql) {
+        return {
+            admitted: ledger.entries().map((e) => e.identifier),
+            admittedEntries: ledger.entries(),
+            corrections,
+            stop: 'no_sql',
+            terminal: 'no_final_sql',
+        };
+    }
+    // One bounded repair. A second would mostly re-spend the budget: if the first
+    // correction — which names the exact identifier that was observed — does not
+    // land, the problem is not a typo.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        deps.onStep?.({ kind: 'verify', label: 'Checking every identifier was actually observed' });
+        const verdict = adjudicateProposedSql(ledger, deps.extractReferences(sql));
+        // Identifiers first: a safety verdict over SQL naming a column that does not
+        // exist is noise, and would send the model chasing the wrong correction.
+        const safety = verdict.ok ? deps.verifySql?.(sql) : undefined;
+        if (verdict.ok && !safety) {
+            deps.onStep?.({ kind: 'answer', label: 'Verified — every name came from a tool result' });
+            return { sql, admitted: ledger.entries().map((e) => e.identifier), admittedEntries: ledger.entries(), corrections, stop: 'composed' };
+        }
+        const correction = verdict.ok ? safety : verdict.correction;
+        corrections.push(correction);
+        if (attempt === 1)
+            break;
+        deps.onStep?.({
+            kind: 'tool',
+            label: verdict.ok ? 'Correcting an unsafe aggregation' : 'Correcting an unobserved identifier',
+            detail: verdict.ok ? safety : verdict.unadmitted.join(', '),
+        });
+        const repair = await runAgenticToolLoopDetailed(input.provider, [...messages, { role: 'assistant', content: raw }, { role: 'user', content: correction }], tools, {
+            ...(input.signal ? { signal: input.signal } : {}),
+            maxToolCalls: deps.maxIterations,
+            ...(deps.maxProviderDispatches !== undefined ? { maxProviderDispatches: deps.maxProviderDispatches } : {}),
+        });
+        raw = repair.text;
+        const repairBudgetTerminal = budgetTerminalForToolLoop(repair.stop);
+        if (repairBudgetTerminal) {
+            return {
+                admitted: ledger.entries().map((e) => e.identifier),
+                admittedEntries: ledger.entries(),
+                corrections,
+                stop: 'budget_exhausted',
+                terminal: repairBudgetTerminal,
+            };
+        }
+        const repaired = deps.parseSql(raw);
+        if (!repaired)
+            break;
+        sql = repaired;
+    }
+    return {
+        sql,
+        admitted: ledger.entries().map((e) => e.identifier),
+        admittedEntries: ledger.entries(),
+        corrections,
+        stop: 'unverified',
+        terminal: 'unverified_identifiers',
+    };
+}
+/**
+ * Wrap the loop as a lane handler, falling back to the legacy answer loop.
+ *
+ * The legacy loop still produces the ANSWER — trust labels, citations,
+ * narration, execution. This only decides whether the SQL that reaches it was
+ * built from observed identifiers. Handing verified SQL to a path that already
+ * knows how to govern it is a much smaller change than replacing that path.
+ */
+export function createAnalystLaneHandler(deps) {
+    return async (input) => {
+        const noGeneratedExecution = {
+            ...input,
+            forcedGeneratedProposal: undefined,
+            agenticSqlExecutionCapability: undefined,
+            executeGeneratedSql: undefined,
+            executeAgenticGeneratedSql: undefined,
+        };
+        const safeLegacy = async (outcome) => {
+            try {
+                return await deps.legacy(noGeneratedExecution);
+            }
+            catch {
+                // Never let `answerAgentic` turn a failure in the guarded path into an
+                // ambient legacy retry. This explicit no-answer retains the truthful
+                // non-executing terminal rather than emitting a second, unproved SQL.
+                return analystNonExecutingAnswer(input, outcome);
+            }
+        };
+        const loopDeps = deps.buildDeps(input);
+        // A generated agentic route may never fall through to an ambient generated
+        // executor when its proof tools are unavailable. Certified/semantic routes
+        // remain host-owned, but this lane has no generated SQL authority.
+        if (!loopDeps || loopDeps.tools.length === 0) {
+            return safeLegacy({ admitted: [], admittedEntries: [], corrections: [], stop: 'no_sql', terminal: 'no_final_sql' });
+        }
+        let outcome;
+        try {
+            outcome = await runAnalystLoop(input, loopDeps);
+        }
+        catch {
+            outcome = {
+                admitted: [],
+                admittedEntries: [],
+                corrections: [],
+                stop: 'no_sql',
+                terminal: 'tool_loop_error',
+            };
+        }
+        if (process.env.DQL_ORCHESTRATOR_TRACE) {
+            console.warn(`[dql] analyst loop outcome: stop=${outcome.stop} sql=${outcome.sql ? 'yes' : 'no'} admitted=${outcome.admitted.length} corrections=${outcome.corrections.length}`);
+        }
+        const scope = input.agenticExecutionScope;
+        const composedSql = outcome.stop === 'composed' ? outcome.sql : undefined;
+        const capability = composedSql
+            ? createAgenticSqlExecutionCapability({
+                sql: composedSql,
+                // Retrieval catalog rows cannot mint execution authority. Preserve
+                // them in the audit ledger, but pass only observed evidence to the
+                // server-only capability.
+                proven: outcome.admittedEntries
+                    .filter((entry) => entry.source !== 'catalog')
+                    .map((entry) => ({ identifier: entry.identifier, evidence: entry.source })),
+                runId: scope?.runId,
+                executionId: scope?.executionId,
+                snapshotId: scope?.snapshotId ?? input.resolvedAnalyticalPlan?.snapshotId,
+                planId: scope?.planId ?? input.resolvedAnalyticalPlan?.planId,
+                targetFingerprint: scope?.targetFingerprint ?? input.generatedProposalTargetFingerprint,
+                bindings: scope?.bindings ?? {},
+            })
+            : undefined;
+        if (outcome.stop === 'composed' && composedSql && !capability) {
+            outcome = { ...outcome, stop: 'unverified', terminal: 'missing_execution_binding' };
+        }
+        const answer = outcome.stop === 'budget_exhausted'
+            // A terminal budget is not a recoverable model answer. Do not ask the
+            // legacy path to take another generation turn: it would conceal the
+            // terminal reason and could turn an explicit bounded stop into an
+            // unrelated answer. This remains deliberately non-executing.
+            ? analystNonExecutingAnswer(input, outcome)
+            : outcome.stop === 'composed' && composedSql && capability
+                ? await (async () => {
+                    try {
+                        return await deps.legacy({
+                            ...input,
+                            // This is a hard handoff, not prompt context. The legacy answer loop
+                            // keeps its validation/narration/artifact behavior but cannot ask a
+                            // second model to replace the analyst SQL.
+                            forcedGeneratedProposal: {
+                                sql: composedSql,
+                                summary: 'Prepared from identifiers observed during this bounded analyst run. Review-required until an analyst promotes it.',
+                            },
+                            agenticSqlExecutionCapability: capability,
+                        });
+                    }
+                    catch {
+                        // Do not rethrow into `answerAgentic`: its compatibility fallback
+                        // executes the original legacy input, which lacks this capability.
+                        return analystNonExecutingAnswer(input, {
+                            ...outcome,
+                            stop: 'unverified',
+                            terminal: 'tool_loop_error',
+                        });
+                    }
+                })()
+                : await safeLegacy(outcome);
+        // ALWAYS record the verdict, not only when a correction was needed. A
+        // verification that passed is precisely what an audit wants to see, and a
+        // loop that is invisible when it works cannot be told apart from one that
+        // never ran — the same silent-degradation trap the fallback marker avoids.
+        return withAnalystEvidence(answer, outcome);
+    };
+}
+function analystNonExecutingAnswer(input, outcome) {
+    const reason = outcome.terminal === 'missing_execution_binding'
+        ? 'DQL established the query identifiers but could not bind this run to its frozen plan and execution target, so it did not run generated SQL.'
+        : outcome.terminal === 'tool_loop_error'
+            ? 'DQL could not complete the bounded evidence check, so it did not run generated SQL.'
+            : outcome.terminal === 'tool_budget_exhausted'
+                ? 'DQL reached its bounded tool budget before it received final SQL, so no generated warehouse query was run.'
+                : outcome.terminal === 'provider_dispatch_budget_exhausted'
+                    ? 'DQL reached its bounded AI dispatch budget before it received final SQL, so no generated warehouse query was run.'
+                    : outcome.terminal === 'no_final_sql'
+                        ? 'DQL did not receive final SQL from the bounded analyst loop, so no generated warehouse query was run.'
+                        : 'DQL could not verify every generated identifier against a tool observation, so no generated warehouse query was run.';
+    return {
+        kind: 'no_answer',
+        certification: 'analyst_review_required',
+        reviewStatus: 'analyst_review_required',
+        refusalCode: 'grounding_gap',
+        text: reason,
+        answer: reason,
+        citations: [],
+        considered: [],
+        ...(input.contextPack ? { contextPack: input.contextPack } : {}),
+    };
+}
+function withAnalystEvidence(answer, outcome) {
+    // The host initialises `evidence` AFTER the answer call, so at this point it is
+    // usually undefined. Bailing out then silently dropped the verdict on every
+    // real run — the loop worked and left no trace, which is indistinguishable
+    // from it never having run. Create the envelope instead of skipping.
+    const evidence = answer.evidence ?? {
+        route: [], lineage: [], businessContext: [], selectedAssets: [],
+        sourceTables: [], semanticObjects: [], citations: answer.citations ?? [],
+    };
+    return {
+        ...answer,
+        evidence: {
+            ...evidence,
+            route: [
+                ...(evidence.route ?? []),
+                {
+                    tool: 'identifier_ledger',
+                    // 'checked' not 'ok': the ledger VERIFIED the identifiers, it did not
+                    // select the route or execute anything.
+                    status: outcome.stop === 'composed' ? 'checked' : 'failed',
+                    label: outcome.stop === 'composed'
+                        ? `Verified ${outcome.admitted.length} identifier(s) against tool observations`
+                        : outcome.terminal === 'no_final_sql'
+                            ? 'The analyst loop did not produce final SQL; no generated warehouse query was run'
+                            : outcome.terminal === 'tool_budget_exhausted'
+                                ? 'The analyst loop reached its bounded tool budget before final SQL; no generated warehouse query was run'
+                                : outcome.terminal === 'provider_dispatch_budget_exhausted'
+                                    ? 'The analyst loop reached its bounded provider-dispatch budget before final SQL; no generated warehouse query was run'
+                                    : outcome.terminal === 'missing_execution_binding'
+                                        ? 'The analyst proposal had no complete run/plan/target execution binding; no generated warehouse query was run'
+                                        : 'Could not verify every identifier against a tool observation',
+                    ...(outcome.corrections.length > 0 ? { detail: outcome.corrections.join(' ') } : {}),
+                },
+            ],
+        },
+    };
+}
+//# sourceMappingURL=analyst-loop.js.map

package/dist/agentic/analyst-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyst-loop.js","sourceRoot":"","sources":["../../src/agentic/analyst-loop.ts"],"names":[],"mappings":"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"}

package/dist/agentic/assumptions.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Assumptions — the mechanism that lets a turn ANSWER where it would otherwise
+ * ask a question with only one sensible reply.
+ *
+ * The measured baseline on the jaffle fixture was: false-refusal 0%, but
+ * clarification 100%. Nothing dead-ended, yet every answerable question came
+ * back as a question. That is a dead end with extra steps whenever the user's
+ * only real move is to accept the obvious candidate.
+ *
+ * The rule is a MARGIN, not a count. One candidate is not the same as no
+ * ambiguity: a lone `top_beverage_customers` block is a poor answer to "who are
+ * the top customers", and binding it silently would narrow the question without
+ * saying so. What makes an assumption safe is that the leading candidate is
+ * clearly better than the alternatives — and that we say which one we took and
+ * offer the others.
+ */
+/** What part of the question was assumed rather than proven. */
+export type AssumptionAbout = 'metric' | 'grain' | 'timeframe' | 'filter' | 'entity' | 'join';
+export interface AnswerAssumption {
+    about: AssumptionAbout;
+    /** The governed identifier actually used. */
+    chose: string;
+    /** Human label for `chose`, when it differs from the id. */
+    choseLabel?: string;
+    /** One line the user can check at a glance. */
+    because: string;
+    /** Other candidates, offered as one-click corrections. */
+    alternatives: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+/**
+ * How far ahead the leader must be before binding it without asking.
+ *
+ * Set from the shape of the failure it prevents rather than tuned for a score:
+ * at 1.25 a near-tie between two plausible measures still asks, which is the
+ * case where guessing wrong produces a confidently wrong number.
+ */
+export declare const ASSUMPTION_DOMINANCE_RATIO = 1.25;
+export interface AssumptionCandidate {
+    id: string;
+    label: string;
+    score: number;
+}
+/**
+ * Decide whether the leading candidate is safe to assume.
+ *
+ * Returns `undefined` when the field is genuinely ambiguous, so the caller
+ * clarifies instead — that path stays intact on purpose. "Never dead-end" must
+ * not become "always guess": a wrong silent binding is worse than a good
+ * question, because the user cannot see that it happened.
+ */
+export declare function assumeDominantCandidate(input: {
+    about: AssumptionAbout;
+    candidates: AssumptionCandidate[];
+    because: (chosen: AssumptionCandidate) => string;
+    dominanceRatio?: number;
+}): AnswerAssumption | undefined;
+/** One line the user reads above the answer. */
+export declare function renderAssumptionPreamble(assumptions: AnswerAssumption[]): string | undefined;
+//# sourceMappingURL=assumptions.d.ts.map

package/dist/agentic/assumptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.d.ts","sourceRoot":"","sources":["../../src/agentic/assumptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,gEAAgE;AAChE,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,OAAO,GACP,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,YAAY,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,KAAK,EAAE,eAAe,CAAC;IACvB,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,OAAO,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,MAAM,CAAC;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,gBAAgB,GAAG,SAAS,CAwB/B;AAED,gDAAgD;AAChD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,SAAS,CAU5F"}

package/dist/agentic/assumptions.js

@@ -0,0 +1,73 @@
+/**
+ * Assumptions — the mechanism that lets a turn ANSWER where it would otherwise
+ * ask a question with only one sensible reply.
+ *
+ * The measured baseline on the jaffle fixture was: false-refusal 0%, but
+ * clarification 100%. Nothing dead-ended, yet every answerable question came
+ * back as a question. That is a dead end with extra steps whenever the user's
+ * only real move is to accept the obvious candidate.
+ *
+ * The rule is a MARGIN, not a count. One candidate is not the same as no
+ * ambiguity: a lone `top_beverage_customers` block is a poor answer to "who are
+ * the top customers", and binding it silently would narrow the question without
+ * saying so. What makes an assumption safe is that the leading candidate is
+ * clearly better than the alternatives — and that we say which one we took and
+ * offer the others.
+ */
+/**
+ * How far ahead the leader must be before binding it without asking.
+ *
+ * Set from the shape of the failure it prevents rather than tuned for a score:
+ * at 1.25 a near-tie between two plausible measures still asks, which is the
+ * case where guessing wrong produces a confidently wrong number.
+ */
+export const ASSUMPTION_DOMINANCE_RATIO = 1.25;
+/**
+ * Decide whether the leading candidate is safe to assume.
+ *
+ * Returns `undefined` when the field is genuinely ambiguous, so the caller
+ * clarifies instead — that path stays intact on purpose. "Never dead-end" must
+ * not become "always guess": a wrong silent binding is worse than a good
+ * question, because the user cannot see that it happened.
+ */
+export function assumeDominantCandidate(input) {
+    const ranked = [...input.candidates]
+        .filter((candidate) => Number.isFinite(candidate.score))
+        .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+    const leader = ranked[0];
+    if (!leader)
+        return undefined;
+    const runnerUp = ranked[1];
+    const ratio = input.dominanceRatio ?? ASSUMPTION_DOMINANCE_RATIO;
+    // A single candidate is dominant by definition — there is nothing to confuse
+    // it with. Whether it FITS the question is a separate check the caller owns.
+    if (runnerUp) {
+        if (runnerUp.score <= 0) {
+            // Leader is the only scoring candidate; the rest carry no signal.
+        }
+        else if (leader.score < runnerUp.score * ratio) {
+            return undefined;
+        }
+    }
+    return {
+        about: input.about,
+        chose: leader.id,
+        ...(leader.label && leader.label !== leader.id ? { choseLabel: leader.label } : {}),
+        because: input.because(leader),
+        alternatives: ranked.slice(1, 4).map((candidate) => ({ id: candidate.id, label: candidate.label })),
+    };
+}
+/** One line the user reads above the answer. */
+export function renderAssumptionPreamble(assumptions) {
+    if (assumptions.length === 0)
+        return undefined;
+    const lines = assumptions.map((assumption) => {
+        const chosen = assumption.choseLabel ?? assumption.chose;
+        const alternatives = assumption.alternatives.length > 0
+            ? ` Other options: ${assumption.alternatives.map((alternative) => alternative.label).join(', ')}.`
+            : '';
+        return `Assumed ${assumption.about}: **${chosen}** — ${assumption.because}${alternatives}`;
+    });
+    return lines.join('\n');
+}
+//# sourceMappingURL=assumptions.js.map

package/dist/agentic/assumptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.js","sourceRoot":"","sources":["../../src/agentic/assumptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAQ/C;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAKvC;IACC,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;SACjC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;SACvD,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IACtF,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,IAAI,0BAA0B,CAAC;IACjE,6EAA6E;IAC7E,6EAA6E;IAC7E,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YACxB,kEAAkE;QACpE,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,GAAG,KAAK,EAAE,CAAC;YACjD,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,MAAM,CAAC,EAAE;QAChB,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;KACpG,CAAC;AACJ,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,wBAAwB,CAAC,WAA+B;IACtE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC,KAAK,CAAC;QACzD,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;YACrD,CAAC,CAAC,mBAAmB,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAClG,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,WAAW,UAAU,CAAC,KAAK,OAAO,MAAM,QAAQ,UAAU,CAAC,OAAO,GAAG,YAAY,EAAE,CAAC;IAC7F,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/agentic/business-explanation.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Answering "what does this mean?" from governed metadata, without SQL.
+ *
+ * A definitional question — "what does the top_customers block measure?", "how
+ * is revenue defined here?" — is routed to `converse` today, which replies
+ * conversationally with NO governed evidence attached. So the product knows the
+ * answer (it has the description, the owner, the grain, the outputs, the
+ * certification status) and does not use it, which is the shape of the
+ * complaint that Ask AI cannot explain business context.
+ *
+ * This composes the explanation deterministically from what the catalog already
+ * holds. No provider, no warehouse: the facts are all in the object, and a model
+ * paraphrasing them can only add drift.
+ */
+/** The subset of a catalog object this needs. Structural, so any source can supply it. */
+export interface ExplainableObject {
+    objectKey: string;
+    objectType: string;
+    name: string;
+    fullName?: string;
+    description?: string;
+    domain?: string;
+    owner?: string;
+    status?: string;
+    payload?: Record<string, unknown>;
+}
+export interface BusinessExplanation {
+    text: string;
+    /** Object keys the explanation drew on, for the provenance footer. */
+    citations: string[];
+    /**
+     * Whether every claim came from a governed artifact. False when the object is
+     * a raw dbt/warehouse node rather than something a person certified — the
+     * answer is still useful, it is just not an authored definition.
+     */
+    governed: boolean;
+}
+/**
+ * Compose an explanation of one governed object.
+ *
+ * Returns `null` when there is nothing beyond a bare name to say. A confident
+ * paragraph assembled from an empty description is worse than falling through
+ * to the normal cascade: it reads like an answer and carries no information.
+ */
+export declare function explainObject(object: ExplainableObject): BusinessExplanation | null;
+/**
+ * Pick the object a definitional question is about, then explain it.
+ *
+ * Matching is by NAME MENTION, not relevance rank: "what does top_customers
+ * measure?" is asking about a specific artifact, and answering about a merely
+ * similar one would be a different question confidently answered. When nothing
+ * is named, return null and let the cascade run — guessing the subject of a
+ * definition is exactly the failure this is meant to avoid.
+ */
+export declare function composeBusinessExplanation(question: string, objects: readonly ExplainableObject[]): BusinessExplanation | null;
+//# sourceMappingURL=business-explanation.d.ts.map

package/dist/agentic/business-explanation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business-explanation.d.ts","sourceRoot":"","sources":["../../src/agentic/business-explanation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAuCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,IAAI,CAgCnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,mBAAmB,GAAG,IAAI,CA2B5B"}