fix(cache): project-docs change no longer forces an m[0] fold

A content change to ARCHITECTURE.md/STRUCTURE.md was a HARD mustMaterialize
trigger, so any on-disk docs change folded m[0] and busted the entire cached
prefix. In production this fired every time the dreamer's maintain-docs task
rewrote the docs — a real m[0] bust for every active session on that project
(confirmed live: cached prefix 599,885B → 28,187B, reason=project_docs_hash).

Project docs are slowly-changing reference material living in m[0]; they now
follow the 'Deliberately NOT triggers' pattern (like new compartments /
additive memories): ride along and fold into m[0] on the NEXT natural hard
bust, never force one. Removed projectDocsHash as a DECISION input at 6 sites
(both harnesses): mustMaterialize, the m[1] Phase-3 contention stale-check, and
the sibling CAS. KEPT computed-at-fold + stored, so a natural fold always reads
fresh docs (readProjectDocsCanonical) and persists the hash matching the bytes
it rendered. CAS removal is safe because the byte compare runs first — a
byte-different m[0] still rejects; only docs-hash-only drift with identical
bytes now matches.

Also fixes analyze-cache-busts.ts: verdict now compares the cached prefix
against the PREVIOUS request's last breakpoint (the old check used the current
request's moved-tail breakpoint and stamped normal tail growth as BUST);
timestamps include the date (multi-day dump sets were ambiguous).

Plugin 2010/0, Pi 445/0.

Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

packages/pi-plugin/src/inject-compartments-pi.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { appendCompartments } from "@magic-context/core/features/magic-context/compartment-storage";
@@ -1078,6 +1078,94 @@ describe("injectM0M1Pi", () => {
 			closeQuietly(db);
 		}
 	});
+
+	it("soft m1 refresh CAS rejects byte-different m[0] even when non-doc markers match", () => {
+		const db = createTestDb();
+		const cwd = mkdtempSync(join(tmpdir(), "pi-m1-soft-cas-bytes-"));
+		const originalExec = db.exec.bind(db);
+		try {
+			const state = piState("ses-pi-m1-soft-cas-bytes", cwd);
+			injectM0M1Pi(
+				state,
+				db,
+				[userMessage("hello", 10)] as never,
+				undefined,
+				true,
+			);
+			const siblingM0 = Buffer.from(
+				`<session-history>${"byte mismatch ".repeat(300)}</session-history>`,
+				"utf8",
+			);
+			let injectedSibling = false;
+			db.exec = ((sql: string) => {
+				if (sql === "BEGIN IMMEDIATE" && !injectedSibling) {
+					injectedSibling = true;
+					db.prepare(
+						"UPDATE session_meta SET cached_m0_bytes = ?, cached_m1_bytes = ? WHERE session_id = ?",
+					).run(
+						siblingM0,
+						Buffer.from("sibling cached pi m1 byte mismatch", "utf8"),
+						state.sessionId,
+					);
+				}
+				return originalExec(sql);
+			}) as typeof db.exec;
+
+			const bust = [userMessage("bust", 11)];
+			const result = injectM0M1Pi(state, db, bust as never, undefined, true);
+
+			expect(injectedSibling).toBe(true);
+			expect(result.m0Materialized).toBe(false);
+			expect(textOf(bust[0] as never)).toBe(siblingM0.toString("utf8"));
+			expect(textOf(bust[1] as never)).toBe(
+				"sibling cached pi m1 byte mismatch",
+			);
+		} finally {
+			db.exec = originalExec as typeof db.exec;
+			closeQuietly(db);
+		}
+	});
+
+	it("soft m1 refresh CAS treats docs-hash-only marker drift as a match", () => {
+		const db = createTestDb();
+		const cwd = mkdtempSync(join(tmpdir(), "pi-m1-soft-cas-docs-"));
+		const originalExec = db.exec.bind(db);
+		try {
+			const state = piState("ses-pi-m1-soft-cas-docs", cwd);
+			const first = [userMessage("hello", 10)];
+			injectM0M1Pi(state, db, first as never, undefined, true);
+			const baselineM0 = textOf(first[0] as never);
+			insertMemory(db, {
+				projectPath: state.projectIdentity,
+				category: "ARCHITECTURE",
+				content: "Pi docs-hash-only CAS delta memory",
+				sourceType: "agent",
+			});
+			let changedDocsMarker = false;
+			db.exec = ((sql: string) => {
+				if (sql === "BEGIN IMMEDIATE" && !changedDocsMarker) {
+					changedDocsMarker = true;
+					db.prepare(
+						"UPDATE session_meta SET cached_m0_project_docs_hash = ? WHERE session_id = ?",
+					).run("docs-only-marker-drift", state.sessionId);
+				}
+				return originalExec(sql);
+			}) as typeof db.exec;
+
+			const bust = [userMessage("bust", 11)];
+			const result = injectM0M1Pi(state, db, bust as never, undefined, true);
+
+			expect(changedDocsMarker).toBe(true);
+			expect(result.m0Materialized).toBe(false);
+			expect(textOf(bust[0] as never)).toBe(baselineM0);
+			expect(textOf(bust[1] as never)).toContain(
+				"Pi docs-hash-only CAS delta memory",
+			);
+		} finally {
+			db.exec = originalExec as typeof db.exec;
+			closeQuietly(db);
+		}
+	});
 });
 
 describe("renderM0Pi sibling-block layout (OpenCode parity)", () => {
@@ -1283,4 +1371,74 @@ describe("mustMaterializePi — SOFT/HARD taxonomy (parity with OpenCode)", () =
 			closeQuietly(db);
 		}
 	});
+
+	it("does NOT materialize m[0] on a project docs hash change", () => {
+		const db = createTestDb();
+		const cwd = mkdtempSync(join(tmpdir(), "pi-tax-docs-soft-"));
+		try {
+			const state = {
+				...piState("ses-pi-tax-docs-soft", cwd),
+				hardSignals: baseHard,
+			};
+			writeFileSync(join(cwd, "ARCHITECTURE.md"), "# Old Pi docs\n");
+			injectM0M1Pi(
+				state,
+				db,
+				[userMessage("hi", 10)] as never,
+				undefined,
+				true,
+			);
+
+			writeFileSync(join(cwd, "ARCHITECTURE.md"), "# New Pi docs\n");
+
+			expect(mustMaterializePi(state, db)).toEqual({
+				value: false,
+				reason: null,
+			});
+		} finally {
+			closeQuietly(db);
+		}
+	});
+
+	it("folds current project docs on the next natural HARD materialization", () => {
+		const db = createTestDb();
+		const cwd = mkdtempSync(join(tmpdir(), "pi-tax-docs-hard-"));
+		try {
+			const state = {
+				...piState("ses-pi-tax-docs-hard", cwd),
+				hardSignals: baseHard,
+			};
+			writeFileSync(join(cwd, "ARCHITECTURE.md"), "# Old Pi architecture\n");
+			const first = [userMessage("hi", 10)];
+			injectM0M1Pi(state, db, first as never, undefined, true);
+			expect(textOf(first[0] as never)).toContain("Old Pi architecture");
+
+			writeFileSync(
+				join(cwd, "ARCHITECTURE.md"),
+				"# Updated Pi architecture\nFresh Pi docs folded on hard bust.\n",
+			);
+			const changed = {
+				...state,
+				hardSignals: { ...baseHard, systemHash: "sys-v2" },
+			};
+			const second = [userMessage("hi again", 11)];
+			const result = injectM0M1Pi(
+				changed,
+				db,
+				second as never,
+				undefined,
+				true,
+			);
+
+			expect(result.m0Materialized).toBe(true);
+			expect(result.m0Reason).toBe("system_hash");
+			expect(textOf(second[0] as never)).toContain("Updated Pi architecture");
+			expect(textOf(second[0] as never)).toContain(
+				"Fresh Pi docs folded on hard bust.",
+			);
+			expect(textOf(second[0] as never)).not.toContain("Old Pi architecture");
+		} finally {
+			closeQuietly(db);
+		}
+	});
 });

packages/pi-plugin/src/inject-compartments-pi.ts

@@ -907,9 +907,6 @@ export function mustMaterializePi(
 	if (meta.cachedM0UpgradeState !== current.upgradeState) {
 		return { value: true, reason: "renderer_upgrade" };
 	}
-	if (current.projectDocsHash !== (meta.cachedM0ProjectDocsHash ?? "")) {
-		return { value: true, reason: "project_docs_change" };
-	}
 	if (
 		current.workspaceFingerprint !== null ||
 		(meta.cachedM0WorkspaceFingerprint ?? null) !== null
@@ -943,6 +940,9 @@ export function mustMaterializePi(
 	// maxMemoryId watermark, so they must not bust the m[0] cache. Memory
 	// mutations use cachedM0MaxMemoryMutationId as an m[1] reconcile cursor,
 	// not as a materialization trigger; keep it out of this trigger set.
+	// projectDocsHash is also NOT a trigger: docs-only edits ride along until a
+	// natural HARD fold, which reads fresh docs and persists the hash matching the
+	// bytes it rendered.
 	// session_facts is retired as a render source (facts = promoted memories),
 	// so its version is pinned to 0 and never triggers either.
 	return { value: false, reason: null };
@@ -1361,7 +1361,6 @@ export function materializeM0Pi(
 			current.maxCompartmentSeq !== snapshotMarkers.maxCompartmentSeq ||
 			current.maxMutationId !== snapshotMarkers.maxMutationId ||
 			current.maxMemoryMutationId !== snapshotMarkers.maxMemoryMutationId ||
-			current.projectDocsHash !== snapshotMarkers.projectDocsHash ||
 			// Inert today (both harnesses pin sessionFactsVersion to 0 — facts are
 			// retired in v2), but kept for structural parity with OpenCode
 			// materializeM0 so the two stale checks can't silently drift if either
@@ -1830,8 +1829,9 @@ function cachedPiRowMatchesSnapshot(args: {
 		rowMarkers.maxMemoryId === args.markers.maxMemoryId &&
 		rowMarkers.maxMutationId === args.markers.maxMutationId &&
 		rowMarkers.maxMemoryMutationId === args.markers.maxMemoryMutationId &&
-		(rowMarkers.projectDocsHash ?? "") ===
-			(args.markers.projectDocsHash ?? "") &&
+		// Project-docs hash is inert for CAS decisions: byte-different m[0] rows
+		// fail the buffer compare above, while hash-only drift with identical bytes
+		// must still refresh m[1] against the current cached prefix.
 		rowMarkers.materializedAt === args.markers.materializedAt &&
 		rowMarkers.sessionFactsVersion === args.markers.sessionFactsVersion &&
 		(rowMarkers.upgradeState ?? null) === (args.markers.upgradeState ?? null) &&

packages/plugin/scripts/analyze-cache-busts.ts

@@ -222,9 +222,22 @@ function cachedPrefixBytes(segs: Segment[], divergeIdx: number): { bytes: number
 }
 
 function fmtTime(iso: string): string {
-    // dumps are UTC; show HH:MM:SS UTC for direct correlation with meta.
-    const m = iso.match(/T(\d{2}:\d{2}:\d{2})/);
-    return m ? m[1] : iso;
+    // Dumps are UTC; the dashboard renders local time (UTC+2), so include the date
+    // here to keep multi-day dump sets unambiguous when correlating views.
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) return iso;
+    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(d.getUTCDate()).padStart(2, "0");
+    const hh = String(d.getUTCHours()).padStart(2, "0");
+    const mi = String(d.getUTCMinutes()).padStart(2, "0");
+    const ss = String(d.getUTCSeconds()).padStart(2, "0");
+    return `${mm}-${dd} ${hh}:${mi}:${ss} UTC`;
+}
+
+function lastBreakpointIndex(segs: Segment[]): number {
+    let last = -1;
+    for (let i = 0; i < segs.length; i += 1) if (segs[i].breakpoint) last = i;
+    return last;
 }
 
 function main(): void {
@@ -243,43 +256,42 @@ function main(): void {
     console.log(`Session: ${snaps[0].session}`);
     console.log(`Dumps:   ${snaps.length}  (dir: ${opts.dir})`);
     console.log("");
+    console.log("Dashboard times are local (UTC+2); table times are UTC.");
     console.log(
-        "time(UTC) | segs | verdict | first-divergence        | cachedPrefix@breakpoint",
+        "time(UTC)          | segs | verdict | first-divergence        | prevBytes → curBytes        | cachedPrefix@breakpoint",
     );
     console.log(
-        "----------|------|---------|-------------------------|------------------------",
+        "-------------------|------|---------|-------------------------|-----------------------------|------------------------",
     );
 
     for (let k = 0; k < snaps.length; k += 1) {
         const cur = snaps[k];
         if (k === 0) {
             console.log(
-                `${fmtTime(cur.createdAt)} | ${String(cur.segments.length).padStart(4)} | BASE    | (first request)         |`,
+                `${fmtTime(cur.createdAt)} | ${String(cur.segments.length).padStart(4)} | BASE    | (first request)         |                             |`,
             );
             continue;
         }
         const prev = snaps[k - 1];
         const idx = firstDivergence(prev.segments, cur.segments);
         if (idx === -1) {
             console.log(
-                `${fmtTime(cur.createdAt)} | ${String(cur.segments.length).padStart(4)} | SAME    | (identical to prev)     |`,
+                `${fmtTime(cur.createdAt)} | ${String(cur.segments.length).padStart(4)} | SAME    | (identical to prev)     |                             |`,
             );
             continue;
         }
         const seg = cur.segments[idx] ?? prev.segments[idx];
-        const lastBreakpointIdx = (() => {
-            let last = -1;
-            for (let i = 0; i < cur.segments.length; i += 1) if (cur.segments[i].breakpoint) last = i;
-            return last;
-        })();
-        // STABLE: divergence is only in the growing tail at/after the final
-        // breakpoint (expected — new turn appended). BUST: divergence lands
-        // before the final breakpoint, invalidating cached prefix it should keep.
-        const verdict = idx >= lastBreakpointIdx ? "STABLE" : "BUST";
+        // The reusable cache was written at PREV's breakpoints. OpenCode moves the
+        // tail breakpoint forward every request, so judging against CUR's final
+        // breakpoint mislabels ordinary tail growth as a bust.
+        const prevLastBreakpoint = lastBreakpointIndex(prev.segments);
+        const verdict = idx > prevLastBreakpoint ? "STABLE" : "BUST";
+        const prevPrefix = cachedPrefixBytes(prev.segments, prev.segments.length);
         const cp = cachedPrefixBytes(cur.segments, idx);
+        const byteDelta = `${prevPrefix.bytes.toLocaleString()}B → ${cp.bytes.toLocaleString()}B`;
         const segId = seg?.id ?? `seg[${idx}]`;
         console.log(
-            `${fmtTime(cur.createdAt)} | ${String(cur.segments.length).padStart(4)} | ${verdict.padEnd(7)} | ${segId.padEnd(23)} | ${cp.at} (${cp.bytes.toLocaleString()}B)`,
+            `${fmtTime(cur.createdAt)} | ${String(cur.segments.length).padStart(4)} | ${verdict.padEnd(7)} | ${segId.padEnd(23)} | ${byteDelta.padEnd(27)} | ${cp.at} (${cp.bytes.toLocaleString()}B)`,
         );
 
         if ((opts.showDiff || opts.allBusts) && verdict === "BUST") {