@duckcodeailabs/dql-agent 1.14.1 → 1.14.3-rc.1

package/dist/analytical-orchestration.d.ts

@@ -95,6 +95,381 @@ export interface AnalyticalCoverageGapV1 {
     planFrozen: boolean;
     nextActions: string[];
 }
+/**
+ * Roles are deliberately independent of a source's trust tier.  A semantic
+ * dimension can be an entity label, a categorical breakdown, or a time axis;
+ * treating all members as interchangeable is what made an Account question
+ * offer owner e-mail and sentiment as substitutes for the account itself.
+ *
+ * Acceptance: CTX-005, CTX-007, AGT-009, AGT-010.
+ */
+export type EvidenceCandidateRoleV1 = 'metric' | 'entity_key' | 'entity_label' | 'categorical_dimension' | 'time_dimension' | 'member' | 'relationship' | 'context';
+/**
+ * A typed, content-safe reading of the analytical requirements in a question.
+ * It is advisory for retrieval/ranking only: the compatibility solver and the
+ * immutable resolved plan still own authorization and execution.
+ */
+export interface AnalyticalRequirementSetV1 {
+    version: 1;
+    measures: string[];
+    dimensions: string[];
+    entityTerms: string[];
+    entityDisplayTerms: string[];
+    memberTerms: string[];
+    /** 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[];
+        direction: 'top' | 'bottom';
+        limit: number;
+        /** True means the reader did not specify a count and DQL assumed 10. */
+        defaultedLimit: boolean;
+    };
+    time?: {
+        role: 'time_axis' | 'time_filter';
+        grain?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+        fiscalPeriod?: string;
+        /** A fiscal token is not executable until a declared calendar binds it. */
+        requiresDeclaredFiscalCalendar: boolean;
+    };
+}
+/**
+ * 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;
+    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;
+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. */
+export interface ContextSourceCoverageV1 {
+    version: 1;
+    source: 'certified' | 'semantic' | 'governed_relational' | 'exploratory' | 'dbt_manifest' | 'runtime_schema' | 'vector' | 'conversation';
+    status: ContextSourceCoverageStatusV1;
+    candidateIds: string[];
+    reason?: string;
+}
+export type AnalyticalCascadeTierV1 = 'certified' | 'semantic' | 'governed_relational' | 'exploratory_sql' | 'clarify_or_gap';
+export type AnalyticalCascadeTierOutcomeV1 = 'executable' | 'ineligible' | 'unavailable' | 'ambiguous' | 'denied';
+/** One immutable, inspectable decision per ordered authority tier. */
+export interface CascadeTierAttemptV1 {
+    version: 1;
+    tier: AnalyticalCascadeTierV1;
+    outcome: AnalyticalCascadeTierOutcomeV1;
+    candidateIds: string[];
+    reason: string;
+    /** A denied or frozen tier must never silently fall through to another one. */
+    planFrozen: boolean;
+}
+/**
+ * A server-owned freeze made after a generated exploratory proposal has passed
+ * the selected snapshot's SQL/context checks and has been bound to one live
+ * execution target. It intentionally contains fingerprints and qualified
+ * candidate identities only: the opaque execution capability and SQL text
+ * never leave the in-memory host boundary.
+ */
+export interface ExploratoryExecutionFreezeV1 {
+    version: 1;
+    selectedTier: 'exploratory_sql';
+    planId: string;
+    planFingerprint: string;
+    snapshotId: string;
+    targetFingerprint: string;
+    sqlFingerprint: string;
+    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' | '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' | 'provider' | 'cascade' | 'run';
+    origin: 'internal_invariant' | 'governance_gate' | 'semantic_compiler' | 'plan_compiler' | '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
+ * downstream presentation/execution layers from silently reinterpreting a
+ * question after route selection.
+ */
+export interface AnalyticalCascadeDecisionV1 {
+    version: 1;
+    requirements: AnalyticalRequirementSetV1;
+    sourceCoverage: ContextSourceCoverageV1[];
+    attempts: CascadeTierAttemptV1[];
+    selectedTier?: Exclude<AnalyticalCascadeTierV1, 'clarify_or_gap'>;
+    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';
+/** Content-free, redacted provider diagnostics safe to persist in a run. */
+export interface ProviderFailureDiagnosticV1 {
+    version: 1;
+    cause: ProviderFailureCauseV1;
+    phase: 'preflight' | 'classification' | 'meaning_resolution' | 'planning' | 'generation' | 'repair' | 'narration' | 'unknown';
+    retryable: boolean;
+    safeAction: 'retry_same_provider' | 'fix_provider_configuration' | 'wait_and_retry' | 'inspect_run' | 'none';
+    httpStatusClass?: '4xx' | '5xx';
+    providerFingerprint?: string;
+    modelFingerprint?: string;
+    baseOriginFingerprint?: string;
+}
+/**
+ * Additive durable diagnostics. V1 and V2 intentionally remain the compact
+ * compatibility envelopes used by older persisted runs.
+ */
+export interface AgentRunDiagnosticReceiptV3 {
+    version: 3;
+    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;
+}
 export interface AnalyticalTurnPlanV1 {
     version: 1;
     turnId?: string;
@@ -139,6 +514,156 @@ export interface AnalyticalTurnAnswerV1 {
  * report partial success instead of collapsing the whole turn to one error.
  */
 export declare function inferAnalyticalTurnKind(question: string): AnalyticalTurnKind;
+export type RoleBalancedEvidenceCandidate = {
+    id: string;
+    qualifiedId?: string;
+    kind?: string;
+    semanticObjectType?: string;
+    name?: string;
+    aliases?: string[];
+    dimensions?: string[];
+    timeGrains?: string[];
+    relationshipEvidence?: string[];
+    relevanceScore?: number;
+    exactMatch?: boolean;
+    compatibility?: string;
+    /**
+     * Snapshot-authored compatibility declarations. These are deliberately not
+     * folded into general lexical identity: only the categorical-dimension lane
+     * 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;
+        }>;
+        timeDimensions?: Array<{
+            dimensionId?: string;
+        }>;
+    };
+};
+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
+ * phrases, but an immutable plan must never treat "count for each customer"
+ * 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.
+ */
+export declare function normalizeAnalyticalMeasureTerms(question: string, values: readonly string[], options?: {
+    preserveIdentity?: boolean;
+}): string[];
+/**
+ * Parse only stable analytical roles. This is purposefully narrower than an
+ * LLM interpretation: unknown business phrases remain available to the normal
+ * bounded meaning resolver instead of being guessed here.
+ */
+export declare function buildAnalyticalRequirementSet(input: {
+    question: string;
+    parsedIntent?: Partial<{
+        measures: string[];
+        dimensions: string[];
+        filters: Array<{
+            field: string;
+            value: string;
+        }>;
+        timeGrain: string;
+        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
+ * not a synonym for `region`: it can fill a region lane only when metadata
+ * explicitly says `alternative-for:region`, or when the dimension itself is
+ * 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' | '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
+ * to two candidates before relevance fills remaining cards.
+ */
+export declare function selectRoleBalancedMeaningCandidates<T extends RoleBalancedEvidenceCandidate>(input: {
+    candidates: T[];
+    requirements: AnalyticalRequirementSetV1;
+    maxCandidates?: number;
+    /** Use before any kind cap to reserve exact/required-role cards. */
+    pinOnly?: boolean;
+}): T[];
+export declare function classifyProviderFailure(input: {
+    message?: string;
+    code?: string;
+    phase?: ProviderFailureDiagnosticV1['phase'];
+    providerFingerprint?: string;
+    modelFingerprint?: string;
+    baseOriginFingerprint?: string;
+}): ProviderFailureDiagnosticV1;
+export declare function buildAnalyticalCascadeDecision(input: Omit<AnalyticalCascadeDecisionV1, 'version'>): AnalyticalCascadeDecisionV1;
 export declare function splitAnalyticalTasks(question: string): string[];
 export declare function buildAnalyticalTaskGraph(input: {
     question: string;
@@ -317,6 +842,52 @@ export interface ResearchEvidenceLedgerV1 {
     factIds: string[];
     stoppingReason: 'completed' | 'budget' | 'insufficient_evidence' | 'blocked' | 'not_started';
 }
+export type ResearchEvidenceVerdictV2 = 'supported' | 'contradicted' | 'inconclusive' | 'failed' | 'skipped';
+/** Deterministic observation classes; none infer causality from returned rows. */
+export type ResearchEvidenceValidatorKindV2 = 'trend' | 'comparison' | 'contributor' | 'anomaly' | 'freshness' | 'counter_evidence';
+export interface ResearchEvidenceValidatorV2 {
+    version: 1;
+    kind: ResearchEvidenceValidatorKindV2;
+    /** True only when a deterministic, receipt-bound predicate was evaluated. */
+    evaluated: boolean;
+    /** Optional non-causal observation result. Absent means inconclusive. */
+    outcome?: 'supports_observation' | 'contradicts_observation';
+    receiptFingerprints: string[];
+}
+export interface ResearchHypothesisPlanEntryV2 {
+    id: string;
+    statement: string;
+    expectation: string;
+    targetId: string;
+    validatorKind: ResearchEvidenceValidatorKindV2;
+}
+export interface ResearchHypothesisPlanV2 {
+    version: 2;
+    hypotheses: ResearchHypothesisPlanEntryV2[];
+    limitedScope: boolean;
+}
+/**
+ * V2 makes the difference between a returned row and an evaluated hypothesis
+ * explicit. A branch may be observed yet inconclusive; it is never promoted to
+ * a causal claim merely because it executed.
+ */
+export interface ResearchEvidenceLedgerEntryV2 extends ResearchLedgerEntryV1 {
+    verdict: ResearchEvidenceVerdictV2;
+    hypothesis?: string;
+    validator?: ResearchEvidenceValidatorV2;
+    counterEvidenceFactIds: string[];
+}
+export interface ResearchEvidenceLedgerV2 {
+    version: 2;
+    rootQuestion: string;
+    planId?: string;
+    snapshotId?: string;
+    entries: ResearchEvidenceLedgerEntryV2[];
+    factIds: string[];
+    groundableBranchCount: number;
+    limitedScope: boolean;
+    stoppingReason: ResearchEvidenceLedgerV1['stoppingReason'];
+}
 export declare function capResearchBranches<T>(branches: T[], max?: number): T[];
 export declare function buildResearchEvidenceLedger(input: {
     rootQuestion: string;
@@ -325,6 +896,47 @@ export declare function buildResearchEvidenceLedger(input: {
     entries: ResearchLedgerEntryV1[];
     stoppingReason?: ResearchEvidenceLedgerV1['stoppingReason'];
 }): ResearchEvidenceLedgerV1;
+export declare function buildResearchEvidenceLedgerV2(input: {
+    rootQuestion: string;
+    planId?: string;
+    snapshotId?: string;
+    /** Number of catalog-grounded branches admitted before execution. A runtime
+     * failure must not be misreported as if the catalog had fewer hypotheses. */
+    groundableBranchCount?: number;
+    entries: Array<ResearchLedgerEntryV1 & {
+        verdict?: ResearchEvidenceVerdictV2;
+        hypothesis?: string;
+        validator?: ResearchEvidenceValidatorV2;
+        counterEvidenceFactIds?: string[];
+    }>;
+    stoppingReason?: ResearchEvidenceLedgerV1['stoppingReason'];
+}): ResearchEvidenceLedgerV2;
+/**
+ * Normalise a hypothesis plan into the bounded research contract. The caller
+ * may supply fewer than three grounded hypotheses; that is retained honestly as
+ * limited scope rather than padded with invented joins or explanations.
+ */
+export declare function buildResearchHypothesisPlanV2(input: {
+    hypotheses: Array<{
+        id?: string;
+        statement: string;
+        expectation: string;
+        targetId: string;
+        validatorKind?: ResearchEvidenceValidatorKindV2;
+    }>;
+}): ResearchHypothesisPlanV2;
+/** Map an action/expectation to a deterministic observation class only. */
+export declare function inferResearchValidatorKind(statement: string, expectation?: string): ResearchEvidenceValidatorKindV2;
+/**
+ * A verdict is promoted only from a validator that evaluated a deterministic
+ * observation against a branch receipt. Rows by themselves stay inconclusive;
+ * causal statements are never supported by this helper.
+ */
+export declare function researchVerdictFromValidatedObservation(input: {
+    status: ResearchLedgerEntryV1['status'];
+    requestedVerdict?: ResearchEvidenceVerdictV2;
+    validator?: ResearchEvidenceValidatorV2;
+}): ResearchEvidenceVerdictV2;
 /** The only accepted host-side execution identity is a SHA-256 fingerprint. */
 export declare function normalizeAnalyticalExecutionFingerprint(value: unknown): string | undefined;
 /**
@@ -333,4 +945,5 @@ export declare function normalizeAnalyticalExecutionFingerprint(value: unknown):
  */
 export declare function normalizeAnalyticalExecutionReceipt(value: unknown): DqlArtifactExecutionReceipt | undefined;
 export declare function buildCoverageGap(input: Omit<AnalyticalCoverageGapV1, 'version'>): AnalyticalCoverageGapV1;
+export {};
 //# sourceMappingURL=analytical-orchestration.d.ts.map