@anhlp/alp 0.0.1-beta.4 → 0.0.1-beta.7

package/packages/core/dist/backup.js

@@ -1,681 +0,0 @@
-// packages/core/src/backup.js
-import { createHash, randomBytes } from "node:crypto";
-import { createReadStream, createWriteStream } from "node:fs";
-import { chmod, lstat, mkdir, open, readdir, readFile, readlink, rm, rmdir, stat, symlink, utimes } from "node:fs/promises";
-import path from "node:path";
-import { Readable } from "node:stream";
-import { StringDecoder } from "node:string_decoder";
-import { pipeline } from "node:stream/promises";
-import { createGunzip, createGzip } from "node:zlib";
-import { AlpError } from "./errors.js";
-import { moveFile, writeAtomic } from "./atomic.js";
-import { STATE_SCHEMA, assertStateSupported, readStateSchema } from "./state-schema.js";
-import { withTaskLock } from "./tasks.js";
-var BACKUP_FORMAT = 1;
-var BACKUP_EXTENSION = ".alpbackup";
-var RESULT_LEDGER = "state/assignment-results.json";
-var RESULT_MARKER = `${RESULT_LEDGER}.initialized`;
-var DESTINATIONS = "worktree-destinations.json";
-var QUARANTINED_DESTINATIONS = "state/worktree-destinations.quarantined.json";
-var STATE_UNITS = [RESULT_LEDGER, RESULT_MARKER, "state/schema.json", "state/sessions", "state/timeline", "state/receipts", "state/recall.json", "state/pause.json", "state/trust.json", "state/web-workspaces.json"];
-var CLEARED_UNITS = ["state/live.json", "state/migration.json"];
-var HOME_UNITS = [
-  ...STATE_UNITS,
-  DESTINATIONS,
-  "settings.json",
-  "library.json",
-  "role-skills.json",
-  "lessons.md",
-  "agents",
-  "skills",
-  "teams",
-  "hooks",
-  "mcp",
-  "providers",
-  "formulas",
-  "boards",
-  "runs"
-];
-var PROJECT_UNITS = ["ALP.md", ".alp/settings.json", ".alp/lessons.md", ".alp/tasks", ".alp/agents", ".alp/skills", ".alp/teams", ".alp/hooks", ".alp/mcp", ".alp/formulas"];
-var CHUNK = 1024 * 1024;
-var AUTOMATIC_KEEP = 5;
-var JOURNAL = "restore-journal.json";
-var RESTORED = path.join("state", "restored.json");
-var transient = (name) => name.endsWith(".tmp") || name === ".lock" || /\.pre-restore-[0-9a-f]+$/.test(name) || /^\.restore-[0-9a-f]+$/.test(name);
-var backupsDir = (home) => path.join(home, "backups");
-var journalFile = (home) => path.join(home, JOURNAL);
-var stamp = () => (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
-var exists = (file) => lstat(file).then(() => true, () => false);
-var invalid = (message, options) => new AlpError("BACKUP_INVALID", message, options);
-function safeRelative(value) {
-  return typeof value === "string" && value.length > 0 && value.length < 4096 && !value.startsWith("/") && !/^[A-Za-z]:/.test(value) && !value.includes("\\") && !value.includes("\0") && value.split("/").every((part) => part && part !== "." && part !== "..");
-}
-async function sessionRecords(home) {
-  const directory = path.join(home, "state", "sessions");
-  const records = [];
-  for (const name of await readdir(directory).catch(() => [])) {
-    if (!name.endsWith(".json")) continue;
-    try {
-      records.push(JSON.parse(await readFile(path.join(directory, name), "utf8")));
-    } catch {
-    }
-  }
-  return records;
-}
-async function knownProjects(home) {
-  const roots = /* @__PURE__ */ new Set();
-  for (const record of await sessionRecords(home)) {
-    const root = record?.session?.projectRoot ?? record?.spec?.cwd;
-    if (typeof root === "string" && path.isAbsolute(root)) roots.add(path.resolve(root));
-  }
-  const found = [];
-  for (const root of [...roots].sort()) if (await exists(path.join(root, ".alp"))) found.push(root);
-  return found;
-}
-async function externalReferences(home) {
-  const references = [];
-  for (const record of await sessionRecords(home)) {
-    const session = record?.session;
-    if (session?.threadId) references.push({ sessionId: record.id, runtime: session.runtime, threadId: session.threadId, projectRoot: session.projectRoot });
-  }
-  return references;
-}
-async function* unitEntries(base, unit) {
-  const full = path.join(base, unit);
-  const info = await lstat(full).catch((error) => {
-    if (error?.code === "ENOENT") return void 0;
-    throw error;
-  });
-  if (!info) return;
-  async function* walk(relative, info2) {
-    const file = path.join(base, relative);
-    if (info2.isSymbolicLink()) yield { t: "link", path: relative, target: await readlink(file) };
-    else if (info2.isDirectory()) {
-      yield { t: "dir", path: relative, mode: info2.mode & 511 };
-      for (const name of (await readdir(file)).sort()) {
-        if (transient(name)) continue;
-        const child = await lstat(path.join(file, name)).catch(() => void 0);
-        if (child) yield* walk(`${relative}/${name}`, child);
-      }
-    } else if (info2.isFile()) yield { t: "file", path: relative, mode: info2.mode & 511, file };
-  }
-  yield* walk(unit, info);
-}
-async function unitKind(base, unit) {
-  const info = await lstat(path.join(base, unit)).catch((error) => {
-    if (error?.code === "ENOENT") return void 0;
-    throw error;
-  });
-  return !info ? "absent" : info.isDirectory() ? "dir" : info.isSymbolicLink() ? "link" : "file";
-}
-async function createBackup({ home, out, units = HOME_UNITS, projects = [], by = "alp", kind = "manual" }) {
-  return holdTaskLocks(projects.map((root) => path.resolve(root)), () => writeBackup({ home, out, units, projects, by, kind }));
-}
-async function writeBackup({ home, out, units, projects, by, kind }) {
-  const withState = units.some((unit) => unit.startsWith("state/"));
-  const stateSchema = withState ? await readStateSchema(home).then((info) => info.schema, () => null) : null;
-  const header = {
-    t: "header",
-    format: "alp-backup",
-    version: BACKUP_FORMAT,
-    kind,
-    by,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    home,
-    stateSchema,
-    units: await Promise.all(units.map(async (unit) => ({ path: unit, kind: await unitKind(home, unit) }))),
-    projects: await Promise.all(projects.map(async (root) => ({ root: path.resolve(root), units: await Promise.all(PROJECT_UNITS.map(async (unit) => ({ path: unit, kind: await unitKind(root, unit) }))) }))),
-    external: withState ? await externalReferences(home) : []
-  };
-  const digest = createHash("sha256");
-  const summary = { file: out, files: 0, bytes: 0, projects: header.projects.map((project) => project.root), stateSchema, sessions: 0, tasks: 0 };
-  const line = (record) => {
-    const text = `${JSON.stringify(record)}
-`;
-    digest.update(text);
-    return text;
-  };
-  async function* area(name, base, unitList) {
-    for (const { path: unit, kind: kind2 } of unitList) {
-      if (kind2 === "absent") continue;
-      for await (const entry of unitEntries(base, unit)) {
-        if (entry.t !== "file") {
-          yield line({ ...entry, area: name });
-          continue;
-        }
-        const content = await readFile(entry.file);
-        summary.files++;
-        summary.bytes += content.length;
-        if (name === "home" && /^state\/sessions\/[^/]+\.json$/.test(entry.path)) summary.sessions++;
-        if (name !== "home" && /^\.alp\/tasks\/[^/]+\.json$/.test(entry.path)) summary.tasks++;
-        const chunks = Math.max(1, Math.ceil(content.length / CHUNK));
-        yield line({ t: "file", area: name, path: entry.path, mode: entry.mode, size: content.length, sha256: createHash("sha256").update(content).digest("hex"), chunks });
-        for (let index = 0; index < chunks; index++) yield line({ t: "data", b: content.subarray(index * CHUNK, (index + 1) * CHUNK).toString("base64") });
-      }
-    }
-  }
-  async function* lines() {
-    yield line(header);
-    yield* area("home", home, header.units);
-    for (const [index, project] of header.projects.entries()) yield* area(`project:${index}`, project.root, project.units);
-    yield `${JSON.stringify({ t: "end", files: summary.files, bytes: summary.bytes, sha256: digest.digest("hex") })}
-`;
-  }
-  await mkdir(path.dirname(out), { recursive: true, mode: 448 });
-  const partial = `${out}.${randomBytes(4).toString("hex")}.partial`;
-  try {
-    await pipeline(Readable.from(lines()), createGzip(), createWriteStream(partial, { mode: 384 }));
-    await moveFile(partial, out);
-  } catch (error) {
-    await rm(partial, { force: true }).catch(() => {
-    });
-    throw error;
-  }
-  return summary;
-}
-async function automaticBackup(home, kind, { units = HOME_UNITS, projects = [], by } = {}) {
-  const directory = backupsDir(home);
-  const out = path.join(directory, `${kind}-${stamp()}-${randomBytes(2).toString("hex")}${BACKUP_EXTENSION}`);
-  await createBackup({ home, out, units, projects, by, kind });
-  const prefix = `${kind}-`;
-  const same = (await readdir(directory)).filter((name) => name.startsWith(prefix) && name.endsWith(BACKUP_EXTENSION)).sort();
-  for (const name of same.slice(0, Math.max(0, same.length - AUTOMATIC_KEEP))) await rm(path.join(directory, name), { force: true });
-  return out;
-}
-async function readBackup(file, { onHeader, visit }) {
-  if (!await stat(file).then((info) => info.isFile(), () => false)) throw new AlpError("BACKUP_NOT_FOUND", `${file} is not a backup file`);
-  const digest = createHash("sha256");
-  let header;
-  let end;
-  let pending;
-  let files = 0;
-  let bytes = 0;
-  let lineNumber = 0;
-  const written = /* @__PURE__ */ new Map();
-  async function take(text) {
-    lineNumber++;
-    if (end) throw invalid(`line ${lineNumber} follows the end of the backup`);
-    let record;
-    try {
-      record = JSON.parse(text);
-    } catch {
-      throw invalid(`line ${lineNumber} is not JSON`);
-    }
-    if (record?.t === "end") {
-      end = record;
-      return;
-    }
-    digest.update(`${text}
-`);
-    if (!header) {
-      if (record?.t !== "header" || record.format !== "alp-backup") throw invalid("it does not start with an ALP backup header");
-      if (record.version !== BACKUP_FORMAT) throw new AlpError("BACKUP_UNSUPPORTED", `backup format ${record.version} is not one this ALP reads (${BACKUP_FORMAT}); restore it with the ALP that made it, or a newer one`);
-      if (record.stateSchema !== null && record.stateSchema !== void 0 && !(Number.isSafeInteger(record.stateSchema) && record.stateSchema >= 1)) throw invalid("its header names no valid state schema");
-      if (Number.isSafeInteger(record.stateSchema) && record.stateSchema > STATE_SCHEMA) throw new AlpError("BACKUP_SCHEMA_TOO_NEW", `the backup holds state schema ${record.stateSchema}${record.by ? ` from ${record.by}` : ""}; this ALP knows schema ${STATE_SCHEMA} at most. Restore it with that ALP version or a newer one`);
-      if (!Array.isArray(record.units) || !Array.isArray(record.projects) || ![...record.units, ...record.projects.flatMap((project) => project?.units ?? [])].every((unit2) => safeRelative(unit2?.path) && ["file", "dir", "link", "absent"].includes(unit2.kind))) throw invalid("its header lists units ALP cannot use");
-      if (!record.projects.every((project) => typeof project?.root === "string" && path.isAbsolute(project.root) && Array.isArray(project.units))) throw invalid("its header lists projects without an absolute root");
-      for (const list of [record.units, ...record.projects.map((project) => project.units)]) {
-        const paths = list.map((unit2) => unit2.path);
-        if (paths.some((one, index) => paths.some((other, at) => at !== index && (one === other || one.startsWith(`${other}/`))))) throw invalid("its header lists a unit twice, or one inside another");
-      }
-      header = record;
-      await onHeader?.(header);
-      return;
-    }
-    if (pending) {
-      if (record?.t !== "data" || typeof record.b !== "string") throw invalid(`${pending.entry.path} is cut short`);
-      const chunk = Buffer.from(record.b, "base64");
-      pending.hash.update(chunk);
-      pending.size += chunk.length;
-      await pending.write?.(chunk);
-      if (--pending.left > 0) return;
-      const done = pending;
-      pending = void 0;
-      await done.close();
-      return;
-    }
-    const area = record?.area;
-    const units = area === "home" ? header.units : /^project:\d+$/.test(area ?? "") ? header.projects[Number(area.slice(8))]?.units : void 0;
-    if (!units) throw invalid(`line ${lineNumber} belongs to no area of the backup`);
-    if (!safeRelative(record.path)) throw invalid(`line ${lineNumber} names an unsafe path`);
-    const unit = units.find((candidate) => record.path === candidate.path || record.path.startsWith(`${candidate.path}/`));
-    if (!unit || unit.kind === "absent" || record.path !== unit.path && unit.kind !== "dir") throw invalid(`${record.path} lies outside the units the backup declares`);
-    const seen = written.get(area) ?? written.set(area, { paths: /* @__PURE__ */ new Set(), links: [] }).get(area);
-    if (seen.paths.has(record.path) || seen.links.some((link) => record.path.startsWith(`${link}/`))) throw invalid(`${record.path} comes twice, or lies under a link`);
-    seen.paths.add(record.path);
-    if (record.t === "link") seen.links.push(record.path);
-    if (record.t === "dir" || record.t === "link") {
-      if (record.t === "link" && typeof record.target !== "string") throw invalid(`link ${record.path} has no target`);
-      await visit({ ...record, unit: unit.path });
-      return;
-    }
-    if (record.t !== "file" || !Number.isSafeInteger(record.size) || record.size < 0 || typeof record.sha256 !== "string" || !Number.isSafeInteger(record.chunks) || record.chunks < 1) throw invalid(`line ${lineNumber} is not a backup entry`);
-    files++;
-    bytes += record.size;
-    const sink = await visit({ ...record, unit: unit.path });
-    const hash = createHash("sha256");
-    const state = {
-      entry: record,
-      hash,
-      size: 0,
-      left: record.chunks,
-      write: sink?.write,
-      abort: sink?.abort,
-      async close() {
-        await sink?.close?.();
-        if (state.size !== record.size || hash.digest("hex") !== record.sha256) throw invalid(`${record.path} does not match its checksum`);
-      }
-    };
-    pending = state;
-  }
-  let buffered = "";
-  const decoder = new StringDecoder("utf8");
-  let refused;
-  try {
-    await pipeline(createReadStream(file), createGunzip(), async function(source) {
-      for await (const chunk of source) {
-        buffered += decoder.write(chunk);
-        let newline;
-        while ((newline = buffered.indexOf("\n")) >= 0) {
-          const text = buffered.slice(0, newline);
-          buffered = buffered.slice(newline + 1);
-          if (text) await take(text).catch((error) => {
-            refused ??= error;
-            throw error;
-          });
-        }
-      }
-    });
-  } catch (error) {
-    await pending?.abort?.();
-    if (refused) throw refused;
-    if (error instanceof AlpError) throw error;
-    throw invalid(`it cannot be read (${error?.code ?? error?.message ?? error})`, { cause: error });
-  }
-  buffered += decoder.end();
-  if (pending) await pending.abort?.();
-  if (buffered) throw invalid("its last line is cut short");
-  if (!header) throw invalid("it is empty");
-  if (pending) throw invalid(`${pending.entry.path} is cut short`);
-  if (!end) throw invalid("it has no end: the file was cut short");
-  if (end.files !== files || end.bytes !== bytes || end.sha256 !== digest.digest("hex")) throw invalid("its end does not match its content");
-  return { header, files, bytes };
-}
-async function verifyBackup(file) {
-  let sessions = 0;
-  let tasks = 0;
-  const { header, files, bytes } = await readBackup(file, {
-    visit(entry) {
-      if (entry.t !== "file") return;
-      if (entry.area === "home" && /^state\/sessions\/[^/]+\.json$/.test(entry.path)) sessions++;
-      if (entry.area !== "home" && /^\.alp\/tasks\/[^/]+\.json$/.test(entry.path)) tasks++;
-    }
-  });
-  return {
-    file,
-    kind: header.kind,
-    by: header.by,
-    createdAt: header.createdAt,
-    home: header.home,
-    stateSchema: header.stateSchema,
-    units: header.units.filter((unit) => unit.kind !== "absent").map((unit) => unit.path),
-    projects: header.projects.map((project) => project.root),
-    sessions,
-    tasks,
-    files,
-    bytes,
-    external: header.external?.length ?? 0
-  };
-}
-async function settleJournal(journal, { releaseLocks = false } = {}) {
-  if (journal.phase === "committed") {
-    for (const unit of journal.units) await rm(unit.aside, { recursive: true, force: true });
-  } else {
-    for (const unit of [...journal.units].reverse()) {
-      if (await exists(unit.aside)) {
-        await rm(unit.target, { recursive: true, force: true });
-        await moveFile(unit.aside, unit.target);
-      } else if (!unit.existed && unit.staged && !await exists(unit.staged)) {
-        await rm(unit.target, { recursive: true, force: true });
-      }
-    }
-    if (journal.marker) await rm(journal.marker, { force: true });
-  }
-  for (const directory of journal.staging) await rm(directory, { recursive: true, force: true });
-  for (const directory of journal.created ?? []) await rmdir(directory).catch(() => {
-  });
-  if (releaseLocks) for (const lock of journal.locks ?? []) await rmdir(lock).catch(() => {
-  });
-}
-async function recoverInterruptedRestore(home) {
-  let journal;
-  try {
-    journal = JSON.parse(await readFile(journalFile(home), "utf8"));
-  } catch (error) {
-    if (error?.code === "ENOENT") return void 0;
-    throw new AlpError("RESTORE_JOURNAL_UNREADABLE", `${journalFile(home)} records an interrupted restore but cannot be read; see docs/alp/data-recovery.md before starting ALP`, { cause: error });
-  }
-  if (journal?.version !== void 0 && journal.version !== 1) throw new AlpError("RESTORE_JOURNAL_UNREADABLE", `${journalFile(home)} records a restore by another ALP version (journal ${journal.version}); finish it with that version`);
-  if (!Array.isArray(journal?.units) || !Array.isArray(journal.staging)) throw new AlpError("RESTORE_JOURNAL_UNREADABLE", `${journalFile(home)} records an interrupted restore but does not say what moved; see docs/alp/data-recovery.md before starting ALP`);
-  await settleJournal(journal, { releaseLocks: true });
-  await rm(journalFile(home), { force: true });
-  return { outcome: journal.phase === "committed" ? "completed" : "rolled back", file: journal.file, safety: journal.safety };
-}
-async function holdTaskLocks(roots, work) {
-  const held = [];
-  const touch = setInterval(() => {
-    const now = /* @__PURE__ */ new Date();
-    for (const lock of held) void utimes(lock, now, now).catch(() => {
-    });
-  }, 2e3);
-  touch.unref?.();
-  const take = async ([first, ...rest]) => {
-    if (first === void 0) return work();
-    if (!await exists(path.join(first, ".alp", "tasks"))) return take(rest);
-    return withTaskLock(first, () => {
-      held.push(path.join(first, ".alp", "tasks", ".lock"));
-      return take(rest);
-    });
-  };
-  try {
-    return await take(roots);
-  } finally {
-    clearInterval(touch);
-  }
-}
-async function prepareWorkspaceRestore(home, root, units, warnings) {
-  const relevant = [RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/sessions", "state/web-workspaces.json"];
-  const restorable = units.filter((unit) => unit.path !== QUARANTINED_DESTINATIONS);
-  if (!units.some((unit) => relevant.includes(unit.path))) return restorable;
-  for (const base of [home, root]) {
-    const info = await lstat(path.join(base, "state")).catch((error) => {
-      if (error.code === "ENOENT") return void 0;
-      throw error;
-    });
-    if (info && !info.isDirectory()) throw invalid("workspace state must be a real directory");
-  }
-  const result = restorable.filter((unit) => ![RESULT_LEDGER, RESULT_MARKER, DESTINATIONS, "state/web-workspaces.json"].includes(unit.path));
-  async function regular(base, unit, declared) {
-    if (declared && declared.kind === "absent") return void 0;
-    const file = path.join(base, unit);
-    const info = await lstat(file).catch((error) => {
-      if (error.code === "ENOENT") return void 0;
-      throw error;
-    });
-    if (!info) {
-      if (declared) throw invalid(`${unit} is declared but missing from the backup`);
-      return void 0;
-    }
-    if (!info.isFile()) throw invalid(`${unit} must be a regular file for a workspace restore`);
-    return readFile(file, "utf8");
-  }
-  const incoming = async (unit) => {
-    const declared = units.find((entry) => entry.path === unit);
-    return declared ? regular(root, unit, declared) : void 0;
-  };
-  const owners = /* @__PURE__ */ new Map();
-  let hasLedger = false;
-  for (const text of [await incoming(RESULT_LEDGER), await regular(home, RESULT_LEDGER)]) {
-    if (text === void 0) continue;
-    let value;
-    try {
-      value = JSON.parse(text);
-    } catch {
-      throw invalid("assignment result ledger is not readable JSON; repair it before restoring");
-    }
-    const absolute = (value2) => typeof value2 === "string" && path.isAbsolute(value2);
-    if (value?.version !== 1 || !Array.isArray(value.workspaces) || !value.workspaces.every(absolute) || !Array.isArray(value.results) || !value.results.every((entry) => entry && typeof entry.assignmentId === "string" && absolute(entry.checkout) && (entry.worktree === void 0 || absolute(entry.worktree))))
-      throw invalid("assignment result ledger has an unsupported or invalid shape");
-    hasLedger = true;
-    for (const entry of value.results) {
-      const owner = { assignmentId: entry.assignmentId, checkout: entry.checkout, ...entry.worktree === void 0 ? {} : { worktree: entry.worktree } };
-      const previous = owners.get(owner.assignmentId);
-      if (previous && JSON.stringify(previous) !== JSON.stringify(owner)) throw invalid("assignment result ownership conflicts with current data; reconcile it before restoring");
-      owners.set(owner.assignmentId, owner);
-    }
-  }
-  const markers = [await incoming(RESULT_MARKER), await regular(home, RESULT_MARKER)];
-  if (markers.some((text) => text !== void 0 && text !== "1\n")) throw invalid("assignment result initialized marker is invalid");
-  await mkdir(path.join(root, "state"), { recursive: true, mode: 448 });
-  if (hasLedger) await writeAtomic(path.join(root, RESULT_LEDGER), JSON.stringify({ version: 1, workspaces: [], results: [...owners.values()] }) + "\n");
-  result.push({ path: RESULT_LEDGER, kind: hasLedger ? "file" : "absent" });
-  const initialized = markers.some((text) => text !== void 0);
-  if (initialized) await writeAtomic(path.join(root, RESULT_MARKER), "1\n");
-  result.push({ path: RESULT_MARKER, kind: initialized ? "file" : "absent" });
-  const mappings = await incoming(DESTINATIONS);
-  if (mappings !== void 0) {
-    await writeAtomic(path.join(root, QUARANTINED_DESTINATIONS), mappings);
-    result.push({ path: QUARANTINED_DESTINATIONS, kind: "file" });
-  }
-  result.push({ path: DESTINATIONS, kind: "absent" });
-  const registryUnit = "state/web-workspaces.json";
-  const registryDeclaration = units.find((unit) => unit.path === registryUnit);
-  const registryText = registryDeclaration ? await incoming(registryUnit) : await regular(home, registryUnit);
-  if (registryText !== void 0) {
-    let registry;
-    try {
-      registry = JSON.parse(registryText);
-    } catch {
-      throw invalid("workspace registry is not readable JSON; repair it before restoring");
-    }
-    const epoch = `restore-${randomBytes(16).toString("hex")}`;
-    let revoked = false;
-    const revoke = (value) => {
-      if (!value || typeof value !== "object") return;
-      if (Object.hasOwn(value, "grantEpoch")) {
-        value.grantEpoch = epoch;
-        revoked = true;
-      }
-      for (const child of Object.values(value)) revoke(child);
-    };
-    revoke(registry);
-    await writeAtomic(path.join(root, registryUnit), revoked ? JSON.stringify(registry) + "\n" : registryText);
-    result.push({ path: registryUnit, kind: "file" });
-  } else if (registryDeclaration) result.push({ path: registryUnit, kind: "absent" });
-  if (hasLedger || initialized || mappings !== void 0 || await exists(path.join(home, DESTINATIONS))) warnings.push("Workspace restore retains assignment owners but clears checkout birth certification; old targets require an audited migration. Worktree destination mappings are inactive and require explicit host approval; archived mapping evidence is in state/worktree-destinations.quarantined.json. Historical checkout grants remain revoked after reapproval.");
-  return result;
-}
-async function restoreBackup({ home, file, projects = true, safety = true, clearLive = true, replaceNewer = false, by = "alp", beforeSwap }) {
-  const interrupted = await recoverInterruptedRestore(home);
-  try {
-    assertStateSupported(await readStateSchema(home), home);
-  } catch (error) {
-    if (error?.code !== "STATE_SCHEMA_UNREADABLE" && !(error?.code === "STATE_SCHEMA_TOO_NEW" && replaceNewer)) throw error;
-  }
-  const id = randomBytes(6).toString("hex");
-  const staging = /* @__PURE__ */ new Map();
-  const skipped = [];
-  let header;
-  const warnings = [];
-  const areaBase = (area) => area === "home" ? home : header.projects[Number(area.slice(8))].root;
-  const directories = [];
-  let homeUnits;
-  const journal = { version: 1, id, file: path.resolve(file), by, startedAt: (/* @__PURE__ */ new Date()).toISOString(), phase: "staging", units: [], staging: [], created: [], locks: [] };
-  const record = () => writeAtomic(journalFile(home), JSON.stringify(journal) + "\n");
-  const abandon = async () => {
-    await settleJournal(journal);
-    await rm(journalFile(home), { force: true });
-  };
-  try {
-    await readBackup(file, {
-      async onHeader(found) {
-        header = found;
-        staging.set("home", path.join(home, `.restore-${id}`));
-        for (const [index, project] of header.projects.entries()) {
-          if (!projects) continue;
-          if (!await stat(project.root).then((info) => info.isDirectory(), () => false)) {
-            skipped.push({ root: project.root, reason: "the directory does not exist" });
-            continue;
-          }
-          if (!await exists(path.join(project.root, ".alp"))) journal.created.push(path.join(project.root, ".alp"));
-          staging.set(`project:${index}`, path.join(project.root, ".alp", `.restore-${id}`));
-        }
-        journal.staging = [...staging.values()];
-        await record();
-      },
-      async visit(entry) {
-        const root = staging.get(entry.area);
-        if (!root) return void 0;
-        const target = path.join(root, ...entry.path.split("/"));
-        await mkdir(path.dirname(target), { recursive: true, mode: 448 });
-        if (entry.t === "dir") {
-          await mkdir(target, { recursive: true, mode: 448 });
-          directories.push([target, entry.mode]);
-          return void 0;
-        }
-        if (entry.t === "link") {
-          await symlink(entry.target, target);
-          return void 0;
-        }
-        const handle = await open(target, "wx", 384);
-        return {
-          write: (chunk) => handle.write(chunk).then(() => {
-          }),
-          close: async () => {
-            await handle.close();
-            await chmod(target, entry.mode & 511 || 384).catch(() => {
-            });
-          },
-          abort: () => handle.close().catch(() => {
-          })
-        };
-      }
-    });
-    homeUnits = await prepareWorkspaceRestore(home, staging.get("home"), header.units, warnings);
-    for (const [directory, mode] of directories.reverse()) if (Number.isSafeInteger(mode)) await chmod(directory, mode & 511 | 448).catch(() => {
-    });
-  } catch (error) {
-    await abandon();
-    throw error;
-  }
-  for (const [area, root] of staging) {
-    const base = area === "home" ? "state/sessions" : ".alp/tasks";
-    for (const name of await readdir(path.join(root, ...base.split("/"))).catch(() => [])) {
-      if (!name.endsWith(".json")) continue;
-      try {
-        JSON.parse(await readFile(path.join(root, ...base.split("/"), name), "utf8"));
-      } catch {
-        warnings.push(`${area === "home" ? "" : `${areaBase(area)}/`}${base}/${name} is not readable JSON; ALP skips it as before`);
-      }
-    }
-  }
-  const plan = [];
-  for (const [area, root] of staging) {
-    const base = areaBase(area);
-    const units = area === "home" ? homeUnits : header.projects[Number(area.slice(8))].units;
-    const known = area === "home" ? [...HOME_UNITS, QUARANTINED_DESTINATIONS] : PROJECT_UNITS;
-    for (const unit of units) {
-      if (!known.includes(unit.path)) {
-        warnings.push(`${unit.path} is not a unit this ALP restores; left as it is`);
-        continue;
-      }
-      const target = path.join(base, ...unit.path.split("/"));
-      const staged = unit.kind === "absent" ? void 0 : path.join(root, ...unit.path.split("/"));
-      if (staged && !await exists(staged)) {
-        await abandon();
-        throw invalid(`${unit.path} is declared but missing from the backup`);
-      }
-      plan.push({ area, unit: unit.path, target, staged, aside: `${target}.pre-restore-${id}`, existed: await exists(target) });
-    }
-    if (area === "home" && clearLive && units.some((unit) => unit.path === "state/sessions")) {
-      for (const unit of CLEARED_UNITS) {
-        const target = path.join(base, ...unit.split("/"));
-        plan.push({ area, unit, target, staged: void 0, aside: `${target}.pre-restore-${id}`, existed: await exists(target) });
-      }
-    }
-  }
-  const roots = [...staging.keys()].filter((area) => area !== "home").map(areaBase);
-  let safetyFile;
-  if (safety) {
-    try {
-      safetyFile = await automaticBackup(home, "pre-restore", { units: [.../* @__PURE__ */ new Set([...header.units.map((unit) => unit.path), ...homeUnits.map((unit) => unit.path)])].filter((unit) => HOME_UNITS.includes(unit) || unit === QUARANTINED_DESTINATIONS), projects: roots, by });
-    } catch (error) {
-      await abandon();
-      throw new AlpError("RESTORE_SAFETY_BACKUP_FAILED", `could not save the current data before restoring (${error?.message ?? error}); nothing was changed`, { cause: error });
-    }
-  }
-  const locked = /* @__PURE__ */ new Set();
-  for (const root of roots) if (await exists(path.join(root, ".alp", "tasks"))) locked.add(root);
-  const marking = clearLive && plan.some((entry) => entry.area === "home" && entry.unit === "state/sessions");
-  Object.assign(journal, { safety: safetyFile, phase: "swapping", units: plan, locks: [...locked].map((root) => path.join(root, ".alp", "tasks", ".lock")), ...marking ? { marker: path.join(home, RESTORED) } : {} });
-  await record();
-  let failure;
-  try {
-    await holdTaskLocks(roots, async () => {
-      try {
-        for (const [index, entry] of plan.entries()) {
-          await beforeSwap?.(index, plan.length);
-          if (entry.existed) await moveFile(entry.target, entry.aside);
-          if (entry.staged) {
-            await mkdir(path.dirname(entry.target), { recursive: true, mode: 448 });
-            if (entry.unit === ".alp/tasks" && locked.has(areaBase(entry.area))) await mkdir(path.join(entry.staged, ".lock")).catch(() => {
-            });
-            await moveFile(entry.staged, entry.target);
-          }
-        }
-        if (marking) {
-          await mkdir(path.join(home, "state"), { recursive: true, mode: 448 });
-          await writeAtomic(path.join(home, RESTORED), JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), from: path.resolve(file), by }) + "\n");
-        }
-        await beforeSwap?.(plan.length, plan.length);
-        journal.phase = "committed";
-        await record();
-      } catch (error) {
-        try {
-          await abandon();
-        } catch (rollback) {
-          failure = new AlpError("RESTORE_ROLLBACK_FAILED", `restore failed (${error?.message ?? error}) and moving the data back failed (${rollback?.message ?? rollback}); ${journalFile(home)} records what is where, and the next alp restore or alpd start tries again`, { cause: error });
-          return;
-        }
-        failure = new AlpError("RESTORE_FAILED", `restore failed and was rolled back; the data is as it was: ${error?.message ?? error}`, { cause: error });
-      }
-    });
-  } catch (error) {
-    if (journal.phase !== "committed" && !failure) {
-      await abandon();
-      throw new AlpError("RESTORE_FAILED", `restore failed and was rolled back; the data is as it was: ${error?.message ?? error}`, { cause: error });
-    }
-  }
-  if (failure) throw failure;
-  await settleJournal(journal);
-  await rm(journalFile(home), { force: true });
-  return {
-    file: path.resolve(file),
-    safety: safetyFile,
-    stateSchema: header.stateSchema,
-    interrupted,
-    units: plan.map((entry) => ({ area: entry.area === "home" ? "home" : areaBase(entry.area), unit: entry.unit, present: !!entry.staged })),
-    projects: roots,
-    skipped,
-    warnings
-  };
-}
-async function readRestoredMarker(home) {
-  const text = await readFile(path.join(home, RESTORED), "utf8").catch(() => void 0);
-  if (text === void 0) return void 0;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return { at: void 0 };
-  }
-}
-async function clearRestoredMarker(home) {
-  await rm(path.join(home, RESTORED), { force: true });
-}
-export {
-  BACKUP_EXTENSION,
-  BACKUP_FORMAT,
-  CLEARED_UNITS,
-  HOME_UNITS,
-  PROJECT_UNITS,
-  STATE_UNITS,
-  automaticBackup,
-  backupsDir,
-  clearRestoredMarker,
-  createBackup,
-  knownProjects,
-  readRestoredMarker,
-  recoverInterruptedRestore,
-  restoreBackup,
-  verifyBackup
-};