@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/types/store.d.ts

@@ -0,0 +1,257 @@
+import { type LibraryAssessment, type LibraryAttachmentRef, type LibraryAttempt, type LibraryBinding, type LibraryCard, type LibraryEvent, type LibraryNodeCover, type LibraryPage, type LibraryProject, type LibraryResource, type LibraryRoadmap } from './types.ts';
+/** A store failure that the service maps onto a refusal. */
+export declare class LibraryStoreError extends Error {
+    readonly kind: 'io' | 'corrupt' | 'unavailable';
+    constructor(message: string, kind: 'io' | 'corrupt' | 'unavailable');
+}
+/** Assert an id is usable as a path segment (no traversal, no separators). */
+export declare function assertLibraryId(id: string, what: string): void;
+/** Mint a store id: a readable prefix plus time-and-random uniqueness. */
+export declare function mintLibraryId(prefix: string): string;
+/** A held lock; `release` is idempotent. */
+export interface LibraryLock {
+    release(): void;
+}
+/** Acquire the lock file, waiting out live owners and reclaiming stale ones. */
+export declare function acquireLibraryLock(lockPath: string): Promise<LibraryLock>;
+/** `state.json`: the version-guarded index of projects. */
+export interface LibraryIndexDoc {
+    readonly version: number;
+    readonly projects: readonly LibraryProject[];
+}
+/** The empty index. */
+export declare function emptyLibraryIndex(): LibraryIndexDoc;
+/**
+ * Coerce a parsed value into an index. A version this store does not
+ * recognize reads as empty — v2 through v5 all read tolerantly (every entity
+ * normalize accepts the older shapes; `migrateState` still rewrites v2
+ * chapterRanges into covers).
+ */
+export declare function normalizeLibraryIndex(value: unknown): LibraryIndexDoc;
+/** One project, when it carries the fields that make it one. */
+export declare function normalizeProject(value: unknown): LibraryProject | undefined;
+/**
+ * One shelf entry, when it parses. Reads BOTH layouts: a v5
+ * `resources/<id>.json` (kind may be 'book', toc/meta live at the top) and a
+ * legacy one — a `books/<id>/book.json` (kind forced to 'book', book-ish
+ * fields folded into meta) or a `resources.jsonl` line (a thin link).
+ */
+export declare function normalizeResource(value: unknown): LibraryResource | undefined;
+/**
+ * The shelf's reading order: textbooks (thick) before thin links; textbooks
+ * by `seq`, unnumbered ones after the numbered, ties by age; links by age.
+ */
+export declare function shelfOrder(a: LibraryResource, b: LibraryResource): number;
+/**
+ * One node's cover, when it parses. Reads the v5 shape (`{ ref, locator? }`)
+ * and every legacy union member: `{ kind: 'book', bookId, ranges }`,
+ * `{ kind: 'resource', resourceId }`, `{ kind: 'url', url, title? }`,
+ * `{ kind: 'topic', text }`. Provenance rides along when present.
+ */
+export declare function normalizeNodeCover(value: unknown): LibraryNodeCover | undefined;
+/** One roadmap (adopted or draft), when it parses; rule checks live in the service. */
+export declare function normalizeRoadmap(value: unknown): LibraryRoadmap | undefined;
+/** An attachment reference, when every durable field is present. */
+export declare function normalizeAttachmentRef(value: unknown): LibraryAttachmentRef | undefined;
+/** One photographed page (one pages/<resourceId>.jsonl line), when it parses. */
+export declare function normalizePage(value: unknown): LibraryPage | undefined;
+/** One knowledge card (one cards.jsonl line), when it parses. */
+export declare function normalizeCard(value: unknown): LibraryCard | undefined;
+/**
+ * Options arrive as plain strings, as { label } objects, or letter-keyed maps —
+ * the stored form is always plain strings, letter prefixes ("A) ") stripped
+ * (the answering UI badges the letter itself).
+ */
+export declare function normalizeQuizOptions(value: unknown): string[] | undefined;
+/**
+ * One assessment, when it parses. Reads BOTH shapes: a v5
+ * `assessments/<id>.json` (type quiz | practice, scope.resourceId) and a
+ * legacy `quizzes/<id>.json` (a quiz — scope.bookId folds into resourceId).
+ */
+export declare function normalizeAssessment(value: unknown): LibraryAssessment | undefined;
+/** One attempt (one attempts.jsonl line), when it parses. */
+export declare function normalizeAttempt(value: unknown): LibraryAttempt | undefined;
+/** One audit event (one events.jsonl line), when it parses. */
+export declare function normalizeEvent(value: unknown): LibraryEvent | undefined;
+/** The bindings map, dropping rows that do not parse. */
+export declare function normalizeBindings(value: unknown): Map<string, LibraryBinding>;
+/**
+ * The native-fs library store. Reads never lock (a read observes one committed
+ * revision, never a partial one — writes are atomic renames); writes serialize
+ * on a per-project lock (`projects/<id>.lock`), the index and the bindings on
+ * their own.
+ */
+export declare class LibraryStore {
+    private readonly stateRoot;
+    /** Set once the root has proven unwritable; reads then degrade to empty. */
+    private unwritable;
+    /**
+     * @param config - optional state-root override (tests, deployments that keep
+     *   state elsewhere).
+     */
+    constructor(config?: {
+        stateRoot?: string;
+    });
+    /** The state root (diagnostics and tests). */
+    get root(): string;
+    /** Why persistence is unavailable, when it is. */
+    get unavailableReason(): string | undefined;
+    /**
+     * Whether persistence is available — probed by creating the root, because a
+     * read-only deployment is only knowable by trying.
+     */
+    get available(): boolean;
+    private get indexFile();
+    private get bindingsFile();
+    private get projectsDir();
+    /** One project's directory. */
+    projectDir(projectId: string): string;
+    /** The v5 resource file. */
+    private resourceFile;
+    /** The legacy per-book directory (v3/v4 layout — read-only now). */
+    private legacyBookDir;
+    private cardsFile;
+    /** The legacy thin-links ledger (v3/v4 layout — read-only now). */
+    private legacyResourcesFile;
+    private attemptsFile;
+    private eventsFile;
+    /** The v5 assessment file. */
+    private assessmentFile;
+    /** The legacy quiz file (v3/v4 layout — read-only now). */
+    private legacyQuizFile;
+    /** The v5 roadmap file, keyed by its textbook. */
+    private roadmapFile;
+    /** The legacy per-book roadmap file (v3/v4 layout — read-only now). */
+    private legacyRoadmapFile;
+    /** The v5 pages ledger of one thick resource. */
+    /** notes/<resource>/<node>.md — or <node>.<n>.md, the Nth revision kept before a rewrite. */
+    private notesFile;
+    private pagesFile;
+    /** The per-project lock's path. */
+    private projectLock;
+    /** Serialize under the scope's lock: read-modify-write as one critical section. */
+    withProjectLock<T>(projectId: string, fn: () => Promise<T> | T): Promise<T>;
+    /** The index's own lock (project create/delete). */
+    withIndexLock<T>(fn: () => Promise<T> | T): Promise<T>;
+    /** The bindings' own lock. */
+    withBindingsLock<T>(fn: () => Promise<T> | T): Promise<T>;
+    private withRootLock;
+    /**
+     * Read and normalize one JSON document.
+     *
+     * @returns undefined when the file is absent; throws `corrupt` when it
+     *   exists but does not parse (a hand-edited file stays visible rather than
+     *   being silently clobbered).
+     */
+    private readJsonFile;
+    /** Write one document atomically (temp file + rename). */
+    private writeJsonFile;
+    /** Write one text file atomically. */
+    private writeTextFile;
+    /** Append lines to one JSONL ledger (append-only: never a rewrite). */
+    private appendJsonlFile;
+    /** Read one JSONL ledger tolerantly: unparseable lines drop, never fail the read. */
+    private readJsonlFile;
+    /** The index; absent reads as empty, an unavailable root as empty. */
+    readIndex(): LibraryIndexDoc;
+    /** The session bindings; absent or unreadable reads as empty. */
+    readBindings(): Map<string, LibraryBinding>;
+    /** One project's record; undefined when absent. */
+    readProject(projectId: string): LibraryProject | undefined;
+    private projectFile;
+    /**
+     * One shelf entry; undefined when absent. The v5 file wins; the legacy
+     * spots follow (a book's `books/<id>/book.json`, then a thin link's
+     * resources.jsonl line).
+     */
+    readResource(projectId: string, resourceId: string): LibraryResource | undefined;
+    /**
+     * Every shelf entry of one project, both layouts merged (a v5 file shadows
+     * a legacy twin of the same id): textbooks first in study order (`seq`,
+     * then age — an unnumbered legacy textbook queues behind the numbered
+     * ones), then thin links oldest first.
+     */
+    listResources(projectId: string): LibraryResource[];
+    /**
+     * One textbook's adopted roadmap, or its draft. The v5 file wins; the
+     * legacy book directory follows. A retired project-level path (no
+     * resource) reads as absent.
+     */
+    readRoadmap(projectId: string, resourceId: string | undefined, which?: 'adopted' | 'draft'): LibraryRoadmap | undefined;
+    /** A path with each station's 讲义 text read from its file (a node whose file is gone loses its notes). */
+    private withNotes;
+    /** One station's 讲义 markdown, when written. */
+    readNotes(projectId: string, resourceId: string, nodeId: string): string | undefined;
+    /** Keep the current 讲义 of a station as revision N before a rewrite (call inside `withProjectLock`). */
+    archiveNotes(projectId: string, resourceId: string, nodeId: string, revision: number, text: string): void;
+    /**
+     * One thick resource's photographed pages, oldest first — both layouts
+     * merged: pages recorded before the v5 write cutover stay in the legacy
+     * book directory, new ones append to `pages/<id>.jsonl`.
+     */
+    readPages(projectId: string, resourceId: string): LibraryPage[];
+    /** Every knowledge card of one project (deleted ones included — callers filter). */
+    readCards(projectId: string): LibraryCard[];
+    /** Every attempt (the JSONL ledger, tolerant per line). */
+    readAttempts(projectId: string): LibraryAttempt[];
+    /** The audit ledger, oldest first. */
+    readEvents(projectId: string): LibraryEvent[];
+    /**
+     * One assessment; undefined when absent. The v5 file wins; a legacy quiz
+     * file (`quizzes/<id>.json`) reads as a type=quiz assessment.
+     */
+    readAssessment(projectId: string, assessmentId: string): LibraryAssessment | undefined;
+    /** Every assessment of one project, oldest first, both layouts merged. */
+    listAssessments(projectId: string): LibraryAssessment[];
+    /** Write the index (call inside `withIndexLock`). */
+    writeIndex(doc: LibraryIndexDoc): void;
+    /** Write the bindings (call inside `withBindingsLock`). */
+    writeBindings(bindings: ReadonlyMap<string, LibraryBinding>): void;
+    /** Write one project's record (call inside `withProjectLock`). */
+    writeProject(project: LibraryProject): void;
+    /** Write one shelf entry (call inside `withProjectLock`) — the v5 layout. */
+    writeResource(projectId: string, resource: LibraryResource): void;
+    /** Write one textbook's adopted roadmap or its draft (call inside `withProjectLock`) — the v5 layout. */
+    writeRoadmap(projectId: string, roadmap: LibraryRoadmap): void;
+    /** Drop one textbook's draft (adopted or discarded), in BOTH layouts. */
+    removeDraft(projectId: string, resourceId: string): void;
+    /** Append one photographed page (call inside `withProjectLock`) — the v5 layout. */
+    appendPage(projectId: string, page: LibraryPage): void;
+    /**
+     * Rewrite the cards whole — a merge or a mastery move rewrites an existing
+     * line. The temp+rename keeps the swap atomic; the project lock serializes it.
+     */
+    writeCards(projectId: string, cards: readonly LibraryCard[]): void;
+    /** Append one attempt (call inside `withProjectLock`). */
+    appendAttempt(projectId: string, attempt: LibraryAttempt): void;
+    /** Append audit events (call inside `withProjectLock`). */
+    appendEvents(projectId: string, events: readonly LibraryEvent[]): void;
+    /** Write one assessment (call inside `withProjectLock`) — the v5 layout. */
+    writeAssessment(projectId: string, assessment: LibraryAssessment): void;
+    /**
+     * Remove one shelf entry: the v5 file, its pages ledger, its roadmap files,
+     * and any legacy trace (the book directory, the resources.jsonl line).
+     */
+    removeResource(projectId: string, resourceId: string): void;
+    /** Remove one project's whole directory. */
+    removeProject(projectId: string): void;
+    /**
+     * v2 → covers: wrap every stored roadmap node's `chapterRanges` into a book
+     * cover (the v2 paths are all per-book). Idempotent, each project's files
+     * rewritten under its own lock, the index bump last — a crash midway leaves
+     * the old version and the next run resumes. v1 roots were never deployed:
+     * they read as empty and are NOT migrated. Reads never wait for this pass —
+     * `normalizeRoadmap` wraps a v2 node on the fly.
+     *
+     * @returns whether a migration ran.
+     */
+    migrateState(): Promise<boolean>;
+    /** Rewrite one project's v2 book roadmaps (adopted and draft) into covers. */
+    private migrateProjectRoadmapsV2;
+}
+/**
+ * Resolve the state root: an explicit config value wins, then
+ * `$DSH_HOME/state/dsh-library`, then `<cwd>/.dsh-library`.
+ */
+export declare function resolveLibraryStateRoot(configured: string | undefined): string;
+//# sourceMappingURL=store.d.ts.map