@x1a0f3n9/dsh-session-turn-outline 0.1.5-rc.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: 58a71c6977aaaae8663ea96651c50317a034bb8c
+README.zh.md: 49c0aa3c4f7a9b4950d855359d8c789e375e0806

package/README.md

@@ -0,0 +1,126 @@
+---
+description: "Whole-log turn outline for clients and maintainers composing or debugging the turnOutline projection unit behind full-session turn navigation."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-session-turn-outline
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package gives history clients a whole-session outline of every started turn, including bounded prompt and settled-response previews. Clients can navigate turns that are not yet loaded and page backward from the exact event sequence needed to load a selected turn. It fits assemblies that provide session projections; elsewhere, clients continue using loaded-window navigation. Previews exclude injected context and tool results, and a response appears only after its turn settles.
+
+## 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: '@x1a0f3n9/dsh-session'
+- name: '@x1a0f3n9/dsh-session-projection'
+- name: '@x1a0f3n9/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 |
+| — | No runtime invariant companion is published: the package owns one pure projection fold, `session-projection` schema-validates its served values, and re-folding the same log would duplicate the implementation instead of comparing independently maintained observations; session and agent-loop own turn-boundary ordering. |
+
+### 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,126 @@
+---
+description: "面向组合或调试 turnOutline 投影单元的客户端与维护者的全量轮次大纲说明，支撑整会话轮次导航。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-session-turn-outline
+
+[English](README.md) | 中文
+
+## 概述
+
+本包为历史记录客户端提供涵盖完整会话的轮次大纲，其中包含每个已开始轮次的有界提示词预览与落定回复预览。客户端可以导航尚未加载的轮次，并从载入所选轮次所需的准确事件序号向后分页。它适用于提供会话投影的装配；在其他装配中，客户端继续使用仅覆盖已加载窗口的导航。预览排除注入的上下文与工具结果，并且回复仅在所属轮次落定后出现。
+
+## 目录
+
+- [使用本包](#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: '@x1a0f3n9/dsh-session'
+- name: '@x1a0f3n9/dsh-session-projection'
+- name: '@x1a0f3n9/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` 投影键声明与条目类型的唯一归属 |
+| — | 不发布运行时不变式伴生入口：本包仅拥有一个纯投影折叠，`session-projection` 会对其对外值执行 schema 校验；重新折叠同一日志只会复制实现，无法比较独立维护的观测，而轮次边界顺序由 session 与 agent-loop 负责。 |
+
+### 折叠规则
+
+- 不相关事件返回同一状态引用，纯草稿变化保持 `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 值随会话增长**——每次推送携带完整大纲（整值规则），CJK 字符占满预算时每轮上限约 600 字节、通常远小于此；把预览拆成按需读取推迟到数千轮量级的会话真正需要时。
+- **回复只预览已落定的轮次**——它在 `turn/end` 提交，进行中的轮次（或从未记下结束边界的轮次）在边界落地前只有提示词预览。
+- **没有合格文本的轮次保持 `''`**——纯图片、纯命令的轮次可导航但按轮次号标注，步骤全程不产文本的轮次没有回复预览。
+- **仅在组合了投影注册表时挂载**——其他装配不提供 `turnOutline` 键，其消费方回退到仅按已加载窗口导航。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { SessionSeq } from "@x1a0f3n9/dsh-session";
+//#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 @x1a0f3n9/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().transform(SessionSeq),
+	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 @x1a0f3n9/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/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 @x1a0f3n9/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 @x1a0f3n9/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 @x1a0f3n9/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 @x1a0f3n9/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/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 @x1a0f3n9/dsh-session-turn-outline/projection
+ */
+import { z } from 'zod';
+import { type SessionEvent } from '@x1a0f3n9/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,135 @@
+/**
+ * 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 @x1a0f3n9/dsh-session-turn-outline/projection
+ */
+import { z } from 'zod';
+import { SessionSeq } from '@x1a0f3n9/dsh-session';
+/** 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().transform(SessionSeq),
+    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,45 @@
+/**
+ * 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 @x1a0f3n9/dsh-session-turn-outline/types
+ */
+import type { SessionSeq } from '@x1a0f3n9/dsh-session/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: SessionSeq;
+    /** 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 '@x1a0f3n9/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 @x1a0f3n9/dsh-session-turn-outline/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@x1a0f3n9/dsh-session-turn-outline",
+  "description": "Whole-log turn outline projection (turnOutline) for the DeepSeek Harness",
+  "version": "0.1.5-rc.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"
+    },
+    "./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/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.3"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.3"
+  }
+}