@llblab/pi-kit 0.13.0 → 0.14.1

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

@@ -7,17 +7,11 @@ import { spawn, spawnSync } from "node:child_process";
 import {
 	assertOwnedFileUpdates,
 	captureOwnedFileBases,
-	captureLegacyTemporalFileBases,
 	captureTemporalFileBases,
 	cwdScopePaths,
-	legacySessionRuntimePaths,
-	legacyTemporalScopePaths,
-	durablePaths,
 	isStateFlowOwnedPath,
 	parseScopeProvenance,
 	parseScopeStream,
-	parseStateSource,
-	serializeScopeStream,
 	restoreDurableFileBases,
 	temporalScopePaths,
 	sessionScopePaths,
@@ -28,7 +22,7 @@ import {
 } from "./durable.ts";
 import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { planLegacyStorageMigration } from "./migration.ts";
-import { sameJson } from "./json.ts";
+import { canonicalJson, sameJson } from "./json.ts";
 import { validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
 import { createSessionRuntime, parseSessionRuntime, serializeSessionRuntime, type SessionRuntime, type Snapshot } from "./snapshot.ts";
 import { assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.ts";
@@ -206,8 +200,6 @@ export interface TemporalRevisionLoad {
 	runtime?: { document: SessionRuntime; revision: string };
 	/** Runtime-owned artifact provenance retained at this revision. */
 	provenance: Record<StateScope, ArtifactProvenanceRegistry>;
-	/** True only when this revision directly selected pre-0.4 hashed paths. */
-	legacyLayout?: true;
 }
 
 export function captureTemporalGitBase(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): TemporalGitBase {
@@ -223,64 +215,57 @@ function revisionScopeFiles(read: (path: string) => DurableFileBase, paths: Retu
 		paths,
 		checkpoint: read(paths.checkpoint),
 		patches: read(paths.patches),
-		legacy: read(resolve(paths.directory, "state.json")),
 		meta: read(paths.meta),
 	};
 }
 
-/** Cold scope-stream reconstruction; pre-0.4 hashed paths remain read-only revision input. */
+/** Cold scope-stream reconstruction from canonical revision paths only. */
 export function loadTemporalRevision(cwd: string, sessionId: string, repositoryRoot: string, revision: string, sessionKey = sessionId): TemporalRevisionLoad {
 	const root = assertRepositoryRoot(repositoryRoot);
 	assertReadableRevision(root, revision);
 	const scopePaths = (["global", "cwd", "session"] as const).map((scope) => ({
-		scope,
-		canonical: temporalScopePaths(cwd, sessionId, scope, root, sessionKey),
-		legacy: scope === "global" ? undefined : legacyTemporalScopePaths(cwd, sessionId, scope, root),
+		scope, paths: temporalScopePaths(cwd, sessionId, scope, root, sessionKey),
 	}));
 	const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-	const legacyRuntime = legacySessionRuntimePaths(cwd, sessionId, root);
 	const readFile = revisionFileReader(root, revision, [
-		...scopePaths.flatMap(({ canonical, legacy }) => legacy ? [canonical, legacy] : [canonical])
-			.flatMap((paths) => [paths.checkpoint, paths.patches, resolve(paths.directory, "state.json"), paths.meta]),
-		canonicalRuntime.config, canonicalRuntime.meta, legacyRuntime.config, legacyRuntime.meta,
+		...scopePaths.flatMap(({ paths }) => [paths.checkpoint, paths.patches, paths.meta]),
+		canonicalRuntime.config, canonicalRuntime.meta,
 	]);
 	const files: DurableFileBase[] = [];
 	const scopes = {} as Record<StateScope, ScopeStream | undefined>;
 	const provenance: Record<StateScope, ArtifactProvenanceRegistry> = { global: {}, cwd: {}, session: {} };
-	let legacyLayout = false;
-	for (const { scope, canonical, legacy } of scopePaths) {
-		let selected = { ...revisionScopeFiles(readFile, canonical), legacyLayout: false };
-		if (legacy && [selected.checkpoint, selected.patches, selected.legacy].every(({ identity }) => identity === "missing")) {
-			selected = { ...revisionScopeFiles(readFile, legacy), legacyLayout: true };
-		}
-		if (selected.legacy.identity !== "missing") throw new Error("Historical legacy storage requires explicit migration interpretation");
-		legacyLayout ||= selected.legacyLayout;
-		files.push(selected.checkpoint, selected.patches, selected.legacy, ...(scope === "session" ? [] : [selected.meta]));
+	for (const { scope, paths } of scopePaths) {
+		const selected = revisionScopeFiles(readFile, paths);
+		files.push(selected.checkpoint, selected.patches, ...(scope === "session" ? [] : [selected.meta]));
 		if (scope !== "session") provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
-		scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope,
-			scope === "cwd" && !selected.legacyLayout ? cwd : undefined);
+		try {
+			scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope,
+				scope === "cwd" ? cwd : undefined, selected.meta.content);
+		} catch (error) {
+			throw new Error(`Invalid historical State Flow ${scope} scope`, { cause: error });
+		}
 	}
 	const readRuntime = (paths: ReturnType<typeof sessionRuntimePaths>) => ({
 		paths, config: readFile(paths.config), meta: readFile(paths.meta),
 	});
-	let selectedRuntime = { ...readRuntime(canonicalRuntime), legacyLayout: false };
-	if (selectedRuntime.config.identity === "missing" && selectedRuntime.meta.identity === "missing") {
-		selectedRuntime = { ...readRuntime(legacyRuntime), legacyLayout: true };
-	}
-	legacyLayout ||= selectedRuntime.legacyLayout;
-	const { paths: runtimePaths, config, meta } = selectedRuntime;
+	const { paths: runtimePaths, config, meta } = readRuntime(canonicalRuntime);
 	files.push(config, meta);
 	const document = parseSessionRuntime(config.content, meta.content, cwd, sessionId);
-	if (document === undefined) return { base: { head: revision, files }, scopes, provenance, ...(legacyLayout ? { legacyLayout: true as const } : {}) };
+	if (document === undefined) return { base: { head: revision, files }, scopes, provenance };
 	provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
 	const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
 		relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimePaths.meta, root),
 	]).stdout.trim();
 	assertReadableRevision(root, owner);
-	const temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
+	let temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
 		? owner : document.meta.temporalRevision;
 	if (temporalRevision !== revision) {
-		if (git(root, ["merge-base", "--is-ancestor", temporalRevision, revision], { allowFailure: true }).status !== 0) {
+		const ancestor = git(root, ["merge-base", "--is-ancestor", temporalRevision, revision], { allowFailure: true }).status === 0;
+		const parents = git(root, ["rev-list", "--parents", "-n", "1", revision]).stdout.trim().split(/\s+/);
+		// A store-wide semantic migration intentionally replaces all prior history with one root.
+		// Its complete tree owns every scope, so predecessor temporal pointers collapse to self.
+		if (!ancestor && parents.length === 1) temporalRevision = owner;
+		else if (!ancestor) {
 			throw new Error("Temporal revision must be an ancestor of its runtime owner");
 		}
 		const selected = loadTemporalRevision(cwd, sessionId, root, temporalRevision, sessionKey);
@@ -291,151 +276,7 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 		throw new Error("Session runtime has incomplete temporal scope storage");
 	}
 	validateTemporalState({ lineage: document.meta.lineage, scopes: { global: scopes.global, cwd: scopes.cwd, session: scopes.session } });
-	return { base: { head: revision, files }, scopes, runtime: { document, revision: owner }, provenance, ...(legacyLayout ? { legacyLayout: true as const } : {}) };
-}
-
-/** Legacy state.json is already current; explanatory journals are irrelevant to semantic recovery. */
-export function loadLegacyStatesAtRevision(cwd: string, sessionId: string, repositoryRoot: string, revision: string, sessionKey = sessionId): Record<StateScope, MaterializedState | undefined> {
-	const root = assertRepositoryRoot(repositoryRoot);
-	assertReadableRevision(root, revision);
-	const canonical = {
-		global: durablePaths(root).globalState,
-		cwd: cwdScopePaths(cwd, root).state,
-		session: sessionScopePaths(cwd, sessionId, root, sessionKey).state,
-	};
-	const states = {} as Record<StateScope, MaterializedState | undefined>;
-	for (const scope of ["global", "cwd", "session"] as const) {
-		let path = canonical[scope];
-		let source = revisionFile(root, revision, path).content;
-		if (source === undefined && scope !== "global") {
-			path = resolve(legacyTemporalScopePaths(cwd, sessionId, scope, root).directory, "state.json");
-			source = revisionFile(root, revision, path).content;
-		}
-		states[scope] = parseStateSource(source, path);
-	}
-	return states;
-}
-
-/** Move a current-head draft CWD pair before a new native-named session is initialized. */
-export function migrateHashedCwdAtHead(cwd: string, repositoryRoot: string): void {
-	withPublicationLock(repositoryRoot, (root) => {
-		const head = currentHead(root);
-		if (!head) return;
-		const old = legacyTemporalScopePaths(cwd, "unused", "cwd", root);
-		const target = temporalScopePaths(cwd, "unused", "cwd", root);
-		const paths = [old.checkpoint, old.patches, resolve(old.directory, "state.json"), target.checkpoint, target.patches, resolve(target.directory, "state.json")];
-		const captured = captureOwnedFileBases(paths, root);
-		const byPath = new Map(captured.map((file) => [file.path, file]));
-		const oldCheckpoint = byPath.get(old.checkpoint)!;
-		const oldPatches = byPath.get(old.patches)!;
-		const oldState = byPath.get(resolve(old.directory, "state.json"))!;
-		const targetFiles = [byPath.get(target.checkpoint)!, byPath.get(target.patches)!, byPath.get(resolve(target.directory, "state.json"))!];
-		if (targetFiles[2]!.identity !== "missing") return; // Canonical current-state format migrates in the next owner.
-		if (targetFiles[0]!.identity !== "missing" || targetFiles[1]!.identity !== "missing") {
-			parseScopeStream(targetFiles[0]!.content, targetFiles[1]!.content, "cwd", cwd);
-			return;
-		}
-		if (oldCheckpoint.identity === "missing" && oldPatches.identity === "missing" && oldState.identity === "missing") return;
-		if (oldState.identity !== "missing") throw new Error("Hashed current-state storage requires explicit format migration before path migration");
-		const oldStream = parseScopeStream(oldCheckpoint.content, oldPatches.content, "cwd")!;
-		for (const file of [oldCheckpoint, oldPatches]) {
-			if (revisionFile(root, head, file.path).identity !== file.identity) throw new Error(`Hashed CWD source is not anchored at current HEAD: ${file.path}`);
-		}
-		const source = serializeScopeStream(oldStream, "cwd", cwd);
-		const updates = [
-			{ path: target.checkpoint, content: source.checkpoint }, { path: target.patches, content: source.patches },
-			{ path: old.checkpoint }, { path: old.patches },
-		];
-		try {
-			publishOwnedCohort(root, updates, captured, head, [], "migrate");
-		} catch (error) {
-			try { rmdirSync(target.directory); } catch { /* Preserve nonempty or concurrently used directories. */ }
-			throw error;
-		}
-		try { rmdirSync(old.directory); } catch { /* Draft sessions may remain under this directory. */ }
-	});
-}
-
-/** Move only the selected current-head draft layout; older branch layouts remain cold read input. */
-export function migrateHashedLayoutAtHead(
-	cwd: string,
-	sessionId: string,
-	repositoryRoot: string,
-	revision: string,
-	sessionKey: string,
-): (ReturnType<typeof publishOwnedCohort> & { base: TemporalGitBase; view: TemporalState }) | undefined {
-	return withPublicationLock(repositoryRoot, (root) => {
-		if (currentHead(root) !== revision) return undefined;
-		const selected = loadTemporalRevision(cwd, sessionId, root, revision, sessionKey);
-		if (!selected.legacyLayout || !selected.runtime || !selected.scopes.global || !selected.scopes.cwd || !selected.scopes.session) return undefined;
-		const view = { lineage: selected.runtime.document.meta.lineage, scopes: {
-			global: selected.scopes.global, cwd: selected.scopes.cwd, session: selected.scopes.session,
-		} };
-		validateTemporalState(view);
-		const canonical = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
-		const legacyLive = captureLegacyTemporalFileBases(cwd, sessionId, root);
-		const bases = new Map([...canonical.files, ...legacyLive].map((file) => [file.path, file]));
-		const selectedFiles = new Map(selected.base.files.map((file) => [file.path, file]));
-		const updates: OwnedFileUpdate[] = [];
-		const cleanupDirectories = new Set<string>();
-		const targetDirectories = new Set<string>();
-		const removeEmptyDirectories = (directories: ReadonlySet<string>): void => {
-			for (const directory of [...directories].sort((left, right) => right.length - left.length)) {
-				try { rmdirSync(directory); } catch { /* Preserve nonempty or concurrently used directories. */ }
-			}
-		};
-		const move = (sourcePath: string, targetPath: string, content?: string): void => {
-			const source = selectedFiles.get(sourcePath);
-			if (!source || source.identity === "missing" || source.content === undefined) throw new Error(`Hashed-layout migration source is unavailable: ${sourcePath}`);
-			if (bases.get(sourcePath)?.identity !== source.identity) throw new Error(`Hashed-layout source changed after selected revision: ${sourcePath}`);
-			if (bases.get(targetPath)?.identity !== "missing") throw new Error(`Canonical State Flow path already exists during hashed-layout migration: ${targetPath}`);
-			updates.push({ path: targetPath, content: content ?? source.content }, { path: sourcePath });
-			cleanupDirectories.add(dirname(sourcePath));
-			targetDirectories.add(dirname(targetPath));
-		};
-		for (const scope of ["cwd", "session"] as const) {
-			const old = legacyTemporalScopePaths(cwd, sessionId, scope, root);
-			const target = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
-			if (selectedFiles.get(old.checkpoint)?.identity !== "missing") {
-				if (scope === "cwd") {
-					const stream = parseScopeStream(selectedFiles.get(old.checkpoint)!.content, selectedFiles.get(old.patches)!.content, "cwd")!;
-					const source = serializeScopeStream(stream, "cwd", cwd);
-					move(old.checkpoint, target.checkpoint, source.checkpoint);
-					move(old.patches, target.patches, source.patches);
-				} else {
-					move(old.checkpoint, target.checkpoint);
-					move(old.patches, target.patches);
-				}
-			}
-		}
-		const oldRuntime = legacySessionRuntimePaths(cwd, sessionId, root);
-		const targetRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-		const migratedRuntime = structuredClone(selected.runtime.document);
-		migratedRuntime.meta.temporalRevision = "self";
-		const runtimeSource = serializeSessionRuntime(migratedRuntime, cwd, sessionId);
-		if (selectedFiles.get(oldRuntime.config)?.identity !== "missing") {
-			move(oldRuntime.config, targetRuntime.config, runtimeSource.config);
-			move(oldRuntime.meta, targetRuntime.meta, runtimeSource.meta);
-		} else {
-			for (const [path, content] of [[targetRuntime.config, runtimeSource.config], [targetRuntime.meta, runtimeSource.meta]] as const) {
-				const source = selectedFiles.get(path);
-				if (!source || source.identity === "missing" || source.content === undefined) throw new Error(`Layout migration runtime is unavailable: ${path}`);
-				if (bases.get(path)?.identity !== source.identity) throw new Error(`Layout migration runtime changed after selected revision: ${path}`);
-				if (source.content !== content) updates.push({ path, content });
-			}
-		}
-		if (updates.length === 0) return undefined;
-		let publication: ReturnType<typeof publishOwnedCohort>;
-		try {
-			publication = publishOwnedCohort(root, updates, [...bases.values()], revision, [], "migrate");
-		} catch (error) {
-			removeEmptyDirectories(targetDirectories);
-			throw error;
-		}
-		const nextFiles = temporalFileReceipts(canonical, updates);
-		removeEmptyDirectories(cleanupDirectories);
-		return { ...publication, base: { head: publication.commit ?? revision, files: nextFiles }, view };
-	});
+	return { base: { head: revision, files }, scopes, runtime: { document, revision: owner }, provenance };
 }
 
 function relativeOwnedPath(path: string, repositoryRoot: string): string {
@@ -452,6 +293,7 @@ function commitOwnedFiles(
 	expectedHead: string | undefined,
 	scopes: readonly StateScope[],
 	operation: "persist" | "migrate" = "persist",
+	rootCommit = false,
 ): string | undefined {
 	assertOwnedFileUpdates(updates, repositoryRoot);
 	const branchRef = currentBranchRef(repositoryRoot);
@@ -482,13 +324,13 @@ function commitOwnedFiles(
 		// NUL framing preserves literal path characters while the blobs retain exact prepared bytes.
 		if (entries.length > 0) git(repositoryRoot, ["update-index", "-z", "--index-info"], { env, input: entries.join("") });
 		const tree = git(repositoryRoot, ["write-tree"], { env }).stdout.trim();
-		if (expectedHead !== undefined) {
+		if (expectedHead !== undefined && !rootCommit) {
 			const previousTree = git(repositoryRoot, ["rev-parse", `${expectedHead}^{tree}`]).stdout.trim();
 			if (tree === previousTree) return undefined;
 		}
 		const message = `state-flow: ${operation} ${scopes.join("+") || "runtime"} transition\n\n${STATE_FLOW_COMMIT_TRAILER}\n`;
 		const commitArgs = ["commit-tree", tree];
-		if (expectedHead !== undefined) commitArgs.push("-p", expectedHead);
+		if (expectedHead !== undefined && !rootCommit) commitArgs.push("-p", expectedHead);
 		const commit = git(repositoryRoot, commitArgs, { input: message }).stdout.trim();
 		const zero = "0".repeat(40);
 		assertOwnedFileUpdates(updates, repositoryRoot);
@@ -530,7 +372,7 @@ function migrateLegacyStorageUnderLock(cwd: string, sessionId: string, root: str
 	if (current.some((base, index) => base.identity !== plan.bases[index]!.identity)) {
 		throw new Error("State Flow storage changed concurrently while planning migration");
 	}
-	return { scopes: plan.scopes, ...publishOwnedCohort(root, plan.updates, plan.bases, currentHead(root), plan.scopes, "migrate") };
+	return { scopes: plan.scopes, ...publishOwnedCohort(root, plan.updates, plan.bases, currentHead(root), plan.scopes, "migrate", false, true) };
 }
 
 function publishOwnedCohort(
@@ -541,12 +383,13 @@ function publishOwnedCohort(
 	scopes: readonly StateScope[],
 	operation: "persist" | "migrate",
 	push = true,
+	rootCommit = false,
 ): { commit?: string; push?: GitPushResult } {
 	let published = false;
 	try {
 		writeOwnedFileUpdates(updates, bases, root);
 		published = true;
-		const commit = commitOwnedFiles(root, updates, head, scopes, operation);
+		const commit = commitOwnedFiles(root, updates, head, scopes, operation, rootCommit);
 		return commit === undefined ? {} : push ? { commit, push: pushGitCommit(root, commit) } : { commit };
 	} catch (error) {
 		if (published) {
@@ -567,7 +410,8 @@ export function adoptFileStateToGit(cwd: string, sessionId: string, repositoryRo
 	if (snapshot.meta.step !== selected.runtime.meta.step) throw new Error("Git adoption must preserve the semantic step");
 	const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
 	runtime.meta.temporalRevision = "self";
-	const sources = serializeSessionRuntime(runtime, cwd, sessionId);
+	const sources = serializeSessionRuntime(runtime, cwd, sessionId, selected.view.scopes.session,
+		selected.base.files.find(({ path }) => path === sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey).meta)?.content);
 	initializeGitRepository(repositoryRoot);
 	return withPublicationLock(repositoryRoot, (root) => {
 		const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);

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

@@ -1,19 +1,19 @@
-// Domain: conservative current-snapshot migration planning; Git owns publication and rollback.
-import { randomUUID } from "node:crypto";
-import { lstatSync } from "node:fs";
+// Domain: predecessor temporal-envelope migration planning; Git/files backends own publication and rollback.
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import {
 	captureOwnedFileBases,
 	cwdScopePaths,
 	parseScopeStream,
-	parseStateSource,
+	serializeScopeMetadata,
 	serializeScopeStream,
+	sessionScopeKey,
 	sessionScopePaths,
 	type DurableFileBase,
 	type OwnedFileUpdate,
 } from "./durable.ts";
+import { canonicalJson } from "./json.ts";
 import type { StateScope } from "./state.ts";
-import type { ScopeStream } from "./temporal.ts";
 
 export interface LegacyStorageMigration {
 	bases: DurableFileBase[];
@@ -21,23 +21,66 @@ export interface LegacyStorageMigration {
 	scopes: StateScope[];
 }
 
+interface MigrationDirectory {
+	directory: string;
+	scope: StateScope;
+	cwdIdentity?: string;
+}
+
+/** Discover every owner-proven CWD and session cohort beneath the configured store. */
+function migrationDirectories(cwd: string, sessionId: string, root: string, sessionKey: string): MigrationDirectory[] {
+	const selectedCwd = cwdScopePaths(cwd, root).directory;
+	const selectedSession = sessionScopePaths(cwd, sessionId, root, sessionKey).directory;
+	const directories: MigrationDirectory[] = [{ directory: root, scope: "global" }];
+	const cwdOwners = new Map<string, string>([[selectedCwd, resolve(cwd)]]);
+	if (lstatSync(root, { throwIfNoEntry: false }) !== undefined) {
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			const directory = join(root, entry.name);
+			let checkpoint: unknown;
+			let meta: unknown;
+			try { checkpoint = JSON.parse(readFileSync(join(directory, "checkpoint.json"), "utf8")); }
+			catch { continue; }
+			try { meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8")); } catch { /* predecessor metadata may be absent */ }
+			const owner = checkpoint && typeof checkpoint === "object" && !Array.isArray(checkpoint) && (checkpoint as { owner?: unknown }).owner
+				? (checkpoint as { owner: { cwd?: unknown } }).owner
+				: meta && typeof meta === "object" && !Array.isArray(meta) ? (meta as { owner?: { cwd?: unknown } }).owner : undefined;
+			if (owner && typeof owner.cwd === "string" && resolve(owner.cwd) === owner.cwd) cwdOwners.set(directory, owner.cwd);
+		}
+	}
+	for (const [cwdDirectory, cwdOwner] of cwdOwners) {
+		directories.push({ directory: cwdDirectory, scope: "cwd", cwdIdentity: cwdOwner });
+		if (lstatSync(cwdDirectory, { throwIfNoEntry: false }) === undefined) continue;
+		for (const entry of readdirSync(cwdDirectory, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			try { sessionScopeKey(entry.name); } catch { continue; }
+			const directory = join(cwdDirectory, entry.name);
+			let meta: unknown;
+			try { meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8")); }
+			catch { continue; }
+			const identity = meta && typeof meta === "object" && !Array.isArray(meta) ? (meta as { identity?: unknown }).identity : undefined;
+			if (!identity || typeof identity !== "object" || Array.isArray(identity)) continue;
+			const owner = identity as { cwd?: unknown; sessionId?: unknown };
+			if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) directories.push({ directory, scope: "session" });
+		}
+	}
+	if (!directories.some(({ directory }) => directory === selectedSession)) directories.push({ directory: selectedSession, scope: "session" });
+	return directories;
+}
+
 /** Read-only activation eligibility, before global migration or any repository publication. */
 export function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean {
 	const root = resolve(repositoryRoot);
 	const directory = cwdScopePaths(cwd, root).directory;
-	const [legacy, checkpoint, patches] = captureOwnedFileBases([
-		join(directory, "state.json"), join(directory, "checkpoint.json"), join(directory, "patches.jsonl"),
+	const [checkpoint, patches, meta] = captureOwnedFileBases([
+		join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
 	], root);
-	if (checkpoint!.content !== undefined) {
-		if (legacy!.content !== undefined) throw new Error(`Ambiguous State Flow storage has both current and checkpoint snapshots: ${directory}`);
-		return parseScopeStream(checkpoint!.content, patches!.content, "cwd", cwd) !== undefined;
-	}
-	if (legacy!.content !== undefined) return parseStateSource(legacy!.content, legacy!.path) !== undefined;
-	if (patches!.content !== undefined) throw new Error(`State Flow tail has no provable snapshot: ${directory}`);
+	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;
 }
 
-/** Cheap canonical-layout fast path: inspect only the three predecessor snapshot names. */
+/** Detect predecessor snapshots or temporal envelopes without mutating the store. */
 export function hasLegacyStateSources(
 	cwd: string,
 	sessionId: string,
@@ -45,11 +88,13 @@ export function hasLegacyStateSources(
 	sessionKey = sessionId,
 ): boolean {
 	const root = resolve(repositoryRoot);
-	return [
-		join(root, "state.json"),
-		join(cwdScopePaths(cwd, root).directory, "state.json"),
-		join(sessionScopePaths(cwd, sessionId, root, sessionKey).directory, "state.json"),
-	].some((path) => lstatSync(path, { throwIfNoEntry: false }) !== undefined);
+	return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory }) => {
+		if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined) return false;
+		try {
+			const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
+			return meta === null || typeof meta !== "object" || !("temporal" in meta);
+		} catch { return true; }
+	});
 }
 
 /** Plan from current scope snapshots only; old explanatory journals are never replay input. */
@@ -57,48 +102,39 @@ export function planLegacyStorageMigration(
 	cwd: string,
 	sessionId: string,
 	repositoryRoot: string,
-	origin: string = randomUUID(),
+	_origin?: string,
 	sessionKey = sessionId,
 ): LegacyStorageMigration {
 	const root = resolve(repositoryRoot);
-	const directories: Record<StateScope, string> = {
-		global: root,
-		cwd: cwdScopePaths(cwd, root).directory,
-		session: sessionScopePaths(cwd, sessionId, root, sessionKey).directory,
-	};
-	const paths = Object.values(directories).flatMap((directory) => [
-		join(directory, "state.json"), join(directory, "checkpoint.json"), join(directory, "patches.jsonl"),
+	const directories = migrationDirectories(cwd, sessionId, root, sessionKey);
+	const paths = directories.flatMap(({ directory }) => [
+		join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
 	]);
 	const bases = captureOwnedFileBases(paths, root);
 	const byPath = new Map(bases.map((base) => [base.path, base]));
 	const updates: OwnedFileUpdate[] = [];
 	const scopes: StateScope[] = [];
-	for (const scope of ["global", "cwd", "session"] as const) {
-		const directory = directories[scope];
-		const legacy = byPath.get(join(directory, "state.json"))!;
+	for (const { scope, directory, cwdIdentity } of directories) {
 		const checkpoint = byPath.get(join(directory, "checkpoint.json"))!;
 		const patches = byPath.get(join(directory, "patches.jsonl"))!;
+		const meta = byPath.get(join(directory, "meta.json"))!;
 		if (checkpoint.content !== undefined) {
-			if (legacy.content !== undefined) throw new Error(`Ambiguous State Flow storage has both current and checkpoint snapshots: ${directory}`);
-			parseScopeStream(checkpoint.content, patches.content, scope, scope === "cwd" ? cwd : undefined);
-			continue;
-		}
-		if (legacy.content === undefined) {
-			if (patches.content !== undefined) throw new Error(`State Flow tail has no provable snapshot: ${directory}`);
+			const stream = parseScopeStream(checkpoint.content, patches.content, scope, cwdIdentity, meta.content)!;
+			const source = serializeScopeStream(stream, scope, cwdIdentity);
+			let metadata = serializeScopeMetadata(undefined, stream, scope, cwdIdentity, meta.content);
+			if (scope === "session") {
+				const runtime = JSON.parse(metadata) as Record<string, unknown>;
+				runtime.revision = "self";
+				runtime.temporalRevision = "self";
+				metadata = `${canonicalJson(runtime)}\n`;
+			}
+			if (checkpoint.content !== source.checkpoint || patches.content !== source.patches || meta.content !== metadata) {
+				if (!scopes.includes(scope)) scopes.push(scope);
+				updates.push({ path: checkpoint.path, content: source.checkpoint }, { path: patches.path, content: source.patches }, { path: meta.path, content: metadata });
+			}
 			continue;
 		}
-		const state = parseStateSource(legacy.content, legacy.path)!;
-		const stream: ScopeStream = {
-			checkpoint: { through: { id: origin, position: 0, parent: null }, state },
-			patches: [],
-		};
-		const source = serializeScopeStream(stream, scope, scope === "cwd" ? cwd : undefined);
-		scopes.push(scope);
-		updates.push(
-			{ path: checkpoint.path, content: source.checkpoint },
-			{ path: patches.path, content: source.patches },
-			{ path: legacy.path },
-		);
+		if (patches.content !== undefined) throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
 	}
 	return { bases, updates, scopes };
 }

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

@@ -0,0 +1,40 @@
+import { projectStateForModel, type MaterializedState, type ScopePatch, type StateScope } from "./state.ts";
+import { readTemporalState, type TemporalState, type TransitionBoundary } from "./temporal.ts";
+
+export type StateReadQuery =
+	| { kind: "state"; path: string; offset: number; scope?: StateScope }
+	| { kind: "patch"; path: string; offset: number; scope: StateScope };
+
+export type StateReadResult =
+	| { path: string; boundary: TransitionBoundary; state: MaterializedState }
+	| { path: string; boundary: TransitionBoundary; patch: ScopePatch & { response?: string } };
+
+const PATH_PATTERN = /^state(?:\[(\d+)\])?(?:\.(global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?)?$/;
+
+/** Resolve the compact model-facing path grammar without treating aliases as literal JSON containers. */
+export function parseStateReadPath(path: string): StateReadQuery {
+	const match = PATH_PATTERN.exec(path);
+	if (!match) throw new Error("Invalid State Flow read path");
+	const [, effectiveOffset, scope, scopeOffset, patchOffset] = match;
+	if (effectiveOffset !== undefined && scope !== undefined) throw new Error("State Flow read path cannot index both state and a scope");
+	if (path.includes(".patches") && scopeOffset !== undefined) throw new Error("Index patches after .patches, not after the scope");
+	const rawOffset = patchOffset ?? scopeOffset ?? effectiveOffset ?? "0";
+	const offset = Number(rawOffset);
+	if (!Number.isSafeInteger(offset) || offset < 0 || offset > 7) throw new Error("State Flow read path index must be an integer from 0 to 7");
+	if (patchOffset !== undefined || path.endsWith(".patches")) {
+		return { kind: "patch", path, offset, scope: scope as StateScope };
+	}
+	return { kind: "state", path, offset, ...(scope === undefined ? {} : { scope: scope as StateScope }) };
+}
+
+export function readStatePath(view: TemporalState, path: string): StateReadResult {
+	const query = parseStateReadPath(path);
+	if (query.kind === "state") {
+		const boundary = view.lineage[view.lineage.length - 1 - query.offset];
+		if (!boundary) throw new Error("Requested history predates the proven temporal origin");
+		return { path, boundary: structuredClone(boundary), state: projectStateForModel(readTemporalState(view, query.offset, query.scope)) };
+	}
+	const record = view.scopes[query.scope].patches.at(-1 - query.offset);
+	if (!record) throw new Error(`Requested ${query.scope} patch predates retained hot history`);
+	return { path, boundary: structuredClone(record.transition), patch: structuredClone(record.patch) };
+}

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

@@ -6,49 +6,26 @@ export interface SnapshotRecovery {
 	disabledMarker?: true;
 }
 
-function failureMessage(snapshot: Snapshot): string | undefined {
-	return !snapshot.config.enabled && snapshot.meta.validation?.attempt === 0
-		? snapshot.meta.validation.error
-		: undefined;
-}
-
-/** Recover the newest valid snapshot, falling back through the active branch. */
-export function recoverSnapshot(candidates: readonly unknown[], resolveRevision?: (revision: string, legacy?: Snapshot) => Snapshot): SnapshotRecovery {
+/** Recover the newest supported pointer or disabled marker from the active branch. */
+export function recoverSnapshot(candidates: readonly unknown[], resolveRevision?: (revision: string) => Snapshot): SnapshotRecovery {
 	const skipped: string[] = [];
-	let newestFailure: Snapshot | undefined;
 	for (const candidate of candidates) {
-		let migrated: Snapshot;
 		let selectedRevision: string | undefined;
 		try {
 			const parsed = parsePiCheckpoint(candidate);
-			if ("revision" in parsed) {
-				selectedRevision = parsed.revision;
-				if (!resolveRevision) throw new Error("Checkpoint pointer requires immutable runtime resolution");
-				return { snapshot: resolveRevision(parsed.revision), skipped };
-			}
 			if ("disabled" in parsed) return { snapshot: emptySnapshot(), skipped, disabledMarker: true };
-			migrated = parsed;
-			if (failureMessage(migrated) === undefined && migrated.meta.durableBase) {
-				selectedRevision = migrated.meta.durableBase;
-				if (!resolveRevision) throw new Error("Legacy checkpoint requires immutable runtime resolution");
-				return { snapshot: resolveRevision(migrated.meta.durableBase, migrated), skipped };
-			}
+			selectedRevision = parsed.revision;
+			if (!resolveRevision) throw new Error("Checkpoint pointer requires immutable runtime resolution");
+			return { snapshot: resolveRevision(parsed.revision), skipped };
 		} catch (error) {
 			if (selectedRevision && error instanceof RevisionUnavailableError) {
 				return { snapshot: migrationFailure({ meta: { durableBase: selectedRevision } }, `Snapshot restoration failed: ${error.message}`), skipped };
 			}
-			migrated = migrationFailure(
-				{},
-				`Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`,
-			);
+			skipped.push(`Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`);
 		}
-		const failure = failureMessage(migrated);
-		if (failure === undefined) return { snapshot: migrated, skipped };
-		newestFailure ??= migrated;
-		skipped.push(failure);
 	}
 	return {
-		snapshot: newestFailure ?? emptySnapshot(),
+		snapshot: migrationFailure({}, skipped[0] ?? "Snapshot restoration failed: no supported checkpoint"),
 		skipped,
 	};
 }