From 8ff30ebd9676aef1e4d9083d3a2d43d887d33037 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 19 Oct 2026 02:57:09 +0800 Subject: [PATCH] docs(session-projection): state the shipped summary behavior --- ...-10-18-session-list-summary-projections.i18n.yaml | 12 ++++++------ .../2026-10-18-session-list-summary-projections.md | 8 ++++---- ...2026-10-18-session-list-summary-projections.zh.md | 8 ++++---- docs/subsystems/session-projection.i18n.yaml | 4 ++-- docs/subsystems/session-projection.md | 2 +- docs/subsystems/session-projection.zh.md | 3 ++- 6 files changed, 19 insertions(+), 18 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.i18n.yaml index aa165b3f50..954a507a27 100644 --- a/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.i18n.yaml @@ -6,8 +6,8 @@ en: 983b028b1d2aeb7c zh: 2a2d3ced786ee686 /agent-note-serve-session-list-rows-from-a-summary-key-set/problem: - en: f5ca718ca5e618c6 - zh: cbea7f94a2a293b0 + en: 9f84c9bd85b6aace + zh: 8ebb10962c219624 /agent-note-serve-session-list-rows-from-a-summary-key-set/decision: en: 6e8f43d7a53c35fd zh: a6e2bccc20474515 @@ -15,8 +15,8 @@ en: ce8320f1032018ed zh: 4c5fad5e605bf524 /agent-note-serve-session-list-rows-from-a-summary-key-set/consequences: - en: d0d9bc21e9bb2480 - zh: 3bccbf0b6c4a416c + en: d3465b78160d8c1b + zh: dcbad6768b74b2bf /agent-note-serve-session-list-rows-from-a-summary-key-set/testing: - en: 48ee647077dcecde - zh: b079a5920c33504f + en: 6b34571bdadb0a9d + zh: 41ebfc1b5325b8d6 diff --git a/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.md b/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.md index f860de3580..89e7b2c37d 100644 --- a/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.md +++ b/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.md @@ -6,7 +6,7 @@ English | [中文](2026-10-18-session-list-summary-projections.zh.md) ## Problem -A Session-list row carries every registered client view. Three of those views are never rendered by a row: the whole-log turn outline, the whole-log conversation figures, and the current todo list. The outline grows with the Session's log, so a list payload scales with corpus size and log length even though no row shows it. Omitting values from the list needs a rule that keeps the wire and client types honest: a caller must not be able to request an omitted key, a value that is omitted must still reach an opened Session, and the owning packages must not drift from whatever declaration drives the omission. +A Session-list row carries every registered client view. Four of those views are never rendered by a row: the whole-log turn outline, the whole-log conversation figures, the current todo list, and the host-wide image limits. The outline grows with the Session's log, so a list payload scales with corpus size and log length even though no row shows it. Omitting values from the list needs a rule that keeps the wire and client types honest: a summary consumer must not obtain an omitted key, a value that is omitted must still reach an opened Session, and the owning packages must not drift from whatever declaration drives the omission. ## Decision @@ -35,7 +35,7 @@ Estimated effect: with logs whose outlines dominate the projection payload, the ## Consequences -Bought: a list response no longer scales with outline length or log count, the excluded keys cannot be requested by name, and reading an excluded key from a list row is a type error. The registration interlock makes a marked key without `summary: false` (and the reverse) a compile error rather than a review finding. +Bought: a list response no longer scales with outline length or log count, a summary consumer cannot obtain an excluded key through the derived set (the complete faces still serve an explicitly named key), and reading an excluded key from a list row's type is a type error. `wire.summary` is a plain boolean, so keeping a marked key at `false` is the registering package's responsibility rather than a compile error. A list row carries the summary projection, never the full projection: it promises the summary key set and nothing more. A connected Session's client store may hold more values from its control/follow baseline, but those are outside the list contract and must not be read from a row; the opened Session's own baselines keep every value. @@ -45,8 +45,8 @@ Paid: `ProjectionKeySelection` is a new public signature type and `ReadonlySet` ## Testing -- [`packages/api/session-controller/tests/summary-list.host.spec.ts`](../../../../packages/api/session-controller/tests/summary-list.host.spec.ts): a list row's keys equal the registry's complete snapshot minus the three, a `session/follow` opening snapshot still carries the three with equal values, and two consecutive pulls do not re-add them. +- [`packages/api/session-controller/tests/summary-list.host.spec.ts`](../../../../packages/api/session-controller/tests/summary-list.host.spec.ts): a list row's keys equal the registry's complete snapshot minus the marked keys, a `session/follow` opening snapshot still carries them with equal values, and two consecutive pulls do not re-add them. - [`packages/session/session-projection/tests/summary.spec.ts`](../../../../packages/session/session-projection/tests/summary.spec.ts): the derived set, its stable identity, its rebuild after registration and disposal, summary-shaped reads through the key-taking faces, an empty summary set, and the nullable mark. - [`packages/session/session-projection-cache/tests/cache.spec.ts`](../../../../packages/session/session-projection-cache/tests/cache.spec.ts): a summary read from stored rows omits the marked key and takes its watermark from the served rows only. -- [`packages/api/session-controller/tests/summary-types.client.spec.ts`](../../../../packages/api/session-controller/tests/summary-types.client.spec.ts): `@ts-expect-error` reads of the three keys on `SessionSummary.projectionValues`, with the full snapshot still exposing them and `todos` still nullable. +- [`packages/api/session-controller/tests/summary-types.client.spec.ts`](../../../../packages/api/session-controller/tests/summary-types.client.spec.ts): `@ts-expect-error` reads of `turnOutline`, `sessionStats`, and `todos` on `SessionSummary.projectionValues`, with the full snapshot still exposing them and `todos` still nullable. - [`packages/api/session-controller/tests/manager.client.spec.ts`](../../../../packages/api/session-controller/tests/manager.client.spec.ts): a reconnect refresh replaces the row block, so a stale excluded key does not survive. diff --git a/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.zh.md b/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.zh.md index c0bb13eec3..75c753c345 100644 --- a/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.zh.md +++ b/.agents/notes/implemented/architecture/2026-10-18-session-list-summary-projections.zh.md @@ -6,7 +6,7 @@ Status: implemented ## Problem -Session 列表行携带每个已注册的客户端视图。其中三个视图从不被行渲染：整份日志的 turn outline、整份日志的会话统计，以及当前 todo 清单。outline 随 Session 日志增长，因此列表响应会随语料规模与日志长度增长，而没有一行展示它。从列表省略取值需要一条规则同时守住 wire 与客户端类型：调用方不能按名请求被省略的键；被省略的值仍要送达打开的 Session；owning package 不得与驱动省略的声明漂移。 +Session 列表行携带每个已注册的客户端视图。其中四个视图从不被行渲染：整份日志的 turn outline、整份日志的会话统计、当前 todo 清单，以及宿主级的图片上限。outline 随 Session 日志增长，因此列表响应会随语料规模与日志长度增长，而没有一行展示它。从列表省略取值需要一条规则同时守住 wire 与客户端类型：摘要消费方不能取得被省略的键；被省略的值仍要送达打开的 Session；owning package 不得与驱动省略的声明漂移。 ## Decision @@ -35,7 +35,7 @@ Session 摘要就是每个已注册客户端视图，减去 `SessionProjectionMa ## Consequences -换来的：列表响应不再随 outline 长度或日志数量增长；被排除的键无法按名请求；从列表行读取被排除键是类型错误。注册互锁让「带标记却未声明 `summary: false`」（以及反向）成为编译错误，而不是评审发现。 +换来的：列表响应不再随 outline 长度或日志数量增长；摘要消费方无法通过派生集合取得被排除的键（完整读取面仍按显式键提供）；从列表行的类型读取被排除键是类型错误。`wire.summary` 是普通布尔值，因此让带标记的键保持 `false` 是注册方自己的责任，而不是编译错误。 列表行携带的是摘要投影，绝不是全量投影：它只承诺摘要键集合，不承诺更多。已连接 Session 的客户端 store 可能因 control/follow 基线持有更多值，但那不属于列表契约，不得从行上读取；打开的 Session 自身的基线保留全部取值。 @@ -45,8 +45,8 @@ Session 摘要就是每个已注册客户端视图，减去 `SessionProjectionMa ## Testing -- [`packages/api/session-controller/tests/summary-list.host.spec.ts`](../../../../packages/api/session-controller/tests/summary-list.host.spec.ts)：列表行的键等于注册表完整快照减去三个键；`session/follow` 初始快照仍携带这三个键且值相等；连续两次拉取不会重新加入它们。 +- [`packages/api/session-controller/tests/summary-list.host.spec.ts`](../../../../packages/api/session-controller/tests/summary-list.host.spec.ts)：列表行的键等于注册表完整快照减去被标记的键；`session/follow` 初始快照仍携带它们且值相等；连续两次拉取不会重新加入它们。 - [`packages/session/session-projection/tests/summary.spec.ts`](../../../../packages/session/session-projection/tests/summary.spec.ts)：派生集合、其稳定实例、注册与注销后的重建、经带键读取面的摘要式读取、空摘要集合，以及可空标记。 - [`packages/session/session-projection-cache/tests/cache.spec.ts`](../../../../packages/session/session-projection-cache/tests/cache.spec.ts)：从持久行读取摘要时省略被标记键，且水位只取自被服务的行。 -- [`packages/api/session-controller/tests/summary-types.client.spec.ts`](../../../../packages/api/session-controller/tests/summary-types.client.spec.ts)：在 `SessionSummary.projectionValues` 上读取三个键触发 `@ts-expect-error`，而完整快照仍暴露它们且 `todos` 仍可空。 +- [`packages/api/session-controller/tests/summary-types.client.spec.ts`](../../../../packages/api/session-controller/tests/summary-types.client.spec.ts)：在 `SessionSummary.projectionValues` 上读取 `turnOutline`、`sessionStats`、`todos` 触发 `@ts-expect-error`，而完整快照仍暴露它们且 `todos` 仍可空。 - [`packages/api/session-controller/tests/manager.client.spec.ts`](../../../../packages/api/session-controller/tests/manager.client.spec.ts)：断线重连刷新会替换行块，残留的被排除键不会存活。 diff --git a/docs/subsystems/session-projection.i18n.yaml b/docs/subsystems/session-projection.i18n.yaml index 441f6f2604..25f948c599 100644 --- a/docs/subsystems/session-projection.i18n.yaml +++ b/docs/subsystems/session-projection.i18n.yaml @@ -15,8 +15,8 @@ en: d2bc9bcc775acfb7 zh: b1d2ba74496305b8 /session-projections/summary-reads/summary-vocabulary: - en: 5920d94f98fb323a - zh: a0e24d6ad2a6b739 + en: 6a93a4e1682fd6e6 + zh: 28729129c3d8a3b1 /session-projections/the-registry-ctx-sessionprojections: en: 50e79c1bc16abb63 zh: 200ecbf0e4ab19d2 diff --git a/docs/subsystems/session-projection.md b/docs/subsystems/session-projection.md index 26f7f2472f..69bda39657 100644 --- a/docs/subsystems/session-projection.md +++ b/docs/subsystems/session-projection.md @@ -119,7 +119,7 @@ A list row carries that summary projection, never the full projection: it promis ### Summary vocabulary -Each block below is the declaration the summary rule is stated in. The mark, its stripping, the excluded-key test, and the summary value type live in the pure-type outlet; the key selection both read faces accept lives in the service module. +The declarations below state the summary rule. The mark, its stripping, the excluded-key test, and the summary value type are declared in the pure-type outlet; the key selection both read faces accept is declared in the service module. ```ts type-equiv /** diff --git a/docs/subsystems/session-projection.zh.md b/docs/subsystems/session-projection.zh.md index 0bc04d3d95..8385dddb3b 100644 --- a/docs/subsystems/session-projection.zh.md +++ b/docs/subsystems/session-projection.zh.md @@ -116,9 +116,10 @@ Session 摘要包含每个已注册客户端视图，但排除 `SessionProjectio `summaryKeys()` 从实时注册派生该集合，并在注册或注销改变 key 表之前持续返回同一实例。摘要消费方把它传给既有的带 key 读取面 —— 缓存 cell 用 `cachedSnapshot(session, keys)`，checkpoint 行用 `viewCheckpoint(rows, keys)`，两者保持各自的水位规则且直接使用 Set、不做复制 —— 因此不存在摘要专用读取面，集合也只有一处定义。 列表行携带的是这个摘要投影，绝不是全量投影：它只承诺摘要键集合，不承诺更多。`snapshot`、`cachedSnapshot` 与 `viewCheckpoint` 在不传 key 子集时仍是完整的，打开的 Session、其 follow 基线与控制基线因此保留每个投影值；`@` 引用只通过同一组带 key 的读取面读取其标签 key。 + ### 摘要词汇 -以下每块都是摘要规则所依据的声明。标记、其剥离、被排除键的判定与摘要值类型位于纯类型出口；两个读取面共同接受的 key 选择位于服务模块。 +以下声明构成摘要规则。标记、其剥离、被排除键的判定与摘要值类型声明在纯类型出口；两个读取面共同接受的 key 选择声明在服务模块。 ```ts type-equiv /**