@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/ask-runtime/ask-agent-runtime-v2.d.ts

@@ -0,0 +1,850 @@
+/**
+ * Ask Agent Runtime V2
+ *
+ * V1 made a deterministic interpretation/coverage check the authority for a
+ * natural-language Ask.  That is safe, but it is the wrong authority for an
+ * open-ended business question: an incomplete certified or semantic candidate
+ * is an observation for the agent, not proof that a safe generated route does
+ * not exist.  V2 keeps the existing execution guards and moves only business
+ * interpretation and route progression behind one bounded tool kernel.
+ *
+ * This module is intentionally host-neutral.  The CLI adapts its existing
+ * answer-loop, MetricFlow and analyst-loop tools to this contract; no provider
+ * payload, SQL, result row, credential, file path, or hidden reasoning is
+ * persisted here.
+ */
+import type { AgentRouter, AgentRunRequest } from '../agent-run-engine.js';
+import type { EvidenceCandidateRoleV1 } from '../analytical-orchestration.js';
+import type { ResearchEvidenceLedgerV3 } from '../analytical-orchestration.js';
+import type { AgentEvidenceCandidate, AgentRetrievalEvidence } from '../meaning-resolution.js';
+/** Explicit operator rollout control.  Browser/MCP request bodies never set it. */
+export type AskRuntimeModeV2 = 'legacy_v1' | 'shadow_v2' | 'authoritative_v2';
+/** V2 has one turn owner; classification is an LLM/tool-runtime responsibility. */
+export type AskTurnClassV2 = 'analytics' | 'definition' | 'business_context' | 'prior_result' | 'general' | 'clarification_response' | 'research';
+export type AskToolNameV2 = 'inspect_ask_context' | 'inspect_conversation_result' | 'inspect_business_context' | 'inspect_certified_candidates' | 'run_certified' | 'inspect_semantic_candidates' | 'compile_and_run_semantic' | 'inspect_relational_context' | 'compile_and_run_dql' | 'validate_and_run_sql' | 'search_values' | 'request_clarification' | 'finish_answer';
+export declare const ASK_V2_CANONICAL_TOOLS: readonly AskToolNameV2[];
+/** Opaque proof that a candidate belongs to this immutable retrieval snapshot. */
+export interface AskEvidenceHandleV1 {
+    version: 1;
+    id: string;
+    role: EvidenceCandidateRoleV1;
+    source: 'certified' | 'semantic' | 'governed_relational' | 'dbt_manifest' | 'runtime_schema' | 'vector' | 'conversation' | 'business';
+    snapshotId?: string;
+}
+/**
+ * A relationship path is atomic evidence.  A planner may select a handle, but
+ * it must never splice together edges from separate paths or mint a new join
+ * from their display names.  The host keeps the physical edge payload in its
+ * request-scoped workspace; this persisted projection deliberately contains
+ * identities only.
+ */
+export interface AskRelationshipPathHandleV1 {
+    version: 1;
+    id: string;
+    edgeIds: string[];
+    /**
+     * Snapshot-qualified relation/column cards covered by this exact path. The
+     * model may choose the path handle, but it cannot splice a new join from
+     * labels or cards that were not admitted with the path.
+     */
+    candidateIds?: string[];
+    snapshotId?: string;
+}
+/**
+ * A certified artifact is captured while the retrieval lease is current.  The
+ * executable payload stays server-only, but its revision proof is part of the
+ * request-scoped capability and is checked again immediately before freeze.
+ * It deliberately has no JSON representation.
+ */
+export interface AskCertifiedArtifactHandleV1 {
+    version: 1;
+    artifact: unknown;
+    revisionFingerprint: string;
+    /** Host-owned recheck against the same local project/snapshot. */
+    isCurrent(): boolean;
+}
+/**
+ * Canonical semantic compiler identifiers which an Ask V2 host may advertise
+ * for one immutable semantic capability.  These are deliberately adapter
+ * identifiers, not candidate IDs, display labels, MetricFlow field names, or
+ * provider-authored aliases.
+ */
+export type AskSemanticEngineV1 = 'native' | 'metricflow-cli' | 'dbt-cloud';
+/**
+ * Redacted, host-owned semantic runtime selection for one immutable Ask
+ * workspace.  The controller never chooses this value: it is resolved from
+ * the project's configured preference and target-bound adapter readiness
+ * before a semantic capability is offered as executable.
+ *
+ * `selectedEngine` is optional for backwards-readable receipts/workspaces
+ * created before this additive contract.  New hosts set it only when the
+ * selected project runtime is actually available for the candidate.
+ */
+export interface AskSemanticRuntimeSelectionV1 {
+    version: 1;
+    preference: 'auto' | AskSemanticEngineV1;
+    selectedEngine?: AskSemanticEngineV1;
+    readiness: 'ready' | 'unavailable';
+}
+/**
+ * Host-captured semantic capability. The provider sees the opaque candidate
+ * ID and safe card only; immediately before compilation the runtime resolves
+ * that ID through this immutable mapping to the adapter's authored name.
+ */
+export interface AskSemanticCapabilityHandleV1 {
+    version: 1;
+    candidateId: string;
+    runtimeName: string;
+    /**
+     * Host-observed ready engines for this exact captured capability. This is
+     * retained for diagnostics/backwards readers; it is never model-facing
+     * routing input.
+     */
+    engines: readonly AskSemanticEngineV1[];
+    /**
+     * The one project-selected, target-bound engine for this capability. The
+     * V2 compiler uses this server-owned value exclusively. A missing value
+     * means semantic execution is unavailable before freeze.
+     */
+    selectedEngine?: AskSemanticEngineV1;
+    roles: Array<'metric' | 'dimension' | 'time_dimension' | 'filter_dimension'>;
+    /**
+     * Stable fingerprint of the complete compiler-authority projection of the
+     * retained candidate. The host and provider both recompute this before an
+     * opaque ID is resolved, so two cards with the same ID cannot silently bind
+     * different MetricFlow/dbt time, dimension, or model contracts.
+     */
+    fingerprint: string;
+    isCurrent(): boolean;
+}
+/**
+ * Server-only execution handle for a Research child whose analytical tuple was
+ * already frozen by the root snapshot.  It deliberately carries neither SQL
+ * nor a provider prompt: the host callback executes the exact pre-authorized
+ * certified/semantic capability and returns its own V2 state/receipt.  A
+ * provider may select only a handle the workspace advertised; it cannot mint
+ * one, alter its bindings, or cause a second planning dispatch.
+ */
+export interface AskFrozenResearchChildHandleV1 {
+    version: 1;
+    id: string;
+    snapshotId: string;
+    sourceFingerprint: string;
+    tier: Extract<AskExecutionTierV2, 'certified' | 'semantic'>;
+    candidateIds: string[];
+    /**
+     * The host-frozen execution binding. This is intentionally an opaque,
+     * content-free receipt rather than a provider-authored plan: parameters,
+     * trust, and the artifact/capability fingerprint were fixed before the root
+     * Research planner saw this child ID.
+     */
+    binding: {
+        version: 1;
+        parameters: Record<string, string | number | boolean | null>;
+        trustState: 'certified' | 'governed';
+        planFingerprint: string;
+        /** Present for a certified artifact frozen from its captured source. */
+        artifactRevisionFingerprint?: string;
+        /** Present for one or more immutable semantic compiler capabilities. */
+        capabilityFingerprints?: string[];
+    };
+    /** Re-check captured artifact/capability freshness immediately before use. */
+    isCurrent(): boolean;
+    /** The active root is supplied by the V2 handler, never captured from a pre-router request. */
+    execute(root: AskAgentStateV4): Promise<{
+        state: AskAgentStateV4;
+        /** AgentAnswer stays in the CLI adapter; this host bridge remains neutral. */
+        answer: unknown;
+    }>;
+}
+/**
+ * The host, not a provider inspection flag, owns whether a tier can already
+ * satisfy the full requested tuple.  `available` is useful retrieval context;
+ * only `complete` blocks a lower-tier execution before a plan is frozen.
+ */
+export interface AskTierStateV1 {
+    version: 1;
+    status: 'complete' | 'available' | 'unavailable' | 'ineligible' | 'ambiguous';
+    candidateIds: string[];
+    /** Atomic path handles selected for a governed relational execution. */
+    relationshipPathIds?: string[];
+    reasonCode: string;
+    safeNextTools?: AskToolNameV2[];
+    /**
+     * Host-issued, stable choices for a material ambiguity. A provider may only
+     * reference these opaque IDs; it cannot manufacture alternatives or labels.
+     * Distinct result fingerprints prove that choosing an option changes the
+     * answer rather than merely restating the same business meaning.
+     */
+    clarificationChoices?: AskClarificationChoiceV1[];
+}
+export interface AskClarificationChoiceV1 {
+    version: 1;
+    id: string;
+    label: string;
+    candidateIds: string[];
+    resultFingerprint: string;
+}
+/**
+ * Ephemeral host bridge between retrieval and the provider/tool adapter.
+ *
+ * This is intentionally a function-bearing, server-only value: JSON ingress
+ * cannot hydrate it, it is never persisted, and the raw context pack remains
+ * inside the local runtime.  Its stable handle fields allow the adapter to
+ * reject a stale pack before it exposes any metadata to a provider.
+ */
+export interface AskAgentRuntimeWorkspaceBridgeV2 {
+    version: 2;
+    snapshotId?: string;
+    sourceFingerprint?: string;
+    /**
+     * Host-owned execution readiness for the captured certified artifacts.
+     *
+     * Presence in a context pack is never execution authority. The local host
+     * supplies this only when it can invoke its snapshot-bound certified
+     * executor for this request; omitted bridges fail closed for the engine's
+     * zero-provider shortcut. The provider adapter additionally verifies its
+     * own execution callback before exposing Tier 1 as complete.
+     */
+    isCertifiedExecutionAvailable?(): boolean;
+    /** Optional so a persisted V4 receipt written before this additive field remains readable. */
+    relationshipPathHandles?: AskRelationshipPathHandleV1[];
+    getContextPack(): unknown;
+    /**
+     * Server-only snapshot workspace for the V2 tool adapter.  Unlike the
+     * context-pack accessor this is an explicit, bounded projection: it carries
+     * the exact admitted cards and any immutable executable artifacts captured
+     * during retrieval.  A tool adapter must never replace it with a KG search.
+     */
+    getToolWorkspace?(): AskAgentToolWorkspaceV2 | undefined;
+}
+/**
+ * Ephemeral, immutable-at-request workspace consumed by canonical V2 tools.
+ * The host may retain executable artifacts and physical path facts here, but
+ * this value is neither JSON ingress nor a persisted receipt.  Provider-facing
+ * code must project only safe cards from it.
+ */
+export interface AskAgentToolWorkspaceV2 {
+    version: 1;
+    snapshotId?: string;
+    sourceFingerprint?: string;
+    /** Up to 128 retained candidates from the one retrieval snapshot. */
+    candidates: AgentEvidenceCandidate[];
+    /** Atomic relationship paths; raw edges are host-only and never re-searched. */
+    relationshipPathHandles: AskRelationshipPathHandleV1[];
+    /**
+     * Snapshot-captured certified block nodes keyed by candidate identity. The
+     * value is deliberately unknown here so the runtime stays host-neutral.
+     */
+    certifiedArtifacts?: ReadonlyMap<string, AskCertifiedArtifactHandleV1 | unknown>;
+    /** Host-only opaque-ID -> compiler-name capability mapping. */
+    semanticCapabilities?: ReadonlyMap<string, AskSemanticCapabilityHandleV1>;
+    /** Server-selected semantic runtime; safe to receipt, never provider-selected. */
+    semanticRuntime?: AskSemanticRuntimeSelectionV1;
+    /**
+     * Snapshot-declared fiscal binding. It stays server-only so a controller
+     * cannot invent a calendar, date role, or fiscal-period field from prose.
+     * New workspaces include all three identities when a fiscal question is
+     * eligible for semantic execution; old persisted workspaces simply remain
+     * unable to satisfy a fiscal invocation.
+     */
+    fiscalCalendar?: {
+        id: string;
+        fiscalPeriodFieldId: string;
+        dateRoleId?: string;
+    };
+    /**
+     * Canonical semantic candidate IDs that collided while the host captured
+     * this retrieval snapshot. A collision is not recoverable by choosing the
+     * last card or falling back to a legacy ID: the affected capability is
+     * deliberately withheld until a fresh, unambiguous snapshot is available.
+     * This remains server-only alongside `semanticCapabilities`.
+     */
+    semanticCapabilityCollisionIds?: readonly string[];
+    /**
+     * Candidate identities whose own certified-output contract proved the full
+     * requested tuple during this immutable retrieval pass.  This is separate
+     * from artifact presence: an admitted block can be useful context without
+     * being allowed to freeze the certified tier for this question.
+     */
+    certifiedCompleteCandidateIds?: readonly string[];
+    /**
+     * Subset of `certifiedCompleteCandidateIds` for which the retrieval snapshot
+     * proved a direct certified-question contract: one exact authored example,
+     * block title, or approved alias. This remains distinct from tuple
+     * completeness and is retained for diagnostics/legacy consumers. An
+     * authoritative V2 implicit ranking may alternatively use one uniquely
+     * complete snapshot fit, but only with an independently proven immutable
+     * primary sort and row-bound execution contract.
+     */
+    exactCertifiedQuestionCandidateIds?: readonly string[];
+    /**
+     * Server-owned execution capability for a certified block that has no
+     * authored outer SQL LIMIT. When true, the host binds the question-derived
+     * overall row limit into the frozen invocation and enforces it at the
+     * read-only SQL boundary before result normalisation. This is intentionally
+     * not inferred from provider-visible cards or persisted client state.
+     */
+    certifiedHostEnforcesInvocationRowLimit?: boolean;
+    /**
+     * Host-computed tuple state for the current request.  The provider may
+     * inspect this, but cannot upgrade `available` to `complete` or mint a
+     * state for an unadmitted candidate.
+     */
+    tierStates?: Partial<Record<AskExecutionTierV2, AskTierStateV1>>;
+    /** Safe, bounded business/context projection for the contextual tools. */
+    businessContext?: {
+        available: boolean;
+        objectCount: number;
+        cards?: Array<{
+            id: string;
+            name: string;
+            description?: string;
+            kind?: string;
+        }>;
+    };
+    /**
+     * Explicit-Research-only, root-frozen structural lineage program. It is a
+     * host callback rather than a provider tool: the provider can choose the
+     * lineage branch, but cannot select a graph, widen a snapshot, or turn the
+     * structural walk into SQL/provider work.
+     */
+    runDedicatedLineageProgram?: (input: {
+        snapshotId?: string;
+        targetCandidateIds: string[];
+        relationshipPathIds: string[];
+    }) => {
+        status: 'completed' | 'missing' | 'ambiguous' | 'stale' | 'truncated' | 'unavailable';
+        evidenceHandleIds: string[];
+        validatorEvidenceHandleIds?: string[];
+        counterEvidenceHandleIds?: string[];
+        receiptFingerprint?: string;
+    };
+    /**
+     * Optional root-frozen analytical children for explicit Research.  They are
+     * not a fallback path: each one was separately authorized by the host and
+     * must remain on this exact snapshot.  A missing/mismatched handle is a
+     * typed branch failure, never a reason to rerun retrieval or call a planner.
+     */
+    frozenResearchChildren?: ReadonlyMap<string, AskFrozenResearchChildHandleV1>;
+}
+/** Host-validated continuity; raw browser rows are never an authority. */
+export interface AskConversationContextV2 {
+    version: 2;
+    sourceTurnId?: string;
+    priorPlanId?: string;
+    resultFingerprint?: string;
+    selectedMemberId?: string;
+    selectedMemberBinding?: string;
+    clarificationId?: string;
+    availableResultHandleIds: string[];
+    /**
+     * Members an ambiguous prior-result reference could have meant, when the
+     * host found candidates but could not choose between them. The analyst
+     * offers these in a clarification instead of guessing; they are display
+     * labels the user already saw, never new identity.
+     */
+    ambiguousMemberLabels?: string[];
+}
+/** Agent proposal is identifiers and an intended next tool only, never SQL/trust. */
+export interface AskCandidatePlanV1 {
+    version: 1;
+    turnClass: AskTurnClassV2;
+    candidateIds: string[];
+    intendedTool?: AskToolNameV2;
+    requestedExpansion?: boolean;
+    requirementFingerprint: string;
+}
+export type AskToolObservationOutcomeV1 = 'eligible' | 'executed' | 'ineligible' | 'unavailable' | 'ambiguous' | 'needs_input' | 'denied' | 'error';
+/** Redacted, typed outcome supplied back to the same agent after every tool call. */
+export interface AskToolObservationV1 {
+    version: 1;
+    tool: AskToolNameV2;
+    outcome: AskToolObservationOutcomeV1;
+    tier?: AskExecutionTierV2;
+    reasonCode: string;
+    candidateIds: string[];
+    /** Atomic selected relationship path handles, when this is a DQL execution. */
+    relationshipPathIds?: string[];
+    planId?: string;
+    frozen?: boolean;
+    /**
+     * Set only by the local host after it has minted an execution capability
+     * (or bound an immutable certified artifact).  This is the freeze point:
+     * compiler and warehouse failures which follow cannot reopen routing.
+     */
+    executionAuthorized?: boolean;
+    /** The one permitted post-freeze retry, bound to the existing plan. */
+    samePlanRepair?: boolean;
+    retryable?: boolean;
+    safeAction?: string;
+    /** Wall-clock duration of the physical tool/host boundary, never prompt text. */
+    durationMs?: number;
+    /** Content-free correlations for input/output payloads where the host has one. */
+    inputFingerprint?: string;
+    outputFingerprint?: string;
+    /** The component that produced this observation or final incident. */
+    origin?: 'retrieval' | 'agent_control' | 'tool' | 'validation' | 'freeze' | 'execution' | 'provider' | 'narration';
+    /** Redacted provider classification. Model names, URLs, and responses stay out. */
+    provider?: {
+        phase: 'preflight' | 'classification' | 'meaning_resolution' | 'planning' | 'generation' | 'repair' | 'narration' | 'agent_control' | 'tool_followup' | 'unknown';
+        cause: 'authentication' | 'model_not_found' | 'rate_limited' | 'gateway' | 'network' | 'provider_timeout' | 'run_deadline' | 'admission_denied' | 'dispatch_budget' | 'cancelled' | 'unknown';
+        retryable: boolean;
+        safeAction: string;
+    };
+}
+export type AskExecutionTierV2 = 'certified' | 'semantic' | 'governed_relational' | 'exploratory_sql';
+/** A safe plan becomes immutable only after an execution tool reports executable. */
+export interface ResolvedAnalyticalPlanV3 {
+    version: 3;
+    id: string;
+    snapshotId?: string;
+    tier: AskExecutionTierV2;
+    candidateIds: string[];
+    frozen: boolean;
+    reviewRequired: boolean;
+    /** Immutable selected targets/bindings, deliberately not raw SQL/DQL. */
+    bindingFingerprint?: string;
+    /** Bound relationship paths for governed-relational execution. */
+    relationshipPathIds?: string[];
+    /** Redacted warehouse/connection identity when the host has one. */
+    targetFingerprint?: string;
+    fingerprint: string;
+}
+/** Every tier interaction is durable even when it did not freeze a plan. */
+export interface AskCascadeTierAttemptV2 {
+    version: 2;
+    tier: AskExecutionTierV2;
+    outcome: AskToolObservationOutcomeV1;
+    reasonCode: string;
+    candidateIds: string[];
+    frozen: boolean;
+    durationMs?: number;
+}
+/**
+ * Count-only projection of the immutable retrieval workspace.  It separates a
+ * source that was empty/unavailable from a card that was simply outside the
+ * bounded workspace, so a trace never calls a pruned card "not modeled".
+ */
+export interface AskContextCoverageV2 {
+    version: 2;
+    source: AskEvidenceHandleV1['source'];
+    status: 'available' | 'empty' | 'stale' | 'unavailable' | 'errored' | 'skipped';
+    admittedCandidateCount: number;
+    excludedCandidateCount: number;
+    reasonCodes: string[];
+}
+/** Typed terminal result of the V2 tool runtime, independent of V1 prose. */
+export type AskAgentTerminalOutcomeKindV2 = 'finish_answer' | 'clarification' | 'gap' | 'provider_failure' | 'execution_failure' | 'denied' | 'budget_exhausted';
+export interface AskAgentTerminalOutcomeV2 {
+    version: 2;
+    kind: AskAgentTerminalOutcomeKindV2;
+    reasonCode: string;
+    safeAction?: string;
+    origin: NonNullable<AskToolObservationV1['origin']>;
+}
+/**
+ * Server-minted proof that an authoritative V2 tool run froze and executed
+ * one immutable plan. This is an internal runner-to-host handoff only: it is
+ * never accepted from browser/MCP input and it deliberately contains no SQL,
+ * result rows, credentials, or provider content.
+ */
+export interface AskV2ExecutionReceipt {
+    version: 1;
+    mode: 'authoritative_v2';
+    /**
+     * Opaque ID minted by the engine for this one physical run.  A receipt with
+     * the right-looking plan fields is not sufficient: the engine also checks
+     * its process-local attestation before it can suppress the legacy gate.
+     */
+    capabilityId?: string;
+    /** The engine run to which this receipt is bound. */
+    runId?: string;
+    snapshotId: string;
+    sourceFingerprint?: string;
+    /** Digest of the server-retained candidate universe, never a provider hint. */
+    retainedCandidateFingerprint?: string;
+    planId: string;
+    planFingerprint?: string;
+    tier: AskExecutionTierV2;
+    candidateIds: string[];
+    /** Fingerprint of the exact canonical execution result returned to the engine. */
+    resultFingerprint?: string;
+    frozen: true;
+    executed: true;
+}
+/**
+ * A process-local capability issued by `AgentRunEngine` after immutable
+ * retrieval. It is not parsed from HTTP/MCP input and is intentionally useful
+ * only to the runner that received this request object.  The capability's
+ * opaque attestation is kept in a module-private WeakMap below, so copying
+ * receipt-shaped JSON cannot make a terminal V2 execution authoritative.
+ */
+export interface AskV2ExecutionCapabilityV1 {
+    version: 1;
+    id: string;
+    runId: string;
+    snapshotId: string;
+    sourceFingerprint?: string;
+    retainedCandidateFingerprint: string;
+    exactCertifiedCandidateId?: string;
+}
+/**
+ * Fingerprint only the snapshot-local facts the semantic compiler can consume.
+ * Retrieval rank, descriptions, lane membership, and display prose are
+ * deliberately absent: they do not change a compiler authority. Conversely,
+ * the full analytical capability stays present, including its model-qualified
+ * time dimensions, joins, outputs, and parameter contract. This is used both
+ * when the host captures capabilities and when the provider resolves an
+ * opaque ID, so exact duplicate cards are safe while divergent duplicates are
+ * withheld before compiler execution.
+ */
+export declare function askV2SemanticCandidateAuthorityFingerprint(candidate: AgentEvidenceCandidate): string;
+/**
+ * Return only the semantic object roles that can be bound directly by a
+ * compiler.  A semantic model, saved query, and other context/container card
+ * may be useful retrieval evidence, but it is never an executable field just
+ * because its display/runtime name resembles one.  Keep this classification
+ * deliberately structural: the V2 host captures a capability only from an
+ * exact object type (or the legacy qualified-ID segment where old snapshots
+ * omitted that type), never from a trust tier or a fuzzy name.
+ */
+export declare function askV2ExecutableSemanticRoles(candidate: AgentEvidenceCandidate): AskSemanticCapabilityHandleV1['roles'] | undefined;
+/** Stable digest of the admitted immutable candidate closure. */
+export declare function askV2RetainedCandidateFingerprint(candidateIds: readonly string[]): string;
+/**
+ * Return the canonical execution-result identity without retaining the result
+ * in a receipt. Existing connector fingerprints win; the fallback covers
+ * host-faithful test/local result envelopes that predate that field.
+ */
+export declare function askV2ExecutionResultFingerprint(result: unknown): string | undefined;
+/** Mint one server-owned capability for an authoritative V2 run. */
+export declare function createAskV2ExecutionCapabilityV1(input: {
+    id: string;
+    runId: string;
+    state: AskAgentStateV4;
+}): AskV2ExecutionCapabilityV1 | undefined;
+/**
+ * Mint the only receipt accepted by the engine's V2 terminal boundary. This
+ * is called after a real tool execution advances the cloned provider state.
+ * It rejects pre-freeze, non-executed, stale-snapshot, or mismatched-result
+ * states before an attestation is ever registered.
+ */
+export declare function mintAskV2ExecutionReceiptV1(input: {
+    state: AskAgentStateV4 | undefined;
+    capability: AskV2ExecutionCapabilityV1 | undefined;
+    result: unknown;
+}): AskV2ExecutionReceipt | undefined;
+/**
+ * Verify a live receipt at the engine boundary. A persisted, copied, forged,
+ * stale, legacy, or pre-freeze receipt has no WeakMap attestation and cannot
+ * skip the generic evaluator.
+ */
+export declare function isAskV2ExecutionReceiptAuthorizedV1(input: {
+    receipt: AskV2ExecutionReceipt | undefined;
+    capability: AskV2ExecutionCapabilityV1 | undefined;
+    state: AskAgentStateV4 | undefined;
+    result: unknown;
+    runId: string;
+}): boolean;
+/** The one durable server-side state record for a V2 Ask. */
+export interface AskAgentStateV4 {
+    version: 4;
+    mode: AskRuntimeModeV2;
+    turnClass: AskTurnClassV2;
+    snapshotId?: string;
+    sourceFingerprint?: string;
+    retainedCandidateIds: string[];
+    initialCandidateIds: string[];
+    expansionCandidateIds: string[];
+    /** Additive count-only source state; V4 readers written before V2 omit it. */
+    contextCoverage?: AskContextCoverageV2[];
+    /** Bounded-workspace exclusions are never a source-absence claim. */
+    excludedCandidateCount?: number;
+    exclusionReasonCodes?: string[];
+    relationshipPathHandles: AskRelationshipPathHandleV1[];
+    conversation: AskConversationContextV2;
+    observations: AskToolObservationV1[];
+    /**
+     * Ephemeral host-owned tier truth carried with the live state.  It is
+     * additive/optional so receipts produced before V2 remain readable.  The
+     * durable trace records its outcomes through observations and tier attempts.
+     */
+    tierStates?: Partial<Record<AskExecutionTierV2, AskTierStateV1>>;
+    /** Additive redacted host runtime choice used for semantic V2 execution. */
+    semanticRuntime?: AskSemanticRuntimeSelectionV1;
+    /** Optional so a persisted V4 receipt written before this additive field remains readable. */
+    tierAttempts?: AskCascadeTierAttemptV2[];
+    /**
+     * Live, pre-freeze controller commitment.  An inspection may set this only
+     * after the host has proved that the tier has an executable capability in
+     * the immutable workspace.  It narrows the *next* model turn to that
+     * tier's execution tool; it is not a frozen plan and never bypasses the
+     * earlier-complete-tier guard.
+     */
+    controllerTier?: AskExecutionTierV2;
+    /**
+     * A narrowly-scoped priority exception for an explicit, snapshot-qualified
+     * semantic or DQL artifact reference.  It is host-derived from an admitted
+     * canonical ID; ordinary natural-language relevance never populates it.
+     * Keeping this on the state makes a reload repeat the same Tier 1 decision
+     * instead of trusting a stale lower-tier controller commitment.
+     */
+    explicitQualifiedArtifactReference?: {
+        version: 1;
+        tier: Extract<AskExecutionTierV2, 'semantic' | 'governed_relational'>;
+        candidateId: string;
+    };
+    candidatePlan?: AskCandidatePlanV1;
+    /**
+     * Host-proven Tier 1 shortcut for an ordinary Ask.  This is set only when
+     * the immutable retrieval workspace captured one admitted certified
+     * artifact whose output contract already proves the complete tuple.  It is
+     * deliberately an opaque candidate ID rather than a plan or a provider
+     * instruction: the host still mints the execution capability and rechecks
+     * artifact freshness immediately before execution.
+     *
+     * Exact certified fits are a contractual zero-provider path.  Leaving this
+     * fact implicit forced the authoritative V2 agent loop to ask a model to
+     * rediscover an already-proven block, which could exhaust the dispatch
+     * budget before any Tier 1 execution occurred.
+     */
+    exactCertifiedCandidateId?: string;
+    resolvedPlan?: ResolvedAnalyticalPlanV3;
+    /** Actual V2 Research branch receipts; V3 projections remain readable. */
+    researchLedgerV4?: ResearchEvidenceLedgerV4;
+    terminal?: 'completed' | 'clarification' | 'denied' | 'budget_exhausted' | 'error';
+    terminalOutcome?: AskAgentTerminalOutcomeV2;
+}
+/** Egress default for a remote provider; the local provider may use bounded rows. */
+export interface ProviderResultEgressPolicyV2 {
+    version: 2;
+    transport: 'local' | 'remote';
+    maximumRows: number;
+    maximumColumns: number;
+    maximumCells: number;
+    allowRows: boolean;
+    allowedKinds: Array<'facts' | 'aggregates' | 'schema' | 'fingerprints' | 'bounded_rows'>;
+}
+/** Provider egress is a host policy, not something the LLM may request. */
+export declare function defaultProviderResultEgressPolicyV2(input: {
+    transport: 'local' | 'remote';
+    /** Remote rows require an explicit project setting and retain the same cap. */
+    allowRemoteRows?: boolean;
+}): ProviderResultEgressPolicyV2;
+/** Additive V8 receipt.  Existing V1-V7 readers stay untouched. */
+export interface AgentRunDiagnosticReceiptV8 {
+    version: 8;
+    mode: AskRuntimeModeV2;
+    turnClass: AskTurnClassV2;
+    snapshotId?: string;
+    retainedCandidateCount: number;
+    initialCandidateCount: number;
+    expansionCount: number;
+    /** Objective is the typed turn class, never the user question or prompt. */
+    objective: AskTurnClassV2;
+    /** Count-only context story; no names, definitions, values, or raw rows. */
+    contextCoverage: AskContextCoverageV2[];
+    excludedCandidateCount: number;
+    exclusionReasonCodes: string[];
+    observations: AskToolObservationV1[];
+    tierAttempts: AskCascadeTierAttemptV2[];
+    /**
+     * Server-owned current controller progression for an unfrozen V2 run.
+     * This is deliberately not inferred from the first eligible inspection:
+     * an earlier semantic card may already have become unavailable while the
+     * controller has advanced to governed relational or exploratory SQL.
+     */
+    controllerTier?: AskExecutionTierV2;
+    /** Redacted host-selected semantic runtime/readiness, never model input. */
+    semanticRuntime?: AskSemanticRuntimeSelectionV1;
+    planFrozen: boolean;
+    terminalOutcome?: AskAgentTerminalOutcomeV2;
+    /** Engine-owned final result facts; no result values or narration text. */
+    outcome: {
+        connectionAttempted: boolean;
+        executionAttempts: number;
+        factCount: number;
+        narration: 'fact_bound' | 'deterministic_fallback' | 'not_retained' | 'not_applicable';
+    };
+    /**
+     * Canonical physical/accounted activity for compact trace projections.
+     * Provider dispatches are supplied by the server egress wrapper when it is
+     * available; the kernel never infers a physical send from a planner stage.
+     */
+    activity: {
+        providerDispatches: number;
+        toolCalls: number;
+        executionAttempts: number;
+        repairs: number;
+    };
+    /** Compact timing only; content and raw provider data never enter the receipt. */
+    toolDurationMs: number;
+    finalStopReason: string;
+}
+/** V4 adds branch/tool facts without reinterpreting V1-V3 research receipts. */
+export interface ResearchEvidenceLedgerV4 {
+    version: 4;
+    rootQuestionFingerprint: string;
+    snapshotId?: string;
+    branches: Array<{
+        id: string;
+        verdict: 'supported' | 'contradicted' | 'inconclusive' | 'failed' | 'skipped';
+        evidenceHandleIds: string[];
+        /** Evidence that a deterministic result/receipt validator actually checked. */
+        validatorEvidenceHandleIds?: string[];
+        /** Independent evidence that qualifies a branch; never inferred from rows. */
+        counterEvidenceHandleIds?: string[];
+        /** Opaque child receipt correlation; no SQL, rows, or provider response. */
+        childReceiptFingerprint?: string;
+        lineageProgram?: 'dedicated' | 'not_run';
+    }>;
+    limitedScope: boolean;
+}
+/**
+ * An explicit Research controller supplies these only after it has run a
+ * branch.  A generic tool observation is not a hypothesis and must never be
+ * converted into one merely to make an empty ledger look complete.
+ */
+export interface AskV2ResearchBranchReceiptInput {
+    id: string;
+    verdict: ResearchEvidenceLedgerV4['branches'][number]['verdict'];
+    evidenceHandleIds: string[];
+    validatorEvidenceHandleIds?: string[];
+    counterEvidenceHandleIds?: string[];
+    childReceiptFingerprint?: string;
+    lineageProgram?: 'dedicated' | 'not_run';
+}
+/**
+ * Build a V4 ledger from the V2 tool boundary itself.  In particular lineage
+ * is represented by its own atomic relationship handles; it is never inferred
+ * from (or reused as) an analytical result branch.
+ */
+export declare function recordAskV2ResearchLedger(state: AskAgentStateV4, branchReceipts?: readonly AskV2ResearchBranchReceiptInput[]): ResearchEvidenceLedgerV4 | undefined;
+/**
+ * Project the existing mixed V3 Research ledger into the V2 tool-runtime
+ * reader contract.  This is deliberately a projection, not a second research
+ * planner: it retains opaque receipt/fact identities and the dedicated local
+ * lineage marker while excluding question text, SQL, rows, prompts, and
+ * provider material.
+ */
+export declare function projectResearchEvidenceLedgerV4(ledger: ResearchEvidenceLedgerV3): ResearchEvidenceLedgerV4;
+export declare const ASK_V2_BUDGETS: {
+    readonly ask: {
+        readonly durationMs: 45000;
+        readonly providerDispatches: 6;
+        readonly toolCalls: 8;
+        readonly expansions: 2;
+        readonly executions: 2;
+        readonly repairs: 1;
+        readonly valueSearches: 1;
+        readonly clarifications: 1;
+    };
+    readonly contextual: {
+        readonly durationMs: 15000;
+        readonly providerDispatches: 2;
+        readonly toolCalls: 4;
+    };
+    readonly research: {
+        readonly durationMs: 120000;
+        readonly providerDispatches: 12;
+        readonly toolCalls: 24;
+        readonly branches: 6;
+        readonly repairs: 2;
+    };
+};
+export interface AskToolKernelV2 {
+    readonly state: AskAgentStateV4;
+    observe(observation: AskToolObservationV1): AskToolObservationV1;
+    /**
+     * Server-owned current tool availability for the next model transport.
+     * This constrains repeated discovery after a tier has enough compatible
+     * evidence, but never executes a query on the model's behalf.
+     */
+    toolPolicy(): {
+        allowedToolNames: AskToolNameV2[];
+        instruction?: string;
+        terminalActionToolNames?: AskToolNameV2[];
+    };
+    canCall(tool: AskToolNameV2, input?: {
+        repair?: boolean;
+        expansion?: boolean;
+        /**
+         * Host-only zero-provider shortcut for one uniquely exact, current,
+         * executable Tier 1 artifact. This is never part of a model tool schema:
+         * callers must still bind the state-owned exact candidate below.
+         */
+        directExactCertifiedExecution?: boolean;
+        /** Snapshot-qualified selected IDs for post-freeze same-plan comparison. */
+        candidateIds?: readonly string[];
+        relationshipPathIds?: readonly string[];
+        /** Stable selected-target/binding proof; never raw program or SQL. */
+        bindingFingerprint?: string;
+    }): {
+        ok: boolean;
+        reasonCode?: string;
+        safeNextTools?: AskToolNameV2[];
+    };
+    diagnosticReceipt(finalStopReason?: string, outcome?: AgentRunDiagnosticReceiptV8['outcome'], activity?: Partial<AgentRunDiagnosticReceiptV8['activity']>): AgentRunDiagnosticReceiptV8;
+}
+/**
+ * Tool-kernel safety is deliberately deterministic: it does not decide business
+ * meaning, but it prevents a model from skipping a complete earlier tier,
+ * widening a snapshot, recursively asking itself, or retrying indefinitely.
+ */
+export declare function createAskToolKernelV2(state: AskAgentStateV4): AskToolKernelV2;
+/** Record a live host/tool observation against the shared V2 kernel. */
+export declare function observeAskAgentV2Tool(state: AskAgentStateV4 | undefined, observation: AskToolObservationV1): AskToolObservationV1 | undefined;
+/** Record the host's tuple-completeness verdict without treating cards as SQL authority. */
+export declare function setAskV2TierState(state: AskAgentStateV4 | undefined, tier: AskExecutionTierV2, next: Omit<AskTierStateV1, 'version'>): AskTierStateV1 | undefined;
+/** Seal a V2 terminal without converting it into a legacy business verdict. */
+export declare function finishAskAgentV2Turn(state: AskAgentStateV4 | undefined, outcome: AskAgentTerminalOutcomeV2): void;
+/** A stale bridge must never become a second retrieval or a prompt source. */
+export declare function askAgentV2WorkspaceMatches(state: AskAgentStateV4 | undefined, bridge: AskAgentRuntimeWorkspaceBridgeV2 | undefined): boolean;
+/**
+ * Materialize Tier 1 tuple completeness from the immutable server workspace
+ * before the first V2 tool policy is calculated.  The old fast-path-only
+ * behavior exposed this truth only when there was one certified candidate,
+ * allowing a semantic inspector to commit a lower tier while two complete
+ * certified artifacts were present.  The workspace is the authority here;
+ * provider cards and persisted controller state never create completeness.
+ *
+ * `certifiedExecutionAvailable` is deliberately host-provided rather than
+ * inferred from an artifact card. A complete fit with no authorized local
+ * executor is a pre-freeze unavailable observation, not a Tier 1 priority
+ * trap. The provider adapter passes its actual execution callback; the engine
+ * uses the bridge's host readiness hook for the zero-provider shortcut.
+ */
+export declare function materializeAskV2WorkspaceTierTruth(state: AskAgentStateV4 | undefined, bridge: AskAgentRuntimeWorkspaceBridgeV2 | undefined, reference?: {
+    question?: string;
+    selectedEvidenceId?: string;
+    certifiedExecutionAvailable?: boolean;
+}): AskAgentToolWorkspaceV2 | undefined;
+export interface AskAgentRuntimeV2 extends AgentRouter {
+    readonly mode: AskRuntimeModeV2;
+}
+export interface AskAgentRuntimeOptionsV2 {
+    mode?: AskRuntimeModeV2;
+    /** The sole V2 retrieval boundary for an ordinary natural-language turn. */
+    getEvidence?: (request: AgentRunRequest) => AgentRetrievalEvidence | undefined | Promise<AgentRetrievalEvidence | undefined>;
+    /** Explicit V1 rollback / shadow comparison only; V2 never uses it after serving. */
+    legacyRouter: AgentRouter;
+}
+/**
+ * Retrieval-first V2 ingress.  It deliberately does not prove a business
+ * tuple or choose a compiler.  That choice is made by the bounded provider
+ * tool runtime after it sees the immutable candidate workspace.
+ */
+export declare function createAskAgentRuntimeV2(options: AskAgentRuntimeOptionsV2): AskAgentRuntimeV2;
+/**
+ * Release a certified tier claim that turned out to be unprovable in flight.
+ *
+ * The fast path narrows the tool policy to `run_certified` and nothing else.
+ * When the downstream admission/proof then refuses that one tool, the policy
+ * used to have no exit: the turn looped run_certified → denied → finish
+ * denied until the deadline, and the user saw a fabricated "validation"
+ * message. The bridge now avoids taking an unprovable claim at all; this
+ * release is the in-flight defense for anything the bridge could not know.
+ */
+export declare function releaseAskV2CertifiedTierLock(state: AskAgentStateV4, reasonCode: string): void;
+//# sourceMappingURL=ask-agent-runtime-v2.d.ts.map