DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(surface): use nodeBySeq map for lookup in _replace, drop dead params

Browse Source
This commit is contained in:
Hypatia May
2026-06-23 13:26:45 +08:00
parent 6089e226bc
commit 1ec8c40d0d
3 changed files with 63 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/core-data-structures/session.md
View File

@@ -66,7 +66,51 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
`SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`.
The five message-producing types (`SurfaceEventType` — `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`) additionally carry two optional surface fields: `surfaceOp` (how the event enters the derived surface linked list — `'append'` or a `{ op: 'replace', start, end }` shadow) and `sourceEventSeqs` (provenance). See the [session surface RFC](../rfc/implemented/architecture/2026-06-18-session-surface.md).
## Surface types
The five message-producing types (`SurfaceEventType` — `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`) carry surface metadata declaring how they join the derived surface linked list. See the [session surface RFC](../rfc/implemented/architecture/2026-06-18-session-surface.md).
### `SurfaceEventType` — the message-producing subset of event types
```ts type-equiv
export type SurfaceEventType =
| 'user/message'
| 'assistant/message'
| 'tool/result'
| 'context/message'
| 'steering/message'
```
### `SurfaceOp` — how an event entered the surface
```ts type-equiv
export type SurfaceOp =
| 'append'
| { op: 'replace'; start: number; end: number }
```
`'append'` is the normal tail-append path. `replace` shadows surface nodes from `start` through `end` inclusive (both must be valid surface node seqs; `start === end` replaces a single node) and inserts the new node in their place.
### `SurfaceIntent` — the parameter to `session.append()`
```ts type-equiv
export interface SurfaceIntent {
surfaceOp: SurfaceOp
sourceEventSeqs?: number[]
}
```
Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived history. Non-surface types reject it at compile time.
### `SurfaceNode` — a node in the surface linked list
```ts type-equiv
export interface SurfaceNode {
seq: number
prev: number | null
next: number | null
}
```
## Derived history: `deriveMessages()`