@llblab/pi-kit 0.37.0 → 0.38.0

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

@@ -1,5 +1,173 @@
-import { parseRetainedPiCheckpoint, readCheckpointMode } from "./snapshot.js";
+import { parseRetainedPiCheckpoint, prepareRetainedPolicyMigration, readCheckpointMode, isStateFlowMode } from "./snapshot.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
+import { isJsonValue, isObject } from "./json.js";
+import { isAbsolute, resolve } from "node:path";
+import { RenewableLifetime } from "./operation.js";
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
+function captureRequestPolicy(value) {
+    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 {
+    #lifetime = new RenewableLifetime();
+    #policy;
+    #ended = false;
+    get policy() { return this.#policy; }
+    /** Cancellation only, including Off; unlike capture(), this grants no enabled memory receipt. */
+    get signal() { return this.#lifetime.signal; }
+    /** Same captured policy preserves independent owners; a real choice revokes all old requests. */
+    select(value) {
+        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() {
+        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() {
+        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() {
+        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;
+    #ambiguous = false;
+    #context;
+    #operation;
+    #calls = new Map();
+    begin(request, signal, currentIdentity, controlSignal) {
+        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() {
+        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) {
+        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) {
+        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() { return this.#turn !== undefined || this.#ambiguous; }
+    /** Identify the ambient model owner; deciding which Abort cause to forward belongs to the native port. */
+    ownsOperation(signal) { return signal !== undefined && signal === this.#operation; }
+    has(id) { return this.#calls.has(id); }
+    current() {
+        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, name) {
+        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, name, parent) {
+        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, name) {
+        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() {
+        const previous = this.#turn;
+        this.#turn = undefined;
+        this.#ambiguous = false;
+        this.#context = undefined;
+        this.#calls.clear();
+        previous?.controller.abort();
+    }
+}
 /** Enumerate active-branch snapshots newest-first while containing hostile entries. */
 export function discoverSnapshotData(branch) {
     const candidates = [];
@@ -54,6 +222,226 @@ export function findBranchPolicy(branch, sessionId, stopEntryType, inactiveMode)
     }
     return undefined;
 }
+/** Checkpoint-only preflight: no Stop/fork precedence, installation or authority. Invalid owned data cannot fall back. */
+export function prepareBranchCheckpointPolicy(branch, legacySelection, inactiveMode = "passive") {
+    for (let index = branch.length - 1; index >= 0; index--) {
+        let entry;
+        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;
+}
+function nativeMarkerVersion(value) {
+    let version;
+    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) {
+    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 < 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 < 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 }), ...(mode === undefined ? {} : { mode: mode }),
+        ...(version === 2 ? { scopes: captureScopeSelection(value.scopes) } : {}),
+        ...(reset === true ? { reset: true } : {}), ...(forkPending === true ? { forkPending: true } : {}),
+        ...(at === undefined ? {} : { at: at }), ...(from === undefined ? {} : { from: from }),
+        ...(preserveContext === true ? { preserveContext: true } : {}), ...(memoryDeferred === true ? { memoryDeferred: true } : {}),
+        ...(persistenceError === undefined ? {} : { persistenceError: persistenceError }),
+    };
+}
+/** Closed v2 writer value. Legacy records are translated only in branch context, never given a fabricated owner. */
+export function captureSelectedNativeMarker(value) {
+    const marker = parseNativeMarker(value);
+    if (marker.version !== 2)
+        throw new Error("Selected State Flow native marker requires version 2");
+    return marker;
+}
+/** Complete native branch admission only; never read canonical/parent files, attach policy or confer memory authority. */
+export function prepareSelectedBranchPolicy(branch, options) {
+    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 = [];
+    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(), decoded = new Map();
+    const read = (record) => {
+        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) => {
+        try {
+            return isObject(value) ? value.owner : undefined;
+        }
+        catch {
+            throw new Error("Unreadable State Flow native policy owner");
+        }
+    };
+    const marker = (record) => {
+        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 = "default";
+    let checkpointMode;
+    let stop, persistenceError;
+    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, sessionId, entryType) {
     for (let index = branch.length - 1; index >= 0; index--) {
@@ -107,8 +495,15 @@ export function hasUncheckpointedConversation(branch) {
                     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 {

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

@@ -1,5 +1,6 @@
 import { type ArtifactProvenance, type ArtifactRegistry } from "./artifact.ts";
-import type { StateScope } from "./state.ts";
+import { type ScopeSelection } from "./selection.ts";
+import type { AtomicScopePatches, StateScope } from "./state.ts";
 export declare const SKILL_ARTIFACT_COMPILER = "skill-artifact-v1";
 export declare function hasCompiledSkillArtifact(artifacts: ArtifactRegistry, provenance: ArtifactProvenance | undefined, source: string, expectedHash?: string): boolean;
 export type SkillSourceHasher = (source: string) => string;
@@ -29,7 +30,11 @@ export declare class SkillReadTracker {
     readonly successful: Map<string, SuccessfulSkillRead>;
     readonly hashSource: SkillSourceHasher;
     readonly resolveRegistered: RegisteredSkillResolver;
-    constructor(hashSource?: SkillSourceHasher, resolveRegistered?: RegisteredSkillResolver);
+    constructor(hashSource?: SkillSourceHasher, resolveRegistered?: RegisteredSkillResolver, selection?: ScopeSelection);
+    /** Selection changes revoke correlated reads; a disabled Skill still retains ownership-only volatile evidence. */
+    select(selection: ScopeSelection): void;
+    /** Rehash only attempted selected compilations; this body acquisition must run outside canonical exclusion. */
+    validateCompilations(patches: AtomicScopePatches): void;
     clear(): void;
     recordStart(toolCallId: string, toolName: string, args: unknown): void;
     recordCall(toolCallId: string, toolName: string, input: unknown): void;

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

@@ -1,7 +1,8 @@
-import { readFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { hashArtifactSource, isArtifactHash, } from "./artifact.js";
 import { isObject } from "./json.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
 export const SKILL_ARTIFACT_COMPILER = "skill-artifact-v1";
 function hasContent(value) {
     if (typeof value === "string")
@@ -30,7 +31,26 @@ export function hasCompiledSkillArtifact(artifacts, provenance, source, expected
         && (expectedHash === undefined || sourceHash === expectedHash);
 }
 export function hashSkillSource(source) {
-    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, args) {
     if (toolName !== "read" || !isObject(args) || typeof args.path !== "string")
@@ -67,9 +87,36 @@ export class SkillReadTracker {
     #pending = new Map();
     hashSource;
     resolveRegistered;
-    constructor(hashSource = hashSkillSource, resolveRegistered = () => undefined) {
+    #selection;
+    constructor(hashSource = hashSkillSource, resolveRegistered = () => undefined, selection = 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) {
+        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) {
+        for (const scope of Object.keys(patches))
+            if (!this.#selection.includes(scope))
+                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() {
         this.successful.clear();
@@ -103,6 +150,11 @@ export class SkillReadTracker {
         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;
         try {
             const hash = this.hashSource(registered.path);

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

@@ -1,6 +1,7 @@
 import { type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { type JsonObject } from "./json.ts";
-import { type TransitionBoundary } from "./temporal.ts";
+import { type ExcludedTransitionWitness, type TransitionBoundary } from "./temporal.ts";
+import { type ScopeSelection } from "./selection.ts";
 /** Missing operational capability is not evidence that a checkpoint target is invalid. */
 export declare class RevisionUnavailableError extends Error {
 }
@@ -35,24 +36,47 @@ export interface StateFlowSnapshot {
     meta: SnapshotMeta;
 }
 export type Snapshot = StateFlowSnapshot;
+/** Capture closed caller-owned run fields, omitting only undefined optional in-memory fields. */
+export declare function captureLifecycleSnapshot(value: Snapshot): Snapshot;
 /** Failed Active selection retains its policy and fences inference until explicit recovery or an inactive choice. */
 export declare function isActiveRestorationBlocked(snapshot: Snapshot): boolean;
+interface LifecycleMetadata extends SnapshotMeta {
+    identity: {
+        cwd: string;
+        sessionId: string;
+    };
+    lineage: TransitionBoundary[];
+    [key: string]: unknown;
+}
+interface SessionRuntimeMetadata extends LifecycleMetadata {
+    /** Runtime-owned artifact compilation evidence; never projected as semantic state. */
+    artifacts?: ArtifactProvenanceRegistry;
+    temporal?: {
+        checkpoint: TransitionBoundary;
+        patches: TransitionBoundary[];
+    };
+}
 export interface SessionRuntime {
     config: SnapshotConfig;
-    meta: SnapshotMeta & {
+    meta: SessionRuntimeMetadata & {
         version: 1;
-        identity: {
-            cwd: string;
-            sessionId: string;
-        };
-        lineage: TransitionBoundary[];
-        /** Runtime-owned artifact compilation evidence; never projected as semantic state. */
-        artifacts?: ArtifactProvenanceRegistry;
-        temporal?: {
-            checkpoint: TransitionBoundary;
-            patches: TransitionBoundary[];
-        };
-        [key: string]: unknown;
+    };
+}
+export type PrivateAcquisition = "unacquired" | "deferred" | "acquired";
+export interface PrivateCausalBasis {
+    lineage: TransitionBoundary[];
+    causalWitnesses: ExcludedTransitionWitness[];
+}
+/** Retained private identity proof, never private values or acquisition permission. */
+export declare function capturePrivateCausalBasis(value: unknown): PrivateCausalBasis;
+export interface SelectedSessionRuntime {
+    config: SnapshotConfig & {
+        scopes: ScopeSelection;
+    };
+    meta: LifecycleMetadata & {
+        version: 2;
+        privateAcquisition: PrivateAcquisition;
+        privateCausalBasis?: PrivateCausalBasis;
     };
 }
 export declare function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime;
@@ -63,6 +87,23 @@ export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: st
 };
 /** Legacy `enabled:false` decodes as non-active; native checkpoints, not this file, select branch policy. */
 export declare function parseSessionRuntime(config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined;
+export interface SessionPolicyMigrationCandidate {
+    sourceVersion: 1 | 2;
+    targetVersion: 2;
+    requiresConversion: boolean;
+    /** Original strings, not file observations or publication authority. */
+    source: {
+        config: string;
+        runtime: string;
+    };
+    runtime: SelectedSessionRuntime;
+    target: {
+        config: string;
+        runtime: string;
+    };
+}
+/** Detached lifecycle preflight only; current native readers/writers still admit version 1 exclusively. */
+export declare function prepareSessionPolicyMigration(config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string, legacySelection: ScopeSelection): SessionPolicyMigrationCandidate | undefined;
 export declare function emptySnapshot(mode?: StateFlowMode): Snapshot;
 export type RetainedBoundaryCheckpoint = {
     boundary: string;
@@ -84,5 +125,17 @@ export declare function retainedBoundaryCheckpoint(snapshot: Snapshot, boundary:
 export declare function preRuntimeCheckpoint(mode: StateFlowMode): PreRuntimeCheckpoint;
 /** Decode the retained-window checkpoint contract; legacy `enabled`/`{disabled:true}` markers map through `inactiveMode`. */
 export declare function parseRetainedPiCheckpoint(value: unknown, inactiveMode?: InactiveMode): RetainedPiCheckpoint;
+export type SelectedRetainedPiCheckpoint = RetainedPiCheckpoint & {
+    version: 2;
+    scopes: ScopeSelection;
+};
+export interface RetainedPolicyMigrationCandidate {
+    sourceVersion: "legacy" | 2;
+    targetVersion: 2;
+    requiresConversion: boolean;
+    checkpoint: SelectedRetainedPiCheckpoint;
+}
+/** Native policy value preflight; no retained boundary, fork or acquisition authority is created. */
+export declare function prepareRetainedPolicyMigration(value: unknown, legacySelection: ScopeSelection, inactiveMode?: InactiveMode): RetainedPolicyMigrationCandidate;
 export declare function migrationFailure(data: JsonObject, error: string, mode?: StateFlowMode): Snapshot;
 export {};