@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/types/service/pages.js

@@ -0,0 +1,125 @@
+/**
+ * Photographed pages: recording (marks carded), listing, photo reads and saves.
+ *
+ * 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/pages
+ */
+import { isThickResource, libraryErrorMessage, } from "../types.js";
+import { mintLibraryId } from "../store.js";
+import { refuse } from "./core.js";
+import { profileOf } from "../profiles.js";
+import { LibraryServiceRoadmap } from "./roadmap.js";
+export class LibraryServicePages extends LibraryServiceRoadmap {
+    /* --------------------------------------------------------------- pages */
+    /**
+     * Record one photographed page and card every mark at once (「一键全收」).
+     * Uncertain marks are kept on the page but never carded — the learner
+     * decides them. Each card's gloss is the mark's recognized gloss, else the
+     * learner's handwriting, else a placeholder the learner can fill in.
+     */
+    async recordPage(request) {
+        this.assertAlive('recordPage');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        const resource = this.store.readResource(project.value.id, request.resourceId);
+        if (resource === undefined)
+            return refuse('not-found', `no resource ${JSON.stringify(request.resourceId)} in this project — a page belongs to a resource`);
+        if (!isThickResource(resource))
+            return refuse('invalid', `《${resource.title}》 is a thin link — only a thick resource (one with a contents) has pages to photograph`);
+        const ref = request.attachment;
+        if (typeof ref?.attachmentId !== 'string' || typeof ref.mediaType !== 'string' || typeof ref.bytes !== 'number' || typeof ref.width !== 'number' || typeof ref.height !== 'number') {
+            return refuse('ref-incomplete', 'attachment needs the image block\'s whole durable reference — { attachmentId, mediaType, bytes, width, height }, copied verbatim; the photo itself is never copied');
+        }
+        if (request.text.trim() === '') {
+            return refuse('invalid', 'text is the page\'s printed text as recognized — a photo-backed question quotes it, so transcribe the page, not only the marks');
+        }
+        const marks = request.marks.filter(mark => mark.text.trim() !== '');
+        const pageId = mintLibraryId('pg');
+        const nodeId = request.nodeId;
+        if (nodeId !== undefined) {
+            const roadmap = this.store.readRoadmap(project.value.id, resource.id);
+            if (roadmap !== undefined && !roadmap.nodes.some(node => node.id === nodeId)) {
+                return refuse('not-found', `no node ${JSON.stringify(nodeId)} on this resource's path — omit nodeId or read the roadmap`);
+            }
+        }
+        const kind = profileOf(project.value.template).markKind;
+        const inputs = marks.filter(mark => mark.uncertain !== true).map(mark => ({
+            kind,
+            term: mark.text,
+            gloss: mark.gloss ?? mark.handNote ?? '（待补释义）',
+            ...(mark.handNote === undefined ? {} : { userGloss: mark.handNote }),
+            ...(mark.sentence === undefined ? {} : { context: { sentence: mark.sentence, pageId, ...(nodeId === undefined ? {} : { nodeId }) } }),
+            source: { type: 'photo', ref: pageId, ...(request.label === undefined ? {} : { note: request.label }) },
+            resourceId: resource.id,
+        }));
+        return await this.mutate(project.value.id, () => {
+            const cards = this.applyCardInputs(project.value.id, inputs, resource.id, { mergeNear: kind === 'word' });
+            const page = {
+                id: pageId,
+                resourceId: resource.id,
+                ...(nodeId === undefined ? {} : { nodeId }),
+                ...(request.label === undefined || request.label.trim() === '' ? {} : { label: request.label.trim() }),
+                attachment: { attachmentId: ref.attachmentId, mediaType: ref.mediaType, bytes: ref.bytes, width: ref.width, height: ref.height },
+                text: request.text,
+                marks,
+                cardIds: [...cards.added, ...cards.merged].map(card => card.id),
+                at: new Date().toISOString(),
+            };
+            this.store.appendPage(project.value.id, page);
+            this.event(project.value.id, 'page.recorded', { id: page.id, title: page.label ?? resource.title, resourceId: resource.id, count: cards.added.length, count2: cards.merged.length });
+            return { ok: true, page, cards, uncertain: marks.filter(mark => mark.uncertain === true).map(mark => mark.text) };
+        });
+    }
+    /** One resource's pages, optionally one node's. */
+    async listPages(request) {
+        this.assertAlive('listPages');
+        const pages = this.store.readPages(request.projectId, request.resourceId);
+        return { pages: request.nodeId === undefined ? pages : pages.filter(page => page.nodeId === request.nodeId) };
+    }
+    /** Find one page anywhere in the project. */
+    findPage(projectId, pageId) {
+        for (const resource of this.store.listResources(projectId)) {
+            const page = this.store.readPages(projectId, resource.id).find(candidate => candidate.id === pageId);
+            if (page !== undefined)
+                return page;
+        }
+        return undefined;
+    }
+    /**
+     * One page's photo, as base64 — whitelisted: the page must be one this
+     * project recorded, so the Remote never reads an arbitrary attachment.
+     */
+    async readPagePhoto(request) {
+        this.assertAlive('readPagePhoto');
+        const page = this.findPage(request.projectId, request.pageId);
+        if (page === undefined)
+            return refuse('not-found', `no page ${JSON.stringify(request.pageId)} in this project`);
+        const attachments = this.ctx.get('attachments');
+        if (attachments === undefined)
+            return refuse('unavailable', 'this deployment mounts no attachment store — the photo cannot be read back here');
+        try {
+            const stored = await attachments.readImage(page.attachment);
+            return { ok: true, data: Buffer.from(stored.data).toString('base64'), mediaType: stored.ref.mediaType };
+        }
+        catch (error) {
+            return refuse('io', `the photo could not be read — ${libraryErrorMessage(error)}`);
+        }
+    }
+    /** Save a browser-uploaded photo into the host attachment store (the sidebar's 拍照). */
+    async savePhoto(request) {
+        this.assertAlive('savePhoto');
+        const attachments = this.ctx.get('attachments');
+        if (attachments?.saveImage === undefined)
+            return refuse('unavailable', 'this deployment mounts no attachment store — photos cannot be saved here');
+        try {
+            const attachment = await attachments.saveImage({ data: Buffer.from(request.data, 'base64'), mediaType: request.mediaType });
+            return { ok: true, attachment };
+        }
+        catch (error) {
+            return refuse('invalid', `the photo was refused — ${libraryErrorMessage(error)}`);
+        }
+    }
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Paths: drafts, adoption (with practice rubrics materialized), discard, station notes, 读完.
+ *
+ * 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/roadmap
+ */
+import { type LibraryAcceptanceInput, type LibraryOutcome, type LibraryNodeCover, type LibraryNodeNotes, type LibraryPoint, type LibraryRoadmap, type RoadmapNode } from '../types.ts';
+import { LibraryServiceCards } from './cards.ts';
+export declare class LibraryServiceRoadmap extends LibraryServiceCards {
+    /** One textbook's adopted roadmap and its pending draft. */
+    getRoadmap(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<{
+        roadmap?: LibraryRoadmap;
+        draft?: LibraryRoadmap;
+    }>;
+    /**
+     * Write the coach's draft of one textbook's path; it replaces the
+     * textbook's previous draft. Shape rules: unique ids, a gate, at least one
+     * cover per node, references that exist, locators inside the resource's
+     * contents, dependencies pointing backwards. States are not the coach's to
+     * set — adoption initializes them.
+     */
+    draftRoadmap(request: {
+        projectId: string;
+        resourceId: string;
+        nodes: readonly {
+            id: string;
+            title: string;
+            gate: RoadmapNode['gate'];
+            goals?: readonly string[] | string;
+            covers?: readonly LibraryNodeCover[];
+            dependsOn?: readonly string[];
+            acceptance?: readonly LibraryAcceptanceInput[];
+            /** Quiz-gated stations only: the knowledge points this station tests (3-6) — stable slug ids, reviewed on the draft card. */
+            points?: readonly LibraryPoint[];
+        }[];
+        passRatio?: number;
+        note?: string;
+    }): Promise<LibraryOutcome<{
+        draft: LibraryRoadmap;
+    }>>;
+    /**
+     * The learner's 采用: the draft becomes the path. Nodes whose deps are
+     * all done start `current`; a node that survives a re-split (same id) keeps
+     * its state, its quiz stats and its 讲义, so re-planning never erases
+     * progress. Every acceptance station's rubric materializes as its practice
+     * assessment (unchanged lines reuse the live one — its history stays put;
+     * changed lines supersede it).
+     */
+    adoptRoadmap(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<LibraryOutcome<{
+        roadmap: LibraryRoadmap;
+    }>>;
+    /**
+     * Give every acceptance node a practice assessment keyed to it: an
+     * unchanged rubric reuses the node's live assessment (its attempts stay
+     * attached); a changed rubric supersedes it (the old snapshot keeps the old
+     * history). Call inside the project lock.
+     */
+    protected materializePracticeAssessments(projectId: string, nodes: readonly RoadmapNode[], at: string): void;
+    /** Drop a textbook's draft without adopting it. */
+    discardDraft(request: {
+        projectId: string;
+        resourceId: string;
+    }): Promise<LibraryOutcome<{
+        resourceId: string;
+    }>>;
+    /**
+     * Write (or rewrite) a station's 讲义 — the coach's distilled teaching,
+     * persisted on the adopted path's node. Replanning keeps it when the
+     * station's id survives; every write bumps `revisions`.
+     */
+    /** Why a 讲义 has nowhere to land, naming the fix: the path is only a draft, the station sits on another textbook, or here are this path's stations. */
+    private notesMiss;
+    putNotes(request: {
+        projectId: string;
+        resourceId?: string;
+        nodeId: string;
+        text: string;
+    }): Promise<LibraryOutcome<{
+        notes: LibraryNodeNotes;
+    }>>;
+    /** 「读完」: a current read node completes and unlocks what it gates. */
+    markNodeRead(request: {
+        projectId: string;
+        resourceId?: string;
+        nodeId: string;
+    }): Promise<LibraryOutcome<{
+        roadmap: LibraryRoadmap;
+        unlocked: string[];
+    }>>;
+}
+//# sourceMappingURL=roadmap.d.ts.map

package/lib/types/service/roadmap.js

@@ -0,0 +1,284 @@
+/**
+ * Paths: drafts, adoption (with practice rubrics materialized), discard, station notes, 读完.
+ *
+ * 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/roadmap
+ */
+import { isLibraryId, acceptanceLines, isThickResource, } from "../types.js";
+import { mintLibraryId } from "../store.js";
+import { refuse } from "./core.js";
+import { lessonProblems, titleOf, unlockReady, validateRoadmapShape } from "./rules.js";
+import { LibraryServiceCards } from "./cards.js";
+export class LibraryServiceRoadmap extends LibraryServiceCards {
+    /* ------------------------------------------------------------- roadmap */
+    /** One textbook's adopted roadmap and its pending draft. */
+    async getRoadmap(request) {
+        this.assertAlive('getRoadmap');
+        const roadmap = this.store.readRoadmap(request.projectId, request.resourceId);
+        const draft = this.store.readRoadmap(request.projectId, request.resourceId, 'draft');
+        return { ...(roadmap === undefined ? {} : { roadmap }), ...(draft === undefined ? {} : { draft }) };
+    }
+    /**
+     * Write the coach's draft of one textbook's path; it replaces the
+     * textbook's previous draft. Shape rules: unique ids, a gate, at least one
+     * cover per node, references that exist, locators inside the resource's
+     * contents, dependencies pointing backwards. States are not the coach's to
+     * set — adoption initializes them.
+     */
+    async draftRoadmap(request) {
+        this.assertAlive('draftRoadmap');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        const textbooks = this.store.listResources(project.value.id).filter(isThickResource);
+        const shelf = textbooks.length === 0
+            ? 'this project has no textbook yet — register one first (library_textbook with a contents: the learner\'s book, one you pick, or one you author)'
+            : `this project's textbooks: ${textbooks.map(textbook => `${textbook.seq ?? '-'}. ${textbook.id} 《${textbook.title}》`).join('; ')}`;
+        if (typeof request.resourceId !== 'string' || request.resourceId.trim() === '') {
+            return refuse('invalid', `a path belongs to one textbook — pass resource; ${shelf}`);
+        }
+        const primary = isLibraryId(request.resourceId) ? this.store.readResource(project.value.id, request.resourceId) : undefined;
+        if (primary === undefined) {
+            return refuse('not-found', `no resource ${JSON.stringify(request.resourceId)} in project ${JSON.stringify(project.value.name)} — ${shelf}`);
+        }
+        if (!isThickResource(primary)) {
+            return refuse('invalid', `《${primary.title}》 is a link without contents — it never carries a path; cite it inside a station of a textbook's path (also: ["${primary.id}"]). ${shelf}`);
+        }
+        if (request.nodes.length === 0) {
+            return refuse('invalid', 'a roadmap needs at least one node — split the material into learning stations; each: { id, title, gate: "quiz"|"acceptance"|"read", goals, covers: ["r_…#1-5" | "https://…" | "topic: …"], dependsOn }; an acceptance station also needs acceptance: [...]');
+        }
+        if (request.passRatio !== undefined && !(request.passRatio > 0 && request.passRatio <= 1)) {
+            return refuse('invalid', 'passRatio is a fraction in (0, 1] — 0.8 means 8 of 10 right');
+        }
+        for (const node of request.nodes) {
+            if (node.points === undefined || node.points.length === 0)
+                continue;
+            if (node.gate !== 'quiz')
+                return refuse('invalid', `${node.title} is a ${node.gate} node — points (考点) belong to quiz-gated stations only`);
+            const seen = new Set();
+            for (const point of node.points) {
+                if (!isLibraryId(point.id))
+                    return refuse('invalid', `point id ${JSON.stringify(point.id)} on ${node.title} is not a safe slug (letters, digits, . _ -) — it is the mastery key, stable across quizzes`);
+                if (typeof point.title !== 'string' || point.title.trim() === '')
+                    return refuse('invalid', `point ${point.id} on ${node.title} needs a title — the point as the learner reads it (「极限的定义」)`);
+                if (seen.has(point.id))
+                    return refuse('invalid', `duplicate point id ${point.id} on ${node.title} — reference the existing one`);
+                seen.add(point.id);
+            }
+        }
+        const nodes = request.nodes.map(node => ({
+            id: node.id,
+            title: node.title,
+            gate: node.gate,
+            // A model writes one goal as a bare string as often as a list.
+            goals: typeof node.goals === 'string' ? [node.goals] : (node.goals ?? []).filter(goal => typeof goal === 'string'),
+            covers: node.covers ?? [],
+            dependsOn: node.dependsOn ?? [],
+            state: 'locked',
+            ...(node.points === undefined || node.points.length === 0 ? {} : { points: node.points.map(point => ({ id: point.id, title: point.title.trim() })) }),
+            ...(Array.isArray(node.acceptance) ? {
+                acceptance: node.acceptance.flatMap((entry) => {
+                    if (typeof entry === 'string')
+                        return entry.trim() === '' ? [] : [entry];
+                    if (typeof entry?.line !== 'string' || entry.line.trim() === '')
+                        return [];
+                    return [{ line: entry.line.trim(), ...(typeof entry.ref === 'string' && entry.ref.trim() !== '' ? { ref: entry.ref.trim() } : {}) }];
+                }),
+            } : {}),
+        }));
+        const shapeError = validateRoadmapShape(nodes, {
+            resourceId: primary.id,
+            resource: candidate => this.store.readResource(project.value.id, candidate),
+            hasAssessment: candidate => this.store.readAssessment(project.value.id, candidate) !== undefined,
+        });
+        if (shapeError !== undefined)
+            return refuse('invalid', shapeError);
+        return await this.mutate(project.value.id, () => {
+            const draft = {
+                primaryResourceId: primary.id,
+                status: 'draft',
+                nodes,
+                ...(request.passRatio === undefined ? {} : { passRatio: request.passRatio }),
+                ...(request.note === undefined || request.note.trim() === '' ? {} : { note: request.note.trim() }),
+                generatedAt: new Date().toISOString(),
+            };
+            this.store.writeRoadmap(project.value.id, draft);
+            this.event(project.value.id, 'roadmap.drafted', { id: primary.id, title: primary.title, resourceId: primary.id, count: nodes.length });
+            return { ok: true, draft: draft };
+        });
+    }
+    /**
+     * The learner's 采用: the draft becomes the path. Nodes whose deps are
+     * all done start `current`; a node that survives a re-split (same id) keeps
+     * its state, its quiz stats and its 讲义, so re-planning never erases
+     * progress. Every acceptance station's rubric materializes as its practice
+     * assessment (unchanged lines reuse the live one — its history stays put;
+     * changed lines supersede it).
+     */
+    async adoptRoadmap(request) {
+        this.assertAlive('adoptRoadmap');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        return await this.mutate(project.value.id, () => {
+            const draft = this.store.readRoadmap(project.value.id, request.resourceId, 'draft');
+            if (draft === undefined)
+                return refuse('not-found', 'no draft to adopt here — ask the coach to draft a roadmap first');
+            const prior = new Map((this.store.readRoadmap(project.value.id, request.resourceId)?.nodes ?? []).map(node => [node.id, node]));
+            const nodes = [];
+            for (const node of draft.nodes) {
+                const kept = prior.get(node.id);
+                // No station is locked (user decision 10-26, D6): the path is a recommended
+                // order; any station can be studied and quizzed, and passing records it.
+                const state = kept?.state === 'done' ? 'done' : 'current';
+                nodes.push({
+                    ...node,
+                    state,
+                    ...(node.gate === 'quiz' ? { quizStats: kept?.quizStats ?? { attempts: 0 } } : {}),
+                    // A re-plan that keeps the station's id also keeps its 讲义.
+                    ...(kept?.notes !== undefined ? { notes: kept.notes } : {}),
+                });
+            }
+            const now = new Date().toISOString();
+            const roadmap = { ...draft, primaryResourceId: request.resourceId, status: 'adopted', nodes, adoptedAt: now };
+            this.store.writeRoadmap(project.value.id, roadmap);
+            this.store.removeDraft(project.value.id, request.resourceId);
+            // Materialize each acceptance station's rubric as its practice assessment.
+            this.materializePracticeAssessments(project.value.id, nodes, now);
+            const primary = this.store.readResource(project.value.id, request.resourceId);
+            this.event(project.value.id, 'roadmap.adopted', {
+                at: now,
+                id: request.resourceId,
+                title: primary?.title ?? request.resourceId,
+                resourceId: request.resourceId,
+                count: nodes.length,
+            });
+            return { ok: true, roadmap };
+        });
+    }
+    /**
+     * Give every acceptance node a practice assessment keyed to it: an
+     * unchanged rubric reuses the node's live assessment (its attempts stay
+     * attached); a changed rubric supersedes it (the old snapshot keeps the old
+     * history). Call inside the project lock.
+     */
+    materializePracticeAssessments(projectId, nodes, at) {
+        const assessments = this.store.listAssessments(projectId);
+        for (const node of nodes) {
+            if (node.gate !== 'acceptance')
+                continue;
+            const rubric = acceptanceLines(node);
+            if (rubric.length === 0)
+                continue;
+            const liveAssessment = assessments.find(assessment => assessment.type === 'practice' && assessment.scope.nodeId === node.id && assessment.supersededBy === undefined);
+            const sameRubric = liveAssessment !== undefined
+                && (liveAssessment.rubric ?? []).length === rubric.length
+                && rubric.every((line, index) => liveAssessment.rubric?.[index]?.line === line.line && liveAssessment.rubric?.[index]?.ref === line.ref);
+            if (sameRubric)
+                continue;
+            const assessment = {
+                id: mintLibraryId('q'),
+                type: 'practice',
+                scope: { nodeId: node.id },
+                rubric,
+                createdAt: at,
+            };
+            this.store.writeAssessment(projectId, assessment);
+            if (liveAssessment !== undefined) {
+                this.store.writeAssessment(projectId, { ...liveAssessment, supersededBy: assessment.id });
+            }
+        }
+    }
+    /** Drop a textbook's draft without adopting it. */
+    async discardDraft(request) {
+        this.assertAlive('discardDraft');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        return await this.mutate(project.value.id, () => {
+            this.store.removeDraft(project.value.id, request.resourceId);
+            return { ok: true, resourceId: request.resourceId };
+        });
+    }
+    /**
+     * Write (or rewrite) a station's 讲义 — the coach's distilled teaching,
+     * persisted on the adopted path's node. Replanning keeps it when the
+     * station's id survives; every write bumps `revisions`.
+     */
+    /** Why a 讲义 has nowhere to land, naming the fix: the path is only a draft, the station sits on another textbook, or here are this path's stations. */
+    notesMiss(projectId, resourceId, nodeId) {
+        const book = resourceId === undefined ? undefined : this.store.readResource(projectId, resourceId);
+        const named = book === undefined ? 'this textbook' : `《${book.title}》 (${book.id})`;
+        const roadmap = this.store.readRoadmap(projectId, resourceId);
+        if (roadmap === undefined) {
+            const draft = this.store.readRoadmap(projectId, resourceId, 'draft');
+            return refuse('not-found', draft === undefined
+                ? `${named} has no path yet — draft one (library_roadmap); 讲义 land on an adopted path's stations`
+                : `${named}'s path is still a draft — the learner adopts it in the sidebar (路线 → 采用) before 讲义 can land; teach in the conversation meanwhile, then write the 讲义`);
+        }
+        const elsewhere = this.store.listResources(projectId)
+            .filter(resource => resource.id !== roadmap.primaryResourceId)
+            .find(resource => this.store.readRoadmap(projectId, resource.id)?.nodes.some(candidate => candidate.id === nodeId) === true);
+        if (elsewhere !== undefined)
+            return refuse('not-found', `station ${JSON.stringify(nodeId)} is on 《${elsewhere.title}》's path — pass resource ${elsewhere.id}`);
+        return refuse('not-found', `no station ${JSON.stringify(nodeId)} on ${named}'s path — its stations: ${roadmap.nodes.map(candidate => candidate.id).join(', ')}`);
+    }
+    async putNotes(request) {
+        this.assertAlive('putNotes');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        const text = request.text.trim();
+        if (text === '')
+            return refuse('invalid', 'notes need text — the distilled teaching for this station (markdown): the explanation, the points the learner got stuck on, the pitfalls');
+        return await this.mutate(project.value.id, () => {
+            const roadmap = this.store.readRoadmap(project.value.id, request.resourceId);
+            const node = roadmap?.nodes.find(candidate => candidate.id === request.nodeId);
+            if (roadmap === undefined || node === undefined)
+                return this.notesMiss(project.value.id, request.resourceId, request.nodeId);
+            const book = roadmap.primaryResourceId === undefined ? undefined : this.store.readResource(project.value.id, roadmap.primaryResourceId);
+            // Every textbook's 讲义 are the lesson itself (10-26): the per-point check applies to all.
+            const lesson = lessonProblems(text, node, book !== undefined);
+            if (lesson !== undefined)
+                return refuse('invalid', lesson);
+            // A rewrite keeps the version it replaces (notes/<resource>/<node>.<n>.md).
+            if (node.notes !== undefined && node.notes.text !== '' && roadmap.primaryResourceId !== undefined) {
+                this.store.archiveNotes(project.value.id, roadmap.primaryResourceId, node.id, node.notes.revisions, node.notes.text);
+            }
+            const notes = { text, updatedAt: new Date().toISOString(), revisions: (node.notes?.revisions ?? 0) + 1 };
+            const next = { ...roadmap, nodes: roadmap.nodes.map(candidate => candidate.id === node.id ? { ...candidate, notes } : candidate) };
+            this.store.writeRoadmap(project.value.id, next);
+            this.event(project.value.id, 'node.noted', { id: node.id, title: node.title, ...(request.resourceId === undefined ? {} : { resourceId: request.resourceId }), count: notes.revisions });
+            return { ok: true, notes };
+        });
+    }
+    /** 「读完」: a current read node completes and unlocks what it gates. */
+    async markNodeRead(request) {
+        this.assertAlive('markNodeRead');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        return await this.mutate(project.value.id, () => {
+            const roadmap = this.store.readRoadmap(project.value.id, request.resourceId);
+            const node = roadmap?.nodes.find(candidate => candidate.id === request.nodeId);
+            if (roadmap === undefined || node === undefined)
+                return refuse('not-found', `no node ${JSON.stringify(request.nodeId)} on the adopted path`);
+            if (node.gate !== 'read')
+                return refuse('state-machine', `${node.title} is a ${node.gate} node — only a read node completes by 读完 (a quiz node by passing its quiz, an acceptance station by acceptance)`);
+            if (node.state !== 'current')
+                return refuse('state-machine', `${node.title} is ${node.state} — only a current node can be marked read`);
+            const now = new Date().toISOString();
+            const completed = roadmap.nodes.map(candidate => candidate.id === node.id ? { ...candidate, state: 'done' } : candidate);
+            const { nodes, unlocked } = unlockReady(completed);
+            const next = { ...roadmap, nodes };
+            this.store.writeRoadmap(project.value.id, next);
+            this.store.appendEvents(project.value.id, [
+                { at: now, type: 'node.completed', id: node.id, title: node.title, ...(request.resourceId === undefined ? {} : { resourceId: request.resourceId }) },
+                ...unlocked.map(nodeId => ({ at: now, type: 'node.unlocked', id: nodeId, title: titleOf(nodes, nodeId), ...(request.resourceId === undefined ? {} : { resourceId: request.resourceId }) })),
+            ]);
+            return { ok: true, roadmap: next, unlocked };
+        });
+    }
+}

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

@@ -0,0 +1,63 @@
+/**
+ * The library's pure rules: roadmap shape validation, the unlock pass, the
+ * covers' evidence gate, and two small helpers. No store, no context — the
+ * service layers and the tools call them.
+ *
+ * @module @khorsheed/dsh-library/service/rules
+ */
+import { type LibraryResource, type LibraryNodeCover, type RoadmapNode } from '../types.ts';
+/** A node's title, for event rows. */
+export declare function titleOf(nodes: readonly RoadmapNode[], nodeId: string): string;
+/**
+ * The option an answer key names — a letter in range, a lettered option, the
+ * option text, else a one-way containment — or -1. The sidebar's judge
+ * (`client/judge.ts`'s choiceIndex) resolves the same spellings; a question
+ * this resolves to -1 is judged wrong no matter what the learner picks, so
+ * the write gate refuses it.
+ */
+export declare function choiceOptionIndex(options: readonly string[], answer: string): number;
+/** Move every locked node whose deps are all done to current. */
+export declare function unlockReady(nodes: readonly RoadmapNode[]): {
+    nodes: RoadmapNode[];
+    unlocked: string[];
+};
+/** A lesson's size in knowledge points (a quiz station's points). */
+export declare const STATION_MIN_POINTS = 3;
+export declare const STATION_MAX_POINTS = 5;
+/**
+ * Structural validation of a roadmap's nodes; returns the teaching error or
+ * undefined. `scope.resourceId` marks a resource-level draft: the special case
+ * whose every node covers that one resource only. Every per-node problem is
+ * collected and reported at once — a draft with five mistakes earns ONE
+ * refusal listing all five, not five fail-fast round trips (each retry
+ * resends the whole nodes payload).
+ */
+export declare function validateRoadmapShape(nodes: readonly RoadmapNode[], scope: {
+    /** The textbook whose path this is (a cover of it is the station's main source; others ride along). */
+    resourceId: string;
+    /** Resolve a resource cover (existence + contents length). */
+    resource: (resourceId: string) => LibraryResource | undefined;
+    /** Whether an assessment exists (an acceptance line's ref). */
+    hasAssessment: (assessmentId: string) => boolean;
+}): string | undefined;
+/**
+ * Why a node's covers forbid a memory-backed content question, or undefined
+ * when they allow one: only knowledge books and plain coached teaching (topic)
+ * may be quizzed from domain knowledge; a material book, a thin link or a
+ * bare url demands a verbatim quote. When the station covers its own
+ * textbook (`primaryId`), that cover alone decides — a side reference (a
+ * video, an article) never turns a knowledge chapter into a quote-only one.
+ * The evidence-gate's node-level half (a resource-scoped quiz without a node
+ * keeps the resource rule).
+ */
+export declare function coversVerbatimBlocker(covers: readonly LibraryNodeCover[], resource: (resourceId: string) => LibraryResource | undefined, primaryId?: string): string | undefined;
+/** The least a point's 讲义 section says (characters, markup and blanks aside). */
+export declare const LESSON_SECTION_MIN = 120;
+/**
+ * What keeps a 讲义 from reading as a lesson, or undefined: change logs and
+ * internal words never reach the learner; on a textbook you authored (the 讲义
+ * ARE its text) every knowledge point gets its own section — a heading naming
+ * the point, then enough to learn it from.
+ */
+export declare function lessonProblems(text: string, node: RoadmapNode, authored: boolean): string | undefined;
+//# sourceMappingURL=rules.d.ts.map