@khorsheed/dsh-library 0.0.0-stage → 0.1.0

package/lib/store-DfYOmS44.js

@@ -0,0 +1,1418 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region lib/types/types.js
+/**
+* The library's domain vocabulary: projects, resources, roadmaps, nodes,
+* assessments, attempts, photo pages, knowledge cards and session bindings.
+* Everything here is plain serializable data — the store (`store.ts`)
+* persists exactly these shapes under `$DSH_HOME/state/dsh-library/`, and the
+* Remote face (`remote.ts`) and the model tools (`tool-definition.ts`) both
+* speak them.
+*
+* The shapes follow the proposal `2026-10-16-library-v5-model` (v5: the
+* six-layer core — Project → Resource → Roadmap → Node → Assessment →
+* Attempt, with Card / Page / Event as the trace layer):
+*
+* - a RESOURCE is anything on the project's shelf. Its `toc` is the
+*   thick/thin switch: a resource WITH a contents (a book, a course with
+*   episodes) can carry a roadmap, be covered by chapter, be quizzed and be
+*   photographed; one without is a thin link (an article, a video, a tool)
+*   that only enters a path whole. Nothing is ever uploaded — a thick
+*   resource registers title, kind and a contents the coach verified on the
+*   web (or took from a photo);
+* - a ROADMAP is one path per scope: `primaryResourceId` present = that thick
+*   resource's own path (every node covers that one resource); absent = the
+*   project's own path (the general case, mixing covers freely). A node draws
+*   on mixed COVERS in one shape — `{ ref, locator? }`, where ref is a
+*   resource id, a bare url, or `topic:…` (plain coached teaching) and
+*   locator counts contents rows ("1-5,7"). The coach writes DRAFTS, the
+*   learner adopts one, and the adopted path's state machine has three edges
+*   only (`locked → current → done`);
+* - a NODE's `gate` says how it completes: `quiz` (an assessed quiz at the
+*   pass ratio), `acceptance` (a hands-on station — the learner submits
+*   evidence, the coach judges one verdict per rubric line), `read` (an
+*   optional side stop that 「读完」 completes and never gates);
+* - an ASSESSMENT is the graded thing: `quiz` carries questions, `practice`
+*   carries a station's materialized rubric (stable line ids; a line may
+*   reference another assessment that machine-checks it). Hung on a node, on
+*   a resource (a book-level paper), or on nothing (free practice). A
+*   station's paper history chains by `supersededBy`;
+* - an ATTEMPT is one graded sitting and names only its `assessmentId` (a
+*   verdict's `task` is a question id or a rubric line id, so rewording never
+*   orphans history);
+* - a PAGE is one photographed page of a thick resource: its recognized text
+*   plus the learner's marks;
+* - a CARD (知识卡片) is the learner's own memory: a word or a concept met in a
+*   photo, asked about in a chat, or missed in an assessment — one card per
+*   thing, sources stacked, with a weakness score (0–3) beside its Leitner
+*   mastery;
+* - an EVENT is the append-only audit trail.
+*
+* @module @khorsheed/dsh-library/types
+*/
+/** The state-root directory name under `$DSH_HOME/state`. */
+const STATE_ROOT_SEGMENT = "dsh-library";
+/**
+* The on-disk schema version of `state.json`. v1 (uploaded books, project
+* roadmaps, the vocab book) was never deployed; a v1 root reads as empty. v2
+* roots (per-book roadmaps with `chapterRanges`) and v3/v4 roots (the
+* book/resource split, cover unions, quiz entities) all read tolerantly —
+* every normalize* function reads the old shapes — and rewrite to v5 on their
+* next write. There is no offline migration pass.
+*/
+const LIBRARY_STATE_VERSION = 5;
+/** The Leitner intervals in days, indexed by box (box 5 reuses the last rung). */
+const LEITNER_INTERVAL_DAYS = [
+	1,
+	2,
+	4,
+	7,
+	15
+];
+/** The highest Leitner box. */
+const MAX_BOX = 5;
+/** The highest weakness score (three bars in the UI). */
+const MAX_WEAKNESS = 3;
+/** The default node pass threshold (an assessment ratio at or above it completes the node). */
+const DEFAULT_PASS_RATIO = .8;
+/** The preset project colors (the sidebar maps each to a light and a dark tone). */
+const LIBRARY_COLORS = [
+	"ember",
+	"amber",
+	"moss",
+	"teal",
+	"sky",
+	"indigo",
+	"plum",
+	"rose"
+];
+/** The preset project icons. */
+const LIBRARY_ICONS = [
+	"globe",
+	"brain",
+	"book",
+	"flask",
+	"atom",
+	"leaf",
+	"pen",
+	"music",
+	"scale",
+	"chart",
+	"code",
+	"compass"
+];
+/** A template's default look, until the learner picks another. */
+const TEMPLATE_LOOK = {
+	language: {
+		color: "ember",
+		icon: "globe"
+	},
+	subject: {
+		color: "indigo",
+		icon: "brain"
+	},
+	custom: {
+		color: "teal",
+		icon: "compass"
+	}
+};
+/** What a shelf entry IS: the shape of the thing it is or points at. */
+const LIBRARY_RESOURCE_KINDS = [
+	"book",
+	"article",
+	"video",
+	"repo",
+	"tool",
+	"course",
+	"hardware"
+];
+/** Whether a resource is thick (routable, coverable by chapter, quizzable, photographable). */
+function isThickResource(resource) {
+	return resource.toc !== void 0 && resource.toc.length > 0;
+}
+/**
+* The locator's text form: comma-joined spans ("1-5,7,9-12" — a one-row span
+* is the bare number). Contents-row spans are what cover locators count.
+*/
+function formatLocator(ranges) {
+	return ranges.map((range) => range.from === range.to ? String(range.from) : `${range.from}-${range.to}`).join(",");
+}
+/** Parse a locator ("1-5,7") into spans; bad segments drop out. */
+function parseLocator(locator) {
+	return locator.split(",").flatMap((segment) => {
+		const match = /^\s*(\d+)\s*(?:[-–—]\s*(\d+)\s*)?$/.exec(segment);
+		if (match === null) return [];
+		const from = Number.parseInt(match[1], 10);
+		const to = match[2] === void 0 ? from : Number.parseInt(match[2], 10);
+		return from >= 1 && to >= from ? [{
+			from,
+			to
+		}] : [];
+	});
+}
+/** Discriminate a cover by its ref's form (a resource id resolves against the shelf). */
+function coverKind(cover) {
+	if (cover.ref.startsWith("topic:")) return "topic";
+	if (/^https?:\/\//.test(cover.ref)) return "url";
+	return "resource";
+}
+/** A topic cover's teaching text (the ref minus its `topic:` prefix). */
+function coverTopic(cover) {
+	return cover.ref.startsWith("topic:") ? cover.ref.slice(6) : void 0;
+}
+/** An acceptance station's rubric: its acceptance lines with stable positional ids (L1, L2, …). */
+function acceptanceLines(node) {
+	return (node.acceptance ?? []).map((entry, index) => typeof entry === "string" ? {
+		id: `L${index + 1}`,
+		line: entry
+	} : {
+		id: `L${index + 1}`,
+		line: entry.line,
+		...entry.ref === void 0 ? {} : { ref: entry.ref }
+	});
+}
+/** The event vocabulary, for tests and for writers who must not invent types. */
+const LIBRARY_EVENT_TYPES = [
+	"resource.added",
+	"roadmap.drafted",
+	"roadmap.adopted",
+	"page.recorded",
+	"cards.recorded",
+	"card.edited",
+	"quiz.created",
+	"attempt.assessed",
+	"node.completed",
+	"node.unlocked",
+	"node.noted"
+];
+/** Ids become path segments — keep them inside a safe alphabet (mission rule). */
+const LIBRARY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Whether an id is usable as a path segment. */
+function isLibraryId(id) {
+	return LIBRARY_ID_PATTERN.test(id);
+}
+/** A native fs failure's message, with its code, for the wire. */
+function libraryErrorMessage(error) {
+	const code = error?.code;
+	const message = error instanceof Error ? error.message : String(error);
+	return code === void 0 ? message : `${code}: ${message}`;
+}
+//#endregion
+//#region lib/types/store.js
+/**
+* The host-side state store: a version-guarded index (`state.json`), the
+* session bindings (`bindings.json`), and one directory per project under
+* `$DSH_HOME/state/dsh-library/`:
+*
+* ```
+* state.json                          # version-guarded index (project list)
+* bindings.json                       # sessionId → { projectId, resourceId? }
+* projects/<projectId>/
+*   project.json                      # { id, name, template, goal?, createdAt }
+*   resources/<resourceId>.json       # shelf entries, thick (toc) and thin
+*   pages/<resourceId>.jsonl          # a thick resource's photographed pages, append-only
+*   roadmaps/<key>.json               # the adopted path; key = resourceId | "project"
+*   roadmaps/<key>.draft.json         # the coach's draft, until 采用
+*   assessments/<assessmentId>.json   # quizzes and materialized practice rubrics
+*   cards.jsonl                       # knowledge cards (rewritten whole on update)
+*   attempts.jsonl                    # append-only
+*   events.jsonl                      # append-only audit trail
+* ```
+*
+* **Read-old, write-new (v5).** The v3/v4 layout — `books/<bookId>/book.json`
+* + `roadmap.json` + `pages.jsonl`, `resources.jsonl`, `quizzes/<id>.json`,
+* and the project's root `roadmap.json` — is never written any more but
+* always READ: every reader merges or falls back to the legacy spot, every
+* normalize* function accepts the legacy field names (`bookId`, node `kind`,
+* cover unions, `quizId`). Legacy files stay in place (a rollback loses
+* nothing); the next write of an entity lands in the new layout. v2 roots
+* (per-book roadmaps with `chapterRanges`) still normalize on the fly, and
+* `migrateState` rewrites them into the covers shape as before.
+*
+* The write discipline is the mission store's (the in-repo precedent for
+* shared JSON state): every mutation funnels through a per-scope lock → read →
+* modify → temp-write → atomic rename; the JSONL ledgers are append-only
+* (an `O_APPEND` write under the same lock); ids are path segments and pass
+* the safe-alphabet check before they join a path. The lock is hand-rolled
+* (exclusive-create of a `.lock` file carrying `{pid, at}`; a dead or ancient
+* owner is reclaimed) — no dependency, replaceable without touching the data
+* model.
+*
+* **Why plain `node:fs` and not `ctx.fs`** — the reader's lesson: `ctx.fs` is
+* the session-fenced sandbox, and a workspace-write session refuses writes to
+* `$DSH_HOME/state`; this state belongs to the DEPLOYMENT.
+*
+* An unwritable root degrades reads to empty and refuses writes with
+* `storage-unavailable` — a composition must never fail for lack of a disk.
+*
+* @module @khorsheed/dsh-library/store
+*/
+/** A store failure that the service maps onto a refusal. */
+var LibraryStoreError = class extends Error {
+	kind;
+	constructor(message, kind) {
+		super(message);
+		this.kind = kind;
+		this.name = "LibraryStoreError";
+	}
+};
+/** Assert an id is usable as a path segment (no traversal, no separators). */
+function assertLibraryId(id, what) {
+	if (!isLibraryId(id)) throw new LibraryStoreError(`library: ${what} ${JSON.stringify(id)} is not a usable id (allowed: letters, digits, '.', '_', '-')`, "io");
+}
+/** Mint a store id: a readable prefix plus time-and-random uniqueness. */
+function mintLibraryId(prefix) {
+	return `${prefix}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+const LOCK_TIMEOUT_MS = 1e4;
+const LOCK_STALE_MS = 6e4;
+/** A lock file younger than this but not yet parseable is a writer mid-create — wait, don't reclaim. */
+const LOCK_GRACE_MS = 5e3;
+async function sleep(ms) {
+	await new Promise((resolvePromise) => {
+		setTimeout(resolvePromise, ms);
+	});
+}
+function lockIsStale(lockPath) {
+	let raw;
+	try {
+		raw = readFileSync(lockPath, "utf8");
+	} catch {
+		return false;
+	}
+	let pid;
+	let at;
+	try {
+		const info = JSON.parse(raw);
+		if (typeof info.pid === "number") pid = info.pid;
+		if (typeof info.at === "number") at = info.at;
+	} catch {
+		try {
+			return Date.now() - statSync(lockPath).mtimeMs > LOCK_GRACE_MS;
+		} catch {
+			return false;
+		}
+	}
+	if (at !== void 0 && Date.now() - at > LOCK_STALE_MS) return true;
+	if (pid === void 0) return false;
+	try {
+		process.kill(pid, 0);
+		return false;
+	} catch {
+		return true;
+	}
+}
+/** Acquire the lock file, waiting out live owners and reclaiming stale ones. */
+async function acquireLibraryLock(lockPath) {
+	const deadline = Date.now() + LOCK_TIMEOUT_MS;
+	for (;;) try {
+		const fd = openSync(lockPath, "wx");
+		try {
+			writeFileSync(fd, `${JSON.stringify({
+				pid: process.pid,
+				at: Date.now()
+			})}\n`);
+		} finally {
+			closeSync(fd);
+		}
+		let released = false;
+		return { release() {
+			if (released) return;
+			released = true;
+			try {
+				unlinkSync(lockPath);
+			} catch {}
+		} };
+	} catch (error) {
+		if (error?.code !== "EEXIST") throw error;
+		if (lockIsStale(lockPath)) {
+			try {
+				unlinkSync(lockPath);
+			} catch {}
+			continue;
+		}
+		if (Date.now() > deadline) throw new LibraryStoreError(`library: timed out waiting for the lock ${lockPath}`, "io");
+		await sleep(15 + Math.random() * 35);
+	}
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** A trimmed, length-capped string, or undefined when absent / empty. */
+function text(value, max) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed.slice(0, max);
+}
+function id(value) {
+	return typeof value === "string" && isLibraryId(value) ? value : void 0;
+}
+function finite(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stamp(value) {
+	return typeof value === "string" ? value : (/* @__PURE__ */ new Date(0)).toISOString();
+}
+function strings(value, max) {
+	return Array.isArray(value) ? value.flatMap((item) => {
+		const s = text(item, max);
+		return s === void 0 ? [] : [s];
+	}) : [];
+}
+/** Acceptance lines: bare strings pass through; { line, ref? } objects normalize. */
+function acceptanceEntries(value) {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((entry) => {
+		if (typeof entry === "string") {
+			const line = text(entry, 300);
+			return line === void 0 ? [] : [line];
+		}
+		const record = asRecord(entry);
+		const line = text(record?.line, 300);
+		if (record === void 0 || line === void 0) return [];
+		return [{
+			line,
+			...opt("ref", text(record.ref, 100))
+		}];
+	});
+}
+/** Spread `{ [key]: value }` only when value is defined. */
+function opt(key, value) {
+	return value === void 0 ? {} : { [key]: value };
+}
+/** The empty index. */
+function emptyLibraryIndex() {
+	return {
+		version: 5,
+		projects: []
+	};
+}
+/**
+* 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).
+*/
+function normalizeLibraryIndex(value) {
+	const record = asRecord(value);
+	const version = finite(record?.version);
+	if (record === void 0 || version === void 0 || version < 2 || version > 5) return emptyLibraryIndex();
+	const projects = Array.isArray(record.projects) ? record.projects : [];
+	const seen = /* @__PURE__ */ new Set();
+	return {
+		version: 5,
+		projects: projects.flatMap((item) => {
+			const project = normalizeProject(item);
+			if (project === void 0 || seen.has(project.id)) return [];
+			seen.add(project.id);
+			return [project];
+		})
+	};
+}
+/** One project, when it carries the fields that make it one. */
+function normalizeProject(value) {
+	const record = asRecord(value);
+	const projectId = id(record?.id);
+	const name = text(record?.name, 200);
+	if (record === void 0 || projectId === void 0 || name === void 0) return void 0;
+	return {
+		id: projectId,
+		name,
+		template: record.template === "language" || record.template === "custom" ? record.template : "subject",
+		...opt("color", LIBRARY_COLORS.find((color) => color === record.color)),
+		...opt("icon", LIBRARY_ICONS.find((icon) => icon === record.icon)),
+		...opt("templateNote", text(record.templateNote, 500)),
+		...opt("goal", text(record.goal, 500)),
+		createdAt: stamp(record.createdAt)
+	};
+}
+/** One table-of-contents list, re-numbered 1-based, when any row parses. */
+function tocEntries(value) {
+	if (!Array.isArray(value)) return void 0;
+	return value.flatMap((item) => {
+		const entry = asRecord(item);
+		const entryTitle = text(entry?.title, 300);
+		if (entryTitle === void 0) return [];
+		return [{
+			title: entryTitle,
+			...opt("part", text(entry?.part, 200))
+		}];
+	}).map((entry, index) => ({
+		...entry,
+		n: index + 1
+	}));
+}
+/** The extras strip (开始前 / 附录), when any row parses. */
+function extraEntries(value) {
+	if (!Array.isArray(value)) return void 0;
+	return value.flatMap((item) => {
+		const extra = asRecord(item);
+		const extraTitle = text(extra?.title, 200);
+		if (extra === void 0 || extraTitle === void 0) return [];
+		return [{
+			title: extraTitle,
+			...opt("note", text(extra.note, 300)),
+			...opt("where", text(extra.where, 60)),
+			when: extra.when === "reference" ? "reference" : "before"
+		}];
+	});
+}
+/**
+* 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).
+*/
+function normalizeResource(value) {
+	const record = asRecord(value);
+	const resourceId = id(record?.id);
+	const title = text(record?.title, 300);
+	if (record === void 0 || resourceId === void 0 || title === void 0) return void 0;
+	const legacyBook = Array.isArray(record.toc) || record.bookKind !== void 0;
+	const kind = legacyBook ? "book" : LIBRARY_RESOURCE_KINDS.find((kind) => kind === record.kind) ?? "article";
+	const toc = tocEntries(record.toc);
+	const source = asRecord(record.tocSource);
+	const metaRecord = asRecord(record.meta);
+	const meta = (() => {
+		const bookKind = (metaRecord?.bookKind ?? record.bookKind) === "material" ? "material" : (metaRecord?.bookKind ?? record.bookKind) === "knowledge" ? "knowledge" : void 0;
+		const extras = extraEntries(metaRecord?.extras ?? record.extras);
+		const merged = {
+			...opt("bookKind", bookKind),
+			...opt("short", text(metaRecord?.short ?? record.short, 8)),
+			...extras !== void 0 && extras.length > 0 ? { extras } : {},
+			...opt("author", text(metaRecord?.author ?? record.author, 200)),
+			...opt("edition", text(metaRecord?.edition ?? record.edition, 100)),
+			...opt("isbn", text(metaRecord?.isbn ?? record.isbn, 40))
+		};
+		return Object.keys(merged).length === 0 ? void 0 : merged;
+	})();
+	return {
+		id: resourceId,
+		title,
+		kind,
+		...opt("url", text(record.url, 1e3)),
+		...opt("note", text(record.note, 300)),
+		...opt("addedBy", record.addedBy === "learner" ? "learner" : record.addedBy === "coach" ? "coach" : legacyBook ? "coach" : void 0),
+		...toc !== void 0 && toc.length > 0 ? { toc } : {},
+		...source === void 0 ? {} : { tocSource: {
+			by: source.by === "web" || source.by === "photo" ? source.by : "model",
+			...opt("url", text(source.url, 1e3)),
+			...opt("verifiedAt", text(source.verifiedAt, 40))
+		} },
+		...meta === void 0 ? {} : { meta },
+		createdAt: stamp(record.createdAt)
+	};
+}
+/** A v2/v3 chapter-ranges list, as ranges. */
+function legacyRanges(value) {
+	return Array.isArray(value) ? value.flatMap((range) => {
+		const r = asRecord(range);
+		const from = finite(r?.from);
+		const to = finite(r?.to);
+		return from === void 0 || to === void 0 ? [] : [{
+			from,
+			to
+		}];
+	}) : [];
+}
+/**
+* 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.
+*/
+function normalizeNodeCover(value) {
+	const record = asRecord(value);
+	if (record === void 0) return void 0;
+	const provenance = {
+		...opt("by", record.by === "web" || record.by === "model" || record.by === "user" ? record.by : void 0),
+		...opt("verifiedAt", text(record.verifiedAt, 40))
+	};
+	const ref = text(record.ref, 1e3);
+	if (ref !== void 0) return {
+		ref,
+		...opt("locator", text(record.locator, 200)),
+		...opt("title", text(record.title, 300)),
+		...provenance
+	};
+	switch (record.kind) {
+		case "book": {
+			const bookId = id(record.bookId);
+			if (bookId === void 0) return void 0;
+			const ranges = legacyRanges(record.ranges);
+			return {
+				ref: bookId,
+				...ranges.length === 0 ? {} : { locator: formatLocator(ranges) },
+				...provenance
+			};
+		}
+		case "resource": {
+			const resourceId = id(record.resourceId);
+			return resourceId === void 0 ? void 0 : {
+				ref: resourceId,
+				...provenance
+			};
+		}
+		case "url": {
+			const url = text(record.url, 1e3);
+			return url === void 0 ? void 0 : {
+				ref: url,
+				...opt("title", text(record.title, 300)),
+				...provenance
+			};
+		}
+		case "topic": {
+			const topicText = text(record.text, 300);
+			return topicText === void 0 ? void 0 : {
+				ref: `topic:${topicText}`,
+				...provenance
+			};
+		}
+		default: return;
+	}
+}
+/** One roadmap (adopted or draft), when it parses; rule checks live in the service. */
+function normalizeRoadmap(value) {
+	const record = asRecord(value);
+	if (record === void 0 || !Array.isArray(record.nodes)) return void 0;
+	const primaryResourceId = id(record.primaryResourceId) ?? id(record.bookId);
+	const nodes = [];
+	for (const item of record.nodes) {
+		const node = asRecord(item);
+		const nodeId = id(node?.id);
+		const title = text(node?.title, 300);
+		const state = node?.state === "locked" || node?.state === "current" || node?.state === "done" ? node.state : void 0;
+		if (node === void 0 || nodeId === void 0 || title === void 0 || state === void 0) return void 0;
+		const gate = node.gate === "read" || node.gate === "acceptance" || node.gate === "quiz" ? node.gate : node.kind === "read" ? "read" : node.kind === "practice" ? "acceptance" : "quiz";
+		const covers = Array.isArray(node.covers) ? node.covers.flatMap((cover) => {
+			const normalized = normalizeNodeCover(cover);
+			return normalized === void 0 ? [] : [normalized];
+		}) : primaryResourceId !== void 0 && node.chapterRanges !== void 0 ? [{
+			ref: primaryResourceId,
+			locator: formatLocator(legacyRanges(node.chapterRanges))
+		}] : [];
+		const stats = asRecord(node.quizStats);
+		const notesRec = asRecord(node.notes);
+		const notesText = text(notesRec?.text, 4e4);
+		const points = gate === "quiz" && Array.isArray(node.points) ? node.points.flatMap((entry) => {
+			const point = asRecord(entry);
+			const pointId = point !== void 0 ? id(point.id) : void 0;
+			const pointTitle = text(point?.title, 100);
+			return pointId === void 0 || pointTitle === void 0 ? [] : [{
+				id: pointId,
+				title: pointTitle
+			}];
+		}) : void 0;
+		nodes.push({
+			id: nodeId,
+			title,
+			gate,
+			goals: typeof node.goals === "string" ? strings([node.goals], 300) : strings(node.goals, 300),
+			dependsOn: Array.isArray(node.dependsOn) ? node.dependsOn.filter((dep) => typeof dep === "string") : [],
+			covers,
+			state,
+			...stats === void 0 || gate !== "quiz" ? {} : { quizStats: {
+				attempts: finite(stats.attempts) ?? 0,
+				...opt("lastRatio", finite(stats.lastRatio)),
+				...opt("bestRatio", finite(stats.bestRatio))
+			} },
+			...points === void 0 || points.length === 0 ? {} : { points },
+			...gate === "acceptance" && Array.isArray(node.acceptance) ? { acceptance: acceptanceEntries(node.acceptance) } : {},
+			...notesRec === void 0 || notesText === void 0 ? {} : { notes: {
+				text: notesText,
+				updatedAt: stamp(notesRec.updatedAt),
+				revisions: finite(notesRec.revisions) ?? 1
+			} }
+		});
+	}
+	const passRatio = finite(record.passRatio);
+	return {
+		...opt("primaryResourceId", primaryResourceId),
+		status: record.status === "adopted" ? "adopted" : "draft",
+		nodes,
+		...passRatio !== void 0 && passRatio > 0 && passRatio <= 1 ? { passRatio } : {},
+		...opt("note", text(record.note, 300)),
+		generatedAt: stamp(record.generatedAt),
+		...opt("adoptedAt", text(record.adoptedAt, 40))
+	};
+}
+/** An attachment reference, when every durable field is present. */
+function normalizeAttachmentRef(value) {
+	const record = asRecord(value);
+	const attachmentId = text(record?.attachmentId, 200);
+	const mediaType = text(record?.mediaType, 100);
+	const bytes = finite(record?.bytes);
+	const width = finite(record?.width);
+	const height = finite(record?.height);
+	if (attachmentId === void 0 || mediaType === void 0 || bytes === void 0 || width === void 0 || height === void 0) return void 0;
+	return {
+		attachmentId,
+		mediaType,
+		bytes,
+		width,
+		height
+	};
+}
+/** One photographed page (one pages/<resourceId>.jsonl line), when it parses. */
+function normalizePage(value) {
+	const record = asRecord(value);
+	const pageId = id(record?.id);
+	const resourceId = id(record?.resourceId) ?? id(record?.bookId);
+	const attachment = normalizeAttachmentRef(record?.attachment);
+	if (record === void 0 || pageId === void 0 || resourceId === void 0 || attachment === void 0) return void 0;
+	return {
+		id: pageId,
+		resourceId,
+		...opt("nodeId", id(record.nodeId)),
+		...opt("label", text(record.label, 60)),
+		attachment,
+		text: typeof record.text === "string" ? record.text.slice(0, 2e4) : "",
+		marks: Array.isArray(record.marks) ? record.marks.flatMap((item) => {
+			const mark = asRecord(item);
+			const markText = text(mark?.text, 300);
+			if (mark === void 0 || markText === void 0) return [];
+			return [{
+				text: markText,
+				...opt("sentence", text(mark.sentence, 1e3)),
+				...opt("handNote", text(mark.handNote, 300)),
+				...opt("gloss", text(mark.gloss, 1e3)),
+				...mark.uncertain === true ? { uncertain: true } : {}
+			}];
+		}) : [],
+		cardIds: strings(record.cardIds, 100),
+		at: stamp(record.at)
+	};
+}
+const CARD_SOURCE_TYPES = [
+	"photo",
+	"chat",
+	"quiz",
+	"manual"
+];
+/** One knowledge card (one cards.jsonl line), when it parses. */
+function normalizeCard(value) {
+	const record = asRecord(value);
+	const cardId = id(record?.id);
+	const term = text(record?.term, 300);
+	const gloss = text(record?.gloss, 2e3);
+	if (record === void 0 || cardId === void 0 || term === void 0 || gloss === void 0) return void 0;
+	const mastery = asRecord(record.mastery) ?? {};
+	const box = finite(mastery.box);
+	const weakness = finite(record.weakness) ?? 0;
+	return {
+		id: cardId,
+		kind: record.kind === "word" ? "word" : "concept",
+		term,
+		aliases: strings(record.aliases, 300),
+		gloss,
+		...opt("userGloss", text(record.userGloss, 1e3)),
+		contexts: Array.isArray(record.contexts) ? record.contexts.flatMap((item) => {
+			const context = asRecord(item);
+			const sentence = text(context?.sentence, 1e3);
+			if (context === void 0 || sentence === void 0) return [];
+			return [{
+				sentence,
+				...opt("resourceId", id(context.resourceId) ?? id(context.bookId)),
+				...opt("pageId", id(context.pageId)),
+				...opt("nodeId", id(context.nodeId))
+			}];
+		}) : [],
+		...opt("resourceId", id(record.resourceId) ?? id(record.bookId)),
+		sources: Array.isArray(record.sources) ? record.sources.flatMap((item) => {
+			const source = asRecord(item);
+			const type = CARD_SOURCE_TYPES.find((candidate) => candidate === source?.type);
+			if (source === void 0 || type === void 0) return [];
+			return [{
+				type,
+				...opt("ref", text(source.ref, 200)),
+				...opt("note", text(source.note, 300)),
+				...source.weakened === true ? { weakened: true } : {},
+				at: stamp(source.at)
+			}];
+		}) : [],
+		weakness: Math.min(Math.max(Math.round(weakness), 0), 3),
+		mastery: {
+			box: box === void 0 ? 0 : Math.min(Math.max(Math.round(box), 0), 5),
+			dueAt: stamp(mastery.dueAt),
+			streak: Math.max(0, Math.round(finite(mastery.streak) ?? 0))
+		},
+		status: record.status === "mastered" || record.status === "deleted" ? record.status : "active",
+		createdAt: stamp(record.createdAt),
+		updatedAt: stamp(record.updatedAt ?? record.createdAt)
+	};
+}
+/**
+* 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).
+*/
+function normalizeQuizOptions(value) {
+	const letter = /^[A-Za-z][.、)）:：]\s*/;
+	const list = Array.isArray(value) ? value : typeof value === "object" && value !== null ? Object.values(value) : [];
+	if (list.length === 0) return void 0;
+	const out = [];
+	for (const option of list) {
+		if (typeof option === "string") {
+			out.push(option);
+			continue;
+		}
+		const label = asRecord(option)?.label;
+		if (typeof label === "string") {
+			out.push(label.replace(letter, ""));
+			continue;
+		}
+		return;
+	}
+	return out;
+}
+function normalizeQuizQuestions(value) {
+	if (!Array.isArray(value)) return void 0;
+	const questions = [];
+	for (const item of value) {
+		const q = asRecord(item);
+		const qid = text(q?.id, 60);
+		const kind = q?.kind === "choice" || q?.kind === "fill" || q?.kind === "free" ? q.kind : void 0;
+		const target = asRecord(q?.target);
+		const evidence = asRecord(q?.evidence);
+		if (q === void 0 || qid === void 0 || kind === void 0 || typeof q.prompt !== "string" || target === void 0 || evidence === void 0) return;
+		const targetKind = target.kind === "marked" || target.kind === "asked" || target.kind === "missed" ? target.kind : "topic";
+		const evidenceKind = evidence.kind === "photo" || evidence.kind === "web" ? evidence.kind : "knowledge";
+		questions.push({
+			id: qid,
+			kind,
+			prompt: q.prompt,
+			...(() => {
+				const options = normalizeQuizOptions(q.options);
+				return options === void 0 ? {} : { options };
+			})(),
+			answer: typeof q.answer === "string" ? q.answer : "",
+			...opt("explanation", text(q.explanation, 2e3)),
+			...opt("point", text(q.point, 60)),
+			target: {
+				kind: targetKind,
+				...Array.isArray(target.cardIds) ? { cardIds: strings(target.cardIds, 100) } : {}
+			},
+			evidence: {
+				kind: evidenceKind,
+				...opt("pageId", id(evidence.pageId)),
+				...opt("url", text(evidence.url, 1e3)),
+				...opt("quote", text(evidence.quote, 2e3))
+			}
+		});
+	}
+	return questions;
+}
+function normalizeRubricLines(value) {
+	if (!Array.isArray(value)) return void 0;
+	const lines = [];
+	for (const [index, item] of value.entries()) {
+		const record = asRecord(item);
+		const line = text(record?.line, 300);
+		if (line === void 0) return void 0;
+		lines.push({
+			id: text(record?.id, 20) ?? `L${index + 1}`,
+			line,
+			...opt("ref", text(record?.ref, 100))
+		});
+	}
+	return lines;
+}
+/**
+* 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).
+*/
+function normalizeAssessment(value) {
+	const record = asRecord(value);
+	const assessmentId = id(record?.id);
+	const scope = asRecord(record?.scope);
+	if (record === void 0 || assessmentId === void 0 || scope === void 0) return void 0;
+	const nodeId = id(scope.nodeId);
+	const resourceId = id(scope.resourceId) ?? id(scope.bookId);
+	const type = record.type === "practice" ? "practice" : "quiz";
+	if (type === "practice") {
+		const rubric = normalizeRubricLines(record.rubric);
+		if (rubric === void 0) return void 0;
+		return {
+			id: assessmentId,
+			type,
+			scope: {
+				...opt("nodeId", nodeId),
+				...opt("resourceId", resourceId)
+			},
+			rubric,
+			...opt("supersededBy", id(record.supersededBy)),
+			createdAt: stamp(record.createdAt)
+		};
+	}
+	const questions = normalizeQuizQuestions(record.questions);
+	if (questions === void 0) return void 0;
+	return {
+		id: assessmentId,
+		type,
+		scope: {
+			...opt("nodeId", nodeId),
+			...opt("resourceId", resourceId)
+		},
+		...record.focus === "mine" || record.focus === "book" || record.focus === "mixed" ? { focus: record.focus } : {},
+		questions,
+		...opt("supersededBy", id(record.supersededBy)),
+		createdAt: stamp(record.createdAt)
+	};
+}
+/** One attempt (one attempts.jsonl line), when it parses. */
+function normalizeAttempt(value) {
+	const record = asRecord(value);
+	const attemptId = id(record?.id);
+	const assessmentId = id(record?.assessmentId) ?? id(record?.quizId);
+	const nodeId = id(record?.nodeId);
+	const ratio = finite(record?.ratio);
+	if (record === void 0 || attemptId === void 0 || assessmentId === void 0 && nodeId === void 0 || ratio === void 0 || !Array.isArray(record.verdicts)) return void 0;
+	const verdicts = [];
+	for (const item of record.verdicts) {
+		const v = asRecord(item);
+		if (v === void 0 || typeof v.task !== "string" || typeof v.criterion !== "string" || typeof v.pass !== "boolean" || typeof v.evidence !== "string") return;
+		verdicts.push({
+			task: v.task,
+			criterion: v.criterion,
+			pass: v.pass,
+			...opt("ratio", finite(v.ratio)),
+			evidence: v.evidence,
+			by: v.by === "self" || v.by === "user" || v.by === "auto" ? v.by : "llm",
+			...v.void === true ? { void: true } : {}
+		});
+	}
+	return {
+		id: attemptId,
+		...opt("assessmentId", assessmentId),
+		...opt("nodeId", nodeId),
+		verdicts,
+		ratio,
+		at: stamp(record.at)
+	};
+}
+/** One audit event (one events.jsonl line), when it parses. */
+function normalizeEvent(value) {
+	const record = asRecord(value);
+	const rawType = record?.type === "book.added" ? "resource.added" : record?.type;
+	const type = typeof rawType === "string" && LIBRARY_EVENT_TYPES.includes(rawType) ? rawType : void 0;
+	if (record === void 0 || type === void 0) return void 0;
+	const count = finite(record.count);
+	const count2 = finite(record.count2);
+	return {
+		at: stamp(record.at),
+		type,
+		...opt("id", text(record.id, 200)),
+		...opt("title", text(record.title, 300)),
+		...opt("resourceId", id(record.resourceId) ?? id(record.bookId)),
+		...opt("source", CARD_SOURCE_TYPES.find((candidate) => candidate === record.source)),
+		...opt("session", text(record.session, 200)),
+		...Array.isArray(record.ids) ? { ids: strings(record.ids, 100) } : {},
+		...opt("count", count === void 0 ? void 0 : Math.floor(count)),
+		...opt("count2", count2 === void 0 ? void 0 : Math.floor(count2)),
+		...opt("ratio", finite(record.ratio))
+	};
+}
+/** The bindings map, dropping rows that do not parse. */
+function normalizeBindings(value) {
+	const out = /* @__PURE__ */ new Map();
+	const record = asRecord(value);
+	if (record === void 0) return out;
+	for (const [sessionId, raw] of Object.entries(record)) {
+		const binding = asRecord(raw);
+		const projectId = id(binding?.projectId);
+		if (sessionId === "" || projectId === void 0) continue;
+		out.set(sessionId, {
+			projectId,
+			...opt("resourceId", id(binding?.resourceId) ?? id(binding?.bookId))
+		});
+	}
+	return out;
+}
+/**
+* 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.
+*/
+var LibraryStore = class {
+	stateRoot;
+	/** Set once the root has proven unwritable; reads then degrade to empty. */
+	unwritable;
+	/**
+	* @param config - optional state-root override (tests, deployments that keep
+	*   state elsewhere).
+	*/
+	constructor(config = {}) {
+		this.stateRoot = resolveLibraryStateRoot(config.stateRoot);
+	}
+	/** The state root (diagnostics and tests). */
+	get root() {
+		return this.stateRoot;
+	}
+	/** Why persistence is unavailable, when it is. */
+	get unavailableReason() {
+		return this.unwritable;
+	}
+	/**
+	* Whether persistence is available — probed by creating the root, because a
+	* read-only deployment is only knowable by trying.
+	*/
+	get available() {
+		if (this.unwritable !== void 0) return false;
+		try {
+			mkdirSync(this.stateRoot, { recursive: true });
+			return true;
+		} catch (error) {
+			this.unwritable = `${this.stateRoot}: ${libraryErrorMessage(error)}`;
+			return false;
+		}
+	}
+	get indexFile() {
+		return join(this.stateRoot, "state.json");
+	}
+	get bindingsFile() {
+		return join(this.stateRoot, "bindings.json");
+	}
+	get projectsDir() {
+		return join(this.stateRoot, "projects");
+	}
+	/** One project's directory. */
+	projectDir(projectId) {
+		assertLibraryId(projectId, "project id");
+		return join(this.projectsDir, projectId);
+	}
+	/** The v5 resource file. */
+	resourceFile(projectId, resourceId) {
+		assertLibraryId(resourceId, "resource id");
+		return join(this.projectDir(projectId), "resources", `${resourceId}.json`);
+	}
+	/** The legacy per-book directory (v3/v4 layout — read-only now). */
+	legacyBookDir(projectId, bookId) {
+		assertLibraryId(bookId, "book id");
+		return join(this.projectDir(projectId), "books", bookId);
+	}
+	cardsFile(projectId) {
+		return join(this.projectDir(projectId), "cards.jsonl");
+	}
+	/** The legacy thin-links ledger (v3/v4 layout — read-only now). */
+	legacyResourcesFile(projectId) {
+		return join(this.projectDir(projectId), "resources.jsonl");
+	}
+	attemptsFile(projectId) {
+		return join(this.projectDir(projectId), "attempts.jsonl");
+	}
+	eventsFile(projectId) {
+		return join(this.projectDir(projectId), "events.jsonl");
+	}
+	/** The v5 assessment file. */
+	assessmentFile(projectId, assessmentId) {
+		assertLibraryId(assessmentId, "assessment id");
+		return join(this.projectDir(projectId), "assessments", `${assessmentId}.json`);
+	}
+	/** The legacy quiz file (v3/v4 layout — read-only now). */
+	legacyQuizFile(projectId, quizId) {
+		assertLibraryId(quizId, "quiz id");
+		return join(this.projectDir(projectId), "quizzes", `${quizId}.json`);
+	}
+	/** The roadmap key: the primary resource's id, or 'project' for the project's own path. */
+	roadmapKey(resourceId) {
+		if (resourceId !== void 0) assertLibraryId(resourceId, "resource id");
+		return resourceId ?? "project";
+	}
+	/** The v5 roadmap file. */
+	roadmapFile(projectId, resourceId, which) {
+		const key = this.roadmapKey(resourceId);
+		return join(this.projectDir(projectId), "roadmaps", which === "adopted" ? `${key}.json` : `${key}.draft.json`);
+	}
+	/** The legacy roadmap file (v3/v4 layout — read-only now). */
+	legacyRoadmapFile(projectId, resourceId, which) {
+		const file = which === "adopted" ? "roadmap.json" : "roadmap.draft.json";
+		return resourceId === void 0 ? join(this.projectDir(projectId), file) : join(this.legacyBookDir(projectId, resourceId), file);
+	}
+	/** The v5 pages ledger of one thick resource. */
+	pagesFile(projectId, resourceId) {
+		assertLibraryId(resourceId, "resource id");
+		return join(this.projectDir(projectId), "pages", `${resourceId}.jsonl`);
+	}
+	/** The per-project lock's path. */
+	projectLock(projectId) {
+		assertLibraryId(projectId, "project id");
+		return join(this.projectsDir, `${projectId}.lock`);
+	}
+	/** Serialize under the scope's lock: read-modify-write as one critical section. */
+	async withProjectLock(projectId, fn) {
+		if (!this.available) throw new LibraryStoreError("library: no writable state root", "unavailable");
+		mkdirSync(this.projectsDir, { recursive: true });
+		const lock = await acquireLibraryLock(this.projectLock(projectId));
+		try {
+			return await fn();
+		} finally {
+			lock.release();
+		}
+	}
+	/** The index's own lock (project create/delete). */
+	async withIndexLock(fn) {
+		return await this.withRootLock(this.indexFile, fn);
+	}
+	/** The bindings' own lock. */
+	async withBindingsLock(fn) {
+		return await this.withRootLock(this.bindingsFile, fn);
+	}
+	async withRootLock(file, fn) {
+		if (!this.available) throw new LibraryStoreError("library: no writable state root", "unavailable");
+		mkdirSync(this.stateRoot, { recursive: true });
+		const lock = await acquireLibraryLock(`${file}.lock`);
+		try {
+			return await fn();
+		} finally {
+			lock.release();
+		}
+	}
+	/**
+	* 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).
+	*/
+	readJsonFile(file, normalize) {
+		let raw;
+		try {
+			raw = readFileSync(file, "utf8");
+		} catch (error) {
+			if (error?.code === "ENOENT") return void 0;
+			throw new LibraryStoreError(`library: ${file} could not be read — ${libraryErrorMessage(error)}`, "io");
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			throw new LibraryStoreError(`library: ${file} does not parse — fix or remove it by hand`, "corrupt");
+		}
+		const doc = normalize(parsed);
+		if (doc === void 0) throw new LibraryStoreError(`library: ${file} holds no usable document — fix or remove it by hand`, "corrupt");
+		return doc;
+	}
+	/** Write one document atomically (temp file + rename). */
+	writeJsonFile(file, value) {
+		this.writeTextFile(file, `${JSON.stringify(value, null, 2)}\n`);
+	}
+	/** Write one text file atomically. */
+	writeTextFile(file, body) {
+		mkdirSync(dirname(file), { recursive: true });
+		const temporary = `${file}.${process.pid}.tmp`;
+		try {
+			writeFileSync(temporary, body);
+			renameSync(temporary, file);
+		} catch (error) {
+			rmSync(temporary, { force: true });
+			throw new LibraryStoreError(`library: ${file} could not be written — ${libraryErrorMessage(error)}`, "io");
+		}
+	}
+	/** Append lines to one JSONL ledger (append-only: never a rewrite). */
+	appendJsonlFile(file, values) {
+		if (values.length === 0) return;
+		mkdirSync(dirname(file), { recursive: true });
+		const lines = values.map((value) => `${JSON.stringify(value)}\n`).join("");
+		try {
+			writeFileSync(file, lines, { flag: "a" });
+		} catch (error) {
+			throw new LibraryStoreError(`library: ${file} could not be appended — ${libraryErrorMessage(error)}`, "io");
+		}
+	}
+	/** Read one JSONL ledger tolerantly: unparseable lines drop, never fail the read. */
+	readJsonlFile(file, normalize) {
+		let raw;
+		try {
+			raw = readFileSync(file, "utf8");
+		} catch (error) {
+			if (error?.code === "ENOENT") return [];
+			throw new LibraryStoreError(`library: ${file} could not be read — ${libraryErrorMessage(error)}`, "io");
+		}
+		const out = [];
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed === "") continue;
+			try {
+				const value = normalize(JSON.parse(trimmed));
+				if (value !== void 0) out.push(value);
+			} catch {}
+		}
+		return out;
+	}
+	/** The index; absent reads as empty, an unavailable root as empty. */
+	readIndex() {
+		if (!this.available) return emptyLibraryIndex();
+		return this.readJsonFile(this.indexFile, (value) => normalizeLibraryIndex(value)) ?? emptyLibraryIndex();
+	}
+	/** The session bindings; absent or unreadable reads as empty. */
+	readBindings() {
+		if (!this.available) return /* @__PURE__ */ new Map();
+		try {
+			return normalizeBindings(JSON.parse(readFileSync(this.bindingsFile, "utf8")));
+		} catch {
+			return /* @__PURE__ */ new Map();
+		}
+	}
+	/** One project's record; undefined when absent. */
+	readProject(projectId) {
+		return this.readJsonFile(this.projectFile(projectId), normalizeProject);
+	}
+	projectFile(projectId) {
+		return join(this.projectDir(projectId), "project.json");
+	}
+	/**
+	* 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, resourceId) {
+		const current = this.readJsonFile(this.resourceFile(projectId, resourceId), normalizeResource);
+		if (current !== void 0) return current;
+		const legacyBook = this.readJsonFile(join(this.legacyBookDir(projectId, resourceId), "book.json"), normalizeResource);
+		if (legacyBook !== void 0) return legacyBook;
+		return this.readJsonlFile(this.legacyResourcesFile(projectId), normalizeResource).find((resource) => resource.id === resourceId);
+	}
+	/** Every shelf entry of one project, oldest first, both layouts merged (a v5 file shadows a legacy twin of the same id). */
+	listResources(projectId) {
+		const byId = /* @__PURE__ */ new Map();
+		const legacyDir = join(this.projectDir(projectId), "books");
+		if (existsSync(legacyDir)) for (const entry of readdirSync(legacyDir, { withFileTypes: true })) {
+			if (!entry.isDirectory() || !isLibraryId(entry.name)) continue;
+			const book = this.readJsonFile(join(legacyDir, entry.name, "book.json"), normalizeResource);
+			if (book !== void 0) byId.set(book.id, book);
+		}
+		for (const link of this.readJsonlFile(this.legacyResourcesFile(projectId), normalizeResource)) byId.set(link.id, link);
+		const resourcesDir = join(this.projectDir(projectId), "resources");
+		if (existsSync(resourcesDir)) for (const name of readdirSync(resourcesDir)) {
+			if (!name.endsWith(".json") || !isLibraryId(name.slice(0, -5))) continue;
+			const resource = this.readJsonFile(join(resourcesDir, name), normalizeResource);
+			if (resource !== void 0) byId.set(resource.id, resource);
+		}
+		return [...byId.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	}
+	/**
+	* One scope's adopted roadmap, or its draft; no resourceId = the project's
+	* own path. The v5 file wins; the legacy spot (the project's root file or
+	* the book's directory) follows.
+	*/
+	readRoadmap(projectId, resourceId, which = "adopted") {
+		const current = this.readJsonFile(this.roadmapFile(projectId, resourceId, which), normalizeRoadmap);
+		if (current !== void 0) return current;
+		const legacy = this.readJsonFile(this.legacyRoadmapFile(projectId, resourceId, which), normalizeRoadmap);
+		return legacy === void 0 ? void 0 : {
+			...legacy,
+			...resourceId === void 0 || legacy.primaryResourceId !== void 0 ? {} : { primaryResourceId: resourceId }
+		};
+	}
+	/**
+	* 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, resourceId) {
+		const legacy = this.readJsonlFile(join(this.legacyBookDir(projectId, resourceId), "pages.jsonl"), normalizePage);
+		const current = this.readJsonlFile(this.pagesFile(projectId, resourceId), normalizePage);
+		return [...legacy, ...current];
+	}
+	/** Every knowledge card of one project (deleted ones included — callers filter). */
+	readCards(projectId) {
+		return this.readJsonlFile(this.cardsFile(projectId), normalizeCard);
+	}
+	/** Every attempt (the JSONL ledger, tolerant per line). */
+	readAttempts(projectId) {
+		return this.readJsonlFile(this.attemptsFile(projectId), normalizeAttempt);
+	}
+	/** The audit ledger, oldest first. */
+	readEvents(projectId) {
+		return this.readJsonlFile(this.eventsFile(projectId), normalizeEvent);
+	}
+	/**
+	* One assessment; undefined when absent. The v5 file wins; a legacy quiz
+	* file (`quizzes/<id>.json`) reads as a type=quiz assessment.
+	*/
+	readAssessment(projectId, assessmentId) {
+		const current = this.readJsonFile(this.assessmentFile(projectId, assessmentId), normalizeAssessment);
+		if (current !== void 0) return current;
+		return this.readJsonFile(this.legacyQuizFile(projectId, assessmentId), normalizeAssessment);
+	}
+	/** Every assessment of one project, oldest first, both layouts merged. */
+	listAssessments(projectId) {
+		const byId = /* @__PURE__ */ new Map();
+		const quizzesDir = join(this.projectDir(projectId), "quizzes");
+		if (existsSync(quizzesDir)) for (const name of readdirSync(quizzesDir)) {
+			if (!name.endsWith(".json") || !isLibraryId(name.slice(0, -5))) continue;
+			const quiz = this.readJsonFile(join(quizzesDir, name), normalizeAssessment);
+			if (quiz !== void 0) byId.set(quiz.id, quiz);
+		}
+		const assessmentsDir = join(this.projectDir(projectId), "assessments");
+		if (existsSync(assessmentsDir)) for (const name of readdirSync(assessmentsDir)) {
+			if (!name.endsWith(".json") || !isLibraryId(name.slice(0, -5))) continue;
+			const assessment = this.readJsonFile(join(assessmentsDir, name), normalizeAssessment);
+			if (assessment !== void 0) byId.set(assessment.id, assessment);
+		}
+		return [...byId.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	}
+	/** Write the index (call inside `withIndexLock`). */
+	writeIndex(doc) {
+		this.writeJsonFile(this.indexFile, doc);
+	}
+	/** Write the bindings (call inside `withBindingsLock`). */
+	writeBindings(bindings) {
+		this.writeJsonFile(this.bindingsFile, Object.fromEntries(bindings));
+	}
+	/** Write one project's record (call inside `withProjectLock`). */
+	writeProject(project) {
+		this.writeJsonFile(this.projectFile(project.id), project);
+	}
+	/** Write one shelf entry (call inside `withProjectLock`) — the v5 layout. */
+	writeResource(projectId, resource) {
+		this.writeJsonFile(this.resourceFile(projectId, resource.id), resource);
+	}
+	/** Write one scope's adopted roadmap or its draft (call inside `withProjectLock`) — the v5 layout. */
+	writeRoadmap(projectId, roadmap) {
+		this.writeJsonFile(this.roadmapFile(projectId, roadmap.primaryResourceId, roadmap.status === "adopted" ? "adopted" : "draft"), roadmap);
+	}
+	/** Drop one scope's draft (adopted or discarded), in BOTH layouts; no resourceId = the project's. */
+	removeDraft(projectId, resourceId) {
+		rmSync(this.roadmapFile(projectId, resourceId, "draft"), { force: true });
+		rmSync(this.legacyRoadmapFile(projectId, resourceId, "draft"), { force: true });
+	}
+	/** Append one photographed page (call inside `withProjectLock`) — the v5 layout. */
+	appendPage(projectId, page) {
+		this.appendJsonlFile(this.pagesFile(projectId, page.resourceId), [page]);
+	}
+	/**
+	* 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, cards) {
+		this.writeTextFile(this.cardsFile(projectId), cards.map((card) => `${JSON.stringify(card)}\n`).join(""));
+	}
+	/** Append one attempt (call inside `withProjectLock`). */
+	appendAttempt(projectId, attempt) {
+		this.appendJsonlFile(this.attemptsFile(projectId), [attempt]);
+	}
+	/** Append audit events (call inside `withProjectLock`). */
+	appendEvents(projectId, events) {
+		this.appendJsonlFile(this.eventsFile(projectId), events);
+	}
+	/** Write one assessment (call inside `withProjectLock`) — the v5 layout. */
+	writeAssessment(projectId, assessment) {
+		this.writeJsonFile(this.assessmentFile(projectId, assessment.id), assessment);
+	}
+	/**
+	* 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, resourceId) {
+		rmSync(this.resourceFile(projectId, resourceId), { force: true });
+		rmSync(this.pagesFile(projectId, resourceId), { force: true });
+		rmSync(this.roadmapFile(projectId, resourceId, "adopted"), { force: true });
+		rmSync(this.roadmapFile(projectId, resourceId, "draft"), { force: true });
+		rmSync(this.legacyBookDir(projectId, resourceId), {
+			recursive: true,
+			force: true
+		});
+		if (existsSync(this.legacyResourcesFile(projectId))) {
+			const kept = this.readJsonlFile(this.legacyResourcesFile(projectId), normalizeResource).filter((resource) => resource.id !== resourceId);
+			this.writeTextFile(this.legacyResourcesFile(projectId), kept.map((resource) => `${JSON.stringify(resource)}\n`).join(""));
+		}
+	}
+	/** Remove one project's whole directory. */
+	removeProject(projectId) {
+		rmSync(this.projectDir(projectId), {
+			recursive: true,
+			force: true
+		});
+		rmSync(this.projectLock(projectId), { force: true });
+	}
+	/**
+	* 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.
+	*/
+	async migrateState() {
+		if (!this.available) return false;
+		let raw;
+		try {
+			raw = readFileSync(this.indexFile, "utf8");
+		} catch {
+			return false;
+		}
+		let version;
+		try {
+			version = JSON.parse(raw).version;
+		} catch {
+			return false;
+		}
+		if (version !== 2) return false;
+		await this.withIndexLock(async () => {
+			const index = this.readIndex();
+			for (const project of index.projects) await this.withProjectLock(project.id, () => {
+				this.migrateProjectRoadmapsV2(project.id);
+			});
+			this.writeIndex({
+				...index,
+				version: 5
+			});
+		});
+		return true;
+	}
+	/** Rewrite one project's v2 book roadmaps (adopted and draft) into covers. */
+	migrateProjectRoadmapsV2(projectId) {
+		const dir = join(this.projectDir(projectId), "books");
+		if (!existsSync(dir)) return;
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (!entry.isDirectory() || !isLibraryId(entry.name)) continue;
+			for (const file of ["roadmap.json", "roadmap.draft.json"]) {
+				const path = join(dir, entry.name, file);
+				let parsed;
+				try {
+					parsed = JSON.parse(readFileSync(path, "utf8"));
+				} catch {
+					continue;
+				}
+				const roadmap = asRecord(parsed);
+				if (roadmap === void 0 || !Array.isArray(roadmap.nodes)) continue;
+				let touched = false;
+				const nodes = roadmap.nodes.map((item) => {
+					const node = asRecord(item);
+					if (node === void 0 || node.covers !== void 0 || node.chapterRanges === void 0) return item;
+					touched = true;
+					const { chapterRanges, ...rest } = node;
+					return {
+						...rest,
+						covers: [{
+							kind: "book",
+							bookId: entry.name,
+							ranges: Array.isArray(chapterRanges) ? chapterRanges : []
+						}]
+					};
+				});
+				if (touched) this.writeJsonFile(path, {
+					...roadmap,
+					nodes
+				});
+			}
+		}
+	}
+};
+/**
+* Resolve the state root: an explicit config value wins, then
+* `$DSH_HOME/state/dsh-library`, then `<cwd>/.dsh-library`.
+*/
+function resolveLibraryStateRoot(configured) {
+	if (configured !== void 0 && configured !== "") return configured;
+	const home = process.env.DSH_HOME;
+	if (home !== void 0 && home !== "") return join(home, "state", STATE_ROOT_SEGMENT);
+	return join(process.cwd(), `.${STATE_ROOT_SEGMENT}`);
+}
+//#endregion
+export { MAX_WEAKNESS as A, parseLocator as B, LIBRARY_COLORS as C, LIBRARY_RESOURCE_KINDS as D, LIBRARY_ID_PATTERN as E, coverTopic as F, formatLocator as I, isLibraryId as L, TEMPLATE_LOOK as M, acceptanceLines as N, LIBRARY_STATE_VERSION as O, coverKind as P, isThickResource as R, LEITNER_INTERVAL_DAYS as S, LIBRARY_ICONS as T, normalizeQuizOptions as _, emptyLibraryIndex as a, resolveLibraryStateRoot as b, normalizeAttachmentRef as c, normalizeCard as d, normalizeEvent as f, normalizeProject as g, normalizePage as h, assertLibraryId as i, STATE_ROOT_SEGMENT as j, MAX_BOX as k, normalizeAttempt as l, normalizeNodeCover as m, LibraryStoreError as n, mintLibraryId as o, normalizeLibraryIndex as p, acquireLibraryLock as r, normalizeAssessment as s, LibraryStore as t, normalizeBindings as u, normalizeResource as v, LIBRARY_EVENT_TYPES as w, DEFAULT_PASS_RATIO as x, normalizeRoadmap as y, libraryErrorMessage as z };