@khorsheed/dsh-library 0.0.0-stage → 0.1.0

package/lib/types/mastery.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Knowledge-point mastery — the one rule set the service, the per-turn coach
+ * context and the sidebar all read (proposal 2026-10-19-library-point-mastery).
+ * Pure: no store, no context; give it a station's node, the project's
+ * assessments and attempts.
+ *
+ * - A question is OPEN (待订正) when its newest non-void verdict — on its own
+ *   paper, a re-sitting of that paper, or a retake re-asking it — failed.
+ * - A point is WEAK when a question is open, or a coach note is newer than
+ *   its newest pass; UNTESTED with neither probes nor notes. Otherwise (none
+ *   open, newest probe passed) it is MASTERED once enough evidence stands —
+ *   at least MASTERY_MIN_RIGHT distinct questions right now, across at least
+ *   MASTERY_MIN_SITTINGS sittings with a right answer — and PRACTICING (巩固中)
+ *   until then: one lucky paper never masters a point.
+ * - Retakes (type "retake") re-ask open questions — one station's, or a
+ *   whole project's (今日复习); each question resolves through its `origin`,
+ *   so a cross-station retake credits every station it touched. Their
+ *   verdicts move the points but never a station's pass record.
+ *
+ * @module @khorsheed/dsh-library/mastery
+ */
+import type { LibraryAssessment, LibraryAttempt, LibraryPointChange, LibraryPointNote, LibraryPointState, LibraryQuizQuestion, RoadmapNode } from './types.ts';
+/** Distinct questions that must stand right before a point counts as mastered. */
+export declare const MASTERY_MIN_RIGHT = 3;
+/** Separate sittings (papers or retakes) that must each have answered the point right. */
+export declare const MASTERY_MIN_SITTINGS = 2;
+/** One open question: where it came from, the question, when it was missed. */
+export interface LibraryOpenMiss {
+    /** `${assessmentId}:${questionId}` of the ORIGINAL question (retakes resolve to it). */
+    readonly key: string;
+    readonly assessmentId: string;
+    readonly questionId: string;
+    readonly question: LibraryQuizQuestion;
+    /** When the newest (failing) verdict landed. */
+    readonly at: string;
+}
+/** One point's mastery, with what decided it. */
+export interface LibraryPointMastery {
+    readonly id: string;
+    readonly title: string;
+    readonly state: LibraryPointState;
+    readonly open: readonly LibraryOpenMiss[];
+    readonly notes: readonly LibraryPointNote[];
+    /** The newest verdict on any question probing the point. */
+    readonly lastProbe?: {
+        readonly at: string;
+        readonly pass: boolean;
+    };
+    /** Distinct questions ever asked on the point, and how many of them stand right now (newest verdict passed). */
+    readonly asked: number;
+    readonly right: number;
+    /** Sittings in which at least one question on the point was answered right. */
+    readonly rightSittings: number;
+    /** Every sitting that touched the point, newest first: how many of its questions, how many right. */
+    readonly history: readonly LibraryPointSitting[];
+}
+/** One sitting's share of a point. */
+export interface LibraryPointSitting {
+    readonly at: string;
+    /** A retake (订正) rather than a paper. */
+    readonly retake: boolean;
+    readonly total: number;
+    readonly right: number;
+}
+/** A station's mastery: every point, and every open question (pointless ones too). */
+export interface LibraryStationMastery {
+    readonly points: readonly LibraryPointMastery[];
+    readonly open: readonly LibraryOpenMiss[];
+}
+/**
+ * The station's mastery from the ledger.
+ * @param node - the station (its points and their notes).
+ * @param assessments - the project's assessments (others are ignored).
+ * @param attempts - the project's attempts, any order.
+ */
+export declare function stationMastery(node: RoadmapNode, assessments: readonly LibraryAssessment[], attempts: readonly LibraryAttempt[]): LibraryStationMastery;
+/** The points whose state differs between two readings of the same station. */
+export declare function masteryChanges(nodeId: string, before: LibraryStationMastery, after: LibraryStationMastery): LibraryPointChange[];
+/** One line on why a point is where it is (event detail, context line). */
+export declare function masteryReason(point: LibraryPointMastery): string;
+//# sourceMappingURL=mastery.d.ts.map

package/lib/types/mastery.js

@@ -0,0 +1,110 @@
+/** Distinct questions that must stand right before a point counts as mastered. */
+export const MASTERY_MIN_RIGHT = 3;
+/** Separate sittings (papers or retakes) that must each have answered the point right. */
+export const MASTERY_MIN_SITTINGS = 2;
+/** Whether a verdict passes (partial credit counts at half or more). */
+function passes(verdict) {
+    return verdict.pass && (verdict.ratio ?? 1) >= 0.5;
+}
+/**
+ * The station's mastery from the ledger.
+ * @param node - the station (its points and their notes).
+ * @param assessments - the project's assessments (others are ignored).
+ * @param attempts - the project's attempts, any order.
+ */
+export function stationMastery(node, assessments, attempts) {
+    // The station's papers, plus every retake (a retake counts here only through questions whose origin is one of them).
+    const papers = new Map(assessments
+        .filter(assessment => assessment.scope.nodeId === node.id && assessment.type === 'quiz' && assessment.questions !== undefined)
+        .map(assessment => [assessment.id, assessment]));
+    const own = new Map([...papers, ...assessments
+            .filter(assessment => assessment.type === 'retake' && assessment.questions !== undefined)
+            .map(assessment => [assessment.id, assessment])]);
+    const probes = [];
+    for (const attempt of attempts) {
+        const assessment = attempt.assessmentId === undefined ? undefined : own.get(attempt.assessmentId);
+        if (assessment === undefined)
+            continue;
+        for (const verdict of attempt.verdicts) {
+            if (verdict.void === true)
+                continue;
+            const question = assessment.questions.find(candidate => candidate.id === verdict.task);
+            if (question === undefined)
+                continue;
+            if (assessment.type === 'retake' && (question.origin === undefined || !papers.has(question.origin.assessmentId)))
+                continue;
+            const originId = question.origin?.assessmentId ?? assessment.id;
+            const originQuestion = question.origin === undefined
+                ? question
+                : own.get(question.origin.assessmentId)?.questions?.find(candidate => candidate.id === question.origin.questionId) ?? question;
+            probes.push({ attemptId: attempt.id, retake: assessment.type === 'retake', key: `${originId}:${question.origin?.questionId ?? question.id}`, assessmentId: originId, question: originQuestion, pass: passes(verdict), at: attempt.at });
+        }
+    }
+    probes.sort((a, b) => a.at.localeCompare(b.at));
+    const newestByKey = new Map();
+    for (const probe of probes)
+        newestByKey.set(probe.key, probe);
+    const open = [...newestByKey.values()]
+        .filter(probe => !probe.pass)
+        .map(probe => ({ key: probe.key, assessmentId: probe.assessmentId, questionId: probe.question.id, question: probe.question, at: probe.at }))
+        .sort((a, b) => b.at.localeCompare(a.at));
+    const points = (node.points ?? []).map((point) => {
+        const mine = probes.filter(probe => probe.question.point === point.id);
+        const last = mine.at(-1);
+        const lastPass = [...mine].reverse().find(probe => probe.pass);
+        const pointOpen = open.filter(miss => miss.question.point === point.id);
+        const notes = point.notes ?? [];
+        const newestNote = notes.reduce((latest, note) => latest === undefined || note.at > latest ? note.at : latest, undefined);
+        const noteUnanswered = newestNote !== undefined && (lastPass === undefined || newestNote > lastPass.at);
+        const newest = new Map();
+        for (const probe of mine)
+            newest.set(probe.key, probe);
+        const right = [...newest.values()].filter(probe => probe.pass).length;
+        const rightSittings = new Set(mine.filter(probe => probe.pass).map(probe => probe.attemptId)).size;
+        const state = last === undefined && notes.length === 0
+            ? 'untested'
+            : pointOpen.length > 0 || last?.pass !== true || noteUnanswered
+                ? 'weak'
+                : right >= MASTERY_MIN_RIGHT && rightSittings >= MASTERY_MIN_SITTINGS ? 'mastered' : 'practicing';
+        const sittings = new Map();
+        for (const probe of mine) {
+            const sitting = sittings.get(probe.attemptId) ?? { at: probe.at, retake: probe.retake, total: 0, right: 0 };
+            sittings.set(probe.attemptId, { ...sitting, total: sitting.total + 1, right: sitting.right + (probe.pass ? 1 : 0) });
+        }
+        return {
+            id: point.id,
+            title: point.title,
+            state,
+            open: pointOpen,
+            notes,
+            ...(last === undefined ? {} : { lastProbe: { at: last.at, pass: last.pass } }),
+            asked: newest.size,
+            right,
+            rightSittings,
+            history: [...sittings.values()].sort((a, b) => b.at.localeCompare(a.at)),
+        };
+    });
+    return { points, open };
+}
+/** The points whose state differs between two readings of the same station. */
+export function masteryChanges(nodeId, before, after) {
+    const previous = new Map(before.points.map(point => [point.id, point.state]));
+    return after.points.flatMap(point => {
+        const from = previous.get(point.id) ?? 'untested';
+        return from === point.state ? [] : [{ nodeId, pointId: point.id, title: point.title, from, to: point.state }];
+    });
+}
+/** One line on why a point is where it is (event detail, context line). */
+export function masteryReason(point) {
+    const parts = [];
+    if (point.open.length > 0)
+        parts.push(`${point.open.length} open miss${point.open.length === 1 ? '' : 'es'}`);
+    const note = point.notes.at(-1);
+    if (note !== undefined)
+        parts.push(`note "${note.term ?? note.text}"`);
+    if (point.state === 'mastered' && point.lastProbe !== undefined)
+        parts.push(`${point.right} right across ${point.rightSittings} sittings`);
+    if (point.state === 'practicing')
+        parts.push(`${point.right} right across ${point.rightSittings} sitting${point.rightSittings === 1 ? '' : 's'}; mastered at ${MASTERY_MIN_RIGHT} across ${MASTERY_MIN_SITTINGS}`);
+    return parts.join('; ');
+}

package/lib/types/profiles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Subject profiles — what varies by a project's template, in one place, read
+ * by the service, the per-turn coach context and the sidebar alike. Plain
+ * data: the sidebar maps `fill` onto its judge (judge.ts), the service maps
+ * `markKind` onto the cards it creates.
+ *
+ * A new subject is a new profile; a subject that needs its own UI can ship as
+ * a companion package providing one (proposal 2026-10-19-library-point-mastery).
+ *
+ * @module @khorsheed/dsh-library/profiles
+ */
+import type { LibraryCardKind, LibraryTemplate } from './types.ts';
+/** What a template changes. */
+export interface LibraryProfile {
+    readonly template: LibraryTemplate;
+    /** What a photographed mark (and a single-word miss) becomes. */
+    readonly markKind: LibraryCardKind;
+    /** Whether knowledge points are the mastery unit (a coach note lands on a point; misses wait for 订正). */
+    readonly pointsDriven: boolean;
+    /** How a fill-in is judged: by text or value with math folding, or by spelling (UK/US, plurals). */
+    readonly fill: 'math' | 'spelling';
+    /** Whether answers preview and typeset math. */
+    readonly math: boolean;
+    /** One line for the coach's per-turn context. */
+    readonly coachHint: string;
+}
+/** Every template's profile; custom follows the subject profile. */
+export declare const LIBRARY_PROFILES: Readonly<Record<LibraryTemplate, LibraryProfile>>;
+/** A template's profile (an unknown template reads as subject). */
+export declare function profileOf(template: LibraryTemplate | undefined): LibraryProfile;
+//# sourceMappingURL=profiles.d.ts.map

package/lib/types/profiles.js

@@ -0,0 +1,25 @@
+const SUBJECT = {
+    template: 'subject',
+    markKind: 'concept',
+    pointsDriven: true,
+    fill: 'math',
+    math: true,
+    coachHint: 'Quiz the weak and untested points first, then the practicing ones; every question names its point; math in $…$; a fill key is a value (1/2), several blanks comma-separated.',
+};
+/** Every template's profile; custom follows the subject profile. */
+export const LIBRARY_PROFILES = {
+    subject: SUBJECT,
+    custom: { ...SUBJECT, template: 'custom' },
+    language: {
+        template: 'language',
+        markKind: 'word',
+        pointsDriven: false,
+        fill: 'spelling',
+        math: false,
+        coachHint: 'The learner\'s marked words first (meaning in context, collocation, spelling); a word they miss becomes a card.',
+    },
+};
+/** A template's profile (an unknown template reads as subject). */
+export function profileOf(template) {
+    return (template === undefined ? undefined : LIBRARY_PROFILES[template]) ?? SUBJECT;
+}

package/lib/types/remote.d.ts

@@ -0,0 +1,355 @@
+/**
+ * The library Remote: the browser-facing wire face, and nothing else.
+ *
+ * Every method is a one-line delegation to {@link LibraryService}; the value it
+ * returns is the BARE domain value (a refusal is a value inside the protocol's
+ * own result envelope, never a second `{ ok }` object nested inside the first).
+ * Session-bound methods take the calling session's id first (the canvas
+ * precedent): that session is the one bound.
+ *
+ * v5: the shelf unified — books are resources (`getResource` / `putResource` /
+ * `removeResource`), quizzes are assessments (`listAssessments` /
+ * `getAssessment`), and every scope key is `resourceId`.
+ *
+ * @module @khorsheed/dsh-library/remote
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { LibraryAssessResult, LibraryAssessment, LibraryAttachmentRef, LibraryAttempt, LibraryBinding, LibraryBookKind, LibraryCapabilities, LibraryCard, LibraryCardInput, LibraryCardQuery, LibraryCardWriteResult, LibraryColor, LibraryIcon, LibraryProjectPatch, LibraryEvent, LibraryEventType, LibraryMark, LibraryOutcome, LibraryPage, LibraryProject, LibraryProjectSummary, LibraryResource, LibraryResourceKind, LibraryResourceOrigin, LibraryReviewRating, LibraryRoadmap, LibraryTemplate, LibraryTocSource, LibraryVerdict } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        libraryRemote: LibraryRemoteService;
+    }
+}
+/** Reserved for future config-driven knobs; the service owns today's config. */
+export interface LibraryRemoteConfig {
+}
+/** The wire namespace is `library`: the browser calls `remote.library.*`. */
+export declare class LibraryRemoteService extends TypertRemoteService<LibraryRemoteConfig> {
+    static inject: string[];
+    constructor(ctx: Context, _config?: LibraryRemoteConfig);
+    /** The service core this face delegates to. */
+    private get core();
+    /** What this composition can do: storage and attachments, with the reason — the display contract. */
+    capabilities(): Promise<LibraryCapabilities>;
+    /** Every project with its shelf progress and card tallies. */
+    listProjects(): Promise<{
+        projects: LibraryProjectSummary[];
+    }>;
+    /** One project's summary plus its resources. */
+    getProject(request: {
+        id: string;
+    }): Promise<LibraryOutcome<{
+        project: LibraryProjectSummary;
+        resources: LibraryResource[];
+    }>>;
+    /** Create a project. */
+    createProject(request: {
+        name: string;
+        template?: LibraryTemplate;
+        templateNote?: string;
+        goal?: string;
+        color?: LibraryColor;
+        icon?: LibraryIcon;
+    }): Promise<LibraryOutcome<{
+        project: LibraryProject;
+    }>>;
+    /** Change a project's look, goal or name. */
+    updateProject(request: {
+        id: string;
+        patch: LibraryProjectPatch;
+    }): Promise<LibraryOutcome<{
+        project: LibraryProject;
+    }>>;
+    /** Delete a project and everything it holds. */
+    deleteProject(request: {
+        id: string;
+    }): Promise<LibraryOutcome<{
+        id: string;
+    }>>;
+    /** One shelf entry, whole. */
+    getResource(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<LibraryOutcome<{
+        resource: LibraryResource;
+    }>>;
+    /** A project's shelf: textbooks in study order, then links oldest first. */
+    listResources(request: {
+        projectId: string;
+    }): Promise<{
+        resources: LibraryResource[];
+    }>;
+    /** Put one entry on the shelf (a thin link from the sidebar's add form). */
+    putResource(request: {
+        projectId: string;
+        resourceId?: string;
+        title: string;
+        kind: LibraryResourceKind;
+        url?: string;
+        note?: string;
+        origin?: LibraryResourceOrigin;
+        seq?: number;
+        toc?: readonly {
+            title: string;
+            part?: string;
+        }[];
+        tocSource?: LibraryTocSource;
+        bookKind?: LibraryBookKind;
+        short?: string;
+        extras?: readonly {
+            title: string;
+            note?: string;
+            where?: string;
+            when?: 'before' | 'reference';
+        }[];
+        author?: string;
+        edition?: string;
+        isbn?: string;
+        from?: {
+            projectId: string;
+            resourceId: string;
+        };
+    }): Promise<LibraryOutcome<{
+        resource: LibraryResource;
+    }>>;
+    /** Switch a textbook between 知识型 and 材料型. */
+    setBookKind(request: {
+        projectId: string;
+        resourceId: string;
+        bookKind: 'knowledge' | 'material';
+    }): Promise<LibraryOutcome<{
+        resource: LibraryResource;
+    }>>;
+    /** Move a textbook to another place in the study order. */
+    moveResource(request: {
+        projectId: string;
+        resourceId: string;
+        seq: number;
+    }): Promise<LibraryOutcome<{
+        resources: LibraryResource[];
+    }>>;
+    /** Remove a shelf entry (its cards stay, unhung). */
+    removeResource(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<LibraryOutcome<{
+        id: string;
+    }>>;
+    /** One textbook's adopted roadmap and its pending draft. */
+    getRoadmap(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<{
+        roadmap?: LibraryRoadmap;
+        draft?: LibraryRoadmap;
+    }>;
+    /** The learner's 采用. */
+    adoptRoadmap(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<LibraryOutcome<{
+        roadmap: LibraryRoadmap;
+    }>>;
+    /** Drop a draft. */
+    discardDraft(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<LibraryOutcome<{
+        resourceId: string;
+    }>>;
+    /** 「读完」 a read node. */
+    markNodeRead(request: {
+        projectId: string;
+        resourceId?: string;
+        nodeId: string;
+    }): Promise<LibraryOutcome<{
+        roadmap: LibraryRoadmap;
+        unlocked: string[];
+    }>>;
+    /** One resource's pages, optionally one node's. */
+    listPages(request: {
+        projectId: string;
+        resourceId: string;
+        nodeId?: string;
+    }): Promise<{
+        pages: LibraryPage[];
+    }>;
+    /** One page's photo, base64 — whitelisted to recorded pages. */
+    readPagePhoto(request: {
+        projectId: string;
+        pageId: string;
+    }): Promise<LibraryOutcome<{
+        data: string;
+        mediaType: string;
+    }>>;
+    /** Save a browser-uploaded photo into the attachment store. */
+    savePhoto(request: {
+        data: string;
+        mediaType: string;
+    }): Promise<LibraryOutcome<{
+        attachment: LibraryAttachmentRef;
+    }>>;
+    /** Record a recognized page and card its marks. */
+    recordPage(request: {
+        projectId: string;
+        resourceId: string;
+        nodeId?: string;
+        label?: string;
+        attachment: LibraryAttachmentRef;
+        text: string;
+        marks: readonly LibraryMark[];
+    }): Promise<LibraryOutcome<{
+        page: LibraryPage;
+        cards: LibraryCardWriteResult;
+        uncertain: string[];
+    }>>;
+    /** Cards, filtered and sorted. */
+    listCards(request: LibraryCardQuery): Promise<{
+        cards: LibraryCard[];
+        total: number;
+    }>;
+    /** Due cards across projects (or one). */
+    dueCards(request: {
+        projectId?: string;
+        limit?: number;
+    }): Promise<{
+        cards: (LibraryCard & {
+            projectId: string;
+        })[];
+    }>;
+    /** Record cards by hand. */
+    writeCards(request: {
+        projectId: string;
+        resourceId?: string;
+        cards: readonly LibraryCardInput[];
+    }): Promise<LibraryOutcome<LibraryCardWriteResult>>;
+    /** Edit one card. */
+    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;
+    }>>;
+    /** The toast's 撤销. */
+    undoCards(request: {
+        projectId: string;
+        ids: readonly string[];
+        at: string;
+    }): Promise<LibraryOutcome<{
+        removed: number;
+        reverted: number;
+    }>>;
+    /** One flashcard review. */
+    reviewCard(request: {
+        projectId: string;
+        cardId: string;
+        rating: LibraryReviewRating;
+    }): Promise<LibraryOutcome<{
+        card: LibraryCard;
+    }>>;
+    /** A project's assessments, optionally one resource's / node's / one type's. */
+    listAssessments(request: {
+        projectId: string;
+        resourceId?: string;
+        nodeId?: string;
+        type?: 'quiz' | 'practice';
+    }): Promise<{
+        assessments: LibraryAssessment[];
+    }>;
+    /** One assessment, whole. */
+    getAssessment(request: {
+        projectId: string;
+        assessmentId: string;
+    }): Promise<LibraryOutcome<{
+        assessment: LibraryAssessment;
+    }>>;
+    /** Grade a sitting answered in the sidebar (choice / fill judged in the page). */
+    putAttempt(request: {
+        projectId: string;
+        assessmentId?: string;
+        quizId?: string;
+        nodeId?: string;
+        resourceId?: string;
+        verdicts: readonly LibraryVerdict[];
+    }): Promise<LibraryOutcome<LibraryAssessResult>>;
+    /** A project's graded sittings, newest first; `nodeId` narrows to one station's history, `assessmentId` to one assessment's. */
+    listAttempts(request: {
+        projectId: string;
+        nodeId?: string;
+        assessmentId?: string;
+    }): Promise<{
+        attempts: LibraryAttempt[];
+    }>;
+    /** The calling session's binding, or null. */
+    boundTarget(sessionId: SessionId): Promise<LibraryBinding | null>;
+    /** Bind the calling session to a project / resource (null unbinds). */
+    bindTarget(sessionId: SessionId, request: {
+        binding: LibraryBinding | null;
+    }): Promise<LibraryOutcome<{
+        binding: LibraryBinding | null;
+    }>>;
+    /** One project's audit trail, newest first. */
+    listEvents(request: {
+        projectId: string;
+        limit?: number;
+        types?: readonly LibraryEventType[];
+    }): Promise<{
+        events: LibraryEvent[];
+    }>;
+    /** 「教练最近记下」 across projects. */
+    /** The newest knowledge-point state changes (今日 「最近的变化」). */
+    recentChanges(request: {
+        limit?: number;
+    }): Promise<{
+        changes: (LibraryEvent & {
+            projectId: string;
+            projectName: string;
+        })[];
+    }>;
+    /** 订正: a retake paper over a station's open misses (all, or the keys named). */
+    createRetake(request: {
+        projectId: string;
+        resourceId?: string;
+        nodeId?: string;
+        keys?: readonly string[];
+    }): Promise<LibraryOutcome<{
+        assessment: LibraryAssessment;
+    }>>;
+    recentRecords(request: {
+        limit?: number;
+    }): Promise<{
+        records: (LibraryEvent & {
+            projectId: string;
+            projectName: string;
+        })[];
+    }>;
+    /** The newest event's timestamp anywhere — the pane polls it to re-read (no push channel). */
+    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;
+    }>;
+}
+export default LibraryRemoteService;
+//# sourceMappingURL=remote.d.ts.map