@duckcodeailabs/dql-agent 1.9.4 → 1.10.0

package/dist/research-governance.js

@@ -0,0 +1,68 @@
+/** Bounded, receipt-backed research built from typed deltas over one root plan. */
+import { deriveResolvedAnalyticalPlan, } from './resolved-analytical-plan.js';
+import { RESEARCH_BUDGET } from './research-loop.js';
+export class ResearchBudgetExceededError extends Error {
+    counter;
+    code = 'RESEARCH_BUDGET_EXCEEDED';
+    constructor(counter) {
+        super(`Research budget exceeded: ${counter}.`);
+        this.counter = counter;
+        this.name = 'ResearchBudgetExceededError';
+    }
+}
+export class ResearchBudgetController {
+    budget;
+    now;
+    used = { plannerCalls: 0, sqlExecutions: 0, repairs: 0, narratorCalls: 0 };
+    startedAt;
+    constructor(budget = RESEARCH_BUDGET, now = Date.now) {
+        this.budget = budget;
+        this.now = now;
+        this.startedAt = now();
+    }
+    consume(counter) {
+        this.assertWithinDeadline();
+        const next = this.used[counter] + 1;
+        if (next > this.budget[counter])
+            throw new ResearchBudgetExceededError(counter);
+        this.used[counter] = next;
+    }
+    assertWithinDeadline() {
+        if (this.now() - this.startedAt > this.budget.wallClockMs) {
+            throw new ResearchBudgetExceededError('wallClockMs');
+        }
+    }
+    snapshot() {
+        return Object.freeze({ ...this.used, elapsedMs: Math.max(0, this.now() - this.startedAt) });
+    }
+}
+export function buildTypedResearchBranches(root, inputs) {
+    return inputs.slice(0, RESEARCH_BUDGET.sqlExecutions).map((input) => ({
+        id: input.id,
+        label: input.label,
+        plan: deriveResolvedAnalyticalPlan(root, input.delta),
+        evidenceIds: [...new Set(input.evidenceIds)].sort(),
+    }));
+}
+/** Every numeric claim needs a successful execution and a result fingerprint. */
+export function gateResearchConclusion(observations) {
+    const supported = [];
+    const unsupported = [];
+    for (const observation of observations) {
+        const hasReceipt = observation.status === 'executed'
+            && Boolean(observation.executionReceipt?.resultFingerprint
+                ?? observation.executionReceipt?.result?.resultFingerprint);
+        for (const claim of observation.numericClaims)
+            (hasReceipt ? supported : unsupported).push(claim);
+    }
+    const status = unsupported.length === 0 ? 'complete' : 'partial';
+    return {
+        status,
+        supportedClaimIds: [...new Set(supported)].sort(),
+        unsupportedClaimIds: [...new Set(unsupported)].sort(),
+        message: status === 'complete'
+            ? 'Every numeric research claim is backed by a successful execution receipt.'
+            : 'Research evidence is partial; unsupported numeric claims cannot be presented as a completed causal conclusion.',
+    };
+}
+//# sourceMappingURL=research-governance.js.map

package/dist/research-governance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-governance.js","sourceRoot":"","sources":["../src/research-governance.ts"],"names":[],"mappings":"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"}

package/dist/research-loop.d.ts

@@ -14,6 +14,7 @@ import { type AgentAction } from './intent-controller.js';
 import type { MetadataAgentIntent } from './metadata/catalog.js';
 import type { KGNode } from './kg/types.js';
 import type { PlanBlock } from './app-planner.js';
+import type { ResolvedAnalyticalPlan } from './resolved-analytical-plan.js';
 /** One ReAct step: a thought, the asset-bound action, and what observing it tells us. */
 export interface ResearchStep {
     thought: string;
@@ -42,7 +43,18 @@ export interface ResearchPlan {
     sources: string[];
     /** True when the question is answerable directly (single step, no research needed). */
     done: boolean;
+    /** Root analytical contract reused by every research branch. */
+    rootPlanId?: string;
+    budget: ResearchBudget;
 }
+export interface ResearchBudget {
+    plannerCalls: 1;
+    sqlExecutions: 6;
+    repairs: 1;
+    narratorCalls: 1;
+    wallClockMs: 120_000;
+}
+export declare const RESEARCH_BUDGET: ResearchBudget;
 /**
  * Plan how to handle a research / follow-up question. Returns the decision plus a
  * grounded plan: a direct answer, a multi-step research trace, or a follow-up with
@@ -60,5 +72,7 @@ export declare function planResearch(input: {
     }>;
     /** The user explicitly asked to research/dig deeper — don't collapse to a single-step answer. */
     forceInvestigate?: boolean;
+    /** Authoritative root plan. When present, research never re-matches meaning. */
+    rootPlan?: ResolvedAnalyticalPlan;
 }): Promise<ResearchPlan>;
 //# sourceMappingURL=research-loop.d.ts.map

package/dist/research-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research-loop.d.ts","sourceRoot":"","sources":["../src/research-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACN,IAAI,EAAE,eAAe,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;QACxG,uEAAuE;QACvE,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,kDAAkD;IAClD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uFAAuF;IACvF,IAAI,EAAE,OAAO,CAAC;CACf;AA8CD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,YAAY,CAAC,CA+IxB"}
+{"version":3,"file":"research-loop.d.ts","sourceRoot":"","sources":["../src/research-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACN,IAAI,EAAE,eAAe,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,CAAC;QACxG,uEAAuE;QACvE,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,kDAAkD;IAClD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uFAAuF;IACvF,IAAI,EAAE,OAAO,CAAC;IACd,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,CAAC,CAAC;IAChB,aAAa,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,CAAC,CAAC;IACX,aAAa,EAAE,CAAC,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,eAAO,MAAM,eAAe,EAAE,cAM7B,CAAC;AA8CF;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC,GAAG,OAAO,CAAC,YAAY,CAAC,CAiLxB"}

package/dist/research-loop.js

@@ -12,6 +12,13 @@
  */
 import { decideAgentAction } from './intent-controller.js';
 import { matchSemanticMetric } from './metadata/metric-match.js';
+export const RESEARCH_BUDGET = {
+    plannerCalls: 1,
+    sqlExecutions: 6,
+    repairs: 1,
+    narratorCalls: 1,
+    wallClockMs: 120_000,
+};
 const TIME_DIM_RE = /(_at$|_date$|_time$|_ts$|^date$|^month$|^week$|^day$|ordered_at|created)/i;
 function humanize(name) {
     return name.replace(/[_.]+/g, ' ').replace(/\s+/g, ' ').trim();
@@ -67,23 +74,40 @@ export async function planResearch(input) {
         .filter((ref) => Boolean(ref))
         .flatMap((ref) => [ref, ref.split('.').pop() ?? ref]));
     const backedMetrics = input.metrics.filter((m) => backedNames.has(m.name.toLowerCase()) || backedNames.has(m.name.toLowerCase().split('.').pop() ?? ''));
-    const match = (backedMetrics.length > 0 ? await matchSemanticMetric(input.question, backedMetrics).catch(() => null) : null) ??
-        (await matchSemanticMetric(input.question, input.metrics).catch(() => null));
-    const metricName = match?.metric.name;
+    const rootMetric = input.rootPlan?.executionId
+        ? input.metrics.find((metric) => nodeIdentities(metric).includes(input.rootPlan.executionId))
+        : undefined;
+    const match = input.rootPlan
+        ? null
+        : (backedMetrics.length > 0 ? await matchSemanticMetric(input.question, backedMetrics).catch(() => null) : null) ??
+            (await matchSemanticMetric(input.question, input.metrics).catch(() => null));
+    const metricName = rootMetric?.name ?? match?.metric.name;
     const metricBlocks = blocksForMetric(input.blocks, metricName);
-    const decision = decideAgentAction({
-        question: input.question,
-        intent: input.intent ?? 'definition_lookup',
-        signals: {
-            metricScore: match?.score,
-            // Derive from the actual match, not a flat 0.85 that asserts certainty just
-            // because a block exists (that silently downgraded forced research to a single answer).
-            certifiedScore: metricBlocks.length > 0 ? (match?.score ?? undefined) : undefined,
-            hasRetrieval: input.metrics.length > 0 || input.blocks.length > 0,
-        },
-        isFollowUp: input.isFollowUp,
-        history: input.history,
-    });
+    const decision = input.rootPlan
+        ? {
+            action: input.rootPlan.capability === 'blocked'
+                ? 'clarify'
+                : (input.forceInvestigate || input.rootPlan.questionType === 'diagnosis' || input.rootPlan.questionType === 'research')
+                    ? 'investigate'
+                    : 'answer',
+            confidence: input.rootPlan.confidence === 'high' ? 0.9 : input.rootPlan.confidence === 'medium' ? 0.72 : 0.45,
+            reason: `Research reuses resolved plan ${input.rootPlan.planId}.`,
+            followsUp: Boolean(input.isFollowUp),
+            ...(input.rootPlan.clarification ? { clarifyingQuestion: input.rootPlan.clarification } : {}),
+        }
+        : decideAgentAction({
+            question: input.question,
+            intent: input.intent ?? 'definition_lookup',
+            signals: {
+                metricScore: match?.score,
+                // Derive from the actual match, not a flat 0.85 that asserts certainty just
+                // because a block exists (that silently downgraded forced research to a single answer).
+                certifiedScore: metricBlocks.length > 0 ? (match?.score ?? undefined) : undefined,
+                hasRetrieval: input.metrics.length > 0 || input.blocks.length > 0,
+            },
+            isFollowUp: input.isFollowUp,
+            history: input.history,
+        });
     // When the user explicitly forced research, don't collapse to the single-step "answer"
     // path — investigate. A SOFT "nothing matched cleanly" clarify also becomes an
     // investigation here: the user deliberately asked to research, so we dig rather than
@@ -95,7 +119,13 @@ export async function planResearch(input) {
         ? 'investigate'
         : decision.action;
     const sources = new Set();
-    if (metricName)
+    if (input.rootPlan) {
+        for (const id of input.rootPlan.selectedConceptIds)
+            sources.add(id);
+        if (input.rootPlan.executionId)
+            sources.add(input.rootPlan.executionId);
+    }
+    else if (metricName)
         sources.add(metricName);
     for (const b of metricBlocks)
         sources.add(b.name);
@@ -112,6 +142,8 @@ export async function planResearch(input) {
                 }],
             sources: Array.from(sources),
             done: false,
+            rootPlanId: input.rootPlan?.rootPlanId ?? input.rootPlan?.planId,
+            budget: RESEARCH_BUDGET,
         };
     }
     // ── clarify: ask before researching, with concrete options. ──────────────────
@@ -125,20 +157,25 @@ export async function planResearch(input) {
             followUp,
             sources: Array.from(sources),
             done: false,
+            rootPlanId: input.rootPlan?.rootPlanId ?? input.rootPlan?.planId,
+            budget: RESEARCH_BUDGET,
         };
     }
     // ── investigate: a grounded, multi-step ReAct research trace. ────────────────
     if (action === 'investigate') {
         const steps = [];
         const label = metricName ? humanize(metricName) : humanize(input.question);
+        const metricTarget = input.rootPlan?.executionId ?? metricName;
         if (metricName) {
             steps.push({
                 thought: `Establish the baseline for ${label}.`,
-                action: { kind: 'lookup_metric', target: metricName },
+                action: { kind: 'lookup_metric', target: metricTarget },
                 expectation: `The current ${label} value to reason from.`,
             });
         }
-        const timeDim = timeDimensionOf(metricBlocks);
+        const timeDim = input.rootPlan?.query.dimensions.find((binding) => /date|time|month|week|year/i.test(binding.requested))?.qualifiedId
+            ?? (input.rootPlan?.query.timeGrain || input.rootPlan?.query.timeRange ? 'resolved-plan-time' : undefined)
+            ?? timeDimensionOf(metricBlocks);
         if (timeDim) {
             steps.push({
                 thought: `See how ${label} moved over time to locate the change.`,
@@ -146,8 +183,12 @@ export async function planResearch(input) {
                 expectation: `When ${label} shifted, and by how much.`,
             });
         }
-        const dims = (requestedDimensions(input.question).filter((d) => !TIME_DIM_RE.test(d))
-            .filter((d) => categoricalDimensionsOf(metricBlocks).includes(d)));
+        const dims = input.rootPlan
+            ? input.rootPlan.query.dimensions
+                .filter((binding) => !TIME_DIM_RE.test(binding.requested))
+                .map((binding) => binding.qualifiedId ?? binding.requested)
+            : requestedDimensions(input.question).filter((d) => !TIME_DIM_RE.test(d))
+                .filter((d) => categoricalDimensionsOf(metricBlocks).includes(d));
         const breakdownDim = dims[0] ?? categoricalDimensionsOf(metricBlocks)[0];
         if (breakdownDim) {
             steps.push({
@@ -159,7 +200,7 @@ export async function planResearch(input) {
         else if (metricName) {
             steps.push({
                 thought: `No breakdown dimension is certified yet — check lineage for drivers.`,
-                action: { kind: 'check_lineage', target: metricName },
+                action: { kind: 'check_lineage', target: metricTarget },
                 expectation: `Upstream models/metrics that feed ${label}.`,
             });
         }
@@ -170,6 +211,8 @@ export async function planResearch(input) {
             steps,
             sources: Array.from(sources),
             done: false,
+            rootPlanId: input.rootPlan?.rootPlanId ?? input.rootPlan?.planId,
+            budget: RESEARCH_BUDGET,
         };
     }
     // ── answer: a single grounded step. ──────────────────────────────────────────
@@ -181,7 +224,7 @@ export async function planResearch(input) {
         }
         : {
             thought: metricName ? `The governed metric answers this directly.` : `Answer from the catalog.`,
-            action: { kind: 'lookup_metric', target: metricName ?? humanize(input.question) },
+            action: { kind: 'lookup_metric', target: input.rootPlan?.executionId ?? metricName ?? humanize(input.question) },
             expectation: metricName ? `The governed ${humanize(metricName)} value.` : `A grounded answer.`,
         };
     return {
@@ -191,8 +234,19 @@ export async function planResearch(input) {
         steps: [answerStep],
         sources: Array.from(sources),
         done: true,
+        rootPlanId: input.rootPlan?.rootPlanId ?? input.rootPlan?.planId,
+        budget: RESEARCH_BUDGET,
     };
 }
+function nodeIdentities(node) {
+    const payload = node.payload ?? {};
+    return [
+        node.nodeId,
+        typeof payload.qualifiedId === 'string' ? payload.qualifiedId : undefined,
+        typeof payload.sourceNativeId === 'string' ? payload.sourceNativeId : undefined,
+        ...(Array.isArray(payload.aliases) ? payload.aliases.filter((value) => typeof value === 'string') : []),
+    ].filter((value) => Boolean(value));
+}
 /**
  * Build a follow-up that offers REAL options: nearby metrics to disambiguate, or the
  * certified breakdown dimensions to pick from — never an open-ended "tell me more".

package/dist/research-loop.js.map

@@ -1 +1 @@
-{"version":3,"file":"research-loop.js","sourceRoot":"","sources":["../src/research-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"research-loop.js","sourceRoot":"","sources":["../src/research-loop.ts"],"names":[],"mappings":"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"}

package/dist/resolved-analytical-plan.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Immutable, snapshot-bound analytical plan shared by every downstream route.
+ * The router emits it authoritatively by default. Shadow mode remains the
+ * bounded route-level rollback switch while integration verification closes.
+ *
+ * Acceptance: AGT-013, API-006.
+ */
+import type { KnowledgeLens } from './domain-context.js';
+import type { AgentEvidenceCandidate, AgentRetrievalEvidence, MeaningExecutionRoute, MeaningQuestionType, MeaningResolution } from './meaning-resolution.js';
+export type ResolvedPlanCapability = 'certified_execution' | 'semantic_execution' | 'governed_relational' | 'bounded_exploration' | 'blocked';
+export interface ResolvedPlanMemberBinding {
+    requested: string;
+    qualifiedId?: string;
+    aggregation?: string;
+    status: 'resolved' | 'ambiguous' | 'unresolved';
+    candidateIds: string[];
+}
+export interface ResolvedPlanCompatibilityProof {
+    candidateId: string;
+    compatibility: AgentEvidenceCandidate['compatibility'];
+    facts: string[];
+}
+export interface ResolvedAnalyticalPlan {
+    schemaVersion: 1;
+    mode: 'shadow' | 'authoritative';
+    planId: string;
+    fingerprint: string;
+    parentPlanId?: string;
+    rootPlanId?: string;
+    revision: number;
+    snapshotId: string;
+    sourceFingerprint?: string;
+    question: string;
+    interpretedQuestion: string;
+    questionType: MeaningQuestionType;
+    confidence: MeaningResolution['confidence'];
+    selectedConceptIds: string[];
+    executionId?: string;
+    recommendedRoute: MeaningExecutionRoute;
+    capability: ResolvedPlanCapability;
+    query: {
+        measures: ResolvedPlanMemberBinding[];
+        dimensions: ResolvedPlanMemberBinding[];
+        filters: Array<{
+            field: string;
+            value: string;
+            binding: ResolvedPlanMemberBinding;
+        }>;
+        timeRange?: string;
+        timeBounds?: {
+            expression: string;
+            startInclusive: string;
+            endExclusive: string;
+            timeZone: 'UTC';
+        };
+        timeGrain?: string;
+        order?: 'asc' | 'desc';
+        limit?: number;
+    };
+    entityGrain?: string;
+    sourceRelationIds: string[];
+    relationshipPathIds: string[];
+    compatibilityProof: ResolvedPlanCompatibilityProof[];
+    outputContract: {
+        measures: string[];
+        dimensions: string[];
+        timeGrain?: string;
+    };
+    evidenceIds: string[];
+    rejectedCandidates: Array<{
+        id: string;
+        reason: string;
+    }>;
+    missingInformation: string[];
+    clarification?: string;
+    knowledgeLens?: KnowledgeLens;
+}
+export interface BuildResolvedAnalyticalPlanInput {
+    question: string;
+    resolution: MeaningResolution;
+    evidence: AgentRetrievalEvidence;
+    candidates: AgentEvidenceCandidate[];
+    mode?: ResolvedAnalyticalPlan['mode'];
+    /** Clock captured once by the router; used only to resolve relative time. */
+    referenceTime?: Date;
+}
+export interface ResolvedAnalyticalPlanDelta {
+    question: string;
+    measures?: ResolvedPlanMemberBinding[];
+    dimensions?: ResolvedPlanMemberBinding[];
+    filters?: ResolvedAnalyticalPlan['query']['filters'];
+    selectedResultFilter?: {
+        binding: ResolvedPlanMemberBinding;
+        value: string;
+        sourceTurnId: string;
+    };
+    timeRange?: string;
+    timeGrain?: string;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    referenceTime?: Date;
+}
+export declare function buildResolvedAnalyticalPlan(input: BuildResolvedAnalyticalPlanInput): ResolvedAnalyticalPlan;
+/**
+ * Apply an explicitly typed follow-up delta. No prose, prior SQL, or answer text
+ * is inspected; every carried member remains a qualified binding from the root.
+ * Acceptance: CTX-003, AGT-013, AGT-016.
+ */
+export declare function deriveResolvedAnalyticalPlan(parent: ResolvedAnalyticalPlan, delta: ResolvedAnalyticalPlanDelta): ResolvedAnalyticalPlan;
+/** Resolve common analytical ranges once so no executor reinterprets "last month". */
+export declare function resolvePlanTimeRange(expression: string, referenceTime: Date): ResolvedAnalyticalPlan['query']['timeBounds'] | undefined;
+//# sourceMappingURL=resolved-analytical-plan.d.ts.map

package/dist/resolved-analytical-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolved-analytical-plan.d.ts","sourceRoot":"","sources":["../src/resolved-analytical-plan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,sBAAsB,GAC9B,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,GACrB,SAAS,CAAC;AAEd,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,YAAY,CAAC;IAChD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,8BAA8B;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACvD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,CAAC,CAAC;IACjB,IAAI,EAAE,QAAQ,GAAG,eAAe,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,mBAAmB,CAAC;IAClC,UAAU,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC5C,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,UAAU,EAAE,sBAAsB,CAAC;IACnC,KAAK,EAAE;QACL,QAAQ,EAAE,yBAAyB,EAAE,CAAC;QACtC,UAAU,EAAE,yBAAyB,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;YACd,KAAK,EAAE,MAAM,CAAC;YACd,OAAO,EAAE,yBAAyB,CAAC;SACpC,CAAC,CAAC;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE;YACX,UAAU,EAAE,MAAM,CAAC;YACnB,cAAc,EAAE,MAAM,CAAC;YACvB,YAAY,EAAE,MAAM,CAAC;YACrB,QAAQ,EAAE,KAAK,CAAC;SACjB,CAAC;QACF,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,kBAAkB,EAAE,8BAA8B,EAAE,CAAC;IACrD,cAAc,EAAE;QACd,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kBAAkB,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC,IAAI,CAAC,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACtC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACvC,UAAU,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACzC,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC;IACrD,oBAAoB,CAAC,EAAE;QACrB,OAAO,EAAE,yBAAyB,CAAC;QACnC,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,gCAAgC,GACtC,sBAAsB,CA6FxB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,2BAA2B,GACjC,sBAAsB,CAwDxB;AA2GD,sFAAsF;AACtF,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,IAAI,GAClB,sBAAsB,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,SAAS,CA4B3D"}