@khorsheed/dsh-library 0.0.0-stage → 0.1.0

package/lib/types/service/bindings.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Session bindings, the per-turn binding summary, events, activity and stats — the top layer, exported as LibraryService.
+ *
+ * One layer of the library service (see `service/core.ts` for the layering):
+ * the methods are the service's own, moved here verbatim by domain.
+ *
+ * @module @khorsheed/dsh-library/service/bindings
+ */
+import { type LibraryBinding, type LibraryCard, type LibraryEvent, type LibraryEventType, type LibraryOutcome, type LibraryProject, type LibraryResource, type LibraryResourceProgress } from '../types.ts';
+import type { LibraryStationMastery } from '../mastery.ts';
+import { LibraryServiceAssess } from './assess.ts';
+export declare class LibraryService extends LibraryServiceAssess {
+    /** The project / resource a session works on, when it is bound. */
+    getBinding(sessionId: string): LibraryBinding | undefined;
+    /** Bind a session (null unbinds). The project and resource must exist. */
+    setBinding(sessionId: string, binding: LibraryBinding | null): Promise<LibraryOutcome<{
+        binding: LibraryBinding | null;
+    }>>;
+    /**
+     * The bound session's working set, read synchronously (the per-turn prompt
+     * context renders inside a synchronous callback): the project, the bound
+     * resource, every textbook's path state in study order (so the coach reads
+     * what the learner adopted, discarded or reordered in the sidebar, every
+     * turn), and the weakest live cards.
+     */
+    bindingSummary(sessionId: string, cardLimit?: number): {
+        binding?: LibraryBinding;
+        project?: LibraryProject;
+        resource?: LibraryResource;
+        textbooks: LibraryResourceProgress[];
+        /** The bound textbook's current station and its points' mastery (where the coach is teaching now). */
+        station?: {
+            id: string;
+            title: string;
+            mastery: LibraryStationMastery;
+        };
+        weakCards: LibraryCard[];
+    };
+    /** One project's audit trail, newest first, optionally some types only. */
+    listEvents(request: {
+        projectId: string;
+        limit?: number;
+        types?: readonly LibraryEventType[];
+    }): Promise<{
+        events: LibraryEvent[];
+    }>;
+    /** 「教练最近记下」: card recordings from chats and quizzes, across projects, newest first. */
+    /** A project's name, when it exists (synchronous — the per-turn context reads it). */
+    projectName(projectId: string): string | undefined;
+    /** The newest knowledge-point state changes across projects (今日 「最近的变化」). */
+    recentChanges(request: {
+        limit?: number;
+    }): Promise<{
+        changes: (LibraryEvent & {
+            projectId: string;
+            projectName: string;
+        })[];
+    }>;
+    recentRecords(request: {
+        limit?: number;
+    }): Promise<{
+        records: (LibraryEvent & {
+            projectId: string;
+            projectName: string;
+        })[];
+    }>;
+    /**
+     * The newest event's timestamp across the library — the pane's change poll.
+     * The Remote face is request/response (no push), so the sidebar learns
+     * host-side writes (a landed quiz, a recorded page) by polling this and
+     * re-reading when it moves. Writes that log no event (creating a project)
+     * move it too. `session` names the newest session-made write, so the client
+     * can reveal the library next to the conversation that just started using it.
+     */
+    latestActivity(): Promise<{
+        at?: string;
+        session?: {
+            id: string;
+            at: string;
+        };
+    }>;
+    /** The whole-library tally. */
+    stats(): Promise<{
+        projects: number;
+        books: number;
+        cards: number;
+        due: number;
+        quizzes: number;
+        attempts: number;
+    }>;
+}
+//# sourceMappingURL=bindings.d.ts.map

package/lib/types/service/bindings.js

@@ -0,0 +1,198 @@
+/**
+ * Session bindings, the per-turn binding summary, events, activity and stats — the top layer, exported as LibraryService.
+ *
+ * One layer of the library service (see `service/core.ts` for the layering):
+ * the methods are the service's own, moved here verbatim by domain.
+ *
+ * @module @khorsheed/dsh-library/service/bindings
+ */
+import { isThickResource, } from "../types.js";
+import { refuse, storeRefusal } from "./core.js";
+import { LibraryServiceAssess } from "./assess.js";
+export class LibraryService extends LibraryServiceAssess {
+    /* ------------------------------------------------------------- bindings */
+    /** The project / resource a session works on, when it is bound. */
+    getBinding(sessionId) {
+        this.assertAlive('getBinding');
+        return this.store.readBindings().get(sessionId);
+    }
+    /** Bind a session (null unbinds). The project and resource must exist. */
+    async setBinding(sessionId, binding) {
+        this.assertAlive('setBinding');
+        if (sessionId === '')
+            return refuse('invalid', 'no session to bind');
+        if (binding !== null) {
+            const project = this.readProjectOrRefusal(binding.projectId);
+            if ('error' in project)
+                return project;
+            if (binding.resourceId !== undefined && this.store.readResource(binding.projectId, binding.resourceId) === undefined) {
+                return refuse('not-found', `no resource ${JSON.stringify(binding.resourceId)} in project ${JSON.stringify(project.value.name)} — resource ids are minted (r_…), never chosen by the caller; library_read · resources lists them. Registering the resource (library_textbook) binds this session itself — no separate library_binding call needed`);
+            }
+        }
+        try {
+            await this.store.withBindingsLock(() => {
+                const bindings = new Map(this.store.readBindings());
+                // A switch to another project remembers where the session came from
+                // (the coach is told every turn that the earlier talk is not this
+                // project's material — a reused session once quizzed 数学 inside 神经科学).
+                const before = bindings.get(sessionId);
+                const previous = before === undefined ? undefined : before.projectId !== binding?.projectId ? before.projectId : before.previousProjectId;
+                if (binding === null)
+                    bindings.delete(sessionId);
+                else
+                    bindings.set(sessionId, { projectId: binding.projectId, ...(binding.resourceId === undefined ? {} : { resourceId: binding.resourceId }), ...(previous === undefined ? {} : { previousProjectId: previous }) });
+                this.store.writeBindings(bindings);
+            });
+            if (binding !== null)
+                this.changed(binding.projectId);
+            return { ok: true, binding };
+        }
+        catch (error) {
+            return storeRefusal(error);
+        }
+    }
+    /**
+     * The bound session's working set, read synchronously (the per-turn prompt
+     * context renders inside a synchronous callback): the project, the bound
+     * resource, every textbook's path state in study order (so the coach reads
+     * what the learner adopted, discarded or reordered in the sidebar, every
+     * turn), and the weakest live cards.
+     */
+    bindingSummary(sessionId, cardLimit = 12) {
+        this.assertAlive('bindingSummary');
+        const binding = this.getBinding(sessionId);
+        if (binding === undefined)
+            return { textbooks: [], weakCards: [] };
+        let project;
+        try {
+            project = this.store.readProject(binding.projectId);
+        }
+        catch {
+            project = undefined;
+        }
+        if (project === undefined)
+            return { binding, textbooks: [], weakCards: [] };
+        const resource = binding.resourceId === undefined ? undefined : this.store.readResource(project.id, binding.resourceId);
+        const textbooks = this.store.listResources(project.id).filter(isThickResource).map(textbook => this.resourceProgress(project.id, textbook));
+        const weakCards = this.store.readCards(project.id)
+            .filter(card => card.status === 'active' && card.weakness > 0 && (resource === undefined || card.resourceId === resource.id))
+            .sort((a, b) => b.weakness - a.weakness || b.updatedAt.localeCompare(a.updatedAt))
+            .slice(0, cardLimit);
+        const current = resource === undefined ? undefined : this.store.readRoadmap(project.id, resource.id)?.nodes.find(node => node.state === 'current' && node.gate === 'quiz');
+        const mastery = current === undefined ? undefined : this.stationMasteryOf(project.id, current.id, resource?.id);
+        return {
+            binding,
+            project,
+            ...(resource === undefined ? {} : { resource }),
+            textbooks,
+            ...(current === undefined || mastery === undefined ? {} : { station: { id: current.id, title: current.title, mastery } }),
+            weakCards,
+        };
+    }
+    /* --------------------------------------------------------------- events */
+    /** One project's audit trail, newest first, optionally some types only. */
+    async listEvents(request) {
+        this.assertAlive('listEvents');
+        const types = request.types === undefined ? undefined : new Set(request.types);
+        const events = this.store.readEvents(request.projectId).filter(event => types === undefined || types.has(event.type));
+        return { events: events.reverse().slice(0, request.limit ?? 20) };
+    }
+    /** 「教练最近记下」: card recordings from chats and quizzes, across projects, newest first. */
+    /** A project's name, when it exists (synchronous — the per-turn context reads it). */
+    projectName(projectId) {
+        try {
+            return this.store.readProject(projectId)?.name;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** The newest knowledge-point state changes across projects (今日 「最近的变化」). */
+    async recentChanges(request) {
+        this.assertAlive('recentChanges');
+        const changes = [];
+        for (const project of this.store.readIndex().projects) {
+            for (const event of this.store.readEvents(project.id)) {
+                if (event.type !== 'point.changed' || event.nodeId === undefined || event.resourceId === undefined || event.id === undefined)
+                    continue;
+                // A change about a textbook, station or point that is gone (removed, re-planned away) is not shown.
+                const node = this.store.readRoadmap(project.id, event.resourceId)?.nodes.find(candidate => candidate.id === event.nodeId);
+                if (node?.points?.some(point => point.id === event.id) !== true)
+                    continue;
+                changes.push({ ...event, projectId: project.id, projectName: project.name });
+            }
+        }
+        changes.sort((a, b) => b.at.localeCompare(a.at));
+        return { changes: changes.slice(0, request.limit ?? 10) };
+    }
+    async recentRecords(request) {
+        this.assertAlive('recentRecords');
+        const records = [];
+        for (const project of this.store.readIndex().projects) {
+            // A recording whose cards were all deleted since is not shown; one with
+            // some left names only the live ones.
+            const liveTerms = new Map(this.store.readCards(project.id).filter(card => card.status !== 'deleted').map(card => [card.id, card.term]));
+            for (const event of this.store.readEvents(project.id)) {
+                if (event.type !== 'cards.recorded' || (event.source !== 'chat' && event.source !== 'quiz'))
+                    continue;
+                const ids = (event.ids ?? []).filter(cardId => liveTerms.has(cardId));
+                if (event.ids !== undefined && ids.length === 0)
+                    continue;
+                records.push({
+                    ...event,
+                    ...(event.ids === undefined ? {} : { ids, title: ids.map(cardId => liveTerms.get(cardId)).join('、').slice(0, 300) }),
+                    projectId: project.id,
+                    projectName: project.name,
+                });
+            }
+        }
+        records.sort((a, b) => b.at.localeCompare(a.at));
+        return { records: records.slice(0, request.limit ?? 10) };
+    }
+    /**
+     * The newest event's timestamp across the library — the pane's change poll.
+     * The Remote face is request/response (no push), so the sidebar learns
+     * host-side writes (a landed quiz, a recorded page) by polling this and
+     * re-reading when it moves. Writes that log no event (creating a project)
+     * move it too. `session` names the newest session-made write, so the client
+     * can reveal the library next to the conversation that just started using it.
+     */
+    async latestActivity() {
+        this.assertAlive('latestActivity');
+        let latest = this.lastChangeAt;
+        for (const project of this.store.readIndex().projects) {
+            const at = this.store.readEvents(project.id).at(-1)?.at;
+            if (at !== undefined && (latest === undefined || at > latest))
+                latest = at;
+        }
+        return {
+            ...(latest === undefined ? {} : { at: latest }),
+            ...(this.lastSessionWrite === undefined ? {} : { session: { id: this.lastSessionWrite.session, at: this.lastSessionWrite.at } }),
+        };
+    }
+    /* --------------------------------------------------------------- stats */
+    /** The whole-library tally. */
+    async stats() {
+        this.assertAlive('stats');
+        const now = new Date().toISOString();
+        let books = 0;
+        let cards = 0;
+        let due = 0;
+        let quizzes = 0;
+        let attempts = 0;
+        const index = this.store.readIndex();
+        for (const project of index.projects) {
+            books += this.store.listResources(project.id).filter(isThickResource).length;
+            quizzes += this.store.listAssessments(project.id).filter(assessment => assessment.type === 'quiz').length;
+            attempts += this.store.readAttempts(project.id).length;
+            for (const card of this.store.readCards(project.id)) {
+                if (card.status !== 'active')
+                    continue;
+                cards += 1;
+                if (card.mastery.dueAt <= now)
+                    due += 1;
+            }
+        }
+        return { projects: index.projects.length, books, cards, due, quizzes, attempts };
+    }
+}

package/lib/types/service/cards.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Knowledge cards: the dedupe write path, listing, editing, undo, review scheduling.
+ *
+ * One layer of the library service (see `service/core.ts` for the layering):
+ * the methods are the service's own, moved here verbatim by domain.
+ *
+ * @module @khorsheed/dsh-library/service/cards
+ */
+import { type LibraryCardQuery, type LibraryCard, type LibraryCardInput, type LibraryCardWriteResult, type LibraryOutcome, type LibraryReviewRating } from '../types.ts';
+import { LibraryServiceShelf } from './shelf.ts';
+export declare class LibraryServiceCards extends LibraryServiceShelf {
+    /**
+     * Apply card inputs to the project's cards (call inside the project lock).
+     * Exact keys merge; near matches are held back unless `mergeNear` (photo
+     * words — a plural or a case away is the same word) or the input decides.
+     */
+    protected applyCardInputs(projectId: string, inputs: readonly LibraryCardInput[], defaultResourceId: string | undefined, options?: {
+        mergeNear?: boolean;
+    }): LibraryCardWriteResult & {
+        at: string;
+    };
+    /**
+     * Record cards (the coach's 「记下」, a manual add). Near-duplicates come back
+     * in `pending` with their candidates — resend each with `mergeInto` or `asNew`.
+     */
+    writeCards(request: {
+        projectId: string;
+        resourceId?: string;
+        cards: readonly LibraryCardInput[];
+    }): Promise<LibraryOutcome<LibraryCardWriteResult>>;
+    /** Cards, filtered and sorted (the sidebar list, the coach's search). */
+    listCards(request: LibraryCardQuery): Promise<{
+        cards: LibraryCard[];
+        total: number;
+    }>;
+    /** The cards due for review across projects (or one), weakest first. */
+    dueCards(request: {
+        projectId?: string;
+        limit?: number;
+    }): Promise<{
+        cards: (LibraryCard & {
+            projectId: string;
+        })[];
+    }>;
+    /** Edit a card by hand: its words, or its status (mastered / deleted / active). */
+    editCard(request: {
+        projectId: string;
+        cardId: string;
+        patch: {
+            term?: string;
+            gloss?: string;
+            userGloss?: string;
+            aliases?: readonly string[];
+            status?: LibraryCard['status'];
+            resourceId?: string | null;
+        };
+    }): Promise<LibraryOutcome<{
+        card: LibraryCard;
+    }>>;
+    /**
+     * Undo one recording (the toast's 撤销): cards it created are deleted; cards
+     * it merged into lose the source it stacked (and the weakness it added).
+     */
+    undoCards(request: {
+        projectId: string;
+        ids: readonly string[];
+        at: string;
+    }): Promise<LibraryOutcome<{
+        removed: number;
+        reverted: number;
+    }>>;
+    /**
+     * One flashcard review (the daily 复习): only the schedule moves — forgot
+     * resets to box 0 (tomorrow), fuzzy keeps the box, recalled climbs one.
+     * Reviews never unlock nodes and never touch weakness.
+     */
+    reviewCard(request: {
+        projectId: string;
+        cardId: string;
+        rating: LibraryReviewRating;
+    }): Promise<LibraryOutcome<{
+        card: LibraryCard;
+    }>>;
+}
+//# sourceMappingURL=cards.d.ts.map