@duckcodeailabs/dql-cli 1.14.3-rc.1 → 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 { 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 AgentProvider, 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 AnalyticalRequirementSeedV1, type ResolvedAnalyticalPlan, type IntentDecision, type ProviderDispatchEvent, type ProviderDispatchCompletionEvent, type ProviderDispatchRejectionEvent, 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';
@@ -140,6 +141,24 @@ 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
@@ -147,6 +166,31 @@ export interface LocalServerOptions {
      */
     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 {
@@ -177,6 +221,45 @@ 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;
@@ -364,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.
  *
@@ -402,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.
@@ -446,9 +582,22 @@ export interface AgentRunProviderDispatchBudget {
     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.
@@ -470,6 +619,11 @@ export declare class RunScopedProviderDispatchEvidence implements ProviderDispat
     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;
@@ -507,6 +661,8 @@ export declare class RunScopedProviderDispatchEvidence implements ProviderDispat
         };
         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;
 }
@@ -535,6 +691,25 @@ export declare function createProviderDispatchTrace(input: {
     };
     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
@@ -552,6 +727,24 @@ export declare function createResearchHypothesisPlanningProvider(input: {
     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.
  *
@@ -572,6 +765,31 @@ export declare function executePreparedAgenticSqlBoundary<T>(input: {
     /** 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;
@@ -882,6 +1100,41 @@ 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
@@ -1458,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.
@@ -1517,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. */
@@ -1718,6 +1998,14 @@ export interface ResearchBranchReceiptV1 {
     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
@@ -1879,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