@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/citations/clients/crossref.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { encodeDoiPath, firstNonEmpty, parseYear, sourceOutcome } from "./common.js";
+import { requestJson } from "../../literature/sources/http.js";
+const CrossrefItemSchema = z
+    .object({
+    DOI: z.string().optional(),
+    URL: z.string().optional(),
+    title: z.array(z.string()).optional(),
+    author: z.array(z.object({ given: z.string().optional(), family: z.string().optional(), name: z.string().optional() }).passthrough()).optional(),
+    issued: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    published: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    "container-title": z.array(z.string()).optional(),
+    volume: z.string().optional(),
+    page: z.string().optional(),
+})
+    .passthrough();
+const ExactSchema = z.object({ message: CrossrefItemSchema });
+const SearchSchema = z.object({ message: z.object({ items: z.array(CrossrefItemSchema) }).passthrough() });
+function crossrefRecord(item, index) {
+    const doi = item.DOI?.toLocaleLowerCase("en-US");
+    const sourceRecordId = firstNonEmpty([doi, item.URL, `candidate-${index}`]);
+    if (sourceRecordId === undefined)
+        return undefined;
+    const title = firstNonEmpty(item.title ?? []);
+    const venue = firstNonEmpty(item["container-title"] ?? []);
+    const authors = item.author
+        ?.map((author) => firstNonEmpty([author.name, [author.given, author.family].filter(Boolean).join(" ")]))
+        .filter((author) => author !== undefined);
+    const dateParts = item.issued?.["date-parts"]?.[0] ?? item.published?.["date-parts"]?.[0];
+    return {
+        source: "crossref",
+        sourceRecordId,
+        identifiers: { ...(doi === undefined ? {} : { doi }) },
+        ...(title === undefined ? {} : { title }),
+        ...(authors === undefined || authors.length === 0 ? {} : { authors }),
+        ...(dateParts?.[0] === undefined ? {} : { year: parseYear(dateParts[0]) }),
+        ...(venue === undefined ? {} : { venue }),
+        ...(item.volume === undefined ? {} : { volume: item.volume }),
+        ...(item.page === undefined ? {} : { firstPage: item.page.split(/[-–]/)[0] }),
+        ...(item.URL === undefined ? {} : { url: item.URL }),
+    };
+}
+export function createCrossrefClient(options = {}) {
+    const headers = {};
+    if (options.userAgent)
+        headers["User-Agent"] = options.userAgent;
+    return {
+        source: "crossref",
+        async resolve(request, signal) {
+            if (!request.plan.applicable)
+                return sourceOutcome("crossref", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+            const registration = request.registrationAgency;
+            if (request.plan.operation === "crossref_doi_if_owned") {
+                // Skipping because ownership lies elsewhere is a finding; skipping because
+                // nobody could tell us is a gap, and reporting the gap as `not_applicable`
+                // would let an unchecked DOI reach `not_found` on complete coverage.
+                if (registration.status === "undetermined") {
+                    return sourceOutcome("crossref", request.plan.operation, "unavailable", 0, [], `registration agency undetermined: ${registration.detail}`);
+                }
+                if (registration.status === "absent") {
+                    return sourceOutcome("crossref", request.plan.operation, "not_applicable", 0, [], "the DOI handle does not resolve");
+                }
+                if (registration.agency.toLocaleLowerCase("en-US") !== "crossref") {
+                    return sourceOutcome("crossref", request.plan.operation, "not_applicable", 0, [], "DOI is not registered by Crossref");
+                }
+            }
+            const doi = request.normalized.identifiers.doi;
+            const exact = request.plan.operation === "crossref_doi_if_owned";
+            const url = exact
+                ? (() => {
+                    const target = new URL(`https://api.crossref.org/works/${encodeDoiPath(doi)}`);
+                    if (options.mailto)
+                        target.searchParams.set("mailto", options.mailto);
+                    return target.toString();
+                })()
+                : (() => {
+                    const params = new URLSearchParams({
+                        "query.bibliographic": request.input.citation,
+                        rows: String(options.maxCandidates ?? 5),
+                    });
+                    if (options.mailto)
+                        params.set("mailto", options.mailto);
+                    return `https://api.crossref.org/works?${params}`;
+                })();
+            const result = exact
+                ? await requestJson(url, ExactSchema, options, signal, { headers })
+                : await requestJson(url, SearchSchema, options, signal, { headers });
+            if (result.status !== "ok")
+                return sourceOutcome("crossref", request.plan.operation, result.status, 1, [], result.detail);
+            const items = exact ? [result.value.message] : result.value.message.items;
+            const records = items.flatMap((item, index) => {
+                const record = crossrefRecord(item, index);
+                return record === undefined ? [] : [record];
+            });
+            return sourceOutcome("crossref", request.plan.operation, records.length === 0 ? "no_data" : "ok", 1, records);
+        },
+    };
+}

package/dist/citations/clients/doi-registry.d.ts

@@ -0,0 +1,3 @@
+import type { CitationSourceClient } from "../types.js";
+import { type SourceHttpOptions } from "../../literature/sources/http.js";
+export declare function createDoiRegistryClient(options?: SourceHttpOptions): CitationSourceClient;

package/dist/citations/clients/doi-registry.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { encodeDoiPath, firstNonEmpty, parseYear, sourceOutcome } from "./common.js";
+import { requestJson } from "../../literature/sources/http.js";
+const HandleResponseSchema = z.object({ responseCode: z.number() }).passthrough();
+const RegistrationAgencySchema = z.array(z.object({ DOI: z.string().optional(), RA: z.string().optional() }).passthrough());
+const CslMetadataSchema = z
+    .object({
+    DOI: z.string().optional(),
+    id: z.string().optional(),
+    title: z.union([z.string(), z.array(z.string())]).optional(),
+    author: z.array(z.object({ given: z.string().optional(), family: z.string().optional(), literal: z.string().optional() }).passthrough()).optional(),
+    issued: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    published: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    "container-title": z.union([z.string(), z.array(z.string())]).optional(),
+    volume: z.string().optional(),
+    page: z.string().optional(),
+    URL: z.string().optional(),
+})
+    .passthrough();
+function scalar(value) {
+    return Array.isArray(value) ? firstNonEmpty(value) : firstNonEmpty([value]);
+}
+function cslRecord(doi, registrationAgency, metadata) {
+    const authors = metadata?.author
+        ?.map((author) => firstNonEmpty([author.literal, [author.given, author.family].filter(Boolean).join(" ")]))
+        .filter((author) => author !== undefined);
+    const dateParts = metadata?.issued?.["date-parts"]?.[0] ?? metadata?.published?.["date-parts"]?.[0];
+    const title = scalar(metadata?.title);
+    const venue = scalar(metadata?.["container-title"]);
+    return {
+        source: "doi_registry",
+        sourceRecordId: doi,
+        identifiers: { doi },
+        ...(title === undefined ? {} : { title }),
+        ...(authors === undefined || authors.length === 0 ? {} : { authors }),
+        ...(dateParts?.[0] === undefined ? {} : { year: parseYear(dateParts[0]) }),
+        ...(venue === undefined ? {} : { venue }),
+        ...(metadata?.volume === undefined ? {} : { volume: metadata.volume }),
+        ...(metadata?.page === undefined ? {} : { firstPage: metadata.page.split(/[-–]/)[0] }),
+        ...(registrationAgency === undefined ? {} : { registrationAgency }),
+        ...(metadata?.URL === undefined ? {} : { url: metadata.URL }),
+    };
+}
+export function createDoiRegistryClient(options = {}) {
+    return {
+        source: "doi_registry",
+        async resolve(request, signal) {
+            const doi = request.normalized.identifiers.doi;
+            if (!request.plan.applicable || doi === undefined) {
+                return sourceOutcome("doi_registry", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+            }
+            let requestCount = 1;
+            const handle = await requestJson(`https://doi.org/api/handles/${encodeDoiPath(doi)}`, HandleResponseSchema, options, signal);
+            if (handle.status !== "ok") {
+                return handle.status === "no_data"
+                    ? {
+                        ...sourceOutcome("doi_registry", request.plan.operation, handle.status, requestCount, [], handle.detail),
+                        identifierEvidence: { type: "doi", identifier: doi, exists: false, metadataAvailable: false },
+                    }
+                    : sourceOutcome("doi_registry", request.plan.operation, handle.status, requestCount, [], handle.detail);
+            }
+            if (handle.value.responseCode !== 1) {
+                return {
+                    ...sourceOutcome("doi_registry", request.plan.operation, "no_data", requestCount),
+                    identifierEvidence: { type: "doi", identifier: doi, exists: false, metadataAvailable: false },
+                };
+            }
+            requestCount += 1;
+            const agencyResult = await requestJson(`https://doi.org/doiRA/${encodeDoiPath(doi)}`, RegistrationAgencySchema, options, signal);
+            const registrationAgency = agencyResult.status === "ok" ? agencyResult.value[0]?.RA : undefined;
+            requestCount += 1;
+            const metadataResult = await requestJson(`https://doi.org/${encodeDoiPath(doi)}`, CslMetadataSchema, options, signal, {
+                headers: { Accept: "application/vnd.citationstyles.csl+json" },
+            });
+            const metadata = metadataResult.status === "ok" ? metadataResult.value : undefined;
+            const incomplete = agencyResult.status === "unavailable" || metadataResult.status === "unavailable";
+            const detail = [
+                agencyResult.status === "unavailable" ? agencyResult.detail : undefined,
+                metadataResult.status === "unavailable" ? metadataResult.detail : undefined,
+            ]
+                .filter((value) => value !== undefined)
+                .join("; ");
+            return {
+                ...sourceOutcome("doi_registry", request.plan.operation, incomplete ? "unavailable" : "ok", requestCount, [cslRecord(doi, registrationAgency, metadata)], detail || undefined),
+                identifierEvidence: {
+                    type: "doi",
+                    identifier: doi,
+                    exists: true,
+                    ...(registrationAgency === undefined ? {} : { registrationAgency }),
+                    metadataAvailable: metadata !== undefined,
+                },
+            };
+        },
+    };
+}

package/dist/citations/clients/pubmed.d.ts

@@ -0,0 +1,6 @@
+import type { CitationSourceClient } from "../types.js";
+import { type PubmedSourceOptions } from "../../literature/sources/pubmed.js";
+export interface PubmedCitationClientOptions extends PubmedSourceOptions {
+    readonly maxCandidates?: number;
+}
+export declare function createPubmedCitationClient(options?: PubmedCitationClientOptions): CitationSourceClient;

package/dist/citations/clients/pubmed.js

@@ -0,0 +1,83 @@
+import { createPubmedSource } from "../../literature/sources/pubmed.js";
+import { parseYear, sourceOutcome } from "./common.js";
+function pubmedRecord(article) {
+    const year = parseYear(article.year);
+    return {
+        source: "pubmed",
+        sourceRecordId: article.pmid,
+        identifiers: { pmid: article.pmid, ...(article.doi ? { doi: article.doi.toLocaleLowerCase("en-US") } : {}) },
+        ...(article.title ? { title: article.title } : {}),
+        ...(article.authors.length === 0 ? {} : { authors: article.authors }),
+        ...(year === undefined ? {} : { year }),
+        ...(article.journal ? { venue: article.journal } : {}),
+        url: `https://pubmed.ncbi.nlm.nih.gov/${article.pmid}/`,
+    };
+}
+export function createPubmedCitationClient(options = {}) {
+    const source = createPubmedSource(options);
+    async function resolve(request, signal) {
+        if (!request.plan.applicable)
+            return sourceOutcome("pubmed", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+        let requestCount = 0;
+        let pmids;
+        if (request.plan.operation === "pubmed_exact") {
+            pmids = [request.normalized.identifiers.pmid];
+        }
+        else if (request.plan.operation === "pubmed_structured") {
+            requestCount += 1;
+            const match = await source.matchCitation({
+                ...(request.input.venue === undefined ? {} : { venue: request.input.venue }),
+                ...(request.input.year === undefined ? {} : { year: request.input.year }),
+                ...(request.input.volume === undefined ? {} : { volume: request.input.volume }),
+                ...(request.input.firstPage === undefined ? {} : { firstPage: request.input.firstPage }),
+                ...(request.input.authors?.[0] === undefined ? {} : { firstAuthor: request.input.authors[0] }),
+                key: "citation-0",
+            }, signal);
+            if (match.status !== "ok")
+                return sourceOutcome("pubmed", request.plan.operation, match.status, requestCount, [], match.detail);
+            pmids = match.value;
+        }
+        else {
+            requestCount += 1;
+            const term = request.plan.operation === "pubmed_doi" ? `${request.normalized.identifiers.doi}[AID]` : `${request.input.title ?? ""}[Title]`;
+            const search = await source.searchIds(term, options.maxCandidates ?? 5, signal);
+            if (search.status !== "ok")
+                return sourceOutcome("pubmed", request.plan.operation, search.status, requestCount, [], search.detail);
+            pmids = search.value;
+        }
+        if (pmids.length === 0)
+            return sourceOutcome("pubmed", request.plan.operation, "no_data", requestCount);
+        requestCount += 1;
+        const fetched = await source.fetchArticles(pmids, signal);
+        if (fetched.status !== "ok")
+            return sourceOutcome("pubmed", request.plan.operation, fetched.status, requestCount, [], fetched.detail);
+        const records = fetched.value.map(pubmedRecord);
+        return sourceOutcome("pubmed", request.plan.operation, records.length === 0 ? "no_data" : "ok", requestCount, records);
+    }
+    async function resolveMany(requests, signal) {
+        const results = Array.from({ length: requests.length });
+        const exact = requests.flatMap((request, index) => request.plan.applicable && request.plan.operation === "pubmed_exact" && request.normalized.identifiers.pmid !== undefined
+            ? [{ index, request, pmid: request.normalized.identifiers.pmid }]
+            : []);
+        for (let offset = 0; offset < exact.length; offset += 20) {
+            const chunk = exact.slice(offset, offset + 20);
+            const fetched = await source.fetchArticles(chunk.map(({ pmid }) => pmid), signal);
+            if (fetched.status !== "ok") {
+                for (const entry of chunk)
+                    results[entry.index] = sourceOutcome("pubmed", entry.request.plan.operation, fetched.status, 1, [], fetched.detail);
+                continue;
+            }
+            const byPmid = new Map(fetched.value.map((article) => [article.pmid, pubmedRecord(article)]));
+            for (const entry of chunk) {
+                const record = byPmid.get(entry.pmid);
+                results[entry.index] = sourceOutcome("pubmed", entry.request.plan.operation, record === undefined ? "no_data" : "ok", 1, record === undefined ? [] : [record]);
+            }
+        }
+        await Promise.all(requests.map(async (request, index) => {
+            if (results[index] === undefined)
+                results[index] = await resolve(request, signal);
+        }));
+        return results.map((result) => result);
+    }
+    return { source: "pubmed", resolve, resolveMany };
+}

package/dist/citations/clients/semantic-scholar.d.ts

@@ -0,0 +1,6 @@
+import type { CitationSourceClient } from "../types.js";
+import { type SemanticScholarSourceOptions } from "../../literature/sources/semantic-scholar.js";
+export interface SemanticScholarCitationClientOptions extends SemanticScholarSourceOptions {
+    readonly maxCandidates?: number;
+}
+export declare function createSemanticScholarCitationClient(options?: SemanticScholarCitationClientOptions): CitationSourceClient;

package/dist/citations/clients/semantic-scholar.js

@@ -0,0 +1,60 @@
+import { createSemanticScholarSource } from "../../literature/sources/semantic-scholar.js";
+import { firstNonEmpty, sourceOutcome } from "./common.js";
+function externalId(value, key) {
+    const found = value?.[key];
+    return found?.trim() ? found.trim() : undefined;
+}
+function semanticRecord(paper) {
+    const doi = externalId(paper.externalIds, "DOI")?.toLocaleLowerCase("en-US");
+    const pmid = externalId(paper.externalIds, "PubMed");
+    const arxiv = externalId(paper.externalIds, "ArXiv")?.toLocaleLowerCase("en-US");
+    const corpusId = firstNonEmpty([externalId(paper.externalIds, "CorpusId"), paper.id]);
+    return {
+        source: "semantic_scholar",
+        sourceRecordId: paper.id,
+        identifiers: {
+            ...(doi === undefined ? {} : { doi }),
+            ...(pmid === undefined ? {} : { pmid }),
+            ...(arxiv === undefined ? {} : { arxiv }),
+            ...(corpusId === undefined ? {} : { corpusId }),
+        },
+        ...(paper.title === undefined ? {} : { title: paper.title }),
+        ...(paper.authors.length === 0 ? {} : { authors: paper.authors }),
+        ...(paper.year === undefined ? {} : { year: paper.year }),
+        ...(paper.venue === undefined ? {} : { venue: paper.venue }),
+        ...(paper.url === undefined ? {} : { url: paper.url }),
+    };
+}
+export function createSemanticScholarCitationClient(options = {}) {
+    const source = createSemanticScholarSource(options);
+    return {
+        source: "semantic_scholar",
+        async resolve(request, signal) {
+            if (!request.plan.applicable)
+                return sourceOutcome("semantic_scholar", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+            const identifier = request.normalized.identifiers.doi
+                ? `DOI:${request.normalized.identifiers.doi}`
+                : request.normalized.identifiers.pmid
+                    ? `PMID:${request.normalized.identifiers.pmid}`
+                    : request.normalized.identifiers.arxiv
+                        ? `ARXIV:${request.normalized.identifiers.arxiv}`
+                        : undefined;
+            const exact = request.plan.operation === "semantic_scholar_identifier" && identifier !== undefined;
+            let papers;
+            if (exact) {
+                const result = await source.lookupIdentifier(identifier, signal);
+                if (result.status !== "ok")
+                    return sourceOutcome("semantic_scholar", request.plan.operation, result.status, 1, [], result.detail);
+                papers = [result.value];
+            }
+            else {
+                const result = await source.search(request.input.title ?? request.input.citation, options.maxCandidates ?? 5, signal);
+                if (result.status !== "ok")
+                    return sourceOutcome("semantic_scholar", request.plan.operation, result.status, 1, [], result.detail);
+                papers = result.value;
+            }
+            const records = papers.map(semanticRecord);
+            return sourceOutcome("semantic_scholar", request.plan.operation, records.length === 0 ? "no_data" : "ok", 1, records);
+        },
+    };
+}

package/dist/citations/compare.d.ts

@@ -0,0 +1,9 @@
+import type { CitationCandidateCluster, CitationConflict, CitationFieldComparison, CitationInput } from "./types.js";
+/**
+ * Stamped onto every field comparison so a consumer can tell which rules
+ * produced it. Bump it when the published comparison semantics change — a
+ * revision made before these rules ever shipped is not a new version.
+ */
+export declare const CITATION_COMPARISON_RULE_VERSION = "citation-compare-v1";
+export declare function compareSuppliedMetadata(input: CitationInput, selected: CitationCandidateCluster | undefined): CitationFieldComparison[];
+export declare function detectCitationConflicts(clusters: readonly CitationCandidateCluster[]): CitationConflict[];

package/dist/citations/compare.js

@@ -0,0 +1,72 @@
+import { authorNamesMatch, normalizeAuthor, normalizeComparable } from "./normalize.js";
+/**
+ * Stamped onto every field comparison so a consumer can tell which rules
+ * produced it. Bump it when the published comparison semantics change — a
+ * revision made before these rules ever shipped is not a new version.
+ */
+export const CITATION_COMPARISON_RULE_VERSION = "citation-compare-v1";
+const FIELDS = ["title", "authors", "year", "venue", "volume", "firstPage"];
+function recordValue(record, field) {
+    return record[field];
+}
+function normalizedValue(field, value) {
+    if (field === "authors")
+        return value.map(normalizeAuthor).sort().join("|");
+    if (field === "year")
+        return String(value);
+    return normalizeComparable(String(value));
+}
+function authorMatch(supplied, source) {
+    return supplied.every((author) => source.some((candidate) => authorNamesMatch(author, candidate)));
+}
+function fieldMatches(field, supplied, source) {
+    if (field === "authors")
+        return authorMatch(supplied, source);
+    if (field === "year")
+        return Math.abs(Number(supplied) - Number(source)) <= 1;
+    if (field === "title" || field === "venue") {
+        const left = new Set(normalizeComparable(String(supplied)).split(" ").filter(Boolean));
+        const right = new Set(normalizeComparable(String(source)).split(" ").filter(Boolean));
+        if (left.size === 0 || right.size === 0)
+            return false;
+        let shared = 0;
+        for (const token of left)
+            if (right.has(token))
+                shared += 1;
+        return (2 * shared) / (left.size + right.size) >= 0.92;
+    }
+    return normalizedValue(field, supplied) === normalizedValue(field, source);
+}
+function sourceValues(cluster, field) {
+    return cluster.records.flatMap((record) => {
+        const value = recordValue(record, field);
+        return value === undefined ? [] : [{ source: record.source, value }];
+    });
+}
+export function compareSuppliedMetadata(input, selected) {
+    if (selected === undefined)
+        return [];
+    return FIELDS.flatMap((field) => {
+        const supplied = input[field];
+        if (supplied === undefined)
+            return [];
+        const values = sourceValues(selected, field);
+        const status = values.length === 0 ? "not_compared" : values.every(({ value }) => fieldMatches(field, supplied, value)) ? "match" : "mismatch";
+        return [
+            {
+                field,
+                status,
+                supplied,
+                sourceValues: values,
+                ruleVersion: CITATION_COMPARISON_RULE_VERSION,
+            },
+        ];
+    });
+}
+export function detectCitationConflicts(clusters) {
+    return clusters.flatMap((cluster) => FIELDS.flatMap((field) => {
+        const values = sourceValues(cluster, field);
+        const unique = new Set(values.map(({ value }) => normalizedValue(field, value)));
+        return unique.size > 1 ? [{ field, values }] : [];
+    }));
+}

package/dist/citations/match.d.ts

@@ -0,0 +1,11 @@
+import type { CitationCandidateCluster, CitationInput, CitationRecord, NormalizedCitation } from "./types.js";
+export interface CitationMatchConfig {
+    readonly minimumScore: number;
+    readonly separationMargin: number;
+    readonly clusterSimilarity: number;
+    readonly relatedVersionSimilarity: number;
+}
+export declare const DEFAULT_MATCH_CONFIG: CitationMatchConfig;
+export declare function tokenSimilarity(left: string, right: string): number;
+export declare function clusterCitationRecords(input: CitationInput, normalized: NormalizedCitation, records: readonly CitationRecord[], config?: CitationMatchConfig): CitationCandidateCluster[];
+export declare function selectCitationCluster(clusters: readonly CitationCandidateCluster[], config?: CitationMatchConfig): CitationCandidateCluster | undefined;

package/dist/citations/match.js

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+import { authorNamesMatch, normalizeAuthor, normalizeComparable } from "./normalize.js";
+export const DEFAULT_MATCH_CONFIG = {
+    minimumScore: 0.72,
+    separationMargin: 0.08,
+    clusterSimilarity: 0.9,
+    relatedVersionSimilarity: 0.9,
+};
+function tokens(value) {
+    return new Set(normalizeComparable(value)
+        .split(" ")
+        .filter((token) => token.length > 1));
+}
+export function tokenSimilarity(left, right) {
+    const a = tokens(left);
+    const b = tokens(right);
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const token of a)
+        if (b.has(token))
+            intersection += 1;
+    const dice = (2 * intersection) / (a.size + b.size);
+    const containment = intersection / Math.min(a.size, b.size);
+    return Math.max(dice, containment * 0.96);
+}
+function normalizedAuthors(authors) {
+    return [...new Set((authors ?? []).map(normalizeAuthor).filter(Boolean))];
+}
+function authorSimilarity(left, right) {
+    const a = normalizedAuthors(left);
+    const b = normalizedAuthors(right);
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const intersection = a.filter((author) => b.some((candidate) => authorNamesMatch(author, candidate))).length;
+    return intersection / Math.min(a.length, b.length);
+}
+function identifierEntries(identifiers) {
+    return Object.entries(identifiers).flatMap(([kind, value]) => (value === undefined ? [] : [`${kind}:${value.toLocaleLowerCase("en-US")}`]));
+}
+function sharesStrongIdentifier(left, right) {
+    const rightIds = new Set(identifierEntries(right.identifiers));
+    return identifierEntries(left.identifiers).some((identifier) => rightIds.has(identifier));
+}
+function hasStrongIdentifier(record) {
+    return identifierEntries(record.identifiers).length > 0;
+}
+function recordSimilarity(left, right) {
+    const weighted = [];
+    if (left.title && right.title)
+        weighted.push([tokenSimilarity(left.title, right.title), 0.7]);
+    if (left.authors && right.authors)
+        weighted.push([authorSimilarity(left.authors, right.authors), 0.2]);
+    if (left.year !== undefined && right.year !== undefined)
+        weighted.push([left.year === right.year ? 1 : Math.abs(left.year - right.year) === 1 ? 0.5 : 0, 0.1]);
+    const weight = weighted.reduce((sum, [, value]) => sum + value, 0);
+    return weight === 0 ? 0 : weighted.reduce((sum, [score, value]) => sum + score * value, 0) / weight;
+}
+function stableClusterId(records) {
+    const identity = records
+        .map((record) => `${record.source}:${record.sourceRecordId}`)
+        .sort()
+        .join("|");
+    return `cit-${createHash("sha256").update(identity).digest("hex").slice(0, 16)}`;
+}
+class UnionFind {
+    parent;
+    constructor(size) {
+        this.parent = Array.from({ length: size }, (_, index) => index);
+    }
+    find(index) {
+        const parent = this.parent[index];
+        if (parent === index)
+            return index;
+        const root = this.find(parent);
+        this.parent[index] = root;
+        return root;
+    }
+    union(left, right) {
+        const leftRoot = this.find(left);
+        const rightRoot = this.find(right);
+        if (leftRoot !== rightRoot)
+            this.parent[rightRoot] = leftRoot;
+    }
+}
+function clusterScore(input, normalized, records) {
+    const inputIds = new Set(identifierEntries(normalized.identifiers));
+    if (records.some((record) => identifierEntries(record.identifiers).some((identifier) => inputIds.has(identifier))))
+        return 1;
+    let best = 0;
+    for (const record of records) {
+        const signals = [];
+        if (record.title)
+            signals.push([tokenSimilarity(normalized.supplied.title ?? normalized.query, record.title), 0.65]);
+        if (normalized.supplied.authors && record.authors)
+            signals.push([authorSimilarity(normalized.supplied.authors, record.authors), 0.2]);
+        if (normalized.supplied.year !== undefined && record.year !== undefined) {
+            signals.push([normalized.supplied.year === record.year ? 1 : Math.abs(normalized.supplied.year - record.year) === 1 ? 0.5 : 0, 0.1]);
+        }
+        if (normalized.supplied.venue && record.venue)
+            signals.push([tokenSimilarity(normalized.supplied.venue, record.venue), 0.05]);
+        const weight = signals.reduce((sum, [, value]) => sum + value, 0);
+        const score = weight === 0 ? 0 : signals.reduce((sum, [value, signalWeight]) => sum + value * signalWeight, 0) / weight;
+        best = Math.max(best, score);
+    }
+    return best;
+}
+function containsId(cluster, key) {
+    return cluster.records.some((record) => record.identifiers[key] !== undefined);
+}
+function addRelatedVersions(clusters, config) {
+    for (let left = 0; left < clusters.length; left += 1) {
+        for (let right = left + 1; right < clusters.length; right += 1) {
+            const a = clusters[left];
+            const b = clusters[right];
+            const similarity = Math.max(...a.records.flatMap((one) => b.records.map((two) => recordSimilarity(one, two))));
+            if (similarity < config.relatedVersionSimilarity)
+                continue;
+            const aArxiv = containsId(a, "arxiv");
+            const bArxiv = containsId(b, "arxiv");
+            const aDoi = containsId(a, "doi");
+            const bDoi = containsId(b, "doi");
+            if (aArxiv && bDoi) {
+                a.relations.push({ clusterId: b.id, kind: "published_as" });
+                b.relations.push({ clusterId: a.id, kind: "preprint_of" });
+            }
+            else if (bArxiv && aDoi) {
+                a.relations.push({ clusterId: b.id, kind: "preprint_of" });
+                b.relations.push({ clusterId: a.id, kind: "published_as" });
+            }
+            else {
+                a.relations.push({ clusterId: b.id, kind: "related_version" });
+                b.relations.push({ clusterId: a.id, kind: "related_version" });
+            }
+        }
+    }
+}
+export function clusterCitationRecords(input, normalized, records, config = DEFAULT_MATCH_CONFIG) {
+    const union = new UnionFind(records.length);
+    for (let left = 0; left < records.length; left += 1) {
+        for (let right = left + 1; right < records.length; right += 1) {
+            const a = records[left];
+            const b = records[right];
+            if (sharesStrongIdentifier(a, b))
+                union.union(left, right);
+            else if ((!hasStrongIdentifier(a) || !hasStrongIdentifier(b)) && recordSimilarity(a, b) >= config.clusterSimilarity)
+                union.union(left, right);
+        }
+    }
+    const grouped = new Map();
+    for (let index = 0; index < records.length; index += 1) {
+        const root = union.find(index);
+        grouped.set(root, [...(grouped.get(root) ?? []), records[index]]);
+    }
+    const clusters = [...grouped.values()].map((members) => ({
+        id: stableClusterId(members),
+        score: clusterScore(input, normalized, members),
+        records: members,
+        relations: [],
+    }));
+    clusters.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+    addRelatedVersions(clusters, config);
+    return clusters;
+}
+export function selectCitationCluster(clusters, config = DEFAULT_MATCH_CONFIG) {
+    const first = clusters[0];
+    if (first === undefined || first.score < config.minimumScore)
+        return undefined;
+    const second = clusters[1];
+    if (second !== undefined && first.score - second.score < config.separationMargin)
+        return undefined;
+    return first;
+}

package/dist/citations/normalize.d.ts

@@ -0,0 +1,31 @@
+import { type CitationInput, type NormalizedCitation } from "./types.js";
+export declare function normalizeComparable(value: string): string;
+export declare function normalizeAuthor(value: string): string;
+/**
+ * Whether two author strings can name the same person. Written surname-position
+ * free, because citation styles disagree about it (`Smith, Jane A.`,
+ * `Jane A. Smith`, `Smith JA` all reach us) and normalization has already
+ * discarded the comma that would settle it.
+ *
+ * Sharing a name part is necessary but never sufficient: two spelled-out names
+ * that each carry a part the other lacks are different people, and where both
+ * sides supply given-name evidence it has to agree. Surname-only agreement is
+ * accepted only when one side supplies no given name at all — the case where
+ * there is nothing to contradict.
+ */
+export declare function authorNamesMatch(left: string, right: string): boolean;
+export declare function extractDoi(value: string): string | undefined;
+export declare function extractPmid(value: string): string | undefined;
+export declare function extractArxivId(value: string): string | undefined;
+export declare function normalizeCitation(unparsed: CitationInput): NormalizedCitation;
+/**
+ * Identity of the *lookups* an input provokes, not of the input itself.
+ *
+ * Two citations share this key when the authorities would be asked the same
+ * question, so they share one round of source outcomes; each caller's own
+ * supplied metadata is compared against those outcomes separately. An exact
+ * identifier is the whole question — every operation an identifier plan selects
+ * is driven by the identifier alone — so supplied metadata stays out of the key
+ * there. A free-text citation is dispatched from its metadata, and folds it in.
+ */
+export declare function citationLookupKey(input: CitationInput): string;