@llblab/pi-kit 0.37.0 → 0.38.0

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

@@ -3,12 +3,14 @@ import { lstatSync } from "node:fs";
 import { join } from "node:path";
 import { classifyScopeStream, hasCwdMaterialization, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths, type SessionAddress } from "./durable.ts";
 import { pruneArtifactProvenance, type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./artifact.ts";
-import { assertTemporalFileBase, captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction, type StorageTransaction, type TemporalFileBase } from "./storage.ts";
+import { assertTemporalFileBase, captureSelectedModuleAdditions, captureSelectedProvenanceUpdates, captureTemporalFileBase, temporalFileContents, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction, type StorageTransaction, type TemporalFileBase, type SelectedFilePublication, type SelectedOriginRequest, type SelectedSessionAcquisitionRequest, type SelectedForkCopyRequest, type SelectedFileCohort, type SelectedModuleAdditions, type SelectedProvenanceUpdates, type SelectedReadObservation } from "./storage.ts";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
-import { hashJson, sameJson } from "./json.ts";
-import { RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, preRuntimeCheckpoint, retainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot, type StateFlowMode } from "./snapshot.ts";
-import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type ScopedStates, type StateScope } from "./state.ts";
-import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalScopes, readTemporalState, readTemporalView, validateScopeLineage, type ScopeStream, type TemporalState } from "./temporal.ts";
+import { hashJson, isObject, sameJson } from "./json.ts";
+import { RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, preRuntimeCheckpoint, retainedBoundaryCheckpoint, captureLifecycleSnapshot, type RetainedPiCheckpoint, type SelectedRetainedPiCheckpoint, type Snapshot, type StateFlowMode, type PrivateAcquisition } from "./snapshot.ts";
+import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type ScopedStates, type ScopeStateValues, type StateScope } from "./state.ts";
+import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalScopes, readTemporalState, readTemporalView, selectTemporalState, validateScopeLineage, type ScopeStream, type TemporalState, type SelectedTemporalState } from "./temporal.ts";
+
+import { captureScopeSelection, type ScopeSelection } from "./selection.ts";
 
 const SCOPES = ["global", "cwd", "session"] as const;
 const SHARED_SCOPES = ["global", "cwd"] as const;
@@ -21,6 +23,42 @@ export interface RuntimePatchTransaction {
 	publish(snapshot: Snapshot, accepted?: AcceptedTransition, provenance?: Partial<Record<StateScope, Record<string, ArtifactProvenance>>>): RuntimePublication;
 }
 
+export interface SelectedRuntimePatchTransaction {
+	readonly selection: ScopeSelection;
+	readonly states: ScopeStateValues;
+	readonly modules?: SelectedModuleAdditions;
+	readonly snapshot: Snapshot;
+	readonly causalBasis: string;
+	readonly provenance: SelectedProvenanceUpdates;
+	publish(snapshot: Snapshot, accepted?: AcceptedTransition, provenance?: SelectedProvenanceUpdates, moduleAdditions?: SelectedModuleAdditions): SelectedFilePublication;
+}
+
+export interface SelectedLifecycleInspection {
+	readonly selection: ScopeSelection;
+	readonly privateAcquisition: PrivateAcquisition;
+	readonly snapshot: Snapshot;
+}
+
+function selectedModules(view: SelectedTemporalState): SelectedModuleAdditions {
+	return Object.fromEntries(view.selection.filter(scope => view.scopes[scope]?.modules !== undefined)
+		.map(scope => [scope, structuredClone(view.scopes[scope]!.modules!)]));
+}
+
+function selectedRunSnapshot(cohort: Pick<SelectedFileCohort, "lifecycle">): Snapshot {
+	const source = cohort.lifecycle.runtime;
+	const meta = { step: source.meta.step, ...Object.fromEntries(["specification", "bootstrap", "validation"]
+		.filter((key) => Object.hasOwn(source.meta, key)).map((key) => [key, source.meta[key]])) };
+	return captureLifecycleSnapshot({ config: { mode: source.config.mode }, meta });
+}
+
+/** Detached replay inputs; excluded patch bodies must not be touched even for a rejected raw replay. */
+function captureSelectedReplay(accepted: AcceptedTransition | undefined, selection: ScopeSelection): AcceptedTransition | undefined {
+	if (accepted === undefined) return undefined;
+	if (!isObject(accepted) || !Array.isArray(accepted.transitions)) throw new Error("Invalid selected runtime replay");
+	for (const item of accepted.transitions) if (!isObject(item) || !selection.includes(item.scope as StateScope)) throw new Error("Selected runtime replay contains an excluded owner");
+	return structuredClone(accepted);
+}
+
 type PublicationSelection =
 	| { kind: "patch" | "lifecycle" }
 	| { kind: "start"; allowCreateOrigin: boolean }
@@ -78,10 +116,22 @@ function freshEmptyScopeStream(scope: StateScope, origin: string, historyLimit:
 
 /** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
 export class TemporalRuntime {
-	view: TemporalState | undefined;
+	private memory: { kind: "legacy"; view: TemporalState } | { kind: "selected"; cohort: SelectedFileCohort }
+		| { kind: "observed"; observation: SelectedReadObservation } | undefined;
+	/** Compatibility access to the legacy cache only; selected memory never masquerades as three owners. */
+	get view(): TemporalState | undefined { return this.memory?.kind === "legacy" ? this.memory.view : undefined; }
+	set view(value: TemporalState | undefined) {
+		if (value !== undefined) this.assertLegacyAdmission();
+		this.memory = value === undefined ? undefined : { kind: "legacy", view: value };
+	}
 	private base: TemporalFileBase | undefined;
 	private semanticRevision: string | undefined;
 	private savedRuntime: string | undefined;
+	/** Backend choice survives cache clearing but grants no origin, private acquisition or publication authority. */
+	private selectedBackendChosen = false;
+	private selectedOriginAccepted = false;
+	private observedSessionAuthority = false;
+	private observedPrivateSemantics = false;
 	private transaction: StorageTransaction | undefined;
 	private provenanceByScope: Record<StateScope, ArtifactProvenanceRegistry> = emptyProvenance();
 	/** Shared scopes whose wholly absent live basis was accepted after one stale-target refusal. */
@@ -101,19 +151,201 @@ export class TemporalRuntime {
 	get sessionId(): string { return this.session.id; }
 	get sessionKey(): string { return this.session.key; }
 
+	private rememberSessionAuthority(base: TemporalFileBase | undefined): void {
+		const privatePaths = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
+		const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
+		const privateFiles = new Set([privatePaths.checkpoint, privatePaths.patches, privatePaths.meta]);
+		for (const file of base?.files ?? []) if (file.identity !== "missing") {
+			if (privateFiles.has(file.path)) this.observedPrivateSemantics = true;
+			if (privateFiles.has(file.path) || file.path === paths.config || file.path === paths.runtime) this.observedSessionAuthority = true;
+		}
+	}
+
+	private assertLegacyAdmission(): void {
+		if (this.selectedBackendChosen) throw new Error("Selected State Flow memory requires selected runtime operations");
+	}
+
+	/** Only owned durable acceptance calls this; returned receipts and read-only candidates are not installers. */
+	private installSelected(cohort: SelectedFileCohort): void {
+		this.memory = { kind: "selected", cohort: structuredClone(cohort) };
+		this.selectedBackendChosen = true;
+		this.clearLegacyBasis();
+	}
+
+	private clearLegacyBasis(): void {
+		this.base = undefined;
+		this.savedRuntime = undefined;
+		this.semanticRevision = undefined;
+		this.provenanceByScope = emptyProvenance();
+		this.absentSharedScopes.clear();
+	}
+
+	private installObserved(observation: SelectedReadObservation): void {
+		this.memory = { kind: "observed", observation: structuredClone(observation) };
+		this.selectedBackendChosen = true;
+		this.clearLegacyBasis();
+	}
+
+	private observationGuard(revalidateNativePolicy: () => void, signal?: AbortSignal): () => void {
+		const memory = this.memory;
+		return () => {
+			signal?.throwIfAborted();
+			if (this.selectedOriginAccepted || this.semanticRevision || this.savedRuntime) throw new Error("Accepted State Flow memory requires current acceptance, not observation");
+			if (this.memory !== memory) throw new Error("Selected State Flow runtime selection or acceptance changed concurrently");
+			if (typeof revalidateNativePolicy !== "function") throw new Error("Selected observation requires independent native policy authority");
+			revalidateNativePolicy();
+		};
+	}
+
+	private selectedReadCache(): Pick<SelectedReadObservation, "view" | "provenance"> | undefined {
+		if (this.memory?.kind === "selected") return this.memory.cohort;
+		if (this.memory?.kind === "observed") return this.memory.observation;
+		return undefined;
+	}
+
+	/** Detached read-only selected values; never accepted run fields or a publication/acquisition basis. */
+	observedSelectedView(): SelectedTemporalState | undefined {
+		return this.memory?.kind === "observed" ? structuredClone(this.memory.observation.view) : undefined;
+	}
+
+	/** Explicit shared inspection before acquisition; missing owners stay unavailable rather than becoming empty streams. */
+	async refreshSelectedShared(selection: ScopeSelection, revalidateNativePolicy: () => void, signal?: AbortSignal): Promise<boolean> {
+		const wanted = captureScopeSelection(selection);
+		if (wanted.includes("session")) throw new Error("Shared State Flow observation cannot select Session");
+		const assertAuthority = this.observationGuard(revalidateNativePolicy, signal);
+		const install = (observation: SelectedReadObservation): boolean => {
+			assertAuthority();
+			this.installObserved(observation);
+			return observation.view !== undefined;
+		};
+		assertAuthority();
+		if (!lstatSync(this.root, { throwIfNoEntry: false })) return install({ selection: wanted, provenance: {} });
+		return withStorageTransaction(this.root, storage => {
+			assertAuthority();
+			return install(storage.observeSelectedShared(this.cwd, wanted, this.root));
+		}, signal);
+	}
+
+	/** Header-only disposition data; never semantic observation, acceptance, or acquisition permission. */
+	async inspectSelectedLifecycle(selection: ScopeSelection, revalidateNativePolicy: () => void, signal?: AbortSignal): Promise<SelectedLifecycleInspection | undefined> {
+		const wanted = captureScopeSelection(selection);
+		const memory = this.memory;
+		const check = () => {
+			signal?.throwIfAborted();
+			if (this.memory !== memory) throw new Error("State Flow attachment selection changed");
+			revalidateNativePolicy();
+		};
+		check();
+		if (!lstatSync(this.root, { throwIfNoEntry: false })) {
+			if (this.observedSessionAuthority) throw new RevisionUnavailableError("Known selected session authority is unavailable");
+			return undefined;
+		}
+		return withStorageTransaction(this.root, storage => {
+			check();
+			const lifecycle = storage.inspectSelectedLifecycle(this.cwd, this.sessionId, wanted, this.root, this.sessionKey);
+			check();
+			if (!lifecycle) {
+				if (this.observedSessionAuthority) throw new RevisionUnavailableError("Known selected session authority is unavailable");
+				return undefined;
+			}
+			if (this.observedPrivateSemantics && lifecycle.runtime.meta.privateAcquisition !== "acquired") throw new Error("Known acquired State Flow private authority cannot be downgraded");
+			this.observedSessionAuthority = true;
+			if (lifecycle.runtime.meta.privateAcquisition === "acquired") this.observedPrivateSemantics = true;
+			return { selection: captureScopeSelection(lifecycle.runtime.config.scopes), privateAcquisition: lifecycle.runtime.meta.privateAcquisition,
+				snapshot: selectedRunSnapshot({ lifecycle }) };
+		}, signal);
+	}
+
+	/** Native bookmarks never decide whether current canonical authority exists. */
+	async hasSelectedCurrentAuthority(selection: ScopeSelection, revalidateNativePolicy: () => void, signal?: AbortSignal): Promise<boolean> {
+		return await this.inspectSelectedLifecycle(selection, revalidateNativePolicy, signal) !== undefined;
+	}
+
+	/** Fenced inactive restoration/operator inspection: source proof only, without conversion or durable acceptance. */
+	async refreshSelectedCurrent(selection: ScopeSelection, revalidateNativePolicy: () => void, signal?: AbortSignal): Promise<Snapshot> {
+		const wanted = captureScopeSelection(selection);
+		const assertAuthority = this.observationGuard(revalidateNativePolicy, signal);
+		assertAuthority();
+		if (!lstatSync(this.root, { throwIfNoEntry: false })) throw new RevisionUnavailableError("Selected current session storage is unavailable");
+		return withStorageTransaction(this.root, storage => {
+			assertAuthority();
+			const current = storage.prepareSelectedCurrent(this.cwd, this.sessionId, wanted, this.historyLimit, this.root, this.sessionKey);
+			if (this.observedPrivateSemantics && current.lifecycle.runtime.meta.privateAcquisition !== "acquired") throw new Error("Known acquired State Flow private authority cannot be downgraded");
+			// Current acceptance can plan absent shared owners; observation must not expose those planned empty streams.
+			const present = wanted.filter(scope => {
+				const path = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).checkpoint;
+				return current.basis.files.some(file => file.path === path && file.identity !== "missing");
+			});
+			const observation: SelectedReadObservation = { selection: wanted,
+				provenance: Object.fromEntries(present.map(scope => [scope, current.provenance[scope]!])),
+				...(present.length === 0 ? {} : { view: selectTemporalState(current.view, captureScopeSelection(present), this.historyLimit) }),
+			};
+			const snapshot = selectedRunSnapshot(current);
+			assertAuthority();
+			this.rememberSessionAuthority(current.basis);
+			if (current.lifecycle.runtime.meta.privateAcquisition === "acquired") this.observedPrivateSemantics = true;
+			this.installObserved(observation);
+			return snapshot;
+		}, signal);
+	}
+
+	/** Detached accepted selected values only, never a file receipt or publication capability. */
+	selectedView(): SelectedTemporalState | undefined {
+		return this.memory?.kind === "selected" ? structuredClone(this.memory.cohort.view) : undefined;
+	}
+
+	/** Accepted run fields only; local policy and pending native prompts remain the adapter's responsibility. */
+	selectedSnapshot(): Snapshot {
+		if (this.memory?.kind !== "selected") throw new Error("Selected State Flow runtime is unavailable");
+		return selectedRunSnapshot(this.memory.cohort);
+	}
+
+	/** Native bookkeeping may change mode, never invent accepted run fields or a semantic boundary. */
+	retainedSelectedCheckpoint(mode?: StateFlowMode): SelectedRetainedPiCheckpoint {
+		const memory = this.memory;
+		if (memory?.kind !== "selected") throw new Error("Selected State Flow runtime is unavailable");
+		const snapshot = selectedRunSnapshot(memory.cohort);
+		if (mode !== undefined) snapshot.config.mode = mode;
+		return { ...retainedBoundaryCheckpoint(snapshot, memory.cohort.view.lineage.at(-1)!.id), version: 2, scopes: captureScopeSelection(memory.cohort.view.selection) };
+	}
+
+	/** Read-only cache identity lease; no source acquisition, storage receipt or publication authority. */
+	captureSelectedReadBasis(): () => void {
+		const memory = this.memory;
+		if (!this.selectedReadCache()?.view) throw new Error("Selected State Flow runtime is unavailable");
+		return () => { if (this.memory !== memory) throw new Error("State Flow module context content basis changed"); };
+	}
+
+	/** Exact present owners for the existing selected staging engine; no defaulted disabled scopes. */
+	selectedStates(offset = 0): { selection: ScopeSelection; states: ScopeStateValues } {
+		const view = this.selectedReadCache()?.view;
+		if (!view) throw new Error("Selected State Flow runtime is unavailable");
+		return { selection: captureScopeSelection(view.selection), states: readTemporalScopes(view, offset, this.historyLimit) };
+	}
+
 	/** Runtime-owned artifact compilation evidence for one scope; never model-visible state. */
 	artifactProvenance(scope: StateScope): ArtifactProvenanceRegistry {
+		const selected = this.selectedReadCache();
+		if (selected) {
+			if (!selected.view) throw new Error(`State Flow ${scope} scope is excluded or unavailable`);
+			if (!selected.view.selection.includes(scope)) throw new Error(`State Flow ${scope} scope is excluded`);
+			return structuredClone(selected.provenance[scope]!);
+		}
+		this.assertLegacyAdmission();
 		return structuredClone(this.provenanceByScope[scope]);
 	}
 
 	/** Read canonical shared memory without creating, migrating, or publishing storage. */
 	loadPassive(): boolean {
+		this.assertLegacyAdmission();
 		if (!lstatSync(this.root, { throwIfNoEntry: false })) return false;
 		return this.loadPassiveBase(captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey));
 	}
 
 	private loadPassiveBase(base: TemporalFileBase): boolean {
-		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		this.rememberSessionAuthority(this.base);
+		this.rememberSessionAuthority(base);
+		const files = temporalFileContents(base);
 		const shared = Object.fromEntries(SHARED_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,
@@ -150,26 +382,31 @@ export class TemporalRuntime {
 
 
 	read(offset = 0, scope?: StateScope): MaterializedState {
-		if (!this.view) throw new Error("State Flow temporal runtime is unavailable");
-		return readTemporalState(this.view, offset, scope, this.historyLimit);
+		const view = this.selectedReadCache()?.view ?? this.view;
+		if (!view) throw new Error("State Flow temporal runtime is unavailable");
+		return readTemporalState(view, offset, scope, this.historyLimit);
 	}
 
 	readView(offset = 0, scope?: StateScope): SemanticState {
-		if (!this.view) throw new Error("State Flow temporal runtime is unavailable");
-		return readTemporalView(this.view, offset, scope, this.historyLimit);
+		const view = this.selectedReadCache()?.view ?? this.view;
+		if (!view) throw new Error("State Flow temporal runtime is unavailable");
+		return readTemporalView(view, offset, scope, this.historyLimit);
 	}
 
 	states(): ScopedStates {
+		this.assertLegacyAdmission();
 		return { global: this.read(0, "global"), cwd: this.read(0, "cwd"), session: this.read(0, "session") };
 	}
 
 	causalBasis(): string {
-		if (!this.view) throw new Error("State Flow temporal runtime is unavailable");
-		return this.view.lineage.at(-1)!.id;
+		const view = this.selectedReadCache()?.view ?? this.view;
+		if (!view) throw new Error("State Flow temporal runtime is unavailable");
+		return view.lineage.at(-1)!.id;
 	}
 
 	/** Encode Pi lifecycle state against the current retained semantic boundary. */
 	retainedCheckpoint(snapshot: Snapshot): RetainedPiCheckpoint {
+		this.assertLegacyAdmission();
 		if (!this.view) return preRuntimeCheckpoint(snapshot.config.mode);
 		return retainedBoundaryCheckpoint(snapshot, this.causalBasis());
 	}
@@ -180,9 +417,11 @@ export class TemporalRuntime {
 
 	recent(): RecentTransitionWindow {
 		const result: RecentTransitionWindow = [];
-		for (const boundary of this.view?.lineage.slice(1) ?? []) {
-			const transitions = SCOPES.flatMap((scope) => {
-				const record = this.view!.scopes[scope].patches.find(({ transition }) => transition.id === boundary.id);
+		const selected = this.selectedReadCache()?.view;
+		const view = selected ?? this.view;
+		for (const boundary of view?.lineage.slice(1) ?? []) {
+			const transitions = (selected?.selection ?? SCOPES).flatMap((scope) => {
+				const record = view!.scopes[scope]!.patches.find(({ transition }) => transition.id === boundary.id);
 				return record ? [{ scope, patch: structuredClone(record.patch) }] : [];
 			});
 			if (transitions.length) result.push({ id: boundary.id, at: boundary.position, transitions });
@@ -193,6 +432,7 @@ export class TemporalRuntime {
 	/** Await a coherent read-only recovery view; this neither activates policy nor accepts publication authority. */
 	async refreshCurrentMemory(signal?: AbortSignal): Promise<Snapshot | undefined> {
 		signal?.throwIfAborted();
+		this.assertLegacyAdmission();
 		if (!lstatSync(this.root, { throwIfNoEntry: false })) return undefined;
 		return withStorageTransaction(this.root, (storage) => {
 			const base = storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
@@ -202,10 +442,11 @@ export class TemporalRuntime {
 	}
 
 	private loadCurrentMemoryBase(base: TemporalFileBase): Snapshot | undefined {
-		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		const files = temporalFileContents(base);
 		const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
 		if ([paths.config, paths.runtime, session.checkpoint, session.patches, session.meta].every((path) => files.get(path) === undefined)) return undefined;
+		this.rememberSessionAuthority(base);
 		const document = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), this.cwd, this.sessionId);
 		if (!document) throw new RevisionUnavailableError("Current State Flow session runtime is unavailable");
 		const origin = `start:${randomUUID()}`;
@@ -252,12 +493,13 @@ export class TemporalRuntime {
 		newSessionOrigin?: boolean;
 		copy?: SessionCopy;
 	}): RuntimePublication | undefined {
+		if (this.selectedBackendChosen) throw new Error("Selected State Flow origin requires selected runtime integration");
 		const { allowCreateCwd, expectedShared, newSessionOrigin = false, copy } = options;
 		const hasCwd = hasCwdMaterialization(this.cwd, this.root);
 		if (!allowCreateCwd && !hasCwd) return undefined;
 		if (!copy && allowCreateCwd) initializeFileStore(this.root);
 		const base = captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
-		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		const files = temporalFileContents(base);
 		if (copy) {
 			const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
 			const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "runtime.json"), join(session.directory, "state.json")];
@@ -399,6 +641,7 @@ export class TemporalRuntime {
 	/** Await coherent shared inspection, lazily loading an empty private view only when none is selected. */
 	async refreshShared(signal?: AbortSignal): Promise<boolean> {
 		signal?.throwIfAborted();
+		this.assertLegacyAdmission();
 		if (!this.view && !lstatSync(this.root, { throwIfNoEntry: false })) return false;
 		return withStorageTransaction(this.root, (storage) => {
 			const current = storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
@@ -428,7 +671,7 @@ export class TemporalRuntime {
 			candidate.provenanceByScope = reconciled.provenance;
 			return candidate;
 		}
-		const files = new Map(current.files.map((file) => [file.path, file.content]));
+		const files = temporalFileContents(current);
 		const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
 		if ([paths.config, paths.runtime, session.checkpoint, session.patches, session.meta].some((path) => files.get(path) !== undefined)) {
@@ -464,11 +707,314 @@ export class TemporalRuntime {
 		}), { kind: "patch" }, signal);
 	}
 
+	/** Authored under exclusion against validated live selected values; use the existing selected staging/commit engine. */
+	async withSelectedPatchTransaction<T>(
+		action: (transaction: SelectedRuntimePatchTransaction) => T, revalidateNativePolicy: () => void, signal?: AbortSignal, capturedTargets: readonly StateScope[] = [],
+	): Promise<T> {
+		return this.withSelectedPublicationTransaction(action, "current", revalidateNativePolicy, signal, capturedTargets);
+	}
+
+	/** Mode-only Passive persistence: exact accepted sources, no current-origin adoption or caller-authored run fields. */
+	async persistSelectedPassive(revalidateNativePolicy: () => void, signal?: AbortSignal): Promise<SelectedFilePublication> {
+		const memory = this.memory;
+		if (memory?.kind !== "selected") throw new Error("Selected State Flow runtime is unavailable");
+		const assertAuthority = (): void => {
+			signal?.throwIfAborted();
+			if (this.memory !== memory) throw new Error("Selected State Flow runtime selection or acceptance changed concurrently");
+			if (typeof revalidateNativePolicy !== "function") throw new Error("Selected Passive persistence requires independent native policy authority");
+			revalidateNativePolicy();
+		};
+		assertAuthority();
+		return withStorageTransaction(this.root, storage => {
+			assertAuthority();
+			const publication = storage.persistSelectedPassive(this.cwd, this.sessionId, memory.cohort, this.root, this.sessionKey);
+			if (publication.changed) this.installSelected(publication.cohort);
+			return publication;
+		}, signal);
+	}
+
+	/** Precomputed replay remains tied to its accepted cache; changed selected shared targets conflict before publication. */
+	async publishSelected(
+		snapshot: Snapshot, accepted: AcceptedTransition | undefined, revalidateNativePolicy: () => void,
+		options: { provenance?: SelectedProvenanceUpdates; moduleAdditions?: SelectedModuleAdditions; signal?: AbortSignal } = {},
+	): Promise<SelectedFilePublication> {
+		if (this.memory?.kind !== "selected") throw new Error("Selected State Flow runtime is unavailable");
+		const provenance = captureSelectedProvenanceUpdates(options.provenance, this.memory.cohort.view.selection);
+		const replay = captureSelectedReplay(accepted, this.memory.cohort.view.selection);
+		const additions = captureSelectedModuleAdditions(options.moduleAdditions, this.memory.cohort.view.selection);
+		const lifecycle = captureLifecycleSnapshot(snapshot);
+		return this.withSelectedPublicationTransaction(transaction => transaction.publish(lifecycle, replay, provenance, additions), "replay", revalidateNativePolicy, options.signal);
+	}
+
+	private async withSelectedPublicationTransaction<T>(
+		action: (transaction: SelectedRuntimePatchTransaction) => T, kind: "current" | "replay",
+		revalidateNativePolicy: () => void, signal?: AbortSignal, capturedTargets: readonly StateScope[] = [],
+	): Promise<T> {
+		const memory = this.memory;
+		if (memory?.kind !== "selected") throw new Error("Selected State Flow runtime is unavailable");
+		const selection = captureScopeSelection(memory.cohort.view.selection);
+		const targets = capturedTargets.length ? captureScopeSelection(capturedTargets) : undefined;
+		if (targets?.some(scope => !selection.includes(scope))) throw new Error("Captured State Flow write target is excluded");
+		const assertAuthority = (): void => {
+			signal?.throwIfAborted();
+			if (this.memory !== memory) throw new Error("Selected State Flow runtime selection or acceptance changed concurrently");
+			if (typeof revalidateNativePolicy !== "function") throw new Error("Selected semantic transaction requires independent native policy authority");
+			revalidateNativePolicy();
+		};
+		assertAuthority();
+		return withStorageTransaction(this.root, storage => {
+			assertAuthority();
+			const current = storage.prepareSelectedCurrent(this.cwd, this.sessionId, selection, this.historyLimit, this.root, this.sessionKey);
+			const sharedPaths = new Set(selection.filter(scope => scope !== "session").flatMap(scope => {
+				const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+				return [paths.checkpoint, paths.patches, paths.meta];
+			}));
+			assertTemporalFileBase({ files: memory.cohort.basis.files.filter(file => !sharedPaths.has(file.path)) },
+				{ files: current.basis.files.filter(file => !sharedPaths.has(file.path)) });
+			if (!sameJson(memory.cohort.presence, current.presence)) throw new Error("Selected State Flow presence dependencies changed concurrently");
+			if (targets) this.assertSelectedReplayTargets(memory.cohort, current, undefined, undefined, undefined, targets);
+			let consumed = false;
+			let published = false;
+			const result = action(Object.freeze<SelectedRuntimePatchTransaction>({
+				selection, states: readTemporalScopes(current.view, 0, this.historyLimit), modules: selectedModules(current.view), snapshot: selectedRunSnapshot(current),
+				causalBasis: current.view.lineage.at(-1)!.id, provenance: structuredClone(current.provenance),
+				publish: (snapshot, accepted, requestedProvenance, requestedModules) => {
+					if (consumed) throw new Error("Selected semantic transaction publication was already consumed");
+					consumed = true;
+					assertAuthority();
+					const provenance = captureSelectedProvenanceUpdates(requestedProvenance, selection);
+					const transition = captureSelectedReplay(accepted, selection);
+					const moduleAdditions = captureSelectedModuleAdditions(requestedModules, selection);
+					if (kind === "replay") this.assertSelectedReplayTargets(memory.cohort, current, transition, provenance, moduleAdditions);
+					const publication = storage.acceptSelectedCurrent(this.cwd, this.sessionId,
+						{ selection, historyLimit: this.historyLimit, lifecycle: captureLifecycleSnapshot(snapshot), transition, provenance, moduleAdditions }, current, this.root, this.sessionKey);
+					this.installSelected(publication.cohort);
+					published = true;
+					return publication;
+				},
+			}));
+			if (!published) throw new Error("Selected semantic transaction requires one synchronous publication");
+			return result;
+		}, signal);
+	}
+
+	private assertSelectedReplayTargets(
+		base: SelectedFileCohort, current: SelectedFileCohort, transition?: AcceptedTransition, provenance?: SelectedProvenanceUpdates, additions?: SelectedModuleAdditions, capturedTargets: readonly StateScope[] = [],
+	): void {
+		const targets = new Set([...capturedTargets, ...(transition?.transitions.map(item => item.scope) ?? []), ...Object.keys(provenance ?? {}) as StateScope[], ...Object.keys(additions ?? {}) as StateScope[]]);
+		const files = temporalFileContents(current.basis);
+		const changed: StateScope[] = [], removed: StateScope[] = [];
+		for (const scope of base.view.selection.filter(scope => scope !== "session" && targets.has(scope))) {
+			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+			const live = classifyScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta));
+			if (live.kind === "absent") { removed.push(scope); continue; }
+			if (!sameJson(live.stream, base.view.scopes[scope]) || !sameJson(current.provenance[scope], base.provenance[scope])) changed.push(scope);
+		}
+		if (removed.length > 0) throw removedTargetScopeConflict(removed);
+		if (changed.length > 0) throw targetScopeConflict(changed);
+	}
+
 	/** Activate current owned memory; the caller must authorize a wholly absent private origin after waiting. */
 	async withStartTransaction<T>(action: (current: Snapshot | undefined, publish: (snapshot: Snapshot) => RuntimePublication) => T, signal?: AbortSignal, allowCreateOrigin = false): Promise<T> {
 		return this.withPublicationTransaction((_candidate, publish, current) => action(current, (snapshot) => publish(snapshot)), { kind: "start", allowCreateOrigin }, signal);
 	}
 
+	/** New-session shared-only acceptance; caller rechecks native origin authority after waiting. */
+	async withSelectedSharedOriginTransaction<T>(
+		selection: ScopeSelection, snapshot: Snapshot, action: (publish: () => SelectedFilePublication) => T,
+		signal?: AbortSignal, allowCreateOrigin = false,
+	): Promise<T> {
+		return this.withSelectedOriginAcceptance({ kind: "shared-new", selection, snapshot, historyLimit: this.historyLimit }, action, signal, allowCreateOrigin);
+	}
+
+	/** Child-owned deferred marker only; no parent locator or parent memory is acquired here. */
+	async withSelectedDeferredForkTransaction<T>(
+		selection: ScopeSelection, lifecycle: ForkLifecycle, action: (publish: () => SelectedFilePublication) => T,
+		signal?: AbortSignal, allowDeferFork = false, modeAtPublication?: () => StateFlowMode,
+	): Promise<T> {
+		if (!lifecycle || Object.keys(lifecycle).some((key) => key !== "mode" && key !== "bootstrap")
+			|| (lifecycle.bootstrap !== undefined && lifecycle.bootstrap !== true)) throw new Error("Invalid selected fork lifecycle");
+		if (modeAtPublication !== undefined && typeof modeAtPublication !== "function") throw new Error("Invalid selected fork mode sampler");
+		const snapshot: Snapshot = { config: { mode: lifecycle.mode }, meta: { step: 0, ...(lifecycle.bootstrap ? { bootstrap: true } : {}) } };
+		// Sample mode only; callers cannot replace the fresh child run fields through this hook.
+		const author: SelectedOriginRequest["author"] = modeAtPublication ? (basis, publish) => {
+			const mode = modeAtPublication();
+			signal?.throwIfAborted();
+			publish({ config: { mode }, meta: basis.snapshot.meta });
+		} : undefined;
+		return this.withSelectedOriginAcceptance({ kind: "shared-deferred", selection, snapshot, historyLimit: this.historyLimit, author }, action, signal, allowDeferFork);
+	}
+
+	/** Explicit first private acquisition, never deferred-parent recovery or repair of lost acquired state. */
+	async withSelectedSessionAcquisitionTransaction<T>(
+		request: SelectedSessionAcquisitionRequest, action: (publish: () => SelectedFilePublication) => T,
+		signal?: AbortSignal, allowAcquirePrivate = false,
+	): Promise<T> {
+		return this.withSelectedOriginAcceptance(request, action, signal, allowAcquirePrivate);
+	}
+
+	/** Stage first lifecycle/semantic authoring into one origin acceptance, never an empty publication followed by a patch. */
+	async withSelectedFirstPatchTransaction<T>(
+		selection: ScopeSelection, snapshot: Snapshot, action: (transaction: SelectedRuntimePatchTransaction) => T,
+		revalidateNativePolicy: () => void, signal?: AbortSignal, allowCreateOrigin = false,
+	): Promise<T> {
+		const memory = this.memory;
+		const check = () => {
+			signal?.throwIfAborted();
+			if (!allowCreateOrigin) throw new Error("Selected first authoring requires explicit native origin authority");
+			if (this.memory !== memory) throw new Error("Selected first authoring selection changed concurrently");
+			revalidateNativePolicy();
+		};
+		check();
+		const wanted = captureScopeSelection(selection);
+		let result: T;
+		const author: NonNullable<SelectedOriginRequest["author"]> = (basis, publish) => {
+			check();
+			result = action(Object.freeze<SelectedRuntimePatchTransaction>({
+				selection: captureScopeSelection(basis.view.selection), states: readTemporalScopes(basis.view, 0, this.historyLimit), modules: selectedModules(basis.view),
+				snapshot: basis.snapshot, causalBasis: basis.view.lineage.at(-1)!.id, provenance: basis.provenance,
+				publish: (next, transition, provenance, moduleAdditions) => {
+					check();
+					return publish(next, transition, provenance, captureSelectedModuleAdditions(moduleAdditions, wanted));
+				},
+			}));
+		};
+		await this.withSelectedOriginAcceptance({ kind: wanted.includes("session") ? "new" : "shared-new", selection: wanted, snapshot, historyLimit: this.historyLimit, author },
+			publish => { check(); publish(); }, signal, allowCreateOrigin);
+		return result!;
+	}
+
+	/** Same-session current acceptance/authoring; native policy checks are synchronous under exclusion. */
+	async withSelectedCurrentTransaction<T>(
+		selection: ScopeSelection, action: (current: Snapshot,
+			publish: (snapshot?: Snapshot) => SelectedFilePublication,
+			transaction: SelectedRuntimePatchTransaction) => T,
+		revalidateNativePolicy: () => void, signal?: AbortSignal,
+	): Promise<T> {
+		const wanted = captureScopeSelection(selection);
+		const historyLimit = this.historyLimit;
+		const assertAuthority = (): void => {
+			signal?.throwIfAborted();
+			if (typeof revalidateNativePolicy !== "function") throw new Error("Selected current acceptance requires independent native policy authority");
+			if (historyLimit !== this.historyLimit) throw new Error("Selected current history policy changed concurrently");
+			revalidateNativePolicy();
+		};
+		assertAuthority();
+		if (!lstatSync(this.root, { throwIfNoEntry: false })) throw new RevisionUnavailableError("Selected current session storage is unavailable");
+		return withStorageTransaction(this.root, (storage) => {
+			assertAuthority();
+			const base = storage.prepareSelectedCurrent(this.cwd, this.sessionId, wanted, historyLimit, this.root, this.sessionKey);
+			this.rememberSessionAuthority(base.basis);
+			if (this.observedPrivateSemantics && base.lifecycle.runtime.meta.privateAcquisition !== "acquired") throw new Error("Known acquired State Flow private authority cannot be downgraded");
+			this.observedSessionAuthority = true;
+			if (base.lifecycle.runtime.meta.privateAcquisition === "acquired") this.observedPrivateSemantics = true;
+			const current = selectedRunSnapshot(base);
+			let consumed = false, published = false, authorActive = true;
+			const publish = (snapshot?: Snapshot, accepted?: AcceptedTransition, requestedProvenance?: SelectedProvenanceUpdates, requestedModules?: SelectedModuleAdditions): SelectedFilePublication => {
+				if (!authorActive) throw new Error("Selected current authoring has ended");
+				if (consumed) throw new Error("Selected current acceptance publication was already consumed");
+				consumed = true;
+				assertAuthority();
+				const lifecycle = snapshot === undefined ? undefined : captureLifecycleSnapshot(snapshot);
+				const transition = captureSelectedReplay(accepted, wanted);
+				const provenance = captureSelectedProvenanceUpdates(requestedProvenance, wanted);
+				const moduleAdditions = captureSelectedModuleAdditions(requestedModules, wanted);
+				const publication = storage.acceptSelectedCurrent(this.cwd, this.sessionId, { selection: wanted, historyLimit, lifecycle, transition, provenance, moduleAdditions }, base, this.root, this.sessionKey);
+				this.selectedOriginAccepted = true;
+				this.installSelected(publication.cohort);
+				published = true;
+				return publication;
+			};
+			try {
+				const result = action(current, snapshot => publish(snapshot), Object.freeze<SelectedRuntimePatchTransaction>({
+					selection: wanted, states: readTemporalScopes(base.view, 0, historyLimit), modules: selectedModules(base.view), snapshot: structuredClone(current),
+					causalBasis: base.view.lineage.at(-1)!.id, provenance: structuredClone(base.provenance), publish,
+				}));
+				if (!published) throw new Error("Selected current acceptance requires one synchronous publication");
+				return result;
+			} finally { authorActive = false; }
+		}, signal);
+	}
+
+	/** Prepare may read persisted native identity outside exclusion; recheck must use in-memory native policy only. */
+	async withSelectedForkCopyTransaction<T>(
+		request: SelectedForkCopyRequest, action: (publish: () => SelectedFilePublication) => T,
+		revalidateDirectParent: (source: Readonly<SessionAddress>, phase: "prepare" | "recheck") => void, signal?: AbortSignal,
+	): Promise<T> {
+		return this.withSelectedOriginAcceptance(request, action, signal, true, revalidateDirectParent);
+	}
+
+	private async withSelectedOriginAcceptance<T>(
+		request: SelectedSessionAcquisitionRequest | SelectedForkCopyRequest | (SelectedOriginRequest & { kind: "shared-new" | "shared-deferred" }),
+		action: (publish: () => SelectedFilePublication) => T, signal: AbortSignal | undefined, allowed: boolean,
+		revalidateDirectParent?: (source: Readonly<SessionAddress>, phase: "prepare" | "recheck") => void,
+	): Promise<T> {
+		if (!["shared-new", "shared-deferred", "new", "unacquired", "fork-new", "fork-deferred"].includes(request.kind)) throw new Error("Invalid selected origin admission kind");
+		const kind = request.kind;
+		const historyLimit = request.historyLimit;
+		const wanted = captureScopeSelection(request.selection);
+		const lifecycle = captureLifecycleSnapshot(request.snapshot);
+		const requestedAuthor = request.author;
+		const base = kind === "unacquired" || kind === "fork-deferred" ? structuredClone(request.base) : undefined;
+		const copying = kind === "fork-new" || kind === "fork-deferred";
+		const source = copying ? Object.freeze({ ...request.source }) : undefined;
+		const acquiring = kind === "new" || kind === "unacquired" || copying;
+		const install = (accepted: SelectedFilePublication) => {
+			this.selectedOriginAccepted = true;
+			this.observedSessionAuthority = true;
+			if (acquiring) this.observedPrivateSemantics = true;
+			this.installSelected(accepted.cohort);
+		};
+		const author: SelectedOriginRequest["author"] = requestedAuthor ? (basis, publish) => requestedAuthor(basis, (snapshot, transition, provenance, moduleAdditions) => {
+			const accepted = publish(snapshot, transition, provenance, captureSelectedModuleAdditions(moduleAdditions, wanted));
+			install(accepted);
+			return accepted;
+		}) : undefined;
+		const assertAuthority = (phase: "prepare" | "recheck" = "recheck"): void => {
+			signal?.throwIfAborted();
+			if (!allowed) throw new Error(acquiring ? "Selected private acquisition requires explicit native authority" : kind === "shared-deferred" ? "Selected fork deferral requires explicit native fork authority" : "Selected State Flow shared origin requires explicit new-session authority");
+			if (wanted.includes("session") !== acquiring) throw new Error(acquiring ? "Selected private acquisition requires Session" : "Selected shared origin cannot acquire Session");
+			if (lifecycle.config.mode === "off") throw new Error("Off cannot initialize State Flow memory");
+			if (historyLimit !== this.historyLimit) throw new Error("Selected origin history policy does not match its runtime");
+			if (copying) {
+				if (!source || typeof source.id !== "string" || typeof source.key !== "string" || source.id === this.sessionId || source.key === this.sessionKey) throw new Error("Selected fork requires a distinct direct parent");
+				if (typeof revalidateDirectParent !== "function") throw new Error("Selected fork copy requires independent native direct-parent authority");
+				revalidateDirectParent(source, phase);
+			}
+			this.rememberSessionAuthority(this.base);
+			if (kind === "unacquired" || kind === "fork-deferred") {
+				if (this.observedPrivateSemantics) throw new Error("Known acquired State Flow private memory cannot become an empty origin");
+			} else if (this.selectedOriginAccepted || this.observedSessionAuthority || this.semanticRevision || this.savedRuntime) {
+				throw new Error("Known State Flow session requires current-memory acceptance, not a new origin");
+			}
+		};
+		assertAuthority("prepare");
+		if (kind === "unacquired" || copying) {
+			if (!lstatSync(this.root, { throwIfNoEntry: false })) throw new RevisionUnavailableError("Selected private acquisition source storage is unavailable");
+		} else initializeFileStore(this.root);
+		return withStorageTransaction(this.root, (storage) => {
+			assertAuthority();
+			let consumed = false;
+			let published = false;
+			const result = action(() => {
+				if (consumed) throw new Error("Selected State Flow origin publication was already consumed");
+				consumed = true;
+				assertAuthority();
+				const input = { selection: wanted, snapshot: lifecycle, historyLimit: this.historyLimit, ...(author ? { author } : {}) };
+				const accepted = kind === "shared-new"
+					? storage.initializeSelectedSharedOrigin(this.cwd, this.sessionId, input, this.root, this.sessionKey)
+					: kind === "shared-deferred" ? storage.deferSelectedFork(this.cwd, this.sessionId, input, this.root, this.sessionKey)
+					: copying ? storage.copySelectedFork(this.cwd, this.sessionId, kind === "fork-new" ? { ...input, kind, source: source! } : { ...input, kind: "fork-deferred", source: source!, base: base! }, this.root, this.sessionKey)
+					: storage.acquireSelectedSession(this.cwd, this.sessionId, kind === "new" ? { ...input, kind: "new" } : { ...input, kind: "unacquired", base: base! }, this.root, this.sessionKey);
+				if (!author) install(accepted);
+				published = true;
+				return accepted;
+			});
+			if (!published) throw new Error("Selected State Flow origin requires one synchronous publication");
+			return result;
+		}, signal);
+	}
+
 	/** Copy the parent's current session memory into an unoccupied child; the caller rechecks native selection after waiting. */
 	async withForkTransaction<T>(source: SessionAddress, lifecycle: ForkLifecycle, action: (selected: Snapshot, publish: (snapshot: Snapshot) => RuntimePublication) => T, signal?: AbortSignal): Promise<T> {
 		signal?.throwIfAborted();
@@ -483,7 +1029,7 @@ export class TemporalRuntime {
 		const parent = new TemporalRuntime(this.cwd, source, this.root, undefined, this.historyLimit);
 		if (!parent.loadCurrentMemoryBase(sourceBase)) throw new RevisionUnavailableError("State Flow fork parent memory is unavailable");
 		const base = storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
-		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		const files = temporalFileContents(base);
 		const paths = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
 		if ([paths.checkpoint, paths.patches, paths.meta, join(paths.directory, "config.json"), join(paths.directory, "runtime.json")].some((path) => files.get(path) !== undefined)) {
 			throw new Error("State Flow fork target already has session storage");
@@ -520,6 +1066,7 @@ export class TemporalRuntime {
 		const allowCreateOrigin = selection.kind === "start" && selection.allowCreateOrigin;
 		const semantic = kind !== "lifecycle";
 		const assertAuthority = (): void => {
+			if (this.selectedBackendChosen) throw new Error("Selected State Flow origin requires selected runtime integration");
 			if (selection.kind === "fork") {
 				if (selection.source.id === this.sessionId || selection.source.key === this.sessionKey) throw new Error("State Flow fork requires a distinct session identity and key");
 				if (this.view) throw new Error("State Flow fork target already has session storage");
@@ -613,7 +1160,13 @@ export class TemporalRuntime {
 			const updates = options.provenance?.[scope];
 			if (updates) for (const [path, entry] of Object.entries(updates)) nextProvenance[scope][path] = structuredClone(entry);
 		}
-		if (!runtimeOnly) for (const scope of SCOPES) {
+		const legacyBasis = SCOPES.some((scope) => {
+			const meta = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).meta;
+			const content = base.files.find((file) => file.path === meta)?.content;
+			return content !== undefined && JSON.parse(content).version < 3;
+		});
+		// A representation-only activation must not turn provenance normalization into migration side effects.
+		if (!runtimeOnly && (!legacyBasis || accepted !== undefined || provenanceScopes.length > 0)) for (const scope of SCOPES) {
 			nextProvenance[scope] = pruneArtifactProvenance(nextProvenance[scope], readTemporalState(next, 0, scope, this.historyLimit).artifacts);
 		}
 		const provenanceChanged = !sameJson(nextProvenance, this.provenanceByScope);