pi-readcache 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,8 @@
 # 🧠 pi-readcache
 
 [![pi coding agent](https://img.shields.io/badge/pi-coding%20agent-6f6bff?logo=terminal&logoColor=white)](https://pi.dev/)
-[![license](https://img.shields.io/npm/l/pi-mermaid.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/pi-readcache.svg)](https://www.npmjs.com/package/pi-readcache)
+[![license](https://img.shields.io/npm/l/pi-readcache.svg)](LICENSE)
 
 A pi extension that overrides the built-in `read` tool with hash-based, replay-aware caching.
 
@@ -127,15 +128,15 @@ Rules:
 
 ## File map
 
-- `extension/index.ts` - extension entrypoint + lifecycle reset hooks
-- `extension/src/tool.ts` - `read` override decision engine
-- `extension/src/replay.ts` - replay reconstruction, trust transitions, overlay
-- `extension/src/meta.ts` - metadata/invalidation validators and extractors
-- `extension/src/commands.ts` - `/readcache-status`, `/readcache-refresh`, `readcache_refresh`
-- `extension/src/object-store.ts` - content-addressed storage (`.pi/readcache/objects`)
-- `extension/src/diff.ts` - unified diff creation + usefulness gating
-- `extension/src/path.ts` - path/range parsing and normalization
-- `extension/src/telemetry.ts` - replay window/mode/savings reporting
+- `index.ts` - extension entrypoint + lifecycle reset hooks
+- `src/tool.ts` - `read` override decision engine
+- `src/replay.ts` - replay reconstruction, trust transitions, overlay
+- `src/meta.ts` - metadata/invalidation validators and extractors
+- `src/commands.ts` - `/readcache-status`, `/readcache-refresh`, `readcache_refresh`
+- `src/object-store.ts` - content-addressed storage (`.pi/readcache/objects`)
+- `src/diff.ts` - unified diff creation + usefulness gating
+- `src/path.ts` - path/range parsing and normalization
+- `src/telemetry.ts` - replay window/mode/savings reporting
 
 ## Tool-override compatibility contract
 
@@ -147,7 +148,6 @@ Because this overrides built-in `read`, it must preserve:
 ## Development
 
 ```bash
-cd extension
 npm install
 npm run typecheck
 npm test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readcache",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "🧠 Pi extension that optimizes read tool calls with replay-aware caching and compaction-safe trust reconstruction",
   "author": "Gurpartap Singh",
   "license": "MIT",

package/src/replay.ts

@@ -6,20 +6,28 @@ import type {
 	ReadCacheInvalidationV1,
 	ReadCacheMetaV1,
 	ScopeKey,
+	ScopeRangeKey,
 	ScopeTrust,
 } from "./types.js";
 
 type SessionManagerView = ExtensionContext["sessionManager"];
 
+type RangeBlockersByPath = Map<string, Set<ScopeRangeKey>>;
+
 const OVERLAY_SEQ_START = 1_000_000_000;
 
+interface ReplayMemoEntry {
+	knowledge: KnowledgeMap;
+	blockedRangesByPath: RangeBlockersByPath;
+}
+
 interface OverlayState {
 	leafId: string | null;
 	knowledge: KnowledgeMap;
 }
 
 export interface ReplayRuntimeState {
-	memoByLeaf: Map<string, KnowledgeMap>;
+	memoByLeaf: Map<string, ReplayMemoEntry>;
 	overlayBySession: Map<string, OverlayState>;
 	nextOverlaySeq: number;
 }
@@ -41,6 +49,21 @@ function cloneKnowledgeMap(source: KnowledgeMap): KnowledgeMap {
 	return cloned;
 }
 
+function cloneRangeBlockersByPath(source: RangeBlockersByPath): RangeBlockersByPath {
+	const cloned: RangeBlockersByPath = new Map();
+	for (const [pathKey, scopes] of source.entries()) {
+		cloned.set(pathKey, new Set(scopes));
+	}
+	return cloned;
+}
+
+function cloneReplayMemoEntry(source: ReplayMemoEntry): ReplayMemoEntry {
+	return {
+		knowledge: cloneKnowledgeMap(source.knowledge),
+		blockedRangesByPath: cloneRangeBlockersByPath(source.blockedRangesByPath),
+	};
+}
+
 function getMemoKey(sessionId: string, leafId: string | null, boundaryKey: string): string {
 	return `${sessionId}:${leafId ?? "null"}:${boundaryKey}`;
 }
@@ -55,6 +78,36 @@ function ensureScopeMap(knowledge: KnowledgeMap, pathKey: string): Map<ScopeKey,
 	return created;
 }
 
+function isRangeScope(scopeKey: ScopeKey): scopeKey is ScopeRangeKey {
+	return scopeKey !== SCOPE_FULL;
+}
+
+function ensureRangeBlockerSet(blockedRangesByPath: RangeBlockersByPath, pathKey: string): Set<ScopeRangeKey> {
+	const existing = blockedRangesByPath.get(pathKey);
+	if (existing) {
+		return existing;
+	}
+	const created = new Set<ScopeRangeKey>();
+	blockedRangesByPath.set(pathKey, created);
+	return created;
+}
+
+function setRangeBlocker(blockedRangesByPath: RangeBlockersByPath, pathKey: string, scopeKey: ScopeRangeKey): void {
+	const scopes = ensureRangeBlockerSet(blockedRangesByPath, pathKey);
+	scopes.add(scopeKey);
+}
+
+function clearRangeBlocker(blockedRangesByPath: RangeBlockersByPath, pathKey: string, scopeKey: ScopeRangeKey): void {
+	const scopes = blockedRangesByPath.get(pathKey);
+	if (!scopes) {
+		return;
+	}
+	scopes.delete(scopeKey);
+	if (scopes.size === 0) {
+		blockedRangesByPath.delete(pathKey);
+	}
+}
+
 export function getTrust(knowledge: KnowledgeMap, pathKey: string, scopeKey: ScopeKey): ScopeTrust | undefined {
 	return knowledge.get(pathKey)?.get(scopeKey);
 }
@@ -95,6 +148,61 @@ function leafHasChildren(sessionManager: SessionManagerView, leafId: string | nu
 	return sessionManager.getEntries().some((entry) => entry.parentId === leafId);
 }
 
+function replaySnapshotFromBranch(branchEntries: SessionEntry[], startIndex: number): ReplayMemoEntry {
+	const knowledge: KnowledgeMap = new Map();
+	const blockedRangesByPath: RangeBlockersByPath = new Map();
+	const normalizedStart = Math.max(0, Math.min(startIndex, branchEntries.length));
+	let seq = 0;
+
+	for (let index = normalizedStart; index < branchEntries.length; index += 1) {
+		const entry = branchEntries[index];
+		if (!entry) {
+			continue;
+		}
+
+		const meta = extractReadMetaFromSessionEntry(entry);
+		if (meta) {
+			seq += 1;
+			applyReadMetaTransition(knowledge, meta, seq, blockedRangesByPath);
+			continue;
+		}
+
+		const invalidation = extractInvalidationFromSessionEntry(entry);
+		if (invalidation) {
+			applyInvalidation(knowledge, invalidation, blockedRangesByPath);
+		}
+	}
+
+	return {
+		knowledge,
+		blockedRangesByPath,
+	};
+}
+
+function getReplayMemoEntryForLeaf(
+	sessionManager: SessionManagerView,
+	runtimeState: ReplayRuntimeState,
+): { memoEntry: ReplayMemoEntry; sessionId: string; leafId: string | null } {
+	const sessionId = sessionManager.getSessionId();
+	const leafId = sessionManager.getLeafId();
+	const branchEntries = sessionManager.getBranch();
+	const boundary = findReplayStartIndex(branchEntries);
+	const memoKey = getMemoKey(sessionId, leafId, boundary.boundaryKey);
+
+	let memoEntry = runtimeState.memoByLeaf.get(memoKey);
+	if (!memoEntry) {
+		const replayMemo = replaySnapshotFromBranch(branchEntries, boundary.startIndex);
+		memoEntry = cloneReplayMemoEntry(replayMemo);
+		runtimeState.memoByLeaf.set(memoKey, memoEntry);
+	}
+
+	return {
+		memoEntry,
+		sessionId,
+		leafId,
+	};
+}
+
 export function createReplayRuntimeState(): ReplayRuntimeState {
 	return {
 		memoByLeaf: new Map(),
@@ -128,13 +236,21 @@ export function findReplayStartIndex(branchEntries: SessionEntry[]): ReplayBound
 	};
 }
 
-export function applyReadMetaTransition(knowledge: KnowledgeMap, meta: ReadCacheMetaV1, seq: number): void {
+export function applyReadMetaTransition(
+	knowledge: KnowledgeMap,
+	meta: ReadCacheMetaV1,
+	seq: number,
+	blockedRangesByPath?: RangeBlockersByPath,
+): void {
 	const { pathKey, scopeKey, servedHash, baseHash, mode } = meta;
 	const fullTrust = getTrust(knowledge, pathKey, SCOPE_FULL);
 	const rangeTrust = scopeKey === SCOPE_FULL ? undefined : getTrust(knowledge, pathKey, scopeKey);
 
 	if (mode === "full" || mode === "full_fallback") {
 		setTrust(knowledge, pathKey, scopeKey, servedHash, seq);
+		if (blockedRangesByPath && isRangeScope(scopeKey)) {
+			clearRangeBlocker(blockedRangesByPath, pathKey, scopeKey);
+		}
 		return;
 	}
 
@@ -174,14 +290,24 @@ export function applyReadMetaTransition(knowledge: KnowledgeMap, meta: ReadCache
 	}
 }
 
-export function applyInvalidation(knowledge: KnowledgeMap, invalidation: ReadCacheInvalidationV1): void {
+export function applyInvalidation(
+	knowledge: KnowledgeMap,
+	invalidation: ReadCacheInvalidationV1,
+	blockedRangesByPath?: RangeBlockersByPath,
+): void {
 	const scopes = knowledge.get(invalidation.pathKey);
-	if (!scopes) {
-		return;
-	}
 
 	if (invalidation.scopeKey === SCOPE_FULL) {
 		knowledge.delete(invalidation.pathKey);
+		blockedRangesByPath?.delete(invalidation.pathKey);
+		return;
+	}
+
+	if (blockedRangesByPath && isRangeScope(invalidation.scopeKey)) {
+		setRangeBlocker(blockedRangesByPath, invalidation.pathKey, invalidation.scopeKey);
+	}
+
+	if (!scopes) {
 		return;
 	}
 
@@ -192,53 +318,40 @@ export function applyInvalidation(knowledge: KnowledgeMap, invalidation: ReadCac
 }
 
 export function replayKnowledgeFromBranch(branchEntries: SessionEntry[], startIndex: number): KnowledgeMap {
-	const knowledge: KnowledgeMap = new Map();
-	const normalizedStart = Math.max(0, Math.min(startIndex, branchEntries.length));
-	let seq = 0;
-
-	for (let index = normalizedStart; index < branchEntries.length; index += 1) {
-		const entry = branchEntries[index];
-		if (!entry) {
-			continue;
-		}
-
-		const meta = extractReadMetaFromSessionEntry(entry);
-		if (meta) {
-			seq += 1;
-			applyReadMetaTransition(knowledge, meta, seq);
-			continue;
-		}
-
-		const invalidation = extractInvalidationFromSessionEntry(entry);
-		if (invalidation) {
-			applyInvalidation(knowledge, invalidation);
-		}
-	}
-
-	return knowledge;
+	return replaySnapshotFromBranch(branchEntries, startIndex).knowledge;
 }
 
 export function buildKnowledgeForLeaf(
 	sessionManager: SessionManagerView,
 	runtimeState: ReplayRuntimeState,
 ): KnowledgeMap {
-	const sessionId = sessionManager.getSessionId();
-	const leafId = sessionManager.getLeafId();
-	const branchEntries = sessionManager.getBranch();
-	const boundary = findReplayStartIndex(branchEntries);
-	const memoKey = getMemoKey(sessionId, leafId, boundary.boundaryKey);
-
-	let replayKnowledge = runtimeState.memoByLeaf.get(memoKey);
-	if (!replayKnowledge) {
-		replayKnowledge = replayKnowledgeFromBranch(branchEntries, boundary.startIndex);
-		runtimeState.memoByLeaf.set(memoKey, cloneKnowledgeMap(replayKnowledge));
-	}
-
+	const { memoEntry, sessionId, leafId } = getReplayMemoEntryForLeaf(sessionManager, runtimeState);
 	const overlayState = ensureOverlayForLeaf(runtimeState, sessionId, leafId);
 	if (leafHasChildren(sessionManager, leafId)) {
 		overlayState.knowledge.clear();
 	}
-	return mergeKnowledge(replayKnowledge, overlayState.knowledge);
+	return mergeKnowledge(memoEntry.knowledge, overlayState.knowledge);
+}
+
+export function isRangeScopeBlockedByInvalidation(
+	sessionManager: SessionManagerView,
+	runtimeState: ReplayRuntimeState,
+	pathKey: string,
+	scopeKey: ScopeKey,
+): boolean {
+	if (!isRangeScope(scopeKey)) {
+		return false;
+	}
+
+	const { memoEntry, sessionId, leafId } = getReplayMemoEntryForLeaf(sessionManager, runtimeState);
+	const blockedScopes = memoEntry.blockedRangesByPath.get(pathKey);
+	if (!blockedScopes?.has(scopeKey)) {
+		return false;
+	}
+
+	const overlayState = ensureOverlayForLeaf(runtimeState, sessionId, leafId);
+	const overlayScopeTrust = overlayState.knowledge.get(pathKey)?.get(scopeKey);
+	return overlayScopeTrust === undefined;
 }
 
 export function overlaySet(

package/src/tool.ts

@@ -20,7 +20,13 @@ import { computeUnifiedDiff, isDiffUseful } from "./diff.js";
 import { buildReadCacheMetaV1 } from "./meta.js";
 import { hashBytes, loadObject, persistObjectIfAbsent } from "./object-store.js";
 import { normalizeOffsetLimit, parseTrailingRangeIfNeeded, scopeKeyForRange } from "./path.js";
-import { buildKnowledgeForLeaf, createReplayRuntimeState, overlaySet, type ReplayRuntimeState } from "./replay.js";
+import {
+	buildKnowledgeForLeaf,
+	createReplayRuntimeState,
+	isRangeScopeBlockedByInvalidation,
+	overlaySet,
+	type ReplayRuntimeState,
+} from "./replay.js";
 import { compareSlices, splitLines, truncateForReadcache } from "./text.js";
 import type {
 	ReadCacheDebugReason,
@@ -161,7 +167,11 @@ function buildDebugInfo(
 	};
 }
 
-function selectBaseTrust(pathKnowledge: Map<ScopeKey, ScopeTrust> | undefined, scopeKey: ScopeKey): ScopeTrust | undefined {
+function selectBaseTrust(
+	pathKnowledge: Map<ScopeKey, ScopeTrust> | undefined,
+	scopeKey: ScopeKey,
+	rangeScopeBlocked: boolean,
+): ScopeTrust | undefined {
 	if (!pathKnowledge) {
 		return undefined;
 	}
@@ -170,6 +180,10 @@ function selectBaseTrust(pathKnowledge: Map<ScopeKey, ScopeTrust> | undefined, s
 		return pathKnowledge.get(SCOPE_FULL);
 	}
 
+	if (rangeScopeBlocked) {
+		return undefined;
+	}
+
 	const exactTrust = pathKnowledge.get(scopeKey);
 	const fullTrust = pathKnowledge.get(SCOPE_FULL);
 	if (!exactTrust) {
@@ -290,7 +304,13 @@ export function createReadOverrideTool(runtimeState: ReplayRuntimeState = create
 			const scopeKey = scopeKeyForRange(start, end, totalLines);
 			const knowledge = buildKnowledgeForLeaf(ctx.sessionManager, runtimeState);
 			const pathKnowledge = knowledge.get(pathKey);
-			const baseHash = selectBaseTrust(pathKnowledge, scopeKey)?.hash;
+			const rangeScopeBlocked = isRangeScopeBlockedByInvalidation(
+				ctx.sessionManager,
+				runtimeState,
+				pathKey,
+				scopeKey,
+			);
+			const baseHash = selectBaseTrust(pathKnowledge, scopeKey, rangeScopeBlocked)?.hash;
 
 			if (!baseHash) {
 				const meta = buildReadcacheMeta(