@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/agentic/value-probe.js

@@ -0,0 +1,304 @@
+/** Values that must never be probed, whatever the configuration says. */
+/**
+ * Hard deny. No configuration overrides this.
+ *
+ * Three groups, and the reason each is here:
+ *   SECRETS — a probe returns literal values, so one match leaks the secret.
+ *   FREE TEXT — a note or description can contain anything, including all of
+ *     the above, so its shape gives no safety.
+ *   DIRECT AND REGULATED IDENTIFIERS — payment, government, contact, health,
+ *     and compensation fields. A probe over these is a data-protection
+ *     incident even when the query is otherwise correct, and "the model asked
+ *     for it" is not a defence. Added after a live run answered a request for
+ *     credit-card numbers and home addresses from the nearest certified block.
+ *
+ * Deliberately broad. A false deny costs one value lookup; a false allow
+ * cannot be undone once the values have left the warehouse.
+ */
+const DENY_RE = /\b(password|passwd|secret|token|credential|apikey|api key|private key|hash|salt|signature|session|cookie|auth|otp|pin)\b|\b(notes?|comments?|description|message|body|payload|content|remarks?|feedback|reason)\b|\b(ssn|social security|social insurance|sin\b|dob|date of birth|birth date|birthdate|national id|government id|government identifier|tax id|taxpayer id|taxpayer identification|tin\b|itin\b|ein\b|medicare|medicaid|passport|license|licence|driver license|visa|nric|aadhaar)\b|\b(card|cardnumber|card number|credit card|debit card|cvv|cvc|iban|swift|bic|routing|account number|acct|sort code|bank)\b|\b(address|street|postal|postcode|zip|zipcode|latitude|longitude|geo|coordinates?)\b|\b(phone|mobile|telephone|fax|contact number)\b|\b(salary|compensation|wage|payroll|bonus|income|net pay|gross pay)\b|\b(medical|diagnosis|patient|health|insurance|prescription|disability|biometric|fingerprint|race|ethnicity|religion|gender|sexual)\b/;
+/** Email is denied separately: it is an identifier, but also direct PII. */
+const EMAIL_RE = /\bemail\b/;
+/** Name shapes that plausibly identify an entity rather than describe one. */
+const IDENTIFIER_TOKENS = new Set([
+    'account', 'category', 'channel', 'city', 'code', 'country', 'customer',
+    'full', 'id', 'key', 'member', 'name', 'number', 'product', 'region',
+    'segment', 'sku', 'state', 'status', 'subscriber', 'tier', 'type', 'user',
+]);
+/**
+ * Token-level aliases that must remain denied even when a connector exposes
+ * them with underscores, dashes, or camel case rather than the prose phrases
+ * above.  The phrase regex is intentionally broad, but `tax_number` and
+ * `customerBirthDt` never contain the literal phrase "tax id" or "birth
+ * date".  Normalise the identifier into tokens before the allow-list gets a
+ * chance to treat its `number` / `customer` part as a business key.
+ */
+const SENSITIVE_IDENTIFIER_PREFIXES = new Set([
+    'government', 'govt', 'national', 'tax', 'taxpayer',
+]);
+const SENSITIVE_IDENTIFIER_SUFFIXES = new Set([
+    'id', 'identifier', 'number', 'no', 'num',
+]);
+// Connector metadata often elides separators inside an otherwise ordinary
+// entity identifier (for example `customer_taxnumber`). Match only a
+// sensitive alias at the end of the compact identifier: this catches the
+// sensitive suffix without turning `customer_id` or `product_number` into a
+// false positive.
+const COMPACT_SENSITIVE_IDENTIFIER_ALIAS_RE = /(?:taxpayer|tax|government|govt|national)(?:id|identifier|number|no|num)$/;
+const COMPACT_BIRTH_DATE_ALIAS_RE = /(?:birth(?:date|dt|day|dob|on)|dateofbirth|birthday)$/;
+/** Types that can hold a searchable literal. */
+const TEXTUAL_TYPE_RE = /\b(char|character|clob|string|text|uuid|varchar|nvarchar)\b/;
+function tokenize(name) {
+    return new Set(name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_\-.]+/g, ' ')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean));
+}
+function isSensitiveIdentifierAlias(tokens) {
+    const has = (...values) => values.some((value) => tokens.has(value));
+    const compact = [...tokens].join('');
+    if (COMPACT_SENSITIVE_IDENTIFIER_ALIAS_RE.test(compact) || COMPACT_BIRTH_DATE_ALIAS_RE.test(compact)) {
+        return true;
+    }
+    // `date_of_birth`, `customer_birth_dt`, and `customerDOB` are all direct
+    // personal identifiers despite their otherwise identifier-shaped names.
+    if (has('dob') || (has('birth') && has('date', 'dt', 'day', 'on')))
+        return true;
+    // Treat a government/tax qualifier plus an identifier suffix as sensitive.
+    // This intentionally does not deny ordinary business identifiers such as
+    // `customer_id`, `product_number`, or `order_code`.
+    return has(...SENSITIVE_IDENTIFIER_PREFIXES)
+        && has(...SENSITIVE_IDENTIFIER_SUFFIXES);
+}
+/**
+ * May this column be probed for a literal?
+ *
+ * Canonical implementation — the host's `isAgentValueProbeColumn` delegates here
+ * so the deny-list has exactly one definition. Two copies of a security rule
+ * drift, and the one that drifts is the one nobody is looking at.
+ */
+export function isProbeSafeColumn(column) {
+    const normalized = column.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_\-.]+/g, ' ').toLowerCase();
+    if (DENY_RE.test(normalized))
+        return false;
+    if (EMAIL_RE.test(normalized))
+        return false;
+    const tokens = tokenize(column.name);
+    if (isSensitiveIdentifierAlias(tokens))
+        return false;
+    if (![...tokens].some((token) => IDENTIFIER_TOKENS.has(token)))
+        return false;
+    const type = column.type?.toLowerCase() ?? '';
+    // An unknown type is allowed: many drivers omit it, and the name gates already
+    // passed. A KNOWN non-textual type is not — a literal cannot live in a float.
+    if (!type)
+        return true;
+    return TEXTUAL_TYPE_RE.test(type);
+}
+/** Escape a single-quoted SQL literal. */
+function sqlLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Quote an identifier ANSI-style, rejecting anything that is not a plain name. */
+function quoteIdentifier(value) {
+    // Identifiers come from the SCHEMA, never from the user, so anything exotic
+    // here means a caller is passing something it should not.
+    if (!/^[A-Za-z_][A-Za-z0-9_$]*$/.test(value))
+        return undefined;
+    return `"${value}"`;
+}
+function quoteRelation(relation) {
+    const parts = relation.split('.').map(quoteIdentifier);
+    return parts.every(Boolean) ? parts.join('.') : undefined;
+}
+/**
+ * Build a bounded DISTINCT lookup for one column.
+ *
+ * Exact match first, then a prefix match on the longer tokens. Prefix rather
+ * than `%term%`: a leading wildcard cannot use an index, and on a large
+ * dimension table that is the difference between a probe and an outage.
+ */
+export function buildValueProbeSql(relation, column, terms, limit = 25) {
+    const quotedRelation = quoteRelation(relation);
+    const quotedColumn = quoteIdentifier(column);
+    if (!quotedRelation || !quotedColumn)
+        return undefined;
+    const cast = `LOWER(CAST(${quotedColumn} AS VARCHAR))`;
+    const predicates = [];
+    for (const term of terms) {
+        const normalized = term.toLowerCase().replace(/\s+/g, ' ').trim();
+        if (!normalized)
+            continue;
+        predicates.push(`${cast} = ${sqlLiteral(normalized)}`);
+        for (const token of normalized.split(' ').filter((part) => part.length >= 4).slice(0, 2)) {
+            predicates.push(`${cast} LIKE ${sqlLiteral(`${token.replace(/[%_\\]/g, '\\$&')}%`)} ESCAPE '\\'`);
+        }
+    }
+    if (predicates.length === 0)
+        return undefined;
+    return [
+        `SELECT DISTINCT CAST(${quotedColumn} AS VARCHAR) AS value`,
+        `FROM ${quotedRelation}`,
+        `WHERE ${quotedColumn} IS NOT NULL AND (${[...new Set(predicates)].slice(0, 8).join(' OR ')})`,
+        `LIMIT ${Math.max(1, Math.min(limit, 50))}`,
+    ].join('\n');
+}
+/** The total maximum value-probe queries a single tool call may issue. */
+export const MAX_VALUE_PROBE_COLUMN_QUERIES = 12;
+/**
+ * A tool that answers "does this literal exist, and in which column?".
+ *
+ * Returns the matched VALUES — which is the point, since the loop needs the
+ * exact stored spelling to build a filter — but only from columns that passed
+ * both gates, and only values the caller already named.
+ */
+export function buildSearchValuesTool(options) {
+    const maxRelations = options.maxRelations ?? 6;
+    const maxColumnQueries = Math.max(1, Math.min(options.maxColumnQueries ?? MAX_VALUE_PROBE_COLUMN_QUERIES, MAX_VALUE_PROBE_COLUMN_QUERIES));
+    return {
+        name: 'search_values',
+        description: 'Check whether a literal the question names (a customer, product, region, status) exists as a value in the data, and get its exact stored spelling. Use it BEFORE filtering on a name, so a filter is built from a real value rather than a guess. Only searches columns approved for value lookup.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['terms'],
+            properties: {
+                terms: { type: 'array', items: { type: 'string' }, description: 'Literals named in the question, e.g. ["Wesley Jenkins"].' },
+                relations: { type: 'array', items: { type: 'string' }, description: 'Optional relations to restrict the search to.' },
+            },
+        },
+        run: async (args) => {
+            const input = (args && typeof args === 'object' ? args : {});
+            const terms = Array.isArray(input.terms)
+                ? input.terms.filter((term) => typeof term === 'string' && term.trim().length > 0)
+                : [];
+            if (terms.length === 0)
+                return { error: 'Pass the literal(s) to look up, e.g. ["Wesley Jenkins"].' };
+            if (!options.enabled) {
+                // Say WHY, and name the setting. A silent empty result here is what
+                // produced the false-absence defect: the loop concluded the value did
+                // not exist when it had simply never been allowed to look.
+                return {
+                    searched: false,
+                    reason: 'Value lookup is disabled for this project. Enable agent.runtimeValueGrounding in dql.config.json to let DQL confirm a named value before filtering on it.',
+                    matches: [],
+                    coverage: {
+                        version: 1,
+                        status: 'disabled',
+                        queryLimit: maxColumnQueries,
+                        queriesAttempted: 0,
+                        relationsRequested: [],
+                        relationsSearched: [],
+                        relationsWithNoSearchableColumn: [],
+                        relationsWithUnbuildableIdentifier: [],
+                        failedRelations: [],
+                        unknownRelations: [],
+                    },
+                };
+            }
+            const requestedRelations = Array.isArray(input.relations)
+                ? [...new Set(input.relations.filter((r) => typeof r === 'string' && r.trim().length > 0).map((r) => r.trim()))]
+                : [];
+            const wanted = requestedRelations.length > 0
+                ? new Set(requestedRelations.map((relation) => relation.toLowerCase()))
+                : undefined;
+            const knownRelations = new Set(options.relations.map((relation) => relation.relation.toLowerCase()));
+            const unknownRelations = requestedRelations.filter((relation) => !knownRelations.has(relation.toLowerCase()));
+            const matches = [];
+            const searched = [];
+            const skipped = [];
+            const unbuildableRelations = new Set();
+            const failedRelations = new Set();
+            let queriesAttempted = 0;
+            let relationBudgetExceeded = false;
+            let queryBudgetExceeded = false;
+            let relationsConsidered = 0;
+            for (const relation of options.relations) {
+                if (wanted && !wanted.has(relation.relation.toLowerCase()))
+                    continue;
+                if (relationsConsidered >= maxRelations) {
+                    relationBudgetExceeded = true;
+                    break;
+                }
+                relationsConsidered += 1;
+                const safe = relation.columns.filter(isProbeSafeColumn);
+                if (safe.length === 0) {
+                    skipped.push(relation.relation);
+                    continue;
+                }
+                for (const column of safe) {
+                    if (queriesAttempted >= maxColumnQueries) {
+                        queryBudgetExceeded = true;
+                        break;
+                    }
+                    const sql = buildValueProbeSql(relation.relation, column.name, terms);
+                    if (!sql) {
+                        // Metadata identifiers are not automatically executable SQL
+                        // identifiers.  Never turn an unquotable schema name into a
+                        // zero-query "not found" claim.
+                        unbuildableRelations.add(relation.relation);
+                        continue;
+                    }
+                    if (!searched.includes(relation.relation))
+                        searched.push(relation.relation);
+                    queriesAttempted += 1;
+                    try {
+                        const result = await options.execute(sql);
+                        const values = (result.rows ?? [])
+                            .map((row) => (Array.isArray(row) ? row[0] : row?.value))
+                            .filter((value) => typeof value === 'string');
+                        if (values.length > 0)
+                            matches.push({ relation: relation.relation, column: column.name, values });
+                    }
+                    catch {
+                        // One unreadable relation must not fail the whole probe; a permission
+                        // error on a single table is normal in a governed warehouse.
+                        failedRelations.add(relation.relation);
+                    }
+                }
+                if (queryBudgetExceeded)
+                    break;
+            }
+            const complete = unknownRelations.length === 0
+                && failedRelations.size === 0
+                && skipped.length === 0
+                && unbuildableRelations.size === 0
+                && !relationBudgetExceeded
+                && !queryBudgetExceeded;
+            const status = unknownRelations.length > 0
+                ? 'unknown_relation'
+                : queryBudgetExceeded || relationBudgetExceeded
+                    ? 'budget_exhausted'
+                    : complete
+                        ? 'complete'
+                        : 'partial';
+            const coverage = {
+                version: 1,
+                status,
+                queryLimit: maxColumnQueries,
+                queriesAttempted,
+                relationsRequested: requestedRelations,
+                relationsSearched: searched,
+                relationsWithNoSearchableColumn: skipped,
+                relationsWithUnbuildableIdentifier: [...unbuildableRelations],
+                failedRelations: [...failedRelations],
+                unknownRelations,
+            };
+            return {
+                searched: searched.length > 0,
+                terms,
+                matches,
+                relationsSearched: searched,
+                ...(skipped.length > 0 ? { relationsWithNoSearchableColumn: skipped } : {}),
+                coverage,
+                // Absence is a claim, not a default for an empty array.  Only an
+                // exhaustive, error-free scan of the approved scope may support it.
+                ...(matches.length === 0 && complete
+                    ? { absence: 'not_found', note: 'Searched the approved columns and found no match for these literals.' }
+                    : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=value-probe.js.map

package/dist/agentic/value-probe.js.map

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

package/dist/analytical-orchestration.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Shared contracts for the conversational analytical orchestrator.
+ *
+ * The existing DQL engine remains the authority for compilation, execution,
+ * trust, and the immutable resolved analytical plan.  This module is the thin
+ * outer contract used by the conversational layer to describe what it
+ * understood, what it searched, and why it could or could not continue.
+ *
+ * The contract is intentionally content-only: it never carries model
+ * chain-of-thought, credentials, raw provider payloads, or authorization.
+ *
+ * Acceptance: AGT-027..033, CTX-007, PERF-003, E2E-022.
+ */
+import type { DqlArtifactExecutionReceipt } from '@duckcodeailabs/dql-core';
+export declare const ANALYTICAL_ORCHESTRATION_CONTRACT_VERSION: 1;
+export type AnalyticalTurnKind = 'conversation' | 'definition' | 'lookup' | 'ranking' | 'breakdown' | 'comparison' | 'drilldown' | 'diagnosis' | 'research' | 'compound' | 'clarification' | 'aggregation';
+export type AnalyticalTaskKind = 'definition' | 'aggregation' | 'ranking' | 'attribute_lookup' | 'breakdown' | 'comparison' | 'drilldown' | 'diagnosis' | 'research_branch';
+export type AnalyticalTaskStatus = 'planned' | 'running' | 'completed' | 'partial' | 'gap' | 'blocked';
+export interface AnalyticalTaskOutputContractV1 {
+    metrics: string[];
+    dimensions: string[];
+    filters: Array<{
+        field: string;
+        value: string;
+    }>;
+    grain?: string;
+    limit?: number;
+    order?: 'asc' | 'desc';
+    requestedColumns?: string[];
+}
+/** A bounded, server-computed dependency between two compound tasks. */
+export interface AnalyticalTaskDependencyV1 {
+    version: 1;
+    kind: 'top_ranked_region';
+    sourceTaskId: string;
+    targetDimension: 'region';
+}
+/**
+ * The only parent-result material a dependent child may receive. It carries
+ * one selected canonical value and its row/result proofs, never parent prose,
+ * SQL, or arbitrary rows.
+ */
+export interface AnalyticalTaskDependencyBindingV1 {
+    version: 1;
+    sourceTaskId: string;
+    sourceResultFingerprint: string;
+    canonicalColumn: string;
+    value: string;
+    rowFingerprint: string;
+}
+export type AnalyticalTaskDependencyResolution = {
+    ok: true;
+    binding: AnalyticalTaskDependencyBindingV1;
+} | {
+    ok: false;
+    code: 'RESULT_CONTRACT_MISMATCH';
+    message: string;
+};
+export interface AnalyticalTaskV1 {
+    version: 1;
+    id: string;
+    kind: AnalyticalTaskKind;
+    question: string;
+    dependencies: string[];
+    dependency?: AnalyticalTaskDependencyV1;
+    output: AnalyticalTaskOutputContractV1;
+    status: AnalyticalTaskStatus;
+    /** Only qualified catalog IDs may be placed in this list. */
+    candidateIds: string[];
+    /** Shared prior-result bindings, e.g. region = Philadelphia. */
+    inheritedBindings: Array<{
+        id: string;
+        value: string;
+        source: 'conversation' | 'result' | 'user';
+    }>;
+}
+/** Durable, content-only outcome for one independent clause/branch. */
+export interface AnalyticalTaskOutcomeV1 {
+    version: 1;
+    taskId: string;
+    status: 'completed' | 'partial' | 'gap' | 'blocked';
+    summary?: string;
+    resultFingerprint?: string;
+    gap?: AnalyticalCoverageGapV1;
+}
+export interface AnalyticalCoverageGapV1 {
+    version: 1;
+    code: 'MISSING_MEASURE' | 'MISSING_DIMENSION' | 'MISSING_ATTRIBUTE' | 'MISSING_RELATIONSHIP' | 'MISSING_RUNTIME_CAPABILITY' | 'RESULT_CONTRACT_MISMATCH' | 'PROVIDER_UNAVAILABLE' | 'EXECUTION_FAILED' | 'AMBIGUOUS_MEANING' | 'POLICY_BLOCKED';
+    phase: 'retrieval' | 'meaning' | 'planning' | 'compilation' | 'execution' | 'presentation';
+    message: string;
+    searchedSources: string[];
+    attemptedRoutes: Array<'certified' | 'semantic' | 'governed_relational' | 'generated' | 'research'>;
+    missing: string[];
+    recoverable: boolean;
+    planFrozen: boolean;
+    nextActions: string[];
+}
+export interface AnalyticalTurnPlanV1 {
+    version: 1;
+    turnId?: string;
+    question: string;
+    kind: AnalyticalTurnKind;
+    /** Natural-language turns use one bounded interpretation call by default. */
+    meaningCallBudget: 0 | 1;
+    meaningCallReason: 'explicit_binding' | 'conversation_only' | 'candidate_interpretation' | 'frozen_research_child';
+    snapshotId?: string;
+    sourceFingerprint?: string;
+    taskIds: string[];
+    tasks: AnalyticalTaskV1[];
+    authorityOrder: Array<'certified' | 'semantic' | 'governed_relational' | 'generated'>;
+    /** This is set only after compatibility and authorization have passed. */
+    frozen: boolean;
+    conversationTurnId?: string;
+    parentRunId?: string;
+}
+export interface AnalyticalAnswerSectionV1 {
+    version: 1;
+    id: string;
+    taskId: string;
+    status: 'answered' | 'partial' | 'gap' | 'blocked';
+    answer?: string;
+    result?: CanonicalQueryResultV1;
+    gap?: AnalyticalCoverageGapV1;
+    factIds: string[];
+    trustState: 'certified' | 'governed' | 'review_required' | 'not_applicable' | 'blocked';
+}
+export interface AnalyticalTurnAnswerV1 {
+    version: 1;
+    answer: string;
+    sections: AnalyticalAnswerSectionV1[];
+    followUps: string[];
+    facts: string[];
+}
+/**
+ * Small, explainable intent vocabulary used before the physical plan exists.
+ * It is deliberately not a second semantic matcher: candidate identity still
+ * comes from retrieval plus the bounded meaning call. These helpers only turn
+ * a request into a task graph and output contract, so a compound question can
+ * report partial success instead of collapsing the whole turn to one error.
+ */
+export declare function inferAnalyticalTurnKind(question: string): AnalyticalTurnKind;
+export declare function splitAnalyticalTasks(question: string): string[];
+export declare function buildAnalyticalTaskGraph(input: {
+    question: string;
+    /**
+     * Explicit user-selected mode. Research is a root workflow, not merely a
+     * higher reasoning effort: its evidence ledger and synthesis must retain the
+     * whole question rather than treating story clauses as independent asks.
+     */
+    mode?: 'ask' | 'research';
+    candidateIds?: string[];
+    metrics?: string[];
+    dimensions?: string[];
+    filters?: Array<{
+        field: string;
+        value: string;
+    }>;
+    inheritedBindings?: Array<{
+        id: string;
+        value: string;
+        source: 'conversation' | 'result' | 'user';
+    }>;
+    maxTasks?: number;
+}): {
+    kind: AnalyticalTurnKind;
+    tasks: AnalyticalTaskV1[];
+    partial: boolean;
+};
+export declare function buildAnalyticalTurnPlan(input: {
+    question: string;
+    mode?: 'ask' | 'research';
+    turnId?: string;
+    candidateIds?: string[];
+    metrics?: string[];
+    dimensions?: string[];
+    filters?: Array<{
+        field: string;
+        value: string;
+    }>;
+    inheritedBindings?: Array<{
+        id: string;
+        value: string;
+        source: 'conversation' | 'result' | 'user';
+    }>;
+    zeroCallReason?: AnalyticalTurnPlanV1['meaningCallReason'];
+    frozen?: boolean;
+    snapshotId?: string;
+    sourceFingerprint?: string;
+}): AnalyticalTurnPlanV1;
+export declare function summarizeTaskOutcomes(tasks: AnalyticalTaskV1[]): {
+    status: 'completed' | 'partial' | 'gap' | 'blocked';
+    completed: string[];
+    gaps: string[];
+};
+export interface CanonicalQueryResultV1 {
+    version: 1;
+    columns: string[];
+    rows: Array<Record<string, unknown>>;
+    rowCount: number;
+    executionTime?: number;
+    truncated?: boolean;
+    /** The exact execution proof is carried through every transport boundary. */
+    executionReceipt?: DqlArtifactExecutionReceipt;
+    /** Trust/tier are descriptive identity, never inferred by a renderer. */
+    trustState?: 'certified' | 'governed' | 'review_required' | 'not_applicable' | 'blocked';
+    answerTier?: string;
+    resultFingerprint: string;
+}
+/**
+ * A reader-selected value from a previously rendered canonical result.
+ *
+ * This is intentionally a reference, not copied conversational prose. The
+ * host must resolve `sourceRunId` from its durable run store and validate every
+ * field against the persisted result before the binding may influence routing,
+ * value lookup, or SQL planning.
+ */
+export interface AgentSelectedResultBindingV1 {
+    version: 1;
+    sourceRunId: string;
+    sourceArtifactId: string;
+    canonicalColumn: string;
+    value: string;
+    rowFingerprint: string;
+    resultFingerprint: string;
+}
+export type AgentSelectedResultBindingValidation = {
+    ok: true;
+    binding: AgentSelectedResultBindingV1;
+} | {
+    ok: false;
+    code: 'RESULT_BINDING_INVALID' | 'RESULT_BINDING_RESULT_MISMATCH' | 'RESULT_BINDING_ROW_MISMATCH';
+    message: string;
+};
+/** Stable scalar transport for a selected canonical result cell. */
+export declare function canonicalResultBindingValue(value: unknown): string | undefined;
+/** A row proof includes all canonical columns, not just the selected cell. */
+export declare function canonicalResultRowFingerprint(result: Pick<CanonicalQueryResultV1, 'columns'>, row: Record<string, unknown>): string;
+/**
+ * Validate an untrusted selected-result reference against a persisted
+ * canonical result. The source run/artifact identities are checked by the
+ * host before calling this pure result-level validator.
+ */
+export declare function validateSelectedResultBinding(binding: AgentSelectedResultBindingV1 | undefined, result: CanonicalQueryResultV1 | undefined): AgentSelectedResultBindingValidation;
+/**
+ * Derive the one value a `top region -> customers in that region` child may
+ * consume. A first row alone is never proof. The parent must either return an
+ * explicit rank, or be the server-computed descending ranking task and return
+ * at least two rows with one strictly-leading numeric measure. `rowCount` is
+ * the returned-row contract, not proof that a singleton is the complete group
+ * set. Ties and ambiguous result shapes remain a typed child gap.
+ */
+export declare function resolveTopRankedRegionDependency(sourceTaskId: string, result: CanonicalQueryResultV1 | undefined, parentTask?: Pick<AnalyticalTaskV1, 'kind' | 'output'>): AnalyticalTaskDependencyResolution;
+/**
+ * Normalize connector, MetricFlow, and provider result shapes at one boundary.
+ * Connectors may return `ColumnMeta[]` and rows as arrays; UI surfaces should
+ * never need to guess how to index those rows.
+ */
+export declare function normalizeCanonicalQueryResult(input: {
+    columns?: unknown;
+    rows?: unknown;
+    rowCount?: unknown;
+    executionTime?: unknown;
+    executionTimeMs?: unknown;
+    truncated?: unknown;
+    resultFingerprint?: unknown;
+    executionReceipt?: unknown;
+    trustState?: unknown;
+    answerTier?: unknown;
+}): CanonicalQueryResultV1;
+export declare function canonicalResultRows(result: CanonicalQueryResultV1): unknown[][];
+export declare function assertCanonicalResult(result: CanonicalQueryResultV1): void;
+export interface ContextCandidateCardV1 {
+    id: string;
+    lane: 'exact' | 'lexical' | 'vector' | 'graph' | 'runtime_value' | 'domain' | 'skill' | 'conversation' | 'certified' | 'semantic' | 'relational' | 'business';
+    relevance: number;
+    trust?: 'certified' | 'semantic' | 'governed_sql' | 'exploratory';
+    compatible?: boolean;
+    summary?: string;
+}
+export interface ContextFusionDiagnosticsV1 {
+    lanes: Record<string, {
+        returned: number;
+        durationMs?: number;
+        status?: 'ok' | 'empty' | 'error' | 'skipped';
+        error?: string;
+        skippedReason?: string;
+    }>;
+    selectedIds: string[];
+    truncated: boolean;
+}
+export interface ContextFusionResultV1 {
+    candidates: ContextCandidateCardV1[];
+    diagnostics: ContextFusionDiagnosticsV1;
+}
+/** Reciprocal-rank fusion keeps recall across lexical, vector, and graph lanes. */
+export declare function fuseContextCandidates(lanes: Record<string, ContextCandidateCardV1[]>, limit?: number): ContextFusionResultV1;
+export declare function retrieveContextLanes(lanes: Record<string, () => Promise<ContextCandidateCardV1[]>>, limit?: number, maxConcurrent?: number): Promise<ContextFusionResultV1>;
+export interface ResearchLedgerEntryV1 {
+    id: string;
+    branchId: string;
+    question: string;
+    status: 'observed' | 'failed' | 'skipped';
+    /** Optional complete execution proof; arbitrary IDs are never accepted. */
+    executionReceipt?: DqlArtifactExecutionReceipt;
+    resultFingerprint?: string;
+    rowCount?: number;
+    facts: string[];
+    receipts: string[];
+    error?: string;
+}
+export interface ResearchEvidenceLedgerV1 {
+    version: 1;
+    rootQuestion: string;
+    planId?: string;
+    snapshotId?: string;
+    entries: ResearchLedgerEntryV1[];
+    factIds: string[];
+    stoppingReason: 'completed' | 'budget' | 'insufficient_evidence' | 'blocked' | 'not_started';
+}
+export declare function capResearchBranches<T>(branches: T[], max?: number): T[];
+export declare function buildResearchEvidenceLedger(input: {
+    rootQuestion: string;
+    planId?: string;
+    snapshotId?: string;
+    entries: ResearchLedgerEntryV1[];
+    stoppingReason?: ResearchEvidenceLedgerV1['stoppingReason'];
+}): ResearchEvidenceLedgerV1;
+/** The only accepted host-side execution identity is a SHA-256 fingerprint. */
+export declare function normalizeAnalyticalExecutionFingerprint(value: unknown): string | undefined;
+/**
+ * Normalize a complete DQL execution receipt. A partial object or arbitrary
+ * identifier is deliberately not execution evidence.
+ */
+export declare function normalizeAnalyticalExecutionReceipt(value: unknown): DqlArtifactExecutionReceipt | undefined;
+export declare function buildCoverageGap(input: Omit<AnalyticalCoverageGapV1, 'version'>): AnalyticalCoverageGapV1;
+//# sourceMappingURL=analytical-orchestration.d.ts.map