@kirkchinese/dsh-citeciter 0.4.3 → 0.5.0

package/lib/types/topic.d.ts

@@ -1,8 +1,10 @@
 import { z } from 'zod';
-/** Durable Citation version used by Observer Topics. */
-export declare const CITATION_SCHEMA_VERSION: 3;
-/** Navigation metadata version. Chat history remains in the DSH Session log. */
-export declare const TOPIC_METADATA_SCHEMA_VERSION: 1;
+/** Durable Citation version used by Observer Topics. v4 adds the EvidenceRef entry discriminator. */
+export declare const CITATION_SCHEMA_VERSION: 4;
+/** Navigation metadata version. v2 permits source-bound Topics without a selected Citation. */
+export declare const TOPIC_METADATA_SCHEMA_VERSION: 2;
+/** Scenario applied when neither the creator nor the stored metadata selects one. */
+export declare const DEFAULT_TOPIC_SCENARIO: "qa";
 /** Host settings namespace mirrored by the browser settings scope. */
 export declare const CITECITER_SETTINGS_NAMESPACE: "citeciter";
 /** Topic-scoped system prompt section. */
@@ -14,6 +16,25 @@ export declare const topicModeSchema: z.ZodEnum<{
     "exact-fork": "exact-fork";
 }>;
 export type TopicMode = z.infer<typeof topicModeSchema>;
+/**
+ * Topic turn-content scenario. Orthogonal to {@link TopicMode}: mode describes
+ * the source-session timing relation, scenario selects the assembled tool set,
+ * prompt sections, and future loop decorations for this Topic.
+ */
+export declare const topicScenarioSchema: z.ZodEnum<{
+    qa: "qa";
+    present: "present";
+    read: "read";
+    investigate: "investigate";
+}>;
+export type TopicScenario = z.infer<typeof topicScenarioSchema>;
+/** One user-editable prompt template shown beside the selection popover. */
+export declare const promptTemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type PromptTemplate = z.infer<typeof promptTemplateSchema>;
 /** User preferences applied to new Topics and source reads. */
 export declare const citeCiterSettingsSchema: z.ZodObject<{
     defaultMode: z.ZodEnum<{
@@ -24,6 +45,16 @@ export declare const citeCiterSettingsSchema: z.ZodObject<{
     allowSourceFiles: z.ZodBoolean;
     panelWidthPercent: z.ZodNumber;
     reopenLastTopic: z.ZodBoolean;
+    tutorPrompt: z.ZodOptional<z.ZodString>;
+    followupQuestions: z.ZodOptional<z.ZodBoolean>;
+    promptTemplates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strict>>>;
+    shortcutOpenPanel: z.ZodOptional<z.ZodString>;
+    boardAnimations: z.ZodOptional<z.ZodBoolean>;
+    updateNotifications: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type CiteCiterSettings = z.infer<typeof citeCiterSettingsSchema>;
 /** Settings used before an optional DSH settings provider becomes available. */
@@ -52,7 +83,64 @@ export declare const citationDraftSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** Exact Citation retained for durable data and legacy 0.3.1 requests. */
 export type CitationDraft = z.infer<typeof citationDraftSchema>;
+/**
+ * Evidence anchor discriminator for one durable Citation. `anchorSeq` mirrors
+ * the record-level coordinate; the canonical schema enforces equality.
+ */
+export declare const citationEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"assistant-message">;
+    anchorSeq: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool-result">;
+    anchorSeq: z.ZodNumber;
+    callId: z.ZodString;
+    toolName: z.ZodString;
+    projection: z.ZodEnum<{
+        "result-text": "result-text";
+        terminal: "terminal";
+        diff: "diff";
+    }>;
+    fileIndex: z.ZodOptional<z.ZodNumber>;
+    side: z.ZodOptional<z.ZodEnum<{
+        old: "old";
+        new: "new";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"document-range">;
+    documentId: z.ZodString;
+    startOffset: z.ZodNumber;
+    endOffset: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+/** One anchor kind plus the tool-result coordinates that identify the evidence. */
+export type CitationEntry = z.infer<typeof citationEntrySchema>;
+/** Canonical v4 Citation: the shared text projection plus one EvidenceRef entry. */
 export declare const citationRecordSchema: z.ZodObject<{
+    entry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"assistant-message">;
+        anchorSeq: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"tool-result">;
+        anchorSeq: z.ZodNumber;
+        callId: z.ZodString;
+        toolName: z.ZodString;
+        projection: z.ZodEnum<{
+            "result-text": "result-text";
+            terminal: "terminal";
+            diff: "diff";
+        }>;
+        fileIndex: z.ZodOptional<z.ZodNumber>;
+        side: z.ZodOptional<z.ZodEnum<{
+            old: "old";
+            new: "new";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"document-range">;
+        documentId: z.ZodString;
+        startOffset: z.ZodNumber;
+        endOffset: z.ZodNumber;
+    }, z.core.$strict>], "kind">;
+    selectionFingerprint: z.ZodString;
+    createdAt: z.ZodNumber;
     sourceSessionId: z.ZodString;
     anchorSeq: z.ZodNumber;
     startOffset: z.ZodNumber;
@@ -61,12 +149,63 @@ export declare const citationRecordSchema: z.ZodObject<{
     displayText: z.ZodString;
     prefixText: z.ZodString;
     suffixText: z.ZodString;
+    schemaVersion: z.ZodLiteral<4>;
+}, z.core.$strict>;
+/** Immutable EvidenceRef identity owned by one Topic. */
+export type CitationRecord = z.infer<typeof citationRecordSchema>;
+/** Verified evidence fields before the durable record adds version, time, and fingerprint. */
+export type CitationEvidence = Omit<CitationRecord, 'schemaVersion' | 'createdAt' | 'selectionFingerprint'>;
+/** On-disk Citation written by v3 (no entry) or v4. */
+declare const citationRecordFileSchema: z.ZodObject<{
+    entry: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"assistant-message">;
+        anchorSeq: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"tool-result">;
+        anchorSeq: z.ZodNumber;
+        callId: z.ZodString;
+        toolName: z.ZodString;
+        projection: z.ZodEnum<{
+            "result-text": "result-text";
+            terminal: "terminal";
+            diff: "diff";
+        }>;
+        fileIndex: z.ZodOptional<z.ZodNumber>;
+        side: z.ZodOptional<z.ZodEnum<{
+            old: "old";
+            new: "new";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"document-range">;
+        documentId: z.ZodString;
+        startOffset: z.ZodNumber;
+        endOffset: z.ZodNumber;
+    }, z.core.$strict>], "kind">>;
     selectionFingerprint: z.ZodString;
-    schemaVersion: z.ZodLiteral<3>;
     createdAt: z.ZodNumber;
+    sourceSessionId: z.ZodString;
+    anchorSeq: z.ZodNumber;
+    startOffset: z.ZodNumber;
+    endOffset: z.ZodNumber;
+    sourceText: z.ZodString;
+    displayText: z.ZodString;
+    prefixText: z.ZodString;
+    suffixText: z.ZodString;
+    schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>]>;
 }, z.core.$strict>;
-/** Immutable evidence identity owned by one Topic. */
-export type CitationRecord = z.infer<typeof citationRecordSchema>;
+type CitationRecordFile = z.infer<typeof citationRecordFileSchema>;
+/**
+ * Normalize one durable Citation file record to canonical v4.
+ * @param raw - parsed v3 or v4 file record.
+ * @returns canonical v4 record; v3 synthesizes its assistant-message entry.
+ */
+export declare function normalizeCitationRecord(raw: CitationRecordFile): CitationRecord;
+/**
+ * Parse a durable Citation written by v3 or v4.
+ * @param raw - stored Citation value.
+ * @returns canonical v4 CitationRecord.
+ */
+export declare function parseCitationRecord(raw: unknown): CitationRecord;
 export declare const modelConfigSchema: z.ZodObject<{
     provider: z.ZodString;
     model: z.ZodString;
@@ -76,8 +215,52 @@ export declare const modelConfigSchema: z.ZodObject<{
     stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type TopicModelConfig = z.infer<typeof modelConfigSchema>;
+/** Canonical Topic metadata committed by the current runtime. */
 export declare const topicMetadataSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
+    citation: z.ZodNullable<z.ZodObject<{
+        entry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"assistant-message">;
+            anchorSeq: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"tool-result">;
+            anchorSeq: z.ZodNumber;
+            callId: z.ZodString;
+            toolName: z.ZodString;
+            projection: z.ZodEnum<{
+                "result-text": "result-text";
+                terminal: "terminal";
+                diff: "diff";
+            }>;
+            fileIndex: z.ZodOptional<z.ZodNumber>;
+            side: z.ZodOptional<z.ZodEnum<{
+                old: "old";
+                new: "new";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"document-range">;
+            documentId: z.ZodString;
+            startOffset: z.ZodNumber;
+            endOffset: z.ZodNumber;
+        }, z.core.$strict>], "kind">;
+        selectionFingerprint: z.ZodString;
+        createdAt: z.ZodNumber;
+        sourceSessionId: z.ZodString;
+        anchorSeq: z.ZodNumber;
+        startOffset: z.ZodNumber;
+        endOffset: z.ZodNumber;
+        sourceText: z.ZodString;
+        displayText: z.ZodString;
+        prefixText: z.ZodString;
+        suffixText: z.ZodString;
+        schemaVersion: z.ZodLiteral<4>;
+    }, z.core.$strict>>;
+    scenario: z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+        read: "read";
+        investigate: "investigate";
+    }>;
+    documentId: z.ZodNullable<z.ZodString>;
     topicId: z.ZodNumber;
     createRequestId: z.ZodOptional<z.ZodString>;
     sessionId: z.ZodString;
@@ -87,19 +270,6 @@ export declare const topicMetadataSchema: z.ZodObject<{
         observer: "observer";
         "exact-fork": "exact-fork";
     }>;
-    citation: z.ZodObject<{
-        sourceSessionId: z.ZodString;
-        anchorSeq: z.ZodNumber;
-        startOffset: z.ZodNumber;
-        endOffset: z.ZodNumber;
-        sourceText: z.ZodString;
-        displayText: z.ZodString;
-        prefixText: z.ZodString;
-        suffixText: z.ZodString;
-        selectionFingerprint: z.ZodString;
-        schemaVersion: z.ZodLiteral<3>;
-        createdAt: z.ZodNumber;
-    }, z.core.$strict>;
     modelConfig: z.ZodObject<{
         provider: z.ZodString;
         model: z.ZodString;
@@ -122,9 +292,17 @@ export declare const topicMetadataSchema: z.ZodObject<{
     archivedAt: z.ZodNullable<z.ZodNumber>;
     sourceAvailable: z.ZodBoolean;
     observedThroughSeq: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    schemaVersion: z.ZodLiteral<2>;
 }, z.core.$strict>;
 /** Small navigation record stored outside the standard Topic Session log. */
 export type TopicMetadata = z.infer<typeof topicMetadataSchema>;
+/**
+ * Parse one on-disk Topic metadata record, normalizing legacy v3 Citations and
+ * missing scenario/document fields to their current defaults.
+ * @param raw - stored metadata value.
+ * @returns canonical TopicMetadata.
+ */
+export declare function parseTopicMetadataFile(raw: unknown): TopicMetadata;
 export declare const topicSummarySchema: z.ZodObject<{
     topicId: z.ZodNumber;
     sessionId: z.ZodString;
@@ -133,7 +311,40 @@ export declare const topicSummarySchema: z.ZodObject<{
         observer: "observer";
         "exact-fork": "exact-fork";
     }>;
-    citation: z.ZodObject<{
+    scenario: z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+        read: "read";
+        investigate: "investigate";
+    }>;
+    documentId: z.ZodNullable<z.ZodString>;
+    citation: z.ZodNullable<z.ZodObject<{
+        entry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"assistant-message">;
+            anchorSeq: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"tool-result">;
+            anchorSeq: z.ZodNumber;
+            callId: z.ZodString;
+            toolName: z.ZodString;
+            projection: z.ZodEnum<{
+                "result-text": "result-text";
+                terminal: "terminal";
+                diff: "diff";
+            }>;
+            fileIndex: z.ZodOptional<z.ZodNumber>;
+            side: z.ZodOptional<z.ZodEnum<{
+                old: "old";
+                new: "new";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"document-range">;
+            documentId: z.ZodString;
+            startOffset: z.ZodNumber;
+            endOffset: z.ZodNumber;
+        }, z.core.$strict>], "kind">;
+        selectionFingerprint: z.ZodString;
+        createdAt: z.ZodNumber;
         sourceSessionId: z.ZodString;
         anchorSeq: z.ZodNumber;
         startOffset: z.ZodNumber;
@@ -142,10 +353,8 @@ export declare const topicSummarySchema: z.ZodObject<{
         displayText: z.ZodString;
         prefixText: z.ZodString;
         suffixText: z.ZodString;
-        selectionFingerprint: z.ZodString;
-        schemaVersion: z.ZodLiteral<3>;
-        createdAt: z.ZodNumber;
-    }, z.core.$strict>;
+        schemaVersion: z.ZodLiteral<4>;
+    }, z.core.$strict>>;
     title: z.ZodString;
     titlePending: z.ZodBoolean;
     createdAt: z.ZodNumber;
@@ -249,7 +458,40 @@ export declare const topicSnapshotSchema: z.ZodObject<{
             observer: "observer";
             "exact-fork": "exact-fork";
         }>;
-        citation: z.ZodObject<{
+        scenario: z.ZodEnum<{
+            qa: "qa";
+            present: "present";
+            read: "read";
+            investigate: "investigate";
+        }>;
+        documentId: z.ZodNullable<z.ZodString>;
+        citation: z.ZodNullable<z.ZodObject<{
+            entry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"assistant-message">;
+                anchorSeq: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"tool-result">;
+                anchorSeq: z.ZodNumber;
+                callId: z.ZodString;
+                toolName: z.ZodString;
+                projection: z.ZodEnum<{
+                    "result-text": "result-text";
+                    terminal: "terminal";
+                    diff: "diff";
+                }>;
+                fileIndex: z.ZodOptional<z.ZodNumber>;
+                side: z.ZodOptional<z.ZodEnum<{
+                    old: "old";
+                    new: "new";
+                }>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"document-range">;
+                documentId: z.ZodString;
+                startOffset: z.ZodNumber;
+                endOffset: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+            selectionFingerprint: z.ZodString;
+            createdAt: z.ZodNumber;
             sourceSessionId: z.ZodString;
             anchorSeq: z.ZodNumber;
             startOffset: z.ZodNumber;
@@ -258,10 +500,8 @@ export declare const topicSnapshotSchema: z.ZodObject<{
             displayText: z.ZodString;
             prefixText: z.ZodString;
             suffixText: z.ZodString;
-            selectionFingerprint: z.ZodString;
-            schemaVersion: z.ZodLiteral<3>;
-            createdAt: z.ZodNumber;
-        }, z.core.$strict>;
+            schemaVersion: z.ZodLiteral<4>;
+        }, z.core.$strict>>;
         title: z.ZodString;
         titlePending: z.ZodBoolean;
         createdAt: z.ZodNumber;
@@ -332,6 +572,44 @@ export declare const topicSnapshotSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>;
     error: z.ZodNullable<z.ZodString>;
+    board: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<4>;
+        revision: z.ZodNumber;
+        elements: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                text: "text";
+                markdown: "markdown";
+                math: "math";
+                svg: "svg";
+                html: "html";
+                image: "image";
+                table: "table";
+            }>;
+            content: z.ZodString;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            w: z.ZodNumber;
+            h: z.ZodNumber;
+            style: z.ZodObject<{
+                color: z.ZodOptional<z.ZodString>;
+                fontSize: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            focused: z.ZodBoolean;
+            animation: z.ZodOptional<z.ZodObject<{
+                name: z.ZodEnum<{
+                    "fade-in": "fade-in";
+                    "slide-in": "slide-in";
+                    pulse: "pulse";
+                    highlight: "highlight";
+                }>;
+                durationMs: z.ZodNumber;
+                iterations: z.ZodNumber;
+                run: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        invalid: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TopicSnapshot = z.infer<typeof topicSnapshotSchema>;
 export declare const modelOptionSchema: z.ZodObject<{
@@ -357,8 +635,71 @@ export declare const providerOptionSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ProviderOption = z.infer<typeof providerOptionSchema>;
+/** Whole-card tool-result claim; the Host verifies it against the committed `tool/result`. */
+export declare const toolEvidenceClaimSchema: z.ZodObject<{
+    sourceSessionId: z.ZodString;
+    callId: z.ZodString;
+    displayText: z.ZodString;
+    projection: z.ZodOptional<z.ZodEnum<{
+        "result-text": "result-text";
+        terminal: "terminal";
+        diff: "diff";
+    }>>;
+}, z.core.$strict>;
+/** Browser-submitted claim that anchors one Topic on a committed tool result. */
+export type ToolEvidenceClaim = z.infer<typeof toolEvidenceClaimSchema>;
+/** Browser-submitted claim that anchors one Topic on a CiteCiter document range. */
+export declare const documentEvidenceClaimSchema: z.ZodObject<{
+    sourceSessionId: z.ZodString;
+    documentId: z.ZodString;
+    displayText: z.ZodString;
+    prefixText: z.ZodString;
+    suffixText: z.ZodString;
+}, z.core.$strict>;
+/** Browser claim whose offsets the Host re-resolves against the stored document text. */
+export type DocumentEvidenceClaim = z.infer<typeof documentEvidenceClaimSchema>;
+/** Document format accepted by the CiteCiter private document library. */
+export declare const documentFormatSchema: z.ZodEnum<{
+    text: "text";
+    markdown: "markdown";
+}>;
+export type DocumentFormat = z.infer<typeof documentFormatSchema>;
+/** Document-library metadata exposed to the Reader and document Topics. */
+export declare const documentSummarySchema: z.ZodObject<{
+    documentId: z.ZodString;
+    title: z.ZodString;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+    }>;
+    size: z.ZodNumber;
+    importedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type DocumentSummary = z.infer<typeof documentSummarySchema>;
+/** Bounded document content page returned to the Reader. */
+export declare const documentContentSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    title: z.ZodString;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+    }>;
+    content: z.ZodString;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+export type DocumentContent = z.infer<typeof documentContentSchema>;
 /** One strict direct-RPC command for the private CiteCiter runtime. */
 export declare const citeCiterRequestSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+    action: z.ZodLiteral<"create">;
+    requestId: z.ZodString;
+    sourceSessionId: z.ZodString;
+    question: z.ZodString;
+    mode: z.ZodLiteral<"observer">;
+    scenario: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
     action: z.ZodLiteral<"create">;
     requestId: z.ZodString;
     citation: z.ZodObject<{
@@ -378,6 +719,12 @@ export declare const citeCiterRequestSchema: z.ZodUnion<readonly [z.ZodUnion<rea
         "exact-fork": "exact-fork";
         "exact-when-available": "exact-when-available";
     }>;
+    scenario: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+        read: "read";
+        investigate: "investigate";
+    }>>;
 }, z.core.$strict>, z.ZodObject<{
     action: z.ZodLiteral<"create">;
     requestId: z.ZodString;
@@ -395,6 +742,59 @@ export declare const citeCiterRequestSchema: z.ZodUnion<readonly [z.ZodUnion<rea
         "exact-fork": "exact-fork";
         "exact-when-available": "exact-when-available";
     }>;
+    scenario: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+        read: "read";
+        investigate: "investigate";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"create">;
+    requestId: z.ZodString;
+    toolClaim: z.ZodObject<{
+        sourceSessionId: z.ZodString;
+        callId: z.ZodString;
+        displayText: z.ZodString;
+        projection: z.ZodOptional<z.ZodEnum<{
+            "result-text": "result-text";
+            terminal: "terminal";
+            diff: "diff";
+        }>>;
+    }, z.core.$strict>;
+    question: z.ZodString;
+    mode: z.ZodEnum<{
+        observer: "observer";
+        "exact-fork": "exact-fork";
+        "exact-when-available": "exact-when-available";
+    }>;
+    scenario: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+        read: "read";
+        investigate: "investigate";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"create">;
+    requestId: z.ZodString;
+    documentClaim: z.ZodObject<{
+        sourceSessionId: z.ZodString;
+        documentId: z.ZodString;
+        displayText: z.ZodString;
+        prefixText: z.ZodString;
+        suffixText: z.ZodString;
+    }, z.core.$strict>;
+    question: z.ZodString;
+    mode: z.ZodEnum<{
+        observer: "observer";
+        "exact-fork": "exact-fork";
+        "exact-when-available": "exact-when-available";
+    }>;
+    scenario: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
+        present: "present";
+        read: "read";
+        investigate: "investigate";
+    }>>;
 }, z.core.$strict>]>, z.ZodDiscriminatedUnion<[z.ZodObject<{
     action: z.ZodLiteral<"list">;
     sourceSessionId: z.ZodString;
@@ -454,6 +854,20 @@ export declare const citeCiterRequestSchema: z.ZodUnion<readonly [z.ZodUnion<rea
     provider: z.ZodString;
     model: z.ZodString;
     reasoningEffort: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"document-import">;
+    requestId: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+    }>;
+    content: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"documents">;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"document-get">;
+    documentId: z.ZodString;
 }, z.core.$strict>], "action">]>;
 export type CiteCiterRequest = z.infer<typeof citeCiterRequestSchema>;
 /** Strict response union returned by the single Remote command endpoint. */
@@ -468,7 +882,40 @@ export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                 observer: "observer";
                 "exact-fork": "exact-fork";
             }>;
-            citation: z.ZodObject<{
+            scenario: z.ZodEnum<{
+                qa: "qa";
+                present: "present";
+                read: "read";
+                investigate: "investigate";
+            }>;
+            documentId: z.ZodNullable<z.ZodString>;
+            citation: z.ZodNullable<z.ZodObject<{
+                entry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"assistant-message">;
+                    anchorSeq: z.ZodNumber;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"tool-result">;
+                    anchorSeq: z.ZodNumber;
+                    callId: z.ZodString;
+                    toolName: z.ZodString;
+                    projection: z.ZodEnum<{
+                        "result-text": "result-text";
+                        terminal: "terminal";
+                        diff: "diff";
+                    }>;
+                    fileIndex: z.ZodOptional<z.ZodNumber>;
+                    side: z.ZodOptional<z.ZodEnum<{
+                        old: "old";
+                        new: "new";
+                    }>>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"document-range">;
+                    documentId: z.ZodString;
+                    startOffset: z.ZodNumber;
+                    endOffset: z.ZodNumber;
+                }, z.core.$strict>], "kind">;
+                selectionFingerprint: z.ZodString;
+                createdAt: z.ZodNumber;
                 sourceSessionId: z.ZodString;
                 anchorSeq: z.ZodNumber;
                 startOffset: z.ZodNumber;
@@ -477,10 +924,8 @@ export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                 displayText: z.ZodString;
                 prefixText: z.ZodString;
                 suffixText: z.ZodString;
-                selectionFingerprint: z.ZodString;
-                schemaVersion: z.ZodLiteral<3>;
-                createdAt: z.ZodNumber;
-            }, z.core.$strict>;
+                schemaVersion: z.ZodLiteral<4>;
+            }, z.core.$strict>>;
             title: z.ZodString;
             titlePending: z.ZodBoolean;
             createdAt: z.ZodNumber;
@@ -551,6 +996,44 @@ export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             }, z.core.$strict>>;
         }, z.core.$strict>>;
         error: z.ZodNullable<z.ZodString>;
+        board: z.ZodOptional<z.ZodObject<{
+            version: z.ZodLiteral<4>;
+            revision: z.ZodNumber;
+            elements: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    text: "text";
+                    markdown: "markdown";
+                    math: "math";
+                    svg: "svg";
+                    html: "html";
+                    image: "image";
+                    table: "table";
+                }>;
+                content: z.ZodString;
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+                style: z.ZodObject<{
+                    color: z.ZodOptional<z.ZodString>;
+                    fontSize: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                focused: z.ZodBoolean;
+                animation: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodEnum<{
+                        "fade-in": "fade-in";
+                        "slide-in": "slide-in";
+                        pulse: "pulse";
+                        highlight: "highlight";
+                    }>;
+                    durationMs: z.ZodNumber;
+                    iterations: z.ZodNumber;
+                    run: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            invalid: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"topics">;
@@ -562,7 +1045,40 @@ export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             observer: "observer";
             "exact-fork": "exact-fork";
         }>;
-        citation: z.ZodObject<{
+        scenario: z.ZodEnum<{
+            qa: "qa";
+            present: "present";
+            read: "read";
+            investigate: "investigate";
+        }>;
+        documentId: z.ZodNullable<z.ZodString>;
+        citation: z.ZodNullable<z.ZodObject<{
+            entry: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"assistant-message">;
+                anchorSeq: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"tool-result">;
+                anchorSeq: z.ZodNumber;
+                callId: z.ZodString;
+                toolName: z.ZodString;
+                projection: z.ZodEnum<{
+                    "result-text": "result-text";
+                    terminal: "terminal";
+                    diff: "diff";
+                }>;
+                fileIndex: z.ZodOptional<z.ZodNumber>;
+                side: z.ZodOptional<z.ZodEnum<{
+                    old: "old";
+                    new: "new";
+                }>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"document-range">;
+                documentId: z.ZodString;
+                startOffset: z.ZodNumber;
+                endOffset: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+            selectionFingerprint: z.ZodString;
+            createdAt: z.ZodNumber;
             sourceSessionId: z.ZodString;
             anchorSeq: z.ZodNumber;
             startOffset: z.ZodNumber;
@@ -571,10 +1087,8 @@ export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             displayText: z.ZodString;
             prefixText: z.ZodString;
             suffixText: z.ZodString;
-            selectionFingerprint: z.ZodString;
-            schemaVersion: z.ZodLiteral<3>;
-            createdAt: z.ZodNumber;
-        }, z.core.$strict>;
+            schemaVersion: z.ZodLiteral<4>;
+        }, z.core.$strict>>;
         title: z.ZodString;
         titlePending: z.ZodBoolean;
         createdAt: z.ZodNumber;
@@ -610,9 +1124,56 @@ export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObje
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"deleted">;
     sessionId: z.ZodString;
+    sourceSessionId: z.ZodString;
+    topicId: z.ZodNumber;
+    cleanup: z.ZodEnum<{
+        complete: "complete";
+        pending: "pending";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"document">;
+    document: z.ZodObject<{
+        documentId: z.ZodString;
+        title: z.ZodString;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+        }>;
+        size: z.ZodNumber;
+        importedAt: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"documents">;
+    documents: z.ZodArray<z.ZodObject<{
+        documentId: z.ZodString;
+        title: z.ZodString;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+        }>;
+        size: z.ZodNumber;
+        importedAt: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"document-content">;
+    document: z.ZodObject<{
+        documentId: z.ZodString;
+        title: z.ZodString;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+        }>;
+        content: z.ZodString;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>;
 }, z.core.$strict>], "kind">;
 export type CiteCiterResponse = z.infer<typeof citeCiterResponseSchema>;
-/** Fields whose canonical serialization defines selection identity. */
-export declare function canonicalCitationIdentity(citation: Omit<CitationDraft, 'selectionFingerprint'>): string;
+/** Fields whose canonical serialization defines evidence identity. */
+export type CitationIdentity = Omit<CitationDraft, 'selectionFingerprint'> & {
+    readonly entry?: CitationEntry;
+};
+/** Serialize the identity-bearing fields. Legacy drafts without an entry keep their v3 identity. */
+export declare function canonicalCitationIdentity(citation: CitationIdentity): string;
 /** Render the immutable Citation as explicitly untrusted user-role context. */
 export declare function renderCitationContext(citation: CitationRecord): string;
+export {};