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:
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>>
|
||||
}
|
||||
|
||||
|
||||
@@ -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 }
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user