docs: replace vague provenance prose with recorded facts

2026-08-09 15:35:02 +08:00
parent 8c124f84b6
commit 9704749b01
@@ -1,4 +1,4 @@
-// Context provenance projection: the role and the human-facing producer name
+// Context source projection: the role and the human-facing producer name
 // of one logged non-user `user/message`, read from its durable `source` alone.
 // The client keeps no table of known plugin ids — a renamed or newly mounted
 // producer must never need a client release to stay identifiable, and a resumed
@@ -191,14 +191,14 @@ export interface CompactionSummaryNode {
  seq: number
  /** Unix epoch ms of the checkpoint event. */
  time: number
-  /** Summary text from the checkpoint's `compact/summary` provenance; null when
-   *  the window cut left that provenance outside (the marker is then not expandable). */
+  /** Summary text from the checkpoint's cited `compact/summary` event; null when
+   *  the window cut left that event outside (the marker is then not expandable). */
  summary: string | null
-  /** Seq of the loaded `compact/summary` event, or null when that provenance is outside the window. */
+  /** Seq of the loaded `compact/summary` event, or null when that event is outside the window. */
  summaryEventSeq: number | null
-  /** Number of surface items replaced, or null when summary provenance is unavailable or malformed. */
+  /** Number of surface items replaced, or null when the summary event is unavailable or malformed. */
  shadowedItemCount: number | null
-  /** Estimated token price of the replaced items, or null when summary provenance is unavailable or malformed. */
+  /** Estimated token price of the replaced items, or null when the summary event is unavailable or malformed. */
  shadowedTokenCount: number | null
 }

@@ -686,7 +686,7 @@ export class Session implements SessionFace {
   *  a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
   *  expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
   *  raw range, which is what lets the transcript render every event between its ends and lets a
-   *  compaction checkpoint find its own provenance. */
+   *  compaction checkpoint find its cited summary event. */
  private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
    if (this.openState === 'loading' || this.stitching) {
      this.liveBuffer.push({ event, view })
@@ -184,10 +184,10 @@ function compactSummaryDetails(event: SessionEvent): CompactSummaryDetails {

 /**
 * One landed checkpoint -> the human-facing compaction marker. The summary text
- * comes from the checkpoint's own provenance (`sourceEventSeqs` names the
+ * comes from the checkpoint's cited `compact/summary` event (`sourceEventSeqs` names the
 * `compact/summary` event), never from the framed checkpoint payload, which is
 * an instruction envelope written for the model. A window cut that left the
- * provenance outside soft-falls to `summary: null` (a non-expandable marker),
+ * summary event outside soft-falls to `summary: null` (a non-expandable marker),
 * the same posture as a call-less tool result.
 */
 function materializeCompaction(
@@ -222,7 +222,7 @@ function materializeCompaction(

 /** Log-ordered human transcript over a paged raw event window (never consults surface order). */
 export class TranscriptAdapter {
-  /** Window events by seq: provenance lookup for a checkpoint's summary. */
+  /** Window events by seq, used to find the summary event cited by a checkpoint. */
  private eventIndex = new Map<number, SessionEvent>()
  /** Transcript nodes in log order; copy-on-write so a published array never mutates. */
  private projected: ConversationNode[] = []