@debriefer/core 2.0.0

package/dist/cost-tracker.js

@@ -0,0 +1,62 @@
+/**
+ * BatchCostTracker — tracks costs across a batch enrichment run.
+ *
+ * Supports per-subject cost limits (e.g., maxCostPerSubject) and a global
+ * total cost limit. Also records cost-by-source for reporting.
+ */
+export class BatchCostTracker {
+    totalCost = 0;
+    subjectCosts = new Map();
+    costBySource = {};
+    maxTotalCost;
+    maxCostPerSubject;
+    constructor(options) {
+        this.maxTotalCost = options?.maxTotalCost;
+        this.maxCostPerSubject = options?.maxCostPerSubject;
+    }
+    /**
+     * Add cost to a subject's running total.
+     * Returns whether any limit (total or per-subject) is now exceeded.
+     */
+    addSubjectCost(subjectId, cost) {
+        this.totalCost += cost;
+        const current = this.subjectCosts.get(subjectId) ?? 0;
+        this.subjectCosts.set(subjectId, current + cost);
+        return this.isTotalLimitExceeded() || this.isSubjectLimitExceeded(subjectId);
+    }
+    /** Track cost by source type for reporting. */
+    addSourceCost(sourceType, cost) {
+        this.costBySource[sourceType] = (this.costBySource[sourceType] ?? 0) + cost;
+    }
+    /** Get total cost across all subjects. */
+    getTotalCost() {
+        return this.totalCost;
+    }
+    /** Get cost for a specific subject. */
+    getSubjectCost(subjectId) {
+        return this.subjectCosts.get(subjectId) ?? 0;
+    }
+    /** Check if total limit is exceeded. Returns false when no limit is set. */
+    isTotalLimitExceeded() {
+        if (this.maxTotalCost === undefined)
+            return false;
+        return this.totalCost >= this.maxTotalCost;
+    }
+    /** Check if a specific subject's limit is exceeded. Returns false when no limit is set. */
+    isSubjectLimitExceeded(subjectId) {
+        if (this.maxCostPerSubject === undefined)
+            return false;
+        return this.getSubjectCost(subjectId) >= this.maxCostPerSubject;
+    }
+    /** Get cost breakdown by source type. Returns a shallow copy. */
+    getCostBySource() {
+        return { ...this.costBySource };
+    }
+    /** Reset all tracking state. */
+    reset() {
+        this.totalCost = 0;
+        this.subjectCosts.clear();
+        this.costBySource = {};
+    }
+}
+//# sourceMappingURL=cost-tracker.js.map

package/dist/cost-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tracker.js","sourceRoot":"","sources":["../src/cost-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,GAAG,CAAC,CAAA;IACb,YAAY,GAAG,IAAI,GAAG,EAA2B,CAAA;IACjD,YAAY,GAA2B,EAAE,CAAA;IAEhC,YAAY,CAAoB;IAChC,iBAAiB,CAAoB;IAEtD,YAAY,OAA+D;QACzE,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY,CAAA;QACzC,IAAI,CAAC,iBAAiB,GAAG,OAAO,EAAE,iBAAiB,CAAA;IACrD,CAAC;IAED;;;OAGG;IACH,cAAc,CAAC,SAA0B,EAAE,IAAY;QACrD,IAAI,CAAC,SAAS,IAAI,IAAI,CAAA;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACrD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC,CAAA;QAChD,OAAO,IAAI,CAAC,oBAAoB,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAA;IAC9E,CAAC;IAED,+CAA+C;IAC/C,aAAa,CAAC,UAAkB,EAAE,IAAY;QAC5C,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAA;IAC7E,CAAC;IAED,0CAA0C;IAC1C,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,uCAAuC;IACvC,cAAc,CAAC,SAA0B;QACvC,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAC9C,CAAC;IAED,4EAA4E;IAC5E,oBAAoB;QAClB,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACjD,OAAO,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,YAAY,CAAA;IAC5C,CAAC;IAED,2FAA2F;IAC3F,sBAAsB,CAAC,SAA0B;QAC/C,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACtD,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAA;IACjE,CAAC;IAED,iEAAiE;IACjE,eAAe;QACb,OAAO,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,CAAA;IACjC,CAAC;IAED,gCAAgC;IAChC,KAAK;QACH,IAAI,CAAC,SAAS,GAAG,CAAC,CAAA;QAClB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAA;QACzB,IAAI,CAAC,YAAY,GAAG,EAAE,CAAA;IACxB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Debriefer — Multi-source research orchestration engine.
+ *
+ * Orchestrates data sources with Wikipedia RSP-based reliability scoring,
+ * phased execution with early stopping, per-query cost control, and pluggable synthesis.
+ *
+ * @packageDocumentation
+ */
+export { ResearchOrchestrator } from "./orchestrator.js";
+export { BaseResearchSource } from "./base-source.js";
+export type { BaseSourceOptions } from "./base-source.js";
+export { NoopSynthesizer, stripMarkdownCodeFences } from "./synthesizer.js";
+export { ReliabilityTier, RELIABILITY_SCORES, getReliabilityScore, meetsReliabilityThreshold, } from "./reliability.js";
+export { SourceRateLimiter } from "./rate-limiter.js";
+export type { RateLimiterStats } from "./rate-limiter.js";
+export { BatchCostTracker } from "./cost-tracker.js";
+export { ParallelBatchRunner } from "./batch-runner.js";
+export type { BatchProgress, BatchResult, ParallelBatchRunnerOptions } from "./batch-runner.js";
+export { calculateConfidence } from "./confidence.js";
+export { InMemoryCache } from "./cache/in-memory.js";
+export { ConsoleTelemetry } from "./telemetry/console.js";
+export { NoopTelemetry } from "./telemetry/noop.js";
+export type { ResearchSubject, RawFinding, ScoredFinding, MinimalSource, SourcePhaseGroup, SynthesisOptions, SynthesisResult, Synthesizer, DebriefResult, ResearchConfig, CacheProvider, TelemetryProvider, TelemetrySpan, BatchProgressStats, BatchStats, LifecycleHooks, } from "./types.js";
+export { CostLimitExceededError, SourceTimeoutError, SourceAccessBlockedError } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAG3E,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAGrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnD,YAAY,EACV,eAAe,EACf,UAAU,EACV,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * Debriefer — Multi-source research orchestration engine.
+ *
+ * Orchestrates data sources with Wikipedia RSP-based reliability scoring,
+ * phased execution with early stopping, per-query cost control, and pluggable synthesis.
+ *
+ * @packageDocumentation
+ */
+// Core engine
+export { ResearchOrchestrator } from "./orchestrator.js";
+export { BaseResearchSource } from "./base-source.js";
+// Synthesis (ClaudeSynthesizer moved to @debriefer/ai)
+export { NoopSynthesizer, stripMarkdownCodeFences } from "./synthesizer.js";
+// Reliability scoring
+export { ReliabilityTier, RELIABILITY_SCORES, getReliabilityScore, meetsReliabilityThreshold, } from "./reliability.js";
+// Infrastructure
+export { SourceRateLimiter } from "./rate-limiter.js";
+export { BatchCostTracker } from "./cost-tracker.js";
+export { ParallelBatchRunner } from "./batch-runner.js";
+export { calculateConfidence } from "./confidence.js";
+// Cache implementations
+export { InMemoryCache } from "./cache/in-memory.js";
+// Telemetry implementations
+export { ConsoleTelemetry } from "./telemetry/console.js";
+export { NoopTelemetry } from "./telemetry/noop.js";
+// Error types
+export { CostLimitExceededError, SourceTimeoutError, SourceAccessBlockedError } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc;AACd,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAGrD,uDAAuD;AACvD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAE3E,sBAAsB;AACtB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAA;AAEzB,iBAAiB;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAEvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,wBAAwB;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAsBnD,cAAc;AACd,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA"}

package/dist/orchestrator.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Research Orchestrator — the core engine that wires sources, phases,
+ * rate limiting, cost tracking, and synthesis into a complete pipeline.
+ *
+ * Two entry points:
+ * - `debrief(subject)` — research a single subject through all phases
+ * - `debriefBatch(subjects, hooks)` — research multiple subjects with
+ *   concurrency, cost limits, and lifecycle hooks
+ *
+ * Algorithm (per subject):
+ * 1. For each phase in order:
+ *    a. Filter to available sources (isAvailable())
+ *    b. Execute sources — concurrently via Promise.allSettled() by default,
+ *       or sequentially (stop at first success) when phase.sequential is true
+ *    c. Collect successful findings, tag with reliability info → ScoredFinding
+ *    d. Check early-stop: do we have earlyStopThreshold+ high-quality families?
+ *    e. Check per-subject cost limit
+ * 2. Synthesize all accumulated findings via the injected Synthesizer
+ * 3. Return DebriefResult
+ */
+import type { ResearchSubject, ResearchConfig, DebriefResult, SourcePhaseGroup, Synthesizer, LifecycleHooks } from "./types.js";
+/**
+ * Generic research orchestrator that coordinates source phases, rate limiting,
+ * cost tracking, and AI synthesis into a complete research pipeline.
+ *
+ * @typeParam TSubject - The research subject type (extends ResearchSubject)
+ * @typeParam TOutput - The structured output type produced by synthesis
+ */
+export declare class ResearchOrchestrator<TSubject extends ResearchSubject, TOutput> {
+    private phases;
+    private synthesizer;
+    private config;
+    private rateLimiter;
+    private telemetry;
+    constructor(phases: SourcePhaseGroup<TSubject>[], synthesizer: Synthesizer<TSubject, TOutput>, config?: ResearchConfig);
+    /**
+     * Research a single subject through all configured phases.
+     *
+     * Iterates through phases sequentially. Within each phase, sources run
+     * concurrently via Promise.allSettled by default, or sequentially (stopping
+     * at first success) when `phase.sequential` is true. Accumulates findings,
+     * checks early stopping between phases, then runs synthesis on all collected
+     * findings.
+     *
+     * @param subject - The subject to research
+     * @param options - Optional abort signal and lifecycle hooks
+     * @returns Complete debrief result with findings, synthesis, and cost data
+     */
+    debrief(subject: TSubject, options?: {
+        signal?: AbortSignal;
+        hooks?: LifecycleHooks<TSubject, TOutput>;
+    }): Promise<DebriefResult<TOutput>>;
+    /**
+     * Execute all available sources in a single phase.
+     *
+     * By default, sources run concurrently via Promise.allSettled(). When
+     * `phaseGroup.sequential` is true, sources run one at a time in order,
+     * stopping at the first source that returns a non-null finding.
+     *
+     * Fires onSourceAttempt before each lookup and onSourceComplete after.
+     * Returns the phase's findings, attempt/success counts, and cost.
+     */
+    private executePhase;
+    /**
+     * Execute sources concurrently via Promise.allSettled().
+     */
+    private executePhaseConcurrently;
+    /**
+     * Execute sources sequentially, stopping at the first non-null finding.
+     * Used for AI model phases where cheapest-first ordering controls cost.
+     */
+    private executePhaseSequentially;
+    /**
+     * Check whether early stopping criteria are met.
+     *
+     * Returns a reason string if stopping should occur, or null to continue.
+     */
+    private checkEarlyStop;
+    /**
+     * Research multiple subjects with bounded concurrency and lifecycle hooks.
+     *
+     * Uses ParallelBatchRunner for concurrent subject processing with shared
+     * rate limiting. Fires lifecycle hooks at each stage for observability:
+     * database writes, progress bars, monitoring dashboards, etc.
+     *
+     * @param subjects - Array of subjects to research
+     * @param hooks - Optional lifecycle hooks for progress and monitoring
+     * @returns Map of subject ID → DebriefResult
+     */
+    debriefBatch(subjects: TSubject[], hooks?: LifecycleHooks<TSubject, TOutput>): Promise<Map<string | number, DebriefResult<TOutput>>>;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAGd,aAAa,EACb,gBAAgB,EAEhB,WAAW,EACX,cAAc,EAEf,MAAM,YAAY,CAAA;AAanB;;;;;;GAMG;AACH,qBAAa,oBAAoB,CAAC,QAAQ,SAAS,eAAe,EAAE,OAAO;IACzE,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,SAAS,CAAmB;gBAGlC,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,EACpC,WAAW,EAAE,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC3C,MAAM,GAAE,cAAmB;IAwB7B;;;;;;;;;;;;OAYG;IACG,OAAO,CACX,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;KAAE,GAC5E,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAsElC;;;;;;;;;OASG;YACW,YAAY;IA6B1B;;OAEG;YACW,wBAAwB;IAiEtC;;;OAGG;YACW,wBAAwB;IAmEtC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA6BtB;;;;;;;;;;OAUG;IACG,YAAY,CAChB,QAAQ,EAAE,QAAQ,EAAE,EACpB,KAAK,CAAC,EAAE,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,GACxC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;CAuGzD"}

package/dist/orchestrator.js

@@ -0,0 +1,373 @@
+/**
+ * Research Orchestrator — the core engine that wires sources, phases,
+ * rate limiting, cost tracking, and synthesis into a complete pipeline.
+ *
+ * Two entry points:
+ * - `debrief(subject)` — research a single subject through all phases
+ * - `debriefBatch(subjects, hooks)` — research multiple subjects with
+ *   concurrency, cost limits, and lifecycle hooks
+ *
+ * Algorithm (per subject):
+ * 1. For each phase in order:
+ *    a. Filter to available sources (isAvailable())
+ *    b. Execute sources — concurrently via Promise.allSettled() by default,
+ *       or sequentially (stop at first success) when phase.sequential is true
+ *    c. Collect successful findings, tag with reliability info → ScoredFinding
+ *    d. Check early-stop: do we have earlyStopThreshold+ high-quality families?
+ *    e. Check per-subject cost limit
+ * 2. Synthesize all accumulated findings via the injected Synthesizer
+ * 3. Return DebriefResult
+ */
+import { SourceRateLimiter } from "./rate-limiter.js";
+import { BatchCostTracker } from "./cost-tracker.js";
+import { ParallelBatchRunner } from "./batch-runner.js";
+import { NoopTelemetry } from "./telemetry/noop.js";
+const DEFAULT_CONFIG = {
+    concurrency: 5,
+    confidenceThreshold: 0.6,
+    reliabilityThreshold: 0.6,
+    earlyStopThreshold: 3,
+};
+/**
+ * Generic research orchestrator that coordinates source phases, rate limiting,
+ * cost tracking, and AI synthesis into a complete research pipeline.
+ *
+ * @typeParam TSubject - The research subject type (extends ResearchSubject)
+ * @typeParam TOutput - The structured output type produced by synthesis
+ */
+export class ResearchOrchestrator {
+    phases;
+    synthesizer;
+    config;
+    rateLimiter;
+    telemetry;
+    constructor(phases, synthesizer, config = {}) {
+        this.phases = phases;
+        this.synthesizer = synthesizer;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.rateLimiter = new SourceRateLimiter();
+        this.telemetry = config.telemetry ?? new NoopTelemetry();
+        // Inject infrastructure into all sources
+        for (const phase of phases) {
+            for (const source of phase.sources) {
+                if ("setRateLimiter" in source && typeof source.setRateLimiter === "function") {
+                    source.setRateLimiter(this.rateLimiter);
+                }
+                if ("setCache" in source && typeof source.setCache === "function" && config.cache) {
+                    source.setCache(config.cache);
+                }
+                if ("setTelemetry" in source && typeof source.setTelemetry === "function") {
+                    source.setTelemetry(this.telemetry);
+                }
+            }
+        }
+    }
+    /**
+     * Research a single subject through all configured phases.
+     *
+     * Iterates through phases sequentially. Within each phase, sources run
+     * concurrently via Promise.allSettled by default, or sequentially (stopping
+     * at first success) when `phase.sequential` is true. Accumulates findings,
+     * checks early stopping between phases, then runs synthesis on all collected
+     * findings.
+     *
+     * @param subject - The subject to research
+     * @param options - Optional abort signal and lifecycle hooks
+     * @returns Complete debrief result with findings, synthesis, and cost data
+     */
+    async debrief(subject, options) {
+        const startTime = Date.now();
+        const allFindings = [];
+        let totalCostUsd = 0;
+        let sourcesAttempted = 0;
+        let sourcesSucceeded = 0;
+        let stoppedAtPhase;
+        const signal = options?.signal;
+        const hooks = options?.hooks;
+        for (const phaseGroup of this.phases) {
+            if (signal?.aborted)
+                break;
+            const phaseResult = await this.executePhase(subject, phaseGroup, signal, hooks);
+            sourcesAttempted += phaseResult.sourcesAttempted;
+            sourcesSucceeded += phaseResult.sourcesSucceeded;
+            totalCostUsd += phaseResult.costUsd;
+            allFindings.push(...phaseResult.findings);
+            hooks?.onPhaseComplete?.(subject, phaseGroup.phase, phaseResult.findings);
+            const earlyStopReason = this.checkEarlyStop(allFindings, totalCostUsd);
+            if (earlyStopReason) {
+                stoppedAtPhase = phaseGroup.phase;
+                hooks?.onEarlyStop?.(subject, phaseGroup.phase, earlyStopReason);
+                if (earlyStopReason === "cost_limit") {
+                    hooks?.onCostLimitReached?.(subject, totalCostUsd, this.config.costLimits.maxCostPerSubject);
+                }
+                break;
+            }
+        }
+        // Synthesize all findings
+        let synthesisResult = undefined;
+        if (allFindings.length > 0) {
+            hooks?.onSynthesisStart?.(subject, allFindings.length);
+            try {
+                synthesisResult = await this.synthesizer.synthesize(subject, allFindings, this.config.synthesis ?? {});
+                totalCostUsd += synthesisResult.costUsd;
+                hooks?.onSynthesisComplete?.(subject, synthesisResult);
+            }
+            catch (error) {
+                this.telemetry.recordError(error instanceof Error ? error : new Error(String(error)), {
+                    subject: subject.name,
+                    phase: "synthesis",
+                });
+            }
+        }
+        return {
+            subject,
+            data: synthesisResult?.data ?? null,
+            findings: allFindings,
+            synthesisResult,
+            totalCostUsd,
+            sourcesAttempted,
+            sourcesSucceeded,
+            stoppedAtPhase,
+            durationMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Execute all available sources in a single phase.
+     *
+     * By default, sources run concurrently via Promise.allSettled(). When
+     * `phaseGroup.sequential` is true, sources run one at a time in order,
+     * stopping at the first source that returns a non-null finding.
+     *
+     * Fires onSourceAttempt before each lookup and onSourceComplete after.
+     * Returns the phase's findings, attempt/success counts, and cost.
+     */
+    async executePhase(subject, phaseGroup, signal, hooks) {
+        const availableSources = phaseGroup.sources.filter((s) => s.isAvailable());
+        if (availableSources.length === 0) {
+            return { findings: [], sourcesAttempted: 0, sourcesSucceeded: 0, costUsd: 0 };
+        }
+        if (phaseGroup.sequential) {
+            return this.executePhaseSequentially(subject, availableSources, phaseGroup.phase, signal, hooks);
+        }
+        return this.executePhaseConcurrently(subject, availableSources, phaseGroup.phase, signal, hooks);
+    }
+    /**
+     * Execute sources concurrently via Promise.allSettled().
+     */
+    async executePhaseConcurrently(subject, availableSources, phase, signal, hooks) {
+        const timeoutSignal = AbortSignal.timeout(120_000);
+        const phaseSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+        const results = await Promise.allSettled(availableSources.map(async (source) => {
+            hooks?.onSourceAttempt?.(subject, source.name, phase);
+            return source.lookup(subject, phaseSignal);
+        }));
+        const findings = [];
+        let costUsd = 0;
+        let sourcesSucceeded = 0;
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            const source = availableSources[i];
+            const finding = result.status === "fulfilled" ? result.value : null;
+            if (result.status === "rejected") {
+                this.telemetry.recordError(result.reason instanceof Error ? result.reason : new Error(String(result.reason)), { source: source.name, subject: subject.name, phase });
+            }
+            try {
+                hooks?.onSourceComplete?.(subject, source.name, finding, finding?.costUsd ?? 0);
+            }
+            catch (error) {
+                this.telemetry.recordError(error instanceof Error ? error : new Error(String(error)), {
+                    hook: "onSourceComplete",
+                    source: source.name,
+                    subject: subject.name,
+                    phase,
+                });
+            }
+            if (finding) {
+                costUsd += finding.costUsd;
+                sourcesSucceeded++;
+                findings.push({
+                    ...finding,
+                    sourceType: source.type,
+                    sourceName: source.name,
+                    reliabilityTier: source.reliabilityTier,
+                    reliabilityScore: source.reliabilityScore,
+                });
+            }
+        }
+        return { findings, sourcesAttempted: availableSources.length, sourcesSucceeded, costUsd };
+    }
+    /**
+     * Execute sources sequentially, stopping at the first non-null finding.
+     * Used for AI model phases where cheapest-first ordering controls cost.
+     */
+    async executePhaseSequentially(subject, availableSources, phase, signal, hooks) {
+        const timeoutSignal = AbortSignal.timeout(120_000);
+        const phaseSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+        const findings = [];
+        let costUsd = 0;
+        let sourcesAttempted = 0;
+        let sourcesSucceeded = 0;
+        for (const source of availableSources) {
+            if (phaseSignal.aborted)
+                break;
+            sourcesAttempted++;
+            let finding = null;
+            try {
+                hooks?.onSourceAttempt?.(subject, source.name, phase);
+                finding = await source.lookup(subject, phaseSignal);
+            }
+            catch (error) {
+                // Source/hook errors are swallowed — consistent with concurrent path
+                // where async callbacks turn throws into rejected promises.
+                this.telemetry.recordError(error instanceof Error ? error : new Error(String(error)), {
+                    source: source.name,
+                    subject: subject.name,
+                    phase,
+                });
+            }
+            try {
+                hooks?.onSourceComplete?.(subject, source.name, finding, finding?.costUsd ?? 0);
+            }
+            catch (error) {
+                this.telemetry.recordError(error instanceof Error ? error : new Error(String(error)), {
+                    source: source.name,
+                    subject: subject.name,
+                    phase,
+                    hook: "onSourceComplete",
+                });
+            }
+            if (finding) {
+                costUsd += finding.costUsd;
+                sourcesSucceeded++;
+                findings.push({
+                    ...finding,
+                    sourceType: source.type,
+                    sourceName: source.name,
+                    reliabilityTier: source.reliabilityTier,
+                    reliabilityScore: source.reliabilityScore,
+                });
+                break; // Stop at first success
+            }
+        }
+        return { findings, sourcesAttempted, sourcesSucceeded, costUsd };
+    }
+    /**
+     * Check whether early stopping criteria are met.
+     *
+     * Returns a reason string if stopping should occur, or null to continue.
+     */
+    checkEarlyStop(allFindings, totalCostUsd) {
+        const confidenceThreshold = this.config.confidenceThreshold ?? DEFAULT_CONFIG.confidenceThreshold;
+        const reliabilityThreshold = this.config.reliabilityThreshold ?? DEFAULT_CONFIG.reliabilityThreshold;
+        const earlyStopThreshold = this.config.earlyStopThreshold ?? DEFAULT_CONFIG.earlyStopThreshold;
+        const highQualityFamilies = new Set(allFindings
+            .filter((f) => f.confidence >= confidenceThreshold && f.reliabilityScore >= reliabilityThreshold)
+            .map((f) => f.sourceType));
+        if (highQualityFamilies.size >= earlyStopThreshold) {
+            return `${highQualityFamilies.size} high-quality source families met threshold of ${earlyStopThreshold}`;
+        }
+        if (this.config.costLimits?.maxCostPerSubject &&
+            totalCostUsd >= this.config.costLimits.maxCostPerSubject) {
+            return "cost_limit";
+        }
+        return null;
+    }
+    /**
+     * Research multiple subjects with bounded concurrency and lifecycle hooks.
+     *
+     * Uses ParallelBatchRunner for concurrent subject processing with shared
+     * rate limiting. Fires lifecycle hooks at each stage for observability:
+     * database writes, progress bars, monitoring dashboards, etc.
+     *
+     * @param subjects - Array of subjects to research
+     * @param hooks - Optional lifecycle hooks for progress and monitoring
+     * @returns Map of subject ID → DebriefResult
+     */
+    async debriefBatch(subjects, hooks) {
+        const startTime = Date.now();
+        const concurrency = this.config.concurrency ?? DEFAULT_CONFIG.concurrency;
+        const resultMap = new Map();
+        const costTracker = this.config.costLimits?.maxTotalCost
+            ? new BatchCostTracker({
+                maxTotalCost: this.config.costLimits.maxTotalCost,
+            })
+            : undefined;
+        hooks?.onRunStart?.(subjects.length, this.config);
+        const runner = new ParallelBatchRunner({
+            concurrency,
+            onItemComplete: (subject, result, progress) => {
+                resultMap.set(subject.id, result);
+                if (costTracker) {
+                    costTracker.addSubjectCost(subject.id, result.totalCostUsd);
+                }
+                hooks?.onSubjectComplete?.(subject, result);
+                // Calculate running total cost across all completed subjects
+                const runningCost = costTracker?.getTotalCost() ??
+                    Array.from(resultMap.values()).reduce((sum, r) => sum + r.totalCostUsd, 0);
+                hooks?.onBatchProgress?.({
+                    completed: progress.completed,
+                    total: progress.total,
+                    costUsd: runningCost,
+                    elapsedMs: Date.now() - startTime,
+                });
+            },
+            onItemError: (subject, error) => {
+                // Per-subject errors are not batch failures — the batch continues.
+                // Report via onSubjectComplete with null data.
+                const errorResult = {
+                    subject,
+                    data: null,
+                    findings: [],
+                    totalCostUsd: 0,
+                    sourcesAttempted: 0,
+                    sourcesSucceeded: 0,
+                    durationMs: 0,
+                };
+                resultMap.set(subject.id, errorResult);
+                hooks?.onSubjectComplete?.(subject, errorResult);
+                this.telemetry.recordError(error, { subject: subject.name, phase: "batch" });
+            },
+        });
+        const batchResults = await runner.run(subjects, async (subject) => {
+            // Check total cost limit before starting
+            if (costTracker?.isTotalLimitExceeded()) {
+                return {
+                    subject,
+                    data: null,
+                    findings: [],
+                    totalCostUsd: 0,
+                    sourcesAttempted: 0,
+                    sourcesSucceeded: 0,
+                    durationMs: 0,
+                };
+            }
+            hooks?.onSubjectStart?.(subject, resultMap.size, subjects.length);
+            return this.debrief(subject, { hooks });
+        });
+        // Ensure results from cost-limited subjects (which still succeed via
+        // onItemComplete) and any edge cases are captured in the map
+        for (const entry of batchResults) {
+            if (entry.result && !resultMap.has(entry.item.id)) {
+                resultMap.set(entry.item.id, entry.result);
+            }
+        }
+        const totalCost = costTracker?.getTotalCost() ??
+            Array.from(resultMap.values()).reduce((sum, r) => sum + r.totalCostUsd, 0);
+        const succeeded = Array.from(resultMap.values()).filter((r) => r.data !== null).length;
+        hooks?.onRunComplete?.({
+            completed: resultMap.size,
+            total: subjects.length,
+            costUsd: totalCost,
+            elapsedMs: Date.now() - startTime,
+            succeeded,
+            failed: resultMap.size - succeeded,
+            avgCostPerSubject: resultMap.size > 0 ? totalCost / resultMap.size : 0,
+            avgDurationMs: resultMap.size > 0
+                ? Array.from(resultMap.values()).reduce((sum, r) => sum + r.durationMs, 0) /
+                    resultMap.size
+                : 0,
+        });
+        return resultMap;
+    }
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator.js.map

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

package/dist/rate-limiter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-domain async rate limiter shared across all source instances.
+ *
+ * Uses an async queue per domain to prevent thundering herd — when multiple
+ * callers request the same domain simultaneously, they're serialized so each
+ * waits the correct delay after the previous one, rather than all sleeping
+ * the same amount and firing together.
+ *
+ * Example: Three sources all query en.wikipedia.org. Without rate limiting,
+ * they'd fire simultaneously and risk being blocked. The rate limiter
+ * serializes them with configurable delays between requests.
+ */
+export interface RateLimiterStats {
+    totalRequests: number;
+    totalWaitMs: number;
+}
+export declare class SourceRateLimiter {
+    private domains;
+    private getOrCreateDomain;
+    /**
+     * Acquire permission to make a request to the given domain.
+     * Blocks until minDelayMs has passed since the last request to this domain.
+     */
+    acquire(domain: string, minDelayMs: number): Promise<void>;
+    private processQueue;
+    /** Get rate limiting stats per domain */
+    getStats(): Map<string, RateLimiterStats>;
+    /** Reset all state (useful for testing) */
+    reset(): void;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAiC;IAEhD,OAAO,CAAC,iBAAiB;IAezB;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YASlD,YAAY;IAyB1B,yCAAyC;IACzC,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAWzC,2CAA2C;IAC3C,KAAK,IAAI,IAAI;CAGd"}