@inflexa-ai/harness 0.16.0 → 0.17.0

package/dist/citations/types.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+export const CitationKindSchema = z.enum(["doi", "pmid", "arxiv", "free_text", "auto"]);
+export const CitationInputSchema = z.object({
+    citation: z.string().trim().min(1).max(5_000),
+    kind: CitationKindSchema.optional(),
+    title: z.string().trim().min(1).max(2_000).optional(),
+    authors: z.array(z.string().trim().min(1).max(500)).max(500).optional(),
+    year: z.number().int().min(1000).max(3000).optional(),
+    venue: z.string().trim().min(1).max(1_000).optional(),
+    volume: z.string().trim().min(1).max(100).optional(),
+    firstPage: z.string().trim().min(1).max(100).optional(),
+});
+export const CitationSourceSchema = z.enum(["doi_registry", "crossref", "pubmed", "arxiv", "semantic_scholar"]);
+export const CitationSourceStatusSchema = z.enum(["ok", "no_data", "unavailable", "not_applicable"]);
+export const CitationVerdictSchema = z.enum(["verified", "metadata_mismatch", "not_found", "unverifiable", "inconclusive"]);
+export const CitationCoverageSchema = z.enum(["complete", "partial", "none"]);
+export const ComparisonStatusSchema = z.enum(["match", "mismatch", "not_compared"]);
+export const CitationFieldSchema = z.enum(["title", "authors", "year", "venue", "volume", "firstPage"]);
+export const UnsupportedWorkKindSchema = z.enum(["personal_communication", "unpublished", "unregistered_in_press"]);
+export const CitationIdentifiersSchema = z.object({
+    doi: z.string().optional(),
+    pmid: z.string().optional(),
+    arxiv: z.string().optional(),
+    corpusId: z.string().optional(),
+});
+export const NormalizedCitationMetadataSchema = z.object({
+    title: z.string().optional(),
+    authors: z.array(z.string()).optional(),
+    year: z.number().int().optional(),
+    venue: z.string().optional(),
+    volume: z.string().optional(),
+    firstPage: z.string().optional(),
+});
+export const NormalizedCitationSchema = z.object({
+    citation: z.string(),
+    query: z.string(),
+    kind: z.enum(["doi", "pmid", "arxiv", "free_text"]),
+    identifiers: CitationIdentifiersSchema,
+    supplied: NormalizedCitationMetadataSchema,
+    unsupportedWorkKind: UnsupportedWorkKindSchema.optional(),
+});
+export const CitationRecordSchema = z.object({
+    source: CitationSourceSchema,
+    sourceRecordId: z.string(),
+    identifiers: CitationIdentifiersSchema,
+    title: z.string().optional(),
+    authors: z.array(z.string()).optional(),
+    year: z.number().int().optional(),
+    venue: z.string().optional(),
+    volume: z.string().optional(),
+    firstPage: z.string().optional(),
+    registrationAgency: z.string().optional(),
+    url: z.string().optional(),
+});
+export const IdentifierEvidenceSchema = z.object({
+    type: z.enum(["doi", "pmid", "arxiv"]),
+    identifier: z.string(),
+    exists: z.boolean(),
+    registrationAgency: z.string().optional(),
+    metadataAvailable: z.boolean(),
+});
+export const CitationSourceOutcomeSchema = z.object({
+    source: CitationSourceSchema,
+    operation: z.string(),
+    status: CitationSourceStatusSchema,
+    requestCount: z.number().int().nonnegative(),
+    records: z.array(CitationRecordSchema),
+    detail: z.string().optional(),
+    identifierEvidence: IdentifierEvidenceSchema.optional(),
+});
+export const CitationFieldComparisonSchema = z.object({
+    field: CitationFieldSchema,
+    status: ComparisonStatusSchema,
+    supplied: z.union([z.string(), z.number(), z.array(z.string())]),
+    sourceValues: z.array(z.object({
+        source: CitationSourceSchema,
+        value: z.union([z.string(), z.number(), z.array(z.string())]),
+    })),
+    ruleVersion: z.string(),
+});
+export const CitationConflictSchema = z.object({
+    field: CitationFieldSchema,
+    values: z.array(z.object({
+        source: CitationSourceSchema,
+        value: z.union([z.string(), z.number(), z.array(z.string())]),
+    })),
+});
+export const CitationClusterRelationSchema = z.object({
+    clusterId: z.string(),
+    kind: z.enum(["preprint_of", "published_as", "related_version"]),
+});
+export const CitationCandidateClusterSchema = z.object({
+    id: z.string(),
+    score: z.number().min(0).max(1),
+    records: z.array(CitationRecordSchema).min(1),
+    relations: z.array(CitationClusterRelationSchema),
+});
+export const CitationResolutionResultSchema = z.object({
+    input: CitationInputSchema,
+    normalized: NormalizedCitationSchema,
+    sourceOutcomes: z.array(CitationSourceOutcomeSchema),
+    candidates: z.array(CitationCandidateClusterSchema),
+    selectedClusterId: z.string().optional(),
+    comparisons: z.array(CitationFieldComparisonSchema),
+    conflicts: z.array(CitationConflictSchema),
+    verdict: CitationVerdictSchema,
+    coverage: CitationCoverageSchema,
+});
+export const CitationSourceOperationSchema = z.enum([
+    "doi_exact",
+    "crossref_doi_if_owned",
+    "crossref_bibliographic",
+    "pubmed_exact",
+    "pubmed_doi",
+    "pubmed_structured",
+    "pubmed_title",
+    "arxiv_exact",
+    "arxiv_bibliographic",
+    "semantic_scholar_identifier",
+    "semantic_scholar_bibliographic",
+    "none",
+]);
+export const CitationSourcePlanItemSchema = z.object({
+    source: CitationSourceSchema,
+    applicable: z.boolean(),
+    operation: CitationSourceOperationSchema,
+    candidateGeneration: z.boolean(),
+    reason: z.string(),
+});

package/dist/contracts/schemas/chat-parts.d.ts

@@ -182,6 +182,7 @@ export declare const DagStatePartSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const StepPhaseSchema: z.ZodEnum<{
+    complete: "complete";
     failed: "failed";
     warning: "warning";
     "sandbox-init": "sandbox-init";
@@ -190,7 +191,6 @@ export declare const StepPhaseSchema: z.ZodEnum<{
     "generating-summary": "generating-summary";
     indexing: "indexing";
     persisting: "persisting";
-    complete: "complete";
     retrying: "retrying";
 }>;
 export declare const StepActivityPartSchema: z.ZodObject<{
@@ -199,6 +199,7 @@ export declare const StepActivityPartSchema: z.ZodObject<{
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         warning: "warning";
         "sandbox-init": "sandbox-init";
@@ -207,7 +208,6 @@ export declare const StepActivityPartSchema: z.ZodObject<{
         "generating-summary": "generating-summary";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         retrying: "retrying";
     }>;
     activity: z.ZodString;
@@ -314,8 +314,8 @@ export declare const RunCompletedPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        completed: "completed";
         partial: "partial";
+        completed: "completed";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;
@@ -403,11 +403,11 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SynthesisPhaseSchema: z.ZodEnum<{
+    complete: "complete";
     failed: "failed";
     skipped: "skipped";
     indexing: "indexing";
     persisting: "persisting";
-    complete: "complete";
     starting: "starting";
     researching: "researching";
     drafting: "drafting";
@@ -419,11 +419,11 @@ export declare const SynthesisProgressPartSchema: z.ZodObject<{
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         skipped: "skipped";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         starting: "starting";
         researching: "researching";
         drafting: "drafting";
@@ -574,6 +574,7 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     runId: z.ZodString;
     stepId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         warning: "warning";
         "sandbox-init": "sandbox-init";
@@ -582,7 +583,6 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         "generating-summary": "generating-summary";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         retrying: "retrying";
     }>;
     activity: z.ZodString;
@@ -693,11 +693,11 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     id: z.ZodString;
     runId: z.ZodString;
     phase: z.ZodEnum<{
+        complete: "complete";
         failed: "failed";
         skipped: "skipped";
         indexing: "indexing";
         persisting: "persisting";
-        complete: "complete";
         starting: "starting";
         researching: "researching";
         drafting: "drafting";
@@ -712,8 +712,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     type: z.ZodLiteral<"data-run-completed">;
     runId: z.ZodString;
     status: z.ZodEnum<{
-        completed: "completed";
         partial: "partial";
+        completed: "completed";
     }>;
     completedSteps: z.ZodNumber;
     totalSteps: z.ZodNumber;

package/dist/contracts/target-dossier.d.ts

@@ -1785,11 +1785,11 @@ export declare const ExpressionHeatmapCellSchema: z.ZodObject<{
         dog: "dog";
     }>;
     rank: z.ZodEnum<{
+        no_data: "no_data";
+        absent: "absent";
         high: "high";
         medium: "medium";
         low: "low";
-        absent: "absent";
-        no_data: "no_data";
         not_loaded: "not_loaded";
     }>;
 }, z.core.$strip>;
@@ -1804,11 +1804,11 @@ export declare const ExpressionHeatmapSchema: z.ZodObject<{
             dog: "dog";
         }>;
         rank: z.ZodEnum<{
+            no_data: "no_data";
+            absent: "absent";
             high: "high";
             medium: "medium";
             low: "low";
-            absent: "absent";
-            no_data: "no_data";
             not_loaded: "not_loaded";
         }>;
     }, z.core.$strip>>;
@@ -1911,11 +1911,11 @@ export declare const PreclinicalProfileSchema: z.ZodObject<{
                     dog: "dog";
                 }>;
                 rank: z.ZodEnum<{
+                    no_data: "no_data";
+                    absent: "absent";
                     high: "high";
                     medium: "medium";
                     low: "low";
-                    absent: "absent";
-                    no_data: "no_data";
                     not_loaded: "not_loaded";
                 }>;
             }, z.core.$strip>>;
@@ -4229,11 +4229,11 @@ export declare const DossierSchema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -5482,11 +5482,11 @@ export declare const ReferenceBiologyV4Shape: z.ZodObject<{
                         dog: "dog";
                     }>;
                     rank: z.ZodEnum<{
+                        no_data: "no_data";
+                        absent: "absent";
                         high: "high";
                         medium: "medium";
                         low: "low";
-                        absent: "absent";
-                        no_data: "no_data";
                         not_loaded: "not_loaded";
                     }>;
                 }, z.core.$strip>>;
@@ -6914,11 +6914,11 @@ export declare const DossierV4Schema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -9131,11 +9131,11 @@ export declare const DossierV4BodySchema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -12206,11 +12206,11 @@ export declare const DossierV5Schema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -14928,11 +14928,11 @@ export declare const DossierV5BodySchema: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;
@@ -16557,11 +16557,11 @@ export declare const DossierSchemaV3Legacy: z.ZodObject<{
                             dog: "dog";
                         }>;
                         rank: z.ZodEnum<{
+                            no_data: "no_data";
+                            absent: "absent";
                             high: "high";
                             medium: "medium";
                             low: "low";
-                            absent: "absent";
-                            no_data: "no_data";
                             not_loaded: "not_loaded";
                         }>;
                     }, z.core.$strip>>;

package/dist/execution/run-synthesis.d.ts

@@ -31,6 +31,7 @@ import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { CitationResolver } from "../citations/types.js";
 /**
  * The synthesizer's agent identity — the `source.agentId` on its loop events
  * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
@@ -67,6 +68,8 @@ export interface GenerateRunSynthesisInput {
     readonly model: string;
     /** API keys for the bio/chem tools the embedded literature reviewer uses. */
     readonly bioKeys: BioToolKeys;
+    /** Shared resolver used by the embedded literature reviewer. */
+    readonly citationResolver: CitationResolver;
     /** LLM usage-accounting seam for the synthesizer + reviewer loops; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
     /** Step summaries from the completed run. Non-empty. */

package/dist/execution/run-synthesis.js

@@ -349,6 +349,7 @@ export async function generateRunSynthesis(input) {
         provider: input.provider,
         model: input.model,
         bioKeys: input.bioKeys,
+        citationResolver: input.citationResolver,
         usageRecorder: input.usageRecorder,
     });
     const validateTool = buildValidateTool(innerCtx);

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { assembleCoreRuntime } from "./runtime/assemble.js";
 export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable } from "./runtime/assemble.js";
+export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/assemble.js";
 export { bootHarness } from "./runtime/boot.js";
 export type { BootHarnessDeps, BootedHarness } from "./runtime/boot.js";
 export { createConversationAgent } from "./agents/conversation-agent.js";
@@ -31,6 +32,10 @@ export type { DbosWorkflowPurgerDeps } from "./execution/dbos-workflow-purger.js
 export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
+export { createCitationResolver } from "./citations/resolve.js";
+export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.js";
+export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
+export type { CitationKind, CitationInput, CitationSource, CitationSourceStatus, CitationResolver, CitationResolveOptions, CitationResolutionResult, CitationVerdict, CitationCoverage, ComparisonStatus, CitationField, UnsupportedWorkKind, CitationIdentifiers, NormalizedCitationMetadata, NormalizedCitation, CitationSourceOutcome, CitationRecord, IdentifierEvidence, CitationFieldComparison, CitationConflict, CitationCandidateCluster, CitationSourceClient, CitationSourceRequest, CitationSourceOperation, CitationSourcePlanItem, RegistrationAgencyEvidence, } from "./citations/types.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
 export type { AskGateway, AskGatewayDeps, AskContext, AnswerOutcome, PendingAsk } from "./tools/approval/gateway.js";
 export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
@@ -56,7 +61,7 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
-export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
+export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome, ConversationTurn } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";

package/dist/index.js

@@ -33,6 +33,9 @@ export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// Host-agnostic citation verification service and its public contracts.
+export { createCitationResolver } from "./citations/resolve.js";
+export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 // Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
 // over the injected `Pool` and carries the outward `answer`/`pending` API plus
 // the boot-time `sweepExpired`; `UnavailableAsk` is the shipped deny-by-default

package/dist/lib/cache.d.ts

@@ -0,0 +1,8 @@
+export declare class BoundedTtlCache<Value> {
+    private readonly maximum;
+    private readonly now;
+    private readonly entries;
+    constructor(maximum: number, now?: () => number);
+    get(key: string): Value | undefined;
+    set(key: string, value: Value, ttlMs: number): void;
+}

package/dist/lib/cache.js

@@ -0,0 +1,35 @@
+export class BoundedTtlCache {
+    maximum;
+    now;
+    entries = new Map();
+    constructor(maximum, now = Date.now) {
+        this.maximum = maximum;
+        this.now = now;
+        if (!Number.isInteger(maximum) || maximum < 0)
+            throw new Error("cache maximum must be a non-negative integer");
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        if (this.maximum === 0 || ttlMs <= 0)
+            return;
+        this.entries.delete(key);
+        this.entries.set(key, { value, expiresAt: this.now() + ttlMs });
+        while (this.entries.size > this.maximum) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}

package/dist/lib/rate-limit.d.ts

@@ -0,0 +1,35 @@
+export interface RateLimitConfig {
+    readonly maxConcurrency: number;
+    readonly requestsPerSecond: number;
+    /**
+     * Retry policy for the source's HTTP layer. Retries re-enter the limiter as
+     * fresh attempts, so they are paced like any other request; the limiter
+     * itself does not read these two fields.
+     */
+    readonly maxRetries: number;
+    readonly maxRetryDelayMs: number;
+}
+export interface RateLimitRuntime {
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare function sleepWithSignal(milliseconds: number, signal?: AbortSignal): Promise<void>;
+export declare class BoundedRateLimiter {
+    private readonly config;
+    private readonly semaphore;
+    private readonly now;
+    private readonly sleep;
+    private reservationTail;
+    private nextStartAt;
+    constructor(config: RateLimitConfig, runtime?: RateLimitRuntime);
+    private reserveStart;
+    run<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}
+/**
+ * Admission gate for a source's HTTP layer (`SourceHttpOptions.schedule`).
+ *
+ * It gates the network call alone: the caller arms its request timeout inside
+ * the admitted operation, so a request held behind pacing or a concurrency
+ * ceiling cannot be reported as a timeout before it ever reaches the network.
+ */
+export declare function createRateLimitSchedule(config: RateLimitConfig, runtime?: RateLimitRuntime): <T>(operation: () => Promise<T>, signal?: AbortSignal) => Promise<T>;

package/dist/lib/rate-limit.js

@@ -0,0 +1,121 @@
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
+export function sleepWithSignal(milliseconds, signal) {
+    if (milliseconds <= 0)
+        return Promise.resolve();
+    if (signal?.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(abortReason(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+class Semaphore {
+    maximum;
+    active = 0;
+    waiters = [];
+    constructor(maximum) {
+        this.maximum = maximum;
+    }
+    async acquire(signal) {
+        if (signal?.aborted)
+            throw abortReason(signal);
+        if (this.active < this.maximum) {
+            this.active += 1;
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, ...(signal === undefined ? {} : { signal }) };
+            if (signal !== undefined) {
+                waiter.onAbort = () => {
+                    const index = this.waiters.indexOf(waiter);
+                    if (index >= 0)
+                        this.waiters.splice(index, 1);
+                    reject(abortReason(signal));
+                };
+                signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    release() {
+        const waiter = this.waiters.shift();
+        if (waiter === undefined) {
+            this.active -= 1;
+            return;
+        }
+        if (waiter.signal !== undefined && waiter.onAbort !== undefined)
+            waiter.signal.removeEventListener("abort", waiter.onAbort);
+        waiter.resolve();
+    }
+}
+export class BoundedRateLimiter {
+    config;
+    semaphore;
+    now;
+    sleep;
+    reservationTail = Promise.resolve();
+    nextStartAt = 0;
+    constructor(config, runtime = {}) {
+        this.config = config;
+        if (!Number.isInteger(config.maxConcurrency) || config.maxConcurrency < 1)
+            throw new Error("maxConcurrency must be a positive integer");
+        if (!(config.requestsPerSecond > 0))
+            throw new Error("requestsPerSecond must be positive");
+        this.semaphore = new Semaphore(config.maxConcurrency);
+        this.now = runtime.now ?? Date.now;
+        this.sleep = runtime.sleep ?? sleepWithSignal;
+    }
+    async reserveStart(signal) {
+        let release;
+        const predecessor = this.reservationTail;
+        this.reservationTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        if (signal?.aborted) {
+            release();
+            throw abortReason(signal);
+        }
+        await predecessor;
+        try {
+            if (signal?.aborted)
+                throw abortReason(signal);
+            const startAt = Math.max(this.now(), this.nextStartAt);
+            this.nextStartAt = startAt + 1000 / this.config.requestsPerSecond;
+            return startAt;
+        }
+        finally {
+            release();
+        }
+    }
+    async run(operation, signal) {
+        const startAt = await this.reserveStart(signal);
+        await this.sleep(Math.max(0, startAt - this.now()), signal);
+        await this.semaphore.acquire(signal);
+        try {
+            return await operation();
+        }
+        finally {
+            this.semaphore.release();
+        }
+    }
+}
+/**
+ * Admission gate for a source's HTTP layer (`SourceHttpOptions.schedule`).
+ *
+ * It gates the network call alone: the caller arms its request timeout inside
+ * the admitted operation, so a request held behind pacing or a concurrency
+ * ceiling cannot be reported as a timeout before it ever reaches the network.
+ */
+export function createRateLimitSchedule(config, runtime = {}) {
+    const limiter = new BoundedRateLimiter(config, runtime);
+    return (operation, signal) => limiter.run(operation, signal);
+}

package/dist/literature/sources/arxiv.d.ts

@@ -0,0 +1,22 @@
+import { type SourceHttpOptions, type SourceHttpResult } from "./http.js";
+export interface ArxivPaper {
+    id: string;
+    title: string;
+    abstract: string;
+    authors: string[];
+    published: string;
+    categories: string[];
+    url: string;
+    pdfUrl?: string;
+}
+export interface ArxivSearchInput {
+    readonly query: string;
+    readonly categories?: readonly string[];
+    readonly limit: number;
+}
+export interface ArxivSource {
+    search(input: ArxivSearchInput, signal?: AbortSignal): Promise<SourceHttpResult<ArxivPaper[]>>;
+    lookupExact(id: string, limit: number, signal?: AbortSignal): Promise<SourceHttpResult<ArxivPaper[]>>;
+}
+export declare function parseArxivAtom(xml: string): ArxivPaper[];
+export declare function createArxivSource(options?: SourceHttpOptions): ArxivSource;