@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/sdk/workspace-snapshot.js

@@ -1,614 +1,5 @@
-/**
- * @module sdk/workspace-snapshot
- *
- * Creates and restores content-addressed snapshots of authoritative tracker
- * state while excluding clone-local caches, locks, and recovery journals.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2580e043-8675-5070-b57e-30cae333228c")}catch(e){}}();
-import crypto from "node:crypto";
-import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
-import path from "node:path";
-import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
-import { appendWorkspaceAuditEvent } from "../core/history/workspace-history.js";
-import { acquireLock } from "../core/lock/lock.js";
-import { getLockPath } from "../core/store/paths.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { withHostEnvironmentBoundary } from "./environment/host-environment-errors.js";
-/** Current content-addressed workspace snapshot manifest schema identifier. */
-export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
-/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
-export const WORKSPACE_SNAPSHOT_ACTIONS = [
-    "create",
-    "list",
-    "inspect",
-    "restore",
-    "delete",
-];
-const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
-const EXCLUDED_ROOT_NAMES = new Set([
-    "checkpoints",
-    "locks",
-    "runtime",
-    "search",
-    "transactions",
-]);
-const SNAPSHOT_TARGET_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
-const WORKSPACE_WRITER_LOCK_ID = "sdk-workspace-transaction";
-const SNAPSHOT_HOST_FAULT_CODES = {
-    capacity: { code: "workspace_snapshot_storage_exhausted" },
-    permission: { code: "workspace_snapshot_permission_denied" },
-    resource: { code: "workspace_snapshot_resource_exhausted" },
-};
-const DEFAULT_ATOMIC_OPERATIONS = {
-    renameEntry: rename,
-    removeEntry: async (target) => {
-        await rm(target, { recursive: true, force: true });
-    },
-};
-/** Keeps one workspace writer lease current while a long restore is active. */
-class WorkspaceLockHeartbeat {
-    lockPath;
-    owner;
-    intervalMs;
-    timer;
-    refresh;
-    failure;
-    /** Capture the exact lock identity and derive a sub-TTL renewal interval. */
-    constructor(lockPath, owner, ttlSeconds) {
-        this.lockPath = lockPath;
-        this.owner = owner;
-        this.intervalMs = Math.max(10, Math.floor((ttlSeconds * 1_000) / 3));
-    }
-    /** Begin renewing the lock without keeping the process alive on its own. */
-    start() {
-        this.scheduleRenewal();
-        this.timer = setInterval(() => {
-            this.scheduleRenewal();
-        }, this.intervalMs);
-        this.timer.unref();
-    }
-    /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
-    async refreshNow() {
-        this.scheduleRenewal();
-        await this.refresh;
-        this.assertHealthy();
-    }
-    /** Fail the restore before activation when lease ownership was lost. */
-    assertHealthy() {
-        if (this.failure !== undefined) {
-            throw new Error("Workspace snapshot restore lost its writer lock", {
-                cause: this.failure,
-            });
-        }
-    }
-    /** Stop future renewals and await the last in-flight atomic write. */
-    async stop() {
-        if (this.timer !== undefined)
-            clearInterval(this.timer);
-        await this.refresh;
-        this.assertHealthy();
-    }
-    /** Serialize renewal attempts and retain the first ownership failure. */
-    scheduleRenewal() {
-        if (this.refresh !== undefined || this.failure !== undefined)
-            return;
-        this.refresh = this.renew()
-            .catch((error) => {
-            this.failure = error;
-        })
-            .finally(() => {
-            this.refresh = undefined;
-        });
-    }
-    /** Atomically refresh only the lock still owned by this process and actor. */
-    async renew() {
-        const parsed = JSON.parse(await readFile(this.lockPath, "utf8"));
-        if (typeof parsed !== "object" ||
-            parsed === null ||
-            Array.isArray(parsed)) {
-            throw new Error("Workspace writer lock has invalid structure");
-        }
-        const lock = parsed;
-        if (lock.id !== WORKSPACE_WRITER_LOCK_ID ||
-            lock.owner !== this.owner ||
-            lock.pid !== process.pid) {
-            throw new Error("Workspace writer lock ownership changed");
-        }
-        await writeFileAtomic(this.lockPath, `${JSON.stringify({ ...lock, created_at: new Date().toISOString() }, null, 2)}\n`);
-    }
-}
-/** Internal heartbeat constructor exposed only for deterministic lock tests. */
-export const _testOnlyWorkspaceSnapshot = {
-    WorkspaceLockHeartbeat,
-    withSnapshotFilesystemGuard,
-};
-async function collectAuthoritativeFiles(root, relative = "") {
-    const entries = await readdir(path.join(root, relative), {
-        withFileTypes: true,
-    });
-    const files = [];
-    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-        if (relative.length === 0 && EXCLUDED_ROOT_NAMES.has(entry.name)) {
-            continue;
-        }
-        const entryRelative = path.posix.join(relative.replaceAll(path.sep, "/"), entry.name);
-        if (entry.isSymbolicLink()) {
-            throw new Error(`Workspace snapshots reject symbolic links: ${entryRelative}`);
-        }
-        if (entry.isDirectory()) {
-            files.push(...(await collectAuthoritativeFiles(root, entryRelative)));
-        }
-        else if (entry.isFile()) {
-            files.push(entryRelative);
-        }
-        else {
-            throw new Error(`Workspace snapshots reject unsupported filesystem entries: ${entryRelative}`);
-        }
-    }
-    return files;
-}
-async function buildManifest(pmRoot) {
-    const files = await collectAuthoritativeFiles(pmRoot);
-    const hash = crypto.createHash("sha256");
-    const contents = [];
-    let bytes = 0;
-    for (const file of files) {
-        const content = await readFile(path.join(pmRoot, file));
-        contents.push(content);
-        bytes += content.byteLength;
-        hash.update(file);
-        hash.update("\0");
-        hash.update(String(content.byteLength));
-        hash.update("\0");
-        hash.update(content);
-    }
-    const fingerprint = hash.digest("hex");
-    return {
-        manifest: {
-            schema: SNAPSHOT_SCHEMA,
-            fingerprint,
-            files,
-            bytes,
-        },
-        contents,
-    };
-}
-function lineCount(content) {
-    if (content === undefined || content.byteLength === 0) {
-        return 0;
-    }
-    return content
-        .toString("utf8")
-        .split("\n")
-        .filter((line) => line.trim().length > 0).length;
-}
-async function snapshotContents(root, files) {
-    const contents = new Map();
-    for (let offset = 0; offset < files.length; offset += 32) {
-        const batch = files.slice(offset, offset + 32);
-        const entries = await Promise.all(batch.map(async (file) => [file, await readFile(path.join(root, file))]));
-        for (const [file, content] of entries)
-            contents.set(file, content);
-    }
-    return contents;
-}
-function validateSnapshotTarget(target) {
-    if (!SNAPSHOT_TARGET_PATTERN.test(target)) {
-        throw new PmCliError("Snapshot names and fingerprints must use lowercase letters, digits, dots, underscores, or hyphens", EXIT_CODE.USAGE, {
-            code: "invalid_workspace_snapshot_target",
-            required: "Provide a non-empty lowercase snapshot name or 64-character hexadecimal fingerprint.",
-            why: "Snapshot targets are used as portable reference filenames and content identities.",
-            examples: [
-                "pm workspace snapshot list --json",
-                "pm workspace snapshot inspect baseline --json",
-            ],
-            nextSteps: [
-                "List available snapshots, then retry with a returned name or fingerprint.",
-            ],
-            recovery: {
-                suggested_retry: "pm workspace snapshot list --json",
-            },
-        });
-    }
-}
-/**
- * Runs a bounded snapshot filesystem stage, converting host environment faults
- * into declared refusals.
- *
- * The operation label is a fixed identifier, never a path: snapshot failures
- * are reported without disclosing workspace topology.
- */
-async function withSnapshotFilesystemGuard(operation, run) {
-    return withHostEnvironmentBoundary(`workspace_snapshot_${operation}`, run, {
-        codes: {
-            capacity: SNAPSHOT_HOST_FAULT_CODES.capacity.code,
-            permission: SNAPSHOT_HOST_FAULT_CODES.permission.code,
-            resource: SNAPSHOT_HOST_FAULT_CODES.resource.code,
-        },
-        why: "Snapshot create and restore copy authoritative tracker state before activation, so the stage needs capacity and write access up front.",
-        nextSteps: [
-            "Reclaim rebuildable tracker cache space with pm gc, then retry.",
-        ],
-        suggestedRetry: "pm gc --json",
-    });
-}
-function snapshotStore(pmRoot) {
-    return path.join(pmRoot, SNAPSHOT_RUNTIME_PATH);
-}
-function workspaceSnapshotNotFound(target) {
-    return new PmCliError(`Unknown workspace snapshot: ${target}`, EXIT_CODE.NOT_FOUND, {
-        code: "workspace_snapshot_not_found",
-        required: "Use a snapshot name or fingerprint returned by snapshot list.",
-        why: "The requested reference or immutable snapshot object does not exist.",
-        examples: ["pm workspace snapshot list --json"],
-        nextSteps: ["List available snapshots and retry with an exact target."],
-        recovery: { suggested_retry: "pm workspace snapshot list --json" },
-    });
-}
-async function readSnapshotJson(file, target) {
-    try {
-        return JSON.parse(await readFile(file, "utf8"));
-    }
-    catch (error) {
-        if (isFileMissingError(error)) {
-            throw workspaceSnapshotNotFound(target);
-        }
-        throw error;
-    }
-}
-async function removeSnapshotEntry(entry, target, recursive) {
-    try {
-        await rm(entry, { recursive });
-    }
-    catch (error) {
-        if (isFileMissingError(error)) {
-            throw workspaceSnapshotNotFound(target);
-        }
-        throw error;
-    }
-}
-/**
- * Publish a prepared immutable object, treating a concurrent winning publish
- * as successful deduplication.
- */
-export async function publishWorkspaceSnapshotObject(temporaryRoot, objectRoot, operations = DEFAULT_ATOMIC_OPERATIONS) {
-    try {
-        await operations.renameEntry(temporaryRoot, objectRoot);
-        return false;
-    }
-    catch (error) {
-        if (!(error instanceof Error &&
-            "code" in error &&
-            (error.code === "EEXIST" || error.code === "ENOTEMPTY"))) {
-            throw error;
-        }
-        await operations.removeEntry(temporaryRoot);
-        return true;
-    }
-}
-/** Activate a staged tracker root, run a post-activation hook, and restore the backup if activation fails. */
-async function swapWorkspaceSnapshotRootWithActivation(staging, pmRoot, backup, operations, afterActivation) {
-    await operations.renameEntry(pmRoot, backup);
-    try {
-        await operations.renameEntry(staging, pmRoot);
-        await afterActivation?.();
-    }
-    catch (error) {
-        await operations.renameEntry(backup, pmRoot);
-        await operations.removeEntry(staging);
-        throw error;
-    }
-    await operations.removeEntry(backup);
-}
-/** Activate a staged tracker root and restore the backup if activation fails. */
-export async function swapWorkspaceSnapshotRoot(staging, pmRoot, backup, operations = DEFAULT_ATOMIC_OPERATIONS) {
-    await swapWorkspaceSnapshotRootWithActivation(staging, pmRoot, backup, operations);
-}
-async function resolveSnapshotFingerprint(pmRoot, target) {
-    validateSnapshotTarget(target);
-    if (/^[a-f0-9]{64}$/.test(target)) {
-        return target;
-    }
-    const reference = await readSnapshotJson(path.join(snapshotStore(pmRoot), "refs", `${target}.json`), target);
-    return reference.fingerprint;
-}
-/** Capture authoritative tracker state as a deduplicated immutable object. */
-export async function createWorkspaceSnapshot(pmRoot, options = {}) {
-    if (options.name !== undefined) {
-        validateSnapshotTarget(options.name);
-        if (/^[a-f0-9]{64}$/.test(options.name)) {
-            throw new PmCliError("Snapshot names must not be 64-character lowercase hexadecimal fingerprints", EXIT_CODE.USAGE, {
-                code: "workspace_snapshot_name_reserved_fingerprint",
-                required: "Choose a human-readable reference name that cannot be mistaken for a content fingerprint.",
-                why: "Exact 64-character hexadecimal values address immutable objects.",
-                examples: ["pm workspace snapshot create baseline --json"],
-                nextSteps: ["Retry with a shorter descriptive snapshot name."],
-            });
-        }
-    }
-    const { manifest, contents } = await buildManifest(pmRoot);
-    const store = snapshotStore(pmRoot);
-    const objectRoot = path.join(store, "objects", manifest.fingerprint);
-    let deduplicated = false;
-    try {
-        const objectStat = await lstat(objectRoot);
-        deduplicated = objectStat.isDirectory();
-    }
-    catch (error) {
-        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
-            throw error;
-        }
-    }
-    if (!deduplicated) {
-        const temporaryRoot = path.join(store, "objects", `.create-${process.pid}-${crypto.randomUUID()}`);
-        await withSnapshotFilesystemGuard("create_object", async () => {
-            await mkdir(path.join(temporaryRoot, "files"), { recursive: true });
-            for (const [index, file] of manifest.files.entries()) {
-                const target = path.join(temporaryRoot, "files", file);
-                await mkdir(path.dirname(target), { recursive: true });
-                await writeFile(target, contents[index]);
-            }
-            await writeFile(path.join(temporaryRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-            await mkdir(path.dirname(objectRoot), { recursive: true });
-        });
-        deduplicated = await publishWorkspaceSnapshotObject(temporaryRoot, objectRoot);
-    }
-    if (options.name !== undefined) {
-        const reference = {
-            name: options.name,
-            fingerprint: manifest.fingerprint,
-        };
-        const refsRoot = path.join(store, "refs");
-        await mkdir(refsRoot, { recursive: true });
-        const temporaryRef = path.join(refsRoot, `.ref-${process.pid}-${crypto.randomUUID()}`);
-        await writeFile(temporaryRef, `${JSON.stringify(reference, null, 2)}\n`, "utf8");
-        await rename(temporaryRef, path.join(refsRoot, `${options.name}.json`));
-    }
-    return {
-        manifest,
-        ...(options.name === undefined ? {} : { name: options.name }),
-        deduplicated,
-    };
-}
-/** Read and verify a snapshot manifest by named reference or fingerprint. */
-export async function inspectWorkspaceSnapshot(pmRoot, target) {
-    const fingerprint = await resolveSnapshotFingerprint(pmRoot, target);
-    const manifest = await readSnapshotJson(path.join(snapshotStore(pmRoot), "objects", fingerprint, "manifest.json"), target);
-    if (manifest.schema !== SNAPSHOT_SCHEMA ||
-        manifest.fingerprint !== fingerprint) {
-        throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`, EXIT_CODE.CONFLICT, {
-            code: "workspace_snapshot_manifest_mismatch",
-            required: "Use an intact snapshot whose manifest fingerprint matches its object path.",
-            why: "Content identity must be verified before snapshot data is trusted.",
-            examples: ["pm workspace snapshot list --json"],
-            nextSteps: ["Inspect or recreate the snapshot before restoring it."],
-        });
-    }
-    return manifest;
-}
-/** List immutable objects and human-readable named references. */
-export async function listWorkspaceSnapshots(pmRoot) {
-    const store = snapshotStore(pmRoot);
-    const objectNames = await readdir(path.join(store, "objects")).catch((error) => {
-        if (error instanceof Error &&
-            "code" in error &&
-            isFileMissingError(error)) {
-            return [];
-        }
-        throw error;
-    });
-    const referenceNames = await readdir(path.join(store, "refs")).catch((error) => {
-        if (error instanceof Error &&
-            "code" in error &&
-            isFileMissingError(error)) {
-            return [];
-        }
-        throw error;
-    });
-    return {
-        objects: await Promise.all(objectNames
-            .filter((name) => /^[a-f0-9]{64}$/.test(name))
-            .sort()
-            .map((name) => inspectWorkspaceSnapshot(pmRoot, name))),
-        references: await Promise.all(referenceNames
-            .filter((name) => name.endsWith(".json"))
-            .sort()
-            .map(async (name) => JSON.parse(await readFile(path.join(store, "refs", name), "utf8")))),
-    };
-}
-/** Compute the exact authoritative and history impact of restoring a snapshot. */
-export async function planWorkspaceSnapshotRestore(pmRoot, target) {
-    const targetManifest = await inspectWorkspaceSnapshot(pmRoot, target);
-    const { manifest: currentManifest, contents: currentContentList } = await buildManifest(pmRoot);
-    const currentContents = new Map(currentManifest.files.map((file, index) => [
-        file,
-        currentContentList[index],
-    ]));
-    const targetContents = await snapshotContents(path.join(snapshotStore(pmRoot), "objects", targetManifest.fingerprint, "files"), targetManifest.files);
-    const currentFiles = new Set(currentManifest.files);
-    const targetFiles = new Set(targetManifest.files);
-    const changedFiles = new Set([...currentFiles, ...targetFiles]);
-    for (const file of changedFiles) {
-        const currentContent = currentContents.get(file);
-        const targetContent = targetContents.get(file);
-        if (currentContent !== undefined &&
-            targetContent !== undefined &&
-            currentContent.equals(targetContent)) {
-            changedFiles.delete(file);
-        }
-    }
-    const affectedHistoryStreams = currentManifest.files
-        .filter((file) => file.startsWith("history/") && file.endsWith(".jsonl"))
-        .map((file) => {
-        const currentEntries = lineCount(currentContents.get(file));
-        const targetEntries = lineCount(targetContents.get(file));
-        return {
-            path: file,
-            current_entries: currentEntries,
-            target_entries: targetEntries,
-            removed_entries: Math.max(0, currentEntries - targetEntries),
-        };
-    })
-        .filter((entry) => entry.removed_entries > 0)
-        .sort((left, right) => left.path.localeCompare(right.path));
-    return {
-        target_fingerprint: targetManifest.fingerprint,
-        current_fingerprint: currentManifest.fingerprint,
-        changed_file_count: changedFiles.size,
-        removed_file_count: [...currentFiles].filter((file) => !targetFiles.has(file)).length,
-        added_file_count: [...targetFiles].filter((file) => !currentFiles.has(file))
-            .length,
-        removed_item_count: [...currentFiles].filter((file) => file.endsWith(".toon") && !targetFiles.has(file)).length,
-        affected_history_stream_count: affectedHistoryStreams.length,
-        removed_history_entry_count: affectedHistoryStreams.reduce((total, entry) => total + entry.removed_entries, 0),
-        affected_history_streams: affectedHistoryStreams,
-        changes_authoritative_state: currentManifest.fingerprint !== targetManifest.fingerprint,
-    };
-}
-/**
- * Atomically replace tracker state with an audited, reversible snapshot.
- *
- * The caller must explicitly confirm the whole-workspace mutation. The current
- * state is captured as an immutable recovery object before staging begins, and
- * the staged `_workspace` stream receives the restore event before activation.
- */
-export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, options = {}) {
-    if (options.force !== true) {
-        throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force", EXIT_CODE.USAGE, {
-            code: "workspace_snapshot_force_required",
-            required: "Preview the destructive impact, then explicitly confirm the restore.",
-            why: "A restore replaces the complete authoritative tracker state.",
-            examples: [
-                `pm workspace snapshot restore ${target} --dry-run --json`,
-                `pm workspace snapshot restore ${target} --force --json`,
-            ],
-            nextSteps: ["Review the dry-run counts before retrying with --force."],
-            recovery: {
-                suggested_retry: `pm workspace snapshot restore ${target} --dry-run --json`,
-            },
-        });
-    }
-    const author = options.author?.trim() || "pm-sdk";
-    const lockTtlSeconds = options.lockTtlSeconds ?? 60;
-    const lockWaitMs = options.lockWaitMs ?? 5_000;
-    const releaseWorkspaceLock = await acquireLock(pmRoot, WORKSPACE_WRITER_LOCK_ID, lockTtlSeconds, author, false, false, lockWaitMs);
-    const heartbeat = new WorkspaceLockHeartbeat(getLockPath(pmRoot, WORKSPACE_WRITER_LOCK_ID), author, lockTtlSeconds);
-    heartbeat.start();
-    await heartbeat.refreshNow();
-    let staging;
-    let swapStarted = false;
-    let heartbeatStopped = false;
-    try {
-        const plan = await planWorkspaceSnapshotRestore(pmRoot, target);
-        const manifest = await inspectWorkspaceSnapshot(pmRoot, target);
-        const recovery = await createWorkspaceSnapshot(pmRoot);
-        const fingerprint = manifest.fingerprint;
-        const store = snapshotStore(pmRoot);
-        const source = path.join(store, "objects", fingerprint, "files");
-        const parent = path.dirname(pmRoot);
-        const base = path.basename(pmRoot);
-        staging = path.join(parent, `.${base}.restore-${crypto.randomUUID()}`);
-        const backup = path.join(parent, `.${base}.backup-${crypto.randomUUID()}`);
-        await withSnapshotFilesystemGuard("restore_stage", async () => {
-            await mkdir(staging, { recursive: true });
-            await cp(source, staging, { recursive: true, force: false });
-            await mkdir(path.join(staging, "runtime"), { recursive: true });
-            await cp(store, path.join(staging, SNAPSHOT_RUNTIME_PATH), {
-                recursive: true,
-                force: false,
-            });
-        });
-        const audit = await appendWorkspaceAuditEvent({
-            pmRoot: staging,
-            op: "workspace_snapshot_restore",
-            author,
-            message: options.message ??
-                `Restore workspace snapshot ${fingerprint}; recovery snapshot ${recovery.manifest.fingerprint}`,
-            context: {
-                target_fingerprint: fingerprint,
-                pre_restore_fingerprint: recovery.manifest.fingerprint,
-                changed_file_count: plan.changed_file_count,
-                removed_file_count: plan.removed_file_count,
-                removed_item_count: plan.removed_item_count,
-                affected_history_stream_count: plan.affected_history_stream_count,
-                removed_history_entry_count: plan.removed_history_entry_count,
-            },
-            lockTtlSeconds,
-            lockWaitMs,
-        });
-        const auditHistoryPath = path
-            .relative(staging, audit.historyPath)
-            .replaceAll("\\", "/");
-        await heartbeat.stop();
-        heartbeatStopped = true;
-        const stagedWorkspaceLock = getLockPath(staging, WORKSPACE_WRITER_LOCK_ID);
-        await mkdir(path.dirname(stagedWorkspaceLock), { recursive: true });
-        await writeFile(stagedWorkspaceLock, await readFile(getLockPath(pmRoot, WORKSPACE_WRITER_LOCK_ID)), { flag: "wx" });
-        swapStarted = true;
-        await swapWorkspaceSnapshotRootWithActivation(staging, pmRoot, backup, DEFAULT_ATOMIC_OPERATIONS, async () => {
-            heartbeat.start();
-            heartbeatStopped = false;
-            await heartbeat.refreshNow();
-        });
-        await heartbeat.stop();
-        heartbeatStopped = true;
-        return {
-            manifest,
-            plan,
-            recovery_fingerprint: recovery.manifest.fingerprint,
-            audit_history_path: auditHistoryPath,
-            audit_operation: "workspace_snapshot_restore",
-        };
-    }
-    catch (error) {
-        if (staging !== undefined && !swapStarted) {
-            await Promise.allSettled([rm(staging, { recursive: true, force: true })]);
-        }
-        throw error;
-    }
-    finally {
-        try {
-            if (!heartbeatStopped)
-                await heartbeat.stop();
-        }
-        catch {
-            // A body failure already owns the outcome; lease cleanup must not mask it.
-        }
-        finally {
-            await releaseWorkspaceLock();
-        }
-    }
-}
-/**
- * Restore a snapshot through the backward-compatible SDK signature.
- *
- * Existing callers retain the manifest return contract while every restore now
- * captures a recovery snapshot and writes a durable audit event. New callers
- * that need impact, recovery, and audit coordinates should use
- * `restoreWorkspaceSnapshotWithRecovery`.
- */
-export async function restoreWorkspaceSnapshot(pmRoot, target) {
-    return (await restoreWorkspaceSnapshotWithRecovery(pmRoot, target, {
-        force: true,
-        message: "Restore requested through the compatibility SDK signature",
-    })).manifest;
-}
-/** Delete a named reference, or an unreferenced immutable object fingerprint. */
-export async function deleteWorkspaceSnapshot(pmRoot, target) {
-    validateSnapshotTarget(target);
-    const store = snapshotStore(pmRoot);
-    if (!/^[a-f0-9]{64}$/.test(target)) {
-        await removeSnapshotEntry(path.join(store, "refs", `${target}.json`), target, false);
-        return { deleted: "reference", target };
-    }
-    const { references } = await listWorkspaceSnapshots(pmRoot);
-    if (references.some((reference) => reference.fingerprint === target)) {
-        throw new Error(`Snapshot object ${target} is still referenced`);
-    }
-    await removeSnapshotEntry(path.join(store, "objects", target), target, true);
-    return { deleted: "object", target };
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="91604cb2-8afd-585e-9c18-26e223df25bc")}catch(e2){}})();import crypto from"node:crypto";import{cp,lstat,mkdir,readFile,readdir,rename,rm,writeFile}from"node:fs/promises";import path from"node:path";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{appendWorkspaceAuditEvent}from"../core/history/workspace-history.js";import{acquireLock}from"../core/lock/lock.js";import{getLockPath}from"../core/store/paths.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{withHostEnvironmentBoundary}from"./environment/host-environment-errors.js";const SNAPSHOT_SCHEMA="https://schema.unbrained.dev/pm/workspace-snapshot/v1";const WORKSPACE_SNAPSHOT_ACTIONS=["create","list","inspect","restore","delete"];const SNAPSHOT_RUNTIME_PATH=path.join("runtime","workspace-snapshots");const EXCLUDED_ROOT_NAMES=new Set(["checkpoints","locks","runtime","search","transactions"]);const SNAPSHOT_TARGET_PATTERN=/^[a-z0-9][a-z0-9._-]*$/;const WORKSPACE_WRITER_LOCK_ID="sdk-workspace-transaction";const SNAPSHOT_HOST_FAULT_CODES={capacity:{code:"workspace_snapshot_storage_exhausted"},permission:{code:"workspace_snapshot_permission_denied"},resource:{code:"workspace_snapshot_resource_exhausted"}};const DEFAULT_ATOMIC_OPERATIONS={renameEntry:rename,removeEntry:async target=>{await rm(target,{recursive:true,force:true})}};class WorkspaceLockHeartbeat{lockPath;owner;intervalMs;timer;refresh;failure;constructor(lockPath,owner,ttlSeconds){this.lockPath=lockPath;this.owner=owner;this.intervalMs=Math.max(10,Math.floor(ttlSeconds*1e3/3))}start(){this.scheduleRenewal();this.timer=setInterval(()=>{this.scheduleRenewal()},this.intervalMs);this.timer.unref()}async refreshNow(){this.scheduleRenewal();await this.refresh;this.assertHealthy()}assertHealthy(){if(this.failure!==void 0){throw new Error("Workspace snapshot restore lost its writer lock",{cause:this.failure})}}async stop(){if(this.timer!==void 0)clearInterval(this.timer);await this.refresh;this.assertHealthy()}scheduleRenewal(){if(this.refresh!==void 0||this.failure!==void 0)return;this.refresh=this.renew().catch(error=>{this.failure=error}).finally(()=>{this.refresh=void 0})}async renew(){const parsed=JSON.parse(await readFile(this.lockPath,"utf8"));if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)){throw new Error("Workspace writer lock has invalid structure")}const lock=parsed;if(lock.id!==WORKSPACE_WRITER_LOCK_ID||lock.owner!==this.owner||lock.pid!==process.pid){throw new Error("Workspace writer lock ownership changed")}await writeFileAtomic(this.lockPath,`${JSON.stringify({...lock,created_at:new Date().toISOString()},null,2)}
+`)}}const _testOnlyWorkspaceSnapshot={WorkspaceLockHeartbeat,withSnapshotFilesystemGuard};async function collectAuthoritativeFiles(root,relative=""){const entries=await readdir(path.join(root,relative),{withFileTypes:true});const files=[];for(const entry of entries.sort((left,right)=>left.name.localeCompare(right.name))){if(relative.length===0&&EXCLUDED_ROOT_NAMES.has(entry.name)){continue}const entryRelative=path.posix.join(relative.replaceAll(path.sep,"/"),entry.name);if(entry.isSymbolicLink()){throw new Error(`Workspace snapshots reject symbolic links: ${entryRelative}`)}if(entry.isDirectory()){files.push(...await collectAuthoritativeFiles(root,entryRelative))}else if(entry.isFile()){files.push(entryRelative)}else{throw new Error(`Workspace snapshots reject unsupported filesystem entries: ${entryRelative}`)}}return files}async function buildManifest(pmRoot){const files=await collectAuthoritativeFiles(pmRoot);const hash=crypto.createHash("sha256");const contents=[];let bytes=0;for(const file of files){const content=await readFile(path.join(pmRoot,file));contents.push(content);bytes+=content.byteLength;hash.update(file);hash.update("\0");hash.update(String(content.byteLength));hash.update("\0");hash.update(content)}const fingerprint=hash.digest("hex");return{manifest:{schema:SNAPSHOT_SCHEMA,fingerprint,files,bytes},contents}}function lineCount(content){if(content===void 0||content.byteLength===0){return 0}return content.toString("utf8").split("\n").filter(line=>line.trim().length>0).length}async function snapshotContents(root,files){const contents=new Map;for(let offset=0;offset<files.length;offset+=32){const batch=files.slice(offset,offset+32);const entries=await Promise.all(batch.map(async file=>[file,await readFile(path.join(root,file))]));for(const[file,content]of entries)contents.set(file,content)}return contents}function validateSnapshotTarget(target){if(!SNAPSHOT_TARGET_PATTERN.test(target)){throw new PmCliError("Snapshot names and fingerprints must use lowercase letters, digits, dots, underscores, or hyphens",EXIT_CODE.USAGE,{code:"invalid_workspace_snapshot_target",required:"Provide a non-empty lowercase snapshot name or 64-character hexadecimal fingerprint.",why:"Snapshot targets are used as portable reference filenames and content identities.",examples:["pm workspace snapshot list --json","pm workspace snapshot inspect baseline --json"],nextSteps:["List available snapshots, then retry with a returned name or fingerprint."],recovery:{suggested_retry:"pm workspace snapshot list --json"}})}}async function withSnapshotFilesystemGuard(operation,run){return withHostEnvironmentBoundary(`workspace_snapshot_${operation}`,run,{codes:{capacity:SNAPSHOT_HOST_FAULT_CODES.capacity.code,permission:SNAPSHOT_HOST_FAULT_CODES.permission.code,resource:SNAPSHOT_HOST_FAULT_CODES.resource.code},why:"Snapshot create and restore copy authoritative tracker state before activation, so the stage needs capacity and write access up front.",nextSteps:["Reclaim rebuildable tracker cache space with pm gc, then retry."],suggestedRetry:"pm gc --json"})}function snapshotStore(pmRoot){return path.join(pmRoot,SNAPSHOT_RUNTIME_PATH)}function workspaceSnapshotNotFound(target){return new PmCliError(`Unknown workspace snapshot: ${target}`,EXIT_CODE.NOT_FOUND,{code:"workspace_snapshot_not_found",required:"Use a snapshot name or fingerprint returned by snapshot list.",why:"The requested reference or immutable snapshot object does not exist.",examples:["pm workspace snapshot list --json"],nextSteps:["List available snapshots and retry with an exact target."],recovery:{suggested_retry:"pm workspace snapshot list --json"}})}async function readSnapshotJson(file,target){try{return JSON.parse(await readFile(file,"utf8"))}catch(error){if(isFileMissingError(error)){throw workspaceSnapshotNotFound(target)}throw error}}async function removeSnapshotEntry(entry,target,recursive){try{await rm(entry,{recursive})}catch(error){if(isFileMissingError(error)){throw workspaceSnapshotNotFound(target)}throw error}}async function publishWorkspaceSnapshotObject(temporaryRoot,objectRoot,operations=DEFAULT_ATOMIC_OPERATIONS){try{await operations.renameEntry(temporaryRoot,objectRoot);return false}catch(error){if(!(error instanceof Error&&"code"in error&&(error.code==="EEXIST"||error.code==="ENOTEMPTY"))){throw error}await operations.removeEntry(temporaryRoot);return true}}async function swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,operations,afterActivation){await operations.renameEntry(pmRoot,backup);try{await operations.renameEntry(staging,pmRoot);await afterActivation?.()}catch(error){await operations.renameEntry(backup,pmRoot);await operations.removeEntry(staging);throw error}await operations.removeEntry(backup)}async function swapWorkspaceSnapshotRoot(staging,pmRoot,backup,operations=DEFAULT_ATOMIC_OPERATIONS){await swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,operations)}async function resolveSnapshotFingerprint(pmRoot,target){validateSnapshotTarget(target);if(/^[a-f0-9]{64}$/.test(target)){return target}const reference=await readSnapshotJson(path.join(snapshotStore(pmRoot),"refs",`${target}.json`),target);return reference.fingerprint}async function createWorkspaceSnapshot(pmRoot,options={}){if(options.name!==void 0){validateSnapshotTarget(options.name);if(/^[a-f0-9]{64}$/.test(options.name)){throw new PmCliError("Snapshot names must not be 64-character lowercase hexadecimal fingerprints",EXIT_CODE.USAGE,{code:"workspace_snapshot_name_reserved_fingerprint",required:"Choose a human-readable reference name that cannot be mistaken for a content fingerprint.",why:"Exact 64-character hexadecimal values address immutable objects.",examples:["pm workspace snapshot create baseline --json"],nextSteps:["Retry with a shorter descriptive snapshot name."]})}}const{manifest,contents}=await buildManifest(pmRoot);const store=snapshotStore(pmRoot);const objectRoot=path.join(store,"objects",manifest.fingerprint);let deduplicated=false;try{const objectStat=await lstat(objectRoot);deduplicated=objectStat.isDirectory()}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error))){throw error}}if(!deduplicated){const temporaryRoot=path.join(store,"objects",`.create-${process.pid}-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("create_object",async()=>{await mkdir(path.join(temporaryRoot,"files"),{recursive:true});for(const[index,file]of manifest.files.entries()){const target=path.join(temporaryRoot,"files",file);await mkdir(path.dirname(target),{recursive:true});await writeFile(target,contents[index])}await writeFile(path.join(temporaryRoot,"manifest.json"),`${JSON.stringify(manifest,null,2)}
+`,"utf8");await mkdir(path.dirname(objectRoot),{recursive:true})});deduplicated=await publishWorkspaceSnapshotObject(temporaryRoot,objectRoot)}if(options.name!==void 0){const reference={name:options.name,fingerprint:manifest.fingerprint};const refsRoot=path.join(store,"refs");await mkdir(refsRoot,{recursive:true});const temporaryRef=path.join(refsRoot,`.ref-${process.pid}-${crypto.randomUUID()}`);await writeFile(temporaryRef,`${JSON.stringify(reference,null,2)}
+`,"utf8");await rename(temporaryRef,path.join(refsRoot,`${options.name}.json`))}return{manifest,...options.name===void 0?{}:{name:options.name},deduplicated}}async function inspectWorkspaceSnapshot(pmRoot,target){const fingerprint=await resolveSnapshotFingerprint(pmRoot,target);const manifest=await readSnapshotJson(path.join(snapshotStore(pmRoot),"objects",fingerprint,"manifest.json"),target);if(manifest.schema!==SNAPSHOT_SCHEMA||manifest.fingerprint!==fingerprint){throw new PmCliError(`Snapshot manifest identity mismatch: ${target}`,EXIT_CODE.CONFLICT,{code:"workspace_snapshot_manifest_mismatch",required:"Use an intact snapshot whose manifest fingerprint matches its object path.",why:"Content identity must be verified before snapshot data is trusted.",examples:["pm workspace snapshot list --json"],nextSteps:["Inspect or recreate the snapshot before restoring it."]})}return manifest}async function listWorkspaceSnapshots(pmRoot){const store=snapshotStore(pmRoot);const objectNames=await readdir(path.join(store,"objects")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error)){return[]}throw error});const referenceNames=await readdir(path.join(store,"refs")).catch(error=>{if(error instanceof Error&&"code"in error&&isFileMissingError(error)){return[]}throw error});return{objects:await Promise.all(objectNames.filter(name=>/^[a-f0-9]{64}$/.test(name)).sort().map(name=>inspectWorkspaceSnapshot(pmRoot,name))),references:await Promise.all(referenceNames.filter(name=>name.endsWith(".json")).sort().map(async name=>JSON.parse(await readFile(path.join(store,"refs",name),"utf8"))))}}async function planWorkspaceSnapshotRestore(pmRoot,target){const targetManifest=await inspectWorkspaceSnapshot(pmRoot,target);const{manifest:currentManifest,contents:currentContentList}=await buildManifest(pmRoot);const currentContents=new Map(currentManifest.files.map((file,index)=>[file,currentContentList[index]]));const targetContents=await snapshotContents(path.join(snapshotStore(pmRoot),"objects",targetManifest.fingerprint,"files"),targetManifest.files);const currentFiles=new Set(currentManifest.files);const targetFiles=new Set(targetManifest.files);const changedFiles=new Set([...currentFiles,...targetFiles]);for(const file of changedFiles){const currentContent=currentContents.get(file);const targetContent=targetContents.get(file);if(currentContent!==void 0&&targetContent!==void 0&&currentContent.equals(targetContent)){changedFiles.delete(file)}}const affectedHistoryStreams=currentManifest.files.filter(file=>file.startsWith("history/")&&file.endsWith(".jsonl")).map(file=>{const currentEntries=lineCount(currentContents.get(file));const targetEntries=lineCount(targetContents.get(file));return{path:file,current_entries:currentEntries,target_entries:targetEntries,removed_entries:Math.max(0,currentEntries-targetEntries)}}).filter(entry=>entry.removed_entries>0).sort((left,right)=>left.path.localeCompare(right.path));return{target_fingerprint:targetManifest.fingerprint,current_fingerprint:currentManifest.fingerprint,changed_file_count:changedFiles.size,removed_file_count:[...currentFiles].filter(file=>!targetFiles.has(file)).length,added_file_count:[...targetFiles].filter(file=>!currentFiles.has(file)).length,removed_item_count:[...currentFiles].filter(file=>file.endsWith(".toon")&&!targetFiles.has(file)).length,affected_history_stream_count:affectedHistoryStreams.length,removed_history_entry_count:affectedHistoryStreams.reduce((total,entry)=>total+entry.removed_entries,0),affected_history_streams:affectedHistoryStreams,changes_authoritative_state:currentManifest.fingerprint!==targetManifest.fingerprint}}async function restoreWorkspaceSnapshotWithRecovery(pmRoot,target,options={}){if(options.force!==true){throw new PmCliError("Workspace snapshot restore requires explicit force confirmation; inspect the impact with planWorkspaceSnapshotRestore or pm workspace snapshot restore <target> --dry-run, then retry with force",EXIT_CODE.USAGE,{code:"workspace_snapshot_force_required",required:"Preview the destructive impact, then explicitly confirm the restore.",why:"A restore replaces the complete authoritative tracker state.",examples:[`pm workspace snapshot restore ${target} --dry-run --json`,`pm workspace snapshot restore ${target} --force --json`],nextSteps:["Review the dry-run counts before retrying with --force."],recovery:{suggested_retry:`pm workspace snapshot restore ${target} --dry-run --json`}})}const author=options.author?.trim()||"pm-sdk";const lockTtlSeconds=options.lockTtlSeconds??60;const lockWaitMs=options.lockWaitMs??5e3;const releaseWorkspaceLock=await acquireLock(pmRoot,WORKSPACE_WRITER_LOCK_ID,lockTtlSeconds,author,false,false,lockWaitMs);const heartbeat=new WorkspaceLockHeartbeat(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID),author,lockTtlSeconds);heartbeat.start();await heartbeat.refreshNow();let staging;let swapStarted=false;let heartbeatStopped=false;try{const plan=await planWorkspaceSnapshotRestore(pmRoot,target);const manifest=await inspectWorkspaceSnapshot(pmRoot,target);const recovery=await createWorkspaceSnapshot(pmRoot);const fingerprint=manifest.fingerprint;const store=snapshotStore(pmRoot);const source=path.join(store,"objects",fingerprint,"files");const parent=path.dirname(pmRoot);const base=path.basename(pmRoot);staging=path.join(parent,`.${base}.restore-${crypto.randomUUID()}`);const backup=path.join(parent,`.${base}.backup-${crypto.randomUUID()}`);await withSnapshotFilesystemGuard("restore_stage",async()=>{await mkdir(staging,{recursive:true});await cp(source,staging,{recursive:true,force:false});await mkdir(path.join(staging,"runtime"),{recursive:true});await cp(store,path.join(staging,SNAPSHOT_RUNTIME_PATH),{recursive:true,force:false})});const audit=await appendWorkspaceAuditEvent({pmRoot:staging,op:"workspace_snapshot_restore",author,message:options.message??`Restore workspace snapshot ${fingerprint}; recovery snapshot ${recovery.manifest.fingerprint}`,context:{target_fingerprint:fingerprint,pre_restore_fingerprint:recovery.manifest.fingerprint,changed_file_count:plan.changed_file_count,removed_file_count:plan.removed_file_count,removed_item_count:plan.removed_item_count,affected_history_stream_count:plan.affected_history_stream_count,removed_history_entry_count:plan.removed_history_entry_count},lockTtlSeconds,lockWaitMs});const auditHistoryPath=path.relative(staging,audit.historyPath).replaceAll("\\","/");await heartbeat.stop();heartbeatStopped=true;const stagedWorkspaceLock=getLockPath(staging,WORKSPACE_WRITER_LOCK_ID);await mkdir(path.dirname(stagedWorkspaceLock),{recursive:true});await writeFile(stagedWorkspaceLock,await readFile(getLockPath(pmRoot,WORKSPACE_WRITER_LOCK_ID)),{flag:"wx"});swapStarted=true;await swapWorkspaceSnapshotRootWithActivation(staging,pmRoot,backup,DEFAULT_ATOMIC_OPERATIONS,async()=>{heartbeat.start();heartbeatStopped=false;await heartbeat.refreshNow()});await heartbeat.stop();heartbeatStopped=true;return{manifest,plan,recovery_fingerprint:recovery.manifest.fingerprint,audit_history_path:auditHistoryPath,audit_operation:"workspace_snapshot_restore"}}catch(error){if(staging!==void 0&&!swapStarted){await Promise.allSettled([rm(staging,{recursive:true,force:true})])}throw error}finally{try{if(!heartbeatStopped)await heartbeat.stop()}catch{}finally{await releaseWorkspaceLock()}}}async function restoreWorkspaceSnapshot(pmRoot,target){return(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:true,message:"Restore requested through the compatibility SDK signature"})).manifest}async function deleteWorkspaceSnapshot(pmRoot,target){validateSnapshotTarget(target);const store=snapshotStore(pmRoot);if(!/^[a-f0-9]{64}$/.test(target)){await removeSnapshotEntry(path.join(store,"refs",`${target}.json`),target,false);return{deleted:"reference",target}}const{references}=await listWorkspaceSnapshots(pmRoot);if(references.some(reference=>reference.fingerprint===target)){throw new Error(`Snapshot object ${target} is still referenced`)}await removeSnapshotEntry(path.join(store,"objects",target),target,true);return{deleted:"object",target}}export{SNAPSHOT_SCHEMA,WORKSPACE_SNAPSHOT_ACTIONS,_testOnlyWorkspaceSnapshot,createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,publishWorkspaceSnapshotObject,restoreWorkspaceSnapshot,restoreWorkspaceSnapshotWithRecovery,swapWorkspaceSnapshotRoot};
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=2580e043-8675-5070-b57e-30cae333228c