dsh-diagnostic-tutor 0.1.1 → 0.2.0

package/lib/types/state.d.ts

@@ -37,7 +37,11 @@ import type { DomainFacility } from '@deepseek-ai/dsh-storage-domain';
 import { z } from 'zod';
 import type { NodeRelation, NodeState, Readiness } from './vocabulary.js';
 import type { LessonKey, LessonRecord } from './lesson.js';
+import type { SourceRecord } from './source-schema.js';
+import type { TaskRecord } from './plan.js';
+import type { ReviewCard, ReviewLog } from './review.js';
 import type { HandoffKey, HandoffRecord } from './handoff.js';
+import type { CourseRun, LearningPath } from './path.js';
 /**
  * The learner singleton. Stored in the domain's **global** slot rather than a
  * one-row table, because the global slot exists precisely for a single
@@ -65,9 +69,9 @@ export type LearnerProfile = z.infer<typeof LearnerProfileSchema>;
 /** Lifecycle of a learning goal. Not a mastery status. */
 export declare const COURSE_STATUSES: readonly ["active", "paused", "archived"];
 export declare const CourseStatusSchema: z.ZodEnum<{
+    archived: "archived";
     active: "active";
     paused: "paused";
-    archived: "archived";
 }>;
 export type CourseStatus = z.infer<typeof CourseStatusSchema>;
 /**
@@ -81,9 +85,9 @@ export declare const CourseSchema: z.ZodObject<{
     title: z.ZodString;
     goal: z.ZodString;
     status: z.ZodEnum<{
+        archived: "archived";
         active: "active";
         paused: "paused";
-        archived: "archived";
     }>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -99,11 +103,11 @@ export type CourseRecord = z.infer<typeof CourseSchema>;
  */
 export declare const EvidenceSchema: z.ZodObject<{
     kind: z.ZodEnum<{
+        check: "check";
+        explanation: "explanation";
         "goal-stated": "goal-stated";
         diagnosis: "diagnosis";
-        explanation: "explanation";
         practice: "practice";
-        check: "check";
         transfer: "transfer";
     }>;
     at: z.ZodString;
@@ -116,6 +120,8 @@ export declare const EvidenceSchema: z.ZodObject<{
         "diagnose-again": "diagnose-again";
         "more-practice": "more-practice";
     }>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    attemptId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Evidence = z.infer<typeof EvidenceSchema>;
 /**
@@ -148,11 +154,11 @@ export declare const NodeSchema: z.ZodObject<{
     }>;
     evidence: z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
+            check: "check";
+            explanation: "explanation";
             "goal-stated": "goal-stated";
             diagnosis: "diagnosis";
-            explanation: "explanation";
             practice: "practice";
-            check: "check";
             transfer: "transfer";
         }>;
         at: z.ZodString;
@@ -165,6 +171,8 @@ export declare const NodeSchema: z.ZodObject<{
             "diagnose-again": "diagnose-again";
             "more-practice": "more-practice";
         }>>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        attemptId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -296,9 +304,21 @@ export interface UdExport {
     readonly focus: readonly FocusRecord[];
     /** Which Learning Project each conversation had open. */
     readonly projects: readonly ProjectRecord[];
+    /** Planning and actual course attempts are learner-owned history too. */
+    readonly learningPaths: readonly LearningPath[];
+    readonly courseRuns: readonly CourseRun[];
+    /** Learner-supplied source material, with citations pointing into it. */
+    readonly sources: readonly SourceRecord[];
+    readonly tasks: readonly TaskRecord[];
+    readonly reviewCards: readonly ReviewCard[];
+    readonly reviewLog: readonly ReviewLog[];
 }
 export type CourseKey = string;
 export type NodeKey = string;
+export type SourceKey = string;
+export type TaskKey = string;
+export type ReviewCardKey = string;
+export type ReviewLogKey = string;
 /** Domain name. Must match the storage hub's `UNIT_NAME_RE` (`^[a-z][a-z0-9_]*$`). */
 export declare const UDT_DOMAIN_NAME = "udt";
 /**
@@ -369,7 +389,7 @@ export declare const udtDomain: {
             id: string;
             title: string;
             goal: string;
-            status: "active" | "paused" | "archived";
+            status: "archived" | "active" | "paused";
             createdAt: string;
             updatedAt: string;
         }>;
@@ -380,10 +400,12 @@ export declare const udtDomain: {
             relation: "goal" | "part-of" | "prerequisite" | "related";
             state: "unconfirmed" | "explained" | "practiced" | "checked" | "weak" | "blocked" | "confirmed";
             evidence: {
-                kind: "goal-stated" | "diagnosis" | "explanation" | "practice" | "check" | "transfer";
+                kind: "check" | "explanation" | "goal-stated" | "diagnosis" | "practice" | "transfer";
                 at: string;
                 note?: string | undefined;
                 readiness?: "advance" | "advance-with-caution" | "review-first" | "step-down" | "diagnose-again" | "more-practice" | undefined;
+                sessionId?: string | undefined;
+                attemptId?: string | undefined;
             }[];
             createdAt: string;
             updatedAt: string;
@@ -398,9 +420,18 @@ export declare const udtDomain: {
                 type: "text";
                 content: {
                     md: string;
+                    math?: {
+                        tex: string;
+                        display: boolean;
+                        mathml: string;
+                    }[] | undefined;
                 };
                 id: string;
                 metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
             } | {
                 type: "example";
                 content: {
@@ -410,6 +441,10 @@ export declare const udtDomain: {
                 };
                 id: string;
                 metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
             } | {
                 type: "diagram";
                 content: {
@@ -419,6 +454,10 @@ export declare const udtDomain: {
                 };
                 id: string;
                 metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
             } | {
                 type: "check";
                 content: {
@@ -428,6 +467,107 @@ export declare const udtDomain: {
                 };
                 id: string;
                 metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                type: "formula";
+                content: {
+                    tex: string;
+                    display?: boolean | undefined;
+                    mathml?: string | undefined;
+                    caption?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                type: "code";
+                content: {
+                    source: string;
+                    language?: string | undefined;
+                    caption?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                type: "quiz";
+                content: {
+                    questions: {
+                        id: string;
+                        kind: "mcq" | "short";
+                        prompt: string;
+                        options?: string[] | undefined;
+                        answer?: string | undefined;
+                        rubric?: string | undefined;
+                        explanation?: string | undefined;
+                    }[];
+                    title?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                type: "flashcard";
+                content: {
+                    front: string;
+                    back: string;
+                    tags?: string[] | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                type: "resource";
+                content: {
+                    title: string;
+                    sourceId?: string | undefined;
+                    locator?: string | undefined;
+                    url?: string | undefined;
+                    note?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                type: "comparison";
+                content: {
+                    columns: string[];
+                    rows: string[][];
+                    caption?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
+            } | {
+                id: string;
+                type: string;
+                content: unknown;
+                metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
             })[];
             origin: "prototype" | "tutor";
             createdAt: string;
@@ -455,7 +595,7 @@ export declare const udtDomain: {
             targetNodeId: string;
             courseId: string;
             fromNodeId: string;
-            status: "requested" | "prompted" | "working" | "ready" | "failed";
+            status: "ready" | "requested" | "prompted" | "working" | "failed";
             attempts: number;
             requestedAt: string;
             updatedAt: string;
@@ -473,6 +613,348 @@ export declare const udtDomain: {
             selectedAt: string;
             courseId?: string | undefined;
         }>;
+        learning_paths: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            courseId: string;
+            revision: number;
+            briefRevision: number;
+            assessmentRevision: number;
+            brief: {
+                purpose: string;
+                outcomes: string[];
+                background: string;
+                timeZone: string;
+                targetDate: string | null;
+                durationWeeks: number | null;
+                deadline: "none" | "flexible" | "fixed";
+                weeklyMinutes: number | null;
+                sessionMinutes: number | null;
+                preferences: string;
+            } | null;
+            assessment: {
+                status: "ready" | "in-progress" | "skipped";
+                summary: string;
+                strengths: string[];
+                gaps: string[];
+                uncertainties: string[];
+                evidence: {
+                    nodeId: string;
+                    evidenceIndex: number;
+                }[];
+                briefRevision: number;
+                sessionId: string;
+                updatedAt: string;
+            } | null;
+            curricula: {
+                version: number;
+                briefRevision: number;
+                assessmentRevision: number;
+                createdAt: string;
+                acceptedAt: string | null;
+                title: string;
+                summary: string;
+                modules: {
+                    id: string;
+                    title: string;
+                    overview: string;
+                    outcomes: string[];
+                    milestone: string;
+                }[];
+                items: {
+                    id: string;
+                    moduleId: string;
+                    title: string;
+                    overview: string;
+                    outcomes: string[];
+                    outline: string[];
+                    topics: string[];
+                    nodeIds: string[];
+                    practice: string;
+                    assessment: string;
+                    minutes: {
+                        min: number;
+                        max: number;
+                    };
+                }[];
+                edges: {
+                    from: string;
+                    to: string;
+                    kind: "optional" | "required";
+                }[];
+                assumptions: string[];
+                changeReason: string;
+            }[];
+            acceptedVersion: number | null;
+            requests: {
+                id: string;
+                sessionId: string;
+                kind: "diagnosis" | "plan";
+                briefRevision: number;
+                createdAt: string;
+                prompted: boolean;
+                reason: string | null;
+                failure?: string | null | undefined;
+            }[];
+            updatedAt: string;
+        }>;
+        course_runs: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            courseId: string;
+            sessionId: string;
+            revision: number;
+            activeAttemptId: string | null;
+            attempts: {
+                id: string;
+                operationId: string;
+                operations: string[];
+                dispatchId: string | null;
+                version: number;
+                itemId: string;
+                status: "requested" | "working" | "completed" | "interrupted";
+                nodeId: string | null;
+                startedAt: string;
+                updatedAt: string;
+                prompted: boolean;
+                promptReason: string | null;
+                outcome: string | null;
+                evidence: {
+                    nodeId: string;
+                    evidenceIndex: number;
+                }[];
+                units: {
+                    id: string;
+                    writtenAt: string;
+                    lesson: {
+                        id: string;
+                        courseId: string;
+                        nodeId: string;
+                        title: string;
+                        blocks: ({
+                            type: "text";
+                            content: {
+                                md: string;
+                                math?: {
+                                    tex: string;
+                                    display: boolean;
+                                    mathml: string;
+                                }[] | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "example";
+                            content: {
+                                title: string;
+                                steps: string[];
+                                takeaway?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "diagram";
+                            content: {
+                                format: "ascii" | "mermaid";
+                                spec: string;
+                                caption?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "check";
+                            content: {
+                                prompt: string;
+                                expect?: "reasoning" | "answer" | undefined;
+                                hint?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "formula";
+                            content: {
+                                tex: string;
+                                display?: boolean | undefined;
+                                mathml?: string | undefined;
+                                caption?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "code";
+                            content: {
+                                source: string;
+                                language?: string | undefined;
+                                caption?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "quiz";
+                            content: {
+                                questions: {
+                                    id: string;
+                                    kind: "mcq" | "short";
+                                    prompt: string;
+                                    options?: string[] | undefined;
+                                    answer?: string | undefined;
+                                    rubric?: string | undefined;
+                                    explanation?: string | undefined;
+                                }[];
+                                title?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "flashcard";
+                            content: {
+                                front: string;
+                                back: string;
+                                tags?: string[] | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "resource";
+                            content: {
+                                title: string;
+                                sourceId?: string | undefined;
+                                locator?: string | undefined;
+                                url?: string | undefined;
+                                note?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            type: "comparison";
+                            content: {
+                                columns: string[];
+                                rows: string[][];
+                                caption?: string | undefined;
+                            };
+                            id: string;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        } | {
+                            id: string;
+                            type: string;
+                            content: unknown;
+                            metadata?: Record<string, unknown> | undefined;
+                            sourceRefs?: {
+                                sourceId: string;
+                                locator: string;
+                            }[] | undefined;
+                        })[];
+                        origin: "prototype" | "tutor";
+                        createdAt: string;
+                        updatedAt: string;
+                    };
+                }[];
+                responses?: {
+                    id: string;
+                    blockId: string;
+                    kind: "quiz" | "flashcard";
+                    answers: {
+                        questionId: string;
+                        value: string;
+                    }[];
+                    submittedAt: string;
+                }[] | undefined;
+            }[];
+            updatedAt: string;
+        }>;
+        sources: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            kind: "text" | "file" | "markdown";
+            title: string;
+            locator: string;
+            sha256: string;
+            bytes: number;
+            createdAt: string;
+            status: "error" | "ready";
+            content?: string | undefined;
+        }>;
+        tasks: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            title: string;
+            status: "open" | "done" | "archived";
+            createdAt: string;
+            updatedAt: string;
+            courseId?: string | undefined;
+            nodeId?: string | undefined;
+            dueAt?: string | undefined;
+            estimateMin?: number | undefined;
+            sourceId?: string | undefined;
+        }>;
+        review_cards: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            front: string;
+            back: string;
+            dueAt: string;
+            intervalDays: number;
+            ease: number;
+            reps: number;
+            lapses: number;
+            status: "open" | "suspended";
+            createdAt: string;
+            updatedAt: string;
+            courseId?: string | undefined;
+            nodeId?: string | undefined;
+            blockId?: string | undefined;
+            sourceRefs?: {
+                sourceId: string;
+                locator: string;
+            }[] | undefined;
+        }>;
+        review_log: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            cardId: string;
+            rating: "again" | "hard" | "good" | "easy";
+            at: string;
+            previousDue: string;
+            nextDue: string;
+            intervalDays: number;
+            ease: number;
+            previousIntervalDays?: number | undefined;
+            previousEase?: number | undefined;
+            previousReps?: number | undefined;
+            previousLapses?: number | undefined;
+        }>;
     };
 };
 export type UdtDomain = typeof udtDomain;
@@ -543,6 +1025,8 @@ export interface UdState {
     readNode(id: NodeKey): NodeRecord | undefined;
     /** Insert or fully replace one node. */
     writeNode(record: NodeRecord): Promise<NodeRecord>;
+    /** Read, validate, and commit a node change on the project/planning queue. The transform must not enqueue writes. */
+    mutateNode(courseId: CourseKey, nodeId: NodeKey, change: (current: NodeRecord) => NodeRecord): Promise<NodeRecord>;
     /** Number of nodes across every course. */
     nodeCount(): number;
     /** The course plus its map. */
@@ -666,8 +1150,31 @@ export interface UdState {
     lessonForNode(nodeId: NodeKey): LessonRecord | undefined;
     /** Insert or fully replace one lesson. */
     writeLesson(record: LessonRecord): Promise<LessonRecord>;
+    /** Read, merge, and commit a node's lesson on the project/planning queue. The transform must not enqueue writes. */
+    mutateLesson(courseId: CourseKey, nodeId: NodeKey, change: (current: LessonRecord | undefined) => LessonRecord): Promise<LessonRecord>;
     /** Number of lessons across every course. */
     lessonCount(): number;
+    /** Learner-supplied material, newest first is not guaranteed; callers sort if needed. */
+    listSources(): SourceRecord[];
+    readSource(id: SourceKey): SourceRecord | undefined;
+    writeSource(record: SourceRecord): Promise<SourceRecord>;
+    listTasks(): TaskRecord[];
+    readTask(id: TaskKey): TaskRecord | undefined;
+    writeTask(record: TaskRecord): Promise<TaskRecord>;
+    deleteTask(id: TaskKey): Promise<void>;
+    listReviewCards(): ReviewCard[];
+    readReviewCard(id: ReviewCardKey): ReviewCard | undefined;
+    writeReviewCard(record: ReviewCard): Promise<ReviewCard>;
+    listReviewLog(): ReviewLog[];
+    writeReviewLog(record: ReviewLog): Promise<ReviewLog>;
+    deleteReviewLog(id: ReviewLogKey): Promise<void>;
+    /** Immutable planning snapshots; writes are validated and revision checked inside one queue. */
+    readPath(courseId: string): LearningPath | undefined;
+    mutatePath(courseId: string, expectedRevision: number, change: (current: LearningPath) => LearningPath): Promise<LearningPath>;
+    readCourseRun(courseId: string, sessionId: string): CourseRun | undefined;
+    /** Every planned run across conversations, for resolving "continue learning". */
+    listCourseRuns(): CourseRun[];
+    mutateCourseRun(courseId: string, sessionId: string, change: (current: CourseRun) => CourseRun): Promise<CourseRun>;
     snapshot(): UdStateSnapshot;
     /** Release the backend unit. Idempotent. */
     close(): Promise<void>;