dsh-diagnostic-tutor 0.1.0

package/lib/types/state.d.ts

@@ -0,0 +1,627 @@
+/**
+ * The persistence contract for dsh-diagnostic-tutor.
+ *
+ * This module owns one Cordis **storage domain** — the official DSH
+ * persistence seam — and nothing else. It contains no teaching logic: it
+ * stores what was observed, never what should happen next.
+ *
+ * Why a storage domain rather than files of our own:
+ *   - it is the supported seam; the profile routes it to a backend (the
+ *     standard profiles use `dsh-storage-json` under `dshHomePath('storages')`);
+ *   - **the zod schema is the contract** — every record is validated at the
+ *     durable boundary, so corrupt or hand-edited data cannot enter memory;
+ *   - reads are synchronous from memory and writes ride one per-domain write
+ *     chain, so concurrent writers cannot interleave;
+ *   - unmounting is clean: `Domain.close()` releases the backend unit.
+ *
+ * ---------------------------------------------------------------------------
+ * A refinement of the cross-version discipline (verified against source)
+ * ---------------------------------------------------------------------------
+ * The rule "import `@deepseek-ai/*` as types only" is about **stateful
+ * objects** — services, classes, instances. A second harness cohort must never
+ * supply those, because identity checks and `instanceof` would silently fail.
+ *
+ * `defineDomain` and `domainTable` are a different category: **pure builder
+ * functions**. `domainTable(schema)` is literally `{ valueSchema: schema }`,
+ * and `defineDomain(spec)` validates a spec and returns it unchanged. They
+ * take plain data and return plain data, carry no identity, and are re-exported
+ * by the host for exactly this use — the same pattern every published DSH
+ * plugin follows.
+ *
+ * The rules that still hold absolutely: never `instanceof` a returned object,
+ * and take every service instance (`DomainFacility`, `Domain`, tables) from
+ * `ctx`. Here `DomainFacility` is imported as a **type**, and the `Domain` we
+ * use is whatever the host's facility handed back.
+ */
+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 { HandoffKey, HandoffRecord } from './handoff.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
+ * document and its `initial` value gives a well-defined "never written" state.
+ *
+ * `initializedAt` is the sentinel that distinguishes "the stored profile" from
+ * "the spec's default": it is the empty string until the first write, which is
+ * what makes first-run initialization idempotent and restart-detectable.
+ *
+ * Note there is no field for proficiency, level or score. Preferences only.
+ */
+export declare const LearnerProfileSchema: z.ZodObject<{
+    preferredLanguage: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        "zero-base": "zero-base";
+        standard: "standard";
+        advanced: "advanced";
+    }>>;
+    activeCourseId: z.ZodOptional<z.ZodString>;
+    initializedAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+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<{
+    active: "active";
+    paused: "paused";
+    archived: "archived";
+}>;
+export type CourseStatus = z.infer<typeof CourseStatusSchema>;
+/**
+ * A learning goal in the learner's own words.
+ *
+ * `goal` is the verbatim statement that started the course; `title` is a short
+ * label for display. Neither is ever auto-expanded into a syllabus.
+ */
+export declare const CourseSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    goal: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+        archived: "archived";
+    }>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type CourseRecord = z.infer<typeof CourseSchema>;
+/**
+ * One observation attached to a node.
+ *
+ * Evidence records *what happened*, never how good it was. There is no score,
+ * no weight and no correctness flag — a `readiness` outcome is the skill's own
+ * six-term vocabulary, and it is optional because not every observation rises
+ * to a readiness judgement.
+ */
+export declare const EvidenceSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "goal-stated": "goal-stated";
+        diagnosis: "diagnosis";
+        explanation: "explanation";
+        practice: "practice";
+        check: "check";
+        transfer: "transfer";
+    }>;
+    at: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    readiness: z.ZodOptional<z.ZodEnum<{
+        advance: "advance";
+        "advance-with-caution": "advance-with-caution";
+        "review-first": "review-first";
+        "step-down": "step-down";
+        "diagnose-again": "diagnose-again";
+        "more-practice": "more-practice";
+    }>>;
+}, z.core.$strip>;
+export type Evidence = z.infer<typeof EvidenceSchema>;
+/**
+ * One node of the diagnosis map.
+ *
+ * Nodes are born `unconfirmed` and stay that way until evidence supports
+ * something else; see `diagnosis.ts` for the transition rules. There is no
+ * `progress`, no `weight`, no `order` and no `dueAt`: nothing here describes a
+ * schedule or a completion percentage, because the map is not a syllabus.
+ */
+export declare const NodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    courseId: z.ZodString;
+    title: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+    relation: z.ZodEnum<{
+        goal: "goal";
+        "part-of": "part-of";
+        prerequisite: "prerequisite";
+        related: "related";
+    }>;
+    state: z.ZodEnum<{
+        unconfirmed: "unconfirmed";
+        explained: "explained";
+        practiced: "practiced";
+        checked: "checked";
+        weak: "weak";
+        blocked: "blocked";
+        confirmed: "confirmed";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            "goal-stated": "goal-stated";
+            diagnosis: "diagnosis";
+            explanation: "explanation";
+            practice: "practice";
+            check: "check";
+            transfer: "transfer";
+        }>;
+        at: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+        readiness: z.ZodOptional<z.ZodEnum<{
+            advance: "advance";
+            "advance-with-caution": "advance-with-caution";
+            "review-first": "review-first";
+            "step-down": "step-down";
+            "diagnose-again": "diagnose-again";
+            "more-practice": "more-practice";
+        }>>;
+    }, z.core.$strip>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type NodeRecord = z.infer<typeof NodeSchema>;
+/**
+ * The one node being learned right now, per course.
+ *
+ * This is what makes "Start learning" an explicit act rather than an implicit
+ * one: the runtime records which node the learner asked to work on and when,
+ * and both the tutor and the panel read it from here instead of guessing.
+ *
+ * There is deliberately no `progress` field. A focus is a pointer, not a
+ * measure; how far along the learner is lives in the node's state and evidence.
+ */
+export declare const FOCUS_STATUSES: readonly ["active", "ended"];
+export declare const FocusStatusSchema: z.ZodEnum<{
+    active: "active";
+    ended: "ended";
+}>;
+export type FocusStatus = z.infer<typeof FocusStatusSchema>;
+export declare const FocusSchema: z.ZodObject<{
+    courseId: z.ZodString;
+    nodeId: z.ZodString;
+    startedAt: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        ended: "ended";
+    }>;
+    updatedAt: z.ZodString;
+    endedAt: z.ZodOptional<z.ZodString>;
+    nextStepId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FocusRecord = z.infer<typeof FocusSchema>;
+export type FocusKey = string;
+/**
+ * The tutor's decision about where the learner should go after this node.
+ *
+ * `action` is one of the skill's six readiness outcomes, reused rather than
+ * re-invented: the words for "what this concept showed" and "where that sends
+ * the learner" are the same words. See `vocabulary.ts` for what each one
+ * implies about a target.
+ *
+ * `targetNodeId` absent means **stay here**. That is the only encoding of
+ * "stay" — a named target is always a move — so the runtime never has to guess
+ * what a decision meant.
+ *
+ * `reason` is required and is written for the learner: the panel shows it
+ * verbatim, which is what makes the recommendation explicable instead of
+ * mysterious.
+ */
+export declare const NextStepSchema: z.ZodObject<{
+    fromNodeId: z.ZodString;
+    courseId: z.ZodString;
+    action: z.ZodEnum<{
+        advance: "advance";
+        "advance-with-caution": "advance-with-caution";
+        "review-first": "review-first";
+        "step-down": "step-down";
+        "diagnose-again": "diagnose-again";
+        "more-practice": "more-practice";
+    }>;
+    targetNodeId: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type NextStepRecord = z.infer<typeof NextStepSchema>;
+export type NextStepKey = string;
+/**
+ * Identifies the document, so a file found on a disk years later explains
+ * itself without this project having to be installed.
+ */
+export declare const EXPORT_FORMAT = "dsh-diagnostic-tutor/state";
+export declare const EXPORT_VERSION = 1;
+/**
+ * Everything the learner owns.
+ *
+ * Plain data, no handles and no methods: an export that needed this plugin to
+ * read it would not be an export. `format` and `version` are first so the file
+ * is self-describing, and there is no `handoffs` key on purpose — a handoff is
+ * operational timing for a wait in progress, not learning state.
+ */
+export interface UdExport {
+    readonly format: typeof EXPORT_FORMAT;
+    readonly version: number;
+    readonly exportedAt: string;
+    readonly domain: {
+        readonly name: string;
+        readonly version: number;
+    };
+    readonly learner: LearnerProfile;
+    readonly courses: readonly CourseRecord[];
+    readonly nodes: readonly NodeRecord[];
+    readonly lessons: readonly LessonRecord[];
+    readonly nextSteps: readonly NextStepRecord[];
+    readonly focus: readonly FocusRecord[];
+}
+export type CourseKey = string;
+export type NodeKey = string;
+/** Domain name. Must match the storage hub's `UNIT_NAME_RE` (`^[a-z][a-z0-9_]*$`). */
+export declare const UDT_DOMAIN_NAME = "udt";
+/**
+ * Still 1, and that is a deliberate finding rather than an oversight.
+ *
+ * v0.0.3 added the `nodes` table. That is **additive**: a v1 document simply
+ * has no `nodes` map, and the facility builds its table set from the spec, so
+ * an old document opens with an empty map.
+ *
+ * The version must NOT be bumped for an additive change, because the `single`
+ * layout enforces it strictly: `dsh-storage-json`'s `openSingleUnit` rejects a
+ * document whose stamped version differs from the spec before any compatibility
+ * list is consulted (`StorageError: unit 'udt': stored version 1 != expected 2`,
+ * `code: 'version-mismatch'`). `compatibleVersions` is honoured by `per-record`
+ * backends only. Bumping here would make every existing store unopenable —
+ * an outage in exchange for nothing.
+ *
+ * So: bump this only when a stored *record* can no longer be read as-is, and
+ * ship a migration in the same release.
+ */
+export declare const UDT_DOMAIN_VERSION = 1;
+export declare const COURSES_TABLE = "courses";
+export declare const NODES_TABLE = "nodes";
+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";
+/** Sentinel meaning "the global slot has never been written". */
+export declare const UNINITIALIZED = "";
+export declare const udtDomain: {
+    name: string;
+    version: number;
+    global: {
+        schema: z.ZodObject<{
+            preferredLanguage: z.ZodOptional<z.ZodString>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                "zero-base": "zero-base";
+                standard: "standard";
+                advanced: "advanced";
+            }>>;
+            activeCourseId: z.ZodOptional<z.ZodString>;
+            initializedAt: z.ZodString;
+            updatedAt: z.ZodString;
+        }, z.core.$strip>;
+        initial: {
+            initializedAt: string;
+            updatedAt: string;
+        };
+    };
+    tables: {
+        courses: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            title: string;
+            goal: string;
+            status: "active" | "paused" | "archived";
+            createdAt: string;
+            updatedAt: string;
+        }>;
+        nodes: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            courseId: string;
+            title: string;
+            relation: "goal" | "part-of" | "prerequisite" | "related";
+            state: "unconfirmed" | "explained" | "practiced" | "checked" | "weak" | "blocked" | "confirmed";
+            evidence: {
+                kind: "goal-stated" | "diagnosis" | "explanation" | "practice" | "check" | "transfer";
+                at: string;
+                note?: string | undefined;
+                readiness?: "advance" | "advance-with-caution" | "review-first" | "step-down" | "diagnose-again" | "more-practice" | undefined;
+            }[];
+            createdAt: string;
+            updatedAt: string;
+            parentId?: string | undefined;
+        }>;
+        lessons: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            id: string;
+            courseId: string;
+            nodeId: string;
+            title: string;
+            blocks: ({
+                type: "text";
+                content: {
+                    md: string;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+            } | {
+                type: "example";
+                content: {
+                    title: string;
+                    steps: string[];
+                    takeaway?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+            } | {
+                type: "diagram";
+                content: {
+                    format: "ascii" | "mermaid";
+                    spec: string;
+                    caption?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+            } | {
+                type: "check";
+                content: {
+                    prompt: string;
+                    expect?: "reasoning" | "answer" | undefined;
+                    hint?: string | undefined;
+                };
+                id: string;
+                metadata?: Record<string, unknown> | undefined;
+            })[];
+            origin: "prototype" | "tutor";
+            createdAt: string;
+            updatedAt: string;
+        }>;
+        focus: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            courseId: string;
+            nodeId: string;
+            startedAt: string;
+            status: "active" | "ended";
+            updatedAt: string;
+            endedAt?: string | undefined;
+            nextStepId?: string | undefined;
+        }>;
+        next_steps: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            fromNodeId: string;
+            courseId: string;
+            action: "advance" | "advance-with-caution" | "review-first" | "step-down" | "diagnose-again" | "more-practice";
+            reason: string;
+            createdAt: string;
+            targetNodeId?: string | undefined;
+        }>;
+        handoffs: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            targetNodeId: string;
+            courseId: string;
+            fromNodeId: string;
+            status: "requested" | "prompted" | "working" | "ready" | "failed";
+            attempts: number;
+            requestedAt: string;
+            updatedAt: string;
+            sessionId?: string | undefined;
+            focusRecordedAt?: string | undefined;
+            promptedAt?: string | undefined;
+            firstActivityAt?: string | undefined;
+            lessonAt?: string | undefined;
+            observedAt?: string | undefined;
+            failedAt?: string | undefined;
+            failureReason?: string | undefined;
+        }>;
+    };
+};
+export type UdtDomain = typeof udtDomain;
+/** Read-only diagnostics for the `udt_status` tool and for tests. */
+export interface UdStateSnapshot {
+    readonly domain: string;
+    readonly version: number;
+    /** Whether the global slot holds a written profile (false ⇒ never initialized). */
+    readonly initialized: boolean;
+    readonly learner: LearnerProfile;
+    readonly courseCount: number;
+    readonly nodeCount: number;
+    readonly lessonCount: number;
+    readonly courses: readonly {
+        id: string;
+        title: string;
+        status: CourseStatus;
+    }[];
+}
+/** The map for one course, as returned by `udt_map_get`. */
+export interface CourseMap {
+    readonly course: CourseRecord;
+    readonly nodes: readonly NodeRecord[];
+}
+/**
+ * The plugin's whole persistence surface.
+ *
+ * Nothing outside this module touches the `Domain` handle, so changing the
+ * storage layout later is a change in one file. Every write returns the stored
+ * record so callers never have to re-read.
+ */
+export interface UdState {
+    readonly name: string;
+    readonly version: number;
+    /** Synchronous read of the learner singleton. */
+    readLearner(): LearnerProfile;
+    /** Whether the learner singleton has ever been written. */
+    isInitialized(): boolean;
+    /**
+     * Write the learner singleton on first open, and do nothing on later opens.
+     * @param now - ISO timestamp supplied by the caller so the write is testable.
+     */
+    ensureLearner(now: string): Promise<LearnerProfile>;
+    /**
+     * Merge a patch into the learner singleton and write it durably.
+     * @param patch - fields to overwrite; omitted fields are preserved.
+     * @param now - ISO timestamp for `updatedAt`.
+     */
+    updateLearner(patch: Partial<Omit<LearnerProfile, 'initializedAt' | 'updatedAt'>>, now: string): Promise<LearnerProfile>;
+    listCourses(): CourseRecord[];
+    readCourse(id: CourseKey): CourseRecord | undefined;
+    /** Insert or fully replace one course. */
+    writeCourse(record: CourseRecord): Promise<CourseRecord>;
+    /**
+     * Make one course active: it becomes `active`, every other course that was
+     * active becomes `paused`, and the learner's `activeCourseId` points at it.
+     *
+     * Only one goal is in focus at a time. Pausing is reversible — the other
+     * courses keep their records and all of their nodes.
+     *
+     * @param courseId - the course to focus.
+     * @param now - ISO timestamp.
+     * @returns the activated course.
+     */
+    activateCourse(courseId: CourseKey, now: string): Promise<CourseRecord>;
+    /** Every node of one course, in insertion order. */
+    listNodes(courseId: CourseKey): NodeRecord[];
+    readNode(id: NodeKey): NodeRecord | undefined;
+    /** Insert or fully replace one node. */
+    writeNode(record: 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;
+    /**
+     * Record that learning is starting on one node of one course.
+     *
+     * Fails loudly when the course or the node does not exist, or when the node
+     * belongs to another course — a focus pointing at nothing would leave the
+     * tutor teaching a node the map does not have.
+     *
+     * @param courseId - the course.
+     * @param nodeId - the node to focus.
+     * @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>;
+    /**
+     * Record the tutor's decision about where to go next.
+     *
+     * This is the one place the focus lifecycle turns over: a decision that names
+     * a target ends the focus and links the recommendation to it; a decision that
+     * does not leaves the focus active, because the learner has not moved.
+     *
+     * The runtime validates the *shape* of the decision — the nodes must exist,
+     * belong to the course, and match what the action implies — and never invents
+     * a target. Choosing where to go is the tutor's.
+     *
+     * @param input - the decision.
+     * @returns the stored recommendation and the focus after the decision.
+     */
+    decideNext(input: {
+        courseId: CourseKey;
+        fromNodeId: NodeKey;
+        action: Readiness;
+        targetNodeId?: NodeKey;
+        reason: string;
+        now: 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;
+    /** Every recommendation, for export. */
+    listNextSteps(): NextStepRecord[];
+    /** Every lesson, for export. */
+    listLessons(): LessonRecord[];
+    /** Every focus, for export. */
+    listFocus(): FocusRecord[];
+    /**
+     * Everything the learner owns, as one plain document.
+     *
+     * Handoffs are deliberately **not** included: they are operational timing
+     * for a wait in progress, not learning state, and restoring them would mean
+     * restoring a claim about a model turn that is no longer running.
+     */
+    exportState(now: string): UdExport;
+    /**
+     * Delete everything and return to first-run.
+     *
+     * Irreversible by design — an undo would mean keeping a copy of what the
+     * learner asked to delete, which is the opposite of the point.
+     */
+    resetState(now: string): Promise<void>;
+    readHandoff(targetNodeId: HandoffKey): HandoffRecord | undefined;
+    /** Insert or replace one handoff. */
+    writeHandoff(record: HandoffRecord): Promise<HandoffRecord>;
+    /**
+     * Apply a transition atomically.
+     *
+     * Two writers touch a handoff concurrently in normal operation — the
+     * first-activity listener and the tool that writes a lesson — and a plain
+     * read-modify-write loses one of them. The domain's `update` runs the
+     * transform on its single write chain, so the transitions serialise.
+     *
+     * @param targetNodeId - the handoff.
+     * @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;
+    /** Every handoff, for diagnostics and tests. */
+    listHandoffs(): HandoffRecord[];
+    /** The focus of the learner's active course, joined with its course and node. */
+    activeFocus(): {
+        focus: FocusRecord;
+        course: CourseRecord;
+        node: NodeRecord;
+    } | undefined;
+    readLesson(id: LessonKey): LessonRecord | undefined;
+    /** The lesson already stored for a node, if any. */
+    lessonForNode(nodeId: NodeKey): LessonRecord | undefined;
+    /** Insert or fully replace one lesson. */
+    writeLesson(record: LessonRecord): Promise<LessonRecord>;
+    /** Number of lessons across every course. */
+    lessonCount(): number;
+    snapshot(): UdStateSnapshot;
+    /** Release the backend unit. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Build a fresh node in its born state.
+ *
+ * Kept here rather than in the tool layer so the "nothing is born confirmed"
+ * rule has exactly one implementation.
+ *
+ * @param input - the fields the caller supplies.
+ * @returns a complete, valid record.
+ */
+export declare function newNode(input: {
+    id: string;
+    courseId: string;
+    title: string;
+    relation: NodeRelation;
+    parentId?: string;
+    state?: NodeState;
+    evidence?: Evidence[];
+    now: string;
+}): NodeRecord;
+/**
+ * Open the plugin's domain over the host's facility.
+ *
+ * The caller owns the returned handle and must `close()` it — see `apply`,
+ * which does so from a `ctx.effect` disposer so an unload leaves no residue.
+ *
+ * @param facility - the `storageDomain` service taken from `ctx`.
+ * @returns the open handle.
+ */
+export declare function openUdState(facility: DomainFacility): Promise<UdState>;
+//# sourceMappingURL=state.d.ts.map

package/lib/types/state.d.ts.map

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

package/lib/types/tools.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Model-facing tools.
+ *
+ * v0.0.3 registers four, and the restraint is the architecture: this plugin
+ * owns **state, artifacts and presentation**, while every teaching decision
+ * belongs to the Universal Diagnostic Tutor skill. So each tool here either
+ * records what was observed or reports what is stored. None of them decides
+ * what to teach, how to explain it, or when to advance.
+ *
+ * That is also why the rules in `diagnosis.ts` are enforced *here* rather than
+ * negotiated with the caller: the runtime's job is to make unverified mastery
+ * and curriculum dumps impossible to store, and then get out of the way.
+ *
+ * As in `state.ts`, `defineTool` is a *pure builder* (it compiles the parameter
+ * DSL into JSON Schema and returns a plain descriptor), so it is
+ * value-imported. The registry itself is taken from `ctx`.
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { UdState } from './state.js';
+/**
+ * The slice of `ctx` this module needs.
+ *
+ * Declared structurally on purpose: we depend on the *shape* of the tools
+ * registry, not on a class we might `instanceof` across harness cohorts.
+ */
+export interface ToolsHost {
+    tools: {
+        register(definition: ToolDefinition): unknown;
+    };
+}
+/**
+ * Register this plugin's tools on the host's registry.
+ *
+ * @param host - the context slice carrying the tools registry.
+ * @param state - the open persistence handle the tools read from and write to.
+ */
+export declare function registerTools(host: ToolsHost, state: UdState): void;
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAe5D,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,YAAY,CAAA;AAU/D;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAAA;KAAE,CAAA;CACzD;AA+iCD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAOnE"}