@duckcodeailabs/dql-cli 1.14.2 → 1.14.4

package/dist/local-runtime.d.ts

@@ -1,11 +1,12 @@
 import type { ProviderDispatchPhaseV1, ProviderEgressPurpose } from '@duckcodeailabs/dql-core';
+import { watch } from "node:fs";
 import { QueryExecutor, type ConnectionConfig, type DatabaseConnector, type QueryResult, type SQLParamSpec } from "@duckcodeailabs/dql-connectors";
 import { type NotebookCell, type SemanticRefResolutionOptions } from '@duckcodeailabs/dql-notebook';
-import { type SemanticLayer, type MetricDefinition, type SemanticLayerProviderConfig, type DashboardDocument, type DashboardGridItem, type DQLManifest, type DqlArtifactReference, type ManifestBlock, type DomainInput, type AnalyticalRepairCapabilityV1 } from '@duckcodeailabs/dql-core';
-import { type AgenticSqlExecutionCapabilityV1, type SqlAuthorizationCheck } from '@duckcodeailabs/dql-agent';
+import { LineageGraph, type SemanticLayer, type MetricDefinition, type SemanticLayerProviderConfig, type DashboardDocument, type DashboardGridItem, type DQLManifest, type DqlArtifactReference, type ManifestBlock, type DomainInput, type AnalyticalRepairCapabilityV1, type AgentRunTelemetryV1 } from '@duckcodeailabs/dql-core';
+import { type AgenticSqlExecutionCapabilityV1, type AskTraceObserverV1, type SqlAuthorizationCheck } from '@duckcodeailabs/dql-agent';
 import type { AgentRunner as LLMAgentRunner, ProviderDispatchTerminalEvidence, ProviderDispatchEvidenceSink, ProviderId } from './llm/types.js';
-import { type JoinPatternCandidate, type AnalyticalFreshnessRequestV1, type AnalyticalFailedRunV1, type AgentAnswer, type WarehouseSqlFailureV1, type ConversationTurnInput, type AgentResultPayload, type AgentSchemaTable, type RuntimeSchemaSnapshot, type ProposalResult, type ProposePlan, type ProposePlanCandidate, type ProposeConfigInput, type DomainContextEnvelope, type ResolveDomainContextInput, type AgentRun, type AgentRunExecutors, type AgentRunRequest, type AgentRunBudget, type AgentRunRequestedMode, type AgentRunRoute, type AgentRunStopReason, type AgentRunTrustState, type IntentDecision, type ProviderDispatchEvent, type ProviderResultRowEgressPolicy, type AnalyticalTaskV1, type AnalyticalTaskDependencyBindingV1, type AnalyticalTaskDependencyResolution } from '@duckcodeailabs/dql-agent';
-import type { NotebookResearchDqlArtifact } from '@duckcodeailabs/dql-project';
+import { type JoinPatternCandidate, SqliteAgentRunStore, type AnalyticalFreshnessRequestV1, type AnalyticalFailedRunV1, type AgentAnswer, type WarehouseSqlFailureV1, type ConversationTurnInput, type AgentResultPayload, type AgentProvider, type AgentSchemaTable, type RuntimeSchemaSnapshot, type MetadataObject, type ProposalResult, type ProposePlan, type ProposePlanCandidate, type ProposeConfigInput, type DomainContextEnvelope, type ResolveDomainContextInput, type AgentRun, type AgentRunExecutors, type AgentRunRequest, type AgentRunBudget, type AgentRunRequestedMode, type AgentRunRoute, type AgentRunStopReason, type AgentRunTrustState, type AgentEvidenceCandidate, type AgentRetrievalEvidence, type AnalyticalRequirementSeedV1, type ResolvedAnalyticalPlan, type IntentDecision, type ProviderDispatchEvent, type ProviderDispatchCompletionEvent, type ProviderDispatchRejectionEvent, type ProviderResultRowEgressPolicy, type AnalyticalTaskV1, type AnalyticalTaskDependencyBindingV1, type AnalyticalTaskDependencyResolution, type AskSemanticEngineV1, type AskSemanticRuntimeSelectionV1, type AskSemanticCapabilityHandleV1, type ResearchLineageEvidenceReceiptV1 } from '@duckcodeailabs/dql-agent';
+import type { NotebookResearchDqlArtifact, NotebookResearchRun } from '@duckcodeailabs/dql-project';
 import { type InvariantResult } from '@duckcodeailabs/dql-governance';
 import { type BlockStudioImportInputMode, type BlockStudioImportSource, type BlockStudioImportSourceKind, type DqlGenerationSession } from './block-studio-import.js';
 import { type ConnectionMetadataScopeInput } from './warehouse-metadata.js';
@@ -59,11 +60,10 @@ export interface ProjectConfig {
             searchSafeColumns?: string[];
         };
         /**
-         * How many executed rows may reach the AI provider when it writes the answer.
-         * Defaults to a bounded, redacted sample: a model that cannot see the values
-         * cannot describe them, and the fallback for that is a `column: value` dump.
-         * Set `mode: 'disabled'` to keep every cell value on the host — narration
-         * still runs, grounded in column names and computed statistics only.
+         * Maximum redacted result rows that may reach the provider for an explicit
+         * Research run with one-run consent. Ordinary Ask and Research without
+         * consent keep every result value host-local. Set `mode: 'disabled'` (or
+         * zero rows) to disable even opted-in Research row egress.
          */
         providerResultRowEgress?: {
             mode?: 'bounded_sample' | 'disabled';
@@ -141,7 +141,125 @@ export interface LocalServerOptions {
     agentRunExecutors?: AgentRunExecutors;
     /** Host-owned rollback seam; never read from client request payloads. */
     requireMeaningCallForNaturalLanguage?: boolean;
+    /** Whole-runtime rollout control; never accepted from browser/MCP payloads. */
+    askAnalystRuntimeMode?: 'legacy' | 'shadow' | 'authoritative';
+    /** V2 is the default Ask ingress; V1 remains an explicit operator rollback. */
+    askAgentRuntimeMode?: AskAgentRuntimeMode;
+    /**
+     * Host-only Ask-planner provider seam for deterministic local-runtime
+     * integration tests.  It is never read from HTTP/MCP payloads and does not
+     * grant a caller provider, route, or execution authority.
+     */
+    askAnalyticalPlannerProviderFactory?: (input: {
+        projectRoot: string;
+        request: AgentRunRequest;
+    }) => AgentProvider | null | Promise<AgentProvider | null>;
+    /**
+     * Host-only watcher seam for local-runtime tests and embeddings. Production
+     * uses `fs.watch`; browser/MCP input can never select a watcher or its scope.
+     */
+    projectWatcherFactory?: typeof watch;
+    /**
+     * Per-runtime capability minted by the local CLI launcher. Only a matching
+     * request header may label a trace as `cli`; public JSON never carries this
+     * authority and browser/MCP requests remain their own server-owned surface.
+     */
+    trustedCliTraceToken?: string;
+}
+/**
+ * The Ask rollout mode is an operator-owned server setting.  It is never
+ * parsed from an Ask HTTP/MCP payload, but the built CLI may select it at
+ * startup so an operator can run an explicit authoritative canary.
+ */
+export declare const ASK_AGENT_RUNTIME_MODES: readonly ["legacy_v1", "shadow_v2", "authoritative_v2"];
+export type AskAgentRuntimeMode = typeof ASK_AGENT_RUNTIME_MODES[number];
+export declare function resolveAskAgentRuntimeMode(value: unknown, options?: {
+    legacyFallback?: boolean;
+}): AskAgentRuntimeMode;
+/**
+ * The project's persisted Ask runtime mode, from `agent.askRuntimeMode` in
+ * `dql.config.json`.
+ *
+ * Without this, `authoritative_v2` was reachable only by typing a flag on one
+ * command (`dql notebook`), so a canary could not survive a restart and no
+ * other Ask surface — `dql serve`, `dql preview`, `dql agent ask` — could
+ * enter it at all. An operator selecting a rollout mode is making a project
+ * decision, and it should persist like one.
+ *
+ * Precedence is CLI flag > project config > default. The default stays
+ * `shadow_v2`: a rollout control that turns itself on is not a rollout
+ * control.
+ */
+export declare function readProjectAskRuntimeMode(projectRoot: string): unknown;
+/** One-time local capability lifetime. It is never persisted or sent to a provider. */
+export declare const CLI_ASK_TRACE_CAPABILITY_TTL_MS = 30000;
+export interface LocalCliAskTraceCapabilityV1 {
+    capability: string;
+    expiresAt: string;
+    scope: 'agent-runs';
 }
+export interface LocalCliAskTraceCapabilityRegistryV1 {
+    issue(input?: {
+        capability?: string;
+        nowMs?: number;
+        ttlMs?: number;
+    }): LocalCliAskTraceCapabilityV1;
+    consume(input: {
+        capability: string | string[] | undefined;
+        scope: LocalCliAskTraceCapabilityV1['scope'];
+        loopbackServer: boolean;
+        remoteAddress?: string;
+        nowMs?: number;
+    }): 'cli' | undefined;
+}
+/**
+ * Host-owned, one-shot attribution capabilities for an already-local runtime.
+ * A plain client header is never enough: it must be minted by this process,
+ * unexpired, scoped to AgentRun admission, and arrive over loopback.
+ */
+export declare function createLocalCliAskTraceCapabilityRegistryV1(options?: {
+    now?: () => number;
+    mint?: () => string;
+}): LocalCliAskTraceCapabilityRegistryV1;
+/**
+ * Opaque host-only capability for one cold exact-literal grounding probe.
+ * Unlike the trace-header capability above, this is never returned through an
+ * HTTP response: the runtime holds the token only long enough to invoke its
+ * local callback and strips it before any planner, trace, receipt, or store
+ * projection. The registry owns the physical field details.
+ */
+export declare const CLI_ASK_LITERAL_PROBE_CAPABILITY_TTL_MS = 45000;
+export interface LocalLiteralProbeCapabilityRegistryV1 {
+    issue(input: {
+        request: AgentRunRequest;
+        snapshotId: string;
+        candidate: AgentEvidenceCandidate;
+        relation: string;
+        column: string;
+        token?: string;
+        nowMs?: number;
+    }): string | undefined;
+    consume(input: {
+        token: unknown;
+        request: AgentRunRequest;
+        snapshotId?: string;
+        activeSnapshotId?: string;
+        candidate: AgentEvidenceCandidate;
+        relation: string;
+        column: string;
+        nowMs?: number;
+    }): boolean;
+}
+/**
+ * The local process holds the only mapping from an opaque token to its exact
+ * request, snapshot, candidate identity, and physical field. `consume` is
+ * intentionally fail-closed and deletes a successful authorization before
+ * the caller can construct or execute the probe SQL.
+ */
+export declare function createLocalLiteralProbeCapabilityRegistryV1(options?: {
+    now?: () => number;
+    mint?: () => string;
+}): LocalLiteralProbeCapabilityRegistryV1;
 export interface AppCopilotResearchAgentInput {
     appId: string;
     dashboardId?: string;
@@ -164,6 +282,19 @@ export interface AppCopilotResearchAgentInput {
 }
 /** AGT-007 / AGT-022: App-specific context adapter into the uniform AgentRun. */
 export declare function buildAppCopilotResearchAgentRequest(input: AppCopilotResearchAgentInput): AgentRunRequest;
+export declare function askTraceQuestionPreview(question: string): string | undefined;
+/**
+ * The notebook has exactly two trace client routes. Decode only the single
+ * detail segment for validation so a valid encoded run id (for example
+ * `run%3Aoffice-42`) reaches the SPA, while encoded slashes, malformed escapes,
+ * and nested paths stay ordinary 404s.
+ */
+export declare function isAskTraceClientDetailPath(pathname: string): boolean;
+/**
+ * Ask owns only these client-side routes. Keep the static fallback explicit so
+ * a notebook reload works while an arbitrary missing path remains a real 404.
+ */
+export declare function isAskClientRoutePath(pathname: string): boolean;
 /** UI catalog fallback labels are not declared project domains. */
 /**
  * Resolve a UI-pinned domain scope, tolerating one that no longer exists.
@@ -254,7 +385,7 @@ export declare function scheduleCompoundAnalyticalTasks<T>(input: {
 /** What kind of narration a settled run has earned, and how many rows may ground it. */
 export type AgentNarrationPlan = {
     mode: 'skip';
-    reason: 'no_answer' | 'no_provider' | 'nothing_to_narrate';
+    reason: 'no_answer' | 'no_provider' | 'nothing_to_narrate' | 'ordinary_ask';
 }
 /** Claim-verified narration over the immutable fact set (analytical graph lanes). */
  | {
@@ -270,17 +401,12 @@ export type AgentNarrationAnswer = Pick<AgentAnswer, 'kind'> & Partial<Pick<Agen
 /**
  * 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.
+ * An ordinary Ask already spends its one permitted model call resolving meaning.
+ * Its settled answer is the deterministic, receipt-bound answer produced by the
+ * selected analytical tier; sending result rows to a second narrator would add
+ * a hidden provider phase, change the egress receipt, and make a governed
+ * semantic run look like Research. Only an explicit Research request may run
+ * this optional, fact-checked narration stage.
  */
 export declare function planAgentRunNarration(governedAnswer: AgentNarrationAnswer, context: {
     requestedMode?: AgentRunRequestedMode;
@@ -321,6 +447,37 @@ export declare function compoundTrustState(childTrust: readonly AgentRunTrustSta
 export declare function compoundStopReason(completedCount: number, childCount: number, trustState: AgentRunTrustState): AgentRunStopReason;
 export declare function semanticAnswerHasPassedAggregationProof(governedAnswer: Pick<AgentAnswer, 'route' | 'aggregationSafetyProof'>): boolean;
 export declare function agentAnswerHasExecutionFailure(governedAnswer: Pick<AgentAnswer, 'executionError'>): boolean;
+/**
+ * An error-shaped compatibility string is not enough to rewrite an Ask
+ * failure into an execution incident when the producer retained a typed
+ * analytical boundary. Compiler and result-contract failures can carry the
+ * same redacted string for legacy display, but neither statement reached the
+ * SQL execution failure boundary. Old payloads without a typed failure retain
+ * the legacy compatibility projection.
+ */
+export declare function agentAnswerHasExecutionBoundaryFailure(governedAnswer: Pick<AgentAnswer, 'executionError' | 'analyticalFailure'>): boolean;
+/**
+ * Keep the producer's original refusal evidence intact, but never present a
+ * post-freeze execution failure as a retrieval gap. Older answer-loop paths
+ * used `grounding_gap` as their compatibility code even after a connector or
+ * SQL attempt failed. The runtime is the presentation/persistence boundary,
+ * so it projects that one case to the additive execution code without
+ * changing the frozen plan, selected route, or source answer.
+ */
+export declare function projectAnswerExecutionFailureForRun(answer: AgentAnswer): AgentAnswer;
+/** A user-facing terminal heading must follow the producer's typed boundary. */
+export declare function terminalFailureTitleForAnswer(answer: Pick<AgentAnswer, 'refusalCode' | 'analyticalFailure' | 'refusalDetails'>): string;
+/**
+ * One local-runtime projection supplies all terminal presentation/evaluation
+ * consumers. This prevents an execution-shaped legacy string from making the
+ * title, telemetry, or evaluation disagree with the typed failure boundary.
+ */
+export declare function projectTerminalAnalyticalFailureForRun(answer: AgentAnswer): {
+    answer: AgentAnswer;
+    executionFailure: boolean;
+    fallbackReason?: string;
+    title: string;
+};
 /**
  * Return only a router/producer-issued analytical gap witness.
  *
@@ -359,6 +516,28 @@ export declare function repairPresentationContextFromAgentRun(run: AgentRun): Re
 export declare function analyticalFailureAllowsDeterministicRetry(failure?: WarehouseSqlFailureV1): boolean;
 /** Structured policy/access refusals stay terminal even when retained SQL exists. */
 export declare function analyticalFailureAllowsAppRepair(failure?: AgentAnswer['analyticalFailure']): boolean;
+/**
+ * Resolve a browser-selected result cell from durable local run storage. This
+ * remains valid after a notebook reload because the browser transmits only
+ * stable IDs/fingerprints; result values are accepted only after this host
+ * checks the persisted canonical result and artifact trust state.
+ */
+export declare function hydratePersistedSelectedResultBinding(request: AgentRunRequest, store: Pick<SqliteAgentRunStore, 'get'>): void;
+/**
+ * Materialize a plural prior-result reference before the authoritative Ask
+ * runtime frames the request.  `buildAgentRunContextPack` also classifies
+ * follow-ups for retrieval diagnostics, but it runs after the Ask runtime has
+ * built its immutable requirement seed.  Applying this only after retrieval
+ * made "those customers" an explanation-only hint and let a follow-up rank
+ * the entire warehouse.
+ *
+ * This is intentionally an HTTP-host boundary: it accepts only the
+ * server-reconstructed conversation envelope for the requested persisted
+ * thread. Browser conversation JSON cannot supply this filter, a prior member
+ * set, a shape anchor, or a host requirement seed. The values remain local
+ * execution context; they are never copied into provider prompts.
+ */
+export declare function hydratePersistedPriorResultMemberBinding(request: AgentRunRequest): void;
 /**
  * Presentation projection of a run, for anything that SHIPS it — thread history
  * and the live SSE stream alike.
@@ -395,12 +574,58 @@ export declare function agentRunListEntryForTransport(run: AgentRun): AgentRun;
 export declare function conversationTurnInputFromRun(run: AgentRun): ConversationTurnInput;
 /** UI-007 / E2E-005: report the installed CLI version that owns this runtime. */
 export declare function readDqlRuntimeVersion(runtimeUrl?: string): string;
+/** Server-owned cap for physical provider sends in one Ask run. */
+export interface AgentRunProviderDispatchBudget {
+    total: number;
+    /** Legacy/no-evidence category calls have their own one-call allowance. */
+    classification?: number;
+    meaningResolution: number;
+    /** Optional stricter cap for planning inside `generationGroup`. */
+    planning?: number;
+    /**
+     * One verifier-directed, same-snapshot revision after a successfully
+     * admitted initial analytical planner call.  This is deliberately separate
+     * from the ordinary planning and SQL-generation limits: it cannot turn into
+     * a second free-form plan or consume the SQL generation allowance.
+     */
+    planningRevision?: number;
+    /** One root Research hypothesis plan; separate from child Simple-Ask plans. */
+    researchHypothesisPlanning?: number;
+    generationGroup: number;
+    narration: number;
+    repair: number;
+    /** Authoritative Ask V2's first LLM-controlled tool turn. */
+    agentControl?: number;
+    /** Authoritative Ask V2 tool observations/follow-up turns after control. */
+    toolFollowup?: number;
+}
+/**
+ * The one runtime authority for provider-send caps.
+ *
+ * Research is limited to twelve physical sends total, one planner, and one
+ * narrator. Ordinary generated lookup normally gets two sends across
+ * candidate-ID meaning and planning/generation. A router-frozen bounded
+ * exploratory plan may use one additional, same-plan provider correction only
+ * after the generation response declines SQL. That third send is a `repair`,
+ * not an LLM replan: it retains the frozen snapshot, target, closure, output
+ * tuple, and route. Classification is a separate legacy/no-evidence phase,
+ * but still consumes the total cap and cannot coexist with candidate-ID
+ * meaning resolution in the ledger.
+ */
+export declare function agentRunProviderDispatchBudgetForMode(requestedMode: AgentRunRequestedMode | undefined): AgentRunProviderDispatchBudget;
 export declare class RunScopedProviderDispatchEvidence implements ProviderDispatchEvidenceSink {
     private readonly policy;
     private readonly runBudget?;
     private readonly rowEgress;
     private readonly receipts;
     private readonly phaseCounts;
+    /** Planning revisions have their own verifier-owned admission slot. */
+    private planningInitialCount;
+    private planningRevisionCount;
+    /** The one root Research hypothesis-plan transport. */
+    private researchHypothesisPlanningCount;
+    /** At most one physical same-provider transient retry may be admitted per run. */
+    private retryCount;
     private currentRoute;
     /** Wall-clock start of the previous dispatch, used to learn this provider's cost. */
     private lastDispatchStartedAtMs?;
@@ -423,19 +648,7 @@ export declare class RunScopedProviderDispatchEvidence implements ProviderDispat
      */
     private nowMs;
     private recordDispatchStart;
-    constructor(policy: {
-        total: number;
-        meaningResolution: number;
-        generationGroup: number;
-        /**
-         * Narration has its own bucket. It used to share `generationGroup`, so a
-         * run that spent its generation attempts had nothing left to write the
-         * answer with and threw `PROVIDER_DISPATCH_BUDGET_EXHAUSTED` — which is how
-         * an ordinary Ask ended up shipping its deterministic draft as the answer.
-         */
-        narration: number;
-        repair: number;
-    }, runBudget?: AgentRunBudget | undefined, rowEgress?: ProviderResultRowEgressPolicy);
+    constructor(policy: AgentRunProviderDispatchBudget, runBudget?: AgentRunBudget | undefined, rowEgress?: ProviderResultRowEgressPolicy);
     setRoute(route: AgentRunRoute | undefined): void;
     mayStartToolCall(): boolean;
     observe(event: ProviderDispatchEvent, context: {
@@ -447,9 +660,91 @@ export declare class RunScopedProviderDispatchEvidence implements ProviderDispat
             columnCount: number;
         };
         cumulativeResultRowCount?: number;
+        retryOfAttemptIndex?: number;
+        /** Server-owned subtype for root Research or the Ask planner. */
+        planningKind?: 'initial' | 'targeted_revision' | 'research_hypothesis';
     }): Record<string, unknown>;
     snapshot(fallbackReason?: string): ProviderDispatchTerminalEvidence;
 }
+/**
+ * Attach one physical provider transport to the current redacted Ask trace.
+ * The caller remains the authority for admission and egress; this wrapper only
+ * records the same physical send/settlement with its server-owned phase and
+ * purpose.  It is intentionally reusable for meaning and Research narration
+ * so trace provider-attempt counts cannot drift from egress receipts.
+ */
+/**
+ * @internal Exported solely for the local runtime boundary harness.  It is not
+ * an HTTP or durable API: production callers use it to pair the one provider
+ * transport with its same-run trace span and egress receipt.
+ */
+export declare function createProviderDispatchTrace(input: {
+    observer?: AskTraceObserverV1;
+    phase: ProviderDispatchPhaseV1;
+    purpose: ProviderEgressPurpose;
+    admit: (event: ProviderDispatchEvent) => Record<string, unknown>;
+}): {
+    options: {
+        onProviderDispatch: (event: ProviderDispatchEvent) => Record<string, unknown>;
+        onProviderDispatchComplete: (event: ProviderDispatchCompletionEvent) => void;
+        onProviderDispatchRejected: (event: ProviderDispatchRejectionEvent) => void;
+    };
+    settle: (outcome: 'ok' | 'error' | 'cancelled', error?: unknown) => void;
+};
+/**
+ * Router interpretation happens before the answer runner's AsyncLocal trace
+ * scope exists. Its request already carries the server-owned observer, so
+ * adapt the physical category-classification or candidate-ID meaning call to
+ * the shared physical-send trace wrapper without changing router authority.
+ */
+/**
+ * @internal Host-owned physical dispatch bridge for Ask interpretation and
+ * planning. Exported only for the local egress integration harness; the
+ * runtime never receives a ledger or trace authority from client ingress.
+ */
+export declare function createRouterInterpretationProviderTrace(input: {
+    request: AgentRunRequest;
+    routerPhase: 'classification' | 'meaning_resolution' | 'planning';
+    /** The only planning revision admission is minted by AskAnalystRuntime. */
+    planningKind?: 'initial' | 'targeted_revision';
+    /** Test/host injection only; production resolves the request-local ledger. */
+    ledger?: ProviderDispatchEvidenceSink;
+}): ReturnType<typeof createProviderDispatchTrace>;
+/**
+ * The hypothesis planner is a real Research provider dispatch, not a local
+ * planning convenience.  Keep its one bounded call on the same server-owned
+ * ledger and trace as meaning, generation, and narration so it cannot evade
+ * the Research-12 cap or disappear from the run receipt.
+ *
+ * `planResearchHypotheses` deliberately accepts a small `generate`-only
+ * provider interface.  This adapter preserves that seam while keeping the
+ * physical transport authority at the local-runtime boundary.
+ *
+ * @internal Exported for the local runtime planner/egress regression only.
+ */
+export declare function createResearchHypothesisPlanningProvider(input: {
+    provider: AgentProvider;
+    request: AgentRunRequest;
+    ledger?: ProviderDispatchEvidenceSink;
+}): AgentProvider;
+/** @internal Exported for the Research-root terminal aggregation regression. */
+export declare function mergeRunScopedProviderDispatchEvidence(run: AgentRun, evidence: ProviderDispatchTerminalEvidence): AgentRun;
+/**
+ * Aggregate only durable Research-child evidence into the root telemetry.
+ *
+ * A child may have a provider/tool counter even when its query ultimately
+ * fails, so those counters are retained for every uniquely persisted child.
+ * SQL executions use the server-owned child runtime counter as their physical
+ * authority. A failed warehouse dispatch has no result fingerprint, but it is
+ * still a real SQL attempt and must remain visible at the Research root. A
+ * canonical result fingerprint/execution receipt is only the fallback for
+ * older child records that predate the counter, and remains the separate
+ * authority for observed facts. The child run ID, rather than the result
+ * fingerprint, is the de-duplication key because two independently executed
+ * hypotheses can legitimately return the same result.
+ */
+/** @internal Exported for the focused child-counter aggregation regression. */
+export declare function researchChildTelemetryForRoot(researchRuns: readonly NotebookResearchRun[]): AgentRunTelemetryV1;
 /**
  * Final physical generated-SQL boundary.
  *
@@ -467,7 +762,34 @@ export declare function executePreparedAgenticSqlBoundary<T>(input: {
     bindings: unknown;
     scope?: SqlAuthorizationCheck;
     execute: () => Promise<T>;
+    /** Internal harness injection; production obtains the request-local observer. */
+    traceObserver?: AskTraceObserverV1;
 }): Promise<T>;
+/**
+ * Physical relationship evidence is captured by the immutable retrieval
+ * snapshot, then selected by opaque path handle.  Keep the ID derivation and
+ * compiled-SQL verification outside the server closure so the same exact
+ * predicate can be tested without opening a connection.
+ */
+export interface AskV2PhysicalRelationshipPath {
+    leftRelation: string;
+    leftColumn: string;
+    rightRelation: string;
+    rightColumn: string;
+}
+export declare function askV2RelationshipPathHandleId(path: AskV2PhysicalRelationshipPath): string;
+/**
+ * Reject a compiled governed-relational query unless every physical join is
+ * exactly one of the immutable paths selected by the V2 tool.  The caller has
+ * already validated all referenced relations and columns against its scoped
+ * context pack; this function owns the non-interchangeable join-edge proof.
+ */
+export declare function assertAskV2BoundRelationshipPathsForSql(input: {
+    sql: string;
+    relationshipPathIds: readonly string[];
+    paths: readonly AskV2PhysicalRelationshipPath[];
+    dialect?: string;
+}): void;
 export declare function startLocalServer(opts: LocalServerOptions): Promise<number>;
 export declare function assertLocalQueryRuntimeReady(executor: QueryExecutor, connection: ConnectionConfig): Promise<void>;
 export declare function formatLocalQueryRuntimeError(connection: ConnectionConfig, error: unknown): string;
@@ -507,10 +829,19 @@ export declare function resolveDefaultLLMProvider(projectRoot: string): Provider
  * answer-loop runner — never the MCP `claudeCodeRunner`, which doesn't emit a governed
  * answer envelope. Everything else uses the Settings-resolved default runner.
  */
-export declare function resolveGovernedAnswerRunner(projectRoot: string): {
+export declare function resolveGovernedAnswerRunner(projectRoot: string, requestedProvider?: string): {
     provider: ProviderId;
     runner: LLMAgentRunner;
 } | null;
+/**
+ * The no-runner outcome is still an authoritative provider preflight result.
+ * Preserve an explicit invalid selection as `MODEL_NOT_FOUND` instead of
+ * collapsing it into the historical generic authentication error.
+ */
+export declare function governedProviderPreflightError(requestedProvider?: string): Error & {
+    code: 'MODEL_NOT_FOUND' | 'AUTHENTICATION_FAILED';
+    providerPhase: 'preflight';
+};
 export declare function serializeJSON(value: unknown): string;
 /**
  * Extract the single time value returned by an authorized semantic freshness
@@ -769,6 +1100,50 @@ export declare function generateSemanticCompostingDrafts(projectRoot: string, ca
     limit?: number;
     owner?: string;
 }): GenerateSemanticCompostingDraftsResult;
+/**
+ * Captures the semantic compiler authority for one immutable Ask V2
+ * retrieval snapshot.  The map is keyed exclusively by the canonical
+ * qualified evidence ID advertised to the provider.  Legacy `id` values are
+ * intentionally never aliases: one card's legacy ID may equal another
+ * card's qualified ID, which would otherwise let a provider select A and
+ * compile B's runtime field.
+ *
+ * A repeated canonical ID is treated as an ambiguous snapshot defect unless
+ * the cards prove the exact same owner + semantic identity. Exact duplicate
+ * cards de-duplicate to one capability; distinct owners/runtime definitions
+ * are removed rather than resolved by insertion order. The tool adapter
+ * retains a typed collision marker and requires a fresh snapshot before a
+ * truly ambiguous capability can execute.
+ */
+export declare function captureAskV2SemanticCapabilities(input: {
+    candidates: readonly AgentEvidenceCandidate[];
+    snapshotId?: string;
+    isCurrent: () => boolean;
+    /**
+     * Server-selected runtime from the project settings/readiness probe. The
+     * capability may expose it only when this exact candidate is ready for it.
+     */
+    semanticRuntime?: AskSemanticRuntimeSelectionV1;
+    /** Exact target-bound engines captured during retrieval readiness. */
+    semanticCandidateReadiness?: ReadonlyArray<{
+        candidateId: string;
+        status: 'ready' | 'unavailable' | 'unknown';
+        engines?: ReadonlyArray<AskSemanticEngineV1>;
+        nativeCompilerProven?: boolean;
+    }>;
+}): {
+    capabilities: Map<string, AskSemanticCapabilityHandleV1>;
+    collisionIds: string[];
+};
+/**
+ * Opaque browser-cache identity for local Ask conversations.  A browser origin
+ * is not a project boundary: a user can stop one `dql notebook` process and
+ * start a different project on the same port.  The client therefore receives
+ * only this one-way, server-owned value and never a local path. It is not a
+ * secret: it is intentionally linkable only within the local browser/runtime
+ * across restarts so stale cache can be rejected; never log or export it.
+ */
+export declare function askConversationProjectIdentity(projectRoot: string): string;
 /**
  * Materialize drafts for an APPROVED scope (selected slugs / domains). Reuses
  * the propose engine's `onlySlugs` path + the draft writer. Plumbing is never
@@ -1336,6 +1711,20 @@ export declare function parseBlockSourceMetadata(source: string): {
  */
 export declare function markBlockStudioSourceReusable(source: string): string;
 export declare function setBlockStudioStatus(projectRoot: string, blockPath: string, newStatus: string): void;
+/**
+ * Run the real provider/model readiness check at the planner boundary.  This
+ * has no provider-generation ledger admission and no connector effect: it
+ * exists solely to retain redacted preflight cause and trace truth before a
+ * natural-language Ask depends on a planner call.
+ *
+ * Exported for the local host integration harness only. It is not an API and
+ * receives its provider exclusively from server-owned configuration/tests.
+ */
+export declare function preflightAskAnalyticalPlannerProvider(input: {
+    projectRoot: string;
+    request: AgentRunRequest;
+    provider: AgentProvider | null;
+}): Promise<AgentProvider>;
 export declare function buildConversationContextRecap(context: Record<string, unknown> | undefined): string | undefined;
 /**
  * Explain the latest successful answer from its persisted artifact contract.
@@ -1395,6 +1784,19 @@ export declare function createSemanticBuilderBlock(projectRoot: string, options:
     content: string;
     companionPath: string;
 };
+/**
+ * Immutable structural evidence captured once for an explicit Research root.
+ * `lineageSourceSignature` includes `dql-manifest.json`, so a manifest edit
+ * between root planning and a child check is observable before any graph walk.
+ */
+export interface ResearchLineageRootSnapshotV1 {
+    graph?: InstanceType<typeof LineageGraph>;
+    graphFingerprint: string;
+    stableAtCapture: boolean;
+}
+export declare function captureResearchLineageRootSnapshotV1(projectRoot: string, semanticLayer: SemanticLayer | null | undefined): ResearchLineageRootSnapshotV1;
+/** True only while the root-captured graph still matches all lineage inputs. */
+export declare function researchLineageRootSnapshotIsCurrentV1(snapshot: ResearchLineageRootSnapshotV1, projectRoot: string): boolean;
 export declare function discoverDbtProfileConnections(projectRoot: string, projectConfig: ProjectConfig, explicitPath?: string): DbtProfileConnectionCandidate[];
 export declare function buildDbtParseArgs(dbtProjectDir: string, profilesDir?: string): string[];
 /** CFG-003: use a complete default dbt target when no saved DQL connection exists. */
@@ -1562,6 +1964,115 @@ export declare function ensureLocalRuntimeGitignore(projectRoot: string): void;
  * provider is still respected.
  */
 export declare function predictDispatchMs(observed: readonly number[], assumedMs?: number): number;
+/**
+ * A Research root owns a fixed 120-second deadline.  Reserve the last slice
+ * for durable branch receipts, deterministic synthesis, and run persistence;
+ * otherwise the first slow child can consume the entire investigation and
+ * leave the user with neither an answer nor an explanation of the failure.
+ *
+ * This is deliberately a local runtime scheduling policy, not a second
+ * product deadline.  The root AgentRunBudget remains the one hard authority.
+ */
+export declare const RESEARCH_BRANCH_FINALIZATION_RESERVE_MS = 15000;
+export declare const RESEARCH_MIN_BRANCH_EXECUTION_MS = 1000;
+/**
+ * Research branches are independent bounded investigations.  Run a small
+ * deterministic wave so a five-hypothesis plan does not divide the root
+ * budget into five unusably short serial windows.  This is deliberately below
+ * the provider cap and keeps cancellation/finalization responsive.
+ */
+export declare const RESEARCH_MAX_CONCURRENT_BRANCHES = 3;
+export type ResearchBranchStopReasonV1 = 'completed' | 'research_branch_timeout' | 'budget_exhausted' | 'run_deadline'
+/** The user explicitly stopped the root Research run. */
+ | 'cancelled'
+/** The admitted branch failed before an execution receipt was produced. */
+ | 'execution_failed';
+/** Content-safe execution receipt for one bounded Research child. */
+export interface ResearchBranchReceiptV1 {
+    version: 1;
+    branchId: string;
+    childRunId: string;
+    index: number;
+    state: 'completed' | 'failed' | 'timed_out' | 'skipped';
+    verdict: 'inconclusive' | 'failed' | 'skipped';
+    stopReason: ResearchBranchStopReasonV1;
+    /** Present for an admitted child; skipped children never start provider/SQL work. */
+    branchBudgetMs?: number;
+    /**
+     * Legacy receipts are analytical-result branches. A lineage receipt is an
+     * additive structural program with no provider, SQL, warehouse, or repair
+     * execution; readers that do not know this field retain the V1 behaviour.
+     */
+    evidenceKind?: 'analytical_result' | 'lineage_graph';
+    /** Present only for a content-safe `check_lineage` structural receipt. */
+    lineageStatus?: ResearchLineageEvidenceReceiptV1['status'];
+}
+/**
+ * Fair-share one child deadline from the remaining root time.  The formula is
+ * intentionally deterministic so a trace can explain why a branch stopped:
+ * after finalization is reserved, divide the usable window by the number of
+ * remaining bounded waves.  Every branch in the current wave receives the
+ * same window. A too-small share is a skipped branch, not a late
+ * provider/warehouse admission.
+ */
+export declare function allocateResearchBranchBudget(input: {
+    remainingMs: number;
+    remainingBranches: number;
+    finalizationReserveMs?: number;
+    minExecutionMs?: number;
+    maxConcurrentBranches?: number;
+}): {
+    version: 1;
+    remainingMs: number;
+    finalizationReserveMs: number;
+    maxConcurrentBranches: number;
+    remainingWaves: number;
+    branchBudgetMs?: number;
+    stopReason?: 'budget_exhausted';
+};
+type ResearchBranchActionProjectionInput = {
+    action: {
+        kind: 'lookup_metric' | 'lookup_block' | 'breakdown' | 'compare_time' | 'check_lineage' | 'compose_app';
+        target: string;
+    };
+    /**
+     * The root's host-owned tuple. It may exist before a root route is
+     * executable, which is intentional: Research children still start from the
+     * reader's requirement rather than a planner sentence or root SQL.
+     */
+    rootRequirementSeed: AnalyticalRequirementSeedV1;
+    /** Optional frozen root facts used only to preserve already-resolved terms. */
+    rootPlan?: Pick<ResolvedAnalyticalPlan, 'query' | 'analyticalFrame'>;
+};
+export interface ResearchBranchRequirementProjectionV1 {
+    version: 1;
+    action: ResearchBranchActionProjectionInput['action']['kind'];
+    question: string;
+    /**
+     * A host-owned seed only. It deliberately contains no planner supplied
+     * candidate ID: the child router must retrieve and bind candidates from its
+     * own immutable snapshot before it can freeze a plan.
+     */
+    requirementSeed?: AnalyticalRequirementSeedV1;
+}
+/**
+ * Convert one typed Research action into an ordinary Ask requirement seed.
+ *
+ * The older branch runner reduced every action to the final token of its
+ * target. That meant `compare_time` and `breakdown` silently discarded the
+ * root metric (and, for time, its required role/grain), so distinct research
+ * branches could all execute the same baseline. This projection is host-only:
+ * it preserves the root tuple and adds the action's one requested operation,
+ * but never turns a planner label into a trusted candidate or SQL authority.
+ */
+export declare function buildResearchBranchRequirementProjection(input: ResearchBranchActionProjectionInput): ResearchBranchRequirementProjectionV1;
+/**
+ * Race a child against its own signal while consuming an eventual late
+ * rejection. `runNotebookResearch` also receives that signal and checks it at
+ * persistence boundaries, so a slow provider/query cannot overwrite the
+ * already-recorded timeout receipt after this promise rejects.
+ */
+export declare function awaitResearchBranchDeadline<T>(work: Promise<T>, signal: AbortSignal): Promise<T>;
 export declare function boundedAgentMeaningSignal(signal?: AbortSignal, timeoutMs?: number): AbortSignal;
 /**
  * Whether the project's stored live-schema snapshot is missing or older than the
@@ -1656,14 +2167,75 @@ export interface AgentRuntimeValueGroundingPolicy {
     mode: 'disabled' | 'safe_automatic';
     searchSafeColumns: ReadonlySet<string>;
 }
+/**
+ * Trace-only provenance for the two host-added catalog cards below. This is
+ * not a planner hint or an execution capability: it explains why an exact
+ * physical field was retained when ordinary fused ranking did not select it.
+ */
+export declare const AGENT_RUNTIME_VALUE_GROUNDING_PIN_REASON = "host configured runtime value grounding pin";
 /**
  * Resolve the project-admin boundary for live value lookup. An absent/malformed
  * policy is deliberately disabled; a broad table or wildcard cannot make an
  * unknown column search-safe.
  */
 export declare function resolveAgentRuntimeValueGrounding(config: ProjectConfig): AgentRuntimeValueGroundingPolicy;
+/**
+ * Preserve one explicitly configured physical categorical field in the Ask
+ * evidence snapshot before the runtime applies its 32/16 role-balanced caps.
+ *
+ * A cold runtime-value index is not evidence that a literal is absent. The
+ * host may therefore retain exactly one catalog column that an operator named
+ * in `runtimeValueGrounding`, together with exactly one owning dbt relation.
+ * It does not retain a semantic dimension as a value authority, infer a field
+ * from the question, or broaden a configuration with multiple candidate
+ * fields. The later exact value probe and relationship/compiler gates remain
+ * the only ways this card can become a filter or executable plan.
+ */
+export declare function pinConfiguredRuntimeValueGroundingEvidence(input: {
+    evidence: AgentRetrievalEvidence;
+    question: string;
+    policy: AgentRuntimeValueGroundingPolicy;
+    catalogObjects: readonly MetadataObject[];
+    /**
+     * Ephemeral host token issued by the local server registry after this exact
+     * catalog field was verified. It is opaque: relation/column authority stays
+     * in the registry and the Ask runtime strips this token before projection.
+     */
+    literalProbeToken?: string;
+}): AgentRetrievalEvidence;
 export declare function isAgentValueProbeColumn(column: AgentSchemaTable['columns'][number]): boolean;
 export declare function buildAgentValueProbeSql(table: AgentSchemaTable, column: string, searchTerms: string[], connection: ConnectionConfig): string;
+/**
+ * One host-owned literal check used only after the immutable Ask snapshot has
+ * already selected a qualified physical column. Unlike the advisory value
+ * search above, this returns no values: the caller learns only whether the
+ * current literal exists exactly once on this approved field.
+ */
+/**
+ * Case-insensitive existence probe that also returns the canonical stored
+ * spelling, so a host-bound equality filter matches the warehouse casing
+ * ("ronnie knight" typed, "Ronnie Knight" stored). LIMIT 2 detects two
+ * distinct stored spellings — that is ambiguity, not proof.
+ */
+export declare function buildAgentCanonicalValueProbeSql(relation: string, column: string, literal: string, connection: ConnectionConfig): string;
+export declare function buildAgentExactValueProbeSql(table: AgentSchemaTable, column: string, literal: string, connection: ConnectionConfig): string;
+/**
+ * Resolve a planner-admitted raw field back to exactly one physical relation.
+ * This deliberately accepts only explicit runtime/dbt relation references;
+ * a semantic model name or a bare table leaf is not a warehouse target.
+ */
+export declare function agentLiteralProbeTarget(candidate: AgentEvidenceCandidate): {
+    table: AgentSchemaTable;
+    column: AgentSchemaTable['columns'][number];
+} | undefined;
+/**
+ * Mark only a declared, same-snapshot exploratory path that the canonical
+ * analytical policy has accepted. The marker is deliberately host-local: no
+ * indexed card, provider proposal, client request, or persisted result can
+ * raise a draft edge to this state. The router still keeps it
+ * review-required because `automaticJoinAllowed` remains false.
+ */
+export declare function attestExploratoryRelationshipEvidence(evidence: AgentRetrievalEvidence, manifest: DQLManifest | undefined): AgentRetrievalEvidence;
 export declare function extractAgentValueSearchTerms(question: string): string[];
 export {};
 //# sourceMappingURL=local-runtime.d.ts.map