@llblab/pi-kit 0.13.0 → 0.14.1

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

@@ -0,0 +1,142 @@
+import { type SessionAddress } from "./durable.ts";
+import { type ArtifactProvenance, type ArtifactProvenanceRegistry } from "./artifact.ts";
+import { publishTemporalStateToGit } from "./git.ts";
+import { type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
+import { type Snapshot } from "./snapshot.ts";
+import { type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
+import { type ScopeStream, type TemporalState } from "./temporal.ts";
+export type RuntimePublication = ReturnType<typeof publishTemporalStateToGit> & {
+    revision?: string;
+};
+/** A targeted removed scope was deliberately adopted as empty before refusing the stale semantic patch. */
+export declare class SharedScopeRemovalConflictError extends Error {
+    readonly scopes: readonly StateScope[];
+    constructor(scopes: readonly StateScope[]);
+}
+export declare class MissingSessionRuntimeError extends Error {
+    constructor();
+}
+/** Immutable target validation is independent of acquiring the live publication basis. */
+export declare function inspectRuntimeRevision(cwd: string, sessionId: string, root: string, revision: string, sessionKey?: string): {
+    runtime: {
+        document: import("./snapshot.ts").SessionRuntime;
+        revision: string;
+    };
+    resolved: {
+        snapshot: Snapshot;
+        lineage: import("./temporal.ts").TransitionBoundary[];
+        publicationTarget: string;
+        artifacts: ArtifactProvenanceRegistry;
+    };
+    view: {
+        lineage: import("./temporal.ts").TransitionBoundary[];
+        scopes: {
+            global: ScopeStream;
+            cwd: ScopeStream;
+            session: ScopeStream;
+        };
+    };
+    provenance: Record<StateScope, ArtifactProvenanceRegistry>;
+};
+/** Validate one supported immutable target before any live migration/publication. */
+export declare function inspectSnapshotRevision(cwd: string, sessionId: string, root: string, revision: string, _legacySnapshot?: Snapshot, sessionKey?: string): {
+    snapshot: import("./snapshot.ts").StateFlowSnapshot;
+    file: {
+        runtime: import("./snapshot.ts").SessionRuntime;
+        view: {
+            scopes: Record<StateScope, ScopeStream>;
+            lineage: import("./temporal.ts").TransitionBoundary[];
+        };
+        provenance: Record<StateScope, ArtifactProvenanceRegistry>;
+        base: {
+            files: import("./durable.ts").DurableFileBase[];
+        };
+        revision: `file:${string}`;
+    };
+    temporal?: undefined;
+} | {
+    file?: undefined;
+    snapshot: import("./snapshot.ts").StateFlowSnapshot;
+    temporal: {
+        runtime: {
+            document: import("./snapshot.ts").SessionRuntime;
+            revision: string;
+        };
+        resolved: {
+            snapshot: Snapshot;
+            lineage: import("./temporal.ts").TransitionBoundary[];
+            publicationTarget: string;
+            artifacts: ArtifactProvenanceRegistry;
+        };
+        view: {
+            lineage: import("./temporal.ts").TransitionBoundary[];
+            scopes: {
+                global: ScopeStream;
+                cwd: ScopeStream;
+                session: ScopeStream;
+            };
+        };
+        provenance: Record<StateScope, ArtifactProvenanceRegistry>;
+    };
+};
+/** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
+export declare class TemporalRuntime {
+    view: TemporalState | undefined;
+    private base;
+    private semanticRevision;
+    private savedRuntime;
+    private backend;
+    private provenanceByScope;
+    /** Shared scopes whose wholly absent live basis was accepted after one stale-target refusal. */
+    private readonly absentSharedScopes;
+    readonly cwd: string;
+    private readonly session;
+    readonly root: string;
+    constructor(cwd: string, session: string | SessionAddress, root: string, sessionKey?: string);
+    get sessionId(): string;
+    get sessionKey(): string;
+    /** Runtime-owned artifact freshness evidence for one scope; never model-visible state. */
+    artifactProvenance(scope: StateScope): ArtifactProvenanceRegistry;
+    /** Explicit start owns directory/repository creation; reads never call this. */
+    prepare(): void;
+    /** Explicit start migrates a predecessor envelope even when passive restore already populated the cache. */
+    migrateLegacyStorage(): void;
+    /** Explicit start can upgrade a proven file cohort; failed adoption leaves the cache in file mode. */
+    promote(snapshot: Snapshot): RuntimePublication | undefined;
+    read(offset?: number, scope?: StateScope): MaterializedState;
+    states(): ScopedStates;
+    causalBasis(): string;
+    recent(): RecentTransitionWindow;
+    /** Validate selection without installing state; only a matching immutable Git inspection is reusable. */
+    prepareRestore(revision: string, legacySnapshot?: Snapshot): {
+        snapshot: Snapshot;
+        restore: () => Snapshot;
+    };
+    /** Copy only a proven source session stream; shared streams come from the child's fresh live basis. */
+    prepareFork(source: SessionAddress, revision: string): {
+        snapshot: Snapshot;
+        fork: () => {
+            snapshot: Snapshot;
+            publication: RuntimePublication;
+        };
+    };
+    restore(revision: string, legacySnapshot?: Snapshot): Snapshot;
+    private restoreInspected;
+    initialize(snapshot: Snapshot, allowCreateCwd: boolean, expectedShared?: Pick<ScopedStates, "global" | "cwd">, newSessionOrigin?: boolean): RuntimePublication | undefined;
+    private initializeOrigin;
+    /** Initial copy owns only the new session files, without pruning or rewriting shared provenance. */
+    private publishForkOrigin;
+    /**
+     * Reconcile untouched shared-scope drift against the current proven live basis.
+     *
+     * A restored branch can lag behind live global/CWD state. Untouched shared scopes adopt
+     * the current live streams at a fresh origin; a shared scope the accepted transition
+     * actually changes remains a fail-closed write conflict. Divergence in non-adoptable
+     * session or runtime files also fails closed under the existing race rule.
+     */
+    private reconcileSharedDrift;
+    publish(snapshot: Snapshot, semantic?: boolean, accepted?: AcceptedTransition, options?: {
+        pushRemote?: boolean;
+        provenance?: Partial<Record<StateScope, Record<string, ArtifactProvenance>>>;
+    }): RuntimePublication | undefined;
+}

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

@@ -0,0 +1,529 @@
+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 { parseArtifactProvenanceRegistry, 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 { hashJson, sameJson } from "./json.js";
+import { hasCwdMaterialization, hasLegacyStateSources } from "./migration.js";
+import { RevisionUnavailableError, createSessionRuntime, isFileRevision, parseSessionRuntime, resolveFileSessionRuntime, resolveSessionRuntime } from "./snapshot.js";
+import { emptyState } from "./state.js";
+import { adoptTemporalStreams, advanceTemporalState, createTemporalState, readTemporalState, validateTemporalState } from "./temporal.js";
+const SCOPES = ["global", "cwd", "session"];
+const SHARED_SCOPES = ["global", "cwd"];
+function emptyProvenance() {
+    return { global: {}, cwd: {}, session: {} };
+}
+function scopeLabel(scope) {
+    return scope === "cwd" ? "CWD" : scope;
+}
+/** Precise fail-closed conflict for a shared scope this transition actually overwrites. */
+function targetScopeConflict(scopes) {
+    const labels = scopes.map(scopeLabel);
+    if (labels.length === 1) {
+        return new Error(`State Flow cannot publish the ${labels[0]} patch because the live ${labels[0]} state advanced after this transition's selected basis. Refresh or reconcile the target scope before retrying.`);
+    }
+    return new Error(`State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} states advanced after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
+}
+/** A targeted removed scope was deliberately adopted as empty before refusing the stale semantic patch. */
+export class SharedScopeRemovalConflictError extends Error {
+    scopes;
+    constructor(scopes) {
+        const labels = scopes.map(scopeLabel);
+        super(labels.length === 1
+            ? `State Flow cannot publish the ${labels[0]} patch because the live ${labels[0]} scope was removed after this transition's selected basis. Refresh or reconcile the target scope before retrying.`
+            : `State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} scopes were removed after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
+        this.name = "SharedScopeRemovalConflictError";
+        this.scopes = Object.freeze([...scopes]);
+    }
+}
+/** Disappearance invalidates a selected write target even though untouched scopes can adopt empty reality. */
+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 };
+}
+/** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
+export class TemporalRuntime {
+    view;
+    base;
+    semanticRevision;
+    savedRuntime;
+    backend;
+    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) {
+        this.cwd = cwd;
+        this.session = Object.freeze(typeof session === "string" ? { id: session, key: sessionKey ?? session } : { ...session });
+        this.root = root;
+    }
+    get sessionId() { return this.session.id; }
+    get sessionKey() { return this.session.key; }
+    /** Runtime-owned artifact freshness evidence for one scope; never model-visible state. */
+    artifactProvenance(scope) {
+        return structuredClone(this.provenanceByScope[scope]);
+    }
+    /** 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;
+    }
+    /** 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;
+    }
+    read(offset = 0, scope) {
+        if (!this.view)
+            throw new Error("State Flow temporal runtime is unavailable");
+        return readTemporalState(this.view, offset, scope);
+    }
+    states() {
+        return { global: this.read(0, "global"), cwd: this.read(0, "cwd"), session: this.read(0, "session") };
+    }
+    causalBasis() {
+        if (!this.view)
+            throw new Error("State Flow temporal runtime is unavailable");
+        return this.view.lineage.at(-1).id;
+    }
+    recent() {
+        const result = [];
+        for (const boundary of this.view?.lineage.slice(1) ?? []) {
+            const transitions = SCOPES.flatMap((scope) => {
+                const record = this.view.scopes[scope].patches.find(({ transition }) => transition.id === boundary.id);
+                return record ? [{ scope, patch: structuredClone(record.patch) }] : [];
+            });
+            if (transitions.length)
+                result.push({ id: boundary.id, at: boundary.position, transitions });
+        }
+        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;
+        let consumed = false;
+        return {
+            snapshot: structuredClone(inspected.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);
+            },
+        };
+    }
+    /** Copy only a proven source session stream; shared streams come from the child's fresh live basis. */
+    prepareFork(source, revision) {
+        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 snapshot = {
+            config: structuredClone(inspected.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) }),
+            },
+        };
+        let consumed = false;
+        return {
+            snapshot: { ...structuredClone(snapshot), meta: { ...structuredClone(snapshot.meta), durableBase: revision } },
+            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",
+                    } });
+                const ownedRevision = publication?.revision ?? publication?.commit;
+                if (!publication || !ownedRevision)
+                    throw new Error("State Flow fork requires existing shared scope storage");
+                return { snapshot: { ...structuredClone(snapshot), meta: { ...structuredClone(snapshot.meta), durableBase: ownedRevision } }, 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 });
+    }
+    initializeOrigin(snapshot, options) {
+        const { allowCreateCwd, expectedShared, newSessionOrigin = false, copy } = options;
+        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);
+        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, "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) {
+                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;
+        }))
+            throw new Error("Legacy State Flow storage changed during initialization; retry migration from a fresh basis");
+        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))];
+        }));
+        if (!streams.cwd && !allowCreateCwd)
+            return undefined;
+        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.meta), this.cwd, this.sessionId);
+        if (existingRuntime && !newSessionOrigin)
+            throw new Error("Existing session runtime requires a branch revision pointer");
+        // 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;
+        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()}`);
+        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 = {
+            global: parseScopeProvenance(files.get(globalMeta), globalMeta),
+            cwd: parseScopeProvenance(files.get(cwdMeta), cwdMeta),
+            session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} : parseArtifactProvenanceRegistry(existingRuntime?.meta.artifacts, "State Flow session artifact provenance"),
+        };
+        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");
+        }
+        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. */
+    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;
+        this.base = publication.base;
+        this.semanticRevision = publication.revision ?? publication.commit;
+        this.savedRuntime = hashJson(runtime);
+        return publication;
+    }
+    /**
+     * Reconcile untouched shared-scope drift against the current proven live basis.
+     *
+     * A restored branch can lag behind live global/CWD state. Untouched shared scopes adopt
+     * the current live streams at a fresh origin; a shared scope the accepted transition
+     * 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 = this.backend === "files"
+            ? captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey)
+            : captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        const liveFiles = new Map(captured.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);
+            adoptable.add(paths.checkpoint);
+            adoptable.add(paths.patches);
+            adoptable.add(paths.meta);
+        }
+        for (const file of this.base.files) {
+            if (adoptable.has(file.path))
+                continue;
+            const current = liveFiles.get(file.path);
+            if (current === undefined || current.identity !== file.identity) {
+                throw new Error("Temporal State Flow base or scope identity changed concurrently");
+            }
+        }
+        const provenance = structuredClone(this.provenanceByScope);
+        const adopted = new Map();
+        const targets = [];
+        const removedTargets = [];
+        const absentScopes = [];
+        const head = "head" in captured ? captured.head : undefined;
+        const reconciliation = `${head ?? "files"}:reconcile:${randomUUID()}`;
+        for (const scope of SHARED_SCOPES) {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            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);
+                provenance[scope] = {};
+                if (changedScopes.has(scope) && !this.absentSharedScopes.has(scope))
+                    removedTargets.push(scope);
+                if (!this.absentSharedScopes.has(scope)) {
+                    adopted.set(scope, freshEmptyScopeStream(scope, `${reconciliation}:${scope}:absent`));
+                }
+                continue;
+            }
+            const stream = presence.stream;
+            const liveProvenance = parseScopeProvenance(liveFiles.get(paths.meta)?.content, paths.meta);
+            const streamDrifted = !sameJson(stream, this.view.scopes[scope]);
+            const provenanceDrifted = !sameJson(liveProvenance, this.provenanceByScope[scope]);
+            if (!streamDrifted && !provenanceDrifted)
+                continue;
+            if (changedScopes.has(scope)) {
+                targets.push(scope);
+                continue;
+            }
+            provenance[scope] = liveProvenance;
+            if (streamDrifted)
+                adopted.set(scope, stream);
+        }
+        const reconciledView = () => adopted.size === 0 ? this.view : adoptTemporalStreams({
+            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);
+        if (removedTargets.length > 0) {
+            this.view = reconciledView();
+            this.base = captured;
+            this.provenanceByScope = provenance;
+            for (const scope of absentScopes)
+                this.absentSharedScopes.add(scope);
+            throw removedTargetScopeConflict(removedTargets);
+        }
+        if (targets.length > 0)
+            throw targetScopeConflict(targets);
+        return { view: reconciledView(), base: captured, provenance };
+    }
+    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)));
+        let basis = this.view;
+        let base = this.base;
+        let basisProvenance = this.provenanceByScope;
+        if ((semantic || provenanceScopes.length > 0) && this.semanticRevision) {
+            const changedScopes = new Set([
+                ...(accepted?.transitions ?? []).map(({ scope }) => scope),
+                ...provenanceScopes,
+            ]);
+            const reconciled = this.reconcileSharedDrift(changedScopes);
+            basis = reconciled.view;
+            base = reconciled.base;
+            basisProvenance = reconciled.provenance;
+        }
+        const next = accepted ? advanceTemporalState(basis, accepted.transitions, accepted.id) : basis;
+        const nextProvenance = structuredClone(basisProvenance);
+        for (const scope of SCOPES) {
+            const updates = options.provenance?.[scope];
+            if (updates)
+                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);
+        }
+        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 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.meta]) {
+                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);
+        this.base = result.base;
+        this.view = next;
+        this.provenanceByScope = nextProvenance;
+        this.savedRuntime = fingerprint;
+        if (scopedWrite && result.commit)
+            this.semanticRevision = result.commit;
+        if (semantic)
+            this.absentSharedScopes.clear();
+        return result;
+    }
+}