@luziyang2026/dsh-question-nav 0.3.0 → 0.4.1

package/src/projection.ts

@@ -0,0 +1,98 @@
+/**
+ * The `questionIndex` session projection unit: a pure fold of the session
+ * event log into the ordered list of user questions, each tagged with the
+ * turn that claimed it. Registered on `ctx.sessionProjections` by the host
+ * half (src/index.ts); persistence, replay, and client delivery are the
+ * projection seam's (session-projection-cache checkpoints the state, the
+ * api-proxy carriers seed + push the wire view).
+ *
+ * Fold rules mirror the chat messageDefinition classification: an
+ * append-origin `user/message` with a human (`user`) source is a question;
+ * replacement copies (compaction checkpoints) and injected context are not.
+ * Turns come from `turn/start` boundaries, so retry/goal-continuation turns
+ * without a question simply produce no entry — dots may skip turn numbers,
+ * staying exactly aligned with the Trajectory view's turn labels.
+ *
+ * @module dsh-question-nav/projection
+ */
+
+import { z } from 'zod'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import type { QuestionEntry } from './core/question-entry.ts'
+
+/** Fold state: the last opened turn plus every question recorded so far. */
+export interface QuestionIndexState {
+  /** Turn of the last `turn/start` (0 before any; turns are 1-based). */
+  turn: number
+  /** Every recorded question, in event order. */
+  questions: QuestionEntry[]
+}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    questionIndex: QuestionEntry[]
+  }
+  interface SessionProjectionStateMap {
+    questionIndex: QuestionIndexState
+  }
+}
+
+const questionEntrySchema = z.object({
+  turn: z.number().int().nonnegative(),
+  id: z.string(),
+  seq: z.number().int().nonnegative(),
+  time: z.number().nonnegative(),
+  text: z.string(),
+}).strict()
+
+/** Validates persisted rows after their `ver` gate (the unit's input boundary). */
+const questionIndexStateSchema = z.object({
+  turn: z.number().int().nonnegative(),
+  questions: z.array(questionEntrySchema),
+}).strict()
+
+/** Validates the wire payload before it leaves the host. */
+const questionIndexViewSchema = z.array(questionEntrySchema)
+
+/** First text block of a user message; empty string when absent. */
+function messageText(content: readonly { type?: string; text?: string }[] | undefined): string {
+  if (content === undefined || content.length === 0) return ''
+  const first = content[0]
+  return typeof first?.text === 'string' ? first.text : ''
+}
+
+/** The `questionIndex` unit registered on `ctx.sessionProjections`. */
+export const questionIndexProjectionDefinition: Omit<ProjectionDefinition<'questionIndex', QuestionIndexState>, 'wire'> & {
+  wire: NonNullable<ProjectionDefinition<'questionIndex', QuestionIndexState>['wire']>
+} = {
+  key: 'questionIndex',
+  stateVersion: 1,
+  stateSchema: questionIndexStateSchema,
+  init: () => ({ turn: 0, questions: [] }),
+  apply: (state, event) => {
+    // Every uninteresting event returns the same reference (Object.is gates
+    // the change feed and the persisted-cache dirty check).
+    switch (event.type) {
+      case 'turn/start':
+        return event.data.turn === state.turn ? state : { ...state, turn: event.data.turn }
+      case 'user/message': {
+        if (event.surfaceOp !== 'append') return state
+        if (event.data.source?.kind !== 'user') return state
+        const entry: QuestionEntry = {
+          turn: state.turn,
+          id: String(event.data.id),
+          seq: event.seq,
+          time: event.time,
+          text: messageText(event.data.content),
+        }
+        return { ...state, questions: [...state.questions, entry] }
+      }
+      default:
+        return state
+    }
+  },
+  wire: {
+    viewSchema: questionIndexViewSchema,
+    view: state => state.questions,
+  },
+}

package/lib/types/core/history-index.d.ts

@@ -1,99 +0,0 @@
-/**
- * Question-index builder over the raw session history RPC.
- *
- * DSH pages the rendered conversation window on purpose (memory economy):
- * `chat.nodes` only ever holds the loaded window, and force-expanding it
- * (repeated `loadOlder()`) materializes + renders the whole log — the exact
- * cost DSH's paging exists to avoid. This module instead builds a lightweight
- * index of every user question by paging the RAW history RPC (`session.history`
- * with `beforeSeq`), which reads the host log without touching the render
- * window at all. Only `{key, seq, time, text}` per question is retained.
- *
- * The chat anchor key is derived deterministically from the event — it equals
- * `conversationContextKey('input-message', String(event.data.id))` — so the
- * dots can target rows that are not loaded yet, and a click then pages the
- * window on demand (see `jump.ts`).
- *
- * Pure-ish: takes injected ports (one raw history page read, clocks) so it is
- * unit-testable without a browser or a live session.
- */
-import type { QuestionNode } from './nodes.ts';
-/** Minimal shape of a raw history event (structural, not SDK-bound). */
-export interface RawEventLike {
-    type: string;
-    seq: number;
-    time: number;
-    surfaceOp?: unknown;
-    data?: {
-        id?: unknown;
-        source?: {
-            kind?: string;
-            plugin?: string;
-        };
-        content?: readonly {
-            type?: string;
-            text?: string;
-        }[];
-    };
-}
-/** The conversation Definition kind whose key a user question node uses. */
-export declare const MESSAGE_DEFINITION_KIND = "input-message";
-/**
- * The engine-owned stable chat key for a user question event — mirrors
- * `conversationContextKey('input-message', String(id))` from the DSH runtime
- * (verified against it in the unit test).
- */
-export declare function questionKey(id: unknown): string;
-/**
- * Whether a raw event is one user question the strip should index.
- * Mirrors the DSH `messageDefinition` match + `start` classification:
- * an append-origin `user/message` with a human (`user`) source. Replacement
- * copies (compaction checkpoints, `source.kind === 'plugin'`) and injected
- * context (`source.kind !== 'user'`) are excluded.
- */
-export declare function isQuestionEvent(event: RawEventLike): boolean;
-/** Map one raw question event to a strip question node, or null when not one. */
-export declare function questionFromEvent(event: RawEventLike): QuestionNode | null;
-export interface HistoryIndexPorts {
-    /**
-     * Read one raw history page. `beforeSeq` is exclusive (events with seq <
-     * beforeSeq); `undefined` reads the newest page. Resolves undefined when
-     * the page is unavailable (session gone / transport error).
-     */
-    history: (beforeSeq: number | undefined, maxMessages: number) => Promise<{
-        events: readonly {
-            event: RawEventLike;
-        }[];
-        hasMore: boolean;
-    } | undefined>;
-    /** Monotonic ms clock. */
-    now: () => number;
-}
-export interface HistoryIndexOptions {
-    /** Raw messages per page (default 100). */
-    maxMessages?: number;
-    /** Max pages before giving up (default 200 => 20k messages). */
-    maxPages?: number;
-    /** Total wall-clock budget (default 30s). */
-    totalTimeoutMs?: number;
-    /** Abort the build; checked every iteration. */
-    signal?: AbortSignal;
-    /** Resume from a previous `nextBeforeSeq` instead of the newest page. */
-    startBeforeSeq?: number;
-}
-export type HistoryIndexCode = 'COMPLETE' | 'BUDGET' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELLED';
-export interface HistoryIndexResult {
-    ok: boolean;
-    code: HistoryIndexCode;
-    /** Questions collected so far, ascending by anchorSeq. */
-    questions: QuestionNode[];
-    /** Page count actually read. */
-    pages: number;
-    /** Where to continue (exclusive) when stopped early; undefined when COMPLETE. */
-    nextBeforeSeq: number | undefined;
-}
-/**
- * Page the raw session history backward, collecting every user question into a
- * lightweight index. Never touches the render window.
- */
-export declare function buildQuestionIndex(ports: HistoryIndexPorts, options?: HistoryIndexOptions): Promise<HistoryIndexResult>;

package/lib/types/core/load-all.d.ts

@@ -1,53 +0,0 @@
-/**
- * Load-all orchestration for the question-nav strip.
- *
- * DSH sessions page history in fixed-size chunks: `chat.nodes` only ever holds
- * the currently loaded window, and questions that still sit behind the "load
- * older" button are invisible to the strip until the window is expanded
- * backwards. This loop pages `loadOlder()` until `hasMore` is false (the whole
- * history is materialized), so every user question becomes a dot.
- *
- * Pure-ish: takes injected ports (snapshot read, one paged loadOlder, view
- * liveness, clocks) so it is unit-testable without a browser or session.
- */
-export interface LoadAllSnapshot {
-    openState: string;
-    hasMore: boolean;
-    loadingOlder: boolean;
-}
-export interface LoadAllPorts {
-    /** Read the current session snapshot; undefined when unavailable. */
-    snapshot: () => LoadAllSnapshot | undefined;
-    /** Expand the window backwards by one page (may preserve scroll). */
-    loadOlder: () => Promise<void>;
-    /** True while the chat view is active (a `[data-chat-flow]` is mounted). */
-    isViewActive: () => boolean;
-    /** Monotonic ms clock. */
-    now: () => number;
-    /** Async sleep. */
-    sleep: (ms: number) => Promise<void>;
-}
-export interface LoadAllOptions {
-    /** Max older pages to fetch before giving up (default 400). */
-    maxPages?: number;
-    /** Total wall-clock budget for the whole expansion (default 60s). */
-    totalTimeoutMs?: number;
-    /** Poll interval for open/loading transitions (default 60ms). */
-    pollMs?: number;
-    /** Abort the expansion; checked every iteration. */
-    signal?: AbortSignal;
-}
-export type LoadAllCode = 'COMPLETE' | 'VIEW_INACTIVE' | 'NOT_OPEN' | 'BUDGET' | 'TIMEOUT' | 'CANCELLED';
-export interface LoadAllResult {
-    ok: boolean;
-    code: LoadAllCode;
-    /** Number of `loadOlder` pages actually fetched. */
-    pages: number;
-}
-/**
- * Expand the session window backwards until the earliest history is loaded.
- * Waits while the session is still opening; aborts on cancellation, budget or
- * timeout. Safe to re-enter: once `hasMore` is false the loop returns
- * immediately with `COMPLETE`.
- */
-export declare function loadAllOlder(ports: LoadAllPorts, options?: LoadAllOptions): Promise<LoadAllResult>;

package/src/core/history-index.ts

@@ -1,176 +0,0 @@
-/**
- * Question-index builder over the raw session history RPC.
- *
- * DSH pages the rendered conversation window on purpose (memory economy):
- * `chat.nodes` only ever holds the loaded window, and force-expanding it
- * (repeated `loadOlder()`) materializes + renders the whole log — the exact
- * cost DSH's paging exists to avoid. This module instead builds a lightweight
- * index of every user question by paging the RAW history RPC (`session.history`
- * with `beforeSeq`), which reads the host log without touching the render
- * window at all. Only `{key, seq, time, text}` per question is retained.
- *
- * The chat anchor key is derived deterministically from the event — it equals
- * `conversationContextKey('input-message', String(event.data.id))` — so the
- * dots can target rows that are not loaded yet, and a click then pages the
- * window on demand (see `jump.ts`).
- *
- * Pure-ish: takes injected ports (one raw history page read, clocks) so it is
- * unit-testable without a browser or a live session.
- */
-
-import type { QuestionNode } from './nodes.ts'
-import { messageText } from './nodes.ts'
-
-/** Minimal shape of a raw history event (structural, not SDK-bound). */
-export interface RawEventLike {
-  type: string
-  seq: number
-  time: number
-  surfaceOp?: unknown
-  data?: {
-    id?: unknown
-    source?: { kind?: string; plugin?: string }
-    content?: readonly { type?: string; text?: string }[]
-  }
-}
-
-/** The conversation Definition kind whose key a user question node uses. */
-export const MESSAGE_DEFINITION_KIND = 'input-message'
-
-/**
- * The engine-owned stable chat key for a user question event — mirrors
- * `conversationContextKey('input-message', String(id))` from the DSH runtime
- * (verified against it in the unit test).
- */
-export function questionKey(id: unknown): string {
-  const kind = MESSAGE_DEFINITION_KIND
-  return `${kind.length}:${kind}${String(id)}`
-}
-
-/**
- * Whether a raw event is one user question the strip should index.
- * Mirrors the DSH `messageDefinition` match + `start` classification:
- * an append-origin `user/message` with a human (`user`) source. Replacement
- * copies (compaction checkpoints, `source.kind === 'plugin'`) and injected
- * context (`source.kind !== 'user'`) are excluded.
- */
-export function isQuestionEvent(event: RawEventLike): boolean {
-  if (event.type !== 'user/message') return false
-  if (event.surfaceOp !== 'append') return false
-  return event.data?.source?.kind === 'user'
-}
-
-/** Map one raw question event to a strip question node, or null when not one. */
-export function questionFromEvent(event: RawEventLike): QuestionNode | null {
-  if (!isQuestionEvent(event)) return null
-  return {
-    key: questionKey(event.data?.id),
-    anchorSeq: event.seq,
-    seq: event.seq,
-    time: event.time,
-    text: messageText(event.data?.content),
-  }
-}
-
-export interface HistoryIndexPorts {
-  /**
-   * Read one raw history page. `beforeSeq` is exclusive (events with seq <
-   * beforeSeq); `undefined` reads the newest page. Resolves undefined when
-   * the page is unavailable (session gone / transport error).
-   */
-  history: (
-    beforeSeq: number | undefined,
-    maxMessages: number,
-  ) => Promise<{ events: readonly { event: RawEventLike }[]; hasMore: boolean } | undefined>
-  /** Monotonic ms clock. */
-  now: () => number
-}
-
-export interface HistoryIndexOptions {
-  /** Raw messages per page (default 100). */
-  maxMessages?: number
-  /** Max pages before giving up (default 200 => 20k messages). */
-  maxPages?: number
-  /** Total wall-clock budget (default 30s). */
-  totalTimeoutMs?: number
-  /** Abort the build; checked every iteration. */
-  signal?: AbortSignal
-  /** Resume from a previous `nextBeforeSeq` instead of the newest page. */
-  startBeforeSeq?: number
-}
-
-export type HistoryIndexCode = 'COMPLETE' | 'BUDGET' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELLED'
-
-export interface HistoryIndexResult {
-  ok: boolean
-  code: HistoryIndexCode
-  /** Questions collected so far, ascending by anchorSeq. */
-  questions: QuestionNode[]
-  /** Page count actually read. */
-  pages: number
-  /** Where to continue (exclusive) when stopped early; undefined when COMPLETE. */
-  nextBeforeSeq: number | undefined
-}
-
-const DEFAULTS = {
-  maxMessages: 100,
-  maxPages: 200,
-  totalTimeoutMs: 30_000,
-}
-
-function minSeq(events: readonly { event: RawEventLike }[]): number | undefined {
-  let min: number | undefined
-  for (const { event } of events) {
-    if (min === undefined || event.seq < min) min = event.seq
-  }
-  return min
-}
-
-/**
- * Page the raw session history backward, collecting every user question into a
- * lightweight index. Never touches the render window.
- */
-export async function buildQuestionIndex(
-  ports: HistoryIndexPorts,
-  options: HistoryIndexOptions = {},
-): Promise<HistoryIndexResult> {
-  const cfg = { ...DEFAULTS, ...options }
-  const deadline = ports.now() + cfg.totalTimeoutMs
-  const questions: QuestionNode[] = []
-  let beforeSeq: number | undefined = cfg.startBeforeSeq
-  let pages = 0
-
-  const cancelled = (): boolean => cfg.signal?.aborted === true
-
-  while (true) {
-    if (cancelled()) return { ok: false, code: 'CANCELLED', questions, pages, nextBeforeSeq: beforeSeq }
-    if (ports.now() > deadline) return { ok: false, code: 'TIMEOUT', questions, pages, nextBeforeSeq: beforeSeq }
-    if (pages >= cfg.maxPages) return { ok: false, code: 'BUDGET', questions, pages, nextBeforeSeq: beforeSeq }
-
-    const page = await ports.history(beforeSeq, cfg.maxMessages)
-    if (page === undefined) {
-      // Transient: retry a little, then give up with what we have.
-      if (pages === 0) return { ok: false, code: 'UNAVAILABLE', questions, pages, nextBeforeSeq: beforeSeq }
-      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
-    }
-
-    for (const { event } of page.events) {
-      const question = questionFromEvent(event)
-      if (question !== null) questions.push(question)
-    }
-
-    if (!page.hasMore) {
-      questions.sort((a, b) => a.anchorSeq - b.anchorSeq)
-      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
-    }
-
-    const next = minSeq(page.events)
-    if (next === undefined) {
-      // Empty page with hasMore true is anomalous; stop cleanly.
-      questions.sort((a, b) => a.anchorSeq - b.anchorSeq)
-      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
-    }
-    beforeSeq = next
-    pages += 1
-  }
-}