@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/types/service/cards.js

@@ -0,0 +1,320 @@
+/**
+ * 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 { MAX_BOX, } from "../types.js";
+import { cardKey, cardKeys, cardMatchesQuery, exactMatch, nearMatches, } from "../cards.js";
+import { mintLibraryId } from "../store.js";
+import { refuse, leitnerDueAt, clampWeakness, live } from "./core.js";
+import { LibraryServiceShelf } from "./shelf.js";
+export class LibraryServiceCards extends LibraryServiceShelf {
+    /* --------------------------------------------------------------- cards */
+    /**
+     * 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.
+     */
+    applyCardInputs(projectId, inputs, defaultResourceId, options = {}) {
+        const cards = this.store.readCards(projectId);
+        const byId = new Map(cards.map(card => [card.id, card]));
+        const order = cards.map(card => card.id);
+        const added = [];
+        const merged = [];
+        const pending = [];
+        const now = new Date().toISOString();
+        for (const [index, input] of inputs.entries()) {
+            const keys = [input.term, ...(input.aliases ?? [])].map(cardKey).filter(key => key !== '');
+            const pool = [...byId.values()];
+            let target;
+            if (input.mergeInto !== undefined) {
+                target = byId.get(input.mergeInto);
+            }
+            else if (input.asNew !== true) {
+                target = exactMatch(pool, keys);
+                if (target === undefined) {
+                    const near = nearMatches(pool, keys);
+                    if (near.length > 0) {
+                        if (options.mergeNear === true) {
+                            target = near[0];
+                        }
+                        else {
+                            pending.push({ index, term: input.term, candidates: near.map(card => ({ id: card.id, term: card.term, gloss: card.gloss })) });
+                            continue;
+                        }
+                    }
+                }
+            }
+            const resourceId = input.resourceId ?? defaultResourceId;
+            const source = {
+                type: input.source.type,
+                ...(input.source.ref === undefined ? {} : { ref: input.source.ref }),
+                ...(input.source.note === undefined || input.source.note.trim() === '' ? {} : { note: input.source.note.trim() }),
+                ...(input.weaken === true ? { weakened: true } : {}),
+                at: now,
+            };
+            const context = input.context === undefined || input.context.sentence.trim() === ''
+                ? undefined
+                : {
+                    sentence: input.context.sentence.trim(),
+                    ...(resourceId === undefined ? {} : { resourceId }),
+                    ...(input.context.pageId === undefined ? {} : { pageId: input.context.pageId }),
+                    ...(input.context.nodeId === undefined ? {} : { nodeId: input.context.nodeId }),
+                };
+            if (target !== undefined) {
+                const aliases = new Set(target.aliases);
+                const ownKeys = new Set(cardKeys(target));
+                if (!ownKeys.has(cardKey(input.term)))
+                    aliases.add(input.term.trim());
+                for (const alias of input.aliases ?? [])
+                    if (!ownKeys.has(cardKey(alias)))
+                        aliases.add(alias.trim());
+                const placeholder = target.gloss === '（待补释义）';
+                const next = {
+                    ...target,
+                    aliases: [...aliases],
+                    gloss: placeholder ? input.gloss.trim() : target.gloss,
+                    ...(target.userGloss === undefined && input.userGloss !== undefined ? { userGloss: input.userGloss.trim() } : {}),
+                    contexts: context === undefined || target.contexts.some(existing => existing.sentence === context.sentence)
+                        ? target.contexts
+                        : [...target.contexts, context],
+                    ...(target.resourceId === undefined && resourceId !== undefined ? { resourceId } : {}),
+                    sources: [...target.sources, source],
+                    weakness: clampWeakness(target.weakness + (input.weaken === true ? 1 : 0)),
+                    // A card met again is active again — a re-sighting never resets mastery.
+                    status: target.status === 'deleted' ? 'active' : target.status,
+                    updatedAt: now,
+                };
+                byId.set(next.id, next);
+                merged.push(next);
+                continue;
+            }
+            const card = {
+                id: mintLibraryId('c'),
+                kind: input.kind,
+                term: input.term.trim(),
+                aliases: (input.aliases ?? []).map(alias => alias.trim()).filter(alias => alias !== '' && cardKey(alias) !== cardKey(input.term)),
+                gloss: input.gloss.trim(),
+                ...(input.userGloss === undefined || input.userGloss.trim() === '' ? {} : { userGloss: input.userGloss.trim() }),
+                contexts: context === undefined ? [] : [context],
+                ...(resourceId === undefined ? {} : { resourceId }),
+                sources: [source],
+                weakness: input.weaken === true || input.source.type === 'chat' ? 1 : 0,
+                mastery: { box: 0, dueAt: now, streak: 0 },
+                status: 'active',
+                createdAt: now,
+                updatedAt: now,
+            };
+            byId.set(card.id, card);
+            order.push(card.id);
+            added.push(card);
+        }
+        if (added.length > 0 || merged.length > 0) {
+            this.store.writeCards(projectId, order.map(cardId => byId.get(cardId)));
+            const touched = [...added, ...merged];
+            const sourceType = inputs[0]?.source.type;
+            this.event(projectId, 'cards.recorded', {
+                at: now,
+                title: touched.map(card => card.term).join('、').slice(0, 300),
+                ids: touched.map(card => card.id),
+                ...(sourceType === undefined ? {} : { source: sourceType }),
+                ...(sourceType === 'chat' && inputs[0]?.source.ref !== undefined ? { session: inputs[0].source.ref } : {}),
+                ...(defaultResourceId === undefined ? {} : { resourceId: defaultResourceId }),
+                count: added.length,
+                count2: merged.length,
+            });
+        }
+        return { added, merged, pending, at: now };
+    }
+    /**
+     * Record cards (the coach's 「记下」, a manual add). Near-duplicates come back
+     * in `pending` with their candidates — resend each with `mergeInto` or `asNew`.
+     */
+    async writeCards(request) {
+        this.assertAlive('writeCards');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        if (request.cards.length === 0) {
+            return refuse('invalid', 'cards needs at least one card — each: { kind: word|concept, term, gloss, context?, source: { type: chat|photo|quiz|manual, note? }, weaken? }');
+        }
+        // Per-card problems are collected and reported at once: a batch with
+        // three bad cards earns one refusal listing all three, not three
+        // fail-fast round trips.
+        const errors = [];
+        for (const [index, input] of request.cards.entries()) {
+            if (input.kind !== 'word' && input.kind !== 'concept')
+                errors.push(`cards[${index}].kind is word | concept`);
+            if (input.term.trim() === '' || input.gloss.trim() === '') {
+                errors.push(`cards[${index}] needs term and gloss — the gloss is the in-context meaning (a word) or a one-line explanation (a concept)`);
+            }
+            if (!['photo', 'chat', 'quiz', 'manual'].includes(input.source?.type)) {
+                errors.push(`cards[${index}].source.type is chat | photo | quiz | manual — chat: the learner asked / got stuck in conversation`);
+            }
+        }
+        const cards = this.store.readCards(project.value.id);
+        for (const [index, input] of request.cards.entries()) {
+            if (input.mergeInto !== undefined && !cards.some(card => card.id === input.mergeInto && live(card))) {
+                errors.push(`cards[${index}].mergeInto names ${JSON.stringify(input.mergeInto)}, which is not a live card — use an id from the pending candidates`);
+            }
+        }
+        if (errors.length === 1)
+            return refuse('invalid', errors[0]);
+        if (errors.length > 1) {
+            return refuse('invalid', `${errors.length} problems in cards — fix them all, then resend:\n${errors.map(error => `- ${error}`).join('\n')}`);
+        }
+        if (request.resourceId !== undefined && this.store.readResource(project.value.id, request.resourceId) === undefined) {
+            return refuse('not-found', `no resource ${JSON.stringify(request.resourceId)} in this project — omit resource for a project-level card`);
+        }
+        return await this.mutate(project.value.id, () => {
+            const { at: _at, ...result } = this.applyCardInputs(project.value.id, request.cards, request.resourceId);
+            return { ok: true, ...result };
+        });
+    }
+    /** Cards, filtered and sorted (the sidebar list, the coach's search). */
+    async listCards(request) {
+        this.assertAlive('listCards');
+        const now = new Date().toISOString();
+        let cards = this.store.readCards(request.projectId).filter(live);
+        if (request.includeMastered !== true)
+            cards = cards.filter(card => card.status === 'active');
+        if (request.resourceId !== undefined)
+            cards = cards.filter(card => card.resourceId === request.resourceId);
+        if (request.nodeId !== undefined)
+            cards = cards.filter(card => card.contexts.some(context => context.nodeId === request.nodeId));
+        if (request.kind !== undefined)
+            cards = cards.filter(card => card.kind === request.kind);
+        if (request.source !== undefined)
+            cards = cards.filter(card => card.sources.some(source => source.type === request.source));
+        if (request.weakMin !== undefined)
+            cards = cards.filter(card => card.weakness >= request.weakMin);
+        if (request.due === true)
+            cards = cards.filter(card => card.mastery.dueAt <= now);
+        if (request.query !== undefined && request.query.trim() !== '')
+            cards = cards.filter(card => cardMatchesQuery(card, request.query));
+        const sort = request.sort ?? 'weak';
+        cards.sort((a, b) => sort === 'recent'
+            ? b.updatedAt.localeCompare(a.updatedAt)
+            : sort === 'due'
+                ? a.mastery.dueAt.localeCompare(b.mastery.dueAt)
+                : b.weakness - a.weakness || a.mastery.dueAt.localeCompare(b.mastery.dueAt));
+        return { cards: cards.slice(0, request.limit ?? 200), total: cards.length };
+    }
+    /** The cards due for review across projects (or one), weakest first. */
+    async dueCards(request) {
+        this.assertAlive('dueCards');
+        const now = new Date().toISOString();
+        const projectIds = request.projectId !== undefined ? [request.projectId] : this.store.readIndex().projects.map(project => project.id);
+        const due = [];
+        for (const projectId of projectIds) {
+            for (const card of this.store.readCards(projectId)) {
+                if (card.status === 'active' && card.mastery.dueAt <= now)
+                    due.push({ ...card, projectId });
+            }
+        }
+        due.sort((a, b) => a.mastery.box - b.mastery.box || b.weakness - a.weakness || a.mastery.dueAt.localeCompare(b.mastery.dueAt));
+        return { cards: due.slice(0, request.limit ?? 200) };
+    }
+    /** Edit a card by hand: its words, or its status (mastered / deleted / active). */
+    async editCard(request) {
+        this.assertAlive('editCard');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        return await this.mutate(project.value.id, () => {
+            const cards = this.store.readCards(project.value.id);
+            const card = cards.find(candidate => candidate.id === request.cardId);
+            if (card === undefined)
+                return refuse('not-found', `no card ${JSON.stringify(request.cardId)}`);
+            const patch = request.patch;
+            if (patch.term !== undefined && patch.term.trim() === '')
+                return refuse('invalid', 'a card keeps a term');
+            if (patch.gloss !== undefined && patch.gloss.trim() === '')
+                return refuse('invalid', 'a card keeps a gloss');
+            const { resourceId: _old, ...rest } = card;
+            const next = {
+                ...(patch.resourceId === null ? rest : card),
+                ...(patch.term === undefined ? {} : { term: patch.term.trim() }),
+                ...(patch.gloss === undefined ? {} : { gloss: patch.gloss.trim() }),
+                ...(patch.userGloss === undefined ? {} : { userGloss: patch.userGloss.trim() }),
+                ...(patch.aliases === undefined ? {} : { aliases: patch.aliases.map(alias => alias.trim()).filter(alias => alias !== '') }),
+                ...(patch.status === undefined ? {} : { status: patch.status }),
+                ...(typeof patch.resourceId === 'string' ? { resourceId: patch.resourceId } : {}),
+                updatedAt: new Date().toISOString(),
+            };
+            this.store.writeCards(project.value.id, cards.map(candidate => candidate.id === card.id ? next : candidate));
+            this.event(project.value.id, 'card.edited', { id: card.id, title: next.term });
+            return { ok: true, card: next };
+        });
+    }
+    /**
+     * 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).
+     */
+    async undoCards(request) {
+        this.assertAlive('undoCards');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        return await this.mutate(project.value.id, () => {
+            const wanted = new Set(request.ids);
+            let removed = 0;
+            let reverted = 0;
+            const cards = this.store.readCards(project.value.id).map(card => {
+                if (!wanted.has(card.id))
+                    return card;
+                if (card.createdAt === request.at) {
+                    removed += 1;
+                    return { ...card, status: 'deleted', updatedAt: new Date().toISOString() };
+                }
+                const dropped = card.sources.filter(source => source.at === request.at);
+                if (dropped.length === 0)
+                    return card;
+                reverted += 1;
+                return {
+                    ...card,
+                    sources: card.sources.filter(source => source.at !== request.at),
+                    weakness: clampWeakness(card.weakness - dropped.filter(source => source.weakened === true).length),
+                    updatedAt: new Date().toISOString(),
+                };
+            });
+            this.store.writeCards(project.value.id, cards);
+            return { ok: true, removed, reverted };
+        });
+    }
+    /**
+     * 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.
+     */
+    async reviewCard(request) {
+        this.assertAlive('reviewCard');
+        if (!['forgot', 'fuzzy', 'recalled'].includes(request.rating))
+            return refuse('invalid', 'rating is forgot | fuzzy | recalled');
+        const project = this.readProjectOrRefusal(request.projectId);
+        if ('error' in project)
+            return project;
+        return await this.mutate(project.value.id, () => {
+            const cards = this.store.readCards(project.value.id);
+            const card = cards.find(candidate => candidate.id === request.cardId && live(candidate));
+            if (card === undefined)
+                return refuse('not-found', `no card ${JSON.stringify(request.cardId)}`);
+            const now = new Date();
+            const box = request.rating === 'forgot' ? 0 : request.rating === 'fuzzy' ? card.mastery.box : Math.min(card.mastery.box + 1, MAX_BOX);
+            const next = {
+                ...card,
+                mastery: {
+                    box,
+                    dueAt: leitnerDueAt(box, now),
+                    streak: request.rating === 'recalled' ? card.mastery.streak + 1 : 0,
+                },
+                updatedAt: now.toISOString(),
+            };
+            this.store.writeCards(project.value.id, cards.map(candidate => candidate.id === card.id ? next : candidate));
+            return { ok: true, card: next };
+        });
+    }
+}

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

@@ -0,0 +1,124 @@
+/**
+ * The library service core layer: the store, change listeners, disposal,
+ * the write boundary (`mutate`), the event ledger and the shared refusals.
+ *
+ * The service is ONE class split by domain into a chain of layers, each in
+ * its own file and each extending the one before:
+ *
+ *   core → shelf (projects, resources) → cards → roadmap (paths, notes,
+ *   读完) → pages → assess (quizzes, attempts) → bindings (bindings, events,
+ *   stats) = LibraryService
+ *
+ * A layer may call anything below it. The layering is organization only —
+ * `LibraryService` (service.ts re-exports it) is the one public class.
+ * Pure rules (shape validation, unlock, the evidence gate) live in
+ * `service/rules.ts`.
+ *
+ * @module @khorsheed/dsh-library/service/core
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type LibraryAttachmentRef, type LibraryCapabilities, type LibraryCard, type LibraryErrorCode, type LibraryEvent, type LibraryEventType, type LibraryOutcome, type LibraryProject, type LibraryRefusal } from '../types.ts';
+import { LibraryStore } from '../store.ts';
+export declare const PACKAGE_NAME = "@khorsheed/dsh-library";
+/** The attachment store's faces, mirrored structurally (probed, never injected). */
+export interface AttachmentsSlice {
+    readImage(ref: LibraryAttachmentRef): Promise<{
+        data: Uint8Array;
+        ref: {
+            mediaType: string;
+        };
+    }>;
+    saveImage?(input: {
+        data: Uint8Array;
+        mediaType: string;
+    }): Promise<LibraryAttachmentRef>;
+}
+/**
+ * Thrown by every public verb after {@link LibraryService.dispose} ran (an
+ * explicit teardown, or the borrowed Context's own disposal): a coded,
+ * package-named refusal, never a silent operation on a dead Context. The
+ * disposed instance stays dead — a rebuild over the same state root is a NEW
+ * service instance's business (the canvas-novel/sidechat precedent).
+ */
+export declare class LibraryDisposedError extends Error {
+    readonly code: 'disposed';
+    constructor(message: string, code: 'disposed');
+}
+/** A refusal in one line. */
+export declare function refuse(error: LibraryErrorCode, message: string): LibraryRefusal;
+/** Wrap a store failure as a refusal (the service's error channel is values). */
+export declare function storeRefusal(error: unknown): LibraryRefusal;
+/** The Leitner due date for a box: box b waits INTERVALS[min(b, 4)] days. */
+export declare function leitnerDueAt(box: number, from?: Date): string;
+/** Whitespace-normalize a quote before comparing it with a page's text. */
+export declare function normalizeFragment(value: string): string;
+/** Clamp a weakness score into 0..MAX. */
+export declare function clampWeakness(value: number): number;
+/** Live = not deleted. */
+export declare function live(card: LibraryCard): boolean;
+/**
+ * The library's service core. Constructing it never throws and never touches
+ * the disk: the store probes writability lazily, so a read-only deployment
+ * boots and answers `storage-unavailable` on writes. Disposal follows the
+ * borrowed Context: an instance mounted dynamically (per state root, say)
+ * dies with its mounting Context, and a dead instance refuses every verb
+ * coded, reads included.
+ */
+export declare class LibraryServiceCore {
+    protected readonly ctx: Context;
+    /** The store; public for the package's own tests and diagnostics. */
+    readonly store: LibraryStore;
+    /** Listeners told after every project mutation (the tab's live refresh, the context cache). */
+    protected readonly listeners: Set<(projectId: string) => void>;
+    /** When this instance last wrote anything (a project created, an index edit — writes that log no event). */
+    protected lastChangeAt: string | undefined;
+    /** The newest session-made write (a library tool from a session): the client's cue to reveal the sidebar. */
+    protected lastSessionWrite: {
+        readonly session: string;
+        readonly at: string;
+    } | undefined;
+    /** Set by {@link dispose} (explicit, or the borrowed Context's teardown); every public verb refuses afterwards. */
+    protected disposed: boolean;
+    constructor(ctx: Context, config?: {
+        stateRoot?: string;
+    });
+    /**
+     * Refuse one public verb after disposal: the instance is dead and nothing
+     * it could still answer is meant to be consumed — reads included, so a
+     * mounting side never keeps consuming a stale instance indefinitely.
+     */
+    protected assertAlive(verb: string): void;
+    /**
+     * Tear the instance down (also wired to the borrowed Context's disposal at
+     * construction). Idempotent and TERMINAL: the listener set is dropped and
+     * afterwards every public verb refuses with {@link LibraryDisposedError};
+     * a write that already passed the write boundary may complete (the store's
+     * lock/temp-write/atomic-rename keeps the disk side safe), one reaching it
+     * after disposal refuses before lock acquisition. A rebuild over the same
+     * state root is a NEW instance's business.
+     */
+    dispose(): void;
+    /**
+     * What a client may rely on in this composition: storage availability with
+     * its reason, and the attachment probe's verdict at call time. A read-only
+     * display contract — enforcement stays at the write gates, unchanged.
+     */
+    capabilities(): Promise<LibraryCapabilities>;
+    /** Subscribe to project mutations; returns the unsubscribe. */
+    onChange(listener: (projectId: string) => void): () => void;
+    protected changed(projectId: string): void;
+    /** Run a project mutation under its lock, then notify. */
+    protected mutate<T>(projectId: string, fn: () => Promise<LibraryOutcome<T>> | LibraryOutcome<T>): Promise<LibraryOutcome<T>>;
+    /** A library tool from this session just wrote (kit.autoBind calls it after every successful write). */
+    noteSessionWrite(session: string): void;
+    protected event(projectId: string, type: LibraryEventType, fields?: Omit<LibraryEvent, 'type' | 'at'> & {
+        at?: string;
+    }): void;
+    /** The project, or a not-found refusal that teaches where the list lives. */
+    protected readProjectOrRefusal(projectId: string): {
+        value: LibraryProject;
+    } | (LibraryRefusal & {
+        error: LibraryErrorCode;
+    });
+}
+//# sourceMappingURL=core.d.ts.map

package/lib/types/service/core.js

@@ -0,0 +1,169 @@
+import { LEITNER_INTERVAL_DAYS, libraryErrorMessage, MAX_WEAKNESS, } from "../types.js";
+import { LibraryStore, LibraryStoreError } from "../store.js";
+export const PACKAGE_NAME = '@khorsheed/dsh-library';
+/**
+ * Thrown by every public verb after {@link LibraryService.dispose} ran (an
+ * explicit teardown, or the borrowed Context's own disposal): a coded,
+ * package-named refusal, never a silent operation on a dead Context. The
+ * disposed instance stays dead — a rebuild over the same state root is a NEW
+ * service instance's business (the canvas-novel/sidechat precedent).
+ */
+export class LibraryDisposedError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'LibraryDisposedError';
+    }
+}
+/** A refusal in one line. */
+export function refuse(error, message) {
+    return { ok: false, error, message };
+}
+/** Wrap a store failure as a refusal (the service's error channel is values). */
+export function storeRefusal(error) {
+    if (error instanceof LibraryStoreError) {
+        const code = error.kind === 'corrupt' ? 'corrupt' : error.kind === 'unavailable' ? 'storage-unavailable' : 'io';
+        return refuse(code, error.message);
+    }
+    return refuse('io', `library: ${libraryErrorMessage(error)}`);
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The Leitner due date for a box: box b waits INTERVALS[min(b, 4)] days. */
+export function leitnerDueAt(box, from = new Date()) {
+    const days = LEITNER_INTERVAL_DAYS[Math.min(Math.max(box, 0), LEITNER_INTERVAL_DAYS.length - 1)];
+    return new Date(from.getTime() + days * DAY_MS).toISOString();
+}
+/** Whitespace-normalize a quote before comparing it with a page's text. */
+export function normalizeFragment(value) {
+    return value.normalize('NFKC').replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/** Clamp a weakness score into 0..MAX. */
+export function clampWeakness(value) {
+    return Math.min(Math.max(value, 0), MAX_WEAKNESS);
+}
+/** Live = not deleted. */
+export function live(card) {
+    return card.status !== 'deleted';
+}
+/**
+ * The library's service core. Constructing it never throws and never touches
+ * the disk: the store probes writability lazily, so a read-only deployment
+ * boots and answers `storage-unavailable` on writes. Disposal follows the
+ * borrowed Context: an instance mounted dynamically (per state root, say)
+ * dies with its mounting Context, and a dead instance refuses every verb
+ * coded, reads included.
+ */
+export class LibraryServiceCore {
+    ctx;
+    /** The store; public for the package's own tests and diagnostics. */
+    store;
+    /** Listeners told after every project mutation (the tab's live refresh, the context cache). */
+    listeners = new Set();
+    /** When this instance last wrote anything (a project created, an index edit — writes that log no event). */
+    lastChangeAt;
+    /** The newest session-made write (a library tool from a session): the client's cue to reveal the sidebar. */
+    lastSessionWrite;
+    /** Set by {@link dispose} (explicit, or the borrowed Context's teardown); every public verb refuses afterwards. */
+    disposed = false;
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.store = new LibraryStore(config);
+        // The borrowed Context's disposal IS this instance's disposal: an
+        // instance mounted per state root dies with its mounting Context instead
+        // of answering verbs off a dead scope.
+        ctx.effect(() => () => { this.dispose(); }, 'library: dispose on context teardown');
+    }
+    /**
+     * Refuse one public verb after disposal: the instance is dead and nothing
+     * it could still answer is meant to be consumed — reads included, so a
+     * mounting side never keeps consuming a stale instance indefinitely.
+     */
+    assertAlive(verb) {
+        if (this.disposed)
+            throw new LibraryDisposedError(`${PACKAGE_NAME}: ${verb} after dispose`, 'disposed');
+    }
+    /**
+     * Tear the instance down (also wired to the borrowed Context's disposal at
+     * construction). Idempotent and TERMINAL: the listener set is dropped and
+     * afterwards every public verb refuses with {@link LibraryDisposedError};
+     * a write that already passed the write boundary may complete (the store's
+     * lock/temp-write/atomic-rename keeps the disk side safe), one reaching it
+     * after disposal refuses before lock acquisition. A rebuild over the same
+     * state root is a NEW instance's business.
+     */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    /**
+     * What a client may rely on in this composition: storage availability with
+     * its reason, and the attachment probe's verdict at call time. A read-only
+     * display contract — enforcement stays at the write gates, unchanged.
+     */
+    async capabilities() {
+        this.assertAlive('capabilities');
+        return {
+            protocolVersion: 1,
+            hasStorage: this.store.available,
+            ...(this.store.unavailableReason === undefined ? {} : { storageUnavailableReason: this.store.unavailableReason }),
+            hasAttachments: this.ctx.get('attachments') !== undefined,
+        };
+    }
+    /** Subscribe to project mutations; returns the unsubscribe. */
+    onChange(listener) {
+        this.assertAlive('onChange');
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    changed(projectId) {
+        this.lastChangeAt = new Date().toISOString();
+        for (const listener of this.listeners) {
+            try {
+                listener(projectId);
+            }
+            catch {
+                // A listener's failure is its own.
+            }
+        }
+    }
+    /** Run a project mutation under its lock, then notify. */
+    async mutate(projectId, fn) {
+        // The write boundary: a disposal that landed since the entry guard dies
+        // here, BEFORE the lock is taken — never queuing onto a lock a rebuilt
+        // instance on the same root now owns (kept outside the try, so the coded
+        // refusal propagates as itself rather than folding into a store refusal).
+        this.assertAlive('mutate');
+        try {
+            const outcome = await this.store.withProjectLock(projectId, fn);
+            if (outcome.ok)
+                this.changed(projectId);
+            return outcome;
+        }
+        catch (error) {
+            return storeRefusal(error);
+        }
+    }
+    /** A library tool from this session just wrote (kit.autoBind calls it after every successful write). */
+    noteSessionWrite(session) {
+        this.lastSessionWrite = { session, at: new Date().toISOString() };
+    }
+    event(projectId, type, fields = {}) {
+        this.store.appendEvents(projectId, [{ at: fields.at ?? new Date().toISOString(), type, ...fields }]);
+    }
+    /* -------------------------------------------------------------- helpers */
+    /** The project, or a not-found refusal that teaches where the list lives. */
+    readProjectOrRefusal(projectId) {
+        let project;
+        try {
+            project = this.store.readProject(projectId);
+        }
+        catch (error) {
+            return storeRefusal(error);
+        }
+        if (project === undefined) {
+            return refuse('not-found', `no project ${JSON.stringify(projectId)} — library_read · projects lists every project; create one with library_project`);
+        }
+        return { value: project };
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * 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 { type LibraryAttachmentRef, type LibraryCardWriteResult, type LibraryMark, type LibraryOutcome, type LibraryPage } from '../types.ts';
+import { LibraryServiceRoadmap } from './roadmap.ts';
+export declare class LibraryServicePages extends LibraryServiceRoadmap {
+    /**
+     * 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.
+     */
+    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[];
+    }>>;
+    /** One resource's pages, optionally one node's. */
+    listPages(request: {
+        projectId: string;
+        resourceId: string;
+        nodeId?: string;
+    }): Promise<{
+        pages: LibraryPage[];
+    }>;
+    /** Find one page anywhere in the project. */
+    protected findPage(projectId: string, pageId: string): LibraryPage | undefined;
+    /**
+     * One page's photo, as base64 — whitelisted: the page must be one this
+     * project recorded, so the Remote never reads an arbitrary attachment.
+     */
+    readPagePhoto(request: {
+        projectId: string;
+        pageId: string;
+    }): Promise<LibraryOutcome<{
+        data: string;
+        mediaType: string;
+    }>>;
+    /** Save a browser-uploaded photo into the host attachment store (the sidebar's 拍照). */
+    savePhoto(request: {
+        data: string;
+        mediaType: string;
+    }): Promise<LibraryOutcome<{
+        attachment: LibraryAttachmentRef;
+    }>>;
+}
+//# sourceMappingURL=pages.d.ts.map