@khorsheed/dsh-reader 0.2.0

package/lib/types/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Reader plugin, host half: provides the service core and mounts its Remote
+ * face. Composing this plugin out of a profile removes every surface it adds.
+ *
+ * The host half owns the two things the browser cannot do: reaching the
+ * network through the sanctioned `ctx.web` seam, and persisting state next to
+ * the deployment. The browser half owns parsing. See `service.ts` for the
+ * fetch policy and `store.ts` for the persistence shape; both are deliberately
+ * mirrored on the side-chat precedent so this package reads like its
+ * neighbours.
+ *
+ * @module @khorsheed/dsh-reader
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { ReaderService } from './service.ts';
+export { ReaderService, classifyPayload, normalizeUrl } from './service.ts';
+export { ReaderRemoteService } from './remote.ts';
+export type { ReaderRemoteConfig } from './remote.ts';
+export { MAX_CACHED_BODIES, MAX_TAGS, ReaderStore, ReaderStoreError, boundAnnotations, boundPayloads, emptyStateDoc, normalizeStateDoc, pruneOrphanTags, resolveReaderStateRoot, serializeStateDoc, } from './store.ts';
+export type { ReaderStoreRead } from './store.ts';
+export * from './schedule.ts';
+export * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The reader plugin's service core. */
+        reader: ReaderService;
+    }
+}
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "reader";
+/** Optional state-root override, for deployments that keep state elsewhere. */
+export interface ReaderConfig {
+    /** Directory holding `state.json`; defaults to `$DSH_HOME/state/dsh-reader`. */
+    readonly stateRoot?: string;
+}
+/**
+ * Plugin body: provide the service core, then mount the Remote data face.
+ *
+ * No `static inject`: every optional capability (`fs`, `web`, `sideChat`) is
+ * probed at the point of use, so the row boots in any composition and degrades
+ * — memory-only state without `fs`, `unsupported-content` without `web`, a
+ * hidden side-chat gesture without `sideChat`.
+ *
+ * @param ctx - owning Cordis context.
+ * @param config - optional plugin config.
+ */
+export declare function apply(ctx: Context, config?: ReaderConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,25 @@
+import { ReaderService } from "./service.js";
+import { ReaderRemoteService } from "./remote.js";
+export { ReaderService, classifyPayload, normalizeUrl } from "./service.js";
+export { ReaderRemoteService } from "./remote.js";
+export { MAX_CACHED_BODIES, MAX_TAGS, ReaderStore, ReaderStoreError, boundAnnotations, boundPayloads, emptyStateDoc, normalizeStateDoc, pruneOrphanTags, resolveReaderStateRoot, serializeStateDoc, } from "./store.js";
+export * from "./schedule.js";
+export * from "./types.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'reader';
+/**
+ * Plugin body: provide the service core, then mount the Remote data face.
+ *
+ * No `static inject`: every optional capability (`fs`, `web`, `sideChat`) is
+ * probed at the point of use, so the row boots in any composition and degrades
+ * — memory-only state without `fs`, `unsupported-content` without `web`, a
+ * hidden side-chat gesture without `sideChat`.
+ *
+ * @param ctx - owning Cordis context.
+ * @param config - optional plugin config.
+ */
+export function apply(ctx, config = {}) {
+    const service = new ReaderService(ctx, config);
+    ctx.provide('reader', service);
+    ctx.plugin(ReaderRemoteService, {});
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-reader`.
+ * @module @khorsheed/dsh-reader/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants';
+/** Cordis companion plugin name. */
+export declare const name = "reader-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Capability probe for the reader: the host half fetches and persists, so it
+ * needs a runtime that has `URL` (for the source-URL policy) and a timer (for
+ * the daily refresh). Both are standard in a dsh host, so this is a
+ * low-value check — registered for package-ownership consistency, and kept
+ * pure (no network, no filesystem, no session) so a broken deployment is never
+ * reported as a healthy one and vice versa.
+ *
+ * @param _ctx - host context (unused; the probe touches process globals only).
+ * @param fail - invariant failure reporter.
+ */
+export declare const install: InvariantInstaller;
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,38 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-reader`.
+ * @module @khorsheed/dsh-reader/invariant
+ */
+/** The identity the package publishes under (the manifest's `name`). */
+const PACKAGE_NAME = '@khorsheed/dsh-reader';
+/** Cordis companion plugin name. */
+export const name = 'reader-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Capability probe for the reader: the host half fetches and persists, so it
+ * needs a runtime that has `URL` (for the source-URL policy) and a timer (for
+ * the daily refresh). Both are standard in a dsh host, so this is a
+ * low-value check — registered for package-ownership consistency, and kept
+ * pure (no network, no filesystem, no session) so a broken deployment is never
+ * reported as a healthy one and vice versa.
+ *
+ * @param _ctx - host context (unused; the probe touches process globals only).
+ * @param fail - invariant failure reporter.
+ */
+export const install = async (_ctx, fail) => {
+    try {
+        if (typeof globalThis.URL !== 'function')
+            fail('reader requires a runtime with URL');
+        if (typeof globalThis.setTimeout !== 'function')
+            fail('reader requires a runtime with timers');
+    }
+    catch {
+        fail('reader requires a standard node runtime');
+    }
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

package/lib/types/link-resolvers.d.ts

@@ -0,0 +1,107 @@
+import type { ReaderPreviewFailureCode } from './types.ts';
+/** What a resolver makes of a link it owns. */
+export type LinkResolution = {
+    readonly kind: 'arxiv';
+    /** The paper's arXiv id, version included, as the API reported it. */
+    readonly id: string;
+    /** The paper's title on arXiv — the saved card's default label. */
+    readonly title: string;
+} | {
+    readonly kind: 'link-only';
+    readonly code: ReaderPreviewFailureCode;
+    /** The classifier's own words, kept for diagnosis (the locale sentence rides the code). */
+    readonly message: string;
+};
+/**
+ * The network face a resolver may use: one GET, the status and the decoded
+ * body. Injected — in production it is the host's sanctioned `ctx.web` seam;
+ * in tests a script.
+ */
+export type ResolverFetch = (url: string) => Promise<{
+    readonly statusCode: number;
+    readonly body: string;
+}>;
+/** One row of the resolver table. */
+export interface LinkResolver {
+    /** The source's name, for logs and tests. */
+    readonly name: string;
+    /** Whether this URL is the source's. Cheap and total — no network. */
+    readonly match: (url: URL) => boolean;
+    /** Resolve a matched URL, or return null to leave it to the ordinary path. */
+    readonly resolve: (url: URL, fetch: ResolverFetch) => Promise<LinkResolution | null>;
+}
+/**
+ * The gate a title-search candidate must pass. Normalized edit similarity ≥ the
+ * floor, PLUS one shared author family name when both sides name authors;
+ * authorless comparisons rise to the strict bar.
+ */
+export declare const TITLE_SIMILARITY_MIN = 0.85;
+export declare const TITLE_SIMILARITY_STRICT = 0.95;
+/** One arXiv search hit, parsed. */
+export interface ArxivSearchHit {
+    readonly id: string;
+    readonly title: string;
+    readonly authors: readonly string[];
+}
+/**
+ * Lowercase, accent-folded, punctuation-to-space — the form two titles are
+ * compared in. CJK characters are letters for this purpose (a Japanese paper
+ * title must not collapse to nothing).
+ */
+export declare function normalizeTitle(title: string): string;
+/** Levenshtein distance, two rows, on ALREADY-normalized titles. */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * How alike two titles are: 1 for identical after normalization, 0 for nothing
+ * in common. Either side empty is a 0 — there is nothing to compare.
+ */
+export declare function titleSimilarity(a: string, b: string): number;
+/**
+ * The family-name set of an author list, accent-folded and lowercased.
+ *
+ * Full names ("Nicholas G. Polson", the arXiv spelling) reduce to their last
+ * token; structured records (Crossref's `family`) arrive already reduced.
+ */
+export declare function familyNames(authors: readonly string[]): Set<string>;
+/**
+ * Whether one arXiv hit may stand in for the paper a DOI names.
+ *
+ * The author factor is what makes "no match → degrade" honest: short generic
+ * titles collide across DIFFERENT papers (measured: Crossref's "Deep learning"
+ * — LeCun, Bengio, Hinton — is a perfect title match for arXiv's "Deep
+ * Learning" — Polson, Sokolov), so title similarity alone guesses.
+ *
+ * @param candidate - the arXiv hit.
+ * @param wanted - the Crossref record's title and authors.
+ * @returns true when the candidate is the same paper beyond a title accident.
+ */
+export declare function gateArxivCandidate(candidate: {
+    readonly title: string;
+    readonly authors: readonly string[];
+}, wanted: {
+    readonly title: string;
+    readonly authors: readonly string[];
+}): boolean;
+/** The title phrase the arXiv API is asked for: the title's first words, quote-safe. */
+export declare function titleQuery(title: string): string;
+/**
+ * The entries of an arXiv API Atom answer. A deliberately narrow read — the
+ * host runtime has no XML parser, and this document's shape is fixed: each
+ * `<entry>` carries its `<id>` (the abs URL) and `<title>` first.
+ */
+export declare function parseArxivSearch(xml: string): ArxivSearchHit[];
+/** The resolver table, in match order. */
+export declare const LINK_RESOLVERS: readonly LinkResolver[];
+/**
+ * Resolve a pasted link through the table.
+ *
+ * `null` — not an answer, but the ABSENCE of one — sends the URL down the
+ * ordinary fetch-and-classify path. A resolver's own failure is caught by the
+ * caller (the service): a DOI lookup that throws must not break an add.
+ *
+ * @param url - the normalized pasted URL.
+ * @param fetch - the injected GET face.
+ * @returns the resolution, or `null`.
+ */
+export declare function resolveLink(url: string, fetch: ResolverFetch): Promise<LinkResolution | null>;
+//# sourceMappingURL=link-resolvers.d.ts.map

package/lib/types/link-resolvers.js

@@ -0,0 +1,299 @@
+/**
+ * Paper-link resolvers: turn a link that NAMES a paper into the paper itself.
+ *
+ * A DOI or an OpenReview URL is a reference, not a readable page: doi.org
+ * answers a cross-origin redirect the host seam refuses by design, and
+ * openreview.net cannot be read server-side at all (measured 2026-09-20: the
+ * API sits behind a Cloudflare challenge, the forum is a JS SPA whose static
+ * title is always "Forum | OpenReview"). For such links the add flow asks this
+ * module BEFORE fetching anything.
+ *
+ * Table-driven: one resolver per source, each answering an arXiv candidate, an
+ * honest link-only verdict, or `null` ("not mine — take the ordinary path").
+ * New sources (dblp, Semantic Scholar) are new rows, not new plumbing. The
+ * network face is injected, so every branch is testable without a socket.
+ *
+ * The one rule the module exists to enforce: **a resolution is proven or
+ * absent, never guessed.** A candidate that fails the gate degrades to the
+ * ordinary path — a wrong paper filed under the reader's link is worse than a
+ * card that says "open it in a browser".
+ *
+ * @module @khorsheed/dsh-reader/link-resolvers
+ */
+import { isArxivId } from "./arxiv.js";
+/* ------------------------------------------------------------------ the DOI resolver */
+/** The DOI resolver covers the doi.org alias hosts; publisher URLs are out of scope. */
+const DOI_HOSTS = new Set(['doi.org', 'www.doi.org', 'dx.doi.org']);
+/** A DOI is `10.<registrant>/<suffix>`; the registrant is 4–9 digits. */
+const DOI_PATH = /^\/(10\.\d{4,9}\/\S+)/;
+/** Crossref's filtered list route — see the resolver's doc comment on why not the work route. */
+const CROSSREF_SELECT = 'DOI,title,author';
+/** The arXiv API phrase search silently answers nothing beyond six terms (measured). */
+const TITLE_QUERY_WORDS = 6;
+/** How many candidates one title search is read for. */
+const ARXIV_SEARCH_RESULTS = 5;
+/**
+ * The gate a title-search candidate must pass. Normalized edit similarity ≥ the
+ * floor, PLUS one shared author family name when both sides name authors;
+ * authorless comparisons rise to the strict bar.
+ */
+export const TITLE_SIMILARITY_MIN = 0.85;
+export const TITLE_SIMILARITY_STRICT = 0.95;
+/**
+ * Lowercase, accent-folded, punctuation-to-space — the form two titles are
+ * compared in. CJK characters are letters for this purpose (a Japanese paper
+ * title must not collapse to nothing).
+ */
+export function normalizeTitle(title) {
+    return title
+        .normalize('NFKD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+}
+/** Levenshtein distance, two rows, on ALREADY-normalized titles. */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/**
+ * How alike two titles are: 1 for identical after normalization, 0 for nothing
+ * in common. Either side empty is a 0 — there is nothing to compare.
+ */
+export function titleSimilarity(a, b) {
+    const left = normalizeTitle(a);
+    const right = normalizeTitle(b);
+    if (left.length === 0 || right.length === 0)
+        return 0;
+    if (left === right)
+        return 1;
+    return 1 - editDistance(left, right) / Math.max(left.length, right.length);
+}
+/**
+ * The family-name set of an author list, accent-folded and lowercased.
+ *
+ * Full names ("Nicholas G. Polson", the arXiv spelling) reduce to their last
+ * token; structured records (Crossref's `family`) arrive already reduced.
+ */
+export function familyNames(authors) {
+    const names = new Set();
+    for (const author of authors) {
+        const last = normalizeTitle(author).split(' ').filter(part => part.length > 0).at(-1);
+        if (last !== undefined)
+            names.add(last);
+    }
+    return names;
+}
+/**
+ * Whether one arXiv hit may stand in for the paper a DOI names.
+ *
+ * The author factor is what makes "no match → degrade" honest: short generic
+ * titles collide across DIFFERENT papers (measured: Crossref's "Deep learning"
+ * — LeCun, Bengio, Hinton — is a perfect title match for arXiv's "Deep
+ * Learning" — Polson, Sokolov), so title similarity alone guesses.
+ *
+ * @param candidate - the arXiv hit.
+ * @param wanted - the Crossref record's title and authors.
+ * @returns true when the candidate is the same paper beyond a title accident.
+ */
+export function gateArxivCandidate(candidate, wanted) {
+    const similarity = titleSimilarity(candidate.title, wanted.title);
+    const candidateNames = familyNames(candidate.authors);
+    const wantedNames = familyNames(wanted.authors);
+    if (candidateNames.size === 0 || wantedNames.size === 0)
+        return similarity >= TITLE_SIMILARITY_STRICT;
+    const overlap = [...candidateNames].some(name => wantedNames.has(name));
+    return similarity >= TITLE_SIMILARITY_MIN && overlap;
+}
+/** The title phrase the arXiv API is asked for: the title's first words, quote-safe. */
+export function titleQuery(title) {
+    const words = title.replace(/\s+/g, ' ').trim().split(' ');
+    return words.slice(0, TITLE_QUERY_WORDS).join(' ').replace(/"+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * The entries of an arXiv API Atom answer. A deliberately narrow read — the
+ * host runtime has no XML parser, and this document's shape is fixed: each
+ * `<entry>` carries its `<id>` (the abs URL) and `<title>` first.
+ */
+export function parseArxivSearch(xml) {
+    const hits = [];
+    for (const block of xml.split('<entry>').slice(1)) {
+        const id = /<id>https?:\/\/arxiv\.org\/abs\/([^<]+)<\/id>/.exec(block)?.[1]?.trim();
+        const rawTitle = /<title>([\s\S]*?)<\/title>/.exec(block)?.[1];
+        if (id === undefined || rawTitle === undefined || !isArxivId(id))
+            continue;
+        hits.push({
+            id,
+            title: unescapeXml(rawTitle).replace(/\s+/g, ' ').trim(),
+            authors: [...block.matchAll(/<name>([^<]+)<\/name>/g)].map(match => unescapeXml(match[1]).trim()),
+        });
+    }
+    return hits;
+}
+/** The few entities an API title can carry. */
+function unescapeXml(value) {
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&amp;/g, '&');
+}
+/**
+ * Ask the arXiv API for papers titled like `title`.
+ *
+ * The phrase search accepts at most {@link TITLE_QUERY_WORDS} terms (measured:
+ * a 7-word phrase answers an empty feed where its 6-word prefix finds the
+ * paper), so the query is the title's prefix, and precision is the gate's job,
+ * not the query's.
+ */
+async function searchArxiv(title, fetch) {
+    const phrase = titleQuery(title);
+    if (phrase.length === 0)
+        return [];
+    const url = `https://export.arxiv.org/api/query?${new URLSearchParams({
+        search_query: `ti:"${phrase}"`,
+        max_results: String(ARXIV_SEARCH_RESULTS),
+    }).toString()}`;
+    let body;
+    try {
+        const response = await fetch(url);
+        if (response.statusCode !== 200)
+            return [];
+        body = response.body;
+    }
+    catch {
+        return [];
+    }
+    return parseArxivSearch(body);
+}
+/**
+ * The title and authors Crossref has for one DOI, or `null`.
+ *
+ * The LIST route with a `doi:` filter is used, not `/works/<doi>`: the
+ * single-work route rejects `select` (measured: `parameter-not-allowed`), and
+ * an unfiltered work record can carry hundreds of references — past the fetch
+ * seam's body cap, which truncates JSON into something unparseable. The
+ * filtered route answers a few hundred bytes. A DOI Crossref does not know
+ * (404, empty items) is not an error here: it is the ordinary path's business.
+ */
+async function crossrefWork(doi, fetch) {
+    const url = `https://api.crossref.org/works?${new URLSearchParams({
+        filter: `doi:${doi}`,
+        select: CROSSREF_SELECT,
+    }).toString()}`;
+    let parsed;
+    try {
+        const response = await fetch(url);
+        if (response.statusCode !== 200)
+            return null;
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        // A truncated or malformed record is "no answer", never a crash.
+        return null;
+    }
+    const items = parsed?.message?.items;
+    const work = Array.isArray(items) ? items[0] : undefined;
+    if (typeof work !== 'object' || work === null)
+        return null;
+    const record = work;
+    const title = Array.isArray(record.title) ? record.title.find(item => typeof item === 'string' && item.length > 0) : undefined;
+    if (typeof title !== 'string')
+        return null;
+    const authors = Array.isArray(record.author)
+        ? record.author.flatMap((author) => {
+            const family = author?.family;
+            return typeof family === 'string' && family.length > 0 ? [family] : [];
+        })
+        : [];
+    return { title, authors };
+}
+/** doi.org/<doi> → Crossref → gated arXiv candidate. */
+const doiResolver = {
+    name: 'doi',
+    match: url => DOI_HOSTS.has(url.hostname.toLowerCase()) && DOI_PATH.test(url.pathname),
+    resolve: async (url, fetch) => {
+        const doi = decodeURIComponent(DOI_PATH.exec(url.pathname)?.[1] ?? '');
+        if (doi.length === 0)
+            return null;
+        const work = await crossrefWork(doi, fetch);
+        if (work === null)
+            return null;
+        const hits = await searchArxiv(work.title, fetch);
+        let best;
+        for (const hit of hits) {
+            const similarity = titleSimilarity(hit.title, work.title);
+            if (best === undefined || similarity > best.similarity)
+                best = { hit, similarity };
+        }
+        if (best === undefined || !gateArxivCandidate(best.hit, work))
+            return null;
+        return { kind: 'arxiv', id: best.hit.id, title: best.hit.title };
+    },
+};
+/* ----------------------------------------------------------- the OpenReview resolver */
+/**
+ * OpenReview cannot be read server-side, and that is KNOWN without a request:
+ * the forum is a JS SPA behind an anti-bot wall (measured 2026-09-20: the API
+ * 403s with a Cloudflare challenge; the forum's static HTML always titles
+ * itself "Forum | OpenReview"). The resolver answers the honest card instead
+ * of spending a fetch to learn it again. A future capture backend (the ingest
+ * proposal's M1) is where a rendered read of the forum belongs.
+ */
+const openReviewResolver = {
+    name: 'openreview',
+    match: url => {
+        const host = url.hostname.toLowerCase();
+        if (host !== 'openreview.net' && host !== 'www.openreview.net')
+            return false;
+        return (url.pathname === '/forum' || url.pathname === '/pdf') && (url.searchParams.get('id') ?? '').length > 0;
+    },
+    resolve: () => Promise.resolve({
+        kind: 'link-only',
+        code: 'unreadable',
+        message: 'OpenReview pages are script-rendered behind an anti-bot wall, so the server side cannot read them — if the paper has an arXiv version, paste that link instead',
+    }),
+};
+/** The resolver table, in match order. */
+export const LINK_RESOLVERS = [doiResolver, openReviewResolver];
+/**
+ * Resolve a pasted link through the table.
+ *
+ * `null` — not an answer, but the ABSENCE of one — sends the URL down the
+ * ordinary fetch-and-classify path. A resolver's own failure is caught by the
+ * caller (the service): a DOI lookup that throws must not break an add.
+ *
+ * @param url - the normalized pasted URL.
+ * @param fetch - the injected GET face.
+ * @returns the resolution, or `null`.
+ */
+export async function resolveLink(url, fetch) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    for (const resolver of LINK_RESOLVERS) {
+        if (resolver.match(parsed))
+            return resolver.resolve(parsed, fetch);
+    }
+    return null;
+}