dsh-diagnostic-tutor 0.1.0 → 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;
@@ -196,10 +204,43 @@ export declare const FocusSchema: z.ZodObject<{
     }>;
     updatedAt: z.ZodString;
     endedAt: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
     nextStepId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type FocusRecord = z.infer<typeof FocusSchema>;
 export type FocusKey = string;
+/**
+ * The Learning Project one conversation has selected.
+ *
+ * `courseId` is the project: a course record IS a learning project, and the UI
+ * calls it that. There is deliberately no separate project entity — a second
+ * one would have to be kept in step with the first, and the first already
+ * carries the map, the evidence and the lessons.
+ */
+export declare const ProjectSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    courseId: z.ZodOptional<z.ZodString>;
+    selectedAt: z.ZodString;
+}, z.core.$strip>;
+export type ProjectRecord = z.infer<typeof ProjectSchema>;
+export type ProjectKey = string;
+/** The conversation-local project state shared by the API and model tools. */
+export declare const PROJECT_SELECTIONS: readonly ["none", "new", "project"];
+export type ProjectSelection = (typeof PROJECT_SELECTIONS)[number];
+export interface SessionProjectResolution {
+    selection: ProjectSelection;
+    sessionAvailable: boolean;
+    course?: CourseRecord;
+    reason?: 'missing-session-id' | 'ambiguous-session-project' | 'stale-project';
+    /** In-process choice revision, used to reject a late adoption after a UI choice. */
+    revision: number;
+}
+export declare const PROJECT_BINDINGS: readonly ["adopted", "already-selected", "not-selected", "missing-session-id"];
+export type ProjectBinding = (typeof PROJECT_BINDINGS)[number];
+export interface ProjectBindingResult {
+    projectAdopted: boolean;
+    projectBinding: ProjectBinding;
+}
 /**
  * The tutor's decision about where the learner should go after this node.
  *
@@ -261,9 +302,23 @@ export interface UdExport {
     readonly lessons: readonly LessonRecord[];
     readonly nextSteps: readonly NextStepRecord[];
     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";
 /**
@@ -291,6 +346,21 @@ export declare const LESSONS_TABLE = "lessons";
 export declare const FOCUS_TABLE = "focus";
 export declare const NEXT_STEPS_TABLE = "next_steps";
 export declare const HANDOFFS_TABLE = "handoffs";
+/**
+ * Which Learning Project each conversation is looking at.
+ *
+ * The projects themselves are learner-level: the course, its map, its evidence
+ * and its lessons are shared by every conversation, and this table adds nothing
+ * to them. What it records is a *choice* — which of those projects this
+ * conversation has open — and a choice belongs to the conversation that made
+ * it. Without this the runtime had to guess, and the guess was "the most
+ * recently updated course", which is how a brand-new chat opened onto the
+ * learner's old machine-learning project.
+ *
+ * Keyed by session id. A conversation with no row here has selected nothing,
+ * and that is a real state rather than a missing one.
+ */
+export declare const PROJECTS_TABLE = "session_projects";
 /** Sentinel meaning "the global slot has never been written". */
 export declare const UNINITIALIZED = "";
 export declare const udtDomain: {
@@ -319,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;
         }>;
@@ -330,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;
@@ -348,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: {
@@ -360,6 +441,10 @@ export declare const udtDomain: {
                 };
                 id: string;
                 metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
             } | {
                 type: "diagram";
                 content: {
@@ -369,6 +454,10 @@ export declare const udtDomain: {
                 };
                 id: string;
                 metadata?: Record<string, unknown> | undefined;
+                sourceRefs?: {
+                    sourceId: string;
+                    locator: string;
+                }[] | undefined;
             } | {
                 type: "check";
                 content: {
@@ -378,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;
@@ -390,6 +580,7 @@ export declare const udtDomain: {
             status: "active" | "ended";
             updatedAt: string;
             endedAt?: string | undefined;
+            sessionId?: string | undefined;
             nextStepId?: string | undefined;
         }>;
         next_steps: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
@@ -404,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;
@@ -417,6 +608,353 @@ export declare const udtDomain: {
             failedAt?: string | undefined;
             failureReason?: string | undefined;
         }>;
+        session_projects: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            sessionId: string;
+            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;
@@ -487,12 +1025,36 @@ 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. */
     readMap(courseId: CourseKey): CourseMap | undefined;
     /** The recorded focus for one course, if any. */
-    readFocus(courseId: CourseKey): FocusRecord | undefined;
+    readFocus(sessionId: string, courseId: CourseKey): FocusRecord | undefined;
+    /**
+     * The Learning Project this conversation has selected.
+     *
+     * @returns the record, or undefined when it has chosen nothing — which is
+     *   the state every new conversation starts in.
+     */
+    readProject(sessionId: string): ProjectRecord | undefined;
+    /** Resolve only this conversation's project; never use learner.activeCourseId. */
+    resolveProject(sessionId?: string): SessionProjectResolution;
+    /**
+     * Record this conversation's choice.
+     *
+     * @param sessionId - the conversation.
+     * @param courseId - the project it picked, or undefined for "start
+     *   something new" — a deliberate state, not an absence of one.
+     * @param now - ISO timestamp.
+     */
+    selectProject(sessionId: string, courseId: string | undefined, now: string): Promise<ProjectRecord>;
+    /** Adopt after a successful write only if the conversation's choice has not changed. */
+    adoptProject(sessionId: string | undefined, courseId: string, now: string, expected: SessionProjectResolution, allowNew?: boolean): Promise<ProjectBindingResult>;
+    /** Every conversation's choice, for export. */
+    listProjects(): ProjectRecord[];
     /**
      * Record that learning is starting on one node of one course.
      *
@@ -505,9 +1067,9 @@ export interface UdState {
      * @param now - ISO timestamp.
      * @returns the stored focus.
      */
-    startFocus(courseId: CourseKey, nodeId: NodeKey, now: string): Promise<FocusRecord>;
-    /** Mark the course's focus as ended. No-op when there is none. */
-    endFocus(courseId: CourseKey, now: string): Promise<void>;
+    startFocus(courseId: CourseKey, nodeId: NodeKey, now: string, sessionId?: string): Promise<FocusRecord>;
+    /** Mark this conversation's focus as ended. No-op when there is none. */
+    endFocus(sessionId: string, courseId: CourseKey, now: string): Promise<void>;
     /**
      * Record the tutor's decision about where to go next.
      *
@@ -529,14 +1091,13 @@ export interface UdState {
         targetNodeId?: NodeKey;
         reason: string;
         now: string;
+        sessionId: string;
     }): Promise<{
         nextStep: NextStepRecord;
         focus: FocusRecord;
     }>;
-    /** The most recent recommendation recorded for a course, if any. */
-    latestNextStep(courseId: CourseKey): NextStepRecord | undefined;
-    /** A recommendation by key. */
-    readNextStep(id: NextStepKey): NextStepRecord | undefined;
+    /** A recommendation by the conversation that reached it. */
+    readNextStep(sessionId: string, fromNodeId: NodeKey): NextStepRecord | undefined;
     /** Every recommendation, for export. */
     listNextSteps(): NextStepRecord[];
     /** Every lesson, for export. */
@@ -558,7 +1119,7 @@ export interface UdState {
      * learner asked to delete, which is the opposite of the point.
      */
     resetState(now: string): Promise<void>;
-    readHandoff(targetNodeId: HandoffKey): HandoffRecord | undefined;
+    readHandoff(sessionId: string, targetNodeId: HandoffKey): HandoffRecord | undefined;
     /** Insert or replace one handoff. */
     writeHandoff(record: HandoffRecord): Promise<HandoffRecord>;
     /**
@@ -573,13 +1134,13 @@ export interface UdState {
      * @param transform - pure transform from current to next.
      * @returns the stored record.
      */
-    updateHandoff(targetNodeId: HandoffKey, transform: (record: HandoffRecord) => HandoffRecord): Promise<HandoffRecord>;
-    /** The handoff for whichever node is currently focused, if any. */
-    activeHandoff(): HandoffRecord | undefined;
+    updateHandoff(sessionId: string, targetNodeId: HandoffKey, transform: (record: HandoffRecord) => HandoffRecord): Promise<HandoffRecord>;
+    /** The handoff for whichever node this conversation is currently focused on. */
+    activeHandoff(sessionId: string): HandoffRecord | undefined;
     /** Every handoff, for diagnostics and tests. */
     listHandoffs(): HandoffRecord[];
-    /** The focus of the learner's active course, joined with its course and node. */
-    activeFocus(): {
+    /** This conversation's focus, joined with its course and node. */
+    activeFocus(sessionId: string): {
         focus: FocusRecord;
         course: CourseRecord;
         node: NodeRecord;
@@ -589,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>;