@absolutejs/rag 0.17.0 → 0.18.1

package/dist/src/angular/index.d.ts

@@ -1,3 +1,4 @@
 export { RAGWorkflowService } from "./ai-rag-workflow.service";
 export { RAGStreamService } from "./ai-rag-stream.service";
 export { RAGClientService } from "./rag-client.service";
+export * from "./research.service";

package/dist/src/angular/research.service.d.ts

@@ -0,0 +1,12 @@
+import { type DestroyRef } from "@angular/core";
+export declare class ResearchService {
+    connect(path?: string, destroyRef?: DestroyRef): {
+        state: import("@angular/core").Signal<import("../client").ResearchState>;
+        dispose: () => void;
+        run: (input: import("../client").ResearchRequest) => Promise<import("../research").ResearchResult>;
+        cancel: () => void;
+        getSnapshot: () => import("../client").ResearchState;
+        subscribe: (listener: () => void) => () => void;
+        reset: () => void;
+    };
+}

package/dist/src/client/index.d.ts

@@ -7,3 +7,4 @@ export { buildRAGMaintenanceOverview, createRAGClient } from "./ragClient";
 export type { RAGClient } from "./ragClient";
 export type { RAGClientOptions, RAGDetailedSearchResponse, RAGMaintenanceActionDescriptor, RAGMaintenanceOverview, RAGMaintenancePayload, } from "../../types/client";
 export { buildRAGEvaluationLeaderboard, createRAGEvaluationSuite, runRAGEvaluationSuite, } from "../quality/quality";
+export * from "./research";

package/dist/src/client/research.d.ts

@@ -0,0 +1,30 @@
+import type { ResearchInput, ResearchResult, ResearchProgress } from "../research/types";
+export type ResearchRequest = Pick<ResearchInput, "query" | "task" | "freshness">;
+export type ResearchState = {
+    status: "idle" | "running" | "complete" | "cancelled" | "error";
+    result: ResearchResult | null;
+    progress: ResearchProgress | null;
+    error: string | null;
+};
+export type ResearchClientOptions = {
+    path?: string;
+    fetch?: typeof fetch;
+    headers?: () => HeadersInit;
+};
+export declare const createResearchClient: (options?: ResearchClientOptions) => {
+    run: (input: ResearchRequest) => Promise<ResearchResult>;
+    cancel: () => void;
+    getSnapshot: () => ResearchState;
+    subscribe: (listener: () => void) => () => void;
+    reset: () => void;
+    dispose: () => void;
+};
+/** HTML binding uses textContent, never model-produced HTML. Returns cleanup. */
+export declare const bindResearchForm: (form: HTMLFormElement, output: HTMLElement, options?: ResearchClientOptions) => {
+    dispose: () => void;
+    run: (input: ResearchRequest) => Promise<ResearchResult>;
+    cancel: () => void;
+    getSnapshot: () => ResearchState;
+    subscribe: (listener: () => void) => () => void;
+    reset: () => void;
+};

package/dist/src/react/index.d.ts

@@ -16,3 +16,4 @@ export type { UseRAGStreamResult } from "./useRAGStream";
 export type { UseRAGStreamProgressResult } from "./useRAGStreamProgress";
 export { useRAGSources } from "./useRAGSources";
 export { useRAGStatus } from "./useRAGStatus";
+export * from "./useResearch";

package/dist/src/react/useResearch.d.ts

@@ -0,0 +1,9 @@
+export declare const useResearch: (path?: string) => {
+    state: import("../client").ResearchState;
+    run: (input: import("../client").ResearchRequest) => Promise<import("../research").ResearchResult>;
+    cancel: () => void;
+    getSnapshot: () => import("../client").ResearchState;
+    subscribe: (listener: () => void) => () => void;
+    reset: () => void;
+    dispose: () => void;
+};

package/dist/src/research/budget.d.ts

@@ -0,0 +1,26 @@
+import type { ResearchConfig, ResearchOperation } from "./types";
+type Admission = NonNullable<ResearchConfig["admit"]>;
+type Outcome = Parameters<Exclude<Awaited<ReturnType<Admission>>, false>["settle"]>[0];
+/** Structural adapter for @absolutejs/billing/provider-budget; no second ledger. */
+export type ResearchBudgetConfig = {
+    ledger: {
+        reserve: (input: {
+            id: string;
+            scope: string;
+            period: string;
+            reserveMicros: number;
+            maxMicros: number;
+            maxRequests: number;
+        }) => Promise<boolean>;
+        settle: (id: string, status: "fulfilled" | "rejected" | "unknown", actualMicros: number | null) => Promise<void>;
+    };
+    scope: string;
+    period: () => string;
+    maxMicros: number;
+    maxRequests: number;
+    /** Conservative ceilings for configured models, token limits, search and reader. */
+    reserveMicros: Record<ResearchOperation, number>;
+    actualMicros: (kind: ResearchOperation, outcome: Outcome) => number | null;
+};
+export declare const createResearchBudgetAdmission: (config: ResearchBudgetConfig) => Admission;
+export {};

package/dist/src/research/evaluation.d.ts

@@ -0,0 +1,42 @@
+import type { RAGAnswerGroundingEvaluationCase } from "../../types/engine";
+import type { ResearchInput, ResearchResult, ResearchRuntime } from "./types";
+/** Feed research evidence into the existing @absolutejs/rag/quality evaluators. */
+export declare const researchGroundingCase: (id: string, query: string, result: ResearchResult, expectedSources?: string[]) => RAGAnswerGroundingEvaluationCase;
+export type ResearchAcceptance = {
+    accepted: number;
+    rejected: number;
+    reviewMs: number;
+    reviewer: string;
+};
+export type ResearchEvaluationCase = {
+    id: string;
+    input: Pick<ResearchInput, "query" | "task" | "freshness">;
+    expectedSources?: string[];
+    publishedAfter?: string;
+};
+export declare const evaluateResearch: (options: {
+    runtime: ResearchRuntime;
+    cases: ResearchEvaluationCase[];
+    signal?: AbortSignal;
+    /** Supply independent human decisions; absence means unreviewed, never zero errors. */
+    review?: (test: ResearchEvaluationCase, result: ResearchResult) => Promise<ResearchAcceptance>;
+    /** Total cost must include search, reads, planning, extraction, review and failed attempts. */
+    cost?: (result: ResearchResult) => Promise<number | null>;
+}) => Promise<{
+    cases: {
+        id: string;
+        result: ResearchResult<unknown>;
+        durationMs: number;
+        acceptance: ResearchAcceptance | null;
+        costUsd: number | null;
+        costPerAcceptedFinding: number | null;
+        publicationFreshness: {
+            dated: number;
+            fresh: number;
+            unknown: number;
+        } | null;
+        groundingCase: RAGAnswerGroundingEvaluationCase;
+    }[];
+    independentlyReviewed: number;
+    totalCostUsd: number | null;
+}>;

package/dist/src/research/evidence.d.ts

@@ -0,0 +1,21 @@
+import { type SearchSource } from "@absolutejs/search";
+import type { ResearchField } from "./types";
+export declare const ReviewSchema: import("@sinclair/typebox").TObject<{
+    fields: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        path: import("@sinclair/typebox").TString;
+        verdict: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"unknown" | "supported" | "unsupported" | "conflicting">[]>;
+        citations: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            sourceId: import("@sinclair/typebox").TString;
+            quote: import("@sinclair/typebox").TString;
+        }>>;
+        reason: import("@sinclair/typebox").TString;
+    }>>;
+}>;
+export declare const researchLeaves: (value: unknown, maxFields?: number) => Pick<ResearchField, "value" | "path">[];
+/** A model review is fallible. Citation validation proves provenance, not truth. */
+export declare const bindResearchReview: (leaves: ReturnType<typeof researchLeaves>, reviews: {
+    path: string;
+    verdict: ResearchField["verdict"];
+    citations: ResearchField["citations"];
+    reason: string;
+}[], sources: SearchSource[]) => ResearchField[];

package/dist/src/research/index.d.ts

@@ -0,0 +1,9 @@
+export { createResearch } from "./runtime";
+export { researchPlugin, renderResearchResult, type ResearchPluginOptions, } from "./plugin";
+export { bindResearchReview, researchLeaves } from "./evidence";
+export type * from "./types";
+export * from "./store";
+export * from "./workflows";
+export { researchManifest } from "./manifest";
+export * from "./evaluation";
+export * from "./budget";

package/dist/src/research/manifest.d.ts

@@ -0,0 +1,18 @@
+import type { ResearchConfig, ResearchRuntime } from "./types";
+export declare const researchManifest: Omit<import("@absolutejs/manifest").PackageManifest<ResearchConfig, ResearchRuntime>, "tools" | "contract" | "settings"> & (({
+    contract: 1;
+    tools?: Record<string, import("@absolutejs/manifest").LegacyManifestTool<ResearchRuntime>> | undefined;
+} | {
+    contract: 2;
+    tools?: Record<string, import("@absolutejs/manifest").AuthorizedManifestTool<ResearchRuntime>> | undefined;
+}) & {
+    settings: import("@sinclair/typebox").TObject<{
+        model: import("@sinclair/typebox").TString;
+        limits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            searches: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+            reads: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+            rounds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+            timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        }>>;
+    }>;
+});

package/dist/src/research/plugin.d.ts

@@ -0,0 +1,230 @@
+import type { ResearchRuntime, ResearchResult } from "./types";
+export declare const renderResearchResult: (result: ResearchResult) => string;
+export type ResearchPluginOptions = {
+    runtime: ResearchRuntime | ((request: Request) => ResearchRuntime | Promise<ResearchRuntime>);
+    /** Required for all routes, including HTML and streaming. Resolve identity before selecting tenant runtime. */
+    authorize: (request: Request) => boolean | Promise<boolean>;
+    path?: string;
+};
+export declare const researchPlugin: (options: ResearchPluginOptions) => import("elysia/types").AddRoute<"", "local", import("elysia/types").DefaultSingleton, {
+    typebox: {};
+    error: [];
+}, import("elysia/types").DefaultMetadata, {
+    [x: string]: {
+        post: {
+            body: {
+                task?: string | undefined;
+                freshness?: string | undefined;
+                query: string;
+            };
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+                422: {
+                    type: "validation";
+                    title: "Validation Error";
+                    status: 422;
+                    detail?: string;
+                    on: string;
+                    found?: unknown;
+                    property?: string;
+                    expected?: string;
+                };
+            };
+            error: never;
+        };
+    };
+} & {
+    [x: string]: {
+        html: {
+            post: {
+                body: {
+                    task?: string | undefined;
+                    freshness?: string | undefined;
+                    query: string;
+                };
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: Response;
+                    422: {
+                        type: "validation";
+                        title: "Validation Error";
+                        status: 422;
+                        detail?: string;
+                        on: string;
+                        found?: unknown;
+                        property?: string;
+                        expected?: string;
+                    };
+                };
+                error: never;
+            };
+        };
+    };
+}, import("elysia/types").DefaultEphemeral, import("elysia/types").DefaultEphemeral, "post", `${string}/stream`, import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<{
+    body: import("typebox").TObject<{
+        query: import("typebox").TString;
+        task: import("typebox").TOptional<import("typebox").TString>;
+        freshness: import("typebox").TOptional<import("typebox").TString>;
+    }>;
+}, {}, `/${string}/stream`>, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>, {}, ({ request, body }: {
+    body: {
+        task?: string | undefined;
+        freshness?: string | undefined;
+        query: string;
+    };
+    query: Record<string, string | undefined>;
+    params: {};
+    headers: Record<string, string | undefined>;
+    cookie: Record<string, import("elysia").Cookie<unknown>>;
+    server: import("elysia").Server | null;
+    redirect: import("elysia").redirect;
+    set: {
+        headers: import("elysia").HTTPHeaders;
+        status?: number | keyof import("elysia").StatusMap;
+        cookie?: Record<string, import("elysia").BaseCookie>;
+    };
+    status: <const Code extends number | keyof import("elysia").StatusMap, const T = Code extends 500 | 100 | 200 | 400 | 404 | 300 | 101 | 102 | 103 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 301 | 302 | 303 | 304 | 307 | 308 | 401 | 402 | 403 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 ? {
+        readonly 100: "Continue";
+        readonly 101: "Switching Protocols";
+        readonly 102: "Processing";
+        readonly 103: "Early Hints";
+        readonly 200: "OK";
+        readonly 201: "Created";
+        readonly 202: "Accepted";
+        readonly 203: "Non-Authoritative Information";
+        readonly 204: "No Content";
+        readonly 205: "Reset Content";
+        readonly 206: "Partial Content";
+        readonly 207: "Multi-Status";
+        readonly 208: "Already Reported";
+        readonly 300: "Multiple Choices";
+        readonly 301: "Moved Permanently";
+        readonly 302: "Found";
+        readonly 303: "See Other";
+        readonly 304: "Not Modified";
+        readonly 307: "Temporary Redirect";
+        readonly 308: "Permanent Redirect";
+        readonly 400: "Bad Request";
+        readonly 401: "Unauthorized";
+        readonly 402: "Payment Required";
+        readonly 403: "Forbidden";
+        readonly 404: "Not Found";
+        readonly 405: "Method Not Allowed";
+        readonly 406: "Not Acceptable";
+        readonly 407: "Proxy Authentication Required";
+        readonly 408: "Request Timeout";
+        readonly 409: "Conflict";
+        readonly 410: "Gone";
+        readonly 411: "Length Required";
+        readonly 412: "Precondition Failed";
+        readonly 413: "Payload Too Large";
+        readonly 414: "URI Too Long";
+        readonly 415: "Unsupported Media Type";
+        readonly 416: "Range Not Satisfiable";
+        readonly 417: "Expectation Failed";
+        readonly 418: "I'm a teapot";
+        readonly 420: "Enhance Your Calm";
+        readonly 421: "Misdirected Request";
+        readonly 422: "Unprocessable Content";
+        readonly 423: "Locked";
+        readonly 424: "Failed Dependency";
+        readonly 425: "Too Early";
+        readonly 426: "Upgrade Required";
+        readonly 428: "Precondition Required";
+        readonly 429: "Too Many Requests";
+        readonly 431: "Request Header Fields Too Large";
+        readonly 451: "Unavailable For Legal Reasons";
+        readonly 500: "Internal Server Error";
+        readonly 501: "Not Implemented";
+        readonly 502: "Bad Gateway";
+        readonly 503: "Service Unavailable";
+        readonly 504: "Gateway Timeout";
+        readonly 505: "HTTP Version Not Supported";
+        readonly 506: "Variant Also Negotiates";
+        readonly 507: "Insufficient Storage";
+        readonly 508: "Loop Detected";
+        readonly 510: "Not Extended";
+        readonly 511: "Network Authentication Required";
+    }[Code] : Code>(code: Code, response?: T) => import("elysia").ElysiaStatus<Code, T, Code extends "Continue" | "Switching Protocols" | "Processing" | "Early Hints" | "OK" | "Created" | "Accepted" | "Non-Authoritative Information" | "No Content" | "Reset Content" | "Partial Content" | "Multi-Status" | "Already Reported" | "Multiple Choices" | "Moved Permanently" | "Found" | "See Other" | "Not Modified" | "Temporary Redirect" | "Permanent Redirect" | "Bad Request" | "Unauthorized" | "Payment Required" | "Forbidden" | "Not Found" | "Method Not Allowed" | "Not Acceptable" | "Proxy Authentication Required" | "Request Timeout" | "Conflict" | "Gone" | "Length Required" | "Precondition Failed" | "Payload Too Large" | "URI Too Long" | "Unsupported Media Type" | "Range Not Satisfiable" | "Expectation Failed" | "I'm a teapot" | "Enhance Your Calm" | "Misdirected Request" | "Unprocessable Content" | "Locked" | "Failed Dependency" | "Too Early" | "Upgrade Required" | "Precondition Required" | "Too Many Requests" | "Request Header Fields Too Large" | "Unavailable For Legal Reasons" | "Internal Server Error" | "Not Implemented" | "Bad Gateway" | "Service Unavailable" | "Gateway Timeout" | "HTTP Version Not Supported" | "Variant Also Negotiates" | "Insufficient Storage" | "Loop Detected" | "Not Extended" | "Network Authentication Required" ? {
+        readonly Continue: 100;
+        readonly "Switching Protocols": 101;
+        readonly Processing: 102;
+        readonly "Early Hints": 103;
+        readonly OK: 200;
+        readonly Created: 201;
+        readonly Accepted: 202;
+        readonly "Non-Authoritative Information": 203;
+        readonly "No Content": 204;
+        readonly "Reset Content": 205;
+        readonly "Partial Content": 206;
+        readonly "Multi-Status": 207;
+        readonly "Already Reported": 208;
+        readonly "Multiple Choices": 300;
+        readonly "Moved Permanently": 301;
+        readonly Found: 302;
+        readonly "See Other": 303;
+        readonly "Not Modified": 304;
+        readonly "Temporary Redirect": 307;
+        readonly "Permanent Redirect": 308;
+        readonly "Bad Request": 400;
+        readonly Unauthorized: 401;
+        readonly "Payment Required": 402;
+        readonly Forbidden: 403;
+        readonly "Not Found": 404;
+        readonly "Method Not Allowed": 405;
+        readonly "Not Acceptable": 406;
+        readonly "Proxy Authentication Required": 407;
+        readonly "Request Timeout": 408;
+        readonly Conflict: 409;
+        readonly Gone: 410;
+        readonly "Length Required": 411;
+        readonly "Precondition Failed": 412;
+        readonly "Payload Too Large": 413;
+        readonly "URI Too Long": 414;
+        readonly "Unsupported Media Type": 415;
+        readonly "Range Not Satisfiable": 416;
+        readonly "Expectation Failed": 417;
+        readonly "I'm a teapot": 418;
+        readonly "Enhance Your Calm": 420;
+        readonly "Misdirected Request": 421;
+        readonly "Unprocessable Content": 422;
+        readonly Locked: 423;
+        readonly "Failed Dependency": 424;
+        readonly "Too Early": 425;
+        readonly "Upgrade Required": 426;
+        readonly "Precondition Required": 428;
+        readonly "Too Many Requests": 429;
+        readonly "Request Header Fields Too Large": 431;
+        readonly "Unavailable For Legal Reasons": 451;
+        readonly "Internal Server Error": 500;
+        readonly "Not Implemented": 501;
+        readonly "Bad Gateway": 502;
+        readonly "Service Unavailable": 503;
+        readonly "Gateway Timeout": 504;
+        readonly "HTTP Version Not Supported": 505;
+        readonly "Variant Also Negotiates": 506;
+        readonly "Insufficient Storage": 507;
+        readonly "Loop Detected": 508;
+        readonly "Not Extended": 510;
+        readonly "Network Authentication Required": 511;
+    }[Code] : Code>;
+    defer: (fn: import("elysia/types").AfterResponseHandler<NoInfer<import("elysia/types").IntersectIfObjectSchema<import("elysia").UnwrapRoute<{
+        body: import("typebox").TObject<{
+            query: import("typebox").TString;
+            task: import("typebox").TOptional<import("typebox").TString>;
+            freshness: import("typebox").TOptional<import("typebox").TString>;
+        }>;
+    }, {}, `/${string}/stream`>, import("elysia/types").MergeScopedSchemas<{}, {}, {}>>>, NoInfer<import("elysia/types").DefaultSingleton & {
+        derive: {};
+    }>>) => import("elysia/types").MaybePromise<void>;
+    readonly path: string;
+    route?: string | undefined;
+    rid?: string | undefined;
+    request: Request;
+    store: {};
+}) => Promise<Response>>;

package/dist/src/research/runtime.d.ts

@@ -0,0 +1,2 @@
+import type { ResearchConfig, ResearchRuntime } from "./types";
+export declare const createResearch: (config: ResearchConfig) => ResearchRuntime;

package/dist/src/research/schema.d.ts

@@ -0,0 +1,8 @@
+import { type TSchema, type Static as LegacyStatic } from "@sinclair/typebox";
+import type { Static } from "typebox";
+/** JSON-compatible TypeBox 0.34 or TypeBox 1 schemas, including Elysia 2's t. */
+export type ResearchSchema = TSchema | {
+    "~kind": string;
+};
+export type ResearchStatic<S extends ResearchSchema> = S extends TSchema ? LegacyStatic<S> : Static<S>;
+export declare const checkResearchValue: <S extends ResearchSchema>(schema: S, value: unknown) => value is ResearchStatic<S>;

package/dist/src/research/store.d.ts

@@ -0,0 +1,29 @@
+export type ResearchCheckpoint = {
+    revision: number;
+    value: unknown;
+    fingerprint: string;
+};
+export type ResearchClaim = ResearchCheckpoint & {
+    token: string;
+};
+export type ResearchDelivery = {
+    id: string;
+    key: string;
+    payload: unknown;
+};
+export type ResearchWorkflowStore = {
+    claim: (key: string, fingerprint: string, leaseMs: number) => Promise<ResearchClaim | null>;
+    /** Commit state and append delivery records atomically, fenced against lease expiry and takeover. */
+    commit: (key: string, claim: ResearchClaim, value: unknown, events?: ResearchDelivery[]) => Promise<boolean>;
+    release: (key: string, token: string) => Promise<void>;
+    deliveries: (key: string, limit: number) => Promise<ResearchDelivery[]>;
+    acknowledge: (key: string, id: string) => Promise<void>;
+};
+export declare const researchKey: (value: unknown) => Promise<string>;
+export declare const createMemoryResearchWorkflowStore: (now?: () => number) => ResearchWorkflowStore;
+export type ResearchSqlClient = {
+    unsafe: (query: string, parameters?: unknown[]) => PromiseLike<Record<string, unknown>[]>;
+};
+export declare const researchWorkflowPostgresSchemaSql: () => string;
+/** SQL operations use database time and one fenced statement for state plus outbox. */
+export declare const createPostgresResearchWorkflowStore: (sql: ResearchSqlClient) => ResearchWorkflowStore;

package/dist/src/research/types.d.ts

@@ -0,0 +1,96 @@
+import type { AIProviderConfig, AIUsage } from "@absolutejs/ai";
+import type { SearchProvider, SearchResult, SearchSource, SearchCacheStore } from "@absolutejs/search";
+import type { ResearchSchema, ResearchStatic } from "./schema";
+export type { ResearchSchema, ResearchStatic } from "./schema";
+import type { ReadWebpageOptions, WebReadResult } from "../web";
+export type ResearchOperation = "search" | "read" | "plan" | "extract" | "review";
+export type ResearchProgress = {
+    phase: ResearchOperation | "complete";
+    completed: number;
+    limit: number;
+};
+export type ResearchField = {
+    /** RFC 6901 JSON pointer, including array indices. */
+    path: string;
+    value: string | number | boolean | null;
+    verdict: "supported" | "unsupported" | "conflicting" | "unknown";
+    citations: {
+        sourceId: string;
+        quote: string;
+    }[];
+    reason: string;
+};
+export type ResearchResult<T = unknown> = {
+    id: string;
+    status: "reviewed" | "partial" | "empty" | "unavailable";
+    /** Only populated when every primitive field passed evidence review. */
+    data: T | null;
+    fields: ResearchField[];
+    sources: SearchSource[];
+    searches: SearchResult[];
+    limitations: string[];
+    generatedAt: string;
+    operations: {
+        kind: ResearchOperation;
+        status: "fulfilled" | "unknown";
+        usage?: AIUsage;
+        durationMs: number;
+    }[];
+};
+export type ResearchTask<S extends ResearchSchema = ResearchSchema> = {
+    schema: S;
+    instructions?: string;
+};
+export type ResearchInput = {
+    queries?: string[];
+    requiredPhrases?: string[];
+    query: string;
+    task?: string;
+    freshness?: string;
+    signal?: AbortSignal;
+    onProgress?: (event: ResearchProgress) => void;
+};
+export type ResearchLimits = {
+    searches: number;
+    reads: number;
+    rounds: number;
+    timeoutMs: number;
+    evidenceChars: number;
+    outputTokens: number;
+    fields: number;
+};
+export type ResearchConfig = {
+    /** Optional host accounting adapter; defaults to the standard AI generator. */
+    generateObject?: typeof import("@absolutejs/ai").generateObjectAI;
+    budget?: import("./budget").ResearchBudgetConfig;
+    search: SearchProvider;
+    provider: AIProviderConfig;
+    model: string;
+    tasks?: Record<string, ResearchTask>;
+    limits?: Partial<ResearchLimits>;
+    /** Explicit shared-public or tenant scope. Omit to disable search caching. */
+    cache?: {
+        scope: string;
+        store?: SearchCacheStore;
+        ttlMs?: number;
+        capacity?: number;
+    };
+    reader?: (options: ReadWebpageOptions) => Promise<WebReadResult>;
+    render?: ReadWebpageOptions["render"];
+    /** Called before each operation. May atomically reserve tenant budget or deny. */
+    admit?: (operation: {
+        runId: string;
+        kind: ResearchOperation;
+        signal: AbortSignal;
+    }) => Promise<false | {
+        settle: (outcome: {
+            status: "fulfilled" | "unknown";
+            usage?: AIUsage;
+            search?: SearchResult;
+        }) => Promise<void>;
+    }>;
+};
+export type ResearchRuntime = {
+    run: (input: ResearchInput) => Promise<ResearchResult>;
+    extract: <S extends ResearchSchema>(task: ResearchTask<S>, input: ResearchInput) => Promise<ResearchResult<ResearchStatic<S>>>;
+};

package/dist/src/research/workflows.d.ts

@@ -0,0 +1,96 @@
+import type { ResearchResult, ResearchRuntime } from "./types";
+import { type ResearchWorkflowStore, type ResearchDelivery } from "./store";
+export type ResearchCriterion = {
+    id: string;
+    description: string;
+};
+export type ResearchCandidate = {
+    name: string;
+    domain: string;
+    evidence: ResearchResult;
+    criteria: {
+        id: string;
+        verdict: "matched" | "not_matched" | "unknown";
+        evidence: ResearchResult;
+    }[];
+};
+export declare const discoverResearchCompanies: (runtime: ResearchRuntime, input: {
+    query: string;
+    criteria: ResearchCriterion[];
+    limit?: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    discovery: ResearchResult<{
+        companies: {
+            name: string;
+            domain: string;
+        }[];
+    }>;
+    candidates: ResearchCandidate[];
+    accepted: ResearchCandidate[];
+}>;
+export type ResearchBatchItem = {
+    id: string;
+    query: string;
+    task?: string;
+    freshness?: string;
+};
+export type ResearchMonitorEvent = {
+    id: string;
+    occurredAt: string;
+    fields: string[];
+    payload: unknown;
+};
+export declare const createResearchWorkflows: (options: {
+    runtime: ResearchRuntime;
+    store: ResearchWorkflowStore;
+    scope: string;
+    version: string;
+    leaseMs?: number;
+    now?: () => number;
+}) => {
+    batch(input: {
+        id: string;
+        items: ResearchBatchItem[];
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+        status: "complete" | "busy" | "lease_lost";
+        result?: ResearchResult;
+    }[]>;
+    /** Schedule this function using the existing Queue/cron infrastructure. It owns no timer. */
+    monitor(input: {
+        id: string;
+        query: string;
+        task?: string;
+        freshness?: string;
+        signal?: AbortSignal;
+        select: (result: ResearchResult) => ResearchMonitorEvent[];
+    }): Promise<{
+        status: "busy";
+        events: number;
+        result?: undefined;
+    } | {
+        status: "incomplete";
+        events: number;
+        result: ResearchResult<unknown>;
+    } | {
+        status: "updated" | "baseline" | "lease_lost";
+        events: number;
+        result: ResearchResult<unknown>;
+    }>;
+    /** Delivery is at-least-once: the receiver MUST deduplicate using event.id. */
+    deliverMonitor(id: string, deliver: (event: ResearchDelivery) => Promise<void>): Promise<number>;
+};
+export declare const researchMonitorTask: {
+    schema: import("@sinclair/typebox").TObject<{
+        events: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            entity: import("@sinclair/typebox").TString;
+            type: import("@sinclair/typebox").TString;
+            occurredAt: import("@sinclair/typebox").TString;
+            summary: import("@sinclair/typebox").TString;
+        }>>;
+    }>;
+    instructions: string;
+};
+export declare const selectResearchMonitorEvents: (result: ResearchResult) => ResearchMonitorEvent[];