@llblab/pi-kit 0.18.2 → 0.19.0

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

@@ -1,15 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { lstatSync } from "node:fs";
 import { join } from "node:path";
-import { classifyScopeStream, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
+import { classifyScopeStream, hasCwdMaterialization, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
 import { pruneArtifactProvenance } from "./artifact.js";
-import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit } from "./git.js";
-import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles } from "./storage.js";
+import { captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles } from "./storage.js";
+import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { hashJson, sameJson } from "./json.js";
-import { hasCwdMaterialization, hasLegacyStateSources } from "./migration.js";
-import { RevisionUnavailableError, createSessionRuntime, isFileRevision, parseSessionRuntime, resolveFileSessionRuntime, resolveSessionRuntime } from "./snapshot.js";
+import { RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, retainedBoundaryCheckpoint } from "./snapshot.js";
 import { emptyState } from "./state.js";
-import { adoptTemporalStreams, advanceTemporalState, createTemporalState, readTemporalState, validateTemporalState } from "./temporal.js";
+import { adoptTemporalStreams, advanceTemporalState, createTemporalState, readTemporalState, selectScopeStreamAtBoundary, validateScopeLineage } from "./temporal.js";
 const SCOPES = ["global", "cwd", "session"];
 const SHARED_SCOPES = ["global", "cwd"];
 function emptyProvenance() {
@@ -42,34 +41,8 @@ export class SharedScopeRemovalConflictError extends Error {
 function removedTargetScopeConflict(scopes) {
     return new SharedScopeRemovalConflictError(scopes);
 }
-function freshEmptyScopeStream(scope, origin) {
-    return createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, origin).scopes[scope];
-}
-export class MissingSessionRuntimeError extends Error {
-    constructor() { super("Linked State Flow revision has no session runtime"); }
-}
-/** Immutable target validation is independent of acquiring the live publication basis. */
-export function inspectRuntimeRevision(cwd, sessionId, root, revision, sessionKey = sessionId) {
-    const loaded = loadTemporalRevision(cwd, sessionId, root, revision, sessionKey);
-    if (!loaded.runtime)
-        throw new MissingSessionRuntimeError();
-    const resolved = resolveSessionRuntime(loaded.runtime.document, loaded.runtime.revision);
-    if (!loaded.scopes.global || !loaded.scopes.cwd || !loaded.scopes.session)
-        throw new Error("Incomplete temporal scope cohort");
-    const view = { lineage: resolved.lineage, scopes: { global: loaded.scopes.global, cwd: loaded.scopes.cwd, session: loaded.scopes.session } };
-    validateTemporalState(view);
-    return { runtime: loaded.runtime, resolved, view, provenance: loaded.provenance };
-}
-/** Validate one supported immutable target before any live migration/publication. */
-export function inspectSnapshotRevision(cwd, sessionId, root, revision, _legacySnapshot, sessionKey = sessionId) {
-    if (isFileRevision(revision)) {
-        const file = loadTemporalFileRevision(cwd, sessionId, root, revision, sessionKey);
-        return { snapshot: resolveFileSessionRuntime(file.runtime, revision), file };
-    }
-    if (detectGitCapability() === "files")
-        throw new RevisionUnavailableError("Git is unavailable; cannot restore a Git-linked revision");
-    const temporal = inspectRuntimeRevision(cwd, sessionId, root, revision, sessionKey);
-    return { snapshot: temporal.resolved.snapshot, temporal };
+function freshEmptyScopeStream(scope, origin, historyLimit) {
+    return createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, origin, historyLimit).scopes[scope];
 }
 /** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
 export class TemporalRuntime {
@@ -77,21 +50,25 @@ export class TemporalRuntime {
     base;
     semanticRevision;
     savedRuntime;
-    backend;
+    restoredOriginPending = false;
     provenanceByScope = emptyProvenance();
     /** Shared scopes whose wholly absent live basis was accepted after one stale-target refusal. */
     absentSharedScopes = new Set();
     cwd;
     session;
     root;
-    constructor(cwd, session, root, sessionKey) {
+    historyLimit;
+    constructor(cwd, session, root, sessionKey, historyLimit = DEFAULT_HISTORY_LIMIT) {
         this.cwd = cwd;
         this.session = Object.freeze(typeof session === "string" ? { id: session, key: sessionKey ?? session } : { ...session });
         this.root = root;
+        if (!Number.isSafeInteger(historyLimit) || historyLimit < 0 || historyLimit > MAX_HISTORY_LIMIT)
+            throw new Error(`State Flow history limit must be an integer from 0 to ${MAX_HISTORY_LIMIT}`);
+        this.historyLimit = historyLimit;
     }
     get sessionId() { return this.session.id; }
     get sessionKey() { return this.session.key; }
-    /** Runtime-owned artifact freshness evidence for one scope; never model-visible state. */
+    /** Runtime-owned artifact compilation evidence for one scope; never model-visible state. */
     artifactProvenance(scope) {
         return structuredClone(this.provenanceByScope[scope]);
     }
@@ -99,10 +76,7 @@ export class TemporalRuntime {
     loadPassive() {
         if (!lstatSync(this.root, { throwIfNoEntry: false }))
             return false;
-        const backend = detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files";
-        const base = backend === "git"
-            ? captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey)
-            : captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        const base = captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
         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);
@@ -112,12 +86,10 @@ export class TemporalRuntime {
             return false;
         if (!shared.global)
             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());
-        const basis = backend === "git" ? base.head ?? "unborn" : "files";
+        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:${basis}:${randomUUID()}`);
+        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.backend = backend;
         this.provenanceByScope = {
             global: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta), "State Flow global metadata"),
             cwd: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta), "State Flow CWD metadata"),
@@ -125,73 +97,18 @@ export class TemporalRuntime {
         };
         return true;
     }
-    /** Explicit start owns directory/repository creation; reads never call this. */
-    prepare() {
-        const backend = detectGitCapability();
-        if (backend === "git")
-            initializeGitRepository(this.root);
-        else
-            initializeFileStore(this.root);
-        this.backend = backend;
-    }
-    /** Explicit start migrates a predecessor envelope even when passive restore already populated the cache. */
-    migrateLegacyStorage() {
-        if (!this.view || !this.backend || !hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey))
-            return undefined;
-        const publication = this.backend === "git"
-            ? migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey)
-            : (migrateLegacyStorageToFiles(this.cwd, this.sessionId, this.root, this.sessionKey), undefined);
-        const base = this.backend === "files"
-            ? captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey)
-            : captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
-        const files = new Map(base.files.map((file) => [file.path, file.content]));
-        const scopes = Object.fromEntries(SCOPES.map((scope) => {
-            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-            const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta));
-            if (!stream)
-                throw new Error(`State Flow ${scopeLabel(scope)} scope disappeared during migration`);
-            return [scope, stream];
-        }));
-        const migrated = { lineage: this.view.lineage, scopes };
-        validateTemporalState(migrated);
-        if (!sameJson(this.states(), {
-            global: readTemporalState(migrated, 0, "global"),
-            cwd: readTemporalState(migrated, 0, "cwd"),
-            session: readTemporalState(migrated, 0, "session"),
-        }))
-            throw new Error("State Flow migration changed materialized semantic state");
-        this.view = migrated;
-        this.base = base;
-        this.provenanceByScope = {
-            global: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta), "State Flow global metadata"),
-            cwd: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta), "State Flow CWD metadata"),
-            session: this.provenanceByScope.session,
-        };
-        if (publication?.commit)
-            this.semanticRevision = publication.commit;
+    /** Select canonical file acceptance even when Git is available; backup remains a later concern. */
+    prepareCanonical() {
+        initializeFileStore(this.root);
     }
-    /** Explicit start can upgrade a proven file cohort; failed adoption leaves the cache in file mode. */
-    promote(snapshot) {
-        if (this.backend !== "files" || !this.view || detectGitCapability() === "files")
-            return undefined;
-        if (!snapshot.meta.durableBase || snapshot.meta.durableBase !== this.semanticRevision)
-            throw new Error("Git adoption requires the selected file revision");
-        const pushRemote = (snapshot.meta.remotePublication?.mode ?? "transition") === "transition";
-        const result = adoptFileStateToGit(this.cwd, this.sessionId, this.root, snapshot.meta.durableBase, snapshot, this.sessionKey, pushRemote);
-        this.provenanceByScope = structuredClone(result.provenance);
-        const savedRuntime = hashJson(createSessionRuntime(snapshot, this.cwd, this.sessionId, result.view.lineage, "unconfirmed", this.provenanceByScope.session));
-        this.view = result.view;
-        this.base = result.base;
-        this.backend = "git";
-        this.semanticRevision = result.revision;
-        this.savedRuntime = savedRuntime;
-        this.absentSharedScopes.clear();
-        return result;
+    /** Canonical preparation is the default; Git backup is a later independent concern. */
+    prepare() {
+        this.prepareCanonical();
     }
     read(offset = 0, scope) {
         if (!this.view)
             throw new Error("State Flow temporal runtime is unavailable");
-        return readTemporalState(this.view, offset, scope);
+        return readTemporalState(this.view, offset, scope, this.historyLimit);
     }
     states() {
         return { global: this.read(0, "global"), cwd: this.read(0, "cwd"), session: this.read(0, "session") };
@@ -201,6 +118,15 @@ export class TemporalRuntime {
             throw new Error("State Flow temporal runtime is unavailable");
         return this.view.lineage.at(-1).id;
     }
+    /** Encode Pi lifecycle state against the current retained semantic boundary. */
+    retainedCheckpoint(snapshot) {
+        if (!this.view)
+            return { disabled: true };
+        return retainedBoundaryCheckpoint(snapshot, this.causalBasis());
+    }
+    usesCanonicalFiles() {
+        return true;
+    }
     recent() {
         const result = [];
         for (const boundary of this.view?.lineage.slice(1) ?? []) {
@@ -213,107 +139,115 @@ export class TemporalRuntime {
         }
         return result;
     }
-    /** Validate selection without installing state; only a matching immutable Git inspection is reusable. */
-    prepareRestore(revision, legacySnapshot) {
-        const inspected = inspectSnapshotRevision(this.cwd, this.sessionId, this.root, revision, legacySnapshot, this.sessionKey);
-        const selected = inspected.snapshot.meta.durableBase ?? revision;
+    /** Prepare a retained session boundary from current canonical files; shared scopes remain live. */
+    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);
+        const files = new Map(base.files.map((file) => [file.path, file.content]));
+        const scopes = Object.fromEntries(SCOPES.map((scope) => {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta));
+            if (!stream)
+                throw new RevisionUnavailableError(`State Flow ${scopeLabel(scope)} scope is unavailable for retained-boundary restoration`);
+            return [scope, stream];
+        }));
+        const runtimePaths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
+        const document = parseSessionRuntime(files.get(runtimePaths.config), files.get(runtimePaths.runtime), this.cwd, this.sessionId);
+        if (!document)
+            throw new RevisionUnavailableError("State Flow session runtime is unavailable for retained-boundary restoration");
+        // The codecs validate persisted retention against the format maximum, not the new operator limit.
+        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");
+        const selectedSession = selectScopeStreamAtBoundary(scopes.session, "session", boundary, MAX_HISTORY_LIMIT);
+        const view = adoptTemporalStreams({
+            global: scopes.global,
+            cwd: scopes.cwd,
+            session: selectedSession,
+        }, `restore:${checkpoint.boundary}:${randomUUID()}`, this.historyLimit);
+        const snapshot = {
+            config: { enabled: checkpoint.enabled },
+            meta: {
+                step: checkpoint.step,
+                ...(checkpoint.bootstrap === true ? { bootstrap: true } : {}),
+                ...(checkpoint.specification === undefined ? {} : { specification: checkpoint.specification }),
+            },
+        };
+        const provenance = Object.fromEntries(SCOPES.map((scope) => {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            const parsed = parseScopeProvenance(files.get(paths.meta), paths.meta);
+            const retained = pruneArtifactProvenance(parsed, readTemporalState(view, 0, scope, this.historyLimit).artifacts);
+            if (scope === "session") {
+                // Live evidence cannot prove an earlier artifact version, even after a change-away-and-back.
+                for (const record of scopes.session.patches) {
+                    if (record.transition.position <= boundary.position)
+                        continue;
+                    for (const path of Object.keys(record.patch.artifacts ?? {}))
+                        delete retained[path];
+                }
+            }
+            return [scope, retained];
+        }));
         let consumed = false;
         return {
-            snapshot: structuredClone(inspected.snapshot),
+            snapshot: structuredClone(snapshot),
             restore: () => {
                 if (consumed)
                     throw new Error("Prepared State Flow restore was already consumed");
                 consumed = true;
-                // File cohorts can expire; legacy migration and owner redirection keep their fresh-read path.
-                return inspected.temporal && selected === revision
-                    ? this.restoreInspected(revision, inspected)
-                    : this.restore(selected, inspected.snapshot);
+                this.view = view;
+                this.base = base;
+                this.provenanceByScope = provenance;
+                this.semanticRevision = undefined;
+                this.savedRuntime = hashJson(createSessionRuntime(snapshot, this.cwd, this.sessionId, view.lineage, provenance.session));
+                this.restoredOriginPending = true;
+                this.absentSharedScopes.clear();
+                return structuredClone(snapshot);
             },
         };
     }
-    /** Copy only a proven source session stream; shared streams come from the child's fresh live basis. */
-    prepareFork(source, revision) {
+    /** Restore and canonically accept one retained boundary as a single lifecycle operation. */
+    restoreBoundary(checkpoint) {
+        const prepared = this.prepareBoundaryRestore(checkpoint);
+        const snapshot = prepared.restore();
+        return { snapshot, publication: this.acceptRestoredOrigin(snapshot) };
+    }
+    /** Copy one retained source-session boundary over the child's current shared scopes. */
+    prepareBoundaryFork(source, checkpoint) {
         const parent = Object.freeze({ ...source });
         if (parent.id === this.sessionId || parent.key === this.sessionKey)
             throw new Error("State Flow fork requires a distinct session identity and key");
-        const inspect = () => inspectSnapshotRevision(this.cwd, parent.id, this.root, revision, undefined, parent.key);
-        const inspected = inspect();
+        const sourceRuntime = new TemporalRuntime(this.cwd, parent, this.root, undefined, this.historyLimit);
+        const prepared = sourceRuntime.prepareBoundaryRestore(checkpoint);
+        prepared.restore();
         const snapshot = {
-            config: structuredClone(inspected.snapshot.config),
+            config: structuredClone(prepared.snapshot.config),
             meta: {
                 step: 0,
-                ...(inspected.snapshot.meta.bootstrap === undefined ? {} : { bootstrap: inspected.snapshot.meta.bootstrap }),
-                ...(inspected.snapshot.meta.remotePublication === undefined ? {} : { remotePublication: structuredClone(inspected.snapshot.meta.remotePublication) }),
+                ...(prepared.snapshot.meta.bootstrap === undefined ? {} : { bootstrap: prepared.snapshot.meta.bootstrap }),
             },
         };
         let consumed = false;
         return {
-            snapshot: { ...structuredClone(snapshot), meta: { ...structuredClone(snapshot.meta), durableBase: revision } },
+            snapshot: structuredClone(snapshot),
             fork: () => {
                 if (consumed)
                     throw new Error("Prepared State Flow fork was already consumed");
                 consumed = true;
                 if (this.view)
                     throw new Error("State Flow fork target already has session storage");
-                // Unlike immutable Git input, a file-only source must still match its complete cohort.
-                const current = inspected.file ? inspect() : inspected;
-                const selected = current.temporal ?? current.file;
-                if (!selected)
-                    throw new Error("State Flow fork requires a temporal session stream");
                 const publication = this.initializeOrigin(snapshot, { allowCreateCwd: false, copy: {
-                        stream: selected.view.scopes.session,
-                        provenance: selected.provenance.session,
-                        backend: current.file ? "files" : "git",
+                        stream: sourceRuntime.view.scopes.session,
+                        provenance: sourceRuntime.artifactProvenance("session"),
                     } });
-                const ownedRevision = publication?.revision ?? publication?.commit;
-                if (!publication || !ownedRevision)
+                if (!publication?.revision)
                     throw new Error("State Flow fork requires existing shared scope storage");
-                return { snapshot: { ...structuredClone(snapshot), meta: { ...structuredClone(snapshot.meta), durableBase: ownedRevision } }, publication };
+                return { snapshot: structuredClone(snapshot), publication };
             },
         };
     }
-    restore(revision, legacySnapshot) {
-        return this.restoreInspected(revision, inspectSnapshotRevision(this.cwd, this.sessionId, this.root, revision, legacySnapshot, this.sessionKey));
-    }
-    restoreInspected(revision, inspected) {
-        if (inspected.file) {
-            const savedRuntime = hashJson(createSessionRuntime(inspected.snapshot, this.cwd, this.sessionId, inspected.file.view.lineage, "files", inspected.file.provenance.session));
-            this.view = inspected.file.view;
-            this.base = inspected.file.base;
-            this.backend = "files";
-            this.provenanceByScope = structuredClone(inspected.file.provenance);
-            this.semanticRevision = revision;
-            this.savedRuntime = savedRuntime;
-            this.absentSharedScopes.clear();
-            return inspected.snapshot;
-        }
-        const loaded = inspected.temporal;
-        const { resolved, view } = loaded;
-        let base = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
-        const reference = loaded.runtime.document.meta.temporalRevision;
-        let semanticRevision = reference === undefined || reference === "self" ? loaded.runtime.revision : reference;
-        let publicationTarget = resolved.publicationTarget;
-        resolved.snapshot.meta.durableBase = publicationTarget;
-        const savedRuntime = hashJson(createSessionRuntime(resolved.snapshot, this.cwd, this.sessionId, view.lineage));
-        resolved.snapshot.meta.pendingPublication = { commit: publicationTarget, error: "Durable publication intent is unconfirmed" };
-        {
-            try {
-                if (isLocalGitRepository(this.root))
-                    delete resolved.snapshot.meta.pendingPublication;
-            }
-            catch {
-                // Invalid remote/branch configuration retains unconfirmed publication for explicit retry.
-            }
-        }
-        this.view = view;
-        this.base = base;
-        this.backend = "git";
-        this.provenanceByScope = structuredClone(loaded.provenance);
-        this.semanticRevision = semanticRevision;
-        this.savedRuntime = savedRuntime;
-        this.absentSharedScopes.clear();
-        return resolved.snapshot;
-    }
     initialize(snapshot, allowCreateCwd, expectedShared, newSessionOrigin = false) {
         return this.initializeOrigin(snapshot, { allowCreateCwd, expectedShared, newSessionOrigin });
     }
@@ -322,35 +256,23 @@ export class TemporalRuntime {
         const hasCwd = hasCwdMaterialization(this.cwd, this.root);
         if (!allowCreateCwd && !hasCwd)
             return undefined;
-        const backend = copy?.backend ?? this.backend ?? (detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files");
-        if (!copy && backend === "git") {
-            if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
-                migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey);
-            }
-        }
-        else if (!copy) {
-            if (allowCreateCwd)
-                initializeFileStore(this.root);
-            if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
-                migrateLegacyStorageToFiles(this.cwd, this.sessionId, this.root, this.sessionKey);
-            }
-        }
-        const base = backend === "git" ? captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey) : captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        if (!copy && allowCreateCwd)
+            initializeFileStore(this.root);
+        const base = captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
         const files = new Map(base.files.map((file) => [file.path, file.content]));
         if (copy) {
             const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
             const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "runtime.json"), join(session.directory, "state.json")];
             const occupied = owned.some((path) => files.get(path) !== undefined);
-            const historical = !occupied && backend === "git" && base.head ? loadTemporalRevision(this.cwd, this.sessionId, this.root, base.head, this.sessionKey) : undefined;
-            if (occupied || historical?.runtime || historical?.scopes.session) {
+            if (occupied) {
                 throw new Error("State Flow fork target already has session storage");
             }
         }
         if (SCOPES.some((scope) => {
             const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
-            return files.get(join(paths.directory, "state.json")) !== undefined;
+            return lstatSync(join(paths.directory, "state.json"), { throwIfNoEntry: false }) !== undefined;
         }))
-            throw new Error("Legacy State Flow storage changed during initialization; retry migration from a fresh basis");
+            throw new Error("Unsupported State Flow storage exists; preserve or convert it before initialization");
         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))];
@@ -360,19 +282,18 @@ export class TemporalRuntime {
         if (copy && !streams.global)
             throw new Error("State Flow fork requires existing shared scope storage");
         const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
-        const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), this.cwd, this.sessionId, files.get(paths.meta));
+        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 a branch revision pointer");
+            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.
         if (newSessionOrigin)
             streams.session = undefined;
         if (copy)
             streams.session = copy.stream;
-        const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID());
-        const candidate = new TemporalRuntime(this.cwd, this.session, this.root);
-        candidate.backend = backend;
+        const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID(), this.historyLimit);
+        const candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
         candidate.base = base;
-        candidate.view = adoptTemporalStreams({ global: streams.global ?? fresh.scopes.global, cwd: streams.cwd ?? fresh.scopes.cwd, session: streams.session ?? fresh.scopes.session }, `${base.head ?? "unborn"}:${randomUUID()}`);
+        candidate.view = adoptTemporalStreams({ global: streams.global ?? fresh.scopes.global, cwd: streams.cwd ?? fresh.scopes.cwd, session: streams.session ?? fresh.scopes.session }, `files:${randomUUID()}`, this.historyLimit);
         const globalMeta = temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta;
         const cwdMeta = temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta;
         candidate.provenanceByScope = {
@@ -381,27 +302,23 @@ export class TemporalRuntime {
             session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} : parseScopeProvenance(files.get(paths.meta), paths.meta),
         };
         if (expectedShared && ["global", "cwd"].some((scope) => !sameJson(candidate.read(0, scope), expectedShared[scope]))) {
-            throw new Error("Legacy branch shared scopes diverged from the selected revision; migration cannot overwrite them");
+            throw new Error("Selected branch shared scopes diverged from the live revision");
         }
         const publication = copy ? candidate.publishForkOrigin(snapshot) : candidate.publish(snapshot, true);
         this.view = candidate.view;
         this.base = candidate.base;
-        this.backend = backend;
         this.provenanceByScope = structuredClone(candidate.provenanceByScope);
         this.semanticRevision = candidate.semanticRevision;
         this.savedRuntime = candidate.savedRuntime;
         this.absentSharedScopes.clear();
         return publication;
     }
-    /** Initial copy owns only the new session files, without pruning or rewriting shared provenance. */
+    /** 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.backend === "files" ? "files" : "unconfirmed", this.provenanceByScope.session);
-        const result = this.backend === "files"
-            ? publishTemporalStateToFiles(this.cwd, this.sessionId, this.view, ["session"], this.base, this.root, runtime, this.sessionKey, this.provenanceByScope)
-            : publishTemporalStateToGit(this.cwd, this.sessionId, this.view, ["session"], this.base, this.root, runtime, this.sessionKey, (snapshot.meta.remotePublication?.mode ?? "transition") === "transition", this.provenanceByScope);
-        const publication = result;
+        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);
         this.base = publication.base;
-        this.semanticRevision = publication.revision ?? publication.commit;
+        this.semanticRevision = publication.revision;
         this.savedRuntime = hashJson(runtime);
         return publication;
     }
@@ -414,10 +331,9 @@ export class TemporalRuntime {
      * session or runtime files also fails closed under the existing race rule.
      */
     reconcileSharedDrift(changedScopes) {
-        const captured = this.backend === "files"
-            ? captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey)
-            : captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        const captured = 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();
         for (const scope of SHARED_SCOPES) {
             const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
@@ -438,10 +354,12 @@ export class TemporalRuntime {
         const targets = [];
         const removedTargets = [];
         const absentScopes = [];
-        const head = "head" in captured ? captured.head : undefined;
-        const reconciliation = `${head ?? "files"}:reconcile:${randomUUID()}`;
+        const reconciliation = `files:reconcile:${randomUUID()}`;
         for (const scope of SHARED_SCOPES) {
             const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            // A cached reader may fold wider live tails without owning a semantic write.
+            if ([paths.checkpoint, paths.patches, paths.meta].every((path) => liveFiles.get(path)?.identity === priorFiles.get(path)?.identity))
+                continue;
             const presence = classifyScopeStream(liveFiles.get(paths.checkpoint)?.content, liveFiles.get(paths.patches)?.content, scope, scope === "cwd" ? this.cwd : undefined, liveFiles.get(paths.meta)?.content);
             if (presence.kind === "absent") {
                 absentScopes.push(scope);
@@ -449,7 +367,7 @@ export class TemporalRuntime {
                 if (changedScopes.has(scope) && !this.absentSharedScopes.has(scope))
                     removedTargets.push(scope);
                 if (!this.absentSharedScopes.has(scope)) {
-                    adopted.set(scope, freshEmptyScopeStream(scope, `${reconciliation}:${scope}:absent`));
+                    adopted.set(scope, freshEmptyScopeStream(scope, `${reconciliation}:${scope}:absent`, this.historyLimit));
                 }
                 continue;
             }
@@ -471,7 +389,7 @@ export class TemporalRuntime {
             global: adopted.get("global") ?? structuredClone(this.view.scopes.global),
             cwd: adopted.get("cwd") ?? structuredClone(this.view.scopes.cwd),
             session: structuredClone(this.view.scopes.session),
-        }, reconciliation);
+        }, reconciliation, this.historyLimit);
         if (removedTargets.length > 0) {
             this.view = reconciledView();
             this.base = captured;
@@ -484,18 +402,28 @@ export class TemporalRuntime {
             throw targetScopeConflict(targets);
         return { view: reconciledView(), base: captured, provenance };
     }
+    /** Canonically accept a prepared retained-boundary origin before lifecycle-only persistence. */
+    acceptRestoredOrigin(snapshot) {
+        if (!this.restoredOriginPending)
+            throw new Error("State Flow has no prepared restored origin to accept");
+        const publication = this.publish(snapshot, true);
+        if (!publication)
+            throw new Error("State Flow restored origin produced no canonical publication");
+        this.restoredOriginPending = false;
+        return publication;
+    }
     publish(snapshot, semantic = false, accepted, options = {}) {
         if (!this.view || !this.base)
             throw new Error("State Flow temporal publication is unavailable; restore or initialize before accepting a transition");
-        // Activation and terminal policy: only the legacy transition mode publishes synchronously.
-        const pushRemote = options.pushRemote ?? (snapshot.meta.remotePublication?.mode ?? "transition") === "transition";
-        const provenanceScopes = SCOPES.filter((scope) => Object.entries(options.provenance?.[scope] ?? {})
-            .some(([path, entry]) => this.provenanceByScope[scope][path] === undefined
-            || !sameJson(this.provenanceByScope[scope][path], entry)));
+        if (this.restoredOriginPending && !semantic)
+            throw new Error("State Flow restored origin must be accepted before runtime-only persistence");
+        // Explicit evidence updates still own a scope CAS, even if they equal the stale cache.
+        const provenanceScopes = SCOPES.filter((scope) => Object.keys(options.provenance?.[scope] ?? {}).length > 0);
+        const runtimeOnly = !semantic && accepted === undefined && provenanceScopes.length === 0;
         let basis = this.view;
         let base = this.base;
         let basisProvenance = this.provenanceByScope;
-        if ((semantic || provenanceScopes.length > 0) && this.semanticRevision) {
+        if (this.semanticRevision) {
             const changedScopes = new Set([
                 ...(accepted?.transitions ?? []).map(({ scope }) => scope),
                 ...provenanceScopes,
@@ -505,7 +433,7 @@ export class TemporalRuntime {
             base = reconciled.base;
             basisProvenance = reconciled.provenance;
         }
-        const next = accepted ? advanceTemporalState(basis, accepted.transitions, accepted.id) : basis;
+        const next = accepted ? advanceTemporalState(basis, accepted.transitions, accepted.id, this.historyLimit) : basis;
         const nextProvenance = structuredClone(basisProvenance);
         for (const scope of SCOPES) {
             const updates = options.provenance?.[scope];
@@ -513,45 +441,21 @@ export class TemporalRuntime {
                 for (const [path, entry] of Object.entries(updates))
                     nextProvenance[scope][path] = structuredClone(entry);
         }
-        for (const scope of SCOPES) {
-            nextProvenance[scope] = pruneArtifactProvenance(nextProvenance[scope], readTemporalState(next, 0, scope).artifacts);
-        }
+        if (!runtimeOnly)
+            for (const scope of SCOPES) {
+                nextProvenance[scope] = pruneArtifactProvenance(nextProvenance[scope], readTemporalState(next, 0, scope, this.historyLimit).artifacts);
+            }
         const provenanceChanged = !sameJson(nextProvenance, this.provenanceByScope);
-        const scopedWrite = semantic || provenanceChanged;
-        const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, next.lineage, this.backend === "files" ? "files" : "unconfirmed", nextProvenance.session);
+        const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, next.lineage, nextProvenance.session);
         const fingerprint = hashJson(runtime);
         if (!semantic && fingerprint === this.savedRuntime && !provenanceChanged)
             return undefined;
-        if (this.backend === "files") {
-            runtime.meta.temporalRevision = "self";
-            const result = publishTemporalStateToFiles(this.cwd, this.sessionId, next, semantic ? SCOPES : [], base, this.root, runtime, this.sessionKey, nextProvenance);
-            this.base = result.base;
-            this.view = next;
-            this.provenanceByScope = nextProvenance;
-            this.savedRuntime = fingerprint;
-            this.semanticRevision = result.revision;
-            if (semantic)
-                this.absentSharedScopes.clear();
-            return { base: result.base, revision: result.revision };
-        }
-        if (!scopedWrite) {
-            const current = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
-            const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
-            for (const path of [paths.config, paths.runtime]) {
-                if (current.files.find((file) => file.path === path)?.identity !== base.files.find((file) => file.path === path)?.identity) {
-                    throw new Error("Temporal State Flow runtime changed concurrently");
-                }
-            }
-            base = current;
-        }
-        runtime.meta.temporalRevision = scopedWrite ? "self" : this.semanticRevision;
-        const result = publishTemporalStateToGit(this.cwd, this.sessionId, next, semantic ? SCOPES : provenanceChanged ? provenanceScopes : [], base, this.root, runtime, this.sessionKey, pushRemote, nextProvenance);
+        const result = 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;
         this.savedRuntime = fingerprint;
-        if (scopedWrite && result.commit)
-            this.semanticRevision = result.commit;
+        this.semanticRevision = result.revision;
         if (semantic)
             this.absentSharedScopes.clear();
         return result;