@inflexa-ai/harness 0.15.1 → 0.17.0

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;

package/dist/citations/normalize.js

@@ -0,0 +1,187 @@
+import { CitationInputSchema } from "./types.js";
+// Each registry defines its own identifier syntax, and each is matched here rather than parsed:
+// a citation string is prose, so the identifier has to be found inside it, not read off a field.
+// The DOI suffix is deliberately permissive — the registry allows nearly any character in it, so
+// there is no delimiter to stop at, and `trimDoiPunctuation` walks back the sentence punctuation
+// and brackets a greedy match swallows. PMID and arXiv anchor instead, having fixed shapes.
+const DOI_PATTERN = /(?:https?:\/\/(?:dx\.)?doi\.org\/|doi\s*:\s*)?(10\.\d{4,9}\/[^\s<>"']+)/i;
+const PMID_PATTERN = /^(?:pmid\s*:\s*)?(\d{1,9})$/i;
+const ARXIV_PATTERN = /^(?:https?:\/\/arxiv\.org\/(?:abs|pdf)\/|arxiv\s*:\s*)?((?:\d{4}\.\d{4,5}|[a-z-]+(?:\.[a-z-]+)?\/\d{7})(?:v\d+)?)(?:\.pdf)?$/i;
+function collapseWhitespace(value) {
+    return value.normalize("NFKC").replace(/\s+/g, " ").trim();
+}
+export function normalizeComparable(value) {
+    return collapseWhitespace(value)
+        .toLocaleLowerCase("en-US")
+        .replace(/[\p{P}\p{S}]+/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function normalizeAuthor(value) {
+    return normalizeComparable(value)
+        .replace(/\b(?:jr|sr|ii|iii|iv)\b/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function authorEvidence(value) {
+    const tokens = normalizeAuthor(value).split(" ").filter(Boolean);
+    return { words: tokens.filter((token) => token.length > 1), initials: tokens.filter((token) => token.length === 1) };
+}
+/**
+ * A token long enough to be a spelled-out name part rather than an unpunctuated
+ * block of initials. Two letters is the boundary: `Smith JA` and `Wu` are both
+ * live readings of the same shape, so a token that short is never treated as a
+ * name part that could contradict one.
+ */
+const SPELLED_OUT_MINIMUM = 3;
+/**
+ * The given-name letters a name can account for. A short leftover may itself be
+ * an initial block, so it contributes every letter; a spelled-out one
+ * contributes only the initial it would abbreviate to.
+ */
+function givenLetters(leftover, initials) {
+    return [...initials, ...leftover.flatMap((word) => (word.length < SPELLED_OUT_MINIMUM ? [...word] : [word[0]]))].sort();
+}
+function containsLetters(available, required) {
+    const pool = [...available];
+    return required.every((letter) => {
+        const index = pool.indexOf(letter);
+        if (index < 0)
+            return false;
+        pool.splice(index, 1);
+        return true;
+    });
+}
+/**
+ * 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 function authorNamesMatch(left, right) {
+    const a = authorEvidence(left);
+    const b = authorEvidence(right);
+    if (!a.words.some((word) => b.words.includes(word)))
+        return false;
+    const leftoverA = a.words.filter((word) => !b.words.includes(word));
+    const leftoverB = b.words.filter((word) => !a.words.includes(word));
+    const spelledOut = (leftover) => leftover.some((word) => word.length >= SPELLED_OUT_MINIMUM);
+    if (spelledOut(leftoverA) && spelledOut(leftoverB))
+        return false;
+    const lettersA = givenLetters(leftoverA, a.initials);
+    const lettersB = givenLetters(leftoverB, b.initials);
+    if (lettersA.length === 0 || lettersB.length === 0)
+        return true;
+    return lettersA.length <= lettersB.length ? containsLetters(lettersB, lettersA) : containsLetters(lettersA, lettersB);
+}
+function trimDoiPunctuation(value) {
+    let result = value.replace(/[.,;]+$/g, "");
+    const pairs = [
+        ["(", ")"],
+        ["[", "]"],
+        ["{", "}"],
+    ];
+    for (const [open, close] of pairs) {
+        while (result.endsWith(close) && result.split(open).length <= result.split(close).length)
+            result = result.slice(0, -1);
+    }
+    return result;
+}
+export function extractDoi(value) {
+    const match = collapseWhitespace(value).match(DOI_PATTERN);
+    if (!match?.[1])
+        return undefined;
+    return trimDoiPunctuation(match[1]).toLocaleLowerCase("en-US");
+}
+export function extractPmid(value) {
+    return collapseWhitespace(value).match(PMID_PATTERN)?.[1];
+}
+export function extractArxivId(value) {
+    const match = collapseWhitespace(value).match(ARXIV_PATTERN)?.[1];
+    return match?.toLocaleLowerCase("en-US").replace(/v\d+$/i, "");
+}
+function classifyUnsupportedWork(value) {
+    const normalized = normalizeComparable(value);
+    if (/\bpersonal communication\b/.test(normalized))
+        return "personal_communication";
+    if (/\bunpublished (?:data|work|manuscript)\b/.test(normalized))
+        return "unpublished";
+    if (/\b(?:in press|forthcoming)\b/.test(normalized))
+        return "unregistered_in_press";
+    return undefined;
+}
+function normalizedSupplied(input) {
+    return {
+        ...(input.title === undefined ? {} : { title: normalizeComparable(input.title) }),
+        ...(input.authors === undefined ? {} : { authors: input.authors.map(normalizeAuthor).filter(Boolean) }),
+        ...(input.year === undefined ? {} : { year: input.year }),
+        ...(input.venue === undefined ? {} : { venue: normalizeComparable(input.venue) }),
+        ...(input.volume === undefined ? {} : { volume: normalizeComparable(input.volume) }),
+        ...(input.firstPage === undefined ? {} : { firstPage: normalizeComparable(input.firstPage) }),
+    };
+}
+export function normalizeCitation(unparsed) {
+    const input = CitationInputSchema.parse(unparsed);
+    const citation = collapseWhitespace(input.citation);
+    const doi = extractDoi(citation);
+    const pmid = extractPmid(citation);
+    const arxiv = extractArxivId(citation);
+    const hint = input.kind ?? "auto";
+    let kind;
+    if (hint === "auto")
+        kind = doi ? "doi" : pmid ? "pmid" : arxiv ? "arxiv" : "free_text";
+    else
+        kind = hint;
+    if (kind === "doi" && doi === undefined)
+        throw new Error("citation kind is doi but no valid DOI was found");
+    if (kind === "pmid" && pmid === undefined)
+        throw new Error("citation kind is pmid but no valid PMID was found");
+    if (kind === "arxiv" && arxiv === undefined)
+        throw new Error("citation kind is arxiv but no valid arXiv id was found");
+    const unsupportedWorkKind = kind === "free_text" ? classifyUnsupportedWork(citation) : undefined;
+    // A pinned `free_text` kind asserts the citation carries no usable identifier — `auto`
+    // would have classified it otherwise. Publishing one anyway splits the pipeline against
+    // itself: the plan gives the citation bibliographic-only treatment while candidate
+    // scoring short-circuits to a perfect match on an identifier nothing verified.
+    const identified = kind !== "free_text";
+    return {
+        citation,
+        query: normalizeComparable(citation),
+        kind,
+        identifiers: {
+            ...(doi === undefined || !identified ? {} : { doi }),
+            ...(pmid === undefined || !identified ? {} : { pmid }),
+            ...(arxiv === undefined || !identified ? {} : { arxiv }),
+        },
+        supplied: normalizedSupplied(input),
+        ...(unsupportedWorkKind === undefined ? {} : { unsupportedWorkKind }),
+    };
+}
+/**
+ * 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 function citationLookupKey(input) {
+    const normalized = normalizeCitation(input);
+    return JSON.stringify(normalized.kind === "free_text"
+        ? {
+            kind: normalized.kind,
+            identifiers: normalized.identifiers,
+            query: normalized.query,
+            supplied: normalized.supplied,
+            unsupportedWorkKind: normalized.unsupportedWorkKind ?? null,
+        }
+        : { kind: normalized.kind, identifiers: normalized.identifiers });
+}

package/dist/citations/plan.d.ts

@@ -0,0 +1,2 @@
+import type { CitationInput, CitationSourcePlanItem, NormalizedCitation } from "./types.js";
+export declare function planCitationSources(input: CitationInput, normalized: NormalizedCitation): CitationSourcePlanItem[];