@deepseek-ai/dsh-session-turn-outline 0.1.2-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/session-turn-outline/README.md
+README.md: e02345d01ed4d31a3e20fd3e28d5b90d451618bb
+README.zh.md: d60e70e4b6f72da076f8fca6c9942815448f92e4

package/README.md

@@ -0,0 +1,125 @@
+---
+description: "Whole-log turn outline for clients and maintainers composing or debugging the turnOutline projection unit behind full-session turn navigation."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-session-turn-outline
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-session-turn-outline` serves the whole-log turn outline — every started turn with its `turn/start` seq and bounded prompt and final-response previews — as the `turnOutline` projection unit. A client that pages history in windows reads the outline to offer every turn of the session (loaded or not) and to target its backwards paging at the exact seq that brings a turn's events in. Choose it in compositions that already mount the projection registry, such as the web app bundle whose chat turn rail is the reference consumer; assemblies without the registry are unaffected and their consumers fall back to loaded-window navigation. Setup and entry semantics come first; the fold internals live in a collapsible developer section below.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the plugin beside the session store and the projection registry when clients should navigate every turn of a session without holding its complete event log. The unit registers only when the registry is present.
+
+### Composition
+
+```yaml
+- name: '@deepseek-ai/dsh-session'
+- name: '@deepseek-ai/dsh-session-projection'
+- name: '@deepseek-ai/dsh-session-turn-outline'
+```
+
+### What an entry means
+
+| Field | Meaning |
+|---|---|
+| `turn` | Host-assigned turn number from the `turn/start` payload |
+| `seq` | The turn's `turn/start` event seq — paging a window back through this seq loads the whole turn |
+| `prompt` | Preview of the turn's first human prompt (space-joined text blocks, collapsed whitespace, 50-character cap with a trailing ellipsis when clipped — one rail-card line); `''` until an eligible prompt lands |
+| `response` | Preview of the turn's final text-bearing assistant message (same normalization, 120-character cap — up to three rail-card lines); `''` until the turn ends with assistant text |
+
+The wire value is the complete entry array, strictly increasing by `turn` (whole-value rule): consumers replace, never merge. Prompts fill only from `user/message` events with the human `user` source, so injected context and tool results never leak into navigation; a turn whose prompt is images-only keeps `''` and consumers label it by number. The response buffers as a draft while its turn streams and commits at `turn/end`; the change feed's raw-view identity gate keeps draft-only changes quiet, so the outline pushes at most three times per turn — boundary, prompt, settled response. Preview budgets match the chat rail's loaded-turn previews, so a turn shows the same words before and after its events load.
+
+### Failures and recovery
+
+The unit is inert without the projection registry: `inject` keeps the fiber pending and nothing registers, so other assemblies lack the `turnOutline` key. Unmounting the plugin removes the key, because registrations are effects on the mounting fiber. Persisted-cache rows are schema-validated on restore — including the strictly-increasing turn order — so a corrupt row is discarded instead of seeding a broken fold.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the fold behind the outline; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The unit is a pure fold over committed session events. `turn/start` — not the prompt `user/message` — anchors each entry because its seq is the load-through target for a jump: the agent loop logs `turn/start` before the turn's prompt and steps, so a window paged back through that seq contains the whole turn. The prompt fills from the first human `user/message`, and only while the newest entry is still empty — later human messages in the same turn (steering) keep the first preview. The response cannot fill the same way (`turn/end` carries no text), so each text-bearing `assistant/message` overwrites a state draft and `turn/end` commits the survivor — the newest text, which is the loaded rail's `findLast` semantic.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `inject`, unit registration on the mounting fiber |
+| [`src/projection.ts`](src/projection.ts) | The fold: entry append, preview fill, wire view |
+| [`src/types.ts`](src/types.ts) | One home of the `turnOutline` projection-key declaration and entry types |
+
+### Fold rules
+
+- Uninteresting events return the same state reference, and draft-only changes keep the `turns` array's identity; the registry's two `Object.is` gates then hold the feed to at most three pushes per turn.
+- A `turn/start` that does not advance the turn number is skipped, keeping the outline sorted; a retried boundary's previews then land on the standing entry.
+- The wire view projects `state.turns`; the persisted-cache state schema wraps the wire schema with the draft field.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the unit's contract is not enough. They move from the registry that drives units to adjacent session packages.
+
+- [Session projection subsystem](../../../docs/subsystems/session-projection.md) — the registry that drives units and serves snapshot and change-feed values.
+- [Session projection registry package](../session-projection/README.md) — the registry contract units register against.
+- [Session package map](../README.md) — adjacent persistence, projection, title, and telemetry packages.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the turnOutline unit folds already-logged turn boundaries into a client-facing read model and registers nothing model-facing.
+
+#### KV Cache effect
+
+None; the package never assembles or sends provider requests.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the outline describes and when the unit is absent. They are current package constraints.
+
+- **The wire value grows with the session** — every push carries the complete outline (whole-value rule), up to ~600 bytes per turn at full CJK budgets and typically far less; splitting previews into an on-demand read is deferred until sessions with many thousands of turns need it.
+- **The response previews only settled turns** — it commits at `turn/end`, so an open turn (or one whose end never logged) shows a prompt-only preview until the boundary lands.
+- **A turn without eligible text keeps `''`** — images-only and command-only turns are navigable but labeled by number, and a turn whose steps emit no text gets no response preview.
+- **Mounted only where the projection registry is composed** — other assemblies serve no `turnOutline` key, and their consumers fall back to loaded-window navigation.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,125 @@
+---
+description: "面向组合或调试 turnOutline 投影单元的客户端与维护者的全量轮次大纲说明，支撑整会话轮次导航。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-session-turn-outline
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-session-turn-outline` 以 `turnOutline` 投影单元提供全日志的轮次大纲——每个已开始的轮次连同其 `turn/start` seq 以及有界的提示词与最终回复预览。按窗口分页历史的客户端读取大纲即可提供会话的每一轮（无论是否已加载），并把向后分页精确定位到能载入某轮事件的 seq。在已挂载投影注册表的组合中选择它，例如以聊天轮次导航栏为参考消费者的 Web 应用包；没有注册表的装配不受影响，其消费者回退到仅按已加载窗口导航。用法与条目语义在前；折叠内部细节放在下方可折叠的开发者章节中。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当客户端需要在不持有完整事件日志的情况下导航会话的每一轮时，在会话存储与投影注册表旁挂载此插件。只有存在注册表时单元才会注册。
+
+### 组合
+
+```yaml
+- name: '@deepseek-ai/dsh-session'
+- name: '@deepseek-ai/dsh-session-projection'
+- name: '@deepseek-ai/dsh-session-turn-outline'
+```
+
+### 各字段含义
+
+| 字段 | 含义 |
+|---|---|
+| `turn` | `turn/start` 载荷里的宿主分配轮次号 |
+| `seq` | 该轮 `turn/start` 事件的 seq——窗口向后分页越过此 seq 即载入整轮 |
+| `prompt` | 该轮首条人类提示词的预览（文本块以空格连接、空白折叠、50 字符封顶且截断时补省略号——即导航卡片一行）；合格提示词落日志前为 `''` |
+| `response` | 该轮最后一条带文本的助手消息的预览（同样的归一化、120 字符封顶——即卡片至多三行）；轮次带着助手文本结束前为 `''` |
+
+wire 值是按 `turn` 严格递增的完整条目数组（整值规则）：消费者整体替换，从不合并。提示词只从带人类 `user` 来源的 `user/message` 事件填充，注入的上下文与工具结果绝不进入导航；纯图片提示词的轮次保持 `''`，消费者按轮次号标注。回复在轮次流式期间缓冲为草稿、在 `turn/end` 落定；变更流的原始视图身份门让纯草稿变化保持安静，因此大纲每轮至多推送三次——开轮、提示词、落定回复。预览预算与聊天导航栏已加载轮次的预览一致，同一轮在事件载入前后显示相同的文字。
+
+### 失败与恢复
+
+没有投影注册表时单元是惰性的：`inject` 使 fiber 保持挂起，不注册任何内容，因此其他装配缺少 `turnOutline` 键。卸载插件会移除该键，因为注册是挂载 fiber 上的 effect。持久缓存行在恢复时经受 schema 校验——包括轮次严格递增的顺序——损坏的行被丢弃而不会喂坏折叠。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释大纲背后的折叠；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+该单元是对已提交会话事件的纯折叠。锚定每个条目的是 `turn/start` 而非提示词 `user/message`，因为它的 seq 就是跳转的载入目标：agent loop 先记 `turn/start` 再记该轮的提示词与步骤，窗口向后分页越过该 seq 即包含整轮。提示词由首条人类 `user/message` 填充，且仅当最新条目仍为空时——同一轮内后续的人类消息（steering）保留首个预览。回复无法同样填充（`turn/end` 不带文本），所以每条带文本的 `assistant/message` 覆写状态里的草稿，`turn/end` 提交幸存者——最新的文本，与已加载导航栏 `findLast` 的语义一致。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`inject`、在挂载 fiber 上注册单元 |
+| [`src/projection.ts`](src/projection.ts) | 折叠：条目追加、预览填充、wire 视图 |
+| [`src/types.ts`](src/types.ts) | `turnOutline` 投影键声明与条目类型的唯一归属 |
+
+### 折叠规则
+
+- 不相关事件返回同一状态引用，纯草稿变化保持 `turns` 数组身份不变；注册表的两道 `Object.is` 门由此把变更流压到每轮至多三次推送。
+- 未推进轮次号的 `turn/start` 被跳过，保持大纲有序；重试边界的预览随后落在既有条目上。
+- wire 视图投影 `state.turns`；持久缓存的状态 schema 在 wire schema 外再包一个草稿字段。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当单元约定不够用时阅读以下页面。它们从驱动单元的注册表逐步进入相邻的会话包。
+
+- [会话投影子系统](../../../docs/subsystems/session-projection.zh.md)——驱动单元并提供快照与变更流值的注册表。
+- [会话投影注册表包](../session-projection/README.zh.md)——单元注册所依据的注册表约定。
+- [会话包映射](../README.zh.md)——相邻的持久化、投影、标题与遥测包。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为 turnOutline 单元把已写入日志的轮次边界折叠成面向客户端的读模型，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；本包从不组装或发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明大纲描述什么、单元何时缺失。它们是当前包约束。
+
+- **wire 值随会话增长**——每次推送携带完整大纲（整值规则），全中文预算下每轮上限约 600 字节、通常远小于此；把预览拆成按需读取推迟到数千轮量级的会话真正需要时。
+- **回复只预览已落定的轮次**——它在 `turn/end` 提交，进行中的轮次（或从未记下结束边界的轮次）在边界落地前只有提示词预览。
+- **没有合格文本的轮次保持 `''`**——纯图片、纯命令的轮次可导航但按轮次号标注，步骤全程不产文本的轮次没有回复预览。
+- **仅在组合了投影注册表时挂载**——其他装配不提供 `turnOutline` 键，其消费者回退到仅按已加载窗口导航。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+//#region lib/types/projection.js
+/**
+* The `turnOutline` projection unit: a pure fold of `turn/start` boundaries,
+* first human prompts, and final assistant responses into the whole-log turn
+* outline the chat rail renders for turns outside a client's paged event
+* window.
+*
+* `turn/start` — not the prompt `user/message` — anchors each entry because
+* its seq is the load-through target for a jump: the loop logs `turn/start`
+* before the turn's prompt and steps, so a window paged back through that seq
+* contains the whole turn. Previews mirror the rail's loaded-turn previews
+* (space-joined text blocks, collapsed whitespace, an ellipsis when clipped)
+* with budgets sized to the rail card's clamps — one prompt line, up to three
+* response lines — so a turn shows the same words before and after its events
+* load. The response commits at `turn/end` from a draft of the newest
+* text-bearing assistant message; draft-only applies keep the `turns` array's
+* identity, so the identity-gated change feed pushes at most three times per
+* turn (boundary, prompt, response).
+*
+* @module @deepseek-ai/dsh-session-turn-outline/projection
+*/
+/** Prompt budget: one rail-card line (13px over ~276px), ASCII worst case included. */
+const PROMPT_PREVIEW_LIMIT = 50;
+/** Response budget: three rail-card lines (12px over ~276px). */
+const RESPONSE_PREVIEW_LIMIT = 120;
+/** Space-join text blocks, collapse whitespace, and cap at `limit` with a trailing ellipsis when clipped. */
+function preview(content, limit) {
+	let text = "";
+	let unread = false;
+	for (const block of content) {
+		if (block.type !== "text") continue;
+		if (text.length >= limit * 2) {
+			unread = true;
+			break;
+		}
+		const clipped = block.text.length > limit * 2;
+		const chunk = clipped ? block.text.slice(0, limit * 2) : block.text;
+		text += text === "" ? chunk : ` ${chunk}`;
+		if (clipped) {
+			unread = true;
+			break;
+		}
+	}
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (normalized.length > limit - 1) return `${normalized.slice(0, limit - 1).trimEnd()}…`;
+	return unread ? `${normalized}…` : normalized;
+}
+const turnOutlineEntriesSchema = z.array(z.object({
+	turn: z.number().int().nonnegative(),
+	seq: z.number().int().nonnegative(),
+	prompt: z.string().max(PROMPT_PREVIEW_LIMIT),
+	response: z.string().max(RESPONSE_PREVIEW_LIMIT)
+}).strict()).superRefine((turns, context) => {
+	let previous = -1;
+	for (const entry of turns) {
+		if (entry.turn <= previous) {
+			context.addIssue({
+				code: "custom",
+				message: "turn outline entries must be strictly increasing by turn"
+			});
+			return;
+		}
+		previous = entry.turn;
+	}
+});
+const turnOutlineStateSchema = z.object({
+	turns: turnOutlineEntriesSchema,
+	draft: z.string().max(RESPONSE_PREVIEW_LIMIT)
+}).strict();
+const EMPTY_OUTLINE = {
+	turns: [],
+	draft: ""
+};
+/** The `turnOutline` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+const turnOutlineProjectionDefinition = {
+	key: "turnOutline",
+	stateVersion: 2,
+	stateSchema: turnOutlineStateSchema,
+	init: () => EMPTY_OUTLINE,
+	apply: (state, event) => {
+		switch (event.type) {
+			case "turn/start": {
+				const last = state.turns.at(-1);
+				if (last !== void 0 && event.data.turn <= last.turn) return state;
+				return {
+					turns: [...state.turns, {
+						turn: event.data.turn,
+						seq: event.seq,
+						prompt: "",
+						response: ""
+					}],
+					draft: ""
+				};
+			}
+			case "user/message": {
+				if (event.data.source.kind !== "user") return state;
+				const last = state.turns.at(-1);
+				if (last === void 0 || last.prompt !== "") return state;
+				const prompt = preview(event.data.content, PROMPT_PREVIEW_LIMIT);
+				if (prompt === "") return state;
+				return {
+					turns: [...state.turns.slice(0, -1), {
+						...last,
+						prompt
+					}],
+					draft: state.draft
+				};
+			}
+			case "assistant/message": {
+				const draft = preview(event.data.message.content, RESPONSE_PREVIEW_LIMIT);
+				if (draft === "" || draft === state.draft) return state;
+				return {
+					turns: state.turns,
+					draft
+				};
+			}
+			case "turn/end": {
+				if (state.draft === "") return state;
+				const last = state.turns.at(-1);
+				if (last === void 0 || last.response === state.draft) return {
+					turns: state.turns,
+					draft: ""
+				};
+				return {
+					turns: [...state.turns.slice(0, -1), {
+						...last,
+						response: state.draft
+					}],
+					draft: ""
+				};
+			}
+			default: return state;
+		}
+	},
+	wire: {
+		viewSchema: turnOutlineEntriesSchema,
+		view: (state) => state.turns
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Function plugin registering the `turnOutline` projection unit: the
+* whole-log turn outline (turn number, `turn/start` seq, bounded prompt
+* preview) served through the session-projection seam — registry snapshot,
+* change feed, and every projection carrier — so a client can offer every
+* turn of a session and target history paging at exact seqs without holding
+* the events. The plugin owns only the fold; delivery is the seam's.
+*
+* @module @deepseek-ai/dsh-session-turn-outline
+*/
+/** Cordis plugin name. */
+const name = "session-turn-outline";
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+const inject = ["sessionProjections"];
+/**
+* Register the `turnOutline` unit; the registration is an effect on this
+* plugin's fiber, so unloading removes the key.
+* @param ctx - registrant context carrying the projection registry.
+*/
+function apply(ctx) {
+	ctx.sessionProjections.register(turnOutlineProjectionDefinition);
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,28 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-turn-outline`.
+* @module @deepseek-ai/dsh-session-turn-outline/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-turn-outline";
+/** Cordis companion plugin name. */
+const name = "session-turn-outline-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the package owns a single pure projection fold whose
+* wire payload is schema-validated by the projection registry at every
+* snapshot and change-feed emission (including the strictly-increasing turn
+* order the fold maintains), and the event relations the fold relies on
+* (host-assigned monotonic turn numbers on `turn/start`, the turn's prompt
+* `user/message` logged after its boundary) are owned and runtime-checked by
+* dsh-agent-loop and the session surface, not here.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the turn-outline domain: a pure re-export
+ * of the package's types outlet. Client code imports ONLY the client
+ * namespace (repo discipline), so `./client` projects the same single-source
+ * content `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline/client
+ */
+export type * from './types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the turn-outline domain: a pure re-export
+ * of the package's types outlet. Client code imports ONLY the client
+ * namespace (repo discipline), so `./client` projects the same single-source
+ * content `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline/client
+ */
+export {};
+//# sourceMappingURL=client.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Function plugin registering the `turnOutline` projection unit: the
+ * whole-log turn outline (turn number, `turn/start` seq, bounded prompt
+ * preview) served through the session-projection seam — registry snapshot,
+ * change feed, and every projection carrier — so a client can offer every
+ * turn of a session and target history paging at exact seqs without holding
+ * the events. The plugin owns only the fold; delivery is the seam's.
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export type * from './types.ts';
+/** Cordis plugin name. */
+export declare const name = "session-turn-outline";
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+export declare const inject: string[];
+/**
+ * Register the `turnOutline` unit; the registration is an effect on this
+ * plugin's fiber, so unloading removes the key.
+ * @param ctx - registrant context carrying the projection registry.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,24 @@
+/**
+ * Function plugin registering the `turnOutline` projection unit: the
+ * whole-log turn outline (turn number, `turn/start` seq, bounded prompt
+ * preview) served through the session-projection seam — registry snapshot,
+ * change feed, and every projection carrier — so a client can offer every
+ * turn of a session and target history paging at exact seqs without holding
+ * the events. The plugin owns only the fold; delivery is the seam's.
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline
+ */
+import { turnOutlineProjectionDefinition } from "./projection.js";
+/** Cordis plugin name. */
+export const name = 'session-turn-outline';
+/** The projection registry is the plugin's whole purpose; without it the fiber stays pending. */
+export const inject = ['sessionProjections'];
+/**
+ * Register the `turnOutline` unit; the registration is an effect on this
+ * plugin's fiber, so unloading removes the key.
+ * @param ctx - registrant context carrying the projection registry.
+ */
+export function apply(ctx) {
+    ctx.sessionProjections.register(turnOutlineProjectionDefinition);
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-turn-outline`.
+ * @module @deepseek-ai/dsh-session-turn-outline/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-turn-outline-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,27 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-turn-outline`.
+ * @module @deepseek-ai/dsh-session-turn-outline/invariant
+ */
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-turn-outline';
+/** Cordis companion plugin name. */
+export const name = 'session-turn-outline-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the package owns a single pure projection fold whose
+ * wire payload is schema-validated by the projection registry at every
+ * snapshot and change-feed emission (including the strictly-increasing turn
+ * order the fold maintains), and the event relations the fold relies on
+ * (host-assigned monotonic turn numbers on `turn/start`, the turn's prompt
+ * `user/message` logged after its boundary) are owned and runtime-checked by
+ * dsh-agent-loop and the session surface, not here.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `turnOutline` projection unit: a pure fold of `turn/start` boundaries,
+ * first human prompts, and final assistant responses into the whole-log turn
+ * outline the chat rail renders for turns outside a client's paged event
+ * window.
+ *
+ * `turn/start` — not the prompt `user/message` — anchors each entry because
+ * its seq is the load-through target for a jump: the loop logs `turn/start`
+ * before the turn's prompt and steps, so a window paged back through that seq
+ * contains the whole turn. Previews mirror the rail's loaded-turn previews
+ * (space-joined text blocks, collapsed whitespace, an ellipsis when clipped)
+ * with budgets sized to the rail card's clamps — one prompt line, up to three
+ * response lines — so a turn shows the same words before and after its events
+ * load. The response commits at `turn/end` from a draft of the newest
+ * text-bearing assistant message; draft-only applies keep the `turns` array's
+ * identity, so the identity-gated change feed pushes at most three times per
+ * turn (boundary, prompt, response).
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline/projection
+ */
+import { z } from 'zod';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { TurnOutlineEntry, TurnOutlineState } from './types.ts';
+/** The `turnOutline` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+export declare const turnOutlineProjectionDefinition: {
+    key: "turnOutline";
+    stateVersion: number;
+    stateSchema: z.ZodType<TurnOutlineState, unknown, z.core.$ZodTypeInternals<TurnOutlineState, unknown>>;
+    init: () => TurnOutlineState;
+    apply: (state: NoInfer<TurnOutlineState>, event: SessionEvent) => TurnOutlineState;
+    wire: {
+        viewSchema: z.ZodType<readonly TurnOutlineEntry[], unknown, z.core.$ZodTypeInternals<readonly TurnOutlineEntry[], unknown>>;
+        view: (state: NoInfer<TurnOutlineState>) => readonly TurnOutlineEntry[];
+    };
+};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,134 @@
+/**
+ * The `turnOutline` projection unit: a pure fold of `turn/start` boundaries,
+ * first human prompts, and final assistant responses into the whole-log turn
+ * outline the chat rail renders for turns outside a client's paged event
+ * window.
+ *
+ * `turn/start` — not the prompt `user/message` — anchors each entry because
+ * its seq is the load-through target for a jump: the loop logs `turn/start`
+ * before the turn's prompt and steps, so a window paged back through that seq
+ * contains the whole turn. Previews mirror the rail's loaded-turn previews
+ * (space-joined text blocks, collapsed whitespace, an ellipsis when clipped)
+ * with budgets sized to the rail card's clamps — one prompt line, up to three
+ * response lines — so a turn shows the same words before and after its events
+ * load. The response commits at `turn/end` from a draft of the newest
+ * text-bearing assistant message; draft-only applies keep the `turns` array's
+ * identity, so the identity-gated change feed pushes at most three times per
+ * turn (boundary, prompt, response).
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline/projection
+ */
+import { z } from 'zod';
+/** Prompt budget: one rail-card line (13px over ~276px), ASCII worst case included. */
+const PROMPT_PREVIEW_LIMIT = 50;
+/** Response budget: three rail-card lines (12px over ~276px). */
+const RESPONSE_PREVIEW_LIMIT = 120;
+/** Space-join text blocks, collapse whitespace, and cap at `limit` with a trailing ellipsis when clipped. */
+function preview(content, limit) {
+    let text = '';
+    let unread = false;
+    for (const block of content) {
+        if (block.type !== 'text')
+            continue;
+        if (text.length >= limit * 2) {
+            unread = true;
+            break;
+        }
+        // Per-block bound: the fold runs on every message event, so a single
+        // multi-megabyte block must not be concatenated (and regex-normalized)
+        // whole for a preview this short.
+        const clipped = block.text.length > limit * 2;
+        const chunk = clipped ? block.text.slice(0, limit * 2) : block.text;
+        text += text === '' ? chunk : ` ${chunk}`;
+        if (clipped) {
+            unread = true;
+            break;
+        }
+    }
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (normalized.length > limit - 1)
+        return `${normalized.slice(0, limit - 1).trimEnd()}…`;
+    return unread ? `${normalized}…` : normalized;
+}
+const turnOutlineEntriesSchema = z.array(z.object({
+    turn: z.number().int().nonnegative(),
+    seq: z.number().int().nonnegative(),
+    prompt: z.string().max(PROMPT_PREVIEW_LIMIT),
+    response: z.string().max(RESPONSE_PREVIEW_LIMIT),
+}).strict()).superRefine((turns, context) => {
+    let previous = -1;
+    for (const entry of turns) {
+        if (entry.turn <= previous) {
+            context.addIssue({ code: 'custom', message: 'turn outline entries must be strictly increasing by turn' });
+            return;
+        }
+        previous = entry.turn;
+    }
+});
+const turnOutlineStateSchema = z.object({
+    turns: turnOutlineEntriesSchema,
+    draft: z.string().max(RESPONSE_PREVIEW_LIMIT),
+}).strict();
+const EMPTY_OUTLINE = { turns: [], draft: '' };
+/** The `turnOutline` unit registered on `ctx.sessionProjections` (exported for the unit spec). */
+export const turnOutlineProjectionDefinition = {
+    key: 'turnOutline',
+    stateVersion: 2,
+    stateSchema: turnOutlineStateSchema,
+    init: () => EMPTY_OUTLINE,
+    apply: (state, event) => {
+        // Every uninteresting event returns the same reference (Object.is gates
+        // the drive), and draft-only changes keep `turns` identity (the raw-view
+        // identity gate then keeps the change feed quiet).
+        switch (event.type) {
+            case 'turn/start': {
+                const last = state.turns.at(-1);
+                // Order guard: a boundary that does not advance the turn number keeps
+                // the outline sorted, and a retried turn's previews land on the
+                // standing entry.
+                if (last !== undefined && event.data.turn <= last.turn)
+                    return state;
+                return {
+                    turns: [...state.turns, { turn: event.data.turn, seq: event.seq, prompt: '', response: '' }],
+                    draft: '',
+                };
+            }
+            case 'user/message': {
+                // Only the newest turn can still be waiting for its opening human
+                // prompt; later human messages in the same turn (steering) keep the
+                // first preview.
+                if (event.data.source.kind !== 'user')
+                    return state;
+                const last = state.turns.at(-1);
+                if (last === undefined || last.prompt !== '')
+                    return state;
+                const prompt = preview(event.data.content, PROMPT_PREVIEW_LIMIT);
+                if (prompt === '')
+                    return state;
+                return { turns: [...state.turns.slice(0, -1), { ...last, prompt }], draft: state.draft };
+            }
+            case 'assistant/message': {
+                // Newest text-bearing message wins; the buffer commits at turn/end.
+                const draft = preview(event.data.message.content, RESPONSE_PREVIEW_LIMIT);
+                if (draft === '' || draft === state.draft)
+                    return state;
+                return { turns: state.turns, draft };
+            }
+            case 'turn/end': {
+                if (state.draft === '')
+                    return state;
+                const last = state.turns.at(-1);
+                if (last === undefined || last.response === state.draft)
+                    return { turns: state.turns, draft: '' };
+                return { turns: [...state.turns.slice(0, -1), { ...last, response: state.draft }], draft: '' };
+            }
+            default:
+                return state;
+        }
+    },
+    wire: {
+        viewSchema: turnOutlineEntriesSchema,
+        view: state => state.turns,
+    },
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure types of the turn-outline domain: the ONE home of the `turnOutline`
+ * projection-key declaration, free of this package's host-side value imports
+ * (zod, the projection definition). Host consumers import `./types`; client
+ * aggregates import `./client`, which re-exports this module.
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline/types
+ */
+export {};
+/** One started turn's outline facts, independent of what a client has paged in. */
+export interface TurnOutlineEntry {
+    /** Host-assigned turn number (the `turn/start` payload). */
+    readonly turn: number;
+    /** The turn's `turn/start` event seq — paging a window back through this seq loads the whole turn. */
+    readonly seq: number;
+    /** Bounded first-human-prompt preview (one rail-card line); `''` until an eligible prompt lands. */
+    readonly prompt: string;
+    /** Bounded final-response preview (up to three rail-card lines); `''` until the turn ends with assistant text. */
+    readonly response: string;
+}
+/**
+ * Fold state: the served entries plus the open turn's response draft. The
+ * draft buffers the newest text-bearing assistant message until `turn/end`
+ * commits it, and the wire view projects only `turns` — draft-only applies
+ * keep that array's identity, so the change feed stays quiet between turn
+ * boundaries.
+ */
+export interface TurnOutlineState {
+    /** Started turns in ascending turn order. */
+    readonly turns: readonly TurnOutlineEntry[];
+    /** Newest text-bearing assistant preview of the open turn; `''` outside one. */
+    readonly draft: string;
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        /** Whole-log turn outline fold state (entries plus the open turn's response draft). */
+        turnOutline: TurnOutlineState;
+    }
+    interface SessionProjectionMap {
+        /** Every started turn with its `turn/start` seq and bounded previews, strictly increasing by turn; see {@link TurnOutlineEntry}. */
+        turnOutline: readonly TurnOutlineEntry[];
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Pure types of the turn-outline domain: the ONE home of the `turnOutline`
+ * projection-key declaration, free of this package's host-side value imports
+ * (zod, the projection definition). Host consumers import `./types`; client
+ * aggregates import `./client`, which re-exports this module.
+ *
+ * @module @deepseek-ai/dsh-session-turn-outline/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-session-turn-outline",
+  "description": "Whole-log turn outline projection (turnOutline) for the DeepSeek Harness",
+  "version": "0.1.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-turn-outline"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3"
+  }
+}