@llblab/pi-kit 0.37.1 → 0.38.0

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

@@ -1,7 +1,187 @@
-import { parseRetainedPiCheckpoint, readCheckpointMode, type InactiveMode, type StateFlowMode } from "./snapshot.ts";
+import { parseRetainedPiCheckpoint, prepareRetainedPolicyMigration, readCheckpointMode, isStateFlowMode, type InactiveMode, type StateFlowMode, type RetainedPolicyMigrationCandidate } from "./snapshot.ts";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, type ScopeSelection } from "./selection.ts";
+import { isJsonValue, isObject } from "./json.ts";
+import { isAbsolute, resolve } from "node:path";
+import { RenewableLifetime } from "./operation.ts";
 
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 
+/** Requested native policy, not proof of accepted memory or acquisition permission. */
+export interface SelectedNativeRequestPolicy {
+	readonly cwd: string;
+	readonly owner: string;
+	readonly mode: StateFlowMode;
+	readonly scopes: ScopeSelection;
+}
+
+/** Cancelable pre-provider turn, including Off bookkeeping; not memory/acquisition authority. */
+export type NativeContextRequest = Pick<SelectedPolicyRequest, "signal" | "revalidate">;
+
+export interface SelectedPolicyRequest {
+	readonly policy: SelectedNativeRequestPolicy;
+	readonly signal: AbortSignal;
+	/** Synchronous in-memory recheck, suitable for the selected runtime's native-policy port. */
+	revalidate(): void;
+}
+
+function captureRequestPolicy(value: SelectedNativeRequestPolicy): SelectedNativeRequestPolicy {
+	try {
+		if (!isObject(value) || Reflect.ownKeys(value).length !== 4
+			|| !["cwd", "owner", "mode", "scopes"].every(key => Object.hasOwn(value, key))) throw new Error();
+		const { cwd, owner, mode, scopes } = value;
+		if (typeof cwd !== "string" || !isAbsolute(cwd) || typeof owner !== "string" || !owner.trim() || !isStateFlowMode(mode)) throw new Error();
+		return Object.freeze({ cwd: resolve(cwd), owner, mode, scopes: captureScopeSelection(scopes) });
+	} catch {
+		throw new Error("Invalid State Flow selected request policy");
+	}
+}
+
+/** Owns policy-bound cancellation only; no storage, attachment, source acquisition or slot registry. */
+export class SelectedPolicyLifetime {
+	readonly #lifetime = new RenewableLifetime();
+	#policy: SelectedNativeRequestPolicy | undefined;
+	#ended = false;
+
+	get policy(): SelectedNativeRequestPolicy | undefined { return this.#policy; }
+
+	/** Cancellation only, including Off; unlike capture(), this grants no enabled memory receipt. */
+	get signal(): AbortSignal { return this.#lifetime.signal; }
+
+	/** Same captured policy preserves independent owners; a real choice revokes all old requests. */
+	select(value: SelectedNativeRequestPolicy): void {
+		if (this.#ended) throw new Error("State Flow selected policy lifetime has ended");
+		const next = captureRequestPolicy(value), previous = this.#policy;
+		if (previous && previous.cwd === next.cwd && previous.owner === next.owner && previous.mode === next.mode
+			&& previous.scopes.length === next.scopes.length && previous.scopes.every((scope, index) => scope === next.scopes[index])) return;
+		this.#policy = next;
+		this.#lifetime.renew(new Error("State Flow selected native policy changed"));
+	}
+
+	/** Capture at admission, before any source acquisition, asynchronous wait or queued work. */
+	capture(): SelectedPolicyRequest {
+		const policy = this.#policy, signal = this.#lifetime.signal;
+		if (this.#ended || !policy || signal.aborted) throw new Error("State Flow selected policy lifetime is unavailable");
+		if (policy.mode === "off") throw new Error("Off cannot capture State Flow memory requests");
+		const revalidate = () => {
+			if (this.#ended || this.#policy !== policy || this.#lifetime.signal !== signal || signal.aborted)
+				throw new Error("State Flow selected policy request is no longer current");
+		};
+		return Object.freeze({ policy, signal, revalidate });
+	}
+
+	/** Same-policy branch movement/Abort may revoke requests without inventing a different selection. */
+	invalidate(): void {
+		if (!this.#ended) this.#lifetime.renew(new Error("State Flow selected native request lifetime changed"));
+	}
+
+	/** Shutdown cannot be reopened by a late selection or abort listener. */
+	end(): void {
+		this.#ended = true;
+		this.#policy = undefined;
+		this.#lifetime.end(new Error("State Flow selected policy lifetime has ended"));
+	}
+}
+
+/** One SDK turn and its finalized assistant batch; IDs are evidence only within this owned turn. */
+export class NativeToolRequestCorrelation {
+	#turn: { request?: SelectedPolicyRequest; signal?: AbortSignal; currentIdentity: () => boolean; finalized: boolean; controller: AbortController; prepared?: () => void } | undefined;
+	#ambiguous = false;
+	#context: NativeContextRequest | undefined;
+	#operation: AbortSignal | undefined;
+	readonly #calls = new Map<string, { name: string; consumed: boolean; parent?: string }>();
+
+	begin(request: SelectedPolicyRequest | undefined, signal: AbortSignal | undefined, currentIdentity: () => boolean, controlSignal?: AbortSignal): void {
+		this.#operation = signal;
+		// An overlapping turn has no public request ID to disambiguate its later messages.
+		if (this.#turn || this.#ambiguous) { this.end(); this.#ambiguous = true; return; }
+		this.#turn = { request, signal: controlSignal ? AbortSignal.any([controlSignal, ...(signal ? [signal] : [])]) : signal, currentIdentity, finalized: false, controller: new AbortController() };
+	}
+
+	/** Stable lease from turn_start through provider preparation, before assistant finalization. */
+	preparing(): NativeContextRequest {
+		const turn = this.#turn;
+		const revalidate = () => {
+			if (this.#ambiguous || !turn || this.#turn !== turn || turn.finalized || turn.signal?.aborted || !turn.currentIdentity())
+				throw new Error("State Flow context has no current native request");
+			turn.request?.revalidate();
+			turn.prepared?.();
+		};
+		revalidate();
+		return this.#context ??= Object.freeze({
+			signal: AbortSignal.any([turn!.controller.signal, ...(turn!.signal ? [turn!.signal] : []), ...(turn!.request ? [turn!.request.signal] : [])]),
+			revalidate,
+		});
+	}
+
+	/** Provider-only revalidation of captured context data; callbacks must neither acquire nor recurse into this request. */
+	bindPreparedContext(check: () => void): void {
+		this.preparing().revalidate();
+		const turn = this.#turn!;
+		check();
+		if (this.#turn !== turn) throw new Error("State Flow prepared context owner changed");
+		turn.prepared = check;
+	}
+
+	finalize(calls: readonly { id: string; name: string }[]): void {
+		if (!this.#turn || this.#ambiguous) return;
+		if (this.#turn.finalized) { this.end(); this.#ambiguous = true; return; }
+		this.#turn.finalized = true;
+		for (const { id, name } of calls) {
+			if (!id || !name || this.#calls.has(id)) { this.end(); this.#ambiguous = true; return; }
+			this.#calls.set(id, { name, consumed: false });
+		}
+	}
+
+	get active(): boolean { return this.#turn !== undefined || this.#ambiguous; }
+
+	/** Identify the ambient model owner; deciding which Abort cause to forward belongs to the native port. */
+	ownsOperation(signal: AbortSignal | undefined): boolean { return signal !== undefined && signal === this.#operation; }
+
+	has(id: string): boolean { return this.#calls.has(id); }
+
+	current(): SelectedPolicyRequest {
+		const turn = this.#turn;
+		if (this.#ambiguous || !turn?.request || !turn.finalized || turn.signal?.aborted || !turn.currentIdentity())
+			throw new Error("State Flow tool batch has no current native request");
+		turn.request.revalidate();
+		return turn.request;
+	}
+
+	check(id: string, name: string): SelectedPolicyRequest {
+		const request = this.current(), call = this.#calls.get(id);
+		if (!call || call.name !== name) throw new Error("State Flow tool batch has no current native request");
+		return request;
+	}
+
+	/** Only explicit SDK parent evidence, never an ID prefix or branch-history guess. */
+	nested(id: string, name: string, parent: string): void {
+		const call = this.#calls.get(parent), previous = this.#calls.get(id);
+		if (!id || !call || previous && (previous.name !== name || previous.parent !== parent)) throw new Error("State Flow nested tool has no current native parent");
+		this.check(parent, call.name);
+		if (!previous) this.#calls.set(id, { name, consumed: false, parent });
+	}
+
+	take(id: string, name: string): SelectedPolicyRequest {
+		const request = this.check(id, name), call = this.#calls.get(id)!;
+		if (call.consumed) throw new Error("State Flow native tool admission was already consumed");
+		call.consumed = true;
+		const turn = this.#turn!;
+		return Object.freeze({ policy: request.policy,
+			signal: AbortSignal.any([request.signal, turn.controller.signal, ...(turn.signal ? [turn.signal] : [])]),
+			revalidate: () => { if (this.#turn !== turn) throw new Error("State Flow native request turn has ended"); this.check(id, name); },
+		});
+	}
+
+	end(): void {
+		const previous = this.#turn;
+		this.#turn = undefined;
+		this.#ambiguous = false;
+		this.#context = undefined;
+		this.#calls.clear();
+		previous?.controller.abort();
+	}
+}
+
 interface BranchEntry {
 	type?: unknown;
 	customType?: unknown;
@@ -78,6 +258,205 @@ export function findBranchPolicy(
 	return undefined;
 }
 
+/** Checkpoint-only preflight: no Stop/fork precedence, installation or authority. Invalid owned data cannot fall back. */
+export function prepareBranchCheckpointPolicy(
+	branch: readonly BranchEntry[], legacySelection: ScopeSelection, inactiveMode: InactiveMode = "passive",
+): RetainedPolicyMigrationCandidate | undefined {
+	for (let index = branch.length - 1; index >= 0; index--) {
+		let entry: BranchEntry;
+		try {
+			entry = branch[index];
+			if (entry?.type !== "custom" || entry.customType !== SNAPSHOT_ENTRY_TYPE) continue;
+		} catch {
+			// Unclassifiable foreign entries grant no policy authority.
+			continue;
+		}
+		return prepareRetainedPolicyMigration(entry.data, legacySelection, inactiveMode);
+	}
+	return undefined;
+}
+
+/** Native-only policy/bookkeeping. This marker never grants canonical memory or parent-copy authority. */
+export interface SelectedNativePolicyMarker {
+	version: 2;
+	owner: string;
+	mode: StateFlowMode;
+	scopes: ScopeSelection;
+	reset?: true;
+	forkPending?: true;
+	at?: number;
+	from?: number;
+	preserveContext?: true;
+	persistenceError?: string;
+	memoryDeferred?: true;
+}
+
+type ParsedNativeMarker = Omit<SelectedNativePolicyMarker, "version" | "owner" | "mode" | "scopes"> & {
+	version: "legacy" | 2; owner?: string; mode?: StateFlowMode; scopes?: ScopeSelection;
+};
+
+function nativeMarkerVersion(value: Record<string, unknown>): "legacy" | 2 {
+	let version: unknown;
+	try { if (!Object.hasOwn(value, "version")) return "legacy"; version = value.version; }
+	catch { throw new Error("Unreadable State Flow native policy marker version"); }
+	if (version !== 2) throw new Error("Unsupported State Flow native policy marker version");
+	return 2;
+}
+
+function parseNativeMarker(value: unknown): ParsedNativeMarker {
+	if (!isObject(value)) throw new Error("Invalid State Flow native policy marker");
+	const version = nativeMarkerVersion(value);
+	if (version === "legacy" && Object.hasOwn(value, "scopes")) throw new Error("Target policy fields in legacy State Flow native marker");
+	const keys = ["version", "owner", "mode", "scopes", "reset", "forkPending", "at", "from", "preserveContext", "persistenceError", "memoryDeferred"];
+	if (Object.keys(value).some(key => !keys.includes(key)) || !isJsonValue(value)) throw new Error("Invalid State Flow native policy marker");
+	const { owner, mode, reset, forkPending, at, from: rawFrom, preserveContext, persistenceError, memoryDeferred } = value;
+	// Legacy Stop treated an invalid optional anchor as absent, retaining the valid cutoff.
+	const from = version === "legacy" && (!Number.isSafeInteger(rawFrom) || (rawFrom as number) < 0) ? undefined : rawFrom;
+	if ((owner !== undefined && (typeof owner !== "string" || !owner.trim()))
+		|| (mode !== undefined && !isStateFlowMode(mode))
+		|| (version === 2 && (typeof owner !== "string" || !isStateFlowMode(mode) || !Object.hasOwn(value, "scopes")))
+		|| [reset, forkPending, preserveContext, memoryDeferred].some(flag => flag !== undefined && flag !== true)
+		|| [at, from].some(time => time !== undefined && (!Number.isSafeInteger(time) || (time as number) < 0))
+		|| (persistenceError !== undefined && (typeof persistenceError !== "string" || !persistenceError.trim()))
+		|| ((from !== undefined || preserveContext !== undefined || persistenceError !== undefined || memoryDeferred !== undefined) && at === undefined)
+		|| (at !== undefined && mode === "active")
+		|| (memoryDeferred === true && (mode !== "off" || owner === undefined))
+		|| ((reset === true || forkPending === true) && owner === undefined)
+		|| (reset === true && (forkPending !== undefined || at !== undefined || from !== undefined || preserveContext !== undefined || persistenceError !== undefined || memoryDeferred !== undefined))
+		|| (version === "legacy" && at === undefined && reset !== true && forkPending !== true)
+		|| (version === "legacy" && reset === true && mode !== undefined)) throw new Error("Invalid State Flow native policy marker");
+	return {
+		version, ...(owner === undefined ? {} : { owner: owner as string }), ...(mode === undefined ? {} : { mode: mode as StateFlowMode }),
+		...(version === 2 ? { scopes: captureScopeSelection(value.scopes) } : {}),
+		...(reset === true ? { reset: true } : {}), ...(forkPending === true ? { forkPending: true } : {}),
+		...(at === undefined ? {} : { at: at as number }), ...(from === undefined ? {} : { from: from as number }),
+		...(preserveContext === true ? { preserveContext: true } : {}), ...(memoryDeferred === true ? { memoryDeferred: true } : {}),
+		...(persistenceError === undefined ? {} : { persistenceError: persistenceError as string }),
+	};
+}
+
+/** Closed v2 writer value. Legacy records are translated only in branch context, never given a fabricated owner. */
+export function captureSelectedNativeMarker(value: unknown): SelectedNativePolicyMarker {
+	const marker = parseNativeMarker(value);
+	if (marker.version !== 2) throw new Error("Selected State Flow native marker requires version 2");
+	return marker as SelectedNativePolicyMarker;
+}
+
+export interface SelectedBranchPolicyOptions {
+	owner: string;
+	markerEntryType: string;
+	/** The caller chooses new-session versus inactive fallback mode; absence itself grants no acquisition. */
+	defaults: { mode: StateFlowMode; scopes: ScopeSelection };
+	inactiveMode?: InactiveMode;
+	/** Native fresh-fork fact only; no parent header or store lookup belongs in this resolver. */
+	fork?: boolean;
+}
+
+export interface SelectedBranchPolicyCandidate {
+	mode: StateFlowMode;
+	scopes: ScopeSelection;
+	source: "default" | "checkpoint" | "marker";
+	forkPending: boolean;
+	stop?: PassiveStopBoundary;
+	persistenceError?: string;
+	requiresCapture: boolean;
+	/** Policy-only capture preserves fences; only a separately owned acceptance may append reset/checkpoint. */
+	capture: SelectedNativePolicyMarker;
+}
+
+/** Complete native branch admission only; never read canonical/parent files, attach policy or confer memory authority. */
+export function prepareSelectedBranchPolicy(branch: readonly BranchEntry[], options: SelectedBranchPolicyOptions): SelectedBranchPolicyCandidate {
+	const { owner, markerEntryType } = options;
+	const inactiveMode = options.inactiveMode ?? "passive";
+	const fallbackMode = options.defaults?.mode;
+	if (typeof owner !== "string" || !owner.trim() || typeof markerEntryType !== "string" || !markerEntryType.trim() || markerEntryType === SNAPSHOT_ENTRY_TYPE
+		|| !isStateFlowMode(fallbackMode) || (inactiveMode !== "passive" && inactiveMode !== "off")
+		|| (options.fork !== undefined && typeof options.fork !== "boolean")) throw new Error("Invalid State Flow selected branch policy context");
+	let mode = fallbackMode, scopes = captureScopeSelection(options.defaults.scopes);
+	const classified: Array<{ type: "checkpoint" | "marker"; entry: BranchEntry; index: number }> = [];
+	for (let index = 0; index < branch.length; index++) {
+		try {
+			const entry = branch[index];
+			if (entry?.type !== "custom") continue;
+			if (entry.customType === SNAPSHOT_ENTRY_TYPE) classified.push({ type: "checkpoint", entry, index });
+			else if (entry.customType === markerEntryType) classified.push({ type: "marker", entry, index });
+		} catch { /* Unclassifiable foreign entries supply no policy. */ }
+	}
+	const data = new Map<number, unknown>(), decoded = new Map<number, ParsedNativeMarker>();
+	const read = (record: typeof classified[number]): unknown => {
+		if (!data.has(record.index)) {
+			try { data.set(record.index, record.entry.data); }
+			catch { throw new Error("Unreadable State Flow native policy data"); }
+		}
+		return data.get(record.index);
+	};
+	const markerOwner = (value: unknown): unknown => {
+		try { return isObject(value) ? value.owner : undefined; }
+		catch { throw new Error("Unreadable State Flow native policy owner"); }
+	};
+	const marker = (record: typeof classified[number]): ParsedNativeMarker => {
+		if (!decoded.has(record.index)) decoded.set(record.index, parseNativeMarker(read(record)));
+		return decoded.get(record.index)!;
+	};
+	let forkPending = options.fork === true;
+	// A later owned reset/pending record supersedes older fork evidence, not a checkpoint or mode-only choice.
+	for (const record of [...classified].reverse()) {
+		if (record.type !== "marker") continue;
+		const value = read(record);
+		if (markerOwner(value) !== owner || !isObject(value)) continue;
+		nativeMarkerVersion(value);
+		if (!Object.hasOwn(value, "reset") && !Object.hasOwn(value, "forkPending")) continue;
+		const selected = marker(record);
+		if (selected.reset) { forkPending = false; break; }
+		if (selected.forkPending) { forkPending = true; break; }
+	}
+	const inherit = options.fork === true || forkPending;
+	let localSeen = false, policyError = false, requiresCapture = true;
+	let source: SelectedBranchPolicyCandidate["source"] = "default";
+	let checkpointMode: StateFlowMode | undefined;
+	let stop: PassiveStopBoundary | undefined, persistenceError: string | undefined;
+	for (const record of classified) {
+		if (record.type === "checkpoint") {
+			try {
+				const selected = prepareRetainedPolicyMigration(read(record), scopes, inactiveMode);
+				mode = selected.checkpoint.mode; scopes = selected.checkpoint.scopes; checkpointMode = mode;
+				if (selected.sourceVersion === 2) policyError = false;
+				requiresCapture = selected.requiresConversion || inherit;
+				source = "checkpoint";
+				if (Object.hasOwn(selected.checkpoint, "boundary")) persistenceError = undefined;
+			} catch { policyError = true; }
+			continue;
+		}
+		const raw = read(record), physicalOwner = markerOwner(raw);
+		const local = physicalOwner === owner;
+		const inherited = typeof physicalOwner === "string" && physicalOwner.trim() && inherit && !localSeen;
+		if (physicalOwner !== undefined && !local && !inherited) continue;
+		try {
+			const selected = marker(record);
+			const policyOwner = local || inherited;
+			if (policyOwner) {
+				if (selected.version === 2) { scopes = selected.scopes!; mode = selected.mode!; policyError = false; source = "marker"; requiresCapture = !local; }
+				else if (selected.reset) { mode = checkpointMode ?? fallbackMode; source = "marker"; requiresCapture = true; }
+				else if (selected.memoryDeferred || selected.persistenceError) { mode = selected.memoryDeferred ? "off" : selected.mode ?? inactiveMode; source = "marker"; requiresCapture = true; }
+				if (local) localSeen = true;
+			}
+			if (local && selected.reset) { stop = undefined; persistenceError = undefined; }
+			if ((local || physicalOwner === undefined) && selected.at !== undefined) {
+				stop = { at: selected.at, ...(selected.from === undefined ? {} : { from: selected.from }),
+					...(selected.preserveContext ? { preserveContext: true } : {}), ...(selected.mode === "passive" || selected.mode === "off" ? { mode: selected.mode } : {}),
+					...(selected.memoryDeferred ? { memoryDeferred: true } : {}) };
+				if (local && selected.persistenceError) persistenceError = selected.persistenceError;
+			}
+		} catch { if (local || inherited || isObject(raw) && Object.hasOwn(raw, "version")) policyError = true; }
+	}
+	if (policyError) throw new Error("State Flow selected branch policy is invalid or unsupported");
+	scopes = captureScopeSelection(scopes);
+	const capture = captureSelectedNativeMarker({ version: 2, owner, mode, scopes, ...(forkPending ? { forkPending: true } : {}) });
+	return { mode, scopes, source, forkPending, requiresCapture, capture,
+		...(stop === undefined ? {} : { stop: { ...stop, ...(persistenceError === undefined ? {} : { persistenceError }) } }),
+		...(persistenceError === undefined ? {} : { persistenceError }) };
+}
+
 /** Native policy bookkeeping retains an unacquired fork across extension reloads. */
 export function hasPendingFork(branch: readonly BranchEntry[], sessionId: string, entryType: string): boolean {
 	for (let index = branch.length - 1; index >= 0; index--) {
@@ -126,8 +505,13 @@ export function hasUncheckpointedConversation(branch: readonly BranchEntry[]): b
 				if (role === "user" || role === "assistant" || role === "toolResult") return true;
 			}
 			if (entry?.type === "custom" && entry.customType === SNAPSHOT_ENTRY_TYPE) {
-				parseRetainedPiCheckpoint(entry.data);
-				return false;
+				if (isObject(entry.data) && Object.hasOwn(entry.data, "version")) {
+					const retained = prepareRetainedPolicyMigration(entry.data, DEFAULT_SCOPE_SELECTION).checkpoint;
+					if (Object.hasOwn(retained, "boundary")) return false;
+				} else {
+					parseRetainedPiCheckpoint(entry.data);
+					return false;
+				}
 			}
 		} catch {
 			// Malformed entries cannot prove that pending input was checkpointed.

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

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import {
 	hashArtifactSource,
@@ -7,7 +7,8 @@ import {
 	type ArtifactRegistry,
 } from "./artifact.ts";
 import { isObject } from "./json.ts";
-import type { StateScope } from "./state.ts";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, type ScopeSelection } from "./selection.ts";
+import type { AtomicScopePatches, StateScope } from "./state.ts";
 
 export const SKILL_ARTIFACT_COMPILER = "skill-artifact-v1";
 
@@ -43,7 +44,20 @@ export function hasCompiledSkillArtifact(
 export type SkillSourceHasher = (source: string) => string;
 
 export function hashSkillSource(source: string): string {
-	return hashArtifactSource(readFileSync(source));
+	const expected = lstatSync(source, { bigint: true });
+	if (!expected.isFile() || expected.isSymbolicLink()) throw new Error("Skill source must be a regular non-symlink file");
+	const descriptor = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+	try {
+		const before = fstatSync(descriptor, { bigint: true });
+		if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino) throw new Error("Skill source changed before identity capture");
+		const bytes = readFileSync(descriptor);
+		const after = fstatSync(descriptor, { bigint: true });
+		const current = lstatSync(source, { bigint: true });
+		if (current.isSymbolicLink() || !current.isFile() || current.dev !== before.dev || current.ino !== before.ino
+			|| after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs
+			|| current.size !== after.size || current.mtimeNs !== after.mtimeNs || current.ctimeNs !== after.ctimeNs) throw new Error("Skill source changed during identity capture");
+		return hashArtifactSource(bytes);
+	} finally { closeSync(descriptor); }
 }
 
 function readPath(toolName: unknown, args: unknown): string | undefined {
@@ -103,10 +117,32 @@ export class SkillReadTracker {
 	readonly #pending = new Map<string, PendingRead>();
 	readonly hashSource: SkillSourceHasher;
 	readonly resolveRegistered: RegisteredSkillResolver;
+	#selection: ScopeSelection;
 
-	constructor(hashSource: SkillSourceHasher = hashSkillSource, resolveRegistered: RegisteredSkillResolver = () => undefined) {
+	constructor(hashSource: SkillSourceHasher = hashSkillSource, resolveRegistered: RegisteredSkillResolver = () => undefined, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION) {
 		this.hashSource = hashSource;
 		this.resolveRegistered = resolveRegistered;
+		this.#selection = captureScopeSelection(selection);
+	}
+
+	/** Selection changes revoke correlated reads; a disabled Skill still retains ownership-only volatile evidence. */
+	select(selection: ScopeSelection): void {
+		const wanted = captureScopeSelection(selection);
+		if (wanted.join(",") !== this.#selection.join(",")) this.clear();
+		this.#selection = wanted;
+	}
+
+	/** Rehash only attempted selected compilations; this body acquisition must run outside canonical exclusion. */
+	validateCompilations(patches: AtomicScopePatches): void {
+		for (const scope of Object.keys(patches)) if (!this.#selection.includes(scope as StateScope)) throw new Error(`State Flow ${scope} Skill compilation owner is excluded`);
+		for (const read of this.successful.values()) {
+			if (!this.#selection.includes(read.scope) || !Object.hasOwn(patches, read.scope)) continue;
+			const artifacts = patches[read.scope]?.artifacts;
+			if (!isObject(artifacts) || !Object.hasOwn(artifacts, read.path) || !isObject(artifacts[read.path])) continue;
+			const registered = this.resolveRegistered(read.path);
+			if (!registered || registered.path !== read.path || registered.scope !== read.scope) throw new Error(`Registered Skill ownership changed after acquisition: ${read.path}`);
+			if (!isArtifactHash(read.hash) || read.error !== undefined || this.hashSource(read.path) !== read.hash) throw new Error(`Skill source changed after acquisition: ${read.path}`);
+		}
 	}
 
 	clear(): void {
@@ -143,6 +179,11 @@ export class SkillReadTracker {
 		if (!source) return undefined;
 		const registered = this.resolveRegistered(source);
 		if (!registered) return undefined;
+		if (!this.#selection.includes(registered.scope)) {
+			const read = { path: registered.path, scope: registered.scope };
+			this.successful.set(registered.path, read);
+			return read;
+		}
 		let read: SuccessfulSkillRead;
 		try {
 			const hash = this.hashSource(registered.path);