@llblab/pi-kit 0.22.2 → 0.23.1

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

@@ -3,12 +3,12 @@ import { lstatSync } from "node:fs";
 import { join } from "node:path";
 import { classifyScopeStream, hasCwdMaterialization, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
 import { pruneArtifactProvenance } from "./artifact.js";
-import { captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles } from "./storage.js";
+import { assertTemporalFileBase, captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction } from "./storage.js";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { hashJson, sameJson } from "./json.js";
-import { RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, retainedBoundaryCheckpoint } from "./snapshot.js";
+import { HistoryBoundaryExpiredError, RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, retainedBoundaryCheckpoint } from "./snapshot.js";
 import { emptyState } from "./state.js";
-import { adoptTemporalStreams, advanceTemporalState, createTemporalState, readTemporalState, selectScopeStreamAtBoundary, validateScopeLineage } from "./temporal.js";
+import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalState, selectScopeStreamAtBoundary, validateScopeLineage } from "./temporal.js";
 const SCOPES = ["global", "cwd", "session"];
 const SHARED_SCOPES = ["global", "cwd"];
 function emptyProvenance() {
@@ -50,6 +50,7 @@ export class TemporalRuntime {
     base;
     semanticRevision;
     savedRuntime;
+    transaction;
     restoredOriginPending = false;
     provenanceByScope = emptyProvenance();
     /** Shared scopes whose wholly absent live basis was accepted after one stale-target refusal. */
@@ -76,7 +77,9 @@ export class TemporalRuntime {
     loadPassive() {
         if (!lstatSync(this.root, { throwIfNoEntry: false }))
             return false;
-        const base = captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        return this.loadPassiveBase(captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey));
+    }
+    loadPassiveBase(base) {
         const files = new Map(base.files.map((file) => [file.path, file.content]));
         const shared = Object.fromEntries(SHARED_SCOPES.map((scope) => {
             const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
@@ -88,13 +91,19 @@ export class TemporalRuntime {
             throw new Error("Incomplete passive State Flow shared storage: CWD state exists without global state");
         const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID(), this.historyLimit);
         // Global memory is valid before this CWD has ever materialized its own scope.
-        this.view = adoptTemporalStreams({ global: shared.global, cwd: shared.cwd ?? fresh.scopes.cwd, session: fresh.scopes.session }, `passive:files:${randomUUID()}`, this.historyLimit);
-        this.base = base;
-        this.provenanceByScope = {
+        const view = adoptTemporalStreams({ global: shared.global, cwd: shared.cwd ?? fresh.scopes.cwd, session: fresh.scopes.session }, `passive:files:${randomUUID()}`, this.historyLimit);
+        const provenance = {
             global: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta), "State Flow global metadata"),
             cwd: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta), "State Flow CWD metadata"),
             session: {},
         };
+        this.view = view;
+        this.base = base;
+        this.provenanceByScope = provenance;
+        this.semanticRevision = undefined;
+        this.savedRuntime = undefined;
+        this.restoredOriginPending = false;
+        this.absentSharedScopes.clear();
         return true;
     }
     /** Select canonical file acceptance even when Git is available; backup remains a later concern. */
@@ -143,7 +152,9 @@ export class TemporalRuntime {
     prepareBoundaryRestore(checkpoint) {
         if (!lstatSync(this.root, { throwIfNoEntry: false }))
             throw new RevisionUnavailableError("Selected State Flow boundary storage is unavailable");
-        const base = captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        return this.prepareBoundaryRestoreBase(checkpoint, captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey));
+    }
+    prepareBoundaryRestoreBase(checkpoint, base) {
         const files = new Map(base.files.map((file) => [file.path, file.content]));
         const scopes = Object.fromEntries(SCOPES.map((scope) => {
             const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
@@ -160,7 +171,7 @@ export class TemporalRuntime {
         validateScopeLineage(scopes.session, "session", document.meta.lineage, MAX_HISTORY_LIMIT);
         const boundary = document.meta.lineage.slice(-(this.historyLimit + 1)).find(({ id }) => id === checkpoint.boundary);
         if (!boundary)
-            throw new RevisionUnavailableError("Selected State Flow history boundary is outside the retained temporal window");
+            throw new HistoryBoundaryExpiredError("Selected State Flow history boundary is outside the retained temporal window");
         const selectedSession = selectScopeStreamAtBoundary(scopes.session, "session", boundary, MAX_HISTORY_LIMIT);
         const view = adoptTemporalStreams({
             global: scopes.global,
@@ -214,6 +225,60 @@ export class TemporalRuntime {
         const snapshot = prepared.restore();
         return { snapshot, publication: this.acceptRestoredOrigin(snapshot) };
     }
+    /** Await a coherent read-only recovery view; this neither activates policy nor accepts publication authority. */
+    async refreshCurrentMemory(signal) {
+        signal?.throwIfAborted();
+        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);
+            signal?.throwIfAborted();
+            return this.loadCurrentMemoryBase(base);
+        }, signal);
+    }
+    loadCurrentMemoryBase(base) {
+        const files = new Map(base.files.map((file) => [file.path, file.content]));
+        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;
+        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()}`;
+        const scopes = Object.fromEntries(SCOPES.map((scope) => {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta));
+            if (!stream && scope === "session")
+                throw new RevisionUnavailableError("Current State Flow session memory is unavailable");
+            return [scope, stream ?? freshEmptyScopeStream(scope, origin, this.historyLimit)];
+        }));
+        validateScopeLineage(scopes.session, "session", document.meta.lineage, MAX_HISTORY_LIMIT);
+        let view;
+        try {
+            view = constrainTemporalState({ scopes, lineage: document.meta.lineage }, this.historyLimit);
+        }
+        catch {
+            // Independently validated live shared streams can belong to another writer's lineage.
+            view = adoptTemporalStreams(scopes, origin, this.historyLimit);
+        }
+        const provenance = Object.fromEntries(SCOPES.map((scope) => {
+            const meta = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).meta;
+            return [scope, parseScopeProvenance(files.get(meta), meta)];
+        }));
+        const snapshot = {
+            config: { enabled: false },
+            meta: { step: document.meta.step, ...(document.meta.bootstrap === true ? { bootstrap: true } : {}) },
+        };
+        this.view = view;
+        this.base = base;
+        this.provenanceByScope = provenance;
+        this.semanticRevision = undefined;
+        this.savedRuntime = undefined;
+        this.restoredOriginPending = false;
+        this.absentSharedScopes.clear();
+        return snapshot;
+    }
     /** Copy one retained source-session boundary over the child's current shared scopes. */
     prepareBoundaryFork(source, checkpoint) {
         const parent = Object.freeze({ ...source });
@@ -285,7 +350,7 @@ export class TemporalRuntime {
         const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), this.cwd, this.sessionId);
         if (existingRuntime && !newSessionOrigin)
             throw new Error("Existing session runtime requires retained-boundary restoration");
-        // Explicit start before any branch runtime is a new origin, never inheritance of a later session layer.
+        // A pre-runtime branch may establish an empty origin, never import a later session layer.
         if (newSessionOrigin)
             streams.session = undefined;
         if (copy)
@@ -316,7 +381,7 @@ export class TemporalRuntime {
     /** Copy the private origin and apply configured retention folding, preserving live shared values/provenance. */
     publishForkOrigin(snapshot) {
         const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, this.view.lineage, this.provenanceByScope.session);
-        const publication = publishTemporalStateToFiles(this.cwd, this.sessionId, this.view, SCOPES, this.base, this.root, runtime, this.sessionKey, this.provenanceByScope);
+        const publication = (this.transaction?.publish ?? publishTemporalStateToFiles)(this.cwd, this.sessionId, this.view, SCOPES, this.base, this.root, runtime, this.sessionKey, this.provenanceByScope);
         this.base = publication.base;
         this.semanticRevision = publication.revision;
         this.savedRuntime = hashJson(runtime);
@@ -330,8 +395,8 @@ export class TemporalRuntime {
      * actually changes remains a fail-closed write conflict. Divergence in non-adoptable
      * session or runtime files also fails closed under the existing race rule.
      */
-    reconcileSharedDrift(changedScopes) {
-        const captured = captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+    reconcileSharedDrift(changedScopes, current) {
+        const captured = current ?? captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
         const liveFiles = new Map(captured.files.map((file) => [file.path, file]));
         const priorFiles = new Map(this.base.files.map((file) => [file.path, file]));
         const adoptable = new Set();
@@ -402,16 +467,201 @@ export class TemporalRuntime {
             throw targetScopeConflict(targets);
         return { view: reconciledView(), base: captured, provenance };
     }
-    /** Refresh live shared scopes in memory without publishing or advancing private semantic history. */
-    refreshShared() {
-        if (!this.view || !this.base)
-            throw new Error("State Flow shared refresh requires a selected temporal runtime");
-        const before = this.view;
-        const reconciled = this.reconcileSharedDrift(new Set());
-        this.view = reconciled.view;
-        this.base = reconciled.base;
-        this.provenanceByScope = reconciled.provenance;
-        return before !== this.view;
+    /** Await coherent shared inspection, lazily loading an empty private view only when none is selected. */
+    async refreshShared(signal) {
+        signal?.throwIfAborted();
+        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);
+            if (!this.view)
+                return this.loadPassiveBase(current);
+            if (!this.base)
+                throw new Error("State Flow shared refresh requires a selected temporal runtime");
+            const before = this.view;
+            const reconciled = this.reconcileSharedDrift(new Set(), current);
+            this.view = reconciled.view;
+            this.base = reconciled.base;
+            this.provenanceByScope = reconciled.provenance;
+            return before !== this.view;
+        }, signal);
+    }
+    /** Prepare current shared state while retaining the exact accepted private publication basis. */
+    publicationCandidate(storage, current) {
+        if (this.restoredOriginPending)
+            throw new RevisionUnavailableError("State Flow restored origin must be accepted before patching memory");
+        current ??= storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
+        const candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
+        candidate.transaction = storage;
+        if (this.semanticRevision && this.view && this.base) {
+            candidate.view = this.view;
+            candidate.base = this.base;
+            candidate.provenanceByScope = this.provenanceByScope;
+            const reconciled = candidate.reconcileSharedDrift(new Set(), current);
+            candidate.view = reconciled.view;
+            candidate.base = reconciled.base;
+            candidate.provenanceByScope = reconciled.provenance;
+            return candidate;
+        }
+        const files = new Map(current.files.map((file) => [file.path, file.content]));
+        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)) {
+            const document = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), this.cwd, this.sessionId);
+            const stream = parseScopeStream(files.get(session.checkpoint), files.get(session.patches), "session", undefined, files.get(session.meta));
+            if (!document || !stream)
+                throw new RevisionUnavailableError("Current State Flow session memory is incomplete");
+            validateScopeLineage(stream, "session", document.meta.lineage, MAX_HISTORY_LIMIT);
+            throw new RevisionUnavailableError("Existing State Flow session memory is not selected; select an accepted boundary or use /state-flow-start");
+        }
+        const origin = `patch:${randomUUID()}`;
+        const streams = Object.fromEntries(SCOPES.map((scope) => {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta)) ?? freshEmptyScopeStream(scope, `${origin}:empty`, this.historyLimit)];
+        }));
+        candidate.view = adoptTemporalStreams(streams, origin, this.historyLimit);
+        candidate.base = current;
+        candidate.provenanceByScope = Object.fromEntries(SCOPES.map((scope) => {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            // Absent semantic pairs cannot confer compilation evidence on a new registration.
+            return [scope, files.get(paths.checkpoint) === undefined ? {} : parseScopeProvenance(files.get(paths.meta), paths.meta)];
+        }));
+        return candidate;
+    }
+    /** Stage and accept synchronously inside an awaited lock; expose neither selection nor raw storage operations. */
+    async withPatchTransaction(action, signal) {
+        return this.withPublicationTransaction((candidate, publish) => action({
+            states: candidate.states(),
+            causalBasis: candidate.causalBasis(),
+            provenance: structuredClone(candidate.provenanceByScope),
+            publish,
+        }), { kind: "patch" }, signal);
+    }
+    /** Activate current owned memory; the caller must authorize a wholly absent private origin after waiting. */
+    async withStartTransaction(action, signal, allowCreateOrigin = false) {
+        return this.withPublicationTransaction((_candidate, publish, current) => action(current, (snapshot) => publish(snapshot)), { kind: "start", allowCreateOrigin }, signal);
+    }
+    /** Select one retained private boundary beside current shared streams, then accept only after caller policy is rechecked. */
+    async withRestoreTransaction(checkpoint, action, signal) {
+        signal?.throwIfAborted();
+        return this.withPublicationTransaction((_candidate, publish, selected) => action(selected, (snapshot) => publish(snapshot)), { kind: "restore", checkpoint: structuredClone(checkpoint) }, signal);
+    }
+    /** Copy exact retained parent authority into an unoccupied child; the caller rechecks native selection after waiting. */
+    async withForkTransaction(source, checkpoint, action, signal) {
+        signal?.throwIfAborted();
+        return this.withPublicationTransaction((_candidate, publish, selected) => action(selected, (snapshot) => publish(snapshot)), { kind: "fork", source: { ...source }, checkpoint: structuredClone(checkpoint) }, signal);
+    }
+    prepareForkCandidate(storage, source, checkpoint) {
+        const sourceBase = storage.capture(this.cwd, source.id, this.root, source.key);
+        const parent = new TemporalRuntime(this.cwd, source, this.root, undefined, this.historyLimit);
+        const selected = parent.prepareBoundaryRestoreBase(checkpoint, sourceBase).restore();
+        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 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");
+        }
+        if (SCOPES.some((scope) => lstatSync(join(temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).directory, "state.json"), { throwIfNoEntry: false }))) {
+            throw new Error("Unsupported State Flow storage exists; preserve or convert it before initialization");
+        }
+        const candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
+        candidate.transaction = storage;
+        candidate.base = base;
+        candidate.view = adoptTemporalStreams(parent.view.scopes, `files:${randomUUID()}`, this.historyLimit);
+        candidate.provenanceByScope = { ...parent.provenanceByScope };
+        for (const scope of SHARED_SCOPES) {
+            const meta = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).meta;
+            candidate.provenanceByScope[scope] = parseScopeProvenance(files.get(meta), meta);
+        }
+        return {
+            candidate,
+            current: { config: selected.config, meta: { step: 0, ...(selected.meta.bootstrap === undefined ? {} : { bootstrap: selected.meta.bootstrap }) } },
+            assertSource: () => assertTemporalFileBase(sourceBase, storage.capture(this.cwd, source.id, this.root, source.key)),
+        };
+    }
+    /** Recheck caller policy after waiting, then accept only config/runtime over an already accepted private basis. */
+    async withLifecycleTransaction(action, signal) {
+        return this.withPublicationTransaction((_candidate, publish) => action((snapshot) => publish(snapshot)), { kind: "lifecycle" }, signal);
+    }
+    async withPublicationTransaction(action, selection, signal) {
+        const { kind } = selection;
+        const allowCreateOrigin = selection.kind === "start" && selection.allowCreateOrigin;
+        const semantic = kind !== "lifecycle";
+        const assertAuthority = () => {
+            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");
+            }
+            if (!semantic && (!this.semanticRevision || !this.view || !this.base || this.restoredOriginPending)) {
+                throw new Error("State Flow lifecycle transaction requires an accepted runtime");
+            }
+        };
+        signal?.throwIfAborted();
+        assertAuthority();
+        if (kind === "patch" || allowCreateOrigin)
+            initializeFileStore(this.root);
+        if ((kind === "start" || kind === "restore" || kind === "fork") && !lstatSync(this.root, { throwIfNoEntry: false })) {
+            throw new RevisionUnavailableError(kind !== "start" ? "Selected State Flow boundary storage is unavailable" : "Current State Flow session storage is unavailable");
+        }
+        return withStorageTransaction(this.root, (storage) => {
+            assertAuthority();
+            let current;
+            let candidate;
+            let assertSource;
+            if (selection.kind === "fork") {
+                ({ candidate, current, assertSource } = this.prepareForkCandidate(storage, selection.source, selection.checkpoint));
+            }
+            else if (selection.kind === "restore" || selection.kind === "start") {
+                candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
+                candidate.transaction = storage;
+                const base = storage.capture(this.cwd, this.sessionId, this.root, this.sessionKey);
+                current = selection.kind === "restore"
+                    ? candidate.prepareBoundaryRestoreBase(selection.checkpoint, base).restore()
+                    : candidate.loadCurrentMemoryBase(base);
+                if (!current) {
+                    if (!allowCreateOrigin)
+                        throw new RevisionUnavailableError("Current State Flow session memory is unavailable");
+                    if (SCOPES.some((scope) => lstatSync(join(temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).directory, "state.json"), { throwIfNoEntry: false }))) {
+                        throw new Error("Unsupported State Flow storage exists; preserve or convert it before initialization");
+                    }
+                    candidate = candidate.publicationCandidate(storage, base);
+                }
+            }
+            else
+                candidate = this.publicationCandidate(storage);
+            let consumed = false;
+            let published = false;
+            const result = action(candidate, (snapshot, accepted, provenance) => {
+                if (consumed)
+                    throw new Error(`State Flow ${kind} transaction publication was already consumed`);
+                consumed = true;
+                signal?.throwIfAborted();
+                assertSource?.();
+                // Patch preparation without semantic work preserves complete accepted cohorts; selection accepts origins with configured folding.
+                // New authority or wholly absent shared pairs still need normal atomic initialization; partial evidence already failed.
+                const writeSemantic = semantic && (kind === "start" || kind === "restore" || kind === "fork" || accepted !== undefined || !this.semanticRevision
+                    || SCOPES.some((scope) => Object.keys(provenance?.[scope] ?? {}).length > 0)
+                    || candidate.base.files.some((file) => file.content === undefined));
+                // Every capability acceptance validates its captured cohort, including semantic no-ops.
+                const publication = kind === "fork" ? candidate.publishForkOrigin(snapshot) : candidate.publish(snapshot, writeSemantic, accepted, { provenance });
+                if (!publication)
+                    throw new Error(`State Flow ${kind} transaction produced no canonical publication`);
+                this.view = candidate.view;
+                this.base = candidate.base;
+                this.provenanceByScope = candidate.provenanceByScope;
+                this.semanticRevision = candidate.semanticRevision;
+                this.savedRuntime = candidate.savedRuntime;
+                this.restoredOriginPending = false;
+                this.absentSharedScopes.clear();
+                published = true;
+                return publication;
+            }, current);
+            if (!published)
+                throw new Error(`State Flow ${kind} transaction requires one synchronous publication`);
+            return result;
+        }, signal);
     }
     /** Canonically accept a prepared retained-boundary origin before lifecycle-only persistence. */
     acceptRestoredOrigin(snapshot) {
@@ -434,8 +684,8 @@ export class TemporalRuntime {
         let basis = this.view;
         let base = this.base;
         let basisProvenance = this.provenanceByScope;
-        // First passive writes also reconcile their selected basis; origin-only acceptance keeps its strict CAS.
-        if (this.semanticRevision || accepted !== undefined || provenanceScopes.length > 0) {
+        // A transaction already selected its current basis under exclusion; raw replay callers still guard their older basis.
+        if (!this.transaction && (this.semanticRevision || accepted !== undefined || provenanceScopes.length > 0)) {
             const changedScopes = new Set([
                 ...(accepted?.transitions ?? []).map(({ scope }) => scope),
                 ...provenanceScopes,
@@ -462,7 +712,7 @@ export class TemporalRuntime {
         const fingerprint = hashJson(runtime);
         if (!semantic && fingerprint === this.savedRuntime && !provenanceChanged)
             return undefined;
-        const result = publishTemporalStateToFiles(this.cwd, this.sessionId, next, runtimeOnly ? [] : SCOPES, base, this.root, runtime, this.sessionKey, runtimeOnly ? undefined : nextProvenance, runtimeOnly);
+        const result = (this.transaction?.publish ?? publishTemporalStateToFiles)(this.cwd, this.sessionId, next, runtimeOnly ? [] : SCOPES, base, this.root, runtime, this.sessionKey, runtimeOnly ? undefined : nextProvenance, runtimeOnly);
         this.base = result.base;
         this.view = next;
         this.provenanceByScope = nextProvenance;

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

@@ -20,6 +20,9 @@ export interface SessionEntryLookup {
 export interface PassiveStopBoundary {
     at: number;
     from?: number;
+    preserveContext?: true;
+    /** A same-owner failed Stop remains a write fence until a later accepted checkpoint. */
+    persistenceError?: string;
 }
 export interface SnapshotDiscovery {
     candidates: unknown[];
@@ -30,6 +33,8 @@ export declare function discoverSnapshotData(branch: readonly BranchEntry[]): Sn
 export declare function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[];
 export declare function latestSnapshotData(branch: readonly BranchEntry[]): unknown;
 export declare function hasPriorConversation(branch: readonly BranchEntry[]): boolean;
+/** Native conversation after the latest valid checkpoint may contain uncompiled work, not a new semantic authority. */
+export declare function hasUncheckpointedConversation(branch: readonly BranchEntry[]): boolean;
 /** Auto-start eligibility is session identity/lifecycle, not the presence of CWD materialization. */
 export declare function isNewSession(reason: unknown, branch: readonly BranchEntry[]): boolean;
 export declare function findAssistantToolBatch(session: SessionEntryLookup, toolCallId: string): string[] | undefined;

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

@@ -1,3 +1,4 @@
+import { parseRetainedPiCheckpoint } from "./snapshot.js";
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 /** Enumerate active-branch snapshots newest-first while containing hostile entries. */
 export function discoverSnapshotData(branch) {
@@ -36,6 +37,27 @@ export function hasPriorConversation(branch) {
     }
     return false;
 }
+/** Native conversation after the latest valid checkpoint may contain uncompiled work, not a new semantic authority. */
+export function hasUncheckpointedConversation(branch) {
+    for (let index = branch.length - 1; index >= 0; index--) {
+        try {
+            const entry = branch[index];
+            if (entry?.type === "message") {
+                const role = entry.message?.role;
+                if (role === "user" || role === "assistant" || role === "toolResult")
+                    return true;
+            }
+            if (entry?.type === "custom" && entry.customType === SNAPSHOT_ENTRY_TYPE) {
+                parseRetainedPiCheckpoint(entry.data);
+                return false;
+            }
+        }
+        catch {
+            // Malformed entries cannot prove that pending input was checkpointed.
+        }
+    }
+    return false;
+}
 /** Auto-start eligibility is session identity/lifecycle, not the presence of CWD materialization. */
 export function isNewSession(reason, branch) {
     if (reason === "new")
@@ -58,17 +80,29 @@ export function findAssistantToolBatch(session, toolCallId) {
     return undefined;
 }
 export function findPassiveStopBoundary(branch, sessionId, entryType) {
+    let checkpointSeen = false;
     for (const entry of [...branch].reverse()) {
         try {
-            if (entry?.type !== "custom" || entry.customType !== entryType)
+            if (entry?.type !== "custom")
                 continue;
-            const { at, from, reset, owner } = entry.data ?? {};
+            if (entry.customType === SNAPSHOT_ENTRY_TYPE) {
+                parseRetainedPiCheckpoint(entry.data);
+                checkpointSeen = true;
+                continue;
+            }
+            if (entry.customType !== entryType)
+                continue;
+            const { at, from, reset, owner, preserveContext, persistenceError } = entry.data ?? {};
             if (reset === true && owner === sessionId)
                 return undefined;
+            if (owner !== undefined && owner !== sessionId)
+                continue;
             if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0)
                 return {
                     at,
                     ...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
+                    ...(preserveContext === true ? { preserveContext: true } : {}),
+                    ...(!checkpointSeen && owner === sessionId && typeof persistenceError === "string" && persistenceError.trim().length > 0 ? { persistenceError } : {}),
                 };
         }
         catch {

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

@@ -4,6 +4,9 @@ import { type TransitionBoundary } from "./temporal.ts";
 /** Missing operational capability is not evidence that a checkpoint target is invalid. */
 export declare class RevisionUnavailableError extends Error {
 }
+/** Expired history cannot be restored, but explicit activation may use validated current memory. */
+export declare class HistoryBoundaryExpiredError extends RevisionUnavailableError {
+}
 export interface SnapshotConfig {
     enabled: boolean;
 }

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

@@ -8,6 +8,9 @@ const MAX_LEGACY_VALIDATION_ATTEMPT = 7;
 /** Missing operational capability is not evidence that a checkpoint target is invalid. */
 export class RevisionUnavailableError extends Error {
 }
+/** Expired history cannot be restored, but explicit activation may use validated current memory. */
+export class HistoryBoundaryExpiredError extends RevisionUnavailableError {
+}
 export function validateSessionRuntime(value, cwd, sessionId) {
     if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "config,meta"
         || !isObject(value.config) || !isObject(value.meta))

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

@@ -26,6 +26,7 @@ export interface StatusDiagnostics {
     };
     staleArtifacts: readonly StaleArtifactDiagnostic[];
     durableStateError?: string;
+    publicationError?: string;
 }
 export declare function formatScopeRevisionVector(revisions: ScopeRevisions): string;
 export declare function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined;

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

@@ -1,5 +1,6 @@
 import { projectRecentTransitionsWithLimit } from "./history.js";
 import { retainedMemoryScopes } from "./memory.js";
+import { conciseDiagnostic } from "./protocol.js";
 import { overlayStates } from "./state.js";
 export const STATUS_KEY = "state-flow";
 export function formatScopeRevisionVector(revisions) {
@@ -27,7 +28,7 @@ export function detailedStatus(snapshot, diagnostics) {
         ];
     const temporal = available ? diagnostics.temporal : undefined;
     const temporalLines = temporal === undefined
-        ? [`Temporal materialization unavailable: ${diagnostics.durableStateError ?? "no selected branch runtime"}`,
+        ? [`Temporal materialization unavailable: ${conciseDiagnostic(diagnostics.durableStateError ?? "no selected branch runtime")}`,
             `Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
             "Retained patch tails: unavailable"]
         : [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
@@ -45,6 +46,7 @@ export function detailedStatus(snapshot, diagnostics) {
         "Memory: owner state-flow; global retention enabled; global fallback active",
         `Memory-bearing scopes: global ${memoryScopes?.global ?? "unknown"}; CWD ${memoryScopes?.cwd ?? "unknown"}; session ${memoryScopes?.session ?? "unknown"}`,
         ...temporalLines,
+        ...(diagnostics.publicationError === undefined ? [] : [`Memory writes paused after Stop: ${conciseDiagnostic(diagnostics.publicationError)}`]),
         `Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`,
         available ? `Recent transitions: global ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "global")).length}; CWD ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "cwd")).length}; session ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "session")).length}; active ${projectedRecent.length}` : "Recent transitions: unavailable",
         ...invalidationLines,

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

@@ -14,6 +14,17 @@ export declare function initializeFileStore(root: string): void;
 export declare function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number;
 /** Canonical writers and bounded backup capture share exclusion; no Git work runs under this lock. */
 export declare function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T;
+export interface StorageTransaction {
+    readonly capture: typeof captureTemporalFileBase;
+    readonly publish: typeof publishTemporalStateToFiles;
+}
+export declare class PublicationBusyError extends Error {
+    constructor(path: string);
+}
+/** Await an exact file mutex; shared by canonical transactions and the independent Git backup owner. */
+export declare function withFilePublicationLock<T>(lockPath: string, action: () => T | Promise<T>, signal?: AbortSignal, unavailable?: (cause: unknown) => Error, waitForLock?: boolean): Promise<T>;
+/** Await store-wide exclusion, then capture/apply/publish through callback-scoped operations. */
+export declare function withStorageTransaction<T>(repositoryRoot: string, action: (transaction: StorageTransaction) => T | Promise<T>, signal?: AbortSignal, waitForLock?: boolean): Promise<T>;
 export declare function assertTemporalFileBase(expected: TemporalFileBase, current: TemporalFileBase): void;
 /** Plan exact canonical updates; lifecycle-only writes exclude semantic files and provenance. */
 export declare function planTemporalPublication(cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[], current: TemporalFileBase, root: string, runtime?: SessionRuntime, runtimeOnly?: boolean, sessionKey?: string, provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>): {