@llblab/pi-kit 0.23.2 → 0.24.0

package/node_modules/@llblab/pi-state-flow/lib/context.ts

@@ -1,10 +1,11 @@
+import { randomUUID } from "node:crypto";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { projectArtifactForModel, type ArtifactInvalidationNotice, type ArtifactModelHints } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
-import { isObject, presentationJson, type JsonValue } from "./json.ts";
+import { applyPatch, isObject, presentationJson, sameJson, type JsonValue } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { projectStateForModel, type MaterializedState, type ModelState } from "./state.ts";
+import { projectStateForModel, type AtomicScopePatches, type MaterializedState, type ModelState, type StateScope } from "./state.ts";
 
 /** Refresh only our section; Pi owns system frames, tools and forced-prompt precedence. */
 export function projectSystemProtocol(messages: AgentMessage[], protocol: string | undefined): AgentMessage[] {
@@ -53,12 +54,222 @@ export function lazyNavigationHint(state: MaterializedState): { available: boole
 }
 
 
+export type ModelStateUpdate = { path: (string | number)[] } & ({ value: JsonValue } | { deleted: true });
+
+/** Exact projected replacements, not authored merge patches; paths are unambiguous key/index segments. */
+export function acceptedStateUpdates(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches) {
+	return projectedStateUpdates(projectStateForModel(before), projectStateForModel(after), patches, lazyNavigationHint(before), lazyNavigationHint(after));
+}
+
+function projectedStateUpdates(previous: ModelState, current: ModelState, patches: AtomicScopePatches,
+	beforeNavigation: ReturnType<typeof lazyNavigationHint> | undefined, navigation: ReturnType<typeof lazyNavigationHint> | undefined) {
+	const effective: ModelStateUpdate[] = [];
+	const prefix = (parent: readonly (string | number)[], child: readonly (string | number)[]) =>
+		parent.length <= child.length && parent.every((part, index) => part === child[index]);
+	const put = (path: (string | number)[], value: JsonValue | undefined) => {
+		if (effective.some((entry) => prefix(entry.path, path))) return;
+		for (let index = effective.length - 1; index >= 0; index--) {
+			if (prefix(path, effective[index]!.path)) effective.splice(index, 1);
+		}
+		effective.push({ path, ...(value === undefined ? { deleted: true as const } : { value: structuredClone(value) }) });
+	};
+	const child = (value: JsonValue | undefined, key: string | number): JsonValue | undefined =>
+		value !== null && typeof value === "object" && Object.hasOwn(value, key)
+			? (value as Record<string | number, JsonValue>)[key] : undefined;
+	const diff = (left: JsonValue | undefined, right: JsonValue | undefined, path: (string | number)[]) => {
+		if (left === undefined && right === undefined || left !== undefined && right !== undefined && sameJson(left, right)) return;
+		if (isObject(left) && isObject(right)) {
+			for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) diff(child(left, key), child(right, key), [...path, key]);
+		} else if (Array.isArray(left) && Array.isArray(right) && left.length === right.length) {
+			for (let index = 0; index < right.length; index++) diff(left[index], right[index], [...path, index]);
+		} else put(path, right);
+	};
+	const touched = (patch: JsonValue, value: JsonValue | undefined, path: (string | number)[]) => {
+		if (!isObject(patch)) { put(path, value); return; }
+		const keys = Object.keys(patch);
+		if (keys.length === 0) return;
+		if (Array.isArray(value) && keys.every((key) => /^\[(0|[1-9]\d*)\]$/.test(key))) {
+			for (const key of keys) {
+				const index = Number(key.slice(1, -1));
+				// A higher-scope array may mask the patched array with a different length.
+				if (index >= value.length) { put(path, value); return; }
+				touched(patch[key]!, value[index], [...path, index]);
+			}
+		} else if (isObject(value)) {
+			for (const key of keys) touched(patch[key]!, child(value, key), [...path, key]);
+		} else put(path, value);
+	};
+	diff(previous, current, []);
+	for (const patch of Object.values(patches)) for (const [plane, value] of Object.entries(patch)) {
+		if (plane === "lazy") continue;
+		if (plane === "artifacts" && isObject(value)) {
+			for (const path of Object.keys(value)) put([plane, path], child(current.artifacts, path));
+		} else touched(value as JsonValue, child(current, plane), [plane]);
+	}
+	return { effective, ...(navigation !== undefined && (beforeNavigation === undefined || !sameJson(beforeNavigation, navigation)) ? { lazy_navigation: navigation } : {}) };
+}
+
+export interface ContextView {
+	state: ModelState;
+	lazy_navigation?: ReturnType<typeof lazyNavigationHint>;
+	artifact_invalidations: readonly ArtifactInvalidationNotice[];
+	knowledge_rehydration: { phase: RehydrationPhase } | null;
+}
+
+export function contextView(state: MaterializedState, hints: ArtifactModelHints, invalidations: readonly ArtifactInvalidationNotice[], phase?: RehydrationPhase): ContextView {
+	return { state: projectStateForModel(state, hints), lazy_navigation: lazyNavigationHint(state),
+		artifact_invalidations: structuredClone(invalidations), knowledge_rehydration: phase === undefined ? null : { phase } };
+}
+
+/** Volatile model projection only. Native messages own trajectory; this cache owns no persistence or lifecycle. */
+export class ContextProjection {
+	private identity = randomUUID();
+	private head: AgentMessage | undefined;
+	private view: ContextView | undefined;
+	private native: string[] = [];
+	private notices: Array<{ after: number; message: AgentMessage }> = [];
+
+	reset(): void {
+		this.identity = randomUUID();
+		this.head = undefined;
+		this.view = undefined;
+		this.native = [];
+		this.notices = [];
+	}
+
+	/** Called only after successful publication and ancillary acceptance, immediately before returning the native result. */
+	acceptPatch(before: MaterializedState, after: MaterializedState, patches: AtomicScopePatches, hints: ArtifactModelHints) {
+		const state = projectStateForModel(after, hints);
+		const navigation = lazyNavigationHint(after);
+		const beforeNavigation = this.view?.lazy_navigation ?? lazyNavigationHint(before);
+		const updates = projectedStateUpdates(this.view?.state ?? projectStateForModel(before, hints), state, patches,
+			beforeNavigation, navigation);
+		// Suppress direct writes only when the accepted effective value matches.
+		// Overlap stays conservative except for explicit top-scope replacements:
+		// Session scalars/arrays mask every lower-scope value at that path.
+		const leaves: Array<{ scope: StateScope; path: (string | number)[]; value: JsonValue; artifact?: true }> = [];
+		const objects: typeof leaves = [];
+		const known = (path: readonly (string | number)[]): JsonValue | undefined => {
+			let value: JsonValue | undefined = this.view?.state;
+			for (const part of path) {
+				if (value === undefined || value === null || typeof value !== "object" || !Object.hasOwn(value, part)) return undefined;
+				value = (value as Record<string | number, JsonValue>)[part];
+			}
+			return value;
+		};
+		const visit = (scope: StateScope, value: JsonValue, path: (string | number)[]) => {
+			if (isObject(value) && Object.keys(value).length > 0) {
+				// Diff may coalesce a newly created/replaced object at this path.
+				// Keep its authored value without widening the overlap frontier.
+				objects.push({ scope, path, value });
+				const basis = known(path);
+				const entries = Object.entries(value);
+				const indexed = Array.isArray(basis) && entries.every(([key]) => {
+					if (!/^\[(0|[1-9]\d*)\]$/.test(key)) return false;
+					const index = Number(key.slice(1, -1));
+					return Number.isSafeInteger(index) && index < basis.length;
+				});
+				for (const [key, child] of entries) visit(scope, child,
+					[...path, indexed ? Number(key.slice(1, -1)) : key]);
+			} else leaves.push({ scope, path, value });
+		};
+		for (const scope of ["global", "cwd", "session"] as const) for (const [plane, value] of Object.entries(patches[scope] ?? {})) {
+			if (plane === "lazy") continue;
+			if (plane === "artifacts" && isObject(value)) {
+				for (const [path, card] of Object.entries(value)) leaves.push({ scope, path: ["artifacts", path], value: card, artifact: true });
+			} else visit(scope, value as JsonValue, [plane]);
+		}
+		const prefix = (a: readonly (string | number)[], b: readonly (string | number)[]) =>
+			a.length <= b.length && a.every((part, index) => part === b[index]);
+		updates.effective = updates.effective.filter((entry) => {
+			const matches = ({ path }: typeof leaves[number]) => path.length === entry.path.length && prefix(path, entry.path);
+			const authored = leaves.findLast(matches) ?? objects.findLast(matches);
+			if (!authored) return true;
+			const sessionReplacement = authored.scope === "session" && authored.value !== null && !isObject(authored.value);
+			if (!sessionReplacement && leaves.some(({ scope, path }) => scope !== authored.scope && (prefix(path, authored.path) || prefix(authored.path, path)))) return true;
+			if (authored.value !== null) {
+				if (authored.artifact) {
+					// Projected authored fields merge into the communicated card. Hints
+					// are not authored; keeping one is predictable, changing it is not.
+					const prior = known(entry.path);
+					const card = projectArtifactForModel(authored.value);
+					if (!isObject(card)) return true;
+					let expected: JsonValue = card;
+					if (isObject(prior)) {
+						try { expected = applyPatch(prior, card); }
+						catch {
+							// Canonical acceptance already succeeded. A masked effective
+							// array may reject an index valid in the authored scope.
+							return true;
+						}
+					}
+					return !("value" in entry && sameJson(entry.value, expected));
+				}
+				return !("value" in entry && sameJson(entry.value, authored.value));
+			}
+			// A deletion cannot predict a fallback from effective state alone. It
+			// needs no echo only when the communicated and accepted values coincide.
+			if (!this.view) return true;
+			const before = known(entry.path);
+			return "value" in entry ? before === undefined || !sameJson(before, entry.value) : before !== undefined;
+		});
+		// A complete communicated key/kind catalog can predict non-deleting
+		// top-level lazy writes. Missing/over-budget catalogs, deletions and
+		// overlapping scopes cannot prove the post-patch navigation summary.
+		if (updates.lazy_navigation && this.view && (beforeNavigation.keys || !beforeNavigation.available) && navigation.keys) {
+			const expected = new Map(Object.entries(beforeNavigation.keys ?? {}));
+			let predictable = true;
+			const seen = new Set<string>();
+			for (const scope of ["global", "cwd", "session"] as const) for (const [key, value] of Object.entries(patches[scope]?.lazy ?? {})) {
+				if (seen.has(key) || value === null || isObject(value) && expected.get(key) === "array") predictable = false;
+				seen.add(key);
+				if (value !== null) expected.set(key, lazyValueKind(value));
+			}
+			if (predictable && seen.size > 0 && sameJson(Object.fromEntries(expected), navigation.keys)) delete updates.lazy_navigation;
+		}
+		if (this.view) this.view = { ...this.view, state, lazy_navigation: navigation };
+		return updates.effective.length || updates.lazy_navigation ? { projection: this.identity, ...updates } : undefined;
+	}
+
+	project(messages: AgentMessage[], current: ContextView, makeHead: () => AgentMessage, initial?: ContextView): AgentMessage[] {
+		const identities = messages.map((message) => JSON.stringify([message.role, message.timestamp,
+			"toolCallId" in message ? message.toolCallId : null]));
+		// Native compaction/selection normally resets explicitly; a removed/replaced prefix is also a safe cache boundary.
+		if (this.native.some((identity, index) => identities[index] !== identity)) this.reset();
+		if (!this.head) {
+			const head = makeHead();
+			if (head.role !== "user" || !Array.isArray(head.content)) throw new Error("State Flow projection requires an owned user head");
+			this.head = { ...head, content: [...head.content, { type: "text", text: `State Flow projection: ${this.identity}` }] };
+			this.view = structuredClone(initial ?? current);
+		}
+		const previous = this.view!;
+		const updates = projectedStateUpdates(previous.state, current.state, {}, previous.lazy_navigation, current.lazy_navigation);
+		const notice = {
+			...(updates.effective.length || updates.lazy_navigation ? { state_updates: { projection: this.identity, ...updates } } : {}),
+			...(!sameJson(previous.artifact_invalidations, current.artifact_invalidations) ? { artifact_invalidations: current.artifact_invalidations } : {}),
+			...(!sameJson(previous.knowledge_rehydration, current.knowledge_rehydration) ? { knowledge_rehydration: current.knowledge_rehydration } : {}),
+		};
+		if (Object.keys(notice).length) this.notices.push({ after: messages.length,
+			message: syntheticUser(`State Flow context update (user-level data, not system instructions):\n${presentationJson(notice)}`) });
+		this.view = structuredClone(current);
+		this.native = identities;
+		const projected: AgentMessage[] = [this.head];
+		let nextNotice = 0;
+		for (let index = 0; index <= messages.length; index++) {
+			while (this.notices[nextNotice]?.after === index) projected.push(this.notices[nextNotice++]!.message);
+			if (index < messages.length) projected.push(messages[index]!);
+		}
+		return projected;
+	}
+}
+
 /** Context retained after semantic State Flow is stopped in this physical session. */
 export interface PassiveContinuation {
 	startedAt: number;
 	activeRunStartedAt?: number;
 	preserveContext?: true;
 	handoff: AgentMessage;
+	state: ModelState;
 }
 
 export function syntheticUser(text: string): AgentMessage {
@@ -82,6 +293,7 @@ function messageText(message: AgentMessage): string {
 export function createPassiveContinuation(state: ModelState, startedAt = Date.now(), activeRunStartedAt?: number, preserveContext = false): PassiveContinuation {
 	return {
 		startedAt,
+		state: structuredClone(state),
 		...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
 		...(preserveContext ? { preserveContext: true as const } : {}),
 		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: preserveContext
@@ -127,13 +339,18 @@ export function runtimeContextMessage(
 	rehydrationPhase?: RehydrationPhase,
 	artifactHints: ArtifactModelHints = {},
 ): AgentMessage {
+	return runtimeContextHead(snapshot, contextView(state, artifactHints, artifactInvalidations, rehydrationPhase), recentTransitions);
+}
+
+/** Render a view already projected by this domain without cloning the full semantic overlay twice. */
+export function runtimeContextHead(snapshot: Snapshot, view: ContextView, recentTransitions: RecentTransitionWindow = []): AgentMessage {
 	const recent = projectRecentForModel(recentTransitions);
 	const context = {
 		...(snapshot.meta.specification === undefined ? {} : { specification: snapshot.meta.specification }),
-		state: projectStateForModel(state, artifactHints),
-		lazy_navigation: lazyNavigationHint(state),
-		...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
-		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason })) }),
+		state: view.state,
+		...(view.lazy_navigation === undefined ? {} : { lazy_navigation: view.lazy_navigation }),
+		...(view.knowledge_rehydration === null ? {} : { knowledge_rehydration: view.knowledge_rehydration }),
+		...(view.artifact_invalidations.length === 0 ? {} : { artifact_invalidations: view.artifact_invalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason })) }),
 		...(recent.length === 0 ? {} : { recent_transitions: recent }),
 	};
 	return syntheticUser(

package/node_modules/@llblab/pi-state-flow/lib/extension.ts

@@ -16,7 +16,7 @@ import {
 } from "./artifact.ts";
 import { hasCompactionSizedTranscript, planStateFlowCompaction, shouldRequestStateFlowCompaction, stateFlowCompactionResult, type StateFlowCompactionPlan } from "./compaction.ts";
 import { loadStateFlowConfig } from "./config.ts";
-import { createPassiveContinuation, currentRunTrajectory, lazyNavigationHint, passiveContinuationMessages, projectSystemProtocol, runtimeContextMessage, syntheticUser, type PassiveContinuation } from "./context.ts";
+import { ContextProjection, contextView, createPassiveContinuation, currentRunTrajectory, passiveContinuationMessages, projectSystemProtocol, runtimeContextHead, syntheticUser, type PassiveContinuation } from "./context.ts";
 import { readNativeSessionHeader } from "./continuation.ts";
 import {
   cwdScopeKey,
@@ -109,6 +109,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	const compactionMarker = `state-flow-boundary:${randomUUID()}`;
 	let passiveContinuation: PassiveContinuation | undefined;
 	let bootstrapContinuation: PassiveContinuation | undefined;
+	const contextProjection = new ContextProjection();
 	let inferencePreparation: InferencePreparation | undefined;
 	let runAnchorTimestamp: number | undefined;
 	let runtime: TemporalRuntime | undefined;
@@ -459,6 +460,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	/** Select the active native branch under one owned restoration lifetime; only current accepted work installs memory. */
 	function restoreActiveBranch(ctx: ExtensionContext, sessionStartReason?: unknown, notifyRecovery = true, startOwner?: AbortController): Promise<void> {
+		contextProjection.reset();
 		cancelBranchRestoration();
 		// Start-owned attachment/fork recovery keeps its owner; only accepted Start cancels Stop.
 		if (!startOwner) {
@@ -771,6 +773,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				const selected = runtime ??= createRuntime(ctx);
 				const acquiredArtifacts = structuredClone([...artifactReads.successful.values()]);
 				const acquiredSkills = structuredClone([...skillReads.successful.values()]);
+				const previousEffective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
 				return await selected.withPatchTransaction((transaction) => {
 					if (runtime !== selected) throw new Error("State Flow session selection changed while awaiting publication");
 					if (!passiveToolsAvailable()) throw new Error("State Flow tools are disabled by configuration");
@@ -800,9 +803,14 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 					}
 					clearAcceptedAcquisitions(new Set(acquiredArtifacts.map(({ path }) => path)));
 					updateUi(ctx);
-					return { content: [{ type: "text" as const, text: changed
+					const updates = contextProjection.acceptPatch(previousEffective, overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session), patches, artifactHints);
+					const acknowledgement = changed
 						? `\nState materialized atomically at ${scopes.join("+")} scope${scopes.length === 1 ? "" : "s"}.`
-						: "\nState already current." }], details: { scopes, step: snapshot.meta.step, changed } };
+						: "\nState already current.";
+					return { content: [
+						{ type: "text" as const, text: acknowledgement },
+						...(updates ? [{ type: "text" as const, text: `\n${presentationJson({ state_updates: updates })}` }] : []),
+					], details: { scopes, step: snapshot.meta.step, changed } };
 				}, signal);
 			} catch (error) {
 				let attempted: unknown;
@@ -908,6 +916,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				stopPersistenceError = undefined;
 				installScopeStates();
 				clearRunTransient();
+				contextProjection.reset();
 				passiveContinuation = undefined;
 				bootstrapContinuation = snapshot.meta.bootstrap ? continuation : undefined;
 				deferInferencePreparation();
@@ -993,6 +1002,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			&& !shuttingDown && ctx.sessionManager.getSessionId() === owner && !snapshot.config.enabled;
 		const superseded = (): StateFlowTelegramControlResult => ({ ok: false, message: "State Flow Stop was superseded" });
 		const freezeHandoff = (): PassiveContinuation | undefined => {
+			contextProjection.reset();
 			const handoff = (current.config.enabled || stopPersistenceError) && selected?.view && current.meta.validation?.attempt !== 0
 				? createPassiveContinuation(
 					projectModelState(overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session)),
@@ -1112,6 +1122,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 			(event.systemPromptOptions.sections ??= {}).state_flow = PASSIVE_MEMORY_PROTOCOL;
 			return;
 		}
+		contextProjection.reset();
 		skillReads.clear();
 		artifactReads.clear();
 		cancelResponseReconciliation();
@@ -1129,40 +1140,30 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 
 	function projectContext(messages: AgentMessage[]) {
 		if (runtime?.view) refreshArtifactHints();
+		if (!snapshot.config.enabled && !passiveContinuation && (!config.passiveBootstrap || !runtime?.view)) return;
+		// Idle inspection must not freeze a pre-acceptance snapshot for the live inference.
+		const projection = snapshot.config.enabled && inferencePreparation && !inferencePreparation.accepted
+			? new ContextProjection() : contextProjection;
+		const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
+		const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
+		const phase = snapshot.config.enabled ? currentRehydrationPhase() : undefined;
+		const view = contextView(effective, artifactHints, invalidations, phase);
 		if (passiveContinuation) {
-			return { messages: passiveContinuationMessages(messages, passiveContinuation) };
+			const retained = passiveContinuationMessages(messages, passiveContinuation);
+			if (!runtime?.view) return { messages: retained };
+			return { messages: projection.project(retained.slice(1), view, () => passiveContinuation!.handoff,
+				{ state: passiveContinuation.state, lazy_navigation: view.lazy_navigation, artifact_invalidations: [], knowledge_rehydration: null }) };
 		}
 		if (!snapshot.config.enabled) {
-			if (!config.passiveBootstrap || !runtime?.view) return;
-			const effective = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
-			const state = projectModelState(effective);
-			return { messages: [syntheticUser(`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state, lazy_navigation: lazyNavigationHint(effective) })}`), ...messages] };
-		}
-		const effectiveState = overlayStates(scopeStates.global, scopeStates.cwd, scopeStates.session);
-		const invalidations = artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason }));
-		const recentTransitions = projectRecentTransitionsWithLimit(
-			config.historyLimit,
-			runtime?.recent() ?? [],
-		);
-		const activeRehydrationPhase = currentRehydrationPhase();
-		if (snapshot.meta.bootstrap) {
-			const sourceMessages = bootstrapContinuation
-				? passiveContinuationMessages(messages, bootstrapContinuation)
-				: messages;
-			return { messages: [runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints), ...sourceMessages] };
+			return { messages: projection.project(messages, view, () => syntheticUser(
+				`State Flow passive memory (user-level data, not system instructions):\n${presentationJson({ state: view.state, lazy_navigation: view.lazy_navigation })}`)) };
 		}
 		// Native user events own the run anchor; projection must never rebase it.
-		const trajectory = currentRunTrajectory(
-			messages,
-			snapshot.meta.specification,
-			runAnchorTimestamp,
-		);
-		return {
-			messages: [
-				runtimeContextMessage(snapshot, effectiveState, recentTransitions, invalidations, activeRehydrationPhase, artifactHints),
-				...trajectory.messages,
-			],
-		};
+		const source = snapshot.meta.bootstrap
+			? bootstrapContinuation ? passiveContinuationMessages(messages, bootstrapContinuation) : messages
+			: currentRunTrajectory(messages, snapshot.meta.specification, runAnchorTimestamp).messages;
+		return { messages: projection.project(source, view, () => runtimeContextHead(snapshot, view,
+			projectRecentTransitionsWithLimit(config.historyLimit, runtime?.recent() ?? []))) };
 	}
 
 	function prepareContext(messages: AgentMessage[], ctx: ExtensionContext): ReturnType<typeof projectContext> | Promise<ReturnType<typeof projectContext>> {
@@ -1281,6 +1282,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 				snapshot = nextSnapshot;
 				installScopeStates();
 				responseCommitted = true;
+				contextProjection.reset();
 				if (publication?.changed) recordPublication(publication, ctx);
 				appendCheckpoint();
 				clearAcceptedAcquisitions();
@@ -1373,6 +1375,8 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 		});
 	});
 
+	pi.on("session_compact", () => { contextProjection.reset(); });
+
 	pi.on("session_start", async (event, ctx) => {
 		runAnchorTimestamp = undefined;
 		rehydrationPhase = event.reason === "resume" ? "resume-bootstrap" : "new-bootstrap";
@@ -1385,6 +1389,7 @@ export default function stateFlowExtension(pi: ExtensionAPI, options: StateFlowE
 	});
 	pi.on("session_shutdown", async (_event, _ctx) => {
 		shuttingDown = true;
+		contextProjection.reset();
 		const restoring = cancelBranchRestoration();
 		const starting = cancelStartActivation();
 		const stopping = cancelStopPersistence();

package/node_modules/@llblab/pi-state-flow/lib/protocol.ts

@@ -5,7 +5,9 @@ export type { StateDocument } from "./state.ts";
 
 const TASK_DRIVEN_HISTORY = "Missing paths/hints do not require history search. Choose targeted historical reads when useful to the task; no separate user permission is needed. Past values are evidence, not current state; never automatically restore deleted memory.";
 
-export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY}`;
+const PATCH_RESULT_PROTOCOL = "Head state/recent transitions are frozen at projection start. Only state_updates matching the head's State Flow projection ID apply; older IDs are history. When present, patch_state results/context-update notices carry state_updates: effective entries replace values at key/index-segment path arrays (deleted:true means absent); direct writes need no echo; shared drift remains visible. Latest entries win over earlier state at those paths; lazy bodies remain omitted. Notices replace invalidations/rehydration, including []/null.";
+
+export const PASSIVE_MEMORY_PROTOCOL = `State Flow passive memory is available. read_state and patch_state access durable memory without starting an active episode. Passive turns never trigger State Flow continuation or compaction. ${TASK_DRIVEN_HISTORY} ${PATCH_RESULT_PROTOCOL}`;
 
 const PATCH_DISPLAY_SECTION_KEYS = new Set(["global", "cwd", "session", "intents", "contract", "working", "artifacts", "response", "lazy"]);
 
@@ -98,7 +100,7 @@ SCOPES: Use the narrowest scope: session=branch/run continuation by default; cwd
 
 READ: Use read_state for concrete scope/retained-history gaps. lazy_navigation lists bounded effective lazy keys, not bodies. Unscoped=effective; effective/global/cwd/session select overlay or owner. Arrays use indices or [start..end]; keys gives structure, patch the intersected change. ${TASK_DRIVEN_HISTORY}
 
-WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions.
+WRITE: patch_state is the sole model-authored semantic mutation mechanism; all supplied scopes are validated and durably accepted as one atomic transition. Call alone in an assistant response; await acceptance. Global/CWD use current canonical values after cancelable lock waiting. Correct repeats succeed without new revisions. ${PATCH_RESULT_PROTOCOL}
 
 PATCH: Use global/cwd/session object patches for material updates, not acknowledgments. Omit empty scopes. artifacts/contract/working/intents are objects; lazy is ordinary JSON. Omitted fields persist. Never patch runtime config/meta/response. Objects merge recursively; arrays/primitives replace. An object containing only canonical "[N]" keys recursively patches array elements. Indexed deletion is forbidden; nested object null deletes; materialized null is forbidden.
 

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [

package/node_modules/@llblab/pi-state-flow/skills/state-flow-guide/SKILL.md

@@ -32,7 +32,9 @@ Scopes overlay `global → cwd → session`: cross-project, project, branch/run.
 
 ## Read
 
-Reuse sufficient visible state. `read_state` accepts `path` or `paths`, never both. Multi-path reads succeed or fail together. Projections: `value` (default), `keys` (structure), `patch` (intersecting change at the selected boundary).
+Reuse sufficient visible state. The memory head and its recent transitions are frozen at projection start. Apply later `state_updates` only when their `projection` matches the head's `State Flow projection:` ID; older native results remain historical. Effective update paths are key/index arrays whose values replace that path, while `deleted: true` means absence. Current notices can replace invalidation lists or rehydration phase, including clearing them with `[]` or `null`; lazy bodies still require explicit reads.
+
+`read_state` accepts `path` or `paths`, never both. Multi-path reads succeed or fail together. Projections: `value` (default), `keys` (structure), `patch` (intersecting change at the selected boundary).
 
 Example arguments:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "@llblab/pi-clean-room": "0.2.0",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.2",
-    "@llblab/pi-state-flow": "0.19.1",
+    "@llblab/pi-state-flow": "0.21.0",
     "@llblab/pi-telegram": "0.51.4",
     "@llblab/skills": "1.15.0"
   },