This document explains the fine-grained editing timeline file that coexists with (but is separate from) the canonical chatSessions history. It captures incremental multi-file edit evolution, undo boundaries, and per-file telemetry request identifiers.

Provide a replayable timeline of an editing turn's internal phases: which files changed, at which undo boundary, and under which underlying model request (telemetryInfo.requestId). Enables:

• Accurate counting of model (HTTP) calls that led to persisted edits.
• Distinguishing context (unchanged) files from actively modified ones.
• Reconstructing per-file diff progression across "stops".

{
  version: number,
  sessionId: string,
  linearHistory: [ TurnTimeline, ... ]
}

TurnTimeline (conceptual turn): {
  requestId: string,          // turnId (high-level)
  stops: [ Stop, ... ]
}

Stop (undo boundary): {
  stopId?: string,            // absent for initial placeholder stop
  entries: [ FileEntry, ... ]
}

FileEntry: {
  resource: string,           // file URI
  languageId: string,
  originalHash: string,       // file content hash before this turn (empty sentinel possible)
  currentHash: string,        // hash after this stop
  state: number,              // small status flag (0/1 observed)
  snapshotUri: string,        // internal snapshot reference
  telemetryInfo: { requestId: string, agentId: string }
}

Turn (requestId) groups user-visible action; model request (telemetryInfo.requestId) is the underlying backend invocation that produced specific file modifications. A turn may reference multiple distinct model requestIds (retries, staged generations, refinement phases) or inherit untouched files from prior turns retaining their original telemetry IDs.

Each stop represents a cohesive batch of changes such that one editor undo would revert the group. Multiple stops appear as the agent refines output or files are sequentially updated.

An entry captures the file's state after applying changes for that stop. Re-emission across stops allows full reconstruction without computing cumulative diffs.

Change detection logic for enrichment:

changed = (
  firstAppearance && originalHash !== currentHash
) || (
  previousStopHash !== currentHash
)

Only entries producing changed = true should count toward model request attribution (to avoid inflating counts with carry-over context entries).

Model Request → File Entries: 1 → many (one model invocation can modify multiple files in a stop or across consecutive stops if the same invocation ID persists). Turn → Model Requests: 1 → many (retries, staged passes) BUT the file may retain older telemetry IDs for unchanged context.

Context (carry-over) entry heuristics:

• originalHash === currentHash on first appearance AND never changes in later stops.
• All appearances of that resource share a telemetryInfo.requestId ≠ parent turnId and the file never changes → purely contextual.

Active edit entries are those where at least one stop yields changed = true.

For each turn (top-level requestId):

modelRequestIds: string[]                // unique telemetryInfo.requestIds for *changed* files only
allModelRequestIds?: string[]            // (optional) including context
modelRequestsCount: number               // modelRequestIds.length
contextOnlyRequestIds?: string[]         // telemetry IDs seen but no file changes
changedFiles: number                     // number of files with >=1 change
stops: number                            // total stops for this turn

1. Implement EditStateScanner to locate and parse state files.
2. Build per-turn summaries (hash tracking + telemetry sets).
3. Enrich existing usage events post SessionDataTransformer using (sessionId, requestId) key.
4. Add debug command to dump correlation vs logs.
5. (Optional) Feature flag the enrichment initially.

Revision History:

• v1 (initial extraction) – codifies observed semantics & enrichment strategy.