@inflexa-ai/harness 0.15.1 → 0.17.0

package/dist/citations/plan.js

@@ -0,0 +1,59 @@
+const SOURCES = ["doi_registry", "crossref", "pubmed", "arxiv", "semantic_scholar"];
+function item(source, applicable, operation, reason, candidateGeneration = false) {
+    return { source, applicable, operation: applicable ? operation : "none", candidateGeneration: applicable && candidateGeneration, reason };
+}
+function enoughForEcitMatch(input) {
+    if (!input.venue)
+        return false;
+    const disambiguators = [input.year, input.volume, input.firstPage, input.authors?.[0]].filter((value) => value !== undefined).length;
+    return disambiguators >= 2;
+}
+function indicatesArxiv(input, normalized) {
+    return /\b(?:arxiv|preprint)\b/i.test(input.citation) || /\barxiv\b/i.test(input.venue ?? "") || normalized.identifiers.arxiv !== undefined;
+}
+export function planCitationSources(input, normalized) {
+    if (normalized.unsupportedWorkKind !== undefined) {
+        return SOURCES.map((source) => item(source, false, "none", `unsupported work kind: ${normalized.unsupportedWorkKind}`));
+    }
+    if (normalized.kind === "doi") {
+        return [
+            item("doi_registry", true, "doi_exact", "exact DOI handle and registration-agency lookup"),
+            item("crossref", true, "crossref_doi_if_owned", "exact lookup only when DOI registry identifies Crossref"),
+            item("pubmed", true, "pubmed_doi", "bounded DOI lookup in PubMed", true),
+            item("arxiv", false, "none", "a DOI alone does not indicate an arXiv preprint"),
+            item("semantic_scholar", true, "semantic_scholar_identifier", "DOI identifier lookup", true),
+        ];
+    }
+    if (normalized.kind === "pmid") {
+        return [
+            item("doi_registry", false, "none", "no DOI supplied"),
+            item("crossref", false, "none", "PMID-only input has no Crossref bibliographic query"),
+            item("pubmed", true, "pubmed_exact", "exact PMID retrieval"),
+            item("arxiv", false, "none", "PMID-only input does not indicate arXiv"),
+            item("semantic_scholar", true, "semantic_scholar_identifier", "PMID identifier lookup", true),
+        ];
+    }
+    if (normalized.kind === "arxiv") {
+        return [
+            item("doi_registry", false, "none", "no DOI supplied"),
+            item("crossref", false, "none", "arXiv-only input has no Crossref bibliographic query"),
+            item("pubmed", false, "none", "arXiv-only input has no PubMed query"),
+            item("arxiv", true, "arxiv_exact", "exact arXiv identifier retrieval"),
+            item("semantic_scholar", true, "semantic_scholar_identifier", "arXiv identifier lookup", true),
+        ];
+    }
+    const pubmedStructured = enoughForEcitMatch(input);
+    const pubmedTitle = !pubmedStructured && input.title !== undefined;
+    const arxiv = indicatesArxiv(input, normalized);
+    return [
+        item("doi_registry", false, "none", "no exact DOI supplied"),
+        item("crossref", true, "crossref_bibliographic", "raw or structured bibliographic match", true),
+        item("pubmed", pubmedStructured || pubmedTitle, pubmedStructured ? "pubmed_structured" : "pubmed_title", pubmedStructured
+            ? "structured fields support constrained citation match"
+            : pubmedTitle
+                ? "supplied title supports bounded candidate search"
+                : "insufficient structured PubMed signal", true),
+        item("arxiv", arxiv, "arxiv_bibliographic", arxiv ? "citation indicates an arXiv preprint" : "citation does not indicate arXiv", true),
+        item("semantic_scholar", true, "semantic_scholar_bibliographic", "bounded bibliographic candidate search", true),
+    ];
+}

package/dist/citations/resolve.d.ts

@@ -0,0 +1,28 @@
+import { type CitationMatchConfig } from "./match.js";
+import { type RateLimitConfig, type RateLimitRuntime } from "../lib/rate-limit.js";
+import { type CitationResolver, type CitationSource, type CitationSourceClient } from "./types.js";
+export interface CitationResolverSourceConfig extends Partial<RateLimitConfig> {
+    readonly enabled?: boolean;
+}
+export interface CitationResolverConfig {
+    readonly maxBatchSize?: number;
+    readonly timeoutMs?: number;
+    readonly cache?: {
+        readonly maximum?: number;
+        readonly positiveTtlMs?: number;
+        readonly negativeTtlMs?: number;
+    };
+    readonly match?: Partial<CitationMatchConfig>;
+    readonly sources?: Partial<Record<CitationSource, CitationResolverSourceConfig>>;
+    readonly crossref?: {
+        readonly mailto?: string;
+        readonly userAgent?: string;
+    };
+    readonly ncbiApiKey?: string;
+    readonly semanticScholarApiKey?: string;
+}
+export interface CitationResolverDependencies extends RateLimitRuntime {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly clients?: readonly CitationSourceClient[];
+}
+export declare function createCitationResolver(config?: CitationResolverConfig, deps?: CitationResolverDependencies): CitationResolver;

package/dist/citations/resolve.js

@@ -0,0 +1,238 @@
+import { aggregateCitationResolution } from "./aggregate.js";
+import { BoundedTtlCache } from "../lib/cache.js";
+import { createArxivCitationClient } from "./clients/arxiv.js";
+import { notApplicableOutcome, sourceOutcome } from "./clients/common.js";
+import { createCrossrefClient } from "./clients/crossref.js";
+import { createDoiRegistryClient } from "./clients/doi-registry.js";
+import { createPubmedCitationClient } from "./clients/pubmed.js";
+import { createSemanticScholarCitationClient } from "./clients/semantic-scholar.js";
+import { DEFAULT_MATCH_CONFIG } from "./match.js";
+import { citationLookupKey, normalizeCitation } from "./normalize.js";
+import { planCitationSources } from "./plan.js";
+import { createRateLimitSchedule } from "../lib/rate-limit.js";
+import { CitationInputSchema, } from "./types.js";
+const SOURCE_PLAN_VERSION = "citation-plan-v1";
+const SOURCE_ORDER = ["doi_registry", "crossref", "pubmed", "arxiv", "semantic_scholar"];
+const DEFAULT_RATE_LIMITS = {
+    doi_registry: { maxConcurrency: 2, requestsPerSecond: 5, maxRetries: 2, maxRetryDelayMs: 5_000 },
+    crossref: { maxConcurrency: 2, requestsPerSecond: 5, maxRetries: 2, maxRetryDelayMs: 5_000 },
+    pubmed: { maxConcurrency: 3, requestsPerSecond: 3, maxRetries: 2, maxRetryDelayMs: 5_000 },
+    arxiv: { maxConcurrency: 1, requestsPerSecond: 1, maxRetries: 2, maxRetryDelayMs: 10_000 },
+    semantic_scholar: { maxConcurrency: 1, requestsPerSecond: 1, maxRetries: 2, maxRetryDelayMs: 10_000 },
+};
+function mergedRateLimit(source, config) {
+    return { ...DEFAULT_RATE_LIMITS[source], ...(config.sources?.[source] ?? {}) };
+}
+function createDefaultClients(config, deps) {
+    const runtime = { ...(deps.now ? { now: deps.now } : {}), ...(deps.sleep ? { sleep: deps.sleep } : {}) };
+    const http = (source) => {
+        const limits = mergedRateLimit(source, config);
+        return {
+            ...(deps.fetch === undefined ? {} : { fetch: deps.fetch }),
+            ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
+            ...(deps.sleep ? { sleep: deps.sleep } : {}),
+            schedule: createRateLimitSchedule(limits, runtime),
+            maxRetries: limits.maxRetries,
+            maxRetryDelayMs: limits.maxRetryDelayMs,
+        };
+    };
+    return [
+        createDoiRegistryClient(http("doi_registry")),
+        createCrossrefClient({
+            ...http("crossref"),
+            ...(config.crossref?.mailto === undefined ? {} : { mailto: config.crossref.mailto }),
+            ...(config.crossref?.userAgent === undefined ? {} : { userAgent: config.crossref.userAgent }),
+        }),
+        createPubmedCitationClient({
+            ...http("pubmed"),
+            ...(config.ncbiApiKey === undefined ? {} : { apiKey: config.ncbiApiKey }),
+        }),
+        createArxivCitationClient(http("arxiv")),
+        createSemanticScholarCitationClient({
+            ...http("semantic_scholar"),
+            ...(config.semanticScholarApiKey === undefined ? {} : { apiKey: config.semanticScholarApiKey }),
+        }),
+    ];
+}
+function cacheable(outcomes) {
+    if (outcomes.some((outcome) => outcome.status === "unavailable"))
+        return undefined;
+    return outcomes.some((outcome) => outcome.records.length > 0) ? "positive" : "negative";
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
+function withCallerSignal(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortReason(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * Read the DOI registry's outcome as evidence about the registration agency.
+ *
+ * The registry runs first in `SOURCE_ORDER`, so every later source sees its
+ * result. Only a named agency is a finding; every other shape — the registry
+ * disabled, unreachable, or silent on the agency — leaves ownership unknown.
+ */
+function registrationAgencyEvidence(outcome) {
+    if (outcome === undefined)
+        return { status: "undetermined", detail: "the DOI registry was not consulted" };
+    const evidence = outcome.identifierEvidence;
+    if (evidence?.registrationAgency !== undefined)
+        return { status: "determined", agency: evidence.registrationAgency };
+    if (evidence?.exists === false)
+        return { status: "absent" };
+    return { status: "undetermined", detail: outcome.detail ?? `the DOI registry returned ${outcome.status}` };
+}
+/**
+ * Run one source over the requests routed to it, keeping its failures its own.
+ *
+ * A source that throws, or that answers a batch with the wrong number of
+ * outcomes, is an unavailable source — the same operational state as an HTTP
+ * failure — not a failed batch. Caller cancellation still propagates.
+ */
+async function runSource(client, requests, signal) {
+    const unavailable = (request, detail) => sourceOutcome(client.source, request.plan.operation, "unavailable", 0, [], detail);
+    const describe = (error) => (error instanceof Error ? error.message : String(error));
+    if (client.resolveMany === undefined) {
+        const settled = await Promise.allSettled(requests.map((request) => client.resolve(request, signal)));
+        if (signal?.aborted)
+            throw abortReason(signal);
+        return settled.map((outcome, index) => (outcome.status === "fulfilled" ? outcome.value : unavailable(requests[index], describe(outcome.reason))));
+    }
+    try {
+        const resolved = await client.resolveMany(requests, signal);
+        if (resolved.length === requests.length)
+            return [...resolved];
+        return requests.map((request) => unavailable(request, `${client.source} returned ${resolved.length} outcomes for ${requests.length} requests`));
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw abortReason(signal);
+        return requests.map((request) => unavailable(request, describe(error)));
+    }
+}
+export function createCitationResolver(config = {}, deps = {}) {
+    const clients = new Map((deps.clients ?? createDefaultClients(config, deps)).map((client) => [client.source, client]));
+    const now = deps.now ?? Date.now;
+    const cacheConfig = {
+        maximum: config.cache?.maximum ?? 500,
+        positiveTtlMs: config.cache?.positiveTtlMs ?? 15 * 60_000,
+        negativeTtlMs: config.cache?.negativeTtlMs ?? 2 * 60_000,
+    };
+    const cache = new BoundedTtlCache(cacheConfig.maximum, now);
+    const inFlight = new Map();
+    const matchConfig = { ...DEFAULT_MATCH_CONFIG, ...(config.match ?? {}) };
+    const maxBatchSize = config.maxBatchSize ?? 200;
+    const keyFor = (input) => `${SOURCE_PLAN_VERSION}:${citationLookupKey(input)}`;
+    async function resolveUncachedBatch(entries, signal) {
+        const outcomes = entries.map(() => new Map());
+        for (const source of SOURCE_ORDER) {
+            const sourceConfig = config.sources?.[source];
+            const client = clients.get(source);
+            const requests = [];
+            const requestIndices = [];
+            for (let index = 0; index < entries.length; index += 1) {
+                const entry = entries[index];
+                const plan = entry.plans.find((candidate) => candidate.source === source);
+                if (!plan.applicable || sourceConfig?.enabled === false || client === undefined) {
+                    outcomes[index].set(source, sourceConfig?.enabled === false
+                        ? notApplicableOutcome({ ...plan, applicable: false, operation: "none", reason: "source disabled by resolver configuration" })
+                        : client === undefined
+                            ? notApplicableOutcome({ ...plan, applicable: false, operation: "none", reason: "source client unavailable" })
+                            : notApplicableOutcome(plan));
+                    continue;
+                }
+                requests.push({
+                    input: entry.input,
+                    normalized: entry.normalized,
+                    plan,
+                    registrationAgency: registrationAgencyEvidence(outcomes[index].get("doi_registry")),
+                });
+                requestIndices.push(index);
+            }
+            if (requests.length === 0 || client === undefined)
+                continue;
+            const resolved = await runSource(client, requests, signal);
+            for (let requestIndex = 0; requestIndex < resolved.length; requestIndex += 1) {
+                outcomes[requestIndices[requestIndex]].set(source, resolved[requestIndex]);
+            }
+        }
+        return entries.map((entry, index) => SOURCE_ORDER.map((source) => outcomes[index].get(source) ?? notApplicableOutcome(entry.plans.find((plan) => plan.source === source))));
+    }
+    async function resolveMany(inputs, options = {}) {
+        if (inputs.length > maxBatchSize)
+            throw new Error(`citation batch size ${inputs.length} exceeds configured maximum ${maxBatchSize}`);
+        if (inputs.length === 0)
+            return [];
+        const parsed = inputs.map((input) => CitationInputSchema.parse(input));
+        const uniqueOrder = [];
+        const firstByKey = new Map();
+        for (const input of parsed) {
+            const key = keyFor(input);
+            if (!firstByKey.has(key)) {
+                uniqueOrder.push(key);
+                firstByKey.set(key, input);
+            }
+        }
+        const pending = new Map();
+        const uncached = [];
+        for (const key of uniqueOrder) {
+            const cached = cache.get(key);
+            if (cached !== undefined) {
+                pending.set(key, Promise.resolve(cached));
+                continue;
+            }
+            const running = inFlight.get(key);
+            if (running !== undefined) {
+                pending.set(key, running);
+                continue;
+            }
+            const input = firstByKey.get(key);
+            const normalized = normalizeCitation(input);
+            uncached.push({ key, entry: { input, normalized, plans: planCitationSources(input, normalized) } });
+        }
+        if (uncached.length > 0) {
+            const batch = resolveUncachedBatch(uncached.map(({ entry }) => entry), options.signal);
+            for (let index = 0; index < uncached.length; index += 1) {
+                const { key } = uncached[index];
+                const one = batch.then((results) => results[index]);
+                const tracked = one.then((outcomes) => {
+                    const kind = cacheable(outcomes);
+                    if (kind !== undefined)
+                        cache.set(key, outcomes, kind === "positive" ? cacheConfig.positiveTtlMs : cacheConfig.negativeTtlMs);
+                    inFlight.delete(key);
+                    return outcomes;
+                }, (error) => {
+                    inFlight.delete(key);
+                    throw error;
+                });
+                inFlight.set(key, tracked);
+                pending.set(key, tracked);
+            }
+        }
+        const outcomesByKey = new Map();
+        await Promise.all(uniqueOrder.map(async (key) => {
+            outcomesByKey.set(key, await withCallerSignal(pending.get(key), options.signal));
+        }));
+        // Aggregated per input, never per shared lookup: comparisons and the
+        // verdict they drive belong to the caller's own supplied metadata.
+        return parsed.map((input) => aggregateCitationResolution(input, normalizeCitation(input), outcomesByKey.get(keyFor(input)), matchConfig));
+    }
+    return {
+        resolveOne: async (input, options = {}) => (await resolveMany([input], options))[0],
+        resolveMany,
+    };
+}