refactor(session-projection): review fixes for the summary key set

- Export `ProjectionKeySelection` (the read faces' key selection) and reuse it
  from the projection cache instead of restating the union twice. The Cordis
  catalog can now resolve the type its generated signatures reference.
- Make `wire.summary` a plain boolean: omitted means `true`, and a key whose
  map entry carries the summary mark declares `false` so the runtime key set
  and the client view type agree. The type no longer forbids a declaration.
- Describe the mark accurately: it has no runtime representation; `wire.view`
  and `viewSchema` are typed with `SessionProjectionViewValue`, which strips it,
  so the registration erase only widens the state type.
- Say plainly in the package README, the subsystem page, the client field
  comments, and the Agent Note that a list row carries the summary projection
  and never the full projection: a connected Session's store may hold more
  values, but those are outside the list contract.
- Document the summary vocabulary on the subsystem page with `ts type-equiv`
  blocks for the mark, its stripping, the excluded-key test, the summary value
  type, and the key selection; split the prose paragraph.
- Revert the behavior-neutral cache-double refactors in three specs, and record
  in the Agent Note why no upgrade guide accompanies the wire change and how a
  consumer migrates.
This commit is contained in:
imccyu committed 2026-10-19 01:13:24 +08:00
1 parent 64a1d1e95f
commit f230fc2fc2
21 files changed
+312 -106

No files matched your search

@@ -9,7 +9,12 @@ import type { SessionSummary } from '../../types.ts'
/** Host list summary enriched with the latest Session Controller title projection. */
export interface TitledSessionSummary extends SessionSummary {
title?: string
/** Current host-computed summary projection values for list consumers. */
/**
* The row's summary projection values, never the full projection set. A
* connected Session's client store may hold more values from its
* control/follow baseline; those are outside the list contract and must not
* be read here.
*/
projectionValues?: Readonly<Partial<SessionProjectionSummaryValues>>
}
@@ -30,7 +35,10 @@ export interface SessionListEntry {
/** Format classification supplied by the Host list. */
formatStatus?: SessionSummary['formatStatus']
cwd?: string
/** Current host-computed summary projection values for list consumers. */
/**
* The row's summary projection values, never the full projection set; see
* `TitledSessionSummary.projectionValues`.
*/
projectionValues?: Readonly<Partial<SessionProjectionSummaryValues>>
/** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
depth: number
@@ -58,7 +58,12 @@ export interface SessionListSnapshot {
}
/** Shared projection values and the lifecycle of their explicit baseline read. */
/**
* Every projection value the store currently holds, with the summary mark
* stripped, and the lifecycle of its explicit baseline read. This is the full
* attached-Session set, not a list row's summary contract (see
* `SessionListEntry.projectionValues`).
*/
export interface SessionProjectionSnapshot {
readonly values: Readonly<Partial<SessionProjectionViewValues>>
readonly state: 'idle' | 'loading' | 'ready' | 'migration-required' | 'error'
@@ -49,7 +49,11 @@ export interface SessionSummary {
*/
blank: boolean
updatedAt: number
/** Current host-computed summary projection values retained by the object layer. */
/**
* The row's summary projection values retained by the object layer, never the
* full projection set. A connected Session's store may hold more values from
* its control/follow baseline; those are outside the list contract.
*/
projectionValues?: Readonly<Partial<SessionProjectionSummaryValues>>
}
+4 -3
View File
@@ -319,7 +319,8 @@ export class ApiSessionList {
}
/**
* Wrap one projection block as Session-list hints of the named sequence space.
* Wrap one summary projection block as Session-list hints of the named sequence space.
* The block is the summary key set's values, not every value the source holds.
* @param kind - which sequence space the block's watermark belongs to.
* @param block - the block, or `undefined` when no source served one.
* @returns the hints, or `undefined` when the block is absent or carries no value.
@@ -329,8 +330,8 @@ function hintsOf(
block: ProjectionSnapshot | undefined,
): SessionProjectionHints | undefined {
if (block === undefined || Object.keys(block.values).length === 0) return undefined
// Listing hints contain every wire value the source currently holds but
// remain partial: missing cells and cache rows are never materialized here.
// Listing hints contain every summary wire value the source currently holds
// but remain partial: missing cells and cache rows are never materialized here.
return { kind, asOfSeq: block.asOfSeq, values: block.values as SessionProjectionValues }
}