dsh-diagnostic-tutor 0.1.1 → 0.2.0

package/lib/review-tools.js

@@ -0,0 +1,115 @@
+/** Model-facing review queue. Scheduling only; no mastery judgement. */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { MAX_REVIEW_CARDS, REVIEW_RATINGS, dueCards, scheduleReview, } from './review.js';
+const ReviewInputSchema = z.object({
+    front: z.string().min(1).max(2000),
+    back: z.string().min(1).max(4000),
+    courseId: z.string().min(1).max(120).optional(),
+    nodeId: z.string().min(1).max(120).optional(),
+    blockId: z.string().min(1).max(120).optional(),
+    sourceRefs: z.array(z.object({ sourceId: z.string().min(1).max(120), locator: z.string().min(1).max(300) })).max(6).optional(),
+}).strict();
+function output() {
+    return { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] };
+}
+function validate(state, raw, index) {
+    const input = ReviewInputSchema.parse(raw);
+    if (input.courseId !== undefined) {
+        if (state.readCourse(input.courseId) === undefined)
+            throw new Error(`card[${index}] references an unknown course`);
+        if (input.nodeId !== undefined && state.readNode(input.nodeId)?.courseId !== input.courseId)
+            throw new Error(`card[${index}] references a node outside the course`);
+    }
+    else if (input.nodeId !== undefined)
+        throw new Error(`card[${index}] cannot name a node without its course`);
+    for (const ref of input.sourceRefs ?? []) {
+        if (state.readSource(ref.sourceId) === undefined)
+            throw new Error(`card[${index}] references an unknown source`);
+    }
+    return input;
+}
+export function reviewTools(state) {
+    return [
+        defineTool({
+            name: 'udt_review_add',
+            description: 'Add review cards to the learner-owned spaced-repetition queue. Scheduling is runtime policy, not a mastery claim: no node state changes. ' +
+                'Use a flashcard or a check as the source of a card; include sourceRefs when the card quotes a source. New cards are due immediately.',
+            parameters: {
+                cards: {
+                    type: 'array', required: true,
+                    items: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            front: { type: 'string', required: true },
+                            back: { type: 'string', required: true },
+                            courseId: { type: 'string' },
+                            nodeId: { type: 'string' },
+                            blockId: { type: 'string' },
+                            sourceRefs: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { sourceId: { type: 'string', required: true }, locator: { type: 'string', required: true } } } },
+                        },
+                    },
+                },
+            },
+            output: output(),
+            execute: async (args) => {
+                const input = args;
+                if (!Array.isArray(input.cards) || input.cards.length === 0)
+                    throw new Error('review-add-needs-cards');
+                if (state.listReviewCards().length + input.cards.length > MAX_REVIEW_CARDS)
+                    throw new Error('too-many-review-cards');
+                const now = new Date().toISOString();
+                const cards = input.cards.map((candidate, index) => {
+                    const parsed = validate(state, candidate, index);
+                    return {
+                        id: randomUUID(), front: parsed.front, back: parsed.back,
+                        dueAt: now, intervalDays: 0, ease: 2.5, reps: 0, lapses: 0, status: 'open', createdAt: now, updatedAt: now,
+                        ...(parsed.courseId === undefined ? {} : { courseId: parsed.courseId }),
+                        ...(parsed.nodeId === undefined ? {} : { nodeId: parsed.nodeId }),
+                        ...(parsed.blockId === undefined ? {} : { blockId: parsed.blockId }),
+                        ...(parsed.sourceRefs === undefined ? {} : { sourceRefs: parsed.sourceRefs }),
+                    };
+                });
+                for (const card of cards)
+                    await state.writeReviewCard(card);
+                return JSON.parse(JSON.stringify({ ok: true, cards }));
+            },
+        }),
+        defineTool({
+            name: 'udt_review_next',
+            description: 'Read the review cards that are due now (open, dueAt <= now), earliest first. This only reports the queue; it does not grade or change learning state.',
+            parameters: { limit: { type: 'integer', description: 'Maximum cards, 1-20; default 5.' } },
+            output: output(),
+            execute: async (args) => {
+                const raw = args.limit;
+                const limit = Number.isInteger(raw) ? Math.min(20, Math.max(1, raw)) : 5;
+                return JSON.parse(JSON.stringify({ now: new Date().toISOString(), cards: dueCards(state.listReviewCards()).slice(0, limit) }));
+            },
+        }),
+        defineTool({
+            name: 'udt_review_grade',
+            description: 'Record one review grade (again | hard | good | easy) and schedule the card. This is interval arithmetic only: it does not mark a node confirmed, does not complete a lesson and does not auto-advance.',
+            parameters: {
+                cardId: { type: 'string', required: true },
+                rating: { type: 'string', required: true, enum: [...REVIEW_RATINGS] },
+            },
+            output: output(),
+            execute: async (args) => {
+                const input = args;
+                if (input.cardId === undefined)
+                    throw new Error('review-grade-needs-cardId');
+                if (input.rating === undefined || !REVIEW_RATINGS.includes(input.rating))
+                    throw new Error('review-grade-needs-rating');
+                const card = state.readReviewCard(input.cardId);
+                if (card === undefined)
+                    throw new Error('no-such-review-card: read udt_review_next');
+                const { card: updated, log } = scheduleReview(card, input.rating);
+                await state.writeReviewCard(updated);
+                await state.writeReviewLog(log);
+                return JSON.parse(JSON.stringify({ ok: true, card: updated, log }));
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=review-tools.js.map

package/lib/review-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-tools.js","sourceRoot":"","sources":["../src/review-tools.ts"],"names":[],"mappings":"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"}

package/lib/review.js

@@ -0,0 +1,103 @@
+/** Review cards and a dependency-free local interval scheduler. No mastery claims. */
+import { z } from 'zod';
+export const REVIEW_CARDS_TABLE = 'review_cards';
+export const REVIEW_LOG_TABLE = 'review_log';
+export const REVIEW_RATINGS = ['again', 'hard', 'good', 'easy'];
+export const REVIEW_STATUSES = ['open', 'suspended'];
+export const MAX_REVIEW_CARDS = 500;
+export const MAX_REVIEW_FRONT_CHARS = 2000;
+export const MAX_REVIEW_BACK_CHARS = 4000;
+export const ReviewSourceRefSchema = z.object({
+    sourceId: z.string().min(1).max(120),
+    locator: z.string().min(1).max(300),
+}).strict();
+export const ReviewCardSchema = z.object({
+    id: z.string().min(1).max(120),
+    courseId: z.string().min(1).max(120).optional(),
+    nodeId: z.string().min(1).max(120).optional(),
+    blockId: z.string().min(1).max(120).optional(),
+    front: z.string().min(1).max(MAX_REVIEW_FRONT_CHARS),
+    back: z.string().min(1).max(MAX_REVIEW_BACK_CHARS),
+    sourceRefs: z.array(ReviewSourceRefSchema).max(6).optional(),
+    dueAt: z.string(),
+    /** Days; fractional values are allowed for the first "again" step. */
+    intervalDays: z.number().min(0).max(3650),
+    ease: z.number().min(1.3).max(3.2),
+    reps: z.number().int().min(0),
+    lapses: z.number().int().min(0),
+    status: z.enum(REVIEW_STATUSES),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+}).strict();
+export const ReviewLogSchema = z.object({
+    id: z.string().min(1).max(120),
+    cardId: z.string().min(1).max(120),
+    rating: z.enum(REVIEW_RATINGS),
+    at: z.string(),
+    previousDue: z.string(),
+    nextDue: z.string(),
+    intervalDays: z.number().min(0),
+    ease: z.number().min(1.3).max(3.2),
+    /** Present on logs written by the current build; old logs may lack them. */
+    previousIntervalDays: z.number().min(0).optional(),
+    previousEase: z.number().min(1.3).max(3.2).optional(),
+    previousReps: z.number().int().min(0).optional(),
+    previousLapses: z.number().int().min(0).optional(),
+}).strict();
+const DAY_MS = 86_400_000;
+/** Apply one grade. This is scheduling arithmetic, not a judgement about learning. */
+export function scheduleReview(card, rating, now = new Date()) {
+    let intervalDays = card.intervalDays;
+    let ease = card.ease;
+    let lapses = card.lapses;
+    if (rating === 'again') {
+        intervalDays = 0;
+        ease = Math.max(1.3, ease - 0.2);
+        lapses += 1;
+    }
+    else if (rating === 'hard') {
+        intervalDays = Math.max(1, card.intervalDays * 1.2);
+        ease = Math.max(1.3, ease - 0.15);
+    }
+    else if (rating === 'good') {
+        intervalDays = Math.max(1, card.intervalDays * ease);
+    }
+    else {
+        intervalDays = Math.max(2, card.intervalDays * ease * 1.3);
+        ease = Math.min(3.2, ease + 0.15);
+    }
+    const dueAt = rating === 'again'
+        ? new Date(now.getTime() + 10 * 60_000)
+        : new Date(now.getTime() + intervalDays * DAY_MS);
+    const updated = {
+        ...card,
+        intervalDays,
+        ease,
+        lapses,
+        reps: card.reps + 1,
+        dueAt: dueAt.toISOString(),
+        updatedAt: now.toISOString(),
+    };
+    const log = {
+        id: `${card.id}:${now.getTime()}:${card.reps + 1}`,
+        cardId: card.id,
+        rating,
+        at: now.toISOString(),
+        previousDue: card.dueAt,
+        nextDue: updated.dueAt,
+        intervalDays,
+        ease,
+        previousIntervalDays: card.intervalDays,
+        previousEase: card.ease,
+        previousReps: card.reps,
+        previousLapses: card.lapses,
+    };
+    return { card: updated, log };
+}
+export function dueCards(cards, now = new Date()) {
+    const time = now.getTime();
+    return [...cards]
+        .filter((card) => card.status === 'open' && Date.parse(card.dueAt) <= time)
+        .sort((left, right) => Date.parse(left.dueAt) - Date.parse(right.dueAt));
+}
+//# sourceMappingURL=review.js.map

package/lib/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../src/review.ts"],"names":[],"mappings":"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"}

package/lib/source-schema.js

@@ -0,0 +1,24 @@
+/** Learner-owned source material. Pure schema, no DSH imports. */
+import { z } from 'zod';
+export const SOURCE_KINDS = ['text', 'file', 'markdown'];
+export const SOURCE_STATUSES = ['ready', 'error'];
+export const MAX_SOURCE_BYTES = 131_072;
+export const MAX_SOURCE_CHARS = MAX_SOURCE_BYTES;
+export const MAX_SOURCES = 40;
+export const MAX_SOURCE_TITLE_CHARS = 200;
+export const MAX_SOURCE_LOCATOR_CHARS = 500;
+export const SourceRecordSchema = z.object({
+    id: z.string().min(1).max(120),
+    kind: z.enum(SOURCE_KINDS),
+    title: z.string().min(1).max(MAX_SOURCE_TITLE_CHARS),
+    /** Original path, URL, or a human-readable locator. Never fetched by the plugin. */
+    locator: z.string().min(1).max(MAX_SOURCE_LOCATOR_CHARS),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().min(0).max(MAX_SOURCE_BYTES),
+    createdAt: z.string(),
+    status: z.enum(SOURCE_STATUSES),
+    /** Extracted text. Optional so an errored future record can stay metadata-only. */
+    content: z.string().max(MAX_SOURCE_CHARS).optional(),
+}).strict();
+export const SOURCES_TABLE = 'sources';
+//# sourceMappingURL=source-schema.js.map

package/lib/source-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-schema.js","sourceRoot":"","sources":["../src/source-schema.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU,CAAA;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,CAAU,CAAA;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAChD,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAA;AAC7B,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA;AACzC,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAE3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC9B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACpD,oFAAoF;IACpF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,wBAAwB,CAAC;IACxD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACpD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;IAC/B,mFAAmF;IACnF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC,MAAM,EAAE,CAAA;AAIX,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAA"}

package/lib/source-tools.js

@@ -0,0 +1,61 @@
+/** Model-facing source ingestion: zero network, explicit local file or pasted text. */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { addSource, sourceDraftFromFile, sourceDraftFromText } from './sources.js';
+function output() {
+    return { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] };
+}
+function metadata(record) {
+    return { id: record.id, kind: record.kind, title: record.title, locator: record.locator, sha256: record.sha256, bytes: record.bytes, createdAt: record.createdAt, status: record.status };
+}
+export function sourceTools(state) {
+    return [
+        defineTool({
+            name: 'udt_source_add',
+            description: 'Add learner-owned source material before teaching from it. Use kind=file with an absolute path to one local .md/.markdown/.txt file, or kind=text/markdown with pasted text. ' +
+                'The plugin reads only that explicit file and never scans a directory or fetches a URL; for a web page, use your own web tool and pass the extracted text with a locator. ' +
+                'Content is stored locally in the udt storage domain. Identical content is deduplicated by SHA-256. ' +
+                'After adding, cite passages on lesson blocks with sourceRefs; never invent a sourceId.',
+            parameters: {
+                kind: { type: 'string', required: true, enum: ['text', 'file', 'markdown'] },
+                path: { type: 'string', description: 'Absolute path for kind=file. Never a directory or URL.' },
+                text: { type: 'string', description: 'Text for kind=text/markdown.' },
+                title: { type: 'string' },
+                locator: { type: 'string', description: 'Original URL, path or human-readable location.' },
+            },
+            output: output(),
+            execute: async (args) => {
+                const input = args;
+                if (input.kind !== 'text' && input.kind !== 'markdown' && input.kind !== 'file')
+                    throw new Error('source-kind-required: use text, markdown or file');
+                const draft = input.kind === 'file'
+                    ? await sourceDraftFromFile(input.path ?? '')
+                    : sourceDraftFromText({ text: input.text ?? '', kind: input.kind, ...(input.title === undefined ? {} : { title: input.title }), ...(input.locator === undefined ? {} : { locator: input.locator }) });
+                const { source, deduped } = await addSource(state, draft);
+                return { ...metadata(source), deduped };
+            },
+        }),
+        defineTool({
+            name: 'udt_source_list',
+            description: 'List learner-owned sources with metadata only. Never returns full content; use udt_source_get for a selected source.',
+            parameters: {},
+            output: output(),
+            execute: async () => {
+                const sources = state.listSources().map(metadata);
+                return { count: sources.length, bytes: state.listSources().reduce((sum, source) => sum + source.bytes, 0), sources };
+            },
+        }),
+        defineTool({
+            name: 'udt_source_get',
+            description: 'Read one learner-owned source by sourceId. This returns stored text for citation; it does not fetch anything.',
+            parameters: { sourceId: { type: 'string', required: true } },
+            output: output(),
+            execute: async (args) => {
+                const source = state.readSource(args.sourceId ?? '');
+                if (source === undefined)
+                    throw new Error('no-such-source: read udt_source_list');
+                return JSON.parse(JSON.stringify(source));
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=source-tools.js.map

package/lib/source-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-tools.js","sourceRoot":"","sources":["../src/source-tools.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGnD,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGlF,SAAS,MAAM;IACb,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAW,EAAE,MAAM,EAAE,CAAC,KAAc,EAAE,KAAc,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAA;AAClL,CAAC;AAED,SAAS,QAAQ,CAAC,MAAkD;IAClE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;AAC3L,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO;QACL,UAAU,CAAC;YACT,IAAI,EAAE,gBAAgB;YACtB,WAAW,EACT,+KAA+K;gBAC/K,2KAA2K;gBAC3K,qGAAqG;gBACrG,wFAAwF;YAC1F,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE;gBAC5E,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wDAAwD,EAAE;gBAC/F,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8BAA8B,EAAE;gBACrE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gDAAgD,EAAE;aAC3F;YACD,MAAM,EAAE,MAAM,EAAE;YAChB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACtB,MAAM,KAAK,GAAG,IAAyF,CAAA;gBACvG,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;gBACpJ,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,KAAK,MAAM;oBACjC,CAAC,CAAC,MAAM,mBAAmB,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;oBAC7C,CAAC,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAA;gBACvM,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;gBACzD,OAAO,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;YACzC,CAAC;SACF,CAAC;QACF,UAAU,CAAC;YACT,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,sHAAsH;YACnI,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,MAAM,EAAE;YAChB,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;gBACjD,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAA;YACtH,CAAC;SACF,CAAC;QACF,UAAU,CAAC;YACT,IAAI,EAAE,gBAAgB;YACtB,WAAW,EAAE,+GAA+G;YAC5H,UAAU,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;YAC5D,MAAM,EAAE,MAAM,EAAE;YAChB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACtB,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAE,IAA8B,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAA;gBAC/E,IAAI,MAAM,KAAK,SAAS;oBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;gBACjF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAA0B,CAAA;YACpE,CAAC;SACF,CAAC;KACH,CAAA;AACH,CAAC"}

package/lib/sources.js

@@ -0,0 +1,78 @@
+/** Local source ingestion. No network access is ever made by this module. */
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, readFile } from 'node:fs/promises';
+import { basename, extname, isAbsolute, resolve } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { MAX_SOURCE_BYTES, MAX_SOURCE_TITLE_CHARS, MAX_SOURCES } from './source-schema.js';
+const ALLOWED_EXTENSIONS = new Set(['.md', '.markdown', '.txt']);
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export function sourceDraftFromText(input) {
+    const text = input.text;
+    if (text.length === 0)
+        throw new Error('source-empty: paste some text first');
+    if (Buffer.byteLength(text, 'utf8') > MAX_SOURCE_BYTES)
+        throw new Error(`source-too-large: keep one source under ${MAX_SOURCE_BYTES} bytes`);
+    const kind = input.kind ?? 'text';
+    const title = (input.title?.trim() || (kind === 'markdown' ? 'Pasted Markdown' : 'Pasted text')).slice(0, MAX_SOURCE_TITLE_CHARS);
+    return { kind, title, locator: (input.locator?.trim() || title).slice(0, 500), content: text };
+}
+/**
+ * Read one explicitly selected local markdown/text file.
+ *
+ * This is the only place the plugin reads outside its own storage domain. It
+ * refuses directories, symlinks, unsupported extensions and oversized files;
+ * it never scans a directory or follows a URL.
+ */
+export async function sourceDraftFromFile(path) {
+    if (!isAbsolute(path))
+        throw new Error('source-path-must-be-absolute: pass the full path to one file');
+    const resolved = resolve(path);
+    const stats = await lstat(resolved);
+    if (stats.isSymbolicLink())
+        throw new Error('source-symlink-refused: pass the file itself');
+    if (!stats.isFile())
+        throw new Error('source-not-a-file: choose one markdown or text file');
+    const extension = extname(resolved).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.has(extension))
+        throw new Error('source-unsupported-file: only .md, .markdown and .txt are accepted in this phase');
+    if (stats.size > MAX_SOURCE_BYTES)
+        throw new Error(`source-too-large: keep one source under ${MAX_SOURCE_BYTES} bytes`);
+    const buffer = await readFile(resolved);
+    if (buffer.byteLength > MAX_SOURCE_BYTES)
+        throw new Error(`source-too-large: keep one source under ${MAX_SOURCE_BYTES} bytes`);
+    let content;
+    try {
+        content = decoder.decode(buffer);
+    }
+    catch {
+        throw new Error('source-not-utf8: convert the file to UTF-8 first');
+    }
+    if (content.includes('\u0000'))
+        throw new Error('source-binary: the selected file is not text');
+    const title = basename(resolved).slice(0, MAX_SOURCE_TITLE_CHARS);
+    return { kind: 'file', title, locator: resolved, content };
+}
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+export function sourceRecord(draft, now = new Date().toISOString()) {
+    const bytes = Buffer.byteLength(draft.content, 'utf8');
+    if (bytes > MAX_SOURCE_BYTES)
+        throw new Error(`source-too-large: keep one source under ${MAX_SOURCE_BYTES} bytes`);
+    return {
+        id: randomUUID(), kind: draft.kind, title: draft.title, locator: draft.locator,
+        sha256: sha256(draft.content), bytes, createdAt: now, status: 'ready', content: draft.content,
+    };
+}
+/** Add one source, deduplicating identical content by SHA-256. */
+export async function addSource(store, draft, now) {
+    const record = sourceRecord(draft, now);
+    const existing = store.listSources().find((source) => source.sha256 === record.sha256 && source.status === 'ready');
+    if (existing !== undefined)
+        return { source: existing, deduped: true };
+    if (store.listSources().length >= MAX_SOURCES)
+        throw new Error(`too-many-sources: this learner already has ${MAX_SOURCES} sources`);
+    await store.writeSource(record);
+    return { source: record, deduped: false };
+}
+//# sourceMappingURL=sources.js.map

package/lib/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"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"}

package/lib/state.js

@@ -38,8 +38,12 @@ import { z } from 'zod';
 import { endsFocus } from './vocabulary.js';
 import { EvidenceKindSchema, INITIAL_NODE_STATE, NodeRelationSchema, NodeStateSchema, ReadinessSchema, TeachingModeSchema, } from './vocabulary.js';
 import { LessonSchema } from './lesson.js';
+import { SOURCES_TABLE, SourceRecordSchema } from './source-schema.js';
+import { TASKS_TABLE, TaskSchema } from './plan.js';
+import { REVIEW_CARDS_TABLE, REVIEW_LOG_TABLE, ReviewCardSchema, ReviewLogSchema } from './review.js';
 import { HandoffSchema } from './handoff.js';
 import { focusKey, handoffKey, isLegacyExecutionKey, nextStepKey } from './execution-key.js';
+import { CourseRunSchema, LearningPathSchema, emptyPath, emptyRun } from './path.js';
 /* -------------------------------------------------------------------------- */
 /* Records                                                                    */
 /* -------------------------------------------------------------------------- */
@@ -91,6 +95,9 @@ export const EvidenceSchema = z.object({
     at: z.string(),
     note: z.string().min(1).optional(),
     readiness: ReadinessSchema.optional(),
+    /** Runtime-stamped provenance for observations made during a planned attempt. */
+    sessionId: z.string().min(1).optional(),
+    attemptId: z.string().min(1).optional(),
 });
 /**
  * One node of the diagnosis map.
@@ -295,6 +302,13 @@ export const udtDomain = defineDomain({
         // handoff rather than two.
         [HANDOFFS_TABLE]: domainTable(HandoffSchema),
         [PROJECTS_TABLE]: domainTable(ProjectSchema),
+        // Additive v1 tables: older v1 documents open with empty planning maps.
+        learning_paths: domainTable(LearningPathSchema),
+        course_runs: domainTable(CourseRunSchema),
+        [SOURCES_TABLE]: domainTable(SourceRecordSchema),
+        [TASKS_TABLE]: domainTable(TaskSchema),
+        [REVIEW_CARDS_TABLE]: domainTable(ReviewCardSchema),
+        [REVIEW_LOG_TABLE]: domainTable(ReviewLogSchema),
     },
 });
 /**
@@ -339,6 +353,14 @@ export async function openUdState(facility) {
     const nextSteps = domain.table(NEXT_STEPS_TABLE);
     const handoffs = domain.table(HANDOFFS_TABLE);
     const projects = domain.table(PROJECTS_TABLE);
+    const paths = domain.table('learning_paths');
+    const runs = domain.table('course_runs');
+    const sources = domain.table(SOURCES_TABLE);
+    const tasks = domain.table(TASKS_TABLE);
+    const reviewCards = domain.table(REVIEW_CARDS_TABLE);
+    const reviewLog = domain.table(REVIEW_LOG_TABLE);
+    let planningGeneration = 0;
+    const runKey = (courseId, sessionId) => JSON.stringify([sessionId, courseId]);
     const learner = domain.global;
     const listNodesFor = (courseId) => [...nodes.entries()].map(([, record]) => record).filter((record) => record.courseId === courseId);
     const projectRevisions = new Map();
@@ -451,6 +473,22 @@ export async function openUdState(facility) {
             await nodes.put(record.id, record);
             return record;
         },
+        mutateNode(courseId, nodeId, change) {
+            const generation = planningGeneration;
+            return withProjectWrite(async () => {
+                if (generation !== planningGeneration || !courses.get(courseId))
+                    throw new Error('project-unavailable: refresh the selected project');
+                const current = nodes.get(nodeId);
+                if (!current || current.courseId !== courseId)
+                    throw new Error('node-unavailable: use an existing node in this project');
+                const proposed = change(structuredClone(current));
+                if (proposed.id !== nodeId || proposed.courseId !== courseId)
+                    throw new Error('node identity cannot change');
+                const next = NodeSchema.parse(proposed);
+                await nodes.put(nodeId, next);
+                return structuredClone(next);
+            });
+        },
         nodeCount: () => nodes.size,
         readMap(courseId) {
             const course = courses.get(courseId);
@@ -594,16 +632,25 @@ export async function openUdState(facility) {
                 // owns: it is a choice they made, and an export that dropped it would
                 // restore them to a library with nothing selected.
                 projects: [...projects.entries()].map(([, record]) => record),
+                learningPaths: [...paths.entries()].map(([, record]) => structuredClone(record)),
+                courseRuns: [...runs.entries()].map(([, record]) => structuredClone(record)),
+                sources: [...sources.entries()].map(([, record]) => structuredClone(record)),
+                tasks: [...tasks.entries()].map(([, record]) => structuredClone(record)),
+                reviewCards: [...reviewCards.entries()].map(([, record]) => structuredClone(record)),
+                reviewLog: [...reviewLog.entries()].map(([, record]) => structuredClone(record)),
             };
         },
         async resetState(now) {
-            // Table by table, on the domain's own write chain, so a reset cannot
-            // interleave with a write that is already queued.
-            for (const table of [courses, nodes, lessons, focus, nextSteps, handoffs, projects]) {
-                for (const key of [...table.keys()])
-                    await table.delete(key);
-            }
-            await learner.set({ initializedAt: UNINITIALIZED, updatedAt: now });
+            // Invalidate planning work captured before reset; serialize with planning
+            // and project selections so late writes cannot resurrect deleted plans.
+            ++planningGeneration;
+            await withProjectWrite(async () => {
+                for (const table of [courses, nodes, lessons, focus, nextSteps, handoffs, projects, paths, runs, sources, tasks, reviewCards, reviewLog]) {
+                    for (const key of [...table.keys()])
+                        await table.delete(key);
+                }
+                await learner.set({ initializedAt: UNINITIALIZED, updatedAt: now });
+            });
         },
         readHandoff: (sessionId, targetNodeId) => {
             const record = handoffs.get(handoffKey(sessionId, targetNodeId));
@@ -641,7 +688,101 @@ export async function openUdState(facility) {
             await lessons.put(record.id, record);
             return record;
         },
+        mutateLesson(courseId, nodeId, change) {
+            const generation = planningGeneration;
+            return withProjectWrite(async () => {
+                if (generation !== planningGeneration || !courses.get(courseId))
+                    throw new Error('project-unavailable: refresh the selected project');
+                if (nodes.get(nodeId)?.courseId !== courseId)
+                    throw new Error('node-unavailable: use an existing node in this project');
+                const current = [...lessons.entries()].map(([, record]) => record).find((record) => record.nodeId === nodeId);
+                const proposed = change(current === undefined ? undefined : structuredClone(current));
+                if (proposed.courseId !== courseId || proposed.nodeId !== nodeId || (current && proposed.id !== current.id))
+                    throw new Error('lesson identity cannot change');
+                const next = LessonSchema.parse(proposed);
+                await lessons.put(next.id, next);
+                return structuredClone(next);
+            });
+        },
         lessonCount: () => lessons.size,
+        listSources: () => [...sources.entries()].map(([, record]) => structuredClone(record)),
+        readSource: (id) => {
+            const record = sources.get(id);
+            return record === undefined ? undefined : structuredClone(record);
+        },
+        async writeSource(record) {
+            await sources.put(record.id, record);
+            return record;
+        },
+        listTasks: () => [...tasks.entries()].map(([, record]) => structuredClone(record)),
+        readTask: (id) => {
+            const record = tasks.get(id);
+            return record === undefined ? undefined : structuredClone(record);
+        },
+        async writeTask(record) {
+            await tasks.put(record.id, record);
+            return record;
+        },
+        async deleteTask(id) {
+            await tasks.delete(id);
+        },
+        listReviewCards: () => [...reviewCards.entries()].map(([, record]) => structuredClone(record)),
+        readReviewCard: (id) => {
+            const record = reviewCards.get(id);
+            return record === undefined ? undefined : structuredClone(record);
+        },
+        async writeReviewCard(record) {
+            await reviewCards.put(record.id, record);
+            return record;
+        },
+        listReviewLog: () => [...reviewLog.entries()].map(([, record]) => structuredClone(record)),
+        async writeReviewLog(record) {
+            await reviewLog.put(record.id, record);
+            return record;
+        },
+        async deleteReviewLog(id) {
+            await reviewLog.delete(id);
+        },
+        readPath: (courseId) => {
+            const record = paths.get(courseId);
+            return record === undefined ? undefined : structuredClone(record);
+        },
+        mutatePath(courseId, expectedRevision, change) {
+            const generation = planningGeneration;
+            return withProjectWrite(async () => {
+                if (generation !== planningGeneration || !courses.get(courseId))
+                    throw new Error('project-unavailable: refresh the selected project');
+                const current = structuredClone(paths.get(courseId) ?? emptyPath(courseId, new Date().toISOString()));
+                if (current.revision !== expectedRevision)
+                    throw new Error('revision-conflict: learning plan changed; refresh before writing');
+                const proposed = change(current);
+                if (proposed.courseId !== courseId)
+                    throw new Error('planning project identity cannot change');
+                const next = LearningPathSchema.parse({ ...proposed, revision: current.revision + 1 });
+                await paths.put(courseId, next);
+                return structuredClone(next);
+            });
+        },
+        readCourseRun: (courseId, sessionId) => {
+            const record = runs.get(runKey(courseId, sessionId));
+            return record === undefined ? undefined : structuredClone(record);
+        },
+        listCourseRuns: () => [...runs.entries()].map(([, record]) => structuredClone(record)),
+        mutateCourseRun(courseId, sessionId, change) {
+            const generation = planningGeneration;
+            return withProjectWrite(async () => {
+                if (!sessionId || generation !== planningGeneration || !courses.get(courseId))
+                    throw new Error('project-unavailable: refresh the selected project');
+                const key = runKey(courseId, sessionId);
+                const current = structuredClone(runs.get(key) ?? emptyRun(courseId, sessionId, new Date().toISOString()));
+                const proposed = change(current);
+                if (proposed.courseId !== courseId || proposed.sessionId !== sessionId)
+                    throw new Error('course run identity cannot change');
+                const next = CourseRunSchema.parse({ ...proposed, revision: current.revision + 1 });
+                await runs.put(key, next);
+                return structuredClone(next);
+            });
+        },
         snapshot() {
             const profile = learner.get();
             return {