@duckcodeailabs/dql-agent 1.14.2 → 1.14.4

package/dist/analytical-orchestration.d.ts

@@ -11,7 +11,7 @@
  *
  * Acceptance: AGT-027..033, CTX-007, PERF-003, E2E-022.
  */
-import type { DqlArtifactExecutionReceipt } from '@duckcodeailabs/dql-core';
+import type { AgentRunTelemetryV1, DqlArtifactExecutionReceipt } from '@duckcodeailabs/dql-core';
 export declare const ANALYTICAL_ORCHESTRATION_CONTRACT_VERSION: 1;
 export type AnalyticalTurnKind = 'conversation' | 'definition' | 'lookup' | 'ranking' | 'breakdown' | 'comparison' | 'drilldown' | 'diagnosis' | 'research' | 'compound' | 'clarification' | 'aggregation';
 export type AnalyticalTaskKind = 'definition' | 'aggregation' | 'ranking' | 'attribute_lookup' | 'breakdown' | 'comparison' | 'drilldown' | 'diagnosis' | 'research_branch';
@@ -74,14 +74,53 @@ export interface AnalyticalTaskV1 {
         source: 'conversation' | 'result' | 'user';
     }>;
 }
+/**
+ * Trust projected for one task outcome.  This is intentionally the same
+ * local-first vocabulary used by the canonical answer, but it is declared
+ * independently so task receipts remain readable without importing the run
+ * engine (and old JSON records remain valid).
+ */
+export type AnalyticalTaskOutcomeTrustStateV1 = 'certified' | 'governed' | 'review_required' | 'blocked' | 'not_applicable';
+/** Finalized state for one bounded Ask clause or Research branch. */
+export type AnalyticalTaskOutcomeStatusV1 = 'completed' | 'partial' | 'gap' | 'blocked'
+/** A child was deliberately not executed because its required parent failed. */
+ | 'dependency_blocked';
+/** Typed, content-safe failure retained per task rather than collapsed into the root. */
+export interface AnalyticalTaskFailureV1 {
+    version: 1;
+    code: string;
+    message: string;
+    phase: 'planning' | 'execution' | 'dependency';
+}
 /** Durable, content-only outcome for one independent clause/branch. */
 export interface AnalyticalTaskOutcomeV1 {
     version: 1;
     taskId: string;
-    status: 'completed' | 'partial' | 'gap' | 'blocked';
+    status: AnalyticalTaskOutcomeStatusV1;
+    /** Present once a compiler or executor established task-local provenance. */
+    trustState?: AnalyticalTaskOutcomeTrustStateV1;
     summary?: string;
     resultFingerprint?: string;
     gap?: AnalyticalCoverageGapV1;
+    /** Typed cause when the task did not produce an independent result. */
+    failure?: AnalyticalTaskFailureV1;
+    /** Parent task IDs that prevented this child from executing. */
+    dependencyTaskIds?: string[];
+}
+/**
+ * Additive turn-level task receipt for ordinary Ask.  The run's historical
+ * terminal status stays wire-compatible; this summary distinguishes a
+ * completed, partial, or fully blocked multi-task answer without hiding any
+ * independently validated sibling result.
+ */
+export interface AnalyticalTaskOutcomeSummaryV1 {
+    version: 1;
+    status: 'completed' | 'partial' | 'blocked';
+    trustState: AnalyticalTaskOutcomeTrustStateV1;
+    taskCount: number;
+    successfulTaskIds: string[];
+    failedTaskIds: string[];
+    dependencyBlockedTaskIds: string[];
 }
 export interface AnalyticalCoverageGapV1 {
     version: 1;
@@ -104,6 +143,13 @@ export interface AnalyticalCoverageGapV1 {
  * Acceptance: CTX-005, CTX-007, AGT-009, AGT-010.
  */
 export type EvidenceCandidateRoleV1 = 'metric' | 'entity_key' | 'entity_label' | 'categorical_dimension' | 'time_dimension' | 'member' | 'relationship' | 'context';
+/**
+ * Content-safe statement of what the bounded planner package established for
+ * one requested role. `alternatives` deliberately means that qualified cards
+ * were retained for a user choice; it never claims the business meaning was
+ * proven merely because retrieval found related fields.
+ */
+export type EvidenceRoleCoverageStateV1 = 'proven' | 'alternatives';
 /**
  * A typed, content-safe reading of the analytical requirements in a question.
  * It is advisory for retrieval/ranking only: the compatibility solver and the
@@ -116,6 +162,17 @@ export interface AnalyticalRequirementSetV1 {
     entityTerms: string[];
     entityDisplayTerms: string[];
     memberTerms: string[];
+    /**
+     * A host-validated predicate reconstructed from one stable prior result
+     * selection. This is execution context, not an LLM-selected meaning: the
+     * runtime keeps it through retrieval/planning so a deictic follow-up cannot
+     * widen back to the full warehouse after reload.
+     */
+    priorResultMemberBinding?: AnalyticalPriorResultMemberBindingV1;
+    /** Explicit projection fields are requirements, not optional prompt hints. */
+    outputTerms?: string[];
+    /** `individual` requests a row-level relation rather than an aggregate. */
+    grain?: 'individual' | 'aggregate';
     ranking?: {
         metricTerms: string[];
         entityTerms: string[];
@@ -123,15 +180,165 @@ export interface AnalyticalRequirementSetV1 {
         limit: number;
         /** True means the reader did not specify a count and DQL assumed 10. */
         defaultedLimit: boolean;
+        /** Per-group top-N ("top 2 per month") vs one overall ranking. */
+        scope?: 'overall' | 'per_group';
     };
     time?: {
         role: 'time_axis' | 'time_filter';
         grain?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+        /**
+         * A bounded period the answer must be restricted to. This clause was
+         * previously UNREPRESENTABLE: "last two months" had no slot anywhere in
+         * the requirement layer, so it degraded into a grouping dimension while
+         * its count was misread as a row limit. A window is a restriction on
+         * WHEN, independent of whether the answer also groups by a grain.
+         */
+        window?: AnalyticalTimeWindowV1;
         fiscalPeriod?: string;
         /** A fiscal token is not executable until a declared calendar binds it. */
         requiresDeclaredFiscalCalendar: boolean;
     };
+    /**
+     * Where each clause came from, so runtime re-derivation can refresh a
+     * clause read from the current question without silently deleting one the
+     * user established earlier in the conversation or via a clarification.
+     */
+    clauseMeta?: {
+        time?: RequirementClauseMetaV1;
+        ranking?: RequirementClauseMetaV1;
+    };
+}
+/** A typed time restriction; `expression` is the canonical resolver input. */
+export interface AnalyticalTimeWindowV1 {
+    version: 1;
+    kind: 'relative' | 'absolute' | 'named_period';
+    /** Canonical digits form accepted by `resolvePlanTimeRange`, e.g. "last 2 months". */
+    expression: string;
+    relative?: {
+        count: number;
+        unit: 'day' | 'week' | 'month' | 'quarter' | 'year';
+        /** True = complete calendar periods; false = trailing from now. */
+        complete: boolean;
+    };
+    absolute?: {
+        startInclusive: string;
+        endExclusive: string;
+    };
+    namedPeriod?: string;
 }
+export type RequirementClauseProvenance = 'question' | 'inherited' | 'clarification' | 'defaulted';
+export interface RequirementClauseMetaV1 {
+    provenance: RequirementClauseProvenance;
+    required: boolean;
+    sourceTurnId?: string;
+}
+/**
+ * Additive, host-owned representation of a selected value from a prior
+ * canonical result. It intentionally mirrors the engine boundary without
+ * importing that module, so analytical framing remains cycle-free.
+ */
+export interface AnalyticalPriorResultMemberBindingV1 {
+    version: 1;
+    displayDimension: string;
+    values: string[];
+    sourceTurnId?: string;
+    resultFingerprint?: string;
+}
+/**
+ * Preserve a validated prior-result predicate as typed analytical context.
+ * The selected display key supplies the entity/display requirements needed to
+ * retrieve relationship closure; the literal values remain an immutable host
+ * filter and are never treated as a provider-selected member meaning.
+ */
+export declare function withAnalyticalPriorResultMemberBinding(requirements: AnalyticalRequirementSetV1, binding: AnalyticalPriorResultMemberBindingV1 | undefined): AnalyticalRequirementSetV1;
+/**
+ * Host-owned analytical input to the one bounded meaning call.  The seed is
+ * built before any provider response and is the only source of explicit user
+ * requirements downstream.  The model may bind supplied candidate IDs and
+ * explain ambiguity; it may not erase, add, or replace the request tuple.
+ *
+ * This is deliberately not an execution plan. It contains business terms and
+ * parsed filters only; the compatibility solver and immutable resolved plan
+ * still own qualified identifiers, joins, SQL, trust, and route selection.
+ */
+export interface AnalyticalRequirementSeedV1 {
+    version: 1;
+    sourceQuestion: string;
+    requirements: AnalyticalRequirementSetV1;
+    queryIntent: {
+        measures: string[];
+        dimensions: string[];
+        filters: Array<{
+            field: string;
+            value: string;
+        }>;
+        timeRange?: string;
+        timeGrain?: string;
+        order?: 'asc' | 'desc';
+        limit?: number;
+        fiscalCalendarId?: string;
+        fiscalDateRoleId?: string;
+    };
+}
+/** Build the immutable host request tuple before a meaning model can respond. */
+export declare function buildAnalyticalRequirementSeedV1(input: {
+    question: string;
+    parsedIntent?: Partial<{
+        measures: string[];
+        dimensions: string[];
+        filters: Array<{
+            field: string;
+            value: string;
+        }>;
+        timeRange: string;
+        timeGrain: string;
+        order: 'asc' | 'desc';
+        limit: number;
+        fiscalCalendarId: string;
+        fiscalDateRoleId: string;
+    }>;
+    requirements?: AnalyticalRequirementSetV1;
+    priorResultMemberBinding?: AnalyticalPriorResultMemberBindingV1;
+    fiscalCalendar?: {
+        id: string;
+        dateRoleId?: string;
+        fiscalPeriodFieldId?: string;
+    };
+}): AnalyticalRequirementSeedV1;
+type RetrievalParsedIntentRefinement = Partial<{
+    measures: string[];
+    dimensions: string[];
+    filters: Array<{
+        field: string;
+        value: string;
+    }>;
+    timeRange: string;
+    timeGrain: string;
+    order: 'asc' | 'desc';
+    limit: number;
+    fiscalCalendarId: string;
+    fiscalDateRoleId: string;
+}>;
+/**
+ * Return only parser refinements whose business words occur in the current
+ * source question. This deliberately does not try to recover previous turn
+ * context: continuation is represented by a server-issued structured choice
+ * and merged separately by the host. The helper is exported for regression
+ * tests and for router paths that construct a requirement set before a seed.
+ */
+export declare function currentQuestionGroundedParsedIntent(question: string, parsedIntent: RetrievalParsedIntentRefinement | undefined): RetrievalParsedIntentRefinement | undefined;
+/**
+ * Preserve a small set of explicit current-question literals even when a
+ * retriever did not emit a parser filter. This is deliberately not a value
+ * search or synonym engine: it records only quoted values, capitalized proper
+ * names, and values introduced by an explicit predicate phrase. The planner
+ * must still bind each term to an admitted, qualified member/dimension card
+ * before it can become an executable filter.
+ *
+ * Without this host-owned atom, "customers in Philadelphia" could reach a
+ * broad certified fit after retrieval silently omitted the parser filter.
+ */
+export declare function currentQuestionLiteralMemberTerms(question: string): string[];
 export type ContextSourceCoverageStatusV1 = 'available' | 'empty' | 'stale' | 'unavailable' | 'errored' | 'skipped';
 /** Source coverage is distinct from a missing capability.  A bounded package
  * may omit a relevant candidate; that is not proof that the source lacks it. */
@@ -172,6 +379,162 @@ export interface ExploratoryExecutionFreezeV1 {
     candidateIds: string[];
     /** The host minted one single-use capability before connector execution. */
     authorization: 'capability_minted';
+    /**
+     * Per-output proof emitted by the host SQL validator.  When a frozen plan
+     * names explicit projected identifiers, a result is displayable only if the
+     * authorization receipt carries one exact physical source binding for each
+     * of them.  Optional for pre-V4 persisted receipts; required for new
+     * exploratory execution with required outputs.
+     */
+    requiredOutputBindings?: ExploratoryRequiredOutputBindingProofV1[];
+    /**
+     * SQL authorization is distinct from the router plan freeze.  Index zero is
+     * the first exact SQL handoff; index one is the only permitted same-plan
+     * correction after a retryable warehouse execution failure.  Older receipts
+     * omit this additive field and are interpreted as the original handoff.
+     */
+    authorizationAttempt?: ExploratoryExecutionAuthorizationAttemptV1;
+}
+/**
+ * Host-owned proof that one output alias in the authorized SQL came from the
+ * exact physical source selected in the frozen analytical plan.  The SQL text
+ * remains in the local execution boundary; this portable receipt carries only
+ * qualified identifiers and normalized relation/column names.
+ */
+export interface ExploratoryRequiredOutputBindingProofV1 {
+    version: 1;
+    outputName: string;
+    qualifiedId: string;
+    relation: string;
+    column: string;
+}
+/**
+ * Server-owned lifecycle marker for an exploratory SQL capability.  A repair
+ * does not reopen routing or meaning: it may only replace the SQL bytes while
+ * preserving the frozen plan, snapshot, target, candidate closure, and
+ * read-only validation proof.
+ */
+export type ExploratoryExecutionAuthorizationAttemptV1 = {
+    version: 1;
+    index: 0;
+    parentSqlFingerprint?: never;
+} | {
+    version: 1;
+    index: 1;
+    parentSqlFingerprint: string;
+};
+/**
+ * A host authorization attaches to a plan the router has already frozen.  The
+ * plan freeze establishes the meaning, candidate closure, and source snapshot;
+ * this receipt establishes only the exact read-only SQL and live target.  It
+ * is intentionally an alias of the existing wire shape so persisted V1/V3
+ * runs remain readable while callers stop treating authorization as the point
+ * at which a plan becomes frozen.
+ *
+ * Acceptance: AGT-029, AGT-031, AGT-034.
+ */
+export type ExploratoryExecutionAuthorizationReceiptV1 = ExploratoryExecutionFreezeV1;
+/** A content-safe, server-produced terminal incident for Ask observability. */
+export interface AskTerminalIncidentV1 {
+    version: 1;
+    code: 'INTERNAL_EXPLORATORY_AUTHORIZATION_STATE_MISMATCH' | 'CONNECTION_NOT_CONFIGURED'
+    /** A frozen plan failed before any statement reached the warehouse. */
+     | 'COMPILATION_FAILED'
+    /** The executed rows did not satisfy the immutable frozen result contract. */
+     | 'RESULT_CONTRACT_MISMATCH' | 'ANALYTICAL_EXECUTION_FAILED' | 'ANALYTICAL_COVERAGE_GAP' | 'PROVIDER_FAILURE'
+    /** Every admitted Research branch used its bounded window without a finding. */
+     | 'RESEARCH_BRANCH_TIMEOUT'
+    /** Explicit Research exhausted its root deadline before finalization. */
+     | 'RESEARCH_RUN_DEADLINE' | 'CANCELLED';
+    boundary: 'plan.compile' | 'semantic.compile' | 'sql.authorize' | 'sql.execute' | 'result.validate' | 'provider' | 'cascade' | 'run';
+    origin: 'internal_invariant' | 'governance_gate' | 'semantic_compiler' | 'plan_compiler' | 'result_validator' | 'provider' | 'warehouse' | 'unknown';
+    impact: 'execution_not_attempted' | 'execution_failed' | 'answer_not_produced' | 'run_cancelled';
+    safeAction: 'export_redacted_trace' | 'configure_connection' | 'change_authorized_connection' | 'inspect_failure' | 'retry_same_plan' | 'refresh_snapshot' | 'edit_dql' | 'open_sql_notebook' | 'request_access' | 'reapply_semantic_runtime' | 'review_analytical_failure' | 'inspect_research_failures' | 'none';
+}
+/**
+ * A compact, producer-owned account of a completed-but-limited Research run.
+ *
+ * This is deliberately distinct from `AskTerminalIncidentV1`: the root Ask
+ * can retain a receipt-backed finding and its selected trust state while one
+ * or more independently bounded Research children failed, timed out, or were
+ * skipped.  The summary carries only typed counts, reason codes, and frozen
+ * child-plan evidence; it never retains branch prompts, result rows, SQL, or
+ * provider content.
+ */
+export interface AskResearchBranchSummaryV1 {
+    version: 1;
+    totalBranches: number;
+    /** Children that completed their bounded lifecycle. */
+    completedBranches: number;
+    /** Completed children with a persisted execution receipt in the V2 ledger. */
+    receiptBackedBranches: number;
+    failedBranches: number;
+    timedOutBranches: number;
+    skippedBranches: number;
+    /** True only when a receipt-backed finding survived alongside a limited child. */
+    partialSuccess: boolean;
+    failureReasons: Array<{
+        code: 'execution_failed' | 'research_branch_timeout' | 'budget_exhausted' | 'run_deadline' | 'cancelled';
+        branchCount: number;
+    }>;
+    /** Frozen child plans actually persisted by the Research root. */
+    availableChildPlans: Array<{
+        tier: Exclude<AnalyticalCascadeTierV1, 'clarify_or_gap'>;
+        frozenPlanCount: number;
+        branchCount: number;
+        reviewRequired: boolean;
+    }>;
+    /** Distinct child run IDs carried by durable branch receipts. */
+    linkedChildRunCount: number;
+    safeAction: 'inspect_research_failures';
+}
+/** One compact canonical story used by both the inspector and full trace. */
+export interface AskDecisionSummaryV1 {
+    version: 1;
+    summaryFingerprint: string;
+    understoodRequest: {
+        measures: number;
+        dimensions: number;
+        entityRequested: boolean;
+        outputCount: number;
+        ranking?: {
+            direction: 'top' | 'bottom';
+            limit: number;
+            defaultedLimit: boolean;
+        };
+        conversationBinding: 'none' | 'structured_clarification' | 'prior_result' | 'task_dependency';
+    };
+    evidenceByRole: Array<{
+        role: EvidenceCandidateRoleV1;
+        candidateCount: number;
+    }>;
+    tierDecisions: Array<{
+        tier: AnalyticalCascadeTierV1;
+        outcome: AnalyticalCascadeTierOutcomeV1;
+        planFrozen: boolean;
+    }>;
+    selectedPlan?: {
+        tier: Exclude<AnalyticalCascadeTierV1, 'clarify_or_gap'>;
+        planFrozen: boolean;
+        reviewRequired: boolean;
+    };
+    terminalIncident?: AskTerminalIncidentV1;
+    /** Present for persisted Research branch evidence; does not change root status. */
+    researchBranchSummary?: AskResearchBranchSummaryV1;
+    safeNextAction: AskTerminalIncidentV1['safeAction'] | 'none';
+}
+/**
+ * A narrow, producer-owned terminal relationship witness carried with the
+ * authoritative cascade.  It is deliberately enumerated rather than a copy
+ * of router prose: durable Ask receipts must explain an allocation/relationship
+ * block without persisting a question, candidate label, or inferred join.
+ */
+export interface AnalyticalCascadeTerminalGapV1 {
+    version: 1;
+    code: 'MISSING_RELATIONSHIP';
+    requirement: 'certified_relationship_or_allocation_proof';
+    /** Qualified evidence IDs only; presentation never infers new paths. */
+    witnessCandidateIds: string[];
 }
 /**
  * The shared cascade receipt.  This does not itself compile SQL; it prevents
@@ -187,6 +550,14 @@ export interface AnalyticalCascadeDecisionV1 {
     planFrozen: boolean;
     /** Present only after a selected exploratory proposal is host-authorized. */
     exploratoryExecutionFreeze?: ExploratoryExecutionFreezeV1;
+    /**
+     * Present only when one retryable warehouse failure received the sole
+     * permitted same-plan exploratory SQL repair authorization.  The original
+     * receipt remains above so persisted evidence proves parent-before-repair.
+     */
+    exploratoryRepairExecutionFreeze?: ExploratoryExecutionFreezeV1;
+    /** Present only when the router supplied a typed, relationship-safe gap. */
+    terminalGap?: AnalyticalCascadeTerminalGapV1;
     stopReason: 'selected' | 'ambiguous' | 'coverage_gap' | 'denied' | 'post_freeze_failure';
 }
 export type ProviderFailureCauseV1 = 'authentication' | 'model_not_found' | 'rate_limited' | 'gateway' | 'network' | 'provider_timeout' | 'run_deadline' | 'admission_denied' | 'dispatch_budget' | 'cancelled' | 'unknown';
@@ -194,7 +565,7 @@ export type ProviderFailureCauseV1 = 'authentication' | 'model_not_found' | 'rat
 export interface ProviderFailureDiagnosticV1 {
     version: 1;
     cause: ProviderFailureCauseV1;
-    phase: 'preflight' | 'meaning_resolution' | 'planning' | 'generation' | 'repair' | 'narration' | 'unknown';
+    phase: 'preflight' | 'classification' | 'meaning_resolution' | 'planning' | 'generation' | 'repair' | 'narration' | 'agent_control' | 'tool_followup' | 'unknown';
     retryable: boolean;
     safeAction: 'retry_same_provider' | 'fix_provider_configuration' | 'wait_and_retry' | 'inspect_run' | 'none';
     httpStatusClass?: '4xx' | '5xx';
@@ -211,11 +582,682 @@ export interface AgentRunDiagnosticReceiptV3 {
     runId: string;
     sourceCoverage: ContextSourceCoverageV1[];
     cascade?: AnalyticalCascadeDecisionV1;
+    /** Direct projection for run-detail consumers that do not traverse cascade. */
+    terminalGap?: AnalyticalCascadeTerminalGapV1;
     planFrozen: boolean;
     orchestrationMode?: 'legacy' | 'shadow' | 'agentic';
     provider?: ProviderFailureDiagnosticV1;
     finalStopReason: string;
 }
+/**
+ * Additive canonical Ask story. V1/V2/V3 remain readable; this receipt is
+ * deliberately JSON-only so no metadata/index migration is needed.
+ */
+export interface AgentRunDiagnosticReceiptV4 {
+    version: 4;
+    runId: string;
+    summary: AskDecisionSummaryV1;
+    terminalIncident?: AskTerminalIncidentV1;
+    finalStopReason: string;
+}
+/**
+ * Ask Analyst Runtime V1 contracts.
+ *
+ * These records deliberately separate an agent's business interpretation from
+ * the deterministic compiler/execution authority.  They contain typed intent,
+ * stable candidate identities, and receipts — never prompts, provider
+ * responses, SQL text, result rows, credentials, or hidden reasoning.
+ *
+ * Acceptance: AGT-035..040, API-015, OBS-015, E2E-023.
+ */
+export type AskAnalystRuntimeModeV1 = 'legacy' | 'shadow' | 'authoritative';
+export interface BusinessQuestionFrameV3 {
+    version: 3;
+    /** Stable only within the persisted run; raw question text stays on AgentRun. */
+    questionFingerprint: string;
+    kind: AnalyticalTurnKind;
+    requirements: AnalyticalRequirementSetV1;
+    /** A source question supplied a top-N default; presentation must disclose it. */
+    defaultedTop?: {
+        limit: number;
+    };
+    conversation: {
+        binding: 'none' | 'structured_clarification' | 'prior_result' | 'task_dependency';
+        sourceTurnId?: string;
+        selectedStableId?: string;
+    };
+}
+export type AnalyticalHypothesisKindV1 = 'direct_answer' | 'trend' | 'comparison' | 'contributor' | 'anomaly' | 'freshness' | 'counter_evidence';
+/** Agent-proposed question to test; deterministic execution validates it. */
+export interface AnalyticalHypothesisV1 {
+    version: 1;
+    id: string;
+    kind: AnalyticalHypothesisKindV1;
+    taskId: string;
+    status: 'planned' | 'supported' | 'contradicted' | 'inconclusive' | 'failed' | 'skipped';
+    requiredRoles: EvidenceCandidateRoleV1[];
+}
+/** Bounded mission owned by the Ask runtime before a compiler is selected. */
+export interface AnalyticalMissionV1 {
+    version: 1;
+    mode: 'ask' | 'research';
+    taskLimit: number;
+    planningContinuationLimit: number;
+    /**
+     * The ingress task graph exceeded this mission's bounded capacity. This is
+     * separate from `deferredTasks`: ordinary Ask must present a scope outcome
+     * before planning/execution rather than silently dropping clauses.
+     */
+    scopeOverflow?: boolean;
+    tasks: AnalyticalTaskV1[];
+    /**
+     * Ordinary Ask currently freezes one route-neutral executable program per
+     * turn. When ingress splits a compound request, retain the unexecuted
+     * clauses explicitly instead of silently running task-1 and losing the
+     * rest. Research owns the multi-branch execution contract.
+     */
+    deferredTasks?: Array<Pick<AnalyticalTaskV1, 'id' | 'kind'>>;
+    hypotheses: AnalyticalHypothesisV1[];
+}
+export interface EvidenceWorkspaceToolReceiptV1 {
+    version: 1;
+    id: string;
+    kind: 'retrieve_snapshot' | 'candidate_extension' | 'compiler_broker' | 'provider_meaning' | 'execute' | 'repair';
+    status: 'completed' | 'skipped' | 'failed';
+    candidateIds: string[];
+    reasonCode: string;
+}
+/** Same-snapshot evidence admission; excluded is never interpreted as absent. */
+export interface EvidenceWorkspaceV1 {
+    version: 1;
+    snapshotId?: string;
+    sourceFingerprint?: string;
+    sourceCoverage: ContextSourceCoverageV1[];
+    /**
+     * Additive V2 admission projection.  Legacy readers use
+     * `admittedCandidateIds`; new Ask runs retain the qualified 32-card
+     * execution workspace separately from the 16 cards released to the
+     * planner.  Both are stable IDs from one immutable snapshot.
+     */
+    workspaceCandidateIds?: string[];
+    plannerCandidateIds?: string[];
+    admittedCandidateIds: string[];
+    excludedCandidates: Array<{
+        id: string;
+        reasonCode: 'role_cap' | 'incompatible' | 'ranking_conflict' | 'duplicate' | 'not_admitted';
+    }>;
+    tools: EvidenceWorkspaceToolReceiptV1[];
+}
+/**
+ * Route-neutral analytical intent.  Certified, MetricFlow, governed
+ * relational, and exploratory SQL are all compilers of this one program.
+ */
+export interface AnalyticalProgramV1 {
+    version: 1;
+    id: string;
+    frameFingerprint: string;
+    taskIds: string[];
+    /** Immutable selected evidence identities. Compilers may only consume these. */
+    candidateIds: string[];
+    /**
+     * Same-snapshot compiler context. This is deliberately separate from the
+     * bounded meaning cards: a physical relation/column closure may be needed
+     * for a pre-freeze fallback even when it was not sent to the meaning model.
+     * It is still immutable, target-scoped by the compiler, and never a license
+     * to retrieve or nominate a new business meaning.
+     */
+    executionCandidateIds?: string[];
+    requiredRoles: EvidenceCandidateRoleV1[];
+    /** Route-neutral predicate/member contract; never inferred by a compiler. */
+    filters: Array<{
+        fieldTerms: string[];
+        memberIds: string[];
+        /** Literal/member binding owned by the program, never guessed by a compiler. */
+        value: string;
+        operator: 'equals' | 'in' | 'between' | 'contains' | 'unknown';
+    }>;
+    ranking?: {
+        metricTerms: string[];
+        direction: 'asc' | 'desc';
+        limit: number;
+        defaultedLimit?: boolean;
+    };
+    time?: {
+        roleTerms: string[];
+        calendarId?: string;
+        fiscalPeriodTerms: string[];
+        grain?: NonNullable<AnalyticalRequirementSetV1['time']>['grain'];
+    };
+    comparison?: {
+        kind: 'none' | 'period_over_period' | 'segment' | 'baseline';
+        terms: string[];
+    };
+    /** Stable relationship evidence IDs required to combine selected objects. */
+    relationshipRequirements: string[];
+    outputs: {
+        measures: string[];
+        dimensions: string[];
+        entityDisplayTerms: string[];
+        timeGrain?: NonNullable<AnalyticalRequirementSetV1['time']>['grain'];
+        limit?: number;
+        assertions: Array<'all_requested_measures' | 'all_requested_dimensions' | 'safe_relationship_closure' | 'result_contract'>;
+    };
+}
+/** Runtime-owned selection receipt around the existing immutable RAP. */
+export interface ResolvedAnalyticalPlanV2 {
+    version: 2;
+    programId: string;
+    compiler: 'certified' | 'metricflow' | 'governed_relational' | 'exploratory_sql' | 'none';
+    selectedTier?: Exclude<AnalyticalCascadeTierV1, 'clarify_or_gap'>;
+    planFrozen: boolean;
+    reviewRequired: boolean;
+    planFingerprint?: string;
+}
+/** Typed continuation material that survives reload without reparsing prose. */
+export interface AskAnalystConversationDeltaV1 {
+    version: 1;
+    sourceQuestionFingerprint: string;
+    selectedStableId?: string;
+    selectedResultBindingId?: string;
+    partialFrame: Pick<BusinessQuestionFrameV3, 'kind' | 'requirements'>;
+}
+export interface AskAnalystStateV1 {
+    version: 1;
+    mode: AskAnalystRuntimeModeV1;
+    phase: 'framed' | 'evidence_ready' | 'program_ready' | 'compiled' | 'executed' | 'clarify' | 'blocked';
+    frame: BusinessQuestionFrameV3;
+    mission: AnalyticalMissionV1;
+    workspace: EvidenceWorkspaceV1;
+    program: AnalyticalProgramV1;
+    resolvedPlan?: ResolvedAnalyticalPlanV2;
+    conversationDelta: AskAnalystConversationDeltaV1;
+    planningContinuations: number;
+    toolCalls: number;
+    executionAttempts: number;
+    repairAttempts: number;
+}
+/** A fact-bound answer envelope. Narrative can only summarize these receipts. */
+export interface BusinessAnswerV1 {
+    version: 1;
+    mode: 'facts_only' | 'deterministic_fallback';
+    trustState: 'certified' | 'governed' | 'review_required' | 'blocked' | 'not_applicable';
+    factIds: string[];
+    resultFingerprint?: string;
+    /** The accepted answer text, already visible in the corresponding artifact. */
+    answer?: string;
+    limitations: string[];
+    /** Additive per-task aggregate; omitted by legacy/single-task records. */
+    taskOutcomeSummary?: AnalyticalTaskOutcomeSummaryV1;
+}
+/**
+ * Content-free runtime projection for diagnostics/trace export. The durable
+ * local run retains typed continuation state; this projection intentionally
+ * omits raw question, requirement/member values, answer text, SQL, and rows.
+ */
+export interface AskAnalystDiagnosticStateV1 {
+    version: 1;
+    mode: AskAnalystRuntimeModeV1;
+    phase: AskAnalystStateV1['phase'];
+    questionFingerprint: string;
+    kind: AnalyticalTurnKind;
+    requirementCounts: {
+        measures: number;
+        dimensions: number;
+        entityTerms: number;
+        members: number;
+        filters: number;
+    };
+    mission: {
+        mode: AnalyticalMissionV1['mode'];
+        taskCount: number;
+        deferredTaskCount: number;
+        hypothesisCount: number;
+    };
+    workspace: {
+        snapshotId?: string;
+        sourceFingerprint?: string;
+        admittedCandidateCount: number;
+        excludedCandidateCount: number;
+        sourceCoverage: Array<{
+            source: ContextSourceCoverageV1['source'];
+            status: ContextSourceCoverageV1['status'];
+            candidateCount: number;
+        }>;
+        tools: Array<Pick<EvidenceWorkspaceToolReceiptV1, 'id' | 'kind' | 'status' | 'reasonCode'>>;
+    };
+    program: {
+        id: string;
+        taskCount: number;
+        candidateCount: number;
+        requiredRoles: EvidenceCandidateRoleV1[];
+        outputAssertionCount: number;
+    };
+    resolvedPlan?: ResolvedAnalyticalPlanV2;
+    counters: {
+        planningContinuations: number;
+        toolCalls: number;
+        executionAttempts: number;
+        repairAttempts: number;
+    };
+}
+export interface BusinessAnswerDiagnosticProjectionV1 {
+    version: 1;
+    mode: BusinessAnswerV1['mode'];
+    trustState: BusinessAnswerV1['trustState'];
+    factIds: string[];
+    resultFingerprint?: string;
+    limitationCount: number;
+}
+/** Compact default trace story; advanced spans remain in local observability. */
+export interface AskDecisionSummaryV2 {
+    version: 2;
+    summaryFingerprint: string;
+    runtimeMode: AskAnalystRuntimeModeV1;
+    whatHappened: string;
+    why: string;
+    impact: string;
+    nextAction: AskTerminalIncidentV1['safeAction'] | 'none';
+    selectedCompiler?: ResolvedAnalyticalPlanV2['compiler'];
+    programTaskCount: number;
+    admittedCandidateCount: number;
+    toolCallCount: number;
+    executionAttempts: number;
+}
+/** Additive V5 receipt; V1-V4 remain readable JSON records. */
+export interface AgentRunDiagnosticReceiptV5 {
+    version: 5;
+    runId: string;
+    state: AskAnalystDiagnosticStateV1;
+    summary: AskDecisionSummaryV2;
+    businessAnswer?: BusinessAnswerDiagnosticProjectionV1;
+    /** Typed terminal provider evidence from the physical provider boundary. */
+    provider?: ProviderFailureDiagnosticV1;
+    finalStopReason: string;
+}
+/**
+ * Additive retrieval-first Ask contracts.  V1 records remain the persisted
+ * compatibility shape; V2 is the authoritative runtime shape for new turns.
+ * The planner gets qualified cards only and cannot turn a raw retrieval term
+ * into an execution identity.
+ */
+export type AskPlanningModeV1 = 'exact_fast_path' | 'initial_planner' | 'targeted_revision' | 'deterministic_binding';
+export interface AnalyticalPlannerCandidateCardV1 {
+    version: 1;
+    id: string;
+    qualifiedId?: string;
+    /** Compact retrieval label/aliases; never a raw definition dump or row data. */
+    label?: string;
+    aliases?: string[];
+    roles: EvidenceCandidateRoleV1[];
+    source: ContextSourceCoverageV1['source'];
+    trustTier: 'certified' | 'semantic' | 'governed' | 'exploratory';
+    exactMatch: boolean;
+    /**
+     * The card was retained so the planner can resolve one otherwise-unmet
+     * business role. This is admission context only: it is not a declared
+     * alias, selected meaning, or execution authorization. The verifier must
+     * still prove an exact declaration or one unique inferred substitution.
+     */
+    admissionReasonCode?: 'candidate_for_unresolved_role';
+    unresolvedRoles?: EvidenceCandidateRoleV1[];
+    relationHints?: string[];
+    /** Present only for a host-authored relationship-path card; exploratory never implies governed authority. */
+    relationshipProofClass?: 'governed' | 'exploratory';
+}
+export interface AnalyticalPlannerRequestV1 {
+    version: 1;
+    planningMode: AskPlanningModeV1;
+    /** Raw business question is intentionally available only at the bounded planner boundary. */
+    question: string;
+    questionFingerprint: string;
+    /**
+     * Advisory frame for the planner. It is deliberately not an immutable
+     * execution tuple: parser-derived metric/entity/dimension guesses can be
+     * corrected only by selecting locally-qualified cards. Explicit user
+     * predicates, time, ranking and output constraints remain host verified.
+     */
+    frame: Pick<BusinessQuestionFrameV4, 'kind' | 'requirements' | 'conversation' | 'planningMode'>;
+    /** Host-owned, content-safe hints; they are advisory and never execution authority. */
+    advisoryHints: string[];
+    sourceCoverage: Array<Pick<ContextSourceCoverageV1, 'source' | 'status'>>;
+    /**
+     * Bounded server-derived task options. They are not an execution plan: the
+     * planner may select one compatible option or two/three independent options,
+     * and the verifier later requires every selected ID to freeze and execute.
+     */
+    taskOptions: Array<{
+        id: string;
+        kind: AnalyticalTaskV1['kind'];
+        question: string;
+    }>;
+    /**
+     * Present only for the one verifier-directed revision. Prior selected
+     * bindings are immutable context; only a card in `targetedCandidates` may
+     * fill the verifier-proven missing role.
+     */
+    priorProposal?: Pick<AnalyticalPlannerProposalV1, 'version' | 'selectedConceptIds' | 'tasks'>;
+    priorSelectedConceptIds?: string[];
+    verificationFeedback?: ProgramVerificationFeedbackV1;
+    /** At most four verifier-admitted cards released for a targeted revision. */
+    targetedCandidates?: AnalyticalPlannerCandidateCardV1[];
+    candidates: AnalyticalPlannerCandidateCardV1[];
+    deadlineMs: number;
+}
+export type AnalyticalPlannerOperationV1 = 'aggregate' | 'rank' | 'group' | 'filter' | 'trend' | 'compare' | 'project';
+export interface AnalyticalPlannerTaskProposalV1 {
+    version: 1;
+    taskId: string;
+    /**
+     * Server task options this one program deliberately covers. Omitted means
+     * only `taskId`. The verifier must prove complete coverage before a
+     * compatible multi-clause Ask may collapse to one execution.
+     */
+    coveredTaskIds?: string[];
+    selectedConceptIds: string[];
+    /** Candidate-ID role bindings only; the verifier owns role compatibility. */
+    roleBindings: Partial<Record<EvidenceCandidateRoleV1, string[]>>;
+    /** Typed analytical intent, never SQL/DQL or a compiler authorization. */
+    operations: AnalyticalPlannerOperationV1[];
+    preferredCompiler?: 'certified' | 'metricflow' | 'governed_relational' | 'exploratory_sql';
+    assumptions?: string[];
+}
+export interface TargetedContextRequestV1 {
+    version: 1;
+    /** Exactly one verifier-proven role may be recovered per Ask turn. */
+    missingRoles: EvidenceCandidateRoleV1[];
+    /**
+     * Normalized business terms used to search the existing immutable 32-card
+     * workspace. The planner never receives or mints hidden workspace IDs.
+     */
+    searchTerms?: string[];
+    /** Optional references to cards already in the supplied 16-card package. */
+    relatedCandidateIds?: string[];
+    /**
+     * Legacy compatibility carrier. New planner JSON must not use this to name
+     * an unadmitted card; the verifier rejects anything outside the planner
+     * package before it can be treated as a recovery hint.
+     */
+    candidateIds?: string[];
+    /** Existing same-snapshot relationship paths, bounded to three. */
+    relationshipPathIds?: string[];
+}
+export interface TargetedContextResultV1 {
+    version: 1;
+    status: 'admitted' | 'unavailable' | 'denied';
+    candidateIds: string[];
+    relationshipPathIds: string[];
+    reasonCode: string;
+}
+export interface AnalyticalPlannerProposalV1 {
+    version: 1;
+    tasks: AnalyticalPlannerTaskProposalV1[];
+    selectedConceptIds: string[];
+    confidence?: 'high' | 'medium' | 'low';
+    missingInformation?: string[];
+    recovery?: TargetedContextRequestV1;
+}
+export interface ProgramVerificationFeedbackV1 {
+    version: 1;
+    status: 'valid' | 'needs_targeted_context' | 'ambiguous' | 'denied' | 'invalid';
+    missingRoles: EvidenceCandidateRoleV1[];
+    candidateIds: string[];
+    reasonCode: string;
+}
+export interface EvidenceWorkspaceV2 extends Omit<EvidenceWorkspaceV1, 'version' | 'admittedCandidateIds'> {
+    version: 2;
+    /** The qualified immutable closure; never exceeds 32 candidates. */
+    workspaceCandidateIds: string[];
+    /** Cards released to the one planner call; never exceeds 16. */
+    plannerCandidateIds: string[];
+    /** V1 consumers read this as the planner admission. */
+    admittedCandidateIds: string[];
+    /**
+     * Content-safe role admission counters. These are captured at the runtime
+     * boundary, rather than reconstructed later from raw retrieval cards, so a
+     * V7 trace can distinguish a missing requested role from a role-cap
+     * exclusion after reload without retaining business labels or values.
+     */
+    roleCoverage?: Array<{
+        role: EvidenceCandidateRoleV1;
+        candidateCount: number;
+        state?: EvidenceRoleCoverageStateV1;
+    }>;
+    targetedContext?: TargetedContextResultV1;
+}
+export interface BusinessQuestionFrameV4 extends Omit<BusinessQuestionFrameV3, 'version'> {
+    version: 4;
+    planningMode: AskPlanningModeV1;
+}
+export interface AnalyticalProgramV2 extends Omit<AnalyticalProgramV1, 'version' | 'candidateIds' | 'executionCandidateIds'> {
+    version: 2;
+    /** Validated meaning cards selected by the planner. */
+    candidateIds: string[];
+    /** Full immutable qualified workspace consumed by compilers. */
+    executionCandidateIds: string[];
+    plannerCandidateIds: string[];
+    workspaceCandidateIds: string[];
+    /**
+     * Provider-neutral business interpretation accepted by the deterministic
+     * verifier. IDs remain canonicalized below; the planner never gains join,
+     * grain, additivity, trust, or compiler authority.
+     */
+    planner: {
+        version: 1;
+        tasks: Array<{
+            taskId: string;
+            coveredTaskIds?: string[];
+            selectedConceptIds: string[];
+            roleBindings: Partial<Record<EvidenceCandidateRoleV1, string[]>>;
+            operations: AnalyticalPlannerOperationV1[];
+            preferredCompiler?: AnalyticalPlannerTaskProposalV1['preferredCompiler'];
+            assumptions: string[];
+        }>;
+        confidence?: AnalyticalPlannerProposalV1['confidence'];
+        missingInformation: string[];
+    };
+}
+/**
+ * Planner V2 is the post-verification business interpretation.  The provider
+ * V1 wire format remains readable during rollout, but a frozen program does
+ * not preserve a provider-selected relationship/join binding: relationship
+ * closure is compiler-owned evidence, not business meaning.
+ */
+export type AnalyticalPlannerBusinessRoleV2 = Exclude<EvidenceCandidateRoleV1, 'relationship'>;
+export interface AnalyticalPlannerTaskV2 {
+    taskId: string;
+    coveredTaskIds?: string[];
+    selectedConceptIds: string[];
+    roleBindings: Partial<Record<AnalyticalPlannerBusinessRoleV2, string[]>>;
+    operations: AnalyticalPlannerOperationV1[];
+    preferredCompiler?: AnalyticalPlannerTaskProposalV1['preferredCompiler'];
+    assumptions: string[];
+}
+export interface AnalyticalPlannerInterpretationV2 {
+    version: 2;
+    /** The source is diagnostic only; it cannot change authority after verify. */
+    source: 'provider' | 'deterministic' | 'legacy_adapter';
+    tasks: AnalyticalPlannerTaskV2[];
+    confidence?: AnalyticalPlannerProposalV1['confidence'];
+    missingInformation: string[];
+}
+/**
+ * One host-derived safe relationship closure.  `candidateId` refers to the
+ * compact same-snapshot path card; `relationshipEvidence` contains only its
+ * canonical proof IDs.  A planner never selects either value.
+ */
+export interface CanonicalRelationshipPathReceiptV1 {
+    version: 1;
+    candidateId: string;
+    proofClass: 'governed' | 'exploratory';
+    relationshipEvidence: string[];
+}
+/**
+ * Lossless typed inputs that survive planner/legacy adapter conversions. The
+ * words remain local program data; diagnostic projections expose counts only.
+ */
+export interface AnalyticalInputAtomV1 {
+    version: 1;
+    source: 'current_question' | 'trusted_successful_task';
+    role: Exclude<EvidenceCandidateRoleV1, 'relationship' | 'context'> | 'filter';
+    term: string;
+    required: true;
+}
+/** A host-validated anchor from a successful prior task/result. */
+export interface TrustedAnalyticalTaskAnchorV1 {
+    version: 1;
+    /**
+     * `member_binding` retains a validated selected result value.
+     * `analytical_shape` retains only a successful task's metric/projection
+     * shape for an explicit additive follow-up such as "add region here".
+     * Neither form is provider supplied.
+     */
+    kind?: 'member_binding' | 'analytical_shape';
+    displayDimension?: string;
+    values: string[];
+    /** Existing successful-task shape; no rows or free-form prior answer. */
+    measures?: string[];
+    dimensions?: string[];
+    sourceTurnId?: string;
+    resultFingerprint?: string;
+}
+/**
+ * The authoritative frozen Ask contract. V1/V2 remain valid persisted JSON
+ * readers; all new authoritative turns construct V3 before compiler entry.
+ */
+export interface AnalyticalProgramV3 extends Omit<AnalyticalProgramV2, 'version' | 'planner'> {
+    version: 3;
+    planner: AnalyticalPlannerInterpretationV2;
+    /** Compiler-owned path receipts; never provider-selected join instructions. */
+    relationshipPaths: CanonicalRelationshipPathReceiptV1[];
+    /** Current-turn atoms cannot be erased by a compatibility MeaningResolution. */
+    inputAtoms: AnalyticalInputAtomV1[];
+    /** Validated prior-result anchors are distinct from free-text member guesses. */
+    trustedTaskAnchors: TrustedAnalyticalTaskAnchorV1[];
+}
+export interface AskAnalystConversationDeltaV2 extends Omit<AskAnalystConversationDeltaV1, 'version' | 'partialFrame'> {
+    version: 2;
+    partialFrame: Pick<BusinessQuestionFrameV4, 'kind' | 'requirements' | 'planningMode'>;
+    programId?: string;
+}
+export interface AskAnalystStateV2 extends Omit<AskAnalystStateV1, 'version' | 'frame' | 'workspace' | 'program' | 'conversationDelta'> {
+    version: 2;
+    frame: BusinessQuestionFrameV4;
+    workspace: EvidenceWorkspaceV2;
+    program: AnalyticalProgramV2;
+    conversationDelta: AskAnalystConversationDeltaV2;
+    planningMode: AskPlanningModeV1;
+    plannerRevisionCount: number;
+    planningReceipt?: AskAnalystPlanningReceiptV1;
+}
+/** New authoritative state; V2 remains readable for interrupted old runs. */
+export interface AskAnalystStateV3 extends Omit<AskAnalystStateV2, 'version' | 'program'> {
+    version: 3;
+    program: AnalyticalProgramV3;
+}
+export interface AskAnalystPlanningReceiptV1 {
+    version: 1;
+    mode: AskPlanningModeV1;
+    plannerCalls: number;
+    revisionCalls: number;
+    verification: ProgramVerificationFeedbackV1;
+}
+export interface BusinessAnswerV2 extends Omit<BusinessAnswerV1, 'version'> {
+    version: 2;
+    /** Facts and result fingerprint are the only authoritative narrative source. */
+    factBinding: 'validated_result_facts' | 'deterministic_fallback';
+}
+export interface AgentRunDiagnosticReceiptV6 extends Omit<AgentRunDiagnosticReceiptV5, 'version'> {
+    version: 6;
+    planning?: AskAnalystPlanningReceiptV1;
+    /** Role coverage is count-only: raw terms and candidate labels stay Advanced-only. */
+    roleCoverage: Array<{
+        role: EvidenceCandidateRoleV1;
+        candidateCount: number;
+        /** `alternatives` is a clarification state, not a proof of business meaning. */
+        state?: EvidenceRoleCoverageStateV1;
+    }>;
+    /** The exact pre-execution cascade record behind the selected compiler. */
+    cascade: {
+        attempts: Array<Pick<CascadeTierAttemptV1, 'tier' | 'outcome' | 'planFrozen'>>;
+        selectedTier?: AnalyticalCascadeDecisionV1['selectedTier'];
+        stopReason?: string;
+        planFrozen: boolean;
+    };
+    /** Present only for a typed terminal incident; never inferred from prose. */
+    origin?: Pick<AskTerminalIncidentV1, 'boundary' | 'origin' | 'impact'>;
+    connection: {
+        attempted: boolean;
+    };
+    execution: {
+        attempts: number;
+    };
+    /**
+     * Content-safe physical counters. Research roots aggregate server-owned
+     * child execution counters (with durable receipt fallback for older child
+     * records); the root dispatch ledger remains the authority for provider
+     * egress so child spans are never double-counted.
+     */
+    telemetry?: AgentRunTelemetryV1;
+    facts: {
+        factCount: number;
+        resultFingerprint?: string;
+    };
+    safeNextAction: AskDecisionSummaryV2['nextAction'];
+    /** Compact default story; raw spans and candidate lifecycle remain Advanced-only. */
+    story: Array<{
+        stage: 'retrieval' | 'role_coverage' | 'planner' | 'verification' | 'targeted_recovery' | 'cascade' | 'freeze' | 'connection' | 'execution' | 'facts';
+        status: 'completed' | 'skipped' | 'blocked' | 'unavailable';
+        reasonCode: string;
+    }>;
+}
+/**
+ * Additive V7 reader receipt.  V6 remains the detailed, content-free trace
+ * record; V7 projects it into the few decisions an analyst needs first:
+ * whether the question was understood, whether evidence was sufficient, what
+ * the planner/cascade decided, and whether a result was actually narrated.
+ * It deliberately carries counts and enum outcomes only—never prompt text,
+ * SQL, result rows, provider payloads, candidate labels, or member values.
+ */
+export interface AgentRunDiagnosticReceiptV7 extends Omit<AgentRunDiagnosticReceiptV6, 'version'> {
+    version: 7;
+    inspector: {
+        understood: {
+            questionKind: BusinessQuestionFrameV4['kind'];
+            conversationBinding: BusinessQuestionFrameV4['conversation']['binding'];
+            measureCount: number;
+            dimensionCount: number;
+            entityRequested: boolean;
+            hasBoundFilter: boolean;
+        };
+        evidence: {
+            admittedCandidateCount: number;
+            roleCount: number;
+            recoveryAttempted: boolean;
+        };
+        planning: {
+            mode: AskPlanningModeV1;
+            plannerCalls: number;
+            verification: ProgramVerificationFeedbackV1['status'];
+        };
+        route: {
+            selectedTier?: AnalyticalCascadeDecisionV1['selectedTier'];
+            tierAttemptCount: number;
+            planFrozen: boolean;
+            reviewRequired: boolean;
+        };
+        outcome: {
+            connectionAttempted: boolean;
+            executionAttempts: number;
+            factCount: number;
+            narration: 'fact_bound' | 'result_without_facts' | 'not_applicable';
+        };
+    };
+}
+/** New runtime values are V2; V1 values remain readable from old JSON runs. */
+export type AskAnalystState = AskAnalystStateV1 | AskAnalystStateV2 | AskAnalystStateV3;
+export type AnalyticalProgram = AnalyticalProgramV1 | AnalyticalProgramV2 | AnalyticalProgramV3;
+export type BusinessQuestionFrame = BusinessQuestionFrameV3 | BusinessQuestionFrameV4;
+export type BusinessAnswer = BusinessAnswerV1 | BusinessAnswerV2;
 export interface AnalyticalTurnPlanV1 {
     version: 1;
     turnId?: string;
@@ -260,16 +1302,27 @@ export interface AnalyticalTurnAnswerV1 {
  * report partial success instead of collapsing the whole turn to one error.
  */
 export declare function inferAnalyticalTurnKind(question: string): AnalyticalTurnKind;
-type RoleBalancedEvidenceCandidate = {
+export type RoleBalancedEvidenceCandidate = {
     id: string;
     qualifiedId?: string;
     kind?: string;
     semanticObjectType?: string;
     name?: string;
     aliases?: string[];
+    /** Source-authored semantic or physical value type when the snapshot has it. */
+    dataType?: string;
     dimensions?: string[];
     timeGrains?: string[];
     relationshipEvidence?: string[];
+    /**
+     * Host-only runtime-value proof attached to one qualified physical column.
+     * It is intentionally structural here so the retrieval selector can reserve
+     * the field for a current literal without exposing values to a provider.
+     */
+    safeValueEvidence?: Array<{
+        normalizedValue?: string;
+        value?: string;
+    }>;
     relevanceScore?: number;
     exactMatch?: boolean;
     compatibility?: string;
@@ -279,6 +1332,15 @@ type RoleBalancedEvidenceCandidate = {
      * may use the narrowly typed declarations below.
      */
     compatibilityFacts?: string[];
+    /**
+     * A narrowly-scoped host extension derived from the same immutable semantic
+     * capability snapshot.  It is not a lexical synonym or model assertion:
+     * the retriever may mint it only when one MetricFlow-capable grouping field
+     * is uniquely available for the requested business role.  Keeping the
+     * source metric and exact dimension identity here lets routing record the
+     * assumption while the frozen capability still owns execution safety.
+     */
+    sameSnapshotRoleExtension?: SameSnapshotRoleExtensionV1;
     analyticalCapability?: {
         dimensions?: Array<{
             dimensionId?: string;
@@ -288,6 +1350,39 @@ type RoleBalancedEvidenceCandidate = {
         }>;
     };
 };
+export interface SameSnapshotRoleExtensionV1 {
+    version: 1;
+    role: 'categorical_dimension';
+    requestedTerm: string;
+    metricId: string;
+    dimensionId: string;
+    /**
+     * `sole_metricflow_grouping_dimension` is the deliberately narrow
+     * geography recovery path. `exact_metricflow_grouping_dimension` is an
+     * equally snapshot-bound extension for a current-question categorical
+     * phrase whose exact, qualified dimension is declared by the admitted
+     * metric capability. Neither value permits lexical joins or a model-owned
+     * field identity.
+     */
+    basis: 'sole_metricflow_grouping_dimension' | 'exact_metricflow_grouping_dimension';
+}
+/**
+ * Entity/display terms are represented in the historical `dimensions` seed
+ * so ranking plans can retain their requested grain. They must not consume
+ * the separate categorical-dimension admission lane. For example, in "top
+ * customers by product category", `customer` is the entity/rank role while
+ * `product category` is the required categorical grouping role.
+ */
+export declare function categoricalDimensionRequirementTerms(requirements: Pick<AnalyticalRequirementSetV1, 'dimensions' | 'entityTerms' | 'entityDisplayTerms'>): string[];
+/**
+ * A small, typed vocabulary bridge for categorical field identities. It is
+ * intentionally not a general synonym engine: only the field-kind suffix is
+ * canonicalized, while the scoped business noun must still match. Thus
+ * `product category` can bind the snapshot-declared `product_type`, whereas
+ * `customer_type` cannot satisfy it. A bare `category` remains potentially
+ * ambiguous when more than one qualified `*_type` field exists.
+ */
+export declare function categoricalDimensionTermsMatch(left: string, right: string): boolean;
 /**
  * Normalize grammatical aggregation wrappers before they become a plan
  * requirement.  Retrieval/parser output is allowed to retain useful search
@@ -295,10 +1390,13 @@ type RoleBalancedEvidenceCandidate = {
  * or "for each customer" as separate physical measures.  The grouping entity
  * is represented by the dimension/entity roles instead.
  *
- * `order count for each customer` is the common prose form for a count
- * aggregation at customer grain.  Keep the aggregation (`count`) and remove
- * the object noun (`order`) only for that exact grouped construction; a named
- * metric such as `order_value` remains untouched.
+ * `order count for each customer` is the common prose form for the authored
+ * `order_count` semantic measure at customer grain.  Keep that compound
+ * identity intact: reducing it to the generic aggregation `count` makes the
+ * unfiltered `Orders` MetricFlow metric indistinguishable from scoped metrics
+ * such as `Drink Orders` and `Food Orders`.  The grouping entity is still
+ * represented by the dimension/entity roles rather than becoming another
+ * measure.
  */
 export declare function normalizeAnalyticalMeasureTerms(question: string, values: readonly string[], options?: {
     preserveIdentity?: boolean;
@@ -321,8 +1419,23 @@ export declare function buildAnalyticalRequirementSet(input: {
         limit: number;
     }>;
 }): AnalyticalRequirementSetV1;
+/**
+ * Keep account display-key selection separate from common account attributes.
+ * Candidate names originate in dbt/semantic identifiers, so underscores and
+ * dots must be normalized before testing (`account_sentiment_rating` is just
+ * as much an attribute as "Account Sentiment Rating").
+ */
+export declare function hasEntityAttributeTerm(value: string): boolean;
+export declare function isEntityAttributeCandidate(candidate: RoleBalancedEvidenceCandidate): boolean;
 /** Classify the role an already-qualified candidate may fill. */
 export declare function evidenceCandidateRoles(candidate: RoleBalancedEvidenceCandidate): EvidenceCandidateRoleV1[];
+/**
+ * A direct ranking measure is authoritative for metric admission.  Other
+ * retrieved metrics remain visible in the lifecycle receipt, but they cannot
+ * become a second metric choice merely because they are correlated with the
+ * entity phrase in the question.
+ */
+export declare function candidateConflictsWithExplicitRankingMeasure(candidate: RoleBalancedEvidenceCandidate, requirements: AnalyticalRequirementSetV1): boolean;
 /**
  * A categorical dimension may satisfy a requested business role only through
  * its own snapshot-authored declaration. In particular, `location_name` is
@@ -331,7 +1444,7 @@ export declare function evidenceCandidateRoles(candidate: RoleBalancedEvidenceCa
  * declared with the semantic geography role. This protects admission from
  * broad lexical geography expansion while retaining role-balanced recall.
  */
-export declare function candidateMatchesCategoricalDimensionRequirement(candidate: Pick<RoleBalancedEvidenceCandidate, 'compatibilityFacts'>, terms: readonly string[]): boolean;
+export declare function candidateMatchesCategoricalDimensionRequirement(candidate: Pick<RoleBalancedEvidenceCandidate, 'compatibilityFacts' | 'sameSnapshotRoleExtension'>, terms: readonly string[]): boolean;
 /**
  * Keep an internal retrieval result broad while making the provider package
  * role-balanced. Exact/alias matches stay pinned; each requested role gets up
@@ -344,6 +1457,16 @@ export declare function selectRoleBalancedMeaningCandidates<T extends RoleBalanc
     /** Use before any kind cap to reserve exact/required-role cards. */
     pinOnly?: boolean;
 }): T[];
+/**
+ * Build the Ask execution workspace before planner admission.  It is the
+ * only helper that may create the 32-card closure; all later compiler paths
+ * must intersect with this immutable result rather than reaching back into a
+ * broad snapshot.
+ */
+export declare function selectRoleBalancedWorkspaceCandidates<T extends RoleBalancedEvidenceCandidate>(input: {
+    candidates: T[];
+    requirements: AnalyticalRequirementSetV1;
+}): T[];
 export declare function classifyProviderFailure(input: {
     message?: string;
     code?: string;
@@ -577,6 +1700,133 @@ export interface ResearchEvidenceLedgerV2 {
     limitedScope: boolean;
     stoppingReason: ResearchEvidenceLedgerV1['stoppingReason'];
 }
+/**
+ * A local structural lineage observation is not a query result.  This receipt
+ * deliberately carries only bounded counts, opaque fingerprints, and
+ * allowlisted status values: it must never become a place where prompts, SQL,
+ * rows, graph labels, paths, or provider output are persisted.
+ */
+export type ResearchLineageEvidenceStatusV1 = 'completed' | 'missing' | 'ambiguous' | 'stale' | 'truncated' | 'unavailable';
+export type ResearchLineageResolutionV1 = 'exact_id' | 'exact_name' | 'canonical_alias' | 'missing' | 'ambiguous' | 'stale' | 'unavailable';
+export type ResearchLineageNodeTypeV1 = 'source_table' | 'dbt_model' | 'dbt_source' | 'term' | 'block' | 'business_view' | 'metric' | 'dimension' | 'domain' | 'chart' | 'notebook' | 'dashboard' | 'app';
+export interface ResearchLineageEvidenceReceiptV1 {
+    version: 1;
+    evidenceKind: 'lineage_graph';
+    /** Opaque local identity only; no source path or graph content is retained. */
+    snapshotId?: string;
+    snapshotFingerprint?: string;
+    graphFingerprint: string;
+    targetFingerprint: string;
+    status: ResearchLineageEvidenceStatusV1;
+    resolution: ResearchLineageResolutionV1;
+    candidateCount: number;
+    targetType?: ResearchLineageNodeTypeV1;
+    upstreamNodeCount: number;
+    downstreamNodeCount: number;
+    upstreamPathCount: number;
+    downstreamPathCount: number;
+    traversedNodeCount: number;
+    traversedEdgeCount: number;
+    maxDepth: number;
+    maxPaths: number;
+    maxNodes: number;
+    maxEdges: number;
+    truncated: boolean;
+    /** One-way digest of the bounded structural program, never a result digest. */
+    structuralFingerprint?: string;
+    validator: {
+        version: 1;
+        kind: 'structural_dependency';
+        evaluated: boolean;
+        outcome: 'dependency_observed' | 'inconclusive';
+        /** A lineage edge is structural evidence only, never a causal conclusion. */
+        nonCausal: true;
+    };
+    /** This program must not dispatch AI, SQL, warehouse, or repair work. */
+    zeroCallCounters: {
+        providerCalls: 0;
+        sqlExecutions: 0;
+        warehouseExecutions: 0;
+        repairAttempts: 0;
+    };
+}
+export type ResearchEvidenceKindV3 = 'analytical_result' | 'lineage_graph';
+/**
+ * V3 is additive and content-safe.  V1/V2 remain available to old readers,
+ * while V3 distinguishes a receipt-bound analytical result from a bounded
+ * structural lineage observation.  In particular, the lineage variant has no
+ * result fingerprint, execution receipt, row count, SQL, or provider payload.
+ */
+export interface ResearchEvidenceLedgerAnalyticalEntryV3 {
+    version: 3;
+    id: string;
+    branchId: string;
+    evidenceKind: 'analytical_result';
+    status: ResearchLedgerEntryV1['status'];
+    verdict: ResearchEvidenceVerdictV2;
+    hypothesisFingerprint?: string;
+    factIds: string[];
+    counterEvidenceFactIds: string[];
+    receiptFingerprints: string[];
+    resultFingerprint?: string;
+}
+export interface ResearchEvidenceLedgerLineageEntryV3 {
+    version: 3;
+    id: string;
+    branchId: string;
+    evidenceKind: 'lineage_graph';
+    /** The structural program completed even when a target is missing/stale. */
+    status: 'observed' | 'failed' | 'skipped';
+    verdict: ResearchEvidenceVerdictV2;
+    hypothesisFingerprint?: string;
+    factIds: string[];
+    counterEvidenceFactIds: string[];
+    receiptFingerprints: string[];
+    lineageReceipt: ResearchLineageEvidenceReceiptV1;
+}
+export type ResearchEvidenceLedgerEntryV3 = ResearchEvidenceLedgerAnalyticalEntryV3 | ResearchEvidenceLedgerLineageEntryV3;
+export interface ResearchEvidenceLedgerV3 {
+    version: 3;
+    /** One-way root-question identity; V3 does not retain research prose. */
+    rootQuestionFingerprint: string;
+    planId?: string;
+    snapshotId?: string;
+    entries: ResearchEvidenceLedgerEntryV3[];
+    factIds: string[];
+    groundableBranchCount: number;
+    limitedScope: boolean;
+    stoppingReason: ResearchEvidenceLedgerV1['stoppingReason'];
+}
+export interface ResearchEvidenceLedgerAnalyticalInputV3 {
+    kind: 'analytical_result';
+    index: number;
+    entry: ResearchEvidenceLedgerEntryV2;
+    hypothesisFingerprint?: string;
+}
+export interface ResearchEvidenceLedgerLineageInputV3 {
+    kind: 'lineage_graph';
+    index: number;
+    id: string;
+    branchId: string;
+    receipt: ResearchLineageEvidenceReceiptV1;
+    hypothesisFingerprint?: string;
+    /** Omitted means the direct structural program completed normally. */
+    status?: 'observed' | 'failed' | 'skipped';
+}
+/**
+ * Build a mixed V3 ledger without reinterpreting V1/V2.  The legacy ledgers
+ * continue to contain analytical branches only, because their `observed`
+ * state requires an execution/result receipt and would otherwise falsely
+ * represent a graph walk as query execution.
+ */
+export declare function buildResearchEvidenceLedgerV3(input: {
+    rootQuestionFingerprint: string;
+    planId?: string;
+    snapshotId?: string;
+    groundableBranchCount?: number;
+    entries: Array<ResearchEvidenceLedgerAnalyticalInputV3 | ResearchEvidenceLedgerLineageInputV3>;
+    stoppingReason?: ResearchEvidenceLedgerV1['stoppingReason'];
+}): ResearchEvidenceLedgerV3;
 export declare function capResearchBranches<T>(branches: T[], max?: number): T[];
 export declare function buildResearchEvidenceLedger(input: {
     rootQuestion: string;