@llblab/pi-kit 0.18.2 → 0.19.0

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

@@ -1,19 +1,41 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { projectArtifactForModel, type ArtifactInvalidationNotice } from "./artifact.ts";
+import { projectArtifactForModel, type ArtifactInvalidationNotice, type ArtifactModelHints } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
-import { canonicalJson } from "./json.ts";
+import { isObject, presentationJson, type JsonValue } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import { projectStateForModel, type MaterializedState } from "./state.ts";
+import { projectStateForModel, type MaterializedState, type ModelState } 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[] {
+	let lastSystem = -1;
+	let current: string | undefined;
+	for (let index = 0; index < messages.length; index++) {
+		const message = messages[index]!;
+		if (message.role !== "system") continue;
+		lastSystem = index;
+		if (message.sections && Object.hasOwn(message.sections, "state_flow")) current = message.sections.state_flow ?? undefined;
+	}
+	const section = protocol === undefined ? undefined : `<state_flow>\n${protocol}\n</state_flow>`;
+	if (lastSystem < 0 || current === section) return messages;
+	return messages.map((message, index) => {
+		if (message.role !== "system") return message;
+		const ownsSection = message.sections !== undefined && Object.hasOwn(message.sections, "state_flow");
+		if (!ownsSection && (index !== lastSystem || section === undefined)) return message;
+		const sections = { ...message.sections };
+		delete sections.state_flow;
+		if (index === lastSystem && section !== undefined) sections.state_flow = section;
+		return { ...message, sections };
+	});
+}
 
-export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
 const LAZY_HINT_PATH = "effective.lazy";
 const LAZY_HINT_MAX_KEYS = 32;
 const LAZY_HINT_MAX_JSON_CHARS = 1024;
 
 type LazyValueKind = "array" | "boolean" | "null" | "number" | "object" | "string";
 
-function lazyValueKind(value: Exclude<MaterializedState["lazy"], undefined>): LazyValueKind {
+function lazyValueKind(value: JsonValue): LazyValueKind {
 	if (value === null) return "null";
 	if (Array.isArray(value)) return "array";
 	if (typeof value === "object") return "object";
@@ -22,9 +44,9 @@ function lazyValueKind(value: Exclude<MaterializedState["lazy"], undefined>): La
 
 /** Fixed-budget navigation only: never place lazy bodies or partial key catalogs in baseline context. */
 export function lazyNavigationHint(state: MaterializedState): { available: boolean; path: string; keys?: Record<string, LazyValueKind> } {
-	const base = { available: Object.hasOwn(state, "lazy"), path: LAZY_HINT_PATH };
-	if (!base.available || typeof state.lazy !== "object" || state.lazy === null || Array.isArray(state.lazy)) return base;
-	const entries = Object.entries(state.lazy);
+	const entries = isObject(state.lazy) ? Object.entries(state.lazy) : [];
+	const base = { available: entries.length > 0, path: LAZY_HINT_PATH };
+	if (!base.available) return base;
 	if (entries.length > LAZY_HINT_MAX_KEYS) return base;
 	const keys = Object.fromEntries(entries.map(([key, value]) => [key, lazyValueKind(value)]));
 	return JSON.stringify(keys).length <= LAZY_HINT_MAX_JSON_CHARS ? { ...base, keys } : base;
@@ -56,29 +78,25 @@ function messageText(message: AgentMessage): string {
 	return contentText((message as { content?: unknown }).content);
 }
 
-export function withoutPrivateValidation(messages: AgentMessage[]): AgentMessage[] {
-	return messages.filter((message) => {
-		return !(message.role === "custom" && message.customType === VALIDATION_MESSAGE_TYPE);
-	});
-}
-
-export function createPassiveContinuation(state: MaterializedState, startedAt = Date.now(), activeRunStartedAt?: number): PassiveContinuation {
+export function createPassiveContinuation(state: ModelState, startedAt = Date.now(), activeRunStartedAt?: number): PassiveContinuation {
 	return {
 		startedAt,
 		...(activeRunStartedAt === undefined ? {} : { activeRunStartedAt }),
-		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${canonicalJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
+		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${presentationJson({ state, continuation: "State Flow semantics are disabled; this handoff replaces completed history while retaining the active and post-stop trajectory." })}`),
 	};
 }
 
 /** Keep the interrupted run through later results; an idle stop retains only later conversation. */
 export function passiveContinuationMessages(messages: AgentMessage[], continuation: PassiveContinuation): AgentMessage[] {
-	let start = continuation.activeRunStartedAt === undefined ? -1
-		: messages.findIndex((message) => message.role === "user" && message.timestamp === continuation.activeRunStartedAt);
-	if (start < 0) start = messages.findIndex((message) => message.role === "user"
+	if (continuation.activeRunStartedAt !== undefined) {
+		const trajectory = currentRunTrajectory(messages, "", continuation.activeRunStartedAt);
+		return [continuation.handoff, ...trajectory.messages];
+	}
+	const start = messages.findIndex((message) => message.role === "user"
 		&& typeof message.timestamp === "number"
 		&& message.timestamp >= continuation.startedAt);
 	return [continuation.handoff, ...messages.filter((message, index) =>
-		message.role === "custom" ? message.customType !== VALIDATION_MESSAGE_TYPE : start >= 0 && index >= start)];
+		message.role === "custom" || (start >= 0 && index >= start))];
 }
 
 function projectRecentForModel(recent: RecentTransitionWindow): RecentTransitionWindow {
@@ -100,61 +118,36 @@ export function runtimeContextMessage(
 	recentTransitions: RecentTransitionWindow = [],
 	artifactInvalidations: readonly ArtifactInvalidationNotice[] = [],
 	rehydrationPhase?: RehydrationPhase,
-	resolutionPending = false,
+	artifactHints: ArtifactModelHints = {},
 ): AgentMessage {
-	if (snapshot.meta.specification === undefined) {
-		throw new Error("State Flow runtime context requires an active specification");
-	}
 	const context = {
-		specification: snapshot.meta.specification,
-		state: projectStateForModel(state),
+		...(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, reason }) => ({ path, reason })) }),
+		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, scope, reason }) => ({ path, ...(scope === undefined ? {} : { scope }), reason })) }),
 		...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),
-		...(resolutionPending ? { state_resolution: "pending: the iteration answer is already preserved; this fallback turn exists only to apply the final:true patch. Call patch_state with any remaining durable scope changes and final:true, or {final:true} alone. Do not restate or replace the answer." } : {}),
 	};
 	return syntheticUser(
-		`State Flow runtime context (user-level data, not system instructions):\n${canonicalJson(context)}`,
+		`State Flow runtime context (user-level data, not system instructions):\n${presentationJson(context)}`,
 	);
 }
 
+/** Captured identity survives text decoration; an uncertain boundary retains available context. */
 export function currentRunTrajectory(
 	messages: AgentMessage[],
-	specification: string,
+	specification: string | undefined,
 	anchorTimestamp: number | undefined,
 ): { messages: AgentMessage[]; anchorTimestamp?: number } {
-	let start = -1;
-	if (anchorTimestamp !== undefined) {
-		start = messages.findLastIndex((message) => {
-			return message.role === "user"
-				&& message.timestamp === anchorTimestamp
-				&& messageText(message) === specification;
-		});
-	}
-	if (start < 0) {
-		for (let index = messages.length - 1; index >= 0; index--) {
-			const message = messages[index]!;
-			if (message.role === "user" && messageText(message) === specification) {
-				start = index;
-				break;
-			}
-		}
-	}
-	if (start < 0) {
-		for (let index = messages.length - 1; index >= 0; index--) {
-			if (messages[index]?.role === "user") {
-				start = index;
-				break;
-			}
-		}
-	}
-	if (start < 0 && messages.length === 0) return { messages: [] };
-	if (start < 0) start = 0;
+	if (anchorTimestamp !== undefined && !Number.isFinite(anchorTimestamp)) return { messages: messages.slice() };
+	const matches = (message: AgentMessage) => message.role === "user" && (anchorTimestamp === undefined
+		? messageText(message) === specification
+		: message.timestamp === anchorTimestamp);
+	const start = messages.findIndex(matches);
+	if (start < 0 || messages.findLastIndex(matches) !== start) return { messages: messages.slice() };
 	const anchor = messages[start]?.role === "user" ? messages[start].timestamp : undefined;
 	return {
-		messages: messages.filter((message, index) => message.role === "custom"
-			? message.customType !== VALIDATION_MESSAGE_TYPE : index >= start),
+		messages: messages.filter((message, index) => message.role === "custom" || index >= start),
 		...(typeof anchor === "number" ? { anchorTimestamp: anchor } : {}),
 	};
 }

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

@@ -1,10 +1,9 @@
-import { execFileSync } from "node:child_process";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.ts";
-import { loadTemporalRevision } from "./git.ts";
+import { MAX_HISTORY_LIMIT } from "./history.ts";
 import { parseSessionRuntime } from "./snapshot.ts";
-import { validateTemporalState } from "./temporal.ts";
+import { validateScopeLineage } from "./temporal.ts";
 
 export type ContinuationTransport = "local" | "sdk" | "telegram" | string;
 
@@ -228,24 +227,16 @@ export function inspectStateFlowContinuationProvenance(
 		if (config === undefined && runtimeSource === undefined && meta === undefined) {
 			return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 		}
-		const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id, meta);
+		const runtime = parseSessionRuntime(config, runtimeSource, header.cwd, header.id);
 		if (!runtime) return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
 		if (!runtime.config.enabled) return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
-		if (runtime.meta.publication === "files") {
-			const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
-			const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
-			const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
-			if (!global || !cwd || !session) throw new Error("incomplete file-only temporal cohort");
-			validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
-			return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
-		}
-		const runtimePath = relative(resolve(repositoryRoot), runtimeSource === undefined ? paths.meta : paths.runtime);
-		if (runtimePath.startsWith("..")) throw new Error("runtime provenance escapes repository");
-		const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-		if (!owner) throw new Error("runtime owner commit is unavailable");
-		const restored = loadTemporalRevision(header.cwd, header.id, repositoryRoot, owner, sessionKey);
-		if (!restored.runtime || !restored.runtime.document.config.enabled) throw new Error("selected Git runtime is not enabled");
-		return { stateFlow: { enabled: true, restorable: true }, reason: `exact Git runtime ${owner.slice(0, 12)} is restorable` };
+		const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
+		const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
+		const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
+		if (!global || !cwd || !session) throw new Error("incomplete canonical temporal cohort");
+		// Shared streams are current, independently validated by their codecs, not frozen to this session's history.
+		validateScopeLineage(session, "session", runtime.meta.lineage, MAX_HISTORY_LIMIT);
+		return { stateFlow: { enabled: true, restorable: true }, reason: "canonical session lineage is valid beside current shared streams" };
 	} catch (error) {
 		return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
 	}

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

@@ -18,9 +18,10 @@ import {
 	serializeArtifactProvenanceRegistry,
 	type ArtifactProvenanceRegistry,
 } from "./artifact.ts";
+import { MAX_HISTORY_LIMIT } from "./history.ts";
 import { canonicalJson, isJsonValue, isObject } from "./json.ts";
 import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
-import { migratePreIntentState, type StateScope } from "./state.ts";
+import type { StateScope } from "./state.ts";
 
 const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const STATE_FILE = "state.json";
@@ -36,6 +37,18 @@ export interface ScopeStreamSources {
 	temporal: ScopeTemporalMetadata;
 }
 
+/** Read-only activation eligibility for one canonical CWD scope. */
+export function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean {
+	const root = resolve(repositoryRoot);
+	const directory = cwdScopePaths(cwd, root).directory;
+	const [checkpoint, patches, meta] = captureOwnedFileBases([
+		join(directory, CHECKPOINT_FILE), join(directory, PATCHES_FILE), join(directory, META_FILE),
+	], root);
+	if (checkpoint!.content !== undefined) return parseScopeStream(checkpoint!.content, patches!.content, "cwd", cwd, meta!.content) !== undefined;
+	if (patches!.content !== undefined) throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
+	return false;
+}
+
 export interface ScopeTemporalMetadata {
 	checkpoint: ScopeStream["checkpoint"]["through"];
 	patches: ScopeStream["patches"][number]["transition"][];
@@ -48,7 +61,7 @@ export interface SessionAddress {
 
 /** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
 export function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwdIdentity?: string): ScopeStreamSources {
-	validateScopeStream(stream, scope);
+	validateScopeStream(stream, scope, MAX_HISTORY_LIMIT);
 	if (scope === "cwd" && cwdIdentity === undefined) throw new Error("State Flow CWD scope serialization requires its canonical identity");
 	if (scope !== "cwd" && cwdIdentity !== undefined) throw new Error("Only State Flow CWD scope serialization accepts a CWD identity");
 	return {
@@ -73,6 +86,7 @@ export function classifyScopeStream(
 	expectedCwd?: string,
 	metaSource?: string,
 ): ScopeStreamPresence {
+	if (scope !== "global" && scope !== "cwd" && scope !== "session") throw new Error("Unknown temporal scope");
 	if (checkpointSource === undefined && patchesSource === undefined) return { kind: "absent" };
 	if (checkpointSource === undefined || patchesSource === undefined) {
 		throw new Error(`State Flow ${scope} scope has an incomplete checkpoint/tail pair`);
@@ -99,40 +113,21 @@ export function classifyScopeStream(
 		}
 	}
 	const temporal = meta?.temporal;
-	if (isObject(temporal) && Object.hasOwn(temporal, "checkpoint") && Array.isArray(temporal.patches)) {
-		checkpoint = migratePreIntentState(checkpoint) ?? checkpoint;
-		const owner = meta?.owner;
-		if (scope === "cwd" && expectedCwd !== undefined
-			&& (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
-			throw new Error(owner === undefined ? "State Flow CWD scope identity is missing" : "State Flow CWD scope identity mismatch");
-		}
-		const boundaries = temporal.patches;
-		if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
-		const stream = {
-			checkpoint: { through: temporal.checkpoint, state: checkpoint },
-			patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
-		};
-		validateScopeStream(stream, scope);
-		return { kind: "present", stream };
-	}
-	// Complete predecessor envelopes are the only no-meta form that may be unwrapped.
-	let legacyCheckpoint = checkpoint;
-	if (isObject(checkpoint) && Object.hasOwn(checkpoint, "owner")) {
-		const { owner, ...semantic } = checkpoint;
-		if (scope !== "cwd" || !isObject(owner) || Object.keys(owner).join(",") !== "cwd" || typeof owner.cwd !== "string") {
-			throw new Error("Invalid State Flow CWD scope identity");
-		}
-		if (expectedCwd !== undefined && owner.cwd !== resolve(expectedCwd)) throw new Error("State Flow CWD scope identity mismatch");
-		legacyCheckpoint = semantic;
-	} else if (scope === "cwd" && expectedCwd !== undefined) {
-		throw new Error("State Flow CWD scope identity is missing");
+	if (!isObject(temporal) || !Object.hasOwn(temporal, "checkpoint") || !Array.isArray(temporal.patches)) {
+		throw new Error(`Unsupported State Flow ${scope} storage format`);
 	}
-	if (isObject(legacyCheckpoint) && isObject(legacyCheckpoint.state)) {
-		const migrated = migratePreIntentState(legacyCheckpoint.state);
-		if (migrated) legacyCheckpoint = { ...legacyCheckpoint, state: migrated };
+	const owner = meta?.owner;
+	if (scope === "cwd" && expectedCwd !== undefined
+		&& (!isObject(owner) || Object.keys(owner).join(",") !== "cwd" || owner.cwd !== resolve(expectedCwd))) {
+		throw new Error(owner === undefined ? "State Flow CWD scope identity is missing" : "State Flow CWD scope identity mismatch");
 	}
-	const stream = { checkpoint: legacyCheckpoint, patches };
-	validateScopeStream(stream, scope);
+	const boundaries = temporal.patches;
+	if (boundaries.length !== patches.length) throw new Error(`State Flow ${scope} temporal metadata does not match its semantic tail`);
+	const stream = {
+		checkpoint: { through: temporal.checkpoint, state: checkpoint },
+		patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
+	};
+	validateScopeStream(stream, scope, MAX_HISTORY_LIMIT);
 	return { kind: "present", stream };
 }
 
@@ -174,17 +169,17 @@ export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRo
 export function loadScopeStream(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey = sessionId): ScopeStream | undefined {
 	const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 	if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
-		throw new Error(`Legacy State Flow storage requires explicit migration: ${paths.directory}`);
+		throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
 	}
 	return parseScopeStream(readRegularFile(paths.checkpoint, repositoryRoot), readRegularFile(paths.patches, repositoryRoot), scope, scope === "cwd" ? cwd : undefined, readRegularFile(paths.meta, repositoryRoot));
 }
 
-/** Include legacy names in the CAS basis solely to prevent format races during cutover. */
+/** Include unsupported predecessor names in the CAS basis so they cannot race canonical publication. */
 export function captureTemporalFileBases(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): DurableFileBase[] {
 	const paths = (["global", "cwd", "session"] as const).flatMap((scope) => {
 		const pair = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 		const runtime = scope === "session" ? sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey) : undefined;
-		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
+		return [pair.checkpoint, pair.patches, ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.runtime, runtime.meta])];
 	});
 	return captureOwnedFileBases(paths, repositoryRoot);
 }
@@ -198,26 +193,20 @@ export function temporalStateFileUpdates(
 	repositoryRoot: string,
 	sessionKey = sessionId,
 ): OwnedFileUpdate[] {
-	validateTemporalState(view);
+	validateTemporalState(view, MAX_HISTORY_LIMIT);
 	const seen = new Set<StateScope>();
 	return scopes.flatMap((scope) => {
 		if (seen.has(scope)) throw new Error(`Duplicate temporal scope update: ${scope}`);
 		seen.add(scope);
 		const paths = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 		if (readRegularBytes(join(paths.directory, STATE_FILE), repositoryRoot) !== undefined) {
-			throw new Error(`Legacy State Flow storage requires explicit migration: ${paths.directory}`);
+			throw new Error(`Unsupported State Flow storage format: ${paths.directory}`);
 		}
 		const sources = serializeScopeStream(view.scopes[scope], scope, scope === "cwd" ? cwd : undefined);
 		return [{ path: paths.checkpoint, content: sources.checkpoint }, { path: paths.patches, content: sources.patches }];
 	});
 }
 
-export interface DurablePaths {
-	repositoryRoot: string;
-	globalState: string;
-	globalPatches: string;
-}
-
 /** Merge authoritative owned leaves while preserving forward-compatible metadata siblings. */
 export function serializeScopeMetadata(
 	registry: Readonly<ArtifactProvenanceRegistry> | undefined, stream: ScopeStream, scope: StateScope,
@@ -225,7 +214,7 @@ export function serializeScopeMetadata(
 ): string {
 	const existing = parseMetadataDocument(existingSource, `State Flow metadata`);
 	if (scope === "session") {
-		for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap", "remotePublication", "revision", "temporalRevision", "publication"]) delete existing[key];
+		for (const key of ["identity", "lineage", "step", "specification", "validation", "bootstrap"]) delete existing[key];
 	}
 	const sources = serializeScopeStream(stream, scope, cwdIdentity);
 	const value = {
@@ -263,15 +252,13 @@ export function parseScopeProvenance(source: string | undefined, path: string):
 
 export interface ScopePaths {
 	directory: string;
-	state: string;
-	patches: string;
 }
 
 export interface DurableFileBase {
 	path: string;
 	identity: "missing" | `sha256:${string}`;
 	content?: string;
-	/** Opaque originals for byte-exact rollback, including non-UTF-8 legacy journals. */
+	/** Opaque originals for byte-exact rollback. */
 	bytes?: Uint8Array;
 }
 
@@ -280,16 +267,6 @@ export function getDurableRepositoryRoot(agentDir = getAgentDir()): string {
 	return resolve(agentDir, "state-flow");
 }
 
-/** Legacy snapshot paths retained only for one-way migration and exact ownership checks. */
-export function durablePaths(repositoryRoot = getDurableRepositoryRoot()): DurablePaths {
-	const root = resolve(repositoryRoot);
-	return {
-		repositoryRoot: root,
-		globalState: join(root, STATE_FILE),
-		globalPatches: join(root, PATCHES_FILE),
-	};
-}
-
 /** Match Pi's native project-session directory convention exactly. */
 export function cwdScopeKey(cwd: string): string {
 	const canonical = resolve(cwd);
@@ -319,8 +296,7 @@ export function resolveSessionAddress(sessionFile: string | undefined, sessionId
 }
 
 export function cwdScopePaths(cwd: string, repositoryRoot = getDurableRepositoryRoot()): ScopePaths {
-	const directory = join(resolve(repositoryRoot), cwdScopeKey(cwd));
-	return { directory, state: join(directory, STATE_FILE), patches: join(directory, PATCHES_FILE) };
+	return { directory: join(resolve(repositoryRoot), cwdScopeKey(cwd)) };
 }
 
 export function sessionScopePaths(
@@ -329,45 +305,27 @@ export function sessionScopePaths(
 	repositoryRoot = getDurableRepositoryRoot(),
 	sessionKey = sessionId,
 ): ScopePaths {
-	const directory = join(cwdScopePaths(cwd, repositoryRoot).directory, sessionScopeKey(sessionKey));
-	return { directory, state: join(directory, STATE_FILE), patches: join(directory, PATCHES_FILE) };
-}
-
-export function cwdStatePath(cwd: string, repositoryRoot = getDurableRepositoryRoot()): string {
-	return cwdScopePaths(cwd, repositoryRoot).state;
-}
-
-export function cwdPatchesPath(cwd: string, repositoryRoot = getDurableRepositoryRoot()): string {
-	return cwdScopePaths(cwd, repositoryRoot).patches;
-}
-
-export function sessionStatePath(cwd: string, sessionId: string, repositoryRoot = getDurableRepositoryRoot(), sessionKey = sessionId): string {
-	return sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).state;
-}
-
-export function sessionPatchesPath(cwd: string, sessionId: string, repositoryRoot = getDurableRepositoryRoot(), sessionKey = sessionId): string {
-	return sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).patches;
+	return { directory: join(cwdScopePaths(cwd, repositoryRoot).directory, sessionScopeKey(sessionKey)) };
 }
 
-/** Exact semantic file shapes, including legacy snapshots only during the storage cutover. */
+/** Exact canonical semantic and runtime file shapes. */
 export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDurableRepositoryRoot()): boolean {
 	const root = resolve(repositoryRoot);
 	const absolute = resolve(candidate);
-	const global = durablePaths(root);
-	if (absolute === global.globalState || absolute === global.globalPatches
-		|| absolute === join(root, CHECKPOINT_FILE) || absolute === join(root, META_FILE)) return true;
+	if (absolute === join(root, CHECKPOINT_FILE) || absolute === join(root, PATCHES_FILE)
+		|| absolute === join(root, META_FILE)) return true;
 	const segments = relative(root, absolute).split(sep);
 	const cwdKey = (value: string) => value.startsWith("--") && value.endsWith("--");
 	const sessionKey = (value: string) => {
 		try { return sessionScopeKey(value) === value; } catch { return false; }
 	};
 	if (segments.length === 2) {
-		return cwdKey(segments[0]!) && (segments[1] === STATE_FILE || segments[1] === CHECKPOINT_FILE || segments[1] === PATCHES_FILE || segments[1] === META_FILE);
+		return cwdKey(segments[0]!) && (segments[1] === CHECKPOINT_FILE || segments[1] === PATCHES_FILE || segments[1] === META_FILE);
 	}
 	if (segments.length === 3) {
 		return cwdKey(segments[0]!)
 			&& sessionKey(segments[1]!)
-			&& (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
+			&& (segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
 				|| segments[2] === "config.json" || segments[2] === RUNTIME_FILE || segments[2] === META_FILE);
 	}
 	return false;
@@ -457,7 +415,7 @@ function assertCurrentBytes(path: string, root: string, expected: Uint8Array | u
 	}
 }
 
-/** Capture exact owned bytes for one compare-and-swap publication or migration cohort. */
+/** Capture exact owned bytes for one compare-and-swap publication cohort. */
 export function captureOwnedFileBases(paths: readonly string[], repositoryRoot: string): DurableFileBase[] {
 	const root = resolve(repositoryRoot);
 	return paths.map((path) => {