Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(session): project the inherited-history boundary into the log

Browse Source 
A plugin owning a standalone open/close bracket cannot tell a dead marker
from a live one: an unmatched `compact/start` reads identically whether the
previous writer died mid-compaction or a compaction is running now.
`Session.firstLiveSeq` already holds that answer exactly, but only in memory.

Append the log-only `session/inherited` event at that seq from the seeded
constructor — the single waist all six seeded-start paths pass through
(resume, configured startup on a persisted id, `sessions.fork()`, a subagent
fork child, `adopt()`'s live prefix, and a bare seeded `create`). Read it
through the new `isInheritedSeq(events, seq)`.

The constructor placement means persistence needs no changes: the marker is
already in `events` when a backend captures the creation seed, so it rides
the ordinary seed path with no load-time write. It also covers fork, where
the inherited bracket's owner may still be running — the case a
persistence-layer boundary could not reach.

Activity ordering excludes the boundary through `lastActivityTime()`, since
lazy resume makes browsing a pickup and the three call sites would otherwise
float every opened session to the top of a picker or list.
This commit is contained in:
Hypatia May
2026-07-30 11:38:51 +08:00
parent 2a53806275
commit b341155652
41 changed files with 850 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/cordis-catalog/services.md
View File

@@ -1590,7 +1590,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId):
Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
Source: [`packages/core/session/src/index.ts:695`](../../packages/core/session/src/index.ts)
Source: [`packages/core/session/src/index.ts:706`](../../packages/core/session/src/index.ts)
## `ctx.sessionTitle` — `SessionTitleService`
@@ -2197,7 +2197,7 @@ The concrete provider retains pi-tui, focus, and terminal lifecycle state. Plugi
abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
```
Source: [`packages/ui/tui/src/index.ts:247`](../../packages/ui/tui/src/index.ts)
Source: [`packages/ui/tui/src/index.ts:248`](../../packages/ui/tui/src/index.ts)
## `ctx.typert` — `TypertRegistry`

4
docs/core-data-structures/session.i18n.yaml
View File

@@ -2,5 +2,5 @@
# 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 docs/core-data-structures/session.md
session.md: fd8285eebd76e8bd7723ee86ae15427f4923f4d6
session.zh.md: 1033bfda117b5693421f0bdf4ec3fc136039f223
session.md: 20942722c2c1f86bf9a2b6007ad42c9e97d43b91
session.zh.md: 87ca7dc44ad4ac19456679ecbffd08cfd3023296

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

@@ -91,6 +91,26 @@ interface SessionEventMap {
* It is log-only; the latest snapshot reconstructs the request header.
*/
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
/**
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
* BELOW it was inherited through a constructor seed — resume, fork, or replay
* — and no writer in this session's lifecycle produced it. Appended as the
* first live event of every seeded session.
*
* A plugin owning a standalone open/close bracket (`compact/start` …
* `compact/end`) needs it because inherited history and live work are
* otherwise byte-identical: an unmatched opening marker below this boundary
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
* the process succeeded it, or the events were forked out of a parent that is
* still running. Read it through `isInheritedSeq`.
*
* NOT a liveness signal about other writers: a concurrently live session may
* hold an open bracket over the same stored history with its own boundary
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
*
* The payload is empty by design — position and `time` carry the meaning.
*/
'session/inherited': Record<string, never>
}
```
@@ -326,8 +346,12 @@ declare class Session {
* log as a publication substitute (telemetry adoption) start here. Distinct
* from `header.seedLength`, the DURABLE fork-lineage boundary: a resumed
* session's constructor seed is its full stored log, while its header keeps
* the original fork value — this field is the in-process construction fact
* and is deliberately not persisted.
* the original fork value — this field is the in-process construction fact.
*
* Not persisted itself: a nonzero value is projected into the log as the
* `session/inherited` event at this seq, which is what a consumer reading
* STORED history reads. Prefer this field in-process — it is exact before
* the marker's write reaches storage.
*/
readonly firstLiveSeq: number;
constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);
@@ -507,6 +531,14 @@ A turn encloses one model-loop execution, not the whole session log. Idle inject
The optional `dsh-session/invariant` companion enforces the relations owned by core: turn and step numbering, execution-event enclosure, and same-step tool call/result pairing. Merge-extensible event relations belong to the plugin that declares them, so core does not reject an unknown event merely because no turn is open. See [the standalone-event decision](../../.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md).
## The inherited-history boundary: `session/inherited`
A seeded session — resume, fork, or replay — appends this log-only event as its first live write, at the seq its `firstLiveSeq` names. It is the durable projection of that field: `firstLiveSeq` answers "which prefix did I inherit" for a consumer holding the object, this event for one holding only stored bytes. The payload is empty, so position and `time` carry the whole meaning, and it produces no message. An empty seed writes nothing, and a seed already ending in one is not re-marked, so reopening an untouched session does not grow its log per open.
It exists because inherited history and live work are otherwise byte-identical, which defeats any plugin owning a standalone open/close bracket: an unmatched `compact/start` reads the same whether the writer crashed mid-compaction or is compacting right now. `isInheritedSeq(events, seq)` is the predicate a bracket owner calls — true means the opening marker belongs to an ended lifecycle, whatever ended it (a crash, a succeeding process, or a fork out of a still-running parent). It classifies only brackets *this* session inherited: a concurrently live session holding an open bracket over the same history has its own boundary elsewhere, so tolerating concurrent writers needs a liveness signal beyond the log. Core writes the boundary and reads nothing from it — a bracket's vocabulary stays with its owning plugin, which is why crash repair closes turn/step/tool boundaries and never `compact/*`.
Activity ordering excludes the boundary through `lastActivityTime(events)`: picking a session up is not work, and lazy resume means browsing writes one, so a resume picker or session list ordering by log tail would float every opened session to the top.
## Plugin-contributed log-only events
A plugin may declaration-merge extra `SessionEventMap` types. These are **log-only**: NOT `SurfaceEventType`s (they carry no `surfaceOp` and contribute nothing to derived history). Their owner decides whether they belong to an open execution turn or may stand between turns, and enforces any relation in its own invariant companion. The full per-event enumeration — core and plugin-contributed alike, with payloads and provenance — is the generated [persistence log event catalog](../persistence-catalog.md); the compaction seam's `compact/*` semantics are discussed on [compaction.md](compaction.md).

36
docs/core-data-structures/session.zh.md
View File

@@ -91,6 +91,26 @@ interface SessionEventMap {
* It is log-only; the latest snapshot reconstructs the request header.
*/
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
/**
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
* BELOW it was inherited through a constructor seed — resume, fork, or replay
* — and no writer in this session's lifecycle produced it. Appended as the
* first live event of every seeded session.
*
* A plugin owning a standalone open/close bracket (`compact/start` …
* `compact/end`) needs it because inherited history and live work are
* otherwise byte-identical: an unmatched opening marker below this boundary
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
* the process succeeded it, or the events were forked out of a parent that is
* still running. Read it through `isInheritedSeq`.
*
* NOT a liveness signal about other writers: a concurrently live session may
* hold an open bracket over the same stored history with its own boundary
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
*
* The payload is empty by design — position and `time` carry the meaning.
*/
'session/inherited': Record<string, never>
}
```
@@ -328,8 +348,12 @@ declare class Session {
* log as a publication substitute (telemetry adoption) start here. Distinct
* from `header.seedLength`, the DURABLE fork-lineage boundary: a resumed
* session's constructor seed is its full stored log, while its header keeps
* the original fork value — this field is the in-process construction fact
* and is deliberately not persisted.
* the original fork value — this field is the in-process construction fact.
*
* Not persisted itself: a nonzero value is projected into the log as the
* `session/inherited` event at this seq, which is what a consumer reading
* STORED history reads. Prefer this field in-process — it is exact before
* the marker's write reaches storage.
*/
readonly firstLiveSeq: number;
constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);
@@ -511,6 +535,14 @@ interface TurnEndReasonMap {
可选的 `dsh-session/invariant` 配套插件会强制核心拥有的关系：轮次与步骤编号、执行事件封闭，以及同一步骤内的工具调用／结果配对。可合并扩展事件的关系由声明它的插件拥有，因此核心不会仅因没有开放轮次就拒绝未知事件。见[独立事件决策](../../.agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.md)。
## 继承历史边界：`session/inherited`
带种子的会话（恢复、fork 或重放）把这个仅日志事件作为自己的第一次实时写入追加，位置正是 `firstLiveSeq` 指出的 seq。它是该字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答"我继承了哪一段前缀"，这个事件则为只持有存储字节的消费方回答同一问题。payload 为空，因此位置与 `time` 承载全部含义，且不产生任何消息。空种子不写入任何内容；种子本身已以该事件结尾时不会重复标记，因此重新打开一个未被改动的会话不会每次打开都增长日志。
它之所以必要，是因为继承历史与实时工作在字节层面完全相同，这会让任何拥有独立开／闭括号的插件失效：一个未配对的 `compact/start`，无论写入方是在压缩中途崩溃、还是此刻正在压缩，读起来都一样。`isInheritedSeq(events, seq)` 就是括号所有方调用的谓词——为真意味着该开启标记属于一个已结束的生命周期，无论结束原因为何（崩溃、进程接替，或从仍在运行的父会话 fork 出来）。它只判定*本*会话继承的括号：另一个并发存活的会话可能在同一段历史上持有开放括号，而它自己的边界在别处，因此容忍并发写入方还需要日志之外的存活信号。核心写入该边界但不从中读取任何内容——括号的词汇表仍归其所属插件，这也正是崩溃修复只关闭轮次／步骤／工具边界而从不处理 `compact/*` 的原因。
活动排序通过 `lastActivityTime(events)` 排除该边界：接手会话不算工作，而惰性恢复意味着浏览就会写入一个，因此按日志尾部排序的恢复选择器或会话列表会把每个打开过的会话顶到最前。
## 插件贡献的仅日志事件
插件可以通过 declaration merging 添加额外的 `SessionEventMap` 类型。这些是**仅日志**事件：不是 `SurfaceEventType`（不携带 `surfaceOp`，不参与派生历史）。事件所有方决定它们属于一个开放的执行轮次，还是可以独立位于轮次之间，并在自己的不变量配套插件中强制所需关系。完整的逐事件枚举（核心与插件贡献的，含 payload 与溯源信息）见生成的[持久化日志事件目录](../persistence-catalog.md)；压缩 seam 的 `compact/*` 语义在 [compaction.md](compaction.md) 中讨论。

29
docs/persistence-catalog.md
View File

@@ -78,7 +78,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
}[T]
```
Sources: [`packages/core/session/src/types.ts:256`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:292`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:324`](../packages/core/session/src/types.ts)
Sources: [`packages/core/session/src/types.ts:276`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:283`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:312`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts)
## Events
@@ -404,6 +404,33 @@ Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/s
### `session/*`
#### `session/inherited` — log-only
```ts persistence-catalog
/**
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
* BELOW it was inherited through a constructor seed — resume, fork, or replay
* — and no writer in this session's lifecycle produced it. Appended as the
* first live event of every seeded session.
*
* A plugin owning a standalone open/close bracket (`compact/start` …
* `compact/end`) needs it because inherited history and live work are
* otherwise byte-identical: an unmatched opening marker below this boundary
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
* the process succeeded it, or the events were forked out of a parent that is
* still running. Read it through `isInheritedSeq`.
*
* NOT a liveness signal about other writers: a concurrently live session may
* hold an open bracket over the same stored history with its own boundary
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
*
* The payload is empty by design — position and `time` carry the meaning.
*/
'session/inherited': Record<string, never>
```
Source: [`packages/core/session/src/types.ts:272`](../packages/core/session/src/types.ts)
#### `session/title` — log-only
```ts persistence-catalog