@duckcodeailabs/dql-agent 1.13.5 → 1.14.1

package/dist/agentic/research/hypothesis.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Hypothesis-driven research state.
+ *
+ * `planResearch` emits a fixed three-step template — baseline, compare over
+ * time, break down — always bound to ONE metric, with dimensions scraped by
+ * `/\bby\s+([a-z_][a-z0-9_]*)/gi`. Its own comment says it is deterministic and
+ * offline, `RESEARCH_BUDGET.plannerCalls` is TYPED as the literal `1`, and the
+ * branches it fans out are frozen against the root plan.
+ *
+ * The consequence is the reported one: research answers a question instead of
+ * investigating it. A template cannot be wrong, so it never notices that its
+ * first finding ruled the premise out, and it never follows the thread that
+ * finding opened.
+ *
+ * What is missing is not more steps. It is the edge from an OBSERVATION back to
+ * the plan: a finding has to be able to refute a hypothesis, sharpen it, or
+ * spawn a new one. This module owns that edge as a pure state machine, so the
+ * part that decides what to investigate next is testable without a provider,
+ * a warehouse, or a clock.
+ */
+export type HypothesisStatus = 'open' | 'supported' | 'refuted' | 'inconclusive';
+export interface Hypothesis {
+    id: string;
+    /** A falsifiable statement, not a task ("revenue fell because enterprise churned"). */
+    statement: string;
+    /** Belief before any evidence, 0..1. Drives which hypothesis is tested next. */
+    priorConfidence: number;
+    status: HypothesisStatus;
+    /** Ids of observations that bear on this hypothesis. */
+    evidenceIds: string[];
+    /** Which hypothesis this was spawned from, when a finding opened a new thread. */
+    parentId?: string;
+    /** Why it reached its current status — carried into the final narrative. */
+    rationale?: string;
+}
+/** What one investigation step established. */
+export interface HypothesisFinding {
+    id: string;
+    hypothesisId: string;
+    /**
+     * Whether the finding supports, refutes, or fails to settle the hypothesis.
+     * `inconclusive` is a real outcome, not a failure: an executed query that
+     * simply does not discriminate must not be recorded as support.
+     */
+    verdict: 'supports' | 'refutes' | 'inconclusive';
+    summary: string;
+    /** Confidence the finding itself carries, 0..1. */
+    strength: number;
+    /**
+     * A hypothesis this finding suggests testing next. The edge that a frozen
+     * branch plan cannot express.
+     */
+    spawns?: Array<{
+        statement: string;
+        priorConfidence: number;
+    }>;
+}
+export interface ResearchState {
+    rootQuestion: string;
+    hypotheses: Hypothesis[];
+    findings: HypothesisFinding[];
+    hopsUsed: number;
+}
+export interface ResearchLimits {
+    /** Total investigation steps. Bounded: an unbounded loop is an outage. */
+    maxHops: number;
+    /** Ceiling on live hypotheses, so spawning cannot fan out without end. */
+    maxOpenHypotheses: number;
+}
+export declare const DEFAULT_RESEARCH_LIMITS: ResearchLimits;
+export declare function createResearchState(rootQuestion: string, initial: Array<Omit<Hypothesis, 'status' | 'evidenceIds'>>): ResearchState;
+/**
+ * Which hypothesis to test next: the open one with the highest prior.
+ *
+ * Returns `undefined` when the budget is spent or nothing is open, which is how
+ * the caller learns to stop. Deliberately not "cheapest first" — the point of
+ * research is to resolve the question, and testing a likely explanation first is
+ * what lets a later hop be skipped entirely.
+ */
+export declare function nextHypothesis(state: ResearchState, limits?: ResearchLimits): Hypothesis | undefined;
+/**
+ * Fold a finding into the state — the replan edge.
+ *
+ * A refutation CLOSES its hypothesis rather than leaving it open to be retried:
+ * the template's failure was continuing to elaborate a premise its own evidence
+ * had already ruled out.
+ *
+ * Spawned hypotheses are admitted only while there is room, and never duplicate
+ * an existing statement — a loop that keeps re-proposing the same idea burns the
+ * whole hop budget without learning anything.
+ */
+export declare function applyFinding(state: ResearchState, finding: HypothesisFinding, limits?: ResearchLimits): ResearchState;
+export interface ResearchConclusion {
+    /** Hypotheses the evidence actually settled, strongest first. */
+    supported: Hypothesis[];
+    refuted: Hypothesis[];
+    /** Open or inconclusive — what the investigation could NOT establish. */
+    unresolved: Hypothesis[];
+    /** True when the hop budget ran out with hypotheses still open. */
+    exhausted: boolean;
+}
+/**
+ * Summarise what the investigation established.
+ *
+ * `unresolved` is reported as prominently as `supported` on purpose. A research
+ * answer that lists only what it confirmed reads as a complete explanation, and
+ * the one thing a bounded investigation cannot honestly claim is completeness.
+ */
+export declare function concludeResearch(state: ResearchState, limits?: ResearchLimits): ResearchConclusion;
+//# sourceMappingURL=hypothesis.d.ts.map

package/dist/agentic/research/hypothesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hypothesis.d.ts","sourceRoot":"","sources":["../../../src/agentic/research/hypothesis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,cAAc,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,gBAAgB,CAAC;IACzB,wDAAwD;IACxD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,cAAc,CAAC;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,uBAAuB,EAAE,cAGrC,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,aAAa,CAAC,CAAC,GAAG,aAAa,CAOnI;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,GAAE,cAAwC,GAAG,UAAU,GAAG,SAAS,CAK7H;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,GAAE,cAAwC,GAC/C,aAAa,CAuCf;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,yEAAyE;IACzE,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,GAAE,cAAwC,GAAG,kBAAkB,CAU3H"}

package/dist/agentic/research/hypothesis.js

@@ -0,0 +1,125 @@
+/**
+ * Hypothesis-driven research state.
+ *
+ * `planResearch` emits a fixed three-step template — baseline, compare over
+ * time, break down — always bound to ONE metric, with dimensions scraped by
+ * `/\bby\s+([a-z_][a-z0-9_]*)/gi`. Its own comment says it is deterministic and
+ * offline, `RESEARCH_BUDGET.plannerCalls` is TYPED as the literal `1`, and the
+ * branches it fans out are frozen against the root plan.
+ *
+ * The consequence is the reported one: research answers a question instead of
+ * investigating it. A template cannot be wrong, so it never notices that its
+ * first finding ruled the premise out, and it never follows the thread that
+ * finding opened.
+ *
+ * What is missing is not more steps. It is the edge from an OBSERVATION back to
+ * the plan: a finding has to be able to refute a hypothesis, sharpen it, or
+ * spawn a new one. This module owns that edge as a pure state machine, so the
+ * part that decides what to investigate next is testable without a provider,
+ * a warehouse, or a clock.
+ */
+export const DEFAULT_RESEARCH_LIMITS = {
+    maxHops: 12,
+    maxOpenHypotheses: 6,
+};
+export function createResearchState(rootQuestion, initial) {
+    return {
+        rootQuestion,
+        hypotheses: initial.map((hypothesis) => ({ ...hypothesis, status: 'open', evidenceIds: [] })),
+        findings: [],
+        hopsUsed: 0,
+    };
+}
+/**
+ * Which hypothesis to test next: the open one with the highest prior.
+ *
+ * Returns `undefined` when the budget is spent or nothing is open, which is how
+ * the caller learns to stop. Deliberately not "cheapest first" — the point of
+ * research is to resolve the question, and testing a likely explanation first is
+ * what lets a later hop be skipped entirely.
+ */
+export function nextHypothesis(state, limits = DEFAULT_RESEARCH_LIMITS) {
+    if (state.hopsUsed >= limits.maxHops)
+        return undefined;
+    return [...state.hypotheses]
+        .filter((hypothesis) => hypothesis.status === 'open')
+        .sort((left, right) => right.priorConfidence - left.priorConfidence || left.id.localeCompare(right.id))[0];
+}
+/**
+ * Fold a finding into the state — the replan edge.
+ *
+ * A refutation CLOSES its hypothesis rather than leaving it open to be retried:
+ * the template's failure was continuing to elaborate a premise its own evidence
+ * had already ruled out.
+ *
+ * Spawned hypotheses are admitted only while there is room, and never duplicate
+ * an existing statement — a loop that keeps re-proposing the same idea burns the
+ * whole hop budget without learning anything.
+ */
+export function applyFinding(state, finding, limits = DEFAULT_RESEARCH_LIMITS) {
+    const hypotheses = state.hypotheses.map((hypothesis) => {
+        if (hypothesis.id !== finding.hypothesisId)
+            return hypothesis;
+        const status = finding.verdict === 'supports'
+            ? 'supported'
+            : finding.verdict === 'refutes'
+                ? 'refuted'
+                : 'inconclusive';
+        return {
+            ...hypothesis,
+            status,
+            evidenceIds: [...hypothesis.evidenceIds, finding.id],
+            rationale: finding.summary,
+        };
+    });
+    const known = new Set(hypotheses.map((hypothesis) => normalizeStatement(hypothesis.statement)));
+    const openCount = () => hypotheses.filter((hypothesis) => hypothesis.status === 'open').length;
+    for (const spawn of finding.spawns ?? []) {
+        const key = normalizeStatement(spawn.statement);
+        if (!spawn.statement.trim() || known.has(key))
+            continue;
+        if (openCount() >= limits.maxOpenHypotheses)
+            break;
+        known.add(key);
+        hypotheses.push({
+            id: `${finding.hypothesisId}.${hypotheses.length + 1}`,
+            statement: spawn.statement,
+            priorConfidence: clamp01(spawn.priorConfidence),
+            status: 'open',
+            evidenceIds: [],
+            parentId: finding.hypothesisId,
+        });
+    }
+    return {
+        ...state,
+        hypotheses,
+        findings: [...state.findings, finding],
+        hopsUsed: state.hopsUsed + 1,
+    };
+}
+/**
+ * Summarise what the investigation established.
+ *
+ * `unresolved` is reported as prominently as `supported` on purpose. A research
+ * answer that lists only what it confirmed reads as a complete explanation, and
+ * the one thing a bounded investigation cannot honestly claim is completeness.
+ */
+export function concludeResearch(state, limits = DEFAULT_RESEARCH_LIMITS) {
+    const byConfidence = (left, right) => right.priorConfidence - left.priorConfidence || left.id.localeCompare(right.id);
+    const open = state.hypotheses.filter((hypothesis) => hypothesis.status === 'open');
+    return {
+        supported: state.hypotheses.filter((h) => h.status === 'supported').sort(byConfidence),
+        refuted: state.hypotheses.filter((h) => h.status === 'refuted').sort(byConfidence),
+        unresolved: [...open, ...state.hypotheses.filter((h) => h.status === 'inconclusive')].sort(byConfidence),
+        exhausted: state.hopsUsed >= limits.maxHops && open.length > 0,
+    };
+}
+function normalizeStatement(value) {
+    return value.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}
+//# sourceMappingURL=hypothesis.js.map

package/dist/agentic/research/hypothesis.js.map

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

package/dist/agentic/research/synthesis.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turn the branch outcomes into the story the dossier was missing.
+ *
+ * Measured on a live run: five grounded hypotheses were planned, all five
+ * branches executed, and the answer the reader got was a single fact from one
+ * of them — "2025-05-01T00:00:00.000Z is the largest order_month at 31.1K". The
+ * other four findings existed and were discarded. The real story was sitting in
+ * the data: one explanation was answerable, four were blocked by uncertified
+ * joins. That is a useful answer about the project, and it never surfaced.
+ *
+ * This layer is DELIBERATELY DETERMINISTIC. It reports what was tested and what
+ * each branch established or could not establish, and it never says which
+ * hypothesis is TRUE — that is a judgment the branch summaries do not license,
+ * and inventing it here would put an unverified causal claim into a governed
+ * dossier. Narration of the numbers stays with the verified-fact narrator.
+ */
+import { type ResearchLimits } from './hypothesis.js';
+export interface ResearchBranchOutcome {
+    /** The hypothesis this branch was testing. */
+    statement: string;
+    /** Did the branch actually produce data? */
+    produced: boolean;
+    /** The branch's own summary, used to explain a blocked branch. */
+    summary?: string;
+    status?: string;
+}
+export declare function synthesizeResearchNarrative(input: {
+    question: string;
+    branches: ResearchBranchOutcome[];
+    limits?: ResearchLimits;
+}): string | undefined;
+//# sourceMappingURL=synthesis.d.ts.map

package/dist/agentic/research/synthesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesis.d.ts","sourceRoot":"","sources":["../../../src/agentic/research/synthesis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAuBD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,GAAG,MAAM,GAAG,SAAS,CAwErB"}

package/dist/agentic/research/synthesis.js

@@ -0,0 +1,94 @@
+/**
+ * Turn the branch outcomes into the story the dossier was missing.
+ *
+ * Measured on a live run: five grounded hypotheses were planned, all five
+ * branches executed, and the answer the reader got was a single fact from one
+ * of them — "2025-05-01T00:00:00.000Z is the largest order_month at 31.1K". The
+ * other four findings existed and were discarded. The real story was sitting in
+ * the data: one explanation was answerable, four were blocked by uncertified
+ * joins. That is a useful answer about the project, and it never surfaced.
+ *
+ * This layer is DELIBERATELY DETERMINISTIC. It reports what was tested and what
+ * each branch established or could not establish, and it never says which
+ * hypothesis is TRUE — that is a judgment the branch summaries do not license,
+ * and inventing it here would put an unverified causal claim into a governed
+ * dossier. Narration of the numbers stays with the verified-fact narrator.
+ */
+import { applyFinding, concludeResearch, createResearchState, } from './hypothesis.js';
+/** Why a branch produced nothing, in the reader's language. */
+function blockedReason(summary) {
+    if (!summary)
+        return undefined;
+    if (/isn't certified yet|not certified|uncertified/i.test(summary)) {
+        return 'the join it needs is not certified yet';
+    }
+    if (/not bound to any modeled entity|unmodelled|unmodeled/i.test(summary)) {
+        return 'it references data that is not modeled';
+    }
+    if (/missing|no result|0 rows|empty/i.test(summary)) {
+        return 'the query returned nothing to compare';
+    }
+    return undefined;
+}
+function sentenceList(items) {
+    if (items.length === 0)
+        return '';
+    if (items.length === 1)
+        return items[0];
+    return `${items.slice(0, -1).join('; ')}; and ${items[items.length - 1]}`;
+}
+export function synthesizeResearchNarrative(input) {
+    const branches = input.branches.filter((branch) => branch.statement.trim().length > 0);
+    if (branches.length === 0)
+        return undefined;
+    let state = createResearchState(input.question, branches.map((branch, index) => ({
+        id: `h${index + 1}`,
+        statement: branch.statement.trim(),
+        priorConfidence: 1 - index / (branches.length + 1),
+    })));
+    branches.forEach((branch, index) => {
+        state = applyFinding(state, {
+            id: `f${index + 1}`,
+            hypothesisId: `h${index + 1}`,
+            // `supports` would claim the observation MATCHED what the hypothesis
+            // predicted, and only the expectation can decide that. Producing rows
+            // means the branch was observed, so it is recorded as inconclusive with
+            // higher strength — the narrative below reports "investigated", never
+            // "confirmed", and the distinction has to hold in the data too.
+            verdict: 'inconclusive',
+            summary: branch.summary ?? '',
+            strength: branch.produced ? 0.6 : 0.1,
+        }, input.limits);
+    });
+    const conclusion = concludeResearch(state, input.limits);
+    // Everything lands in `unresolved` now that no branch claims support, so the
+    // split is by whether the branch produced observable evidence at all.
+    const producedBy = new Map(branches.map((branch) => [branch.statement.trim(), branch.produced]));
+    const investigated = conclusion.unresolved.filter((h) => producedBy.get(h.statement) === true);
+    const blocked = conclusion.unresolved.filter((h) => producedBy.get(h.statement) !== true);
+    const lines = [
+        `I tested ${branches.length} competing explanation${branches.length === 1 ? '' : 's'} for this question.`,
+    ];
+    if (investigated.length > 0) {
+        lines.push('', `**Investigated (${investigated.length}):**`, ...investigated.map((hypothesis) => `- ${hypothesis.statement}`));
+    }
+    if (blocked.length > 0) {
+        const reasons = new Set(blocked
+            .map((hypothesis) => {
+            const branch = branches.find((candidate) => candidate.statement.trim() === hypothesis.statement);
+            return blockedReason(branch?.summary);
+        })
+            .filter((reason) => Boolean(reason)));
+        lines.push('', `**Could not be settled (${blocked.length}):**`, ...blocked.map((hypothesis) => `- ${hypothesis.statement}`));
+        if (reasons.size > 0) {
+            lines.push('', `These were blocked because ${sentenceList([...reasons])}.`);
+        }
+    }
+    if (investigated.length === 0) {
+        // The honest headline when nothing could be established: say so first,
+        // rather than leading with a number from the one branch that ran.
+        lines.splice(1, 0, '', 'None of them could be settled with the governed model as it stands.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=synthesis.js.map

package/dist/agentic/research/synthesis.js.map

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

package/dist/agentic/research-agent.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Hypothesis-driven research planning.
+ *
+ * `planResearch` emits a fixed template — baseline, compare over time, break
+ * down by a dimension scraped out of the question with a regex — bound to one
+ * metric and frozen before any observation. That is why deep research answers
+ * one question instead of telling a story: the shape of the investigation is
+ * decided before the investigation starts, so nothing it learns can change what
+ * it does next.
+ *
+ * This produces HYPOTHESES instead: falsifiable statements about why the
+ * observed thing happened, each mapped to a step that would support or refute
+ * it. The existing executor runs them unchanged, because the output is still a
+ * `ResearchStep[]` — the strangler seam is the plan, not the runner.
+ *
+ * Grounding is unchanged and non-negotiable: every hypothesis must name a real
+ * metric, block, or dimension from the catalog. A hypothesis about an asset
+ * that does not exist cannot be investigated, and inventing one is how a
+ * research dossier ends up confidently discussing a table nobody has.
+ */
+import type { ResearchStep } from '../research-loop.js';
+/** The assets a hypothesis may reference. Nothing outside this may appear. */
+export interface ResearchAssets {
+    metrics: string[];
+    blocks: string[];
+    dimensions: string[];
+}
+export interface ResearchHypothesis {
+    /** A falsifiable statement, not a task. */
+    statement: string;
+    /** Belief before evidence, 0..1 — decides what is tested first. */
+    priorConfidence: number;
+    /** The asset whose inspection would settle it. Must exist in ResearchAssets. */
+    target: string;
+    action: ResearchStep['action']['kind'];
+    /** What an observation must show for the statement to hold. */
+    expectation: string;
+}
+interface PlanProvider {
+    generate(messages: {
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }[], options?: Record<string, unknown>): Promise<string>;
+}
+export declare function parseResearchHypotheses(raw: string, assets: ResearchAssets): ResearchHypothesis[];
+/** One structured call. Returns [] on any failure, so the caller keeps its template. */
+export declare function planResearchHypotheses(provider: PlanProvider, question: string, assets: ResearchAssets, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<ResearchHypothesis[]>;
+/** Render hypotheses as the steps the existing executor already knows how to run. */
+export declare function hypothesesToSteps(hypotheses: ResearchHypothesis[]): ResearchStep[];
+export {};
+//# sourceMappingURL=research-agent.d.ts.map

package/dist/agentic/research-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-agent.d.ts","sourceRoot":"","sources":["../../src/agentic/research-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,eAAe,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;IACvC,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,YAAY;IACpB,QAAQ,CACN,QAAQ,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,EACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAiED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,kBAAkB,EAAE,CA+BjG;AAED,wFAAwF;AACxF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0B/B;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,YAAY,EAAE,CAQlF"}

package/dist/agentic/research-agent.js

@@ -0,0 +1,176 @@
+/**
+ * Hypothesis-driven research planning.
+ *
+ * `planResearch` emits a fixed template — baseline, compare over time, break
+ * down by a dimension scraped out of the question with a regex — bound to one
+ * metric and frozen before any observation. That is why deep research answers
+ * one question instead of telling a story: the shape of the investigation is
+ * decided before the investigation starts, so nothing it learns can change what
+ * it does next.
+ *
+ * This produces HYPOTHESES instead: falsifiable statements about why the
+ * observed thing happened, each mapped to a step that would support or refute
+ * it. The existing executor runs them unchanged, because the output is still a
+ * `ResearchStep[]` — the strangler seam is the plan, not the runner.
+ *
+ * Grounding is unchanged and non-negotiable: every hypothesis must name a real
+ * metric, block, or dimension from the catalog. A hypothesis about an asset
+ * that does not exist cannot be investigated, and inventing one is how a
+ * research dossier ends up confidently discussing a table nobody has.
+ */
+const ACTION_KINDS = new Set([
+    'lookup_metric', 'lookup_block', 'breakdown', 'compare_time', 'check_lineage', 'compose_app',
+]);
+const PROMPT = `You plan a data investigation. Do not answer the question and do not write SQL.
+
+Propose competing HYPOTHESES for what the data will show — falsifiable statements
+about WHY, not a list of tasks. "Revenue fell because enterprise customers churned"
+is a hypothesis. "Break revenue down by segment" is a task; do not write those.
+
+Rules:
+- Every hypothesis must name one asset from the catalog list you are given, exactly
+  as spelled there. A hypothesis about an asset that does not exist cannot be tested.
+- Propose competing explanations, not one explanation in several phrasings. If two
+  hypotheses would be settled by the same observation, keep only the stronger.
+- priorConfidence is your belief BEFORE evidence, 0..1. Do not make them all equal.
+- expectation must state what an observation has to show for the statement to HOLD,
+  so that seeing the opposite refutes it.
+
+Reply with ONLY a JSON object:
+{"hypotheses":[{"statement":"...","priorConfidence":0.6,"target":"<asset>",
+  "action":"lookup_metric|lookup_block|breakdown|compare_time|check_lineage",
+  "expectation":"..."}]}
+Between two and five hypotheses.`;
+function extractJsonObject(raw) {
+    const trimmed = raw.trim();
+    const start = trimmed.indexOf('{');
+    if (start < 0)
+        return undefined;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < trimmed.length; i += 1) {
+        const char = trimmed[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (char === '{')
+            depth += 1;
+        else if (char === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(trimmed.slice(start, i + 1));
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Match a model-named asset to a real one, tolerating case and qualification. */
+function resolveAsset(target, assets) {
+    const pool = [...assets.metrics, ...assets.blocks, ...assets.dimensions];
+    const wanted = target.trim().toLowerCase();
+    if (!wanted)
+        return undefined;
+    const exact = pool.find((asset) => asset.toLowerCase() === wanted);
+    if (exact)
+        return exact;
+    // `orders.revenue` offered as `revenue`, and the reverse.
+    return pool.find((asset) => {
+        const leaf = asset.toLowerCase().split('.').at(-1) ?? '';
+        return leaf === wanted || asset.toLowerCase() === wanted.split('.').at(-1);
+    });
+}
+export function parseResearchHypotheses(raw, assets) {
+    const parsed = extractJsonObject(raw);
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const list = parsed.hypotheses;
+    if (!Array.isArray(list))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        const statement = typeof record.statement === 'string' ? record.statement.trim() : '';
+        const expectation = typeof record.expectation === 'string' ? record.expectation.trim() : '';
+        if (!statement || !expectation)
+            continue;
+        // UNGROUNDED HYPOTHESES ARE DROPPED, not repaired. A statement about an
+        // asset nobody has cannot be investigated, and keeping it would put an
+        // invented table into a dossier that reads as governed.
+        const target = resolveAsset(typeof record.target === 'string' ? record.target : '', assets);
+        if (!target)
+            continue;
+        const action = typeof record.action === 'string' && ACTION_KINDS.has(record.action)
+            ? record.action
+            : 'lookup_metric';
+        const key = statement.toLowerCase().replace(/\s+/g, ' ');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const prior = typeof record.priorConfidence === 'number' && Number.isFinite(record.priorConfidence)
+            ? Math.max(0, Math.min(1, record.priorConfidence))
+            : 0.5;
+        out.push({ statement, priorConfidence: prior, target, action, expectation });
+        if (out.length >= 5)
+            break;
+    }
+    return out.sort((left, right) => right.priorConfidence - left.priorConfidence);
+}
+/** One structured call. Returns [] on any failure, so the caller keeps its template. */
+export async function planResearchHypotheses(provider, question, assets, options = {}) {
+    if (assets.metrics.length === 0 && assets.blocks.length === 0)
+        return [];
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 20_000);
+    const onAbort = () => controller.abort();
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        const catalog = [
+            assets.metrics.length ? `metrics: ${assets.metrics.join(', ')}` : '',
+            assets.blocks.length ? `certified blocks: ${assets.blocks.join(', ')}` : '',
+            assets.dimensions.length ? `dimensions: ${assets.dimensions.join(', ')}` : '',
+        ].filter(Boolean).join('\n');
+        const raw = await provider.generate([
+            { role: 'system', content: `${PROMPT}\n\nCatalog:\n${catalog}` },
+            { role: 'user', content: question },
+        ], { signal: controller.signal });
+        return parseResearchHypotheses(raw, assets);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+    }
+}
+/** Render hypotheses as the steps the existing executor already knows how to run. */
+export function hypothesesToSteps(hypotheses) {
+    return hypotheses.map((hypothesis) => ({
+        // The thought IS the hypothesis, so the trace and the dossier show what is
+        // being tested rather than which tool is being called.
+        thought: hypothesis.statement,
+        action: { kind: hypothesis.action, target: hypothesis.target },
+        expectation: hypothesis.expectation,
+    }));
+}
+//# sourceMappingURL=research-agent.js.map

package/dist/agentic/research-agent.js.map

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