@kirkchinese/dsh-citeciter 0.6.0 → 0.8.0

package/lib/types/learning.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import type { TopicMessage } from './topic.ts';
+/** User-selected teaching stages; these indicate intent, never measured mastery. */
+export declare const LEARNING_STAGES: readonly [{
+    readonly id: "logic";
+    readonly label: "底层逻辑";
+    readonly shortLabel: "逻辑";
+    readonly hint: "从定义、成立条件和因果机制讲起。";
+    readonly instruction: "请讲清当前主题的底层逻辑：先给出定义和成立条件，再解释因果机制与为什么成立。区分来源证据、一般知识和假设。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "qualitative";
+    readonly label: "定性分析";
+    readonly shortLabel: "定性";
+    readonly hint: "看方向、边界，以及改变条件会发生什么。";
+    readonly instruction: "请对当前主题做定性分析：解释变量或因素之间的关系、变化方向、边界与反例，用一个具体情境说明。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "quantitative";
+    readonly label: "定量分析（板书）";
+    readonly shortLabel: "定量";
+    readonly hint: "把变量、推导和算例写到板书上。";
+    readonly instruction: "请对当前主题做定量分析，并调用 blackboard_apply 整理板书：注明变量、单位、假设、推导步骤与一个可核查算例。示例数值必须标明是假设，不得伪造来源数据。如果此主题不适合定量或信息不足，请明确说明原因。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "connections";
+    readonly label: "概念关联";
+    readonly shortLabel: "关联";
+    readonly hint: "说明它与哪些概念相连，以及为什么。";
+    readonly instruction: "请围绕当前主题给出 2–4 个最有帮助的概念关联，逐一解释是前提、推论、类比还是对比，说明关联理由与类比的边界。需要时用板书画关系。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "summary";
+    readonly label: "总结学习卡片";
+    readonly shortLabel: "总结";
+    readonly hint: "先核对与纠错，再整理成学习卡片。";
+    readonly instruction: "请先核对本 Topic 的结论与已有板书：检查定义、成立条件、推导、数值和前后矛盾，不要把此前的模型回答当作证据；必要时读取可用来源。纠正发现的错误，将无法核实的内容明确标为“未核实”或省略，不要补造来源与定位。然后调用 learning_cards 生成 1–6 张学习卡片，每张包含核心结论、一个具体例子、可选自测问题和参考答案；逐项检查这些字段的一致性，纠错必须同步到例子和参考答案。涉及来源事实时保留真实可用的定位，区分来源证据与一般知识。完成后简短说明纠正了什么、还有哪些内容未核实；不安排复习计划。";
+}];
+export type LearningStageId = typeof LEARNING_STAGES[number]['id'];
+/** Make the entire stage instruction visible and durable as an ordinary Topic user message. */
+export declare function learningQuestion(stageId: LearningStageId, question?: string): string;
+/** Recover the most recently requested stage from this Topic's own visible history. */
+export declare function latestLearningStage(messages: readonly TopicMessage[]): LearningStageId | null;
+export declare const learningCardSchema: z.ZodObject<{
+    title: z.ZodString;
+    summary: z.ZodString;
+    example: z.ZodString;
+    question: z.ZodString;
+    answer: z.ZodString;
+}, z.core.$strict>;
+export declare const learningCardsInputSchema: z.ZodObject<{
+    cards: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        summary: z.ZodString;
+        example: z.ZodString;
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LearningCard = z.infer<typeof learningCardSchema>;
+export interface LearningCardsProjection {
+    readonly cards: readonly LearningCard[];
+    /** Successful tool message owning this set, or null before any valid set exists. */
+    readonly messageId: string | null;
+    readonly invalid: number;
+}
+/**
+ * Recover the latest complete card set from successful Topic tool records.
+ * Pending, failed and malformed records cannot replace the previous valid set.
+ * No separate storage or migration is needed; older sets remain in the Topic log.
+ */
+export declare function projectLearningCards(messages: readonly TopicMessage[]): LearningCardsProjection;
+/** Export the visible set with its Topic provenance; content is plain Markdown, never executed. */
+export declare function learningCardsMarkdown(cards: readonly LearningCard[], topicTitle: string, topicId: string, source: string): string;
+/** Shared teaching contract appended to every scenario's logged tutor section. */
+export declare const LEARNING_PROMPT = "The optional learning route is \u5E95\u5C42\u903B\u8F91 \u2192 \u5B9A\u6027\u5206\u6790 \u2192 \u5B9A\u91CF\u5206\u6790\uFF08\u677F\u4E66\uFF09 \u2192 \u6982\u5FF5\u5173\u8054 \u2192 \u603B\u7ED3\u5B66\u4E60\u5361\u7247. A user may select or skip any stage. Respond to the current request only; never advance automatically or claim that a stage proves mastery. Never schedule spaced repetition or reminders. Do not require quizzes before continuing.\n\nUse learning_cards only when the user asks to summarize or revise learning cards. Before composing cards in this same turn, check the Topic's conclusions and existing board for incorrect definitions, missing conditions, faulty derivations or arithmetic, and contradictions. Earlier assistant output is not evidence. Read available sources when needed; distinguish source evidence from general knowledge. Correct errors before saving, and explicitly label unresolved claims as \u672A\u6838\u5B9E (unverified) or omit them. Check every card's summary, example, question and reference answer for consistency: a correction in the summary must also reach its example and answer. Briefly report corrections and unresolved points; do not present this self-check as independent verification.\n\nEach successful learning_cards call replaces the visible card set for this Topic; older sets remain in its log. Send the complete desired set in one call, not separate calls for individual cards. Write concise, source-grounded summaries and examples, plus a question and reference answer for optional self-testing. Preserve real available source locators inside summaries; do not invent offsets, sources or evidence. Cards and blackboard tools only record learning material inside this independent Topic; they never write to the workspace or source Session.";

package/lib/types/native-attachment-read.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+/**
+ * Read an image or verbatim file only after finding its reference in this Topic.
+ * @param ctx - the owned Agent context supplying the native attachment store.
+ * @param session - the exact Citer log authorizing the requested identity.
+ * @param id - opaque attachment identity; never interpreted as a filesystem path.
+ * @param signal - cancellation propagated to the host reader.
+ * @returns the durable image/file reference and base64 bytes for the remote client.
+ * Native readers retain byte-integrity checks. The browser materializes the complete
+ * attachment for preview/download; this operation never reads the source Session.
+ */
+export declare function readNativeAttachment(ctx: Context, session: Session, id: string, signal: AbortSignal): Promise<{
+    attachment: import("@deepseek-ai/dsh-attachment").ImageAttachmentRef;
+    data: string;
+} | {
+    attachment: import("@deepseek-ai/dsh-attachment").FileAttachmentRef;
+    data: string;
+}>;

package/lib/types/native-session-contract.d.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+export declare const nativeImageSchema: z.ZodPipe<z.ZodObject<{
+    attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+    mediaType: z.ZodEnum<{
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+        "image/gif": "image/gif";
+    }>;
+    bytes: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    originalDimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+    attachmentId: AttachmentIdType;
+    mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string | undefined;
+    originalDimensions?: {
+        width: number;
+        height: number;
+    } | undefined;
+}>>;
+/** Wire reference for an authorized attachment; generic files have no image metadata. */
+export declare const nativeAttachmentRefSchema: z.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
+    attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+    mediaType: z.ZodEnum<{
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+        "image/gif": "image/gif";
+    }>;
+    bytes: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    originalDimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+    attachmentId: AttachmentIdType;
+    mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string | undefined;
+    originalDimensions?: {
+        width: number;
+        height: number;
+    } | undefined;
+}>>, z.ZodObject<{
+    attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+    name: z.ZodString;
+    bytes: z.ZodNumber;
+}, z.core.$strict>]>;
+export declare const nativeAttachmentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    attachment: z.ZodPipe<z.ZodObject<{
+        attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+        mediaType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/webp": "image/webp";
+            "image/gif": "image/gif";
+        }>;
+        bytes: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        name: z.ZodOptional<z.ZodString>;
+        originalDimensions: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+        attachmentId: AttachmentIdType;
+        mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+        bytes: number;
+        width: number;
+        height: number;
+        name?: string | undefined;
+        originalDimensions?: {
+            width: number;
+            height: number;
+        } | undefined;
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    attachment: z.ZodObject<{
+        attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+        name: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+/** Read-only control projection. The Agent inbox remains the only authoritative queue. */
+export declare const nativeStateSchema: z.ZodObject<{
+    running: z.ZodBoolean;
+    blank: z.ZodBoolean;
+    error: z.ZodNullable<z.ZodString>;
+    queue: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        placement: z.ZodEnum<{
+            queued: "queued";
+            steering: "steering";
+            context: "context";
+        }>;
+        rpcId: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        attachments: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            attachment: z.ZodPipe<z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                mediaType: z.ZodEnum<{
+                    "image/png": "image/png";
+                    "image/jpeg": "image/jpeg";
+                    "image/webp": "image/webp";
+                    "image/gif": "image/gif";
+                }>;
+                bytes: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                name: z.ZodOptional<z.ZodString>;
+                originalDimensions: z.ZodOptional<z.ZodObject<{
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+                attachmentId: AttachmentIdType;
+                mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+                bytes: number;
+                width: number;
+                height: number;
+                name?: string | undefined;
+                originalDimensions?: {
+                    width: number;
+                    height: number;
+                } | undefined;
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            attachment: z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                name: z.ZodString;
+                bytes: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>>;
+    receipts: z.ZodArray<z.ZodObject<{
+        requestId: z.ZodString;
+        attachments: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            attachment: z.ZodPipe<z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                mediaType: z.ZodEnum<{
+                    "image/png": "image/png";
+                    "image/jpeg": "image/jpeg";
+                    "image/webp": "image/webp";
+                    "image/gif": "image/gif";
+                }>;
+                bytes: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                name: z.ZodOptional<z.ZodString>;
+                originalDimensions: z.ZodOptional<z.ZodObject<{
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+                attachmentId: AttachmentIdType;
+                mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+                bytes: number;
+                width: number;
+                height: number;
+                name?: string | undefined;
+                originalDimensions?: {
+                    width: number;
+                    height: number;
+                } | undefined;
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            attachment: z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                name: z.ZodString;
+                bytes: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NativeState = z.infer<typeof nativeStateSchema>;
+export type NativeAttachment = z.infer<typeof nativeAttachmentSchema>;

package/lib/types/native-session-read.d.ts

@@ -0,0 +1,4 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { NativeState } from './native-session-contract.ts';
+/** Read native inbox occurrences and requested admission receipts without registering a Host list row. */
+export declare function readNativeState(agent: Agent, requestIds: readonly string[]): NativeState;

package/lib/types/owned-session-cleanup.d.ts

@@ -0,0 +1,2 @@
+/** Delete a retired Topic's private backend, including its child Agents. The caller must drain the factory and verify its source ownership marker first. Never accepts the Host backend root. */
+export declare function removeOwnedSessionTree(topicDirectory: string): Promise<void>;

package/lib/types/service.d.ts

@@ -62,7 +62,7 @@ export interface CiteCiterService {
     /**
      * List Topics grouped by their source session.
      * @param sourceSessionId - source DSH Session identity.
-     * @param includeArchived - include archived Topics when true.
+     * @param includeArchived - select archived Topics when true; otherwise select active Topics.
      * @param signal - caller cancellation.
      * @returns summaries sorted by update time descending.
      */

package/lib/types/session-migration.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Copy a validated Session through public persistence handles. Resume an interrupted identical prefix; never overwrite divergent data or remove the original. Close both handles before returning. */
+export declare function copySessionHistory(source: Context['sessionPersistence'], target: Context['sessionPersistence'], sessionId: string): Promise<void>;

package/lib/types/source-session.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Session } from '@deepseek-ai/dsh-session';
+import type { ObserverSourceSnapshot } from './observer.ts';
+/** Read one consistent source cut. Release the observation even when copying fails. */
+export declare function readSourceSession(ctx: Context, id: string): Promise<ObserverSourceSnapshot>;
+/** Only an explicitly sent attachment enables later tool reads; unsent metadata grants nothing. */
+export declare function hasSentSource(session: Session | undefined, address: string): boolean;

package/lib/types/source-storage.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Locate only source-owned Citer directories through the installed JSONL backend; persisted paths are never trusted. */
+export declare class SourceStorage {
+    private readonly host;
+    private readonly pending;
+    constructor(host: Context);
+    /** @returns a canonical source/citeciter directory, optionally creating its ownership marker. */
+    root(sourceSessionId: string, create?: boolean): Promise<string | undefined>;
+    private resolveRoot;
+    /** Discover owned roots without creating directories or changing Host Session data. */
+    discover(): Promise<ReadonlyMap<string, string>>;
+}

package/lib/types/topic-index.d.ts

@@ -0,0 +1,75 @@
+import { type SessionHeader } from '@deepseek-ai/dsh-session';
+import { z } from 'zod';
+import { type TopicMetadata } from './topic.ts';
+export declare function errorCode(error: unknown): string | undefined;
+export declare function unlinkIfPresent(path: string): Promise<void>;
+export declare function rmdirIfEmpty(path: string): Promise<void>;
+/**
+ * Remove one artifact from a caller-owned JSONL root without following links.
+ * @param root - fixed private JSONL root owned by the caller.
+ * @param artifact - location returned by that exact JSONL backend.
+ * @returns when the file/link and its empty per-session directory are absent.
+ */
+export declare function removeOwnedJsonlArtifact(root: string, artifact: {
+    readonly kind: string;
+    readonly path: string;
+} | undefined): Promise<void>;
+/**
+ * Delete all JSONL generations of an already retired private Topic.
+ * DSH 0.1.5 has no public delete/location API. This bounded disk adapter follows
+ * its project/Session directory layout and canonical generation filenames.
+ * @param root - exclusively owned CiteCiter Session root, never a host Session root.
+ * @param sessionId - generated CiteCiter identity; arbitrary path segments are refused.
+ * @returns after every canonical generation and the retired lock file are absent.
+ */
+export declare function removeOwnedTopicGenerations(root: string, sessionId: string): Promise<void>;
+declare const topicDeletionMarkerSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    storage: z.ZodOptional<z.ZodLiteral<"source">>;
+    sessionId: z.ZodString;
+    sourceSessionId: z.ZodString;
+    topicId: z.ZodNumber;
+    sessionHeader: z.ZodObject<{
+        version: z.ZodNumber;
+        id: z.ZodString;
+        createdAt: z.ZodNumber;
+        isSeeded: z.ZodDefault<z.ZodBoolean>;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TopicDeletionMarker = Omit<z.infer<typeof topicDeletionMarkerSchema>, 'sessionHeader'> & {
+    readonly sessionHeader: SessionHeader;
+};
+/** Minimal on-disk navigation index; Session history stays in standard DSH JSONL. */
+export declare class TopicIndex {
+    private readonly root;
+    private readonly sourceRoots;
+    /** Bind a canonical source-owned root resolved by SourceStorage. */
+    bindSource(sourceSessionId: string, root: string): void;
+    /** Return the owned metadata directory for one source-backed Topic. */
+    ownedDirectory(sourceSessionId: string, topicId: number): string;
+    /** @param root - private Topic index root. */
+    constructor(root?: string);
+    /** Read navigation records across sources; never opens or mutates a Session log. */
+    all(includeSuperseded?: boolean): Promise<TopicMetadata[]>;
+    reserve(sourceSessionId: string): Promise<{
+        topicId: number;
+        directory: string;
+    }>;
+    save(metadata: TopicMetadata): Promise<void>;
+    loadBySessionId(sessionId: string): Promise<TopicMetadata>;
+    list(sourceSessionId: string): Promise<TopicMetadata[]>;
+    /** Commit a minimal deletion marker before making Topic metadata unreachable. */
+    markDeleting(metadata: TopicMetadata, sessionHeader: SessionHeader): Promise<TopicDeletionMarker>;
+    /** Discover committed deletion markers without following linked directories. */
+    listDeleting(): Promise<TopicDeletionMarker[]>;
+    /** Remove the marker and its now-empty Topic directory after artifact cleanup. */
+    finishDeleting(marker: TopicDeletionMarker): Promise<void>;
+    /** Forget only a superseded plugin index after an owned copy was committed; original logs remain intact. */
+    forgetLegacy(metadata: Pick<TopicMetadata, 'sessionId' | 'sourceSessionId' | 'topicId'>): Promise<void>;
+    private directory;
+    private read;
+    private readIfPresent;
+    private deletionMarkerIfPresent;
+}
+export {};

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

@@ -1,10 +1,9 @@
 import { Context } from '@deepseek-ai/cordis';
 import { SessionLogOffset, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
 import { type SessionTitleProviderRequest } from '@deepseek-ai/dsh-session-title';
-import { z } from 'zod';
 import { type BoardSnapshot } from './board.ts';
 import { type ObserverSourceSnapshot } from './observer.ts';
-import { type CiteCiterRequest, type CiteCiterResponse, type CiteCiterSettings, type CitationRecord, type TopicMessage, type TopicMetadata, type TopicMode, type TopicScenario, type TopicSummary } from './topic.ts';
+import { type CiteCiterRequest, type CiteCiterResponse, type CiteCiterSettings, type CitationRecord, type TopicMessage, type TopicMode, type TopicScenario, type TopicSummary } from './topic.ts';
 type CreateRequest = Extract<CiteCiterRequest, {
     action: 'create';
 }>;
@@ -247,55 +246,8 @@ export interface RuntimeTopicLog {
     readonly header: SessionHeader;
     readonly events: readonly SessionEvent[];
     readonly inheritedEventCount: SessionLogOffset;
-}
-/**
- * Remove one artifact from a caller-owned JSONL root without following links.
- * @param root - fixed private JSONL root owned by the caller.
- * @param artifact - location returned by that exact JSONL backend.
- * @returns when the file/link and its empty per-session directory are absent.
- */
-export declare function removeOwnedJsonlArtifact(root: string, artifact: {
-    readonly kind: string;
-    readonly path: string;
-} | undefined): Promise<void>;
-declare const topicDeletionMarkerSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    sessionId: z.ZodString;
-    sourceSessionId: z.ZodString;
-    topicId: z.ZodNumber;
-    sessionHeader: z.ZodObject<{
-        version: z.ZodNumber;
-        id: z.ZodString;
-        createdAt: z.ZodNumber;
-        isSeeded: z.ZodDefault<z.ZodBoolean>;
-        cwd: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>;
-}, z.core.$strict>;
-type TopicDeletionMarker = Omit<z.infer<typeof topicDeletionMarkerSchema>, 'sessionHeader'> & {
-    readonly sessionHeader: SessionHeader;
-};
-/** Minimal on-disk navigation index; Session history stays in standard DSH JSONL. */
-export declare class TopicIndex {
-    private readonly root;
-    /** @param root - private Topic index root. */
-    constructor(root?: string);
-    reserve(sourceSessionId: string): Promise<{
-        topicId: number;
-        directory: string;
-    }>;
-    save(metadata: TopicMetadata): Promise<void>;
-    loadBySessionId(sessionId: string): Promise<TopicMetadata>;
-    list(sourceSessionId: string): Promise<TopicMetadata[]>;
-    /** Commit a minimal deletion marker before making Topic metadata unreachable. */
-    markDeleting(metadata: TopicMetadata, sessionHeader: SessionHeader): Promise<TopicDeletionMarker>;
-    /** Discover committed deletion markers without following linked directories. */
-    listDeleting(): Promise<TopicDeletionMarker[]>;
-    /** Remove the marker and its now-empty Topic directory after artifact cleanup. */
-    finishDeleting(marker: TopicDeletionMarker): Promise<void>;
-    private directory;
-    private read;
-    private readIfPresent;
-    private deletionMarkerIfPresent;
+    readonly liveMessage?: TopicMessage | undefined;
+    readonly renderKeys?: ReadonlyMap<number, string> | undefined;
 }
 /**
  * Project transcript rows and the latest turn's active failure banner.
@@ -325,8 +277,12 @@ export declare function firstPostSeedUserQuestion(log: RuntimeTopicLog): string
  * @returns the matching question, or `null` when the request is not committed.
  */
 export declare function postSeedUserQuestionById(log: RuntimeTopicLog, messageId: string): string | null;
-/** Fold only titles created inside the private Topic, excluding inherited fork titles. */
-export declare function foldTopicTitle(metadata: TopicMetadata, events: readonly SessionEvent[]): import("@deepseek-ai/dsh-session-title").SessionTitleSnapshot | undefined;
+/**
+ * Fold child-owned titles using the restored logical prefix, including after migration.
+ * @param log - restored Topic events and the host-owned inherited event count.
+ * @returns the latest Topic title projection, or undefined before any title is recorded.
+ */
+export declare function foldTopicTitle(log: RuntimeTopicLog): import("@deepseek-ai/dsh-session-title").SessionTitleSnapshot | undefined;
 /** Resolve the actual Topic mode without forking through an open DSH turn. */
 export declare function resolveTopicModeAndSeed(requested: CreateRequest, source: ObserverSourceSnapshot, anchorSeq: number): {
     mode: TopicMode;
@@ -338,7 +294,9 @@ export declare class TopicRuntime {
     private readonly host;
     private readonly settings;
     private readonly runtime;
+    private readonly native;
     private readonly index;
+    private readonly sourceStorage;
     private readonly documents;
     private readonly lifecycleAbort;
     private readonly fibers;
@@ -359,6 +317,7 @@ export declare class TopicRuntime {
     private readonly sourceAvailabilityChecks;
     private readonly ready;
     private readonly topicListeners;
+    private readonly streams;
     private disposal;
     private releasing;
     private releaseLlm;
@@ -378,6 +337,7 @@ export declare class TopicRuntime {
      * @returns disposer removing the exact listener.
      */
     onTopicChange(listener: TopicChangeListener): () => void;
+    private readonly boardCapture;
     private executeRequest;
     /** Stop every owned Agent and plugin fiber before releasing bridged services. */
     dispose(): Promise<void>;
@@ -385,6 +345,8 @@ export declare class TopicRuntime {
     private beginClosing;
     private assertOpen;
     private start;
+    /** Adopt existing Citer histories into each source directory without deleting or rewriting their original logs. */
+    private migrateStorage;
     private releaseRuntime;
     private releaseOwnedRuntime;
     private settleOwnedOperations;
@@ -394,8 +356,10 @@ export declare class TopicRuntime {
     private createIdempotent;
     private resumeOrCreate;
     private createHandle;
+    private setupHostedAgent;
     private setupAgent;
     private globTool;
+    private learningCardsTool;
     private blackboardApplyTool;
     private readDocumentTool;
     private searchDocumentTool;
@@ -416,9 +380,9 @@ export declare class TopicRuntime {
     private archive;
     private delete;
     private deleteAdmitted;
-    /** Await JSONL retirement without populating its prepared-session cache. */
+    /** Observe the retired Session after its Agent has released write ownership. */
     private readRetiredSessionHeader;
-    /** Remove one artifact only from CiteCiter's fixed private JSONL backend. */
+    /** Remove every retired generation only from CiteCiter's fixed private JSONL backend. */
     private removeSessionArtifact;
     private finishDeletion;
     private recoverDeletions;

package/lib/types/topic-stream.d.ts

@@ -0,0 +1,14 @@
+/** Process-local Topic output; durable settlements remain owned by DSH Session. */
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+import type { TopicMessage } from './topic.ts';
+/** One Agent's ordered live stream. Dispose the instance with that Agent. */
+export declare class TopicStreamProjection {
+    private active;
+    private readonly settled;
+    /** Exact end-frame receipts keep an existing UI row mounted after durable settlement; aliases expire with this Agent. */
+    get renderKeys(): ReadonlyMap<number, string>;
+    /** @param frame - scoped Agent publication. @param nextSeq - current Session event count. */
+    accept(frame: AssistantStreamFrame, nextSeq: number): void;
+    /** @returns a detached display row, absent before visible output or after settlement. */
+    snapshot(): TopicMessage | undefined;
+}