@debriefer/core 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,417 @@
+/**
+ * Core type definitions for the debriefer research orchestration engine.
+ *
+ * These types are generalized from deadonfilm's death-sources/types.ts and
+ * biography-sources/types.ts. They define the contracts for subjects, findings,
+ * sources, synthesis, configuration, lifecycle hooks, and error types that
+ * the orchestrator and all source implementations share.
+ *
+ * Domain-specific types (e.g., ActorForEnrichment, BiographyData) live in
+ * consumer code, not here. Consumers extend ResearchSubject and provide their
+ * own TOutput type to the orchestrator.
+ */
+import type { ReliabilityTier } from "./reliability.js";
+/**
+ * A research subject is the entity being investigated across multiple sources.
+ *
+ * Consumers extend this with domain-specific fields via the `context` bag.
+ * For example, deadonfilm adds `birthday`, `deathday`, `tmdbId`, etc.
+ *
+ * @example
+ * ```typescript
+ * const actor: ResearchSubject = {
+ *   id: 2157,
+ *   name: "John Wayne",
+ *   context: { deathday: "1979-06-11", tmdbId: 2157 },
+ * }
+ * ```
+ */
+export interface ResearchSubject {
+    /** Unique identifier — string or number depending on domain */
+    id: string | number;
+    /** Display name used in search queries and logging */
+    name: string;
+    /** Domain-specific metadata (birthday, deathday, external IDs, etc.) */
+    context?: Record<string, unknown>;
+}
+/**
+ * Raw data extracted from a single source lookup, before reliability scoring.
+ *
+ * This is what a source returns from its `lookup()` method. The orchestrator
+ * then tags it with source reliability info to produce a ScoredFinding.
+ */
+export interface RawFinding {
+    /** Extracted text content from the source */
+    text: string;
+    /** URL of the source page, if applicable */
+    url?: string;
+    /** Publisher name (e.g., "The Guardian", "Wikipedia") */
+    publication?: string;
+    /** Article or page title */
+    articleTitle?: string;
+    /**
+     * Content confidence (0-1): how well does this page answer the research question?
+     * This is independent of source reliability — a Reuters page about weather
+     * has high reliability but zero confidence for death research.
+     */
+    confidence: number;
+    /** Cost in USD incurred for this lookup (API fees, etc.) */
+    costUsd: number;
+    /** Arbitrary metadata for debugging or downstream processing */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A finding tagged with source reliability information.
+ *
+ * Created by the orchestrator after a source returns a RawFinding.
+ * The reliability fields come from the source's declared tier, not
+ * from analyzing the content.
+ */
+export interface ScoredFinding extends RawFinding {
+    /** Source type identifier (e.g., "wikipedia", "google_search") */
+    sourceType: string;
+    /** Human-readable source name (e.g., "Wikipedia", "Google Search") */
+    sourceName: string;
+    /** Reliability tier from the ReliabilityTier enum */
+    reliabilityTier: ReliabilityTier;
+    /**
+     * Numeric reliability score (0-1): how trustworthy is this publisher?
+     * Based on Wikipedia's Reliable Sources Perennial list (RSP).
+     */
+    reliabilityScore: number;
+}
+/**
+ * Options for AI synthesis of accumulated findings.
+ */
+export interface SynthesisOptions {
+    /** AI model identifier (e.g., "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Maximum tokens for the AI response */
+    maxTokens?: number;
+    /** System prompt guiding the synthesis */
+    systemPrompt?: string;
+}
+/**
+ * Result of AI synthesis, including the structured output and cost metadata.
+ */
+export interface SynthesisResult<TOutput> {
+    /** The structured output produced by the AI */
+    data: TOutput;
+    /** Cost in USD for this synthesis call */
+    costUsd: number;
+    /** Number of input tokens consumed */
+    inputTokens: number;
+    /** Number of output tokens generated */
+    outputTokens: number;
+    /** Model identifier used for synthesis */
+    model: string;
+}
+/**
+ * Interface for AI synthesizers that distill findings into structured output.
+ *
+ * Ships with ClaudeSynthesizer. Consumers can implement for OpenAI, Gemini,
+ * local models, or skip AI entirely with a pass-through implementation.
+ */
+export interface Synthesizer<TSubject extends ResearchSubject, TOutput> {
+    synthesize(subject: TSubject, findings: ScoredFinding[], options: SynthesisOptions): Promise<SynthesisResult<TOutput>>;
+}
+/**
+ * Minimal source interface used in SourcePhaseGroup to avoid circular
+ * dependency with BaseResearchSource (which imports from this file).
+ *
+ * BaseResearchSource implements this interface. The orchestrator works
+ * with BaseResearchSource instances but the type system only needs this
+ * minimal contract for phase group definitions.
+ */
+export interface MinimalSource<TSubject extends ResearchSubject> {
+    /** Machine-readable source identifier (e.g., "wikipedia", "google_search") */
+    readonly name: string;
+    /** Source type string matching a registry key */
+    readonly type: string;
+    /** Reliability tier from the ReliabilityTier enum */
+    readonly reliabilityTier: ReliabilityTier;
+    /** Numeric reliability score (0-1) */
+    readonly reliabilityScore: number;
+    /** Whether this source is free to query */
+    readonly isFree: boolean;
+    /** Estimated cost per query in USD */
+    readonly estimatedCostPerQuery: number;
+    /** Domain for rate limiting coordination (e.g., "en.wikipedia.org") */
+    readonly domain: string;
+    /** Check if this source is available (API key configured, etc.) */
+    isAvailable(): boolean;
+    /**
+     * Look up information about a subject.
+     * Returns null if no relevant information was found.
+     */
+    lookup(subject: TSubject, signal: AbortSignal): Promise<RawFinding | null>;
+}
+/**
+ * A group of sources that execute together in a single phase.
+ *
+ * The orchestrator processes phases sequentially. Within each phase,
+ * sources run concurrently via Promise.allSettled() by default. When
+ * `sequential` is true, sources run one at a time in order, stopping
+ * at the first source that returns a non-null finding.
+ */
+export interface SourcePhaseGroup<TSubject extends ResearchSubject> {
+    /** Phase number — determines execution order (lower = earlier) */
+    phase: number;
+    /** Human-readable phase name for logging (e.g., "Structured Data", "Web Search") */
+    name?: string;
+    /** Sources to execute within this phase (concurrently by default, or sequentially when `sequential: true`) */
+    sources: ReadonlyArray<MinimalSource<TSubject>>;
+    /**
+     * If true, execute sources sequentially within this phase instead of
+     * concurrently. Stops at the first source that returns a non-null finding.
+     * Useful for AI model sources where you want cheapest-first with early exit.
+     */
+    sequential?: boolean;
+}
+/**
+ * Complete result of debriefing (researching) a single subject.
+ *
+ * Contains the synthesized output, all collected findings, cost tracking,
+ * and execution metadata.
+ */
+export interface DebriefResult<TOutput> {
+    /** The subject that was researched */
+    subject: ResearchSubject;
+    /** Synthesized output, or null if synthesis failed or was skipped */
+    data: TOutput | null;
+    /** All scored findings collected across all phases */
+    findings: ScoredFinding[];
+    /** Synthesis result with token counts and cost, if synthesis ran */
+    synthesisResult?: SynthesisResult<TOutput>;
+    /** Total cost in USD across all source lookups and synthesis */
+    totalCostUsd: number;
+    /** Number of sources that were attempted */
+    sourcesAttempted: number;
+    /** Number of sources that returned findings */
+    sourcesSucceeded: number;
+    /** Phase number where early stopping occurred, if applicable */
+    stoppedAtPhase?: number;
+    /** Total wall-clock time in milliseconds */
+    durationMs: number;
+}
+/**
+ * Configuration for the research orchestrator.
+ *
+ * All fields are optional — the orchestrator provides sensible defaults.
+ */
+export interface ResearchConfig {
+    /**
+     * Source category flags (e.g., { free: true, news: true, ai: false }).
+     * Categories are domain-specific — consumer code uses these when constructing
+     * phase groups to decide which sources to include. The orchestrator stores
+     * this config for lifecycle hooks but does not filter sources itself.
+     */
+    categories?: Record<string, boolean>;
+    /** Number of subjects to process concurrently in batch mode (default: 5, range: 1-20) */
+    concurrency?: number;
+    /** Minimum content confidence to count as a quality finding (default: 0.6) */
+    confidenceThreshold?: number;
+    /** Minimum source reliability to count as a quality finding (default: 0.6) */
+    reliabilityThreshold?: number;
+    /**
+     * Number of high-quality source families needed before early stopping (default: 3).
+     * A "source family" is a unique sourceType — multiple findings from the same
+     * source type count as one family.
+     */
+    earlyStopThreshold?: number;
+    /** Cost limits to prevent runaway spending */
+    costLimits?: {
+        /** Maximum cost per subject in USD — stops processing that subject */
+        maxCostPerSubject?: number;
+        /** Maximum total cost for the entire batch in USD — stops the batch */
+        maxTotalCost?: number;
+    };
+    /** AI synthesis options */
+    synthesis?: SynthesisOptions;
+    /** Cache provider for source-level result caching */
+    cache?: CacheProvider;
+    /** Telemetry provider for events, spans, and error recording */
+    telemetry?: TelemetryProvider;
+}
+/**
+ * Interface for caching source lookup results.
+ *
+ * Ships with InMemoryCache. Consumers can provide RedisCache, SqliteCache,
+ * or any other implementation.
+ */
+export interface CacheProvider {
+    /** Get a cached value by key. Returns null on cache miss. */
+    get(key: string): Promise<string | null>;
+    /** Set a cached value with optional TTL in seconds. */
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    /** Delete a cached value. */
+    delete(key: string): Promise<void>;
+}
+/**
+ * A telemetry span for timing operations.
+ */
+export interface TelemetrySpan {
+    /** End the span timing. */
+    end(): void;
+    /** Attach attributes to the span (e.g., source name, cost). */
+    setAttributes(attrs: Record<string, string | number | boolean>): void;
+}
+/**
+ * Interface for recording telemetry events, spans, and errors.
+ *
+ * Ships with ConsoleTelemetry and NoopTelemetry. Consumers can provide
+ * OpenTelemetryProvider, New Relic, Datadog, etc.
+ */
+export interface TelemetryProvider {
+    /** Record a named event with arbitrary data. */
+    recordEvent(name: string, data: Record<string, unknown>): void;
+    /** Start a named timing span. Call span.end() when done. */
+    startSpan(name: string): TelemetrySpan;
+    /** Record an error with optional context. */
+    recordError(error: Error, context?: Record<string, unknown>): void;
+}
+/**
+ * Progress stats emitted during batch processing.
+ */
+export interface BatchProgressStats {
+    /** Number of subjects completed so far */
+    completed: number;
+    /** Total number of subjects in the batch */
+    total: number;
+    /** Total cost in USD so far */
+    costUsd: number;
+    /** Elapsed time in milliseconds since batch start */
+    elapsedMs: number;
+}
+/**
+ * Final stats after a batch completes.
+ */
+export interface BatchStats extends BatchProgressStats {
+    /** Number of subjects that produced a result */
+    succeeded: number;
+    /** Number of subjects that failed */
+    failed: number;
+    /** Average cost per subject in USD */
+    avgCostPerSubject: number;
+    /** Average duration per subject in milliseconds */
+    avgDurationMs: number;
+}
+/**
+ * Lifecycle hooks for observability and integration during batch processing.
+ *
+ * All hooks are optional. Consumers wire up what they need: database writes,
+ * progress bars, logging, monitoring dashboards, etc.
+ *
+ * Hook naming follows the pattern: on{Event}{Timing}
+ * - Start/Complete for paired begin/end events
+ * - No suffix for point-in-time events
+ */
+export interface LifecycleHooks<TSubject extends ResearchSubject, TOutput> {
+    /** Fired once at the start of a batch run */
+    onRunStart?(subjectCount: number, config: ResearchConfig): void;
+    /** Fired before processing each subject */
+    onSubjectStart?(subject: TSubject, index: number, total: number): void;
+    /** Fired before each source lookup */
+    onSourceAttempt?(subject: TSubject, sourceName: string, phase: number): void;
+    /** Fired after each source lookup completes (success or failure) */
+    onSourceComplete?(subject: TSubject, sourceName: string, finding: RawFinding | null, costUsd: number): void;
+    /** Fired after all sources in a phase complete */
+    onPhaseComplete?(subject: TSubject, phase: number, findingsInPhase: ScoredFinding[]): void;
+    /** Fired when early stopping is triggered */
+    onEarlyStop?(subject: TSubject, phase: number, reason: string): void;
+    /** Fired before AI synthesis begins */
+    onSynthesisStart?(subject: TSubject, findingCount: number): void;
+    /** Fired after AI synthesis completes */
+    onSynthesisComplete?(subject: TSubject, result: SynthesisResult<TOutput>): void;
+    /** Fired after processing each subject (success or failure) */
+    onSubjectComplete?(subject: TSubject, result: DebriefResult<TOutput>): void;
+    /** Fired periodically during batch processing with progress stats */
+    onBatchProgress?(stats: BatchProgressStats): void;
+    /** Fired when a cost limit is reached */
+    onCostLimitReached?(subject: TSubject, costUsd: number, limit: number): void;
+    /** Fired once when the batch run completes successfully */
+    onRunComplete?(stats: BatchStats): void;
+    /** Fired if the batch run fails with an unrecoverable error */
+    onRunFailed?(error: Error): void;
+}
+/**
+ * Error thrown when a cost limit is exceeded during research.
+ *
+ * Can be thrown for per-subject limits (stops that subject) or total batch
+ * limits (stops the entire batch).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await orchestrator.debriefBatch(subjects)
+ * } catch (error) {
+ *   if (error instanceof CostLimitExceededError) {
+ *     console.log(`Cost limit: $${error.costUsd.toFixed(4)} > $${error.limit.toFixed(4)}`)
+ *   }
+ * }
+ * ```
+ */
+export declare class CostLimitExceededError extends Error {
+    /** ID of the subject being processed when the limit was hit */
+    readonly subjectId: string | number;
+    /** The cost in USD that triggered the limit */
+    readonly costUsd: number;
+    /** The configured limit that was exceeded in USD */
+    readonly limit: number;
+    readonly name = "CostLimitExceededError";
+    constructor(
+    /** ID of the subject being processed when the limit was hit */
+    subjectId: string | number, 
+    /** The cost in USD that triggered the limit */
+    costUsd: number, 
+    /** The configured limit that was exceeded in USD */
+    limit: number);
+}
+/**
+ * Error thrown when a source request times out.
+ *
+ * The orchestrator catches this and continues with remaining sources.
+ * High-priority source timeouts may be logged for investigation.
+ *
+ * @example
+ * ```typescript
+ * throw new SourceTimeoutError("Wikipedia", 30000)
+ * ```
+ */
+export declare class SourceTimeoutError extends Error {
+    /** Name of the source that timed out */
+    readonly sourceName: string;
+    /** Timeout duration in milliseconds */
+    readonly timeoutMs: number;
+    readonly name = "SourceTimeoutError";
+    constructor(
+    /** Name of the source that timed out */
+    sourceName: string, 
+    /** Timeout duration in milliseconds */
+    timeoutMs: number);
+}
+/**
+ * Error thrown when a source access is blocked (403, 429, etc.).
+ *
+ * The orchestrator catches this and caches the blocked status to avoid
+ * re-hitting the same source. Blocked sources should be investigated
+ * for alternative access methods (browser automation, API access, etc.).
+ *
+ * @example
+ * ```typescript
+ * throw new SourceAccessBlockedError("NYTimes", 403)
+ * ```
+ */
+export declare class SourceAccessBlockedError extends Error {
+    /** Name of the source that blocked access */
+    readonly sourceName: string;
+    /** HTTP status code (403, 429, etc.) */
+    readonly statusCode: number;
+    readonly name = "SourceAccessBlockedError";
+    constructor(
+    /** Name of the source that blocked access */
+    sourceName: string, 
+    /** HTTP status code (403, 429, etc.) */
+    statusCode: number);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAMvD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,eAAe,EAAE,eAAe,CAAA;IAChC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO;IACtC,+CAA+C;IAC/C,IAAI,EAAE,OAAO,CAAA;IACb,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ,SAAS,eAAe,EAAE,OAAO;IACpE,UAAU,CACR,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAA;CACrC;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,SAAS,eAAe;IAC7D,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qDAAqD;IACrD,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IACzC,sCAAsC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,sCAAsC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,mEAAmE;IACnE,WAAW,IAAI,OAAO,CAAA;IACtB;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;CAC3E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,SAAS,eAAe;IAChE,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8GAA8G;IAC9G,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC/C;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO;IACpC,sCAAsC;IACtC,OAAO,EAAE,eAAe,CAAA;IACxB,qEAAqE;IACrE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACpB,sDAAsD;IACtD,QAAQ,EAAE,aAAa,EAAE,CAAA;IACzB,oEAAoE;IACpE,eAAe,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;IAC1C,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,gBAAgB,EAAE,MAAM,CAAA;IACxB,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAA;IACxB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAA;CACnB;AAMD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,8EAA8E;IAC9E,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,8CAA8C;IAC9C,UAAU,CAAC,EAAE;QACX,sEAAsE;QACtE,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,uEAAuE;QACvE,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,2BAA2B;IAC3B,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B,qDAAqD;IACrD,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,gEAAgE;IAChE,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAC9B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,uDAAuD;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnE,6BAA6B;IAC7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,GAAG,IAAI,IAAI,CAAA;IACX,+DAA+D;IAC/D,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAA;CACtE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9D,4DAA4D;IAC5D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IACtC,6CAA6C;IAC7C,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACnE;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IACpD,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAA;IACzB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAA;CACtB;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,SAAS,eAAe,EAAE,OAAO;IACvE,6CAA6C;IAC7C,UAAU,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAA;IAC/D,2CAA2C;IAC3C,cAAc,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACtE,sCAAsC;IACtC,eAAe,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5E,oEAAoE;IACpE,gBAAgB,CAAC,CACf,OAAO,EAAE,QAAQ,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,UAAU,GAAG,IAAI,EAC1B,OAAO,EAAE,MAAM,GACd,IAAI,CAAA;IACP,kDAAkD;IAClD,eAAe,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,GAAG,IAAI,CAAA;IAC1F,6CAA6C;IAC7C,WAAW,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACpE,uCAAuC;IACvC,gBAAgB,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAChE,yCAAyC;IACzC,mBAAmB,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IAC/E,+DAA+D;IAC/D,iBAAiB,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IAC3E,qEAAqE;IACrE,eAAe,CAAC,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;IACjD,yCAAyC;IACzC,kBAAkB,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5E,2DAA2D;IAC3D,aAAa,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACvC,+DAA+D;IAC/D,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACjC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAI7C,+DAA+D;aAC/C,SAAS,EAAE,MAAM,GAAG,MAAM;IAC1C,+CAA+C;aAC/B,OAAO,EAAE,MAAM;IAC/B,oDAAoD;aACpC,KAAK,EAAE,MAAM;IAR/B,QAAQ,CAAC,IAAI,4BAA2B;;IAGtC,+DAA+D;IAC/C,SAAS,EAAE,MAAM,GAAG,MAAM;IAC1C,+CAA+C;IAC/B,OAAO,EAAE,MAAM;IAC/B,oDAAoD;IACpC,KAAK,EAAE,MAAM;CAMhC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,wCAAwC;aACxB,UAAU,EAAE,MAAM;IAClC,uCAAuC;aACvB,SAAS,EAAE,MAAM;IANnC,QAAQ,CAAC,IAAI,wBAAuB;;IAGlC,wCAAwC;IACxB,UAAU,EAAE,MAAM;IAClC,uCAAuC;IACvB,SAAS,EAAE,MAAM;CAIpC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAI/C,6CAA6C;aAC7B,UAAU,EAAE,MAAM;IAClC,wCAAwC;aACxB,UAAU,EAAE,MAAM;IANpC,QAAQ,CAAC,IAAI,8BAA6B;;IAGxC,6CAA6C;IAC7B,UAAU,EAAE,MAAM;IAClC,wCAAwC;IACxB,UAAU,EAAE,MAAM;CAIrC"}

package/dist/types.js

@@ -0,0 +1,102 @@
+/**
+ * Core type definitions for the debriefer research orchestration engine.
+ *
+ * These types are generalized from deadonfilm's death-sources/types.ts and
+ * biography-sources/types.ts. They define the contracts for subjects, findings,
+ * sources, synthesis, configuration, lifecycle hooks, and error types that
+ * the orchestrator and all source implementations share.
+ *
+ * Domain-specific types (e.g., ActorForEnrichment, BiographyData) live in
+ * consumer code, not here. Consumers extend ResearchSubject and provide their
+ * own TOutput type to the orchestrator.
+ */
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Error thrown when a cost limit is exceeded during research.
+ *
+ * Can be thrown for per-subject limits (stops that subject) or total batch
+ * limits (stops the entire batch).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await orchestrator.debriefBatch(subjects)
+ * } catch (error) {
+ *   if (error instanceof CostLimitExceededError) {
+ *     console.log(`Cost limit: $${error.costUsd.toFixed(4)} > $${error.limit.toFixed(4)}`)
+ *   }
+ * }
+ * ```
+ */
+export class CostLimitExceededError extends Error {
+    subjectId;
+    costUsd;
+    limit;
+    name = "CostLimitExceededError";
+    constructor(
+    /** ID of the subject being processed when the limit was hit */
+    subjectId, 
+    /** The cost in USD that triggered the limit */
+    costUsd, 
+    /** The configured limit that was exceeded in USD */
+    limit) {
+        super(`Cost limit exceeded for subject ${subjectId}: $${costUsd.toFixed(4)} > $${limit.toFixed(4)}`);
+        this.subjectId = subjectId;
+        this.costUsd = costUsd;
+        this.limit = limit;
+    }
+}
+/**
+ * Error thrown when a source request times out.
+ *
+ * The orchestrator catches this and continues with remaining sources.
+ * High-priority source timeouts may be logged for investigation.
+ *
+ * @example
+ * ```typescript
+ * throw new SourceTimeoutError("Wikipedia", 30000)
+ * ```
+ */
+export class SourceTimeoutError extends Error {
+    sourceName;
+    timeoutMs;
+    name = "SourceTimeoutError";
+    constructor(
+    /** Name of the source that timed out */
+    sourceName, 
+    /** Timeout duration in milliseconds */
+    timeoutMs) {
+        super(`Source ${sourceName} timed out after ${timeoutMs}ms`);
+        this.sourceName = sourceName;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Error thrown when a source access is blocked (403, 429, etc.).
+ *
+ * The orchestrator catches this and caches the blocked status to avoid
+ * re-hitting the same source. Blocked sources should be investigated
+ * for alternative access methods (browser automation, API access, etc.).
+ *
+ * @example
+ * ```typescript
+ * throw new SourceAccessBlockedError("NYTimes", 403)
+ * ```
+ */
+export class SourceAccessBlockedError extends Error {
+    sourceName;
+    statusCode;
+    name = "SourceAccessBlockedError";
+    constructor(
+    /** Name of the source that blocked access */
+    sourceName, 
+    /** HTTP status code (403, 429, etc.) */
+    statusCode) {
+        super(`Source ${sourceName} blocked with status ${statusCode}`);
+        this.sourceName = sourceName;
+        this.statusCode = statusCode;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwYH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAK7B;IAEA;IAEA;IART,IAAI,GAAG,wBAAwB,CAAA;IAExC;IACE,+DAA+D;IAC/C,SAA0B;IAC1C,+CAA+C;IAC/B,OAAe;IAC/B,oDAAoD;IACpC,KAAa;QAE7B,KAAK,CACH,mCAAmC,SAAS,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAC9F,CAAA;QARe,cAAS,GAAT,SAAS,CAAiB;QAE1B,YAAO,GAAP,OAAO,CAAQ;QAEf,UAAK,GAAL,KAAK,CAAQ;IAK/B,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAKzB;IAEA;IANT,IAAI,GAAG,oBAAoB,CAAA;IAEpC;IACE,wCAAwC;IACxB,UAAkB;IAClC,uCAAuC;IACvB,SAAiB;QAEjC,KAAK,CAAC,UAAU,UAAU,oBAAoB,SAAS,IAAI,CAAC,CAAA;QAJ5C,eAAU,GAAV,UAAU,CAAQ;QAElB,cAAS,GAAT,SAAS,CAAQ;IAGnC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAK/B;IAEA;IANT,IAAI,GAAG,0BAA0B,CAAA;IAE1C;IACE,6CAA6C;IAC7B,UAAkB;IAClC,wCAAwC;IACxB,UAAkB;QAElC,KAAK,CAAC,UAAU,UAAU,wBAAwB,UAAU,EAAE,CAAC,CAAA;QAJ/C,eAAU,GAAV,UAAU,CAAQ;QAElB,eAAU,GAAV,UAAU,CAAQ;IAGpC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@debriefer/core",
+  "version": "2.0.0",
+  "description": "Multi-source research orchestration engine with reliability scoring, phase-based execution, and pluggable synthesis",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "research",
+    "orchestration",
+    "multi-source",
+    "reliability",
+    "web-scraping",
+    "ai",
+    "enrichment"
+  ],
+  "author": "Chris Henderson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenders/debriefer.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/chenders/debriefer#readme",
+  "bugs": {
+    "url": "https://github.com/chenders/debriefer/issues"
+  },
+  "dependencies": {
+    "p-limit": "^6"
+  }
+}