@khorsheed/dsh-reader 0.2.0

package/lib/types/remote.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The reader Remote: the browser-facing wire face, and nothing else.
+ *
+ * Every method is a one-line delegation to {@link ReaderService}; the value it
+ * returns is the BARE domain value. The wire layer wraps that in the protocol's
+ * own result envelope, so a domain refusal is a value inside that envelope —
+ * never a second `{ ok }` object nested inside the first (which is how the
+ * discarded scaffold managed to answer `{ ok: true }` twice and throw it away).
+ *
+ * @module @khorsheed/dsh-reader/remote
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { ReaderAddFailure, ReaderAddOutcome, ReaderAddRefusal, ReaderAnnotationOutcome, ReaderBackfillCandidate, ReaderEntryBodyView, ReaderEntryFetchState, ReaderBody, ReaderCapabilities, ReaderEntryTranslationView, ReaderMutationOutcome, ReaderRecentEntry, ReaderRefreshResult, ReaderSentenceLearn, ReaderSourceSummary, ReaderStorageStats, ReaderTag } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        readerRemote: ReaderRemoteService;
+    }
+}
+/** Reserved for future config-driven knobs; the service owns today's config. */
+export interface ReaderRemoteConfig {
+}
+/** The wire namespace is `reader`: the browser calls `remote.reader.*`. */
+export declare class ReaderRemoteService extends TypertRemoteService<ReaderRemoteConfig> {
+    static inject: string[];
+    constructor(ctx: Context, _config?: ReaderRemoteConfig);
+    /** The service core this face delegates to. */
+    private get core();
+    /** Capability handshake: what the browser may rely on in this composition. */
+    capabilities(): Promise<ReaderCapabilities>;
+    /** The configured sources, without payloads. */
+    listSources(): Promise<{
+        sources: ReaderSourceSummary[];
+    }>;
+    /** Add a source; the host decides whether the URL is a feed or an article. */
+    addSource(request: {
+        url: string;
+        label?: string;
+    }): Promise<ReaderAddOutcome | ReaderAddRefusal | ReaderAddFailure>;
+    /** Change a source's label/enabled flag, or the global refresh time. */
+    updateSource(request: {
+        id: string;
+        enabled?: boolean;
+        label?: string;
+        url?: string;
+        timeOfDay?: string;
+    }): Promise<ReaderMutationOutcome>;
+    /** Drop a source; its entries' translations go with it (their bodies stay for the budget). */
+    removeSource(request: {
+        id: string;
+        entryIds?: readonly string[];
+    }): Promise<ReaderMutationOutcome>;
+    /** Fetch the named sources (or every enabled one) now. */
+    refresh(request: {
+        ids?: string[];
+    }): Promise<{
+        results: ReaderRefreshResult[];
+    }>;
+    /** Hand back raw payloads for the browser to parse. */
+    getBodies(request: {
+        ids: string[];
+    }): Promise<{
+        bodies: ReaderBody[];
+    }>;
+    /** What the detail view should render for one entry, and whether a fetch is worth offering. */
+    getEntryBody(request: {
+        entryId: string;
+        url: string;
+        feedHtml?: string;
+    }): Promise<ReaderEntryBodyView>;
+    /** Fetch one entry's article (the network half; the browser extracts). */
+    fetchEntryBody(request: {
+        entryId: string;
+        url: string;
+    }): Promise<{
+        entryId: string;
+        url?: string;
+        raw?: string;
+        rawFile?: string;
+        truncated?: boolean;
+        error?: string;
+    }>;
+    /** Cache the markup the browser extracted for one entry. */
+    storeEntryBody(request: {
+        entryId: string;
+        url: string;
+        html: string;
+        truncated?: boolean;
+        scriptFigures?: number;
+        bodyHash?: string;
+        /** The article's own title, as extracted — the saved link's card upgrade. */
+        title?: string;
+        /** A short excerpt (abstract / first paragraph), with the title. */
+        excerpt?: string;
+    }): Promise<ReaderEntryBodyView>;
+    /** What the plugin holds per entry: a body, a stored raw payload, or a failure. */
+    entryFetchStates(request: {
+        entryIds: readonly string[];
+    }): Promise<{
+        states: Record<string, ReaderEntryFetchState>;
+    }>;
+    /** A stored raw payload, so the browser can extract it later. */
+    getRawBody(request: {
+        entryId: string;
+    }): Promise<{
+        entryId: string;
+        raw?: string;
+        url?: string;
+        truncated?: boolean;
+        error?: string;
+    }>;
+    /** Which entries still need their full text (the automatic backfill's work list). */
+    listBackfillCandidates(request: {
+        entries: readonly {
+            entryId: string;
+            url: string;
+            label: string;
+            hasBody: boolean;
+        }[];
+        limit?: number;
+    }): Promise<{
+        candidates: ReaderBackfillCandidate[];
+    }>;
+    /** One entry's exact-fit translation record (segment map resolved), when usable. */
+    getEntryTranslation(request: {
+        entryId: string;
+    }): Promise<{
+        translation?: ReaderEntryTranslationView;
+    }>;
+    /** Translations for exactly the asked sentence hashes of one pair — never the whole table. */
+    getSentenceTranslations(request: {
+        pair: string;
+        hashes: readonly string[];
+    }): Promise<{
+        translations: Record<string, string>;
+    }>;
+    /** Persist what one translation run learned (and refresh what it reused), in one batch. */
+    rememberSentences(request: {
+        pair: string;
+        entries: readonly ReaderSentenceLearn[];
+        recalled?: readonly ReaderSentenceLearn[];
+        entryId?: string;
+        bodyHash?: string;
+    }): Promise<{
+        stored: number;
+    }>;
+    /** Per-tier cache usage, aggregated on the host (the tables never cross). */
+    getStorageStats(): Promise<ReaderStorageStats>;
+    /** Forget every translation: the global memory and every entry map. */
+    clearTranslations(): Promise<{
+        clearedEntries: number;
+        clearedMemory: boolean;
+    }>;
+    /** The tag vocabulary, with how many entries carry each tag. */
+    listTags(): Promise<{
+        tags: ReaderTag[];
+        counts: Record<string, number>;
+    }>;
+    /** Create a tag, or return the existing one with the same name. */
+    createTag(request: {
+        name: string;
+    }): Promise<ReaderTag | ReaderAnnotationOutcome>;
+    /** Rename a tag without touching the entries that carry it. */
+    renameTag(request: {
+        id: string;
+        name: string;
+    }): Promise<ReaderAnnotationOutcome>;
+    /** Delete a tag and remove it from every entry. */
+    deleteTag(request: {
+        id: string;
+    }): Promise<ReaderAnnotationOutcome>;
+    /** Add or remove one tag on one entry. */
+    tagEntry(request: {
+        entryId: string;
+        tagId: string;
+        on: boolean;
+    }): Promise<ReaderAnnotationOutcome>;
+    /** The tags on one entry. */
+    entryTags(request: {
+        entryId: string;
+    }): Promise<{
+        tags: ReaderTag[];
+    }>;
+    /** Read or set how long a fetched body is served (and the translation budget). */
+    getCachePolicy(): Promise<{
+        ttlHours: number;
+        maxEntries: number;
+        translationBudgetChars: number;
+    }>;
+    setCachePolicy(request: {
+        ttlHours: number;
+        maxEntries?: number;
+        translationBudgetChars?: number;
+    }): Promise<ReaderAnnotationOutcome>;
+    /** Drop tags nothing references any more. */
+    pruneTags(): Promise<{
+        removed: number;
+    }>;
+    /** Record that the reader opened one entry (the recent page's write half). */
+    recordRead(request: {
+        entryId: string;
+        sourceId: string;
+        title: string;
+        url?: string;
+    }): Promise<{
+        entries: number;
+    }>;
+    /** The entries the reader opened, newest first. */
+    listRecent(): Promise<{
+        entries: ReaderRecentEntry[];
+    }>;
+    /** Forget every recent entry. */
+    clearRecent(): Promise<{
+        removed: number;
+    }>;
+    /** Forward a ref block to the side-chat service when one is composed. */
+    quoteToSideChat(request: {
+        contextKey: string;
+        label: string;
+        text: string;
+    }): Promise<'ok' | 'unavailable'>;
+}
+export default ReaderRemoteService;
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/remote.js

@@ -0,0 +1,275 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+/** The wire namespace is `reader`: the browser calls `remote.reader.*`. */
+let ReaderRemoteService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _capabilities_decorators;
+    let _listSources_decorators;
+    let _addSource_decorators;
+    let _updateSource_decorators;
+    let _removeSource_decorators;
+    let _refresh_decorators;
+    let _getBodies_decorators;
+    let _getEntryBody_decorators;
+    let _fetchEntryBody_decorators;
+    let _storeEntryBody_decorators;
+    let _entryFetchStates_decorators;
+    let _getRawBody_decorators;
+    let _listBackfillCandidates_decorators;
+    let _getEntryTranslation_decorators;
+    let _getSentenceTranslations_decorators;
+    let _rememberSentences_decorators;
+    let _getStorageStats_decorators;
+    let _clearTranslations_decorators;
+    let _listTags_decorators;
+    let _createTag_decorators;
+    let _renameTag_decorators;
+    let _deleteTag_decorators;
+    let _tagEntry_decorators;
+    let _entryTags_decorators;
+    let _getCachePolicy_decorators;
+    let _setCachePolicy_decorators;
+    let _pruneTags_decorators;
+    let _recordRead_decorators;
+    let _listRecent_decorators;
+    let _clearRecent_decorators;
+    let _quoteToSideChat_decorators;
+    return class ReaderRemoteService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _capabilities_decorators = [Remote('capabilities')];
+            _listSources_decorators = [Remote('listSources')];
+            _addSource_decorators = [Remote('addSource')];
+            _updateSource_decorators = [Remote('updateSource')];
+            _removeSource_decorators = [Remote('removeSource')];
+            _refresh_decorators = [Remote('refresh')];
+            _getBodies_decorators = [Remote('getBodies')];
+            _getEntryBody_decorators = [Remote('getEntryBody')];
+            _fetchEntryBody_decorators = [Remote('fetchEntryBody')];
+            _storeEntryBody_decorators = [Remote('storeEntryBody')];
+            _entryFetchStates_decorators = [Remote('entryFetchStates')];
+            _getRawBody_decorators = [Remote('getRawBody')];
+            _listBackfillCandidates_decorators = [Remote('listBackfillCandidates')];
+            _getEntryTranslation_decorators = [Remote('getEntryTranslation')];
+            _getSentenceTranslations_decorators = [Remote('getSentenceTranslations')];
+            _rememberSentences_decorators = [Remote('rememberSentences')];
+            _getStorageStats_decorators = [Remote('getStorageStats')];
+            _clearTranslations_decorators = [Remote('clearTranslations')];
+            _listTags_decorators = [Remote('listTags')];
+            _createTag_decorators = [Remote('createTag')];
+            _renameTag_decorators = [Remote('renameTag')];
+            _deleteTag_decorators = [Remote('deleteTag')];
+            _tagEntry_decorators = [Remote('tagEntry')];
+            _entryTags_decorators = [Remote('entryTags')];
+            _getCachePolicy_decorators = [Remote('getCachePolicy')];
+            _setCachePolicy_decorators = [Remote('setCachePolicy')];
+            _pruneTags_decorators = [Remote('pruneTags')];
+            _recordRead_decorators = [Remote('recordRead')];
+            _listRecent_decorators = [Remote('listRecent')];
+            _clearRecent_decorators = [Remote('clearRecent')];
+            _quoteToSideChat_decorators = [Remote('quoteToSideChat')];
+            __esDecorate(this, null, _capabilities_decorators, { kind: "method", name: "capabilities", static: false, private: false, access: { has: obj => "capabilities" in obj, get: obj => obj.capabilities }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listSources_decorators, { kind: "method", name: "listSources", static: false, private: false, access: { has: obj => "listSources" in obj, get: obj => obj.listSources }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _addSource_decorators, { kind: "method", name: "addSource", static: false, private: false, access: { has: obj => "addSource" in obj, get: obj => obj.addSource }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _updateSource_decorators, { kind: "method", name: "updateSource", static: false, private: false, access: { has: obj => "updateSource" in obj, get: obj => obj.updateSource }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _removeSource_decorators, { kind: "method", name: "removeSource", static: false, private: false, access: { has: obj => "removeSource" in obj, get: obj => obj.removeSource }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _refresh_decorators, { kind: "method", name: "refresh", static: false, private: false, access: { has: obj => "refresh" in obj, get: obj => obj.refresh }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getBodies_decorators, { kind: "method", name: "getBodies", static: false, private: false, access: { has: obj => "getBodies" in obj, get: obj => obj.getBodies }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getEntryBody_decorators, { kind: "method", name: "getEntryBody", static: false, private: false, access: { has: obj => "getEntryBody" in obj, get: obj => obj.getEntryBody }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _fetchEntryBody_decorators, { kind: "method", name: "fetchEntryBody", static: false, private: false, access: { has: obj => "fetchEntryBody" in obj, get: obj => obj.fetchEntryBody }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _storeEntryBody_decorators, { kind: "method", name: "storeEntryBody", static: false, private: false, access: { has: obj => "storeEntryBody" in obj, get: obj => obj.storeEntryBody }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _entryFetchStates_decorators, { kind: "method", name: "entryFetchStates", static: false, private: false, access: { has: obj => "entryFetchStates" in obj, get: obj => obj.entryFetchStates }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getRawBody_decorators, { kind: "method", name: "getRawBody", static: false, private: false, access: { has: obj => "getRawBody" in obj, get: obj => obj.getRawBody }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listBackfillCandidates_decorators, { kind: "method", name: "listBackfillCandidates", static: false, private: false, access: { has: obj => "listBackfillCandidates" in obj, get: obj => obj.listBackfillCandidates }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getEntryTranslation_decorators, { kind: "method", name: "getEntryTranslation", static: false, private: false, access: { has: obj => "getEntryTranslation" in obj, get: obj => obj.getEntryTranslation }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getSentenceTranslations_decorators, { kind: "method", name: "getSentenceTranslations", static: false, private: false, access: { has: obj => "getSentenceTranslations" in obj, get: obj => obj.getSentenceTranslations }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _rememberSentences_decorators, { kind: "method", name: "rememberSentences", static: false, private: false, access: { has: obj => "rememberSentences" in obj, get: obj => obj.rememberSentences }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getStorageStats_decorators, { kind: "method", name: "getStorageStats", static: false, private: false, access: { has: obj => "getStorageStats" in obj, get: obj => obj.getStorageStats }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _clearTranslations_decorators, { kind: "method", name: "clearTranslations", static: false, private: false, access: { has: obj => "clearTranslations" in obj, get: obj => obj.clearTranslations }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listTags_decorators, { kind: "method", name: "listTags", static: false, private: false, access: { has: obj => "listTags" in obj, get: obj => obj.listTags }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _createTag_decorators, { kind: "method", name: "createTag", static: false, private: false, access: { has: obj => "createTag" in obj, get: obj => obj.createTag }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _renameTag_decorators, { kind: "method", name: "renameTag", static: false, private: false, access: { has: obj => "renameTag" in obj, get: obj => obj.renameTag }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteTag_decorators, { kind: "method", name: "deleteTag", static: false, private: false, access: { has: obj => "deleteTag" in obj, get: obj => obj.deleteTag }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _tagEntry_decorators, { kind: "method", name: "tagEntry", static: false, private: false, access: { has: obj => "tagEntry" in obj, get: obj => obj.tagEntry }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _entryTags_decorators, { kind: "method", name: "entryTags", static: false, private: false, access: { has: obj => "entryTags" in obj, get: obj => obj.entryTags }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getCachePolicy_decorators, { kind: "method", name: "getCachePolicy", static: false, private: false, access: { has: obj => "getCachePolicy" in obj, get: obj => obj.getCachePolicy }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setCachePolicy_decorators, { kind: "method", name: "setCachePolicy", static: false, private: false, access: { has: obj => "setCachePolicy" in obj, get: obj => obj.setCachePolicy }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _pruneTags_decorators, { kind: "method", name: "pruneTags", static: false, private: false, access: { has: obj => "pruneTags" in obj, get: obj => obj.pruneTags }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _recordRead_decorators, { kind: "method", name: "recordRead", static: false, private: false, access: { has: obj => "recordRead" in obj, get: obj => obj.recordRead }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listRecent_decorators, { kind: "method", name: "listRecent", static: false, private: false, access: { has: obj => "listRecent" in obj, get: obj => obj.listRecent }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _clearRecent_decorators, { kind: "method", name: "clearRecent", static: false, private: false, access: { has: obj => "clearRecent" in obj, get: obj => obj.clearRecent }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _quoteToSideChat_decorators, { kind: "method", name: "quoteToSideChat", static: false, private: false, access: { has: obj => "quoteToSideChat" in obj, get: obj => obj.quoteToSideChat }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['reader'];
+        constructor(ctx, _config = {}) {
+            super(ctx, 'readerRemote', { namespace: 'reader' });
+            __runInitializers(this, _instanceExtraInitializers);
+        }
+        /** The service core this face delegates to. */
+        get core() {
+            return this.ctx.reader;
+        }
+        /** Capability handshake: what the browser may rely on in this composition. */
+        capabilities() {
+            return this.core.capabilities();
+        }
+        /** The configured sources, without payloads. */
+        async listSources() {
+            return this.core.listSources();
+        }
+        /** Add a source; the host decides whether the URL is a feed or an article. */
+        addSource(request) {
+            return this.core.addSource(request);
+        }
+        /** Change a source's label/enabled flag, or the global refresh time. */
+        updateSource(request) {
+            return this.core.updateSource(request);
+        }
+        /** Drop a source; its entries' translations go with it (their bodies stay for the budget). */
+        removeSource(request) {
+            return this.core.removeSource(request);
+        }
+        /** Fetch the named sources (or every enabled one) now. */
+        async refresh(request) {
+            return this.core.refresh(request);
+        }
+        /** Hand back raw payloads for the browser to parse. */
+        async getBodies(request) {
+            return this.core.getBodies(request);
+        }
+        /* ------------------------------------------- entry bodies and reader tags */
+        /** What the detail view should render for one entry, and whether a fetch is worth offering. */
+        getEntryBody(request) {
+            return this.core.getEntryBody(request);
+        }
+        /** Fetch one entry's article (the network half; the browser extracts). */
+        fetchEntryBody(request) {
+            return this.core.fetchEntryBody(request);
+        }
+        /** Cache the markup the browser extracted for one entry. */
+        storeEntryBody(request) {
+            return this.core.storeEntryBody(request);
+        }
+        /** What the plugin holds per entry: a body, a stored raw payload, or a failure. */
+        entryFetchStates(request) {
+            return this.core.entryFetchStates(request);
+        }
+        /** A stored raw payload, so the browser can extract it later. */
+        getRawBody(request) {
+            return this.core.getRawBody(request);
+        }
+        /** Which entries still need their full text (the automatic backfill's work list). */
+        listBackfillCandidates(request) {
+            return this.core.listBackfillCandidates(request);
+        }
+        /* -------------------------------------------------- translation memory */
+        /** One entry's exact-fit translation record (segment map resolved), when usable. */
+        getEntryTranslation(request) {
+            return this.core.getEntryTranslation(request);
+        }
+        /** Translations for exactly the asked sentence hashes of one pair — never the whole table. */
+        getSentenceTranslations(request) {
+            return this.core.getSentenceTranslations(request);
+        }
+        /** Persist what one translation run learned (and refresh what it reused), in one batch. */
+        rememberSentences(request) {
+            return this.core.rememberSentences(request);
+        }
+        /** Per-tier cache usage, aggregated on the host (the tables never cross). */
+        getStorageStats() {
+            return this.core.getStorageStats();
+        }
+        /** Forget every translation: the global memory and every entry map. */
+        clearTranslations() {
+            return this.core.clearTranslations();
+        }
+        /** The tag vocabulary, with how many entries carry each tag. */
+        listTags() {
+            return this.core.listTags();
+        }
+        /** Create a tag, or return the existing one with the same name. */
+        createTag(request) {
+            return this.core.createTag(request);
+        }
+        /** Rename a tag without touching the entries that carry it. */
+        renameTag(request) {
+            return this.core.renameTag(request);
+        }
+        /** Delete a tag and remove it from every entry. */
+        deleteTag(request) {
+            return this.core.deleteTag(request);
+        }
+        /** Add or remove one tag on one entry. */
+        tagEntry(request) {
+            return this.core.tagEntry(request);
+        }
+        /** The tags on one entry. */
+        entryTags(request) {
+            return this.core.entryTags(request);
+        }
+        /** Read or set how long a fetched body is served (and the translation budget). */
+        getCachePolicy() {
+            return this.core.getCachePolicy();
+        }
+        setCachePolicy(request) {
+            return this.core.setCachePolicy(request);
+        }
+        /** Drop tags nothing references any more. */
+        pruneTags() {
+            return this.core.pruneTags();
+        }
+        /** Record that the reader opened one entry (the recent page's write half). */
+        recordRead(request) {
+            return this.core.recordRead(request);
+        }
+        /** The entries the reader opened, newest first. */
+        listRecent() {
+            return this.core.listRecent();
+        }
+        /** Forget every recent entry. */
+        clearRecent() {
+            return this.core.clearRecent();
+        }
+        /** Forward a ref block to the side-chat service when one is composed. */
+        quoteToSideChat(request) {
+            return this.core.quoteToSideChat(request);
+        }
+    };
+})();
+export { ReaderRemoteService };
+export default ReaderRemoteService;

package/lib/types/schedule.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The daily-refresh clock: pure date math, deliberately separated from the
+ * service that arms it.
+ *
+ * There is no host scheduler to hang a "refresh every morning" job on — the
+ * host's `ctx.timer` is fiber-scoped `timeout`/`interval`/`throttle`/`debounce`
+ * only, and `dsh-schedule` is agent-session reminders rather than a service a
+ * plugin may schedule against. So the plugin owns a `setTimeout` and the only
+ * interesting part is deciding *when* — which is what lives here, as functions
+ * that take a `now` and are therefore testable without a clock.
+ *
+ * @module @khorsheed/dsh-reader/schedule
+ */
+/** Local time of day as `HH:MM`. */
+export type TimeOfDay = string;
+/** Milliseconds in one day. */
+declare const DAY_MS: number;
+/**
+ * Parse an `HH:MM` string into hours and minutes.
+ *
+ * A malformed value falls back to the caller's default rather than throwing: a
+ * hand-edited state file must not be able to break the refresh loop.
+ *
+ * @param value - the configured time of day.
+ * @param fallback - the value to use when `value` is unusable.
+ * @returns the parsed hour and minute.
+ */
+export declare function parseTimeOfDay(value: string | undefined, fallback: TimeOfDay): {
+    hour: number;
+    minute: number;
+};
+/**
+ * The next wall-clock occurrence of `timeOfDay` strictly after `now`.
+ *
+ * Computed through the local-time constructor rather than by adding a fixed
+ * day length, so a DST shift moves the refresh to the same wall-clock time
+ * instead of drifting an hour.
+ *
+ * @param now - the reference instant.
+ * @param timeOfDay - the configured local time.
+ * @returns the next occurrence.
+ */
+export declare function nextOccurrence(now: Date, timeOfDay: TimeOfDay): Date;
+/**
+ * The most recent occurrence of `timeOfDay` at or before `now` — the deadline
+ * a catch-up refresh compares against.
+ *
+ * @param now - the reference instant.
+ * @param timeOfDay - the configured local time.
+ * @returns the most recent occurrence.
+ */
+export declare function previousOccurrence(now: Date, timeOfDay: TimeOfDay): Date;
+/** Delay to the next occurrence, clamped to Node's timer ceiling. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+/**
+ * Whether a boot should refresh immediately because the last run missed its
+ * slot — the thing that makes "daily refresh" true on a machine that was
+ * asleep or whose process restarted.
+ *
+ * @param lastRun - the last completed refresh, if any.
+ * @param now - the current instant.
+ * @param timeOfDay - the configured local time.
+ * @param enabled - whether the schedule is on at all.
+ * @returns true when a catch-up run is due.
+ */
+export declare function isCatchUpDue(lastRun: Date | undefined, now: Date, timeOfDay: TimeOfDay, enabled: boolean): boolean;
+/**
+ * The timer delay for the next occurrence, capped so a scheduler survives
+ * dates beyond the 32-bit millisecond limit.
+ *
+ * @param now - the reference instant.
+ * @param timeOfDay - the configured local time.
+ * @returns the delay in milliseconds.
+ */
+export declare function delayUntilNext(now: Date, timeOfDay: TimeOfDay): number;
+/** Exposed for tests that want to assert a day's worth of arithmetic. */
+export { DAY_MS };
+//# sourceMappingURL=schedule.d.ts.map