@llblab/pi-kit 0.13.0 → 0.14.0

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

@@ -0,0 +1,111 @@
+export type ContinuationTransport = "local" | "sdk" | "telegram" | string;
+export interface ContinuationHostContext {
+    cwd: string;
+    agentDir: string;
+    sessionDir: string;
+    transport: ContinuationTransport;
+}
+export type ContinuationHostIntent = {
+    kind: "default";
+} | {
+    kind: "new";
+} | {
+    kind: "resume-exact";
+    sessionFile: string;
+    sessionId: string;
+} | {
+    kind: "native-picker";
+} | {
+    kind: "continue-recent";
+} | {
+    kind: "no-session";
+};
+export interface ContinuationCandidateSummary {
+    sessionFile: string;
+    sessionId: string;
+    lastActivity: string;
+    reason: string;
+}
+export type ContinuationRecommendation = {
+    action: "resume";
+    sessionFile: string;
+    sessionId: string;
+    reason: "latest-enabled-state-flow";
+} | {
+    action: "choose";
+    candidates: ContinuationCandidateSummary[];
+    reason: "ambiguous";
+} | {
+    action: "new";
+    reason: "none" | "last-not-state-flow" | "ineligible";
+};
+export type ContinuationStartupDecision = ContinuationRecommendation | {
+    action: "new";
+    reason: "explicit-new";
+} | {
+    action: "resume";
+    sessionFile: string;
+    sessionId: string;
+    reason: "explicit-resume";
+} | {
+    action: "native";
+    mode: "picker" | "continue-recent" | "no-session";
+};
+export interface ContinuationProjectIdentity {
+    profile: string;
+    cwd: string;
+    gitCommonDir?: string;
+    worktree?: string;
+    branch?: string;
+    transport: ContinuationTransport;
+}
+export interface ContinuationSessionCandidate extends ContinuationCandidateSummary {
+    profile: string;
+    cwd: string;
+    gitCommonDir?: string;
+    worktree?: string;
+    branch?: string;
+    transport: ContinuationTransport;
+    lifecycle: "open" | "closed" | "archived";
+    doNotAutoResume?: boolean;
+    stateFlow: {
+        enabled: boolean;
+        restorable: boolean;
+    };
+}
+export type ContinuationRecommender = (context: Readonly<ContinuationHostContext>) => ContinuationRecommendation | Promise<ContinuationRecommendation>;
+/** Rank already header/provenance-only candidates without transcript content or I/O. */
+export declare function recommendContinuationFromProvenance(identity: ContinuationProjectIdentity, candidates: readonly ContinuationSessionCandidate[]): ContinuationRecommendation;
+export declare function resolveContinuationStartup(context: ContinuationHostContext, intent: ContinuationHostIntent, recommend: ContinuationRecommender): Promise<ContinuationStartupDecision>;
+export interface NativeSessionHeader {
+    file: string;
+    id: string;
+    cwd: string;
+    timestamp: string;
+    lastActivity: string;
+}
+export interface ContinuationCandidateProvenance {
+    profile: string;
+    gitCommonDir?: string;
+    worktree?: string;
+    branch?: string;
+    transport: ContinuationTransport;
+    lifecycle: "open" | "closed" | "archived";
+    doNotAutoResume?: boolean;
+    stateFlow: {
+        enabled: boolean;
+        restorable: boolean;
+    };
+    reason: string;
+}
+export declare function readNativeSessionHeader(path: string): NativeSessionHeader;
+export declare function discoverNativeSessionHeaders(sessionDir: string): {
+    headers: NativeSessionHeader[];
+    invalid: Array<{
+        file: string;
+        error: string;
+    }>;
+};
+/** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
+export declare function inspectStateFlowContinuationProvenance(header: NativeSessionHeader, repositoryRoot: string): Pick<ContinuationCandidateProvenance, "stateFlow" | "reason">;
+export declare function buildContinuationCandidates(headers: readonly NativeSessionHeader[], inspect: (header: Readonly<NativeSessionHeader>) => ContinuationCandidateProvenance | undefined): ContinuationSessionCandidate[];

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

@@ -0,0 +1,189 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { loadScopeStream, resolveSessionAddress, sessionRuntimePaths } from "./durable.js";
+import { loadTemporalRevision } from "./git.js";
+import { parseSessionRuntime } from "./snapshot.js";
+import { validateTemporalState } from "./temporal.js";
+/**
+ * Preserve host-owned explicit session intent and consult State Flow only for
+ * an ordinary default launch. The recommender is a read-only advisory port;
+ * opening or claiming a native session remains the host's responsibility.
+ */
+function sameOptionalIdentity(current, candidate) {
+    return current === undefined ? candidate === undefined : candidate === current;
+}
+function structurallyRelevant(identity, candidate) {
+    return candidate.profile === identity.profile
+        && candidate.cwd === identity.cwd
+        && candidate.transport === identity.transport
+        && candidate.lifecycle === "open"
+        && candidate.doNotAutoResume !== true
+        && sameOptionalIdentity(identity.gitCommonDir, candidate.gitCommonDir)
+        && sameOptionalIdentity(identity.worktree, candidate.worktree)
+        && sameOptionalIdentity(identity.branch, candidate.branch)
+        && Number.isFinite(Date.parse(candidate.lastActivity));
+}
+/** Rank already header/provenance-only candidates without transcript content or I/O. */
+export function recommendContinuationFromProvenance(identity, candidates) {
+    const relevant = candidates.filter((candidate) => structurallyRelevant(identity, candidate));
+    if (relevant.length === 0)
+        return { action: "new", reason: "none" };
+    const latestTime = Math.max(...relevant.map(({ lastActivity }) => Date.parse(lastActivity)));
+    const latest = relevant.filter(({ lastActivity }) => Date.parse(lastActivity) === latestTime)
+        .sort((left, right) => left.sessionFile.localeCompare(right.sessionFile));
+    if (latest.length > 1) {
+        const resumable = latest.filter(({ stateFlow }) => stateFlow.enabled && stateFlow.restorable);
+        if (resumable.length > 1)
+            return { action: "choose", reason: "ambiguous", candidates: resumable.map(({ sessionFile, sessionId, lastActivity }) => ({ sessionFile, sessionId, lastActivity, reason: "equally recent enabled State Flow session" })) };
+        if (resumable.length === 1 && latest.every(({ stateFlow }) => stateFlow.enabled && stateFlow.restorable)) {
+            const candidate = resumable[0];
+            return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
+        }
+        return { action: "new", reason: "ineligible" };
+    }
+    const candidate = latest[0];
+    if (!candidate.stateFlow.enabled)
+        return { action: "new", reason: "last-not-state-flow" };
+    if (!candidate.stateFlow.restorable)
+        return { action: "new", reason: "ineligible" };
+    return { action: "resume", sessionFile: candidate.sessionFile, sessionId: candidate.sessionId, reason: "latest-enabled-state-flow" };
+}
+export async function resolveContinuationStartup(context, intent, recommend) {
+    switch (intent.kind) {
+        case "new":
+            return { action: "new", reason: "explicit-new" };
+        case "resume-exact":
+            return { action: "resume", sessionFile: intent.sessionFile, sessionId: intent.sessionId, reason: "explicit-resume" };
+        case "native-picker":
+            return { action: "native", mode: "picker" };
+        case "continue-recent":
+            return { action: "native", mode: "continue-recent" };
+        case "no-session":
+            return { action: "native", mode: "no-session" };
+        case "default":
+            return recommend(Object.freeze({ ...context }));
+    }
+}
+const MAX_SESSION_HEADER_BYTES = 64 * 1024;
+function readFirstLine(path) {
+    if (realpathSync(path) !== path || !lstatSync(path).isFile())
+        throw new Error("Native Pi session header requires a regular canonical file");
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        if (!fstatSync(fd).isFile())
+            throw new Error("Native Pi session header requires a regular file");
+        const bytes = [];
+        const byte = Buffer.allocUnsafe(1);
+        while (bytes.length <= MAX_SESSION_HEADER_BYTES) {
+            const count = readSync(fd, byte, 0, 1, null);
+            if (count === 0 || byte[0] === 0x0a)
+                break;
+            bytes.push(byte[0]);
+        }
+        if (bytes.length > MAX_SESSION_HEADER_BYTES)
+            throw new Error("Native Pi session header exceeds the safe discovery limit");
+        return Buffer.from(bytes).toString("utf8").replace(/\r$/, "");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readNativeSessionHeader(path) {
+    const file = resolve(path);
+    let value;
+    try {
+        value = JSON.parse(readFirstLine(file));
+    }
+    catch (error) {
+        throw new Error(`Cannot read native Pi session header: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("Invalid native Pi session header");
+    const header = value;
+    if (header.type !== "session" || typeof header.id !== "string" || header.id.trim().length === 0
+        || typeof header.cwd !== "string" || header.cwd.trim().length === 0
+        || typeof header.timestamp !== "string" || !Number.isFinite(Date.parse(header.timestamp))) {
+        throw new Error("Invalid native Pi session header");
+    }
+    const stats = statSync(file);
+    return { file, id: header.id, cwd: resolve(header.cwd), timestamp: header.timestamp, lastActivity: stats.mtime.toISOString() };
+}
+export function discoverNativeSessionHeaders(sessionDir) {
+    const headers = [];
+    const invalid = [];
+    for (const entry of readdirSync(sessionDir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+            continue;
+        const file = join(sessionDir, entry.name);
+        try {
+            headers.push(readNativeSessionHeader(file));
+        }
+        catch (error) {
+            invalid.push({ file: resolve(file), error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { headers, invalid };
+}
+function readRegular(path) {
+    if (!existsSync(path))
+        return undefined;
+    if (!lstatSync(path).isFile())
+        throw new Error("State Flow continuation provenance must be a regular file");
+    return readFileSync(path, "utf8");
+}
+/** Inspect only exact current runtime provenance; never initialize, migrate, lock, checkout, or publish. */
+export function inspectStateFlowContinuationProvenance(header, repositoryRoot) {
+    const sessionKey = resolveSessionAddress(header.file, header.id, header.timestamp).key;
+    const paths = sessionRuntimePaths(header.cwd, header.id, repositoryRoot, sessionKey);
+    try {
+        const config = readRegular(paths.config);
+        const meta = readRegular(paths.meta);
+        if (config === undefined && meta === undefined) {
+            return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
+        }
+        const runtime = parseSessionRuntime(config, meta, header.cwd, header.id);
+        if (!runtime)
+            return { stateFlow: { enabled: false, restorable: true }, reason: "no State Flow session runtime" };
+        if (!runtime.config.enabled)
+            return { stateFlow: { enabled: false, restorable: true }, reason: "State Flow stopped on selected runtime" };
+        if (runtime.meta.publication === "files") {
+            const global = loadScopeStream(header.cwd, header.id, "global", repositoryRoot, sessionKey);
+            const cwd = loadScopeStream(header.cwd, header.id, "cwd", repositoryRoot, sessionKey);
+            const session = loadScopeStream(header.cwd, header.id, "session", repositoryRoot, sessionKey);
+            if (!global || !cwd || !session)
+                throw new Error("incomplete file-only temporal cohort");
+            validateTemporalState({ lineage: runtime.meta.lineage, scopes: { global, cwd, session } });
+            return { stateFlow: { enabled: true, restorable: true }, reason: "exact file-only runtime cohort is restorable" };
+        }
+        const runtimePath = relative(resolve(repositoryRoot), paths.meta);
+        if (runtimePath.startsWith(".."))
+            throw new Error("runtime provenance escapes repository");
+        const owner = execFileSync("git", ["-C", repositoryRoot, "log", "-1", "--format=%H", "--", runtimePath], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+        if (!owner)
+            throw new Error("runtime owner commit is unavailable");
+        const restored = loadTemporalRevision(header.cwd, header.id, repositoryRoot, owner, sessionKey);
+        if (!restored.runtime || !restored.runtime.document.config.enabled)
+            throw new Error("selected Git runtime is not enabled");
+        return { stateFlow: { enabled: true, restorable: true }, reason: `exact Git runtime ${owner.slice(0, 12)} is restorable` };
+    }
+    catch (error) {
+        return { stateFlow: { enabled: true, restorable: false }, reason: `State Flow runtime is ineligible: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export function buildContinuationCandidates(headers, inspect) {
+    const candidates = [];
+    for (const header of headers) {
+        const provenance = inspect(Object.freeze({ ...header }));
+        if (!provenance)
+            continue;
+        candidates.push({
+            sessionFile: header.file,
+            sessionId: header.id,
+            lastActivity: header.lastActivity,
+            cwd: header.cwd,
+            ...provenance,
+        });
+    }
+    return candidates;
+}

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

@@ -0,0 +1,21 @@
+import { type ArtifactSourceIdentity } from "./artifact.ts";
+/** Opaque source metadata discovered without decoding or retaining Markdown bodies. */
+export interface ArtifactSourceCandidate extends ArtifactSourceIdentity {
+    /** Raw byte count used as a conservative maintenance token-budget ceiling. */
+    bytes: number;
+}
+export interface GlobalMarkdownDiscoveryResult {
+    sources: ArtifactSourceCandidate[];
+    removed: string[];
+    unavailable?: string;
+}
+export declare function getKnowledgeRoot(agentDir?: string): string;
+/** Discover regular `*.md` files beneath a Knowledge root without following directory or file symlinks. */
+export declare function discoverGlobalMarkdownSources(knowledgeRoot?: string): ArtifactSourceCandidate[];
+/** Source-owner discovery; retained paths let restart/status re-observe removals until publication. */
+export declare class GlobalMarkdownDiscovery {
+    #private;
+    readonly knowledgeRoot: string;
+    constructor(knowledgeRoot?: string);
+    refresh(retainedPaths?: Iterable<string>): GlobalMarkdownDiscoveryResult;
+}

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

@@ -0,0 +1,125 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { hashArtifactSource } from "./artifact.js";
+export function getKnowledgeRoot(agentDir = getAgentDir()) {
+    return resolve(agentDir, "knowledge");
+}
+function errorCode(error) {
+    return error instanceof Error && "code" in error
+        ? error.code
+        : undefined;
+}
+function isMissing(error) {
+    return errorCode(error) === "ENOENT";
+}
+function isInside(root, path) {
+    const child = relative(root, path);
+    return child === "" || (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`));
+}
+function canonicalExistingPath(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+function readRegularFile(path) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        if (!fstatSync(descriptor).isFile())
+            return undefined;
+        return readFileSync(descriptor);
+    }
+    catch (error) {
+        if (isMissing(error) || errorCode(error) === "ELOOP")
+            return undefined;
+        throw error;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+/** Discover regular `*.md` files beneath a Knowledge root without following directory or file symlinks. */
+export function discoverGlobalMarkdownSources(knowledgeRoot = getKnowledgeRoot()) {
+    const configuredRoot = resolve(knowledgeRoot);
+    const root = canonicalExistingPath(configuredRoot);
+    if (root === undefined)
+        return [];
+    if (!statSync(root).isDirectory())
+        throw new Error(`Knowledge root is not a directory: ${configuredRoot}`);
+    const sources = [];
+    const visit = (directory) => {
+        const entries = readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const entry of entries) {
+            const candidate = join(directory, entry.name);
+            let metadata;
+            try {
+                metadata = lstatSync(candidate);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    continue;
+                throw error;
+            }
+            if (metadata.isSymbolicLink())
+                continue;
+            const canonical = canonicalExistingPath(candidate);
+            if (canonical === undefined || !isInside(root, canonical))
+                continue;
+            if (metadata.isDirectory()) {
+                visit(canonical);
+                continue;
+            }
+            if (!metadata.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            const body = readRegularFile(canonical);
+            if (body === undefined)
+                continue;
+            sources.push({ path: canonical, hash: hashArtifactSource(body), bytes: body.byteLength });
+        }
+    };
+    visit(root);
+    return sources.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+}
+/** Prove absence inside the current source root without following excluded symlink components. */
+function missingOwnedMarkdown(root, path) {
+    if (!isAbsolute(path) || path !== resolve(path) || path === root || !isInside(root, path) || !path.endsWith(".md"))
+        return false;
+    let candidate = root;
+    for (const segment of relative(root, path).split(sep)) {
+        candidate = join(candidate, segment);
+        const metadata = lstatSync(candidate, { throwIfNoEntry: false });
+        if (metadata === undefined)
+            return true;
+        if (metadata.isSymbolicLink() || !metadata.isDirectory())
+            return false;
+    }
+    return false;
+}
+/** Source-owner discovery; retained paths let restart/status re-observe removals until publication. */
+export class GlobalMarkdownDiscovery {
+    knowledgeRoot;
+    #knownPaths = new Set();
+    constructor(knowledgeRoot = getKnowledgeRoot()) {
+        this.knowledgeRoot = resolve(knowledgeRoot);
+    }
+    refresh(retainedPaths = this.#knownPaths) {
+        const root = canonicalExistingPath(this.knowledgeRoot);
+        if (root === undefined)
+            return { sources: [], removed: [], unavailable: `Knowledge root is unavailable: ${this.knowledgeRoot}` };
+        const sources = discoverGlobalMarkdownSources(root);
+        const currentPaths = new Set(sources.map((source) => source.path));
+        const removed = [...new Set(retainedPaths)]
+            .filter((path) => !currentPaths.has(path) && missingOwnedMarkdown(root, path))
+            .sort();
+        this.#knownPaths = currentPaths;
+        return { sources, removed };
+    }
+}

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

@@ -0,0 +1,102 @@
+import { type ArtifactProvenanceRegistry } from "./artifact.ts";
+import { type ScopeStream, type TemporalState } from "./temporal.ts";
+import type { StateScope } from "./state.ts";
+/** Canonical semantic sources plus runtime-owned temporal metadata. */
+export interface ScopeStreamSources {
+    checkpoint: string;
+    patches: string;
+    temporal: ScopeTemporalMetadata;
+}
+export interface ScopeTemporalMetadata {
+    checkpoint: ScopeStream["checkpoint"]["through"];
+    patches: ScopeStream["patches"][number]["transition"][];
+}
+export interface SessionAddress {
+    readonly id: string;
+    readonly key: string;
+}
+/** Semantic files contain no runtime envelope; temporal boundaries and CWD ownership live in meta.json. */
+export declare function serializeScopeStream(stream: ScopeStream, scope: StateScope, cwdIdentity?: string): ScopeStreamSources;
+export type ScopeStreamPresence = {
+    kind: "absent";
+} | {
+    kind: "present";
+    stream: ScopeStream;
+};
+/** Distinguish a wholly absent semantic cohort from partial or malformed surviving authority. */
+export declare function classifyScopeStream(checkpointSource: string | undefined, patchesSource: string | undefined, scope: StateScope, expectedCwd?: string, metaSource?: string): ScopeStreamPresence;
+/** Decode the entire bounded replay input before accepting any materialized state. */
+export declare function parseScopeStream(checkpointSource: string | undefined, patchesSource: string | undefined, scope: StateScope, expectedCwd?: string, metaSource?: string): ScopeStream | undefined;
+export interface TemporalScopePaths {
+    directory: string;
+    checkpoint: string;
+    patches: string;
+    /** Runtime-owned artifact provenance for this scope; the session file also owns runtime lineage. */
+    meta: string;
+}
+export declare function temporalScopePaths(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey?: string): TemporalScopePaths;
+export declare function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): {
+    config: string;
+    meta: string;
+};
+/** Unsupported state.json presence never becomes an anchored checkpoint. */
+export declare function loadScopeStream(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey?: string): ScopeStream | undefined;
+/** Include legacy names in the CAS basis solely to prevent format races during cutover. */
+export declare function captureTemporalFileBases(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): DurableFileBase[];
+/** Select exact serialized scope updates from one validated active temporal cohort. */
+export declare function temporalStateFileUpdates(cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[], repositoryRoot: string, sessionKey?: string): OwnedFileUpdate[];
+export interface DurablePaths {
+    repositoryRoot: string;
+    globalState: string;
+    globalPatches: string;
+}
+/** Merge authoritative owned leaves while preserving forward-compatible metadata siblings. */
+export declare function serializeScopeMetadata(registry: Readonly<ArtifactProvenanceRegistry> | undefined, stream: ScopeStream, scope: StateScope, cwdIdentity?: string, existingSource?: string): string;
+/** Compatibility serializer retained for metadata-only callers. */
+export declare function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string;
+/** Missing provenance is unavailable evidence, never corrupt state. Unknown metadata is preserved by writers. */
+export declare function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry;
+export interface ScopePaths {
+    directory: string;
+    state: string;
+    patches: string;
+}
+export interface DurableFileBase {
+    path: string;
+    identity: "missing" | `sha256:${string}`;
+    content?: string;
+    /** Opaque originals for byte-exact rollback, including non-UTF-8 legacy journals. */
+    bytes?: Uint8Array;
+}
+/** Dedicated runtime storage, independent from Markdown source discovery. */
+export declare function getDurableRepositoryRoot(agentDir?: string): string;
+/** Legacy snapshot paths retained only for one-way migration and exact ownership checks. */
+export declare function durablePaths(repositoryRoot?: string): DurablePaths;
+/** Match Pi's native project-session directory convention exactly. */
+export declare function cwdScopeKey(cwd: string): string;
+/** One safe directory segment, normally the native Pi session filename stem. */
+export declare function sessionScopeKey(key: string): string;
+/** Prefer the actual native file stem; reproduce it from the immutable header when in-memory. */
+export declare function sessionStorageKey(sessionFile: string | undefined, sessionId: string, timestamp?: string): string;
+export declare function resolveSessionAddress(sessionFile: string | undefined, sessionId: string, timestamp?: string): SessionAddress;
+export declare function cwdScopePaths(cwd: string, repositoryRoot?: string): ScopePaths;
+export declare function sessionScopePaths(cwd: string, sessionId: string, repositoryRoot?: string, sessionKey?: string): ScopePaths;
+export declare function cwdStatePath(cwd: string, repositoryRoot?: string): string;
+export declare function cwdPatchesPath(cwd: string, repositoryRoot?: string): string;
+export declare function sessionStatePath(cwd: string, sessionId: string, repositoryRoot?: string, sessionKey?: string): string;
+export declare function sessionPatchesPath(cwd: string, sessionId: string, repositoryRoot?: string, sessionKey?: string): string;
+/** Exact semantic file shapes, including legacy snapshots only during the storage cutover. */
+export declare function isStateFlowOwnedPath(candidate: string, repositoryRoot?: string): boolean;
+/** Capture exact owned bytes for one compare-and-swap publication or migration cohort. */
+export declare function captureOwnedFileBases(paths: readonly string[], repositoryRoot: string): DurableFileBase[];
+export interface OwnedFileUpdate {
+    path: string;
+    /** Omission means removal of this exact owned file, not a semantic null patch. */
+    content?: string;
+}
+/** Verify the publisher's exact output before commit or rollback, without trusting changed worktree bytes. */
+export declare function assertOwnedFileUpdates(updates: readonly OwnedFileUpdate[], repositoryRoot: string): void;
+/** Publish a prevalidated file cohort, preserving original bytes for failed preparation/publication. */
+export declare function writeOwnedFileUpdates(updates: readonly OwnedFileUpdate[], bases: readonly DurableFileBase[], repositoryRoot: string): string[];
+/** Restore exact pre-transition bytes only while files still match this publisher's output. */
+export declare function restoreDurableFileBases(bases: readonly DurableFileBase[], repositoryRoot: string, expectedCurrent: readonly OwnedFileUpdate[]): void;