dsh-diagnostic-tutor 0.1.0 → 0.2.0

package/lib/types/path-runtime.d.ts

@@ -0,0 +1,1558 @@
+import type { UdState } from './state.js';
+import type { LessonRecord } from './lesson.js';
+import type { PathView } from './path.js';
+export declare function pathView(state: UdState, courseId: string, sessionId?: string): PathView;
+export declare function selectedProject(state: UdState, courseId: string, sessionId: string | undefined): asserts sessionId is string;
+export declare function saveBrief(state: UdState, courseId: string, sessionId: string, expectedRevision: number, raw: unknown): Promise<{
+    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;
+}>;
+export declare function saveAssessment(state: UdState, courseId: string, sessionId: string, expectedRevision: number, raw: unknown, allowSkip?: boolean): Promise<{
+    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;
+}>;
+export declare function proposeCurriculum(state: UdState, courseId: string, sessionId: string, expectedRevision: number, raw: unknown): Promise<{
+    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;
+}>;
+export declare function acceptCurriculum(state: UdState, courseId: string, sessionId: string, expectedRevision: number, version: number): Promise<{
+    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;
+}>;
+export declare function reservePathRequest(state: UdState, input: {
+    courseId: string;
+    sessionId: string;
+    expectedRevision: number;
+    kind: 'diagnosis' | 'plan';
+    operationId: string;
+}): Promise<{
+    shouldPrompt: boolean;
+    prompt: string;
+    request: {
+        id: string;
+        sessionId: string;
+        kind: "diagnosis" | "plan";
+        briefRevision: number;
+        createdAt: string;
+        prompted: boolean;
+        reason: string | null;
+        failure?: string | null | undefined;
+    };
+}>;
+/**
+ * Record that the tutor turn behind a path request failed.
+ *
+ * The browser's own session snapshot is memory-only, so it cannot explain a
+ * failed turn after a restart. This stamps the durable request record instead:
+ * only the newest prompted request from that conversation, and only while its
+ * result is still missing. A diagnosis that was already recorded, or another
+ * conversation's request, is never touched — a later unrelated agent error in
+ * the same chat must not mislabel a finished diagnosis.
+ *
+ * @param state - state handle.
+ * @param sessionId - the conversation whose turn failed.
+ * @param reason - the error message shown to the learner.
+ */
+export declare function stampPathRequestFailure(state: UdState, sessionId: string, reason: string): Promise<void>;
+export declare function stampPathRequest(state: UdState, courseId: string, sessionId: string, id: string, prompted: boolean, reason?: string): Promise<void>;
+export interface BeginItemInput {
+    courseId: string;
+    sessionId: string;
+    expectedRevision: number;
+    version: number;
+    itemId: string;
+    operationId: string;
+    review?: boolean | undefined;
+    resume?: boolean | undefined;
+    checkin?: boolean | undefined;
+    teachBack?: boolean | undefined;
+}
+export declare function beginCourseItem(state: UdState, input: BeginItemInput): Promise<{
+    run: {
+        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;
+    };
+    attempt: {
+        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;
+    };
+    shouldPrompt: boolean;
+    prompt: string;
+}>;
+export interface PauseItemInput {
+    courseId: string;
+    sessionId: string;
+    expectedRevision: number;
+}
+/** Mark the current attempt paused without ending it. `interrupted` is the existing attempt state. */
+export declare function pauseCourseItem(state: UdState, input: PauseItemInput): Promise<PathView>;
+export declare function stampCoursePrompt(state: UdState, input: BeginItemInput, attemptId: string, prompted: boolean, reason?: string): Promise<void>;
+export declare function requireAttempt(state: UdState, courseId: string, sessionId: string | undefined, attemptId: string): {
+    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;
+};
+export declare function bindCourseNode(state: UdState, courseId: string, sessionId: string, attemptId: string, nodeId: string): Promise<void>;
+export declare function recordCourseTeaching(state: UdState, courseId: string, sessionId: string, attemptId: string, lesson: LessonRecord): Promise<{
+    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;
+}>;
+/** Merge against the latest committed unit while holding the run/project queue. The builder must not enqueue writes. */
+export declare function writeCourseTeaching(state: UdState, courseId: string, sessionId: string, attemptId: string, nodeId: string, build: (current: LessonRecord | undefined) => LessonRecord): Promise<{
+    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;
+}>;
+export declare function completeCourseItem(state: UdState, courseId: string, sessionId: string, attemptId: string, reason: string, rawRefs: unknown): Promise<{
+    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;
+}>;
+//# sourceMappingURL=path-runtime.d.ts.map