@llblab/pi-kit 0.13.0 → 0.14.1

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

@@ -3,7 +3,7 @@ import { lstatSync } from "node:fs";
 import { join } from "node:path";
 import { classifyScopeStream, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
 import { parseArtifactProvenanceRegistry, pruneArtifactProvenance, type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./artifact.ts";
-import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadLegacyStatesAtRevision, loadTemporalRevision, migrateHashedCwdAtHead, migrateHashedLayoutAtHead, migrateLegacyStorageToGit, publishTemporalStateToGit, type TemporalGitBase } from "./git.ts";
+import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit, type TemporalGitBase } from "./git.ts";
 import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles, type TemporalFileBase } from "./storage.ts";
 import { type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
 import { hashJson, sameJson } from "./json.ts";
@@ -73,26 +73,18 @@ export function inspectRuntimeRevision(cwd: string, sessionId: string, root: str
 	if (!loaded.scopes.global || !loaded.scopes.cwd || !loaded.scopes.session) throw new Error("Incomplete temporal scope cohort");
 	const view = { lineage: resolved.lineage, scopes: { global: loaded.scopes.global, cwd: loaded.scopes.cwd, session: loaded.scopes.session } };
 	validateTemporalState(view);
-	return { runtime: loaded.runtime, resolved, view, provenance: loaded.provenance, ...(loaded.legacyLayout ? { legacyLayout: true as const } : {}) };
+	return { runtime: loaded.runtime, resolved, view, provenance: loaded.provenance };
 }
 
-/** Both checkpoint generations validate their immutable target before any live migration/publication. */
-export function inspectSnapshotRevision(cwd: string, sessionId: string, root: string, revision: string, legacySnapshot?: Snapshot, sessionKey = sessionId) {
+/** Validate one supported immutable target before any live migration/publication. */
+export function inspectSnapshotRevision(cwd: string, sessionId: string, root: string, revision: string, _legacySnapshot?: Snapshot, sessionKey = sessionId) {
 	if (isFileRevision(revision)) {
 		const file = loadTemporalFileRevision(cwd, sessionId, root, revision, sessionKey);
 		return { snapshot: resolveFileSessionRuntime(file.runtime, revision), file };
 	}
 	if (detectGitCapability() === "files") throw new RevisionUnavailableError("Git is unavailable; cannot restore a Git-linked revision");
-	try {
-		const temporal = inspectRuntimeRevision(cwd, sessionId, root, revision, sessionKey);
-		return { snapshot: temporal.resolved.snapshot, temporal };
-	} catch (error) {
-		if (!legacySnapshot || !(error instanceof Error) || !error.message.includes("Historical legacy storage requires explicit migration")) throw error;
-		const historical = loadLegacyStatesAtRevision(cwd, sessionId, root, revision, sessionKey);
-		const snapshot = structuredClone(legacySnapshot);
-		if (historical.session !== undefined) snapshot.legacySession = { state: historical.session };
-		return { snapshot, shared: { global: historical.global ?? emptyState(), cwd: historical.cwd ?? emptyState() } };
-	}
+	const temporal = inspectRuntimeRevision(cwd, sessionId, root, revision, sessionKey);
+	return { snapshot: temporal.resolved.snapshot, temporal };
 }
 
 /** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
@@ -130,6 +122,40 @@ export class TemporalRuntime {
 		this.backend = backend;
 	}
 
+	/** Explicit start migrates a predecessor envelope even when passive restore already populated the cache. */
+	migrateLegacyStorage(): void {
+		if (!this.view || !this.backend || !hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) return undefined;
+		const publication = this.backend === "git"
+			? migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey)
+			: (migrateLegacyStorageToFiles(this.cwd, this.sessionId, this.root, this.sessionKey), undefined);
+		const base = this.backend === "files"
+			? captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey)
+			: captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		const scopes = Object.fromEntries(SCOPES.map((scope) => {
+			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+			const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope,
+				scope === "cwd" ? this.cwd : undefined, files.get(paths.meta));
+			if (!stream) throw new Error(`State Flow ${scopeLabel(scope)} scope disappeared during migration`);
+			return [scope, stream];
+		})) as TemporalState["scopes"];
+		const migrated = { lineage: this.view.lineage, scopes };
+		validateTemporalState(migrated);
+		if (!sameJson(this.states(), {
+			global: readTemporalState(migrated, 0, "global"),
+			cwd: readTemporalState(migrated, 0, "cwd"),
+			session: readTemporalState(migrated, 0, "session"),
+		})) throw new Error("State Flow migration changed materialized semantic state");
+		this.view = migrated;
+		this.base = base;
+		this.provenanceByScope = {
+			global: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta), "State Flow global metadata"),
+			cwd: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta), "State Flow CWD metadata"),
+			session: this.provenanceByScope.session,
+		};
+		if (publication?.commit) this.semanticRevision = publication.commit;
+	}
+
 	/** Explicit start can upgrade a proven file cohort; failed adoption leaves the cache in file mode. */
 	promote(snapshot: Snapshot): RuntimePublication | undefined {
 		if (this.backend !== "files" || !this.view || detectGitCapability() === "files") return undefined;
@@ -244,45 +270,16 @@ export class TemporalRuntime {
 			this.absentSharedScopes.clear();
 			return inspected.snapshot;
 		}
-		if (!inspected.temporal) {
-			const migrated = inspected.snapshot;
-			const publication = this.initialize(migrated, true, inspected.shared);
-			if (publication?.commit) migrated.meta.durableBase = publication.commit;
-			if (publication?.push?.status === "pending") migrated.meta.pendingPublication = { commit: publication.push.commit, error: publication.push.error ?? "Unconfirmed publication" };
-			else delete migrated.meta.pendingPublication;
-			delete migrated.legacySession;
-			return migrated;
-		}
 		const loaded = inspected.temporal;
 		const { resolved, view } = loaded;
 		let base = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const reference = loaded.runtime.document.meta.temporalRevision;
 		let semanticRevision = reference === undefined || reference === "self" ? loaded.runtime.revision : reference;
 		let publicationTarget = resolved.publicationTarget;
-		let migrationPush;
-		if (loaded.legacyLayout && base.head) {
-			const liveRevision = base.head;
-			const migration = migrateHashedLayoutAtHead(this.cwd, this.sessionId, this.root, liveRevision, this.sessionKey);
-			if (migration?.commit) {
-				base = migration.base;
-				if (liveRevision === revision) {
-					semanticRevision = migration.commit;
-					publicationTarget = migration.commit;
-					migrationPush = migration.push;
-				}
-			} else {
-				migrateHashedCwdAtHead(this.cwd, this.root);
-				base = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
-			}
-		}
 		resolved.snapshot.meta.durableBase = publicationTarget;
 		const savedRuntime = hashJson(createSessionRuntime(resolved.snapshot, this.cwd, this.sessionId, view.lineage));
 		resolved.snapshot.meta.pendingPublication = { commit: publicationTarget, error: "Durable publication intent is unconfirmed" };
-		if (migrationPush?.status === "pending") {
-			resolved.snapshot.meta.pendingPublication = { commit: migrationPush.commit, error: migrationPush.error ?? "Unconfirmed publication" };
-		} else if (migrationPush !== undefined) {
-			delete resolved.snapshot.meta.pendingPublication;
-		} else {
+		{
 			try {
 				if (isLocalGitRepository(this.root)) delete resolved.snapshot.meta.pendingPublication;
 			} catch {
@@ -314,7 +311,6 @@ export class TemporalRuntime {
 		if (!allowCreateCwd && !hasCwd) return undefined;
 		const backend = copy?.backend ?? this.backend ?? (detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files");
 		if (!copy && backend === "git") {
-			if (!hasCwd) migrateHashedCwdAtHead(this.cwd, this.root);
 			if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
 				migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey);
 			}
@@ -342,17 +338,18 @@ export class TemporalRuntime {
 		})) throw new Error("Legacy State Flow storage changed during initialization; retry migration from a fresh basis");
 		const streams = Object.fromEntries(SCOPES.map((scope) => {
 			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-			return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined)];
+			return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope,
+				scope === "cwd" ? this.cwd : undefined, files.get(paths.meta))];
 		})) as Record<StateScope, TemporalState["scopes"][StateScope] | undefined>;
 		if (!streams.cwd && !allowCreateCwd) return undefined;
 		if (copy && !streams.global) throw new Error("State Flow fork requires existing shared scope storage");
 		const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.meta), this.cwd, this.sessionId);
-		if (existingRuntime && !snapshot.legacySession && !newSessionOrigin) throw new Error("Existing session runtime requires a branch revision pointer");
+		if (existingRuntime && !newSessionOrigin) throw new Error("Existing session runtime requires a branch revision pointer");
 		// Explicit start before any branch runtime is a new origin, never inheritance of a later session layer.
-		if (snapshot.legacySession || newSessionOrigin) streams.session = undefined;
+		if (newSessionOrigin) streams.session = undefined;
 		if (copy) streams.session = copy.stream;
-		const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: snapshot.legacySession?.state ?? emptyState() }, randomUUID());
+		const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID());
 		const candidate = new TemporalRuntime(this.cwd, this.session, this.root);
 		candidate.backend = backend;
 		candidate.base = base;
@@ -431,7 +428,8 @@ export class TemporalRuntime {
 		const reconciliation = `${head ?? "files"}:reconcile:${randomUUID()}`;
 		for (const scope of SHARED_SCOPES) {
 			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-			const presence = classifyScopeStream(liveFiles.get(paths.checkpoint)?.content, liveFiles.get(paths.patches)?.content, scope, scope === "cwd" ? this.cwd : undefined);
+			const presence = classifyScopeStream(liveFiles.get(paths.checkpoint)?.content, liveFiles.get(paths.patches)?.content, scope,
+				scope === "cwd" ? this.cwd : undefined, liveFiles.get(paths.meta)?.content);
 			if (presence.kind === "absent") {
 				absentScopes.push(scope);
 				provenance[scope] = {};

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

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { parseRemotePublicationPolicyDocument, serializeRemotePublicationPolicyDocument, type RemotePublicationPolicyDocument } from "./publication.ts";
 import { applyPatch, canonicalJson, containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
-import { validateTemporalLineage, type TransitionBoundary } from "./temporal.ts";
+import { validateTemporalLineage, type ScopeStream, type TransitionBoundary } from "./temporal.ts";
 import { migrateLegacySkillCompilations } from "./skills.ts";
 import { isMaterializedState, type MaterializedState } from "./state.ts";
 const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
@@ -37,16 +37,10 @@ export interface SnapshotMeta {
 	remotePublication?: RemotePublicationPolicyDocument;
 }
 
-export interface LegacySessionMigration {
-	state: MaterializedState;
-}
-
 /** In-memory runtime config/provenance; durable config/meta and scope files own restoration. */
 export interface StateFlowSnapshot {
 	config: SnapshotConfig;
 	meta: SnapshotMeta;
-	/** Ephemeral one-way migration payload. persistSnapshot() never writes it to Pi checkpoints. */
-	legacySession?: LegacySessionMigration;
 }
 
 export type Snapshot = StateFlowSnapshot;
@@ -64,13 +58,15 @@ export interface SessionRuntime {
 		temporalRevision?: "self" | string;
 		/** Durable intent survives a crash before the push result can be observed. */
 		publication: "unconfirmed" | "files";
+		temporal?: { checkpoint: TransitionBoundary; patches: TransitionBoundary[] };
+		[key: string]: unknown;
 	};
 }
 
 export function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime {
 	if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "config,meta"
 		|| !isObject(value.config) || !isObject(value.meta)) throw new Error("Invalid State Flow session runtime envelope");
-	const { version, identity, lineage, revision, temporalRevision, publication, artifacts, ...fields } = value.meta;
+	const { version, identity, lineage, revision, temporalRevision, publication, artifacts, temporal: _temporalScope, ...fields } = value.meta;
 	if (artifacts !== undefined) parseArtifactProvenanceRegistry(artifacts, "State Flow session artifact provenance");
 	if (temporalRevision !== undefined && temporalRevision !== "self"
 		&& !isExactRevision(temporalRevision)) throw new Error("Invalid temporal revision reference");
@@ -81,13 +77,16 @@ export function validateSessionRuntime(value: unknown, cwd: string, sessionId: s
 		throw new Error("State Flow runtime scope identity mismatch");
 	}
 	validateTemporalLineage(lineage);
-	const allowed = new Set(["step", "specification", "validation", "bootstrap", "remotePublication"]);
-	if (Object.keys(fields).some((key) => !allowed.has(key))) throw new Error("Unexpected State Flow runtime metadata field");
+	const known = new Set(["step", "specification", "validation", "bootstrap", "remotePublication"]);
+	if (Object.keys(fields).some((key) => ["state", "contract", "working", "response"].includes(key))) {
+		throw new Error("Semantic state does not belong in State Flow runtime metadata");
+	}
+	const runtimeFields = Object.fromEntries(Object.entries(fields).filter(([key]) => known.has(key)));
 	const { transitionWindow: _retiredWindow, ...supportedConfig } = value.config;
-	const normalized = migrateSnapshot({ config: supportedConfig, meta: fields });
-	if (fields.bootstrap === false) normalized.meta.bootstrap = false;
-	if (fields.step === Number.MAX_SAFE_INTEGER) normalized.meta.step = Number.MAX_SAFE_INTEGER;
-	if (canonicalJson({ config: normalized.config, meta: normalized.meta }) !== canonicalJson({ config: supportedConfig, meta: fields })) {
+	const normalized = migrateSnapshot({ config: supportedConfig, meta: runtimeFields });
+	if (runtimeFields.bootstrap === false) normalized.meta.bootstrap = false;
+	if (runtimeFields.step === Number.MAX_SAFE_INTEGER) normalized.meta.step = Number.MAX_SAFE_INTEGER;
+	if (canonicalJson({ config: normalized.config, meta: normalized.meta }) !== canonicalJson({ config: supportedConfig, meta: runtimeFields })) {
 		throw new Error("Invalid State Flow runtime configuration or counters");
 	}
 }
@@ -117,13 +116,31 @@ export function createSessionRuntime(
 	return runtime;
 }
 
-export function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string): { config: string; meta: string } {
+export function serializeSessionRuntime(
+	runtime: SessionRuntime, cwd: string, sessionId: string, stream?: ScopeStream, existingSource?: string,
+): { config: string; meta: string } {
 	validateSessionRuntime(runtime, cwd, sessionId);
-	return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson(runtime.meta)}\n` };
+	let existing: Record<string, unknown> = {};
+	if (existingSource !== undefined) {
+		try { existing = JSON.parse(existingSource) as Record<string, unknown>; }
+		catch { throw new Error("State Flow session runtime contains invalid JSON"); }
+		if (!isObject(existing) || !isJsonValue(existing)) throw new Error("Invalid State Flow session runtime metadata");
+	}
+	const temporal = stream === undefined ? runtime.meta.temporal : {
+		checkpoint: structuredClone(stream.checkpoint.through),
+		patches: stream.patches.map((record) => structuredClone(record.transition)),
+	};
+	return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson({ ...existing, ...runtime.meta, ...(temporal ? { temporal } : {}) })}\n` };
 }
 
 export function parseSessionRuntime(config: string | undefined, meta: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined {
 	if (config === undefined && meta === undefined) return undefined;
+	if (config === undefined && meta !== undefined) {
+		let document: unknown;
+		try { document = JSON.parse(meta); } catch { throw new Error("State Flow session runtime contains invalid JSON"); }
+		if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage")
+			&& Object.keys(document).every((key) => ["version", "artifacts", "temporal", "owner"].includes(key))) return undefined;
+	}
 	if (config === undefined || meta === undefined) throw new Error("Incomplete State Flow config/meta pair");
 	let runtime: unknown;
 	try {
@@ -132,7 +149,8 @@ export function parseSessionRuntime(config: string | undefined, meta: string | u
 		throw new Error("State Flow session runtime contains invalid JSON");
 	}
 	validateSessionRuntime(runtime, cwd, sessionId);
-	return { config: { enabled: runtime.config.enabled }, meta: runtime.meta };
+	const { temporal: _temporal, ...runtimeMeta } = runtime.meta;
+	return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
 }
 
 export function resolveSessionRuntime(runtime: SessionRuntime, revision: string): { snapshot: Snapshot; lineage: TransitionBoundary[]; publicationTarget: string; artifacts: ArtifactProvenanceRegistry } {
@@ -226,16 +244,8 @@ function restoredMeta(value: unknown, legacy: JsonObject = {}): SnapshotMeta {
 	};
 }
 
-function envelope(
-	enabled: boolean,
-	meta: SnapshotMeta,
-	legacySession?: LegacySessionMigration,
-): Snapshot {
-	return {
-		config: { enabled },
-		meta,
-		...(legacySession === undefined ? {} : { legacySession }),
-	};
+function envelope(enabled: boolean, meta: SnapshotMeta): Snapshot {
+	return { config: { enabled }, meta };
 }
 
 export function emptySnapshot(enabled = false): Snapshot {
@@ -262,13 +272,12 @@ export function persistableSnapshot(snapshot: Snapshot): PiCheckpoint {
 		if (!isDurableRevision(snapshot.meta.durableBase)) throw new Error("Checkpoint requires an exact Git revision or file reference");
 		return { revision: snapshot.meta.durableBase };
 	}
-	if (snapshot.legacySession) throw new Error("Legacy semantic state requires migration before checkpoint publication");
 	if (snapshot.config.enabled) throw new Error("Enabled checkpoint requires a durable runtime revision");
 	return { disabled: true };
 }
 
-/** New wire shapes are strict; predecessor envelopes remain one-way migration input. */
-export function parsePiCheckpoint(value: unknown): PiCheckpoint | Snapshot {
+/** Pi checkpoints admit only strict revision pointers or the disabled marker. */
+export function parsePiCheckpoint(value: unknown): PiCheckpoint {
 	if (!isObject(value)) throw new Error("Invalid State Flow checkpoint");
 	if (Object.hasOwn(value, "revision") || Object.hasOwn(value, "disabled")) {
 		if (Object.keys(value).length === 1) {
@@ -277,13 +286,7 @@ export function parsePiCheckpoint(value: unknown): PiCheckpoint | Snapshot {
 		}
 		throw new Error("Invalid State Flow checkpoint pointer or disabled marker");
 	}
-	if (!Object.hasOwn(value, "config") && !Object.hasOwn(value, "enabled")) throw new Error("Unrecognized State Flow checkpoint");
-	const config = Object.hasOwn(value, "config") ? value.config : value;
-	if (!isObject(config) || typeof config.enabled !== "boolean") throw new Error("Invalid legacy State Flow configuration");
-	if (Object.hasOwn(value, "meta") && !isObject(value.meta)) throw new Error("Invalid legacy State Flow metadata");
-	const meta = isObject(value.meta) ? value.meta : value;
-	if (Object.hasOwn(meta, "durableBase") && !isDurableRevision(meta.durableBase)) throw new Error("Invalid legacy State Flow revision");
-	return migrateSnapshot(value);
+	throw new Error("Unrecognized State Flow checkpoint");
 }
 
 export function migrationFailure(data: JsonObject, error: string): Snapshot {
@@ -296,71 +299,12 @@ export function migrationFailure(data: JsonObject, error: string): Snapshot {
 	return envelope(false, meta);
 }
 
-function migratedSnapshot(
-	enabled: boolean,
-	meta: SnapshotMeta,
-	state: MaterializedState,
-): Snapshot {
-	return envelope(enabled, meta, {
-		state: migrateLegacySkillCompilations(state),
-	});
-}
-
 export function migrateSnapshot(value: unknown): Snapshot {
 	if (!isObject(value)) return emptySnapshot();
 	const isEnvelope = Object.hasOwn(value, "config") || Object.hasOwn(value, "meta");
 	const config = isEnvelope && isObject(value.config) ? value.config : value;
 	const meta = restoredMeta(isEnvelope ? value.meta : undefined, value);
 	const enabled = config.enabled === true;
-	if (isMaterializedState(value.state)) {
-		if (!isJsonValue(value.state)) return migrationFailure(value, "Restored state contains non-JSON data");
-		if (containsNull(value.state)) return migrationFailure(value, "Restored state contains null data");
-		return migratedSnapshot(enabled, meta, structuredClone(value.state));
-	}
-	if (isLegacyThreePartState(value.state)) {
-		if (!isJsonValue(value.state)) return migrationFailure(value, "Restored state contains non-JSON data");
-		if (containsNull(value.state)) return migrationFailure(value, "Restored state contains null data");
-		return migratedSnapshot(enabled, meta, {
-			artifacts: {},
-			...structuredClone(value.state),
-		});
-	}
-	if (isLegacyTwoPartState(value.state)) {
-		if (!isJsonValue(value.state)) return migrationFailure(value, "Restored state contains non-JSON data");
-		if (containsNull(value.state)) return migrationFailure(value, "Restored state contains null data");
-		return migratedSnapshot(enabled, meta, {
-			artifacts: {},
-			contract: structuredClone(value.state.contract),
-			working: structuredClone(value.state.working),
-			response: "",
-		});
-	}
-	if (Object.hasOwn(value, "state")) {
-		if (isObject(value.state)
-			&& (Object.hasOwn(value.state, "response")
-				|| Object.hasOwn(value.state, "artifacts")
-				|| (Object.hasOwn(value.state, "contract") && Object.hasOwn(value.state, "working")))) {
-			return migrationFailure(value, "Restored state has an invalid materialized-state schema");
-		}
-		if (value.state !== undefined && !isObject(value.state)) {
-			return migrationFailure(value, "Restored state has an invalid materialized-state schema");
-		}
-	}
-	if (Object.hasOwn(value, "stateBasis") || Object.hasOwn(value, "previousStatePatch")) {
-		const legacyBasis = isObject(value.stateBasis)
-			? value.stateBasis
-			: isObject(value.state)
-				? value.state
-				: {};
-		const legacyPatch = isObject(value.previousStatePatch) ? value.previousStatePatch : undefined;
-		if (!isJsonValue(legacyBasis) || (legacyPatch !== undefined && !isJsonValue(legacyPatch))) {
-			return migrationFailure(value, "Legacy state contains non-JSON data");
-		}
-		const legacyState = legacyPatch === undefined ? legacyBasis : applyPatch(legacyBasis, legacyPatch);
-		if (containsNull(legacyState)) return migrationFailure(value, "Legacy state contains null data");
-		return migratedSnapshot(enabled, meta, {
-			artifacts: {}, contract: {}, working: structuredClone(legacyState), response: "",
-		});
-	}
+	if (Object.hasOwn(value, "state") || Object.hasOwn(value, "stateBasis") || Object.hasOwn(value, "previousStatePatch")) return envelope(false, meta);
 	return envelope(enabled, meta);
 }

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

@@ -6,7 +6,7 @@ import { closeSync, lstatSync, mkdirSync, openSync, rmSync, writeFileSync } from
 import { dirname, relative, resolve } from "node:path";
 import {
 	assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases,
-	serializeScopeProvenance, sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates,
+	serializeScopeMetadata, sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates,
 	type DurableFileBase, type OwnedFileUpdate,
 } from "./durable.ts";
 import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
@@ -84,22 +84,23 @@ export function planTemporalPublication(
 	for (const scope of SCOPES) {
 		const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
 		if (files.get(resolve(paths.directory, "state.json"))!.identity !== "missing") throw new Error("Legacy State Flow storage requires explicit migration");
-		const previous = parseScopeStream(files.get(paths.checkpoint)!.content, files.get(paths.patches)!.content, scope, scope === "cwd" ? cwd : undefined);
+		const previous = parseScopeStream(files.get(paths.checkpoint)!.content, files.get(paths.patches)!.content, scope,
+			scope === "cwd" ? cwd : undefined, files.get(paths.meta)!.content);
 		if (runtimeOnly || (previous !== undefined && sameJson(previous, view.scopes[scope]))) continue;
 		if (!scopes.includes(scope)) throw new Error(`Temporal scope update omitted a changed stream: ${scope}`);
 		changedScopes.push(scope);
 	}
 	const provenanceUpdates: OwnedFileUpdate[] = [];
-	// Shared provenance belongs to its semantic scopes, not the session config being saved.
-	if (!runtimeOnly && provenance !== undefined) {
+	// Shared metadata owns provenance, temporal boundaries, and CWD identity beside semantic files.
+	if (!runtimeOnly) {
 		for (const scope of ["global", "cwd"] as const) {
 			const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
-			const registry = provenance[scope];
+			const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta)!.content, paths.meta);
 			const currentFile = files.get(paths.meta)!;
-			if (Object.keys(registry).length === 0 && currentFile.identity === "missing") continue;
-			if (!sameJson(parseScopeProvenance(currentFile.content, paths.meta), registry)) {
-				provenanceUpdates.push({ path: paths.meta, content: serializeScopeProvenance(registry) });
-			}
+			if (!changedScopes.includes(scope)
+				&& (provenance === undefined || sameJson(parseScopeProvenance(currentFile.content, paths.meta), registry))) continue;
+			const content = serializeScopeMetadata(registry, view.scopes[scope], scope, scope === "cwd" ? cwd : undefined, currentFile.content);
+			if (currentFile.content !== content) provenanceUpdates.push({ path: paths.meta, content });
 		}
 	}
 	const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
@@ -107,11 +108,14 @@ export function planTemporalPublication(
 	if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined) throw new Error("Temporal semantic publication requires its session runtime cohort");
 	const runtimeUpdates: OwnedFileUpdate[] = [];
 	if (runtime !== undefined) {
-		const sources = serializeSessionRuntime(runtime, cwd, sessionId);
+		const sources = serializeSessionRuntime(runtime, cwd, sessionId, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta)!.content);
 		if (!sameJson(runtime.meta.lineage, view.lineage)) throw new Error("Runtime lineage does not match the temporal cohort");
-		if (previousRuntime === undefined || !sameJson(previousRuntime, runtime)) {
+		if (files.get(runtimePaths.config)!.content !== sources.config || files.get(runtimePaths.meta)!.content !== sources.meta) {
 			runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
 		}
+	} else if (!runtimeOnly && changedScopes.includes("session")) {
+		const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta)!.content);
+		if (files.get(runtimePaths.meta)!.content !== content) runtimeUpdates.push({ path: runtimePaths.meta, content });
 	}
 	const changedPaths = new Set(changedScopes.flatMap((scope) => {
 		const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
@@ -143,7 +147,8 @@ function decodeFileCohort(cwd: string, sessionId: string, root: string, base: Te
 	for (const scope of SCOPES) {
 		const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
 		if (files.get(resolve(paths.directory, "state.json")) !== undefined) throw new Error("Legacy State Flow storage requires explicit migration");
-		const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? cwd : undefined);
+		const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope,
+			scope === "cwd" ? cwd : undefined, files.get(paths.meta));
 		if (!stream) throw new Error("Incomplete file-only temporal scope cohort");
 		scopes[scope] = stream;
 	}

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

@@ -4,10 +4,14 @@
 // pi-telegram is absent or its registry is not ready, registration fails open and retries.
 
 export const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
-const SECTIONS_IMPORT_SPECIFIERS = [
-	"@llblab/pi-telegram/sections",
-	new URL("../../pi-telegram/api/sections.ts", import.meta.url).href,
-];
+
+/** Resolve the package export or the compiled sibling-extension layout used in local development. */
+export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url): string[] {
+	return [
+		"@llblab/pi-telegram/sections",
+		new URL("../../../pi-telegram/dist/api/sections.js", moduleUrl).href,
+	];
+}
 
 export interface StateFlowTelegramSnapshot {
 	enabled: boolean;
@@ -26,7 +30,7 @@ export interface StateFlowTelegramState {
 }
 
 export type StateFlowTelegramRichBlock =
-	| { type: "heading"; text: string; size: 2 }
+	| { type: "heading"; text: string; size: 3 }
 	| { type: "pre"; text: string; language?: string }
 	| { type: "details"; summary: string | { type: "bold" | "code"; text: string }; blocks: StateFlowTelegramRichBlock[]; is_open?: true };
 
@@ -177,11 +181,11 @@ function renderStateFlowTelegramField(value: unknown): string {
 	return rendered;
 }
 
-export function renderStateFlowRichState(scope: StateFlowTelegramScope, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
+export function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage {
 	const fields = ["artifacts", "contract", "working", "response"] as const;
 	return {
 		blocks: [
-			{ type: "heading", text: STATE_FLOW_SCOPE_LABELS[scope], size: 2 },
+			{ type: "heading", text: `${STATE_FLOW_SCOPE_LABELS[scope]}: \`#${step}\``, size: 3 },
 			...fields.map((field) => ({
 				type: "details" as const,
 				summary: { type: "code" as const, text: field },
@@ -215,7 +219,7 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort) {
 				}
 				if (ctx.action === "inspect") {
 					if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
-					await ctx.openRich(renderStateFlowRichState(ctx.payload, port.state(ctx.payload)));
+					await ctx.openRich(renderStateFlowRichState(ctx.payload, port.snapshot().step, port.state(ctx.payload)));
 					await ctx.answerCallback();
 					return "handled" as const;
 				}
@@ -259,7 +263,7 @@ async function importTelegramModule<TModule>(
 /** Default loader; injectable so tests and embedded hosts can control transport presence. */
 export async function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules> {
 	const sections = await importTelegramModule<StateFlowTelegramSectionModule>(
-		SECTIONS_IMPORT_SPECIFIERS,
+		stateFlowTelegramSectionSpecifiers(),
 		(module): module is StateFlowTelegramSectionModule =>
 			typeof (module as StateFlowTelegramSectionModule | undefined)?.registerTelegramSection === "function",
 	);

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

@@ -1,8 +1,8 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.11.2",
+  "version": "0.13.3",
   "private": false,
-  "description": "Incremental scoped state/context compiler for Pi, inspired by SKILL.state",
+  "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -20,6 +20,7 @@
   "files": [
     "index.ts",
     "lib",
+    "dist",
     "skills",
     "docs",
     "README.md",
@@ -28,18 +29,32 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "check": "node --experimental-strip-types -e \"await import('./index.ts')\"",
+    "check": "node -e \"await import('./dist/pi-state-flow/index.js'); console.log('pi-state-flow: extension import ok')\"",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "benchmark": "node --experimental-strip-types benchmarks/benchmark.ts",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run typecheck && npm test && npm run check",
-    "prepack": "npm run validate"
+    "build": "node scripts/build-dist.mjs",
+    "pack:check": "npm pack --dry-run",
+    "validate": "npm run build && npm run typecheck && npm test && npm run check && npm run pack:check",
+    "prepack": "npm run build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "pi": {
     "extensions": [
+      "./dist/pi-state-flow/index.js"
+    ],
+    "sourceExtensions": [
       "./index.ts"
     ],
     "skills": [
+      "./dist/skills"
+    ],
+    "sourceSkills": [
       "./skills"
     ],
     "image": "https://raw.githubusercontent.com/llblab/pi-state-flow/main/banner.jpg"
@@ -53,9 +68,11 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "^0.84.4 || ^0.85.1",
     "@earendil-works/pi-ai": "^0.84.4 || ^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.84.4 || ^0.85.1"
+    "@earendil-works/pi-coding-agent": "^0.84.4 || ^0.85.1",
+    "@earendil-works/pi-tui": "^0.84.4 || ^0.85.1"
   },
   "devDependencies": {
+    "@earendil-works/pi-tui": "0.84.4",
     "@types/node": "latest",
     "typescript": "latest"
   }

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

@@ -1,6 +1,6 @@
 ---
 name: state-flow-memory
-description: Audit and reconcile State Flow durable memory across global, CWD, and session scopes. Preserve commitments, established learning, and the point of continuation without freezing provisional approaches. Use for explicit memory curation, ownership migration, contradiction cleanup, stale continuation review, externally evidenced promotion, or a feature/release/project phase-boundary reconciliation required by the State Flow runtime contract; not for unrelated routine turns or background maintenance.
+description: Audit and reconcile State Flow durable memory across global, CWD, and session scopes. Preserve commitments, established learning, and the point of continuation without freezing provisional approaches. Use after completing a major feature, important release, large body of work, campaign, project phase, or meaningful checkpoint—even when the user did not explicitly ask for memory work—as well as for explicit memory curation, ownership migration, contradiction cleanup, stale continuation review, externally evidenced promotion, and active-version boundaries; not for unrelated routine turns or background maintenance.
 ---
 
 # State Flow Memory Curation
@@ -78,6 +78,8 @@ Do not erase a meaningful correction, uncertainty, commitment, negative result,
 
 ### Reconcile phase boundaries
 
+After a major feature, important release, large body of work, or meaningful checkpoint reaches completion or its final stage, proactively optimize the affected State Flow scopes. Distill implementation-specific detail into durable consequences, remove trajectory-bound scaffolding, and rebalance knowledge across global, CWD, and session ownership so the resulting state stays alive, reusable, and open to better future methods rather than preserving the shape of the finished effort.
+
 A completed feature, release, campaign, project switch, or active-version change is evidence that its working set needs one bounded review. Remove completed task lists, obsolete release/version state, run identifiers, timings, incident chronology, dead experiments, and stale continuation. Retain shipped status only when it remains a prerequisite, durable rule, open risk, or useful retrieval pointer.
 
 State branches may move as applicability changes. Global is limited to established cross-project, user, or environment knowledge; CWD owns reusable project truth; session owns branch/run continuation. Narrow project-specific global material into CWD, promote genuinely cross-project learning only when evidence supports the broader boundary, and move reusable session learning into CWD without carrying its transient run shell.