1  // readcache/types.ts - types for read_file caching layer
 2  
 3  import type { SessionEntry } from "@mariozechner/pi-coding-agent";
 4  import type { SCOPE_FULL } from "./constants.js";
 5  
 6  export type ScopeRangeKey = `r:${number}:${number}`;
 7  export type ScopeKey = typeof SCOPE_FULL | ScopeRangeKey;
 8  
 9  export interface ScopeTrust {
10    hash: string;
11    seq: number;
12  }
13  
14  export type ReadCacheMode = "full" | "unchanged" | "unchanged_range" | "diff" | "baseline_fallback";
15  
16  export type ReadCacheDebugReason =
17    | "no_base_hash"
18    | "hash_match"
19    | "base_object_missing"
20    | "range_slice_unchanged"
21    | "range_slice_changed"
22    | "diff_file_too_large_bytes"
23    | "diff_file_too_large_lines"
24    | "diff_unavailable_or_empty"
25    | "diff_not_useful"
26    | "diff_payload_truncated"
27    | "diff_emitted"
28    | "bypass_cache";
29  
30  export interface ReadCacheDebugV1 {
31    reason: ReadCacheDebugReason;
32    scope: "full" | "range";
33    baseHashFound: boolean;
34    diffAttempted: boolean;
35    outsideRangeChanged?: boolean;
36    baseObjectFound?: boolean;
37    largestBytes?: number;
38    maxLines?: number;
39    diffBytes?: number;
40    diffChangedLines?: number;
41  }
42  
43  export interface RpReadcacheMetaV1 {
44    v: 1;
45    tool: "read_file";
46    pathKey: string;
47    scopeKey: ScopeKey;
48    servedHash: string;
49    baseHash?: string;
50    mode: ReadCacheMode;
51    totalLines: number;
52    rangeStart: number;
53    rangeEnd: number;
54    bytes: number;
55    debug?: ReadCacheDebugV1;
56  }
57  
58  export interface RpReadcacheInvalidationV1 {
59    v: 1;
60    kind: "invalidate";
61    tool: "read_file";
62    pathKey: string;
63    scopeKey: ScopeKey;
64    at: number;
65  }
66  
67  export type KnowledgeMap = Map<string, Map<ScopeKey, ScopeTrust>>;
68  
69  export interface ExtractedReplayData {
70    entry: SessionEntry;
71    read?: RpReadcacheMetaV1;
72    invalidation?: RpReadcacheInvalidationV1;
73  }
74  
75  export interface DiffLimits {
76    maxFileBytes: number;
77    maxFileLines: number;
78    maxDiffToBaseRatio: number;
79    maxDiffToBaseLineRatio: number;
80  }