Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

39.9 KB
Raw Blame
/**
 * The data root's storage ledger, and the human-reviewed cleanup that reads it.
 *
 * Two halves, one vocabulary. `report()` walks the root and answers with what is there and
 * what could go — it deletes nothing, moves nothing and is safe to call at any moment (see
 * core's state/storage.ts, the single definition point of the classes it maps). Everything else
 * here is the design's second step: a **bill** written out of that ledger, reviewed by a person,
 * approved once, and only then moved — into the trash, never unlinked.
 *
 * The rules that shape the whole node, in one place:
 *
 * - **Nothing runs by itself.** There is no timer and no threshold that acts; a scan happens
 *   because somebody asked for one, and a move because somebody selected entries and pressed
 *   the button. What may happen automatically is a report.
 * - **The cleanup mode gates every write.** `enabled` is off until a person turns it on;
 *   scanning, pinning, moving and purging are all refused while it is off, so an untouched
 *   install has exactly the read-only behaviour the previous version had.
 * - **A plan is used once, and only if the disk still matches it.** An approval quotes the
 *   bill's fingerprint; the entries are re-measured and re-checked against live state before
 *   anything moves, so a tree that grew, was touched or came alive in the meantime stops the
 *   run instead of being cleaned up half-reviewed.
 * - **A move is a rename into `<root>/.trash/<stamp>/items/<original path>`** plus a manifest,
 *   which makes the whole thing reversible with the same call. The one deletion in the file is
 *   `purge`, which removes a trash entry a person named (or one past the retention) — and it
 *   never touches anything that is not already in the trash.
 *
 * Liveness is the server's own state, so it is assembled here rather than in core's pure
 * `scanStorage`: `SessionIndex.listByProject` over `Projects.listAll` is every Session row that
 * still exists — the index creation, Trace adoption and deletion all keep current — and each
 * row carries both the Workspace it points at and its last activity. At apply time it is read
 * again, so a Workspace that a Session started using after the scan is refused rather than
 * moved.
 *
 * A Session in the middle of being deleted (`SessionManager.beginSessionDeletion`) is NOT
 * excluded, because that window is not reachable from a node: `SessionManager` keeps its
 * `deletingSessions` set private, and the `Sessions` mechanism exposes only the begin/end pair
 * with no way to ask about one id. Counting such a Session as live is the safe direction — it
 * can only make an entry look referenced, never claim that something a deletion is about to
 * remove is free — and for apply it means the entry is refused, which is the answer a person
 * can act on (scan again once the deletion is done).
 */
import fs from "node:fs/promises";
import path from "node:path";
import { randomBytes } from "node:crypto";
import {
  buildStoragePlan,
  EXECUTABLE_STORAGE_CLASSES,
  isExecutableStorageClass,
  isPlannablePath,
  isInsideRoot,
  measureStorageEntry,
  planEntryFingerprint,
  resolveStorageEntry,
  scanStorage,
  storageLogFile,
  storagePlanId,
  storagePlansDir,
  storageTrashDir,
  storageTrashId,
} from "@adelie/core";
import type {
  StorageClass,
  StorageEntry as LedgerEntry,
  StorageLiveSet,
  StoragePlan,
  StoragePlanEntry,
} from "@adelie/core";
import { Component, Interface, Use } from "@adelie/core/kernel";
import { HttpError } from "../http/errors.js";
import type {
  StorageApplyResponse,
  StorageCandidate,
  StoragePlanView,
  StoragePurgeResponse,
  StorageReport,
  StorageRestoreResponse,
  StorageSettings,
  StorageSettingsUpdateRequest,
  StorageTrashEntry,
} from "../api/types.js";
import type { Paths } from "../hmr/capabilities.js";
import type { Projects } from "../mechanisms/projects.js";
import type { SessionIndex } from "../mechanisms/sessions.js";
import type { Settings } from "../mechanisms/settings.js";

/**
 * What a node may require to work with the data root's storage: the report, and the reviewed
 * cleanup that reads it. There is no "clean this class" or "run a policy" method — the design's
 * guarantee is that a removal needs a specific bill a person looked at, and a surface narrower
 * than that could not express one.
 */
@Interface()
export abstract class StorageAdmin {
  abstract report(): Promise<StorageReport>;
  abstract settings(): StorageSettings;
  abstract updateSettings(update: StorageSettingsUpdateRequest): StorageSettings;
  /** Scans and writes a bill; refuses while the cleanup mode is off. */
  abstract scan(): Promise<StoragePlanView>;
  abstract plans(): Promise<StoragePlanView[]>;
  abstract plan(planId: string): Promise<StoragePlanView>;
  abstract pin(input: { path: string; pinned: boolean }): Promise<StorageSettings>;
  abstract apply(input: {
    planId: string;
    fingerprint: string;
    paths: string[];
  }): Promise<StorageApplyResponse>;
  abstract trash(): Promise<StorageTrashEntry[]>;
  abstract restore(trashId: string): Promise<StorageRestoreResponse>;
  abstract purge(trashId: string | null): Promise<StoragePurgeResponse>;
}

/** `server_settings` key holding the cleanup mode's settings, one JSON object. */
const STORAGE_SETTINGS_KEY = "storage";

/** Trash entries live this long before a purge without an id may remove them. */
const DEFAULT_TRASH_TTL_DAYS = 14;
const MIN_TRASH_TTL_DAYS = 1;
const MAX_TRASH_TTL_DAYS = 365;

/** Plans a listing returns, newest first — enough to review, not a second storage table. */
const PLAN_LIST_LIMIT = 20;

/** Ids are used as file and directory names, so they are checked before they are joined. */
const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;

const TRASH_MANIFEST = "manifest.json";
const TRASH_ITEMS_DIR = "items";

/** The defaults of a machine that has never turned the cleanup mode on. */
const DEFAULT_STORAGE_SETTINGS: StorageSettings = {
  enabled: false,
  trashTtlDays: DEFAULT_TRASH_TTL_DAYS,
  pins: [],
};

/** What a trash entry's manifest records: enough to put every tree back where it came from. */
interface TrashManifest {
  id: string;
  createdAtMs: number;
  planId: string;
  items: { path: string; class: StorageClass; bytes: number; files: number }[];
}

@Component()
export class StorageService implements StorageAdmin {
  @Use() private readonly paths!: Paths;
  @Use() private readonly projects!: Projects;
  @Use() private readonly sessions!: SessionIndex;
  @Use() private readonly settingsRepo!: Settings;

  /** The write in flight, by name — the single-writer rule, made visible rather than queued. */
  private running: string | null = null;

  async report(): Promise<StorageReport> {
    // The design's default policy, with no way to pass another one (see the interface above):
    // the report lists what is provably unreferenced or empty, and every age- or budget-based
    // rule stays off.
    const ledger = await scanStorage(this.paths.root, await this.liveSet());
    return {
      root: ledger.root,
      // The instant the walk observed, as ISO: the report describes that moment rather than
      // the moment it is read, which is why the stamp is not taken here.
      scannedAt: new Date(ledger.scannedAtMs).toISOString(),
      totalBytes: ledger.totalBytes,
      // Field-for-field the ledger's own: the DTO spells the shape out instead of importing
      // core's types (api/types.ts is the Web contract and takes core's pure subpaths only),
      // so the compiler is what keeps the two in step.
      classes: ledger.classes,
      candidates: ledger.candidates.map(toCandidate),
      sharedEnvGroups: ledger.sharedEnvGroups,
      disk: ledger.disk,
      unreadable: ledger.unreadable,
    };
  }

  settings(): StorageSettings {
    return this.readSettings();
  }

  updateSettings(update: StorageSettingsUpdateRequest): StorageSettings {
    const current = this.readSettings();
    const next: StorageSettings = {
      enabled: update.enabled ?? current.enabled,
      trashTtlDays: update.trashTtlDays ?? current.trashTtlDays,
      pins: update.pins ?? current.pins,
    };
    if (
      !Number.isInteger(next.trashTtlDays) ||
      next.trashTtlDays < MIN_TRASH_TTL_DAYS ||
      next.trashTtlDays > MAX_TRASH_TTL_DAYS
    ) {
      throw new HttpError(
        400,
        "invalid_trash_ttl",
        `trashTtlDays must be a whole number of days between ${MIN_TRASH_TTL_DAYS} and ${MAX_TRASH_TTL_DAYS}.`,
      );
    }
    for (const pin of next.pins) this.assertPinnablePath(pin);
    if (next.enabled !== current.enabled) {
      this.audit({ action: next.enabled ? "mode_on" : "mode_off" });
    }
    // A changed pin list is a decision about data, so it is recorded like one: the audit file
    // is what answers "why is this entry not on the bill any more" months later.
    for (const pin of next.pins)
      if (!current.pins.includes(pin)) this.audit({ action: "pin", path: pin });
    for (const pin of current.pins)
      if (!next.pins.includes(pin)) this.audit({ action: "unpin", path: pin });
    this.settingsRepo.set(STORAGE_SETTINGS_KEY, JSON.stringify(next));
    return next;
  }

  async pin(input: { path: string; pinned: boolean }): Promise<StorageSettings> {
    this.assertModeOn("pinning");
    this.assertPinnablePath(input.path);
    const current = this.readSettings();
    const pins = input.pinned
      ? [...new Set([...current.pins, input.path])].sort()
      : current.pins.filter((pin) => pin !== input.path);
    return this.updateSettings({ pins });
  }

  async scan(): Promise<StoragePlanView> {
    this.assertModeOn("scanning");
    this.assertIdle("scan");
    this.running = "scan";
    try {
      const nowMs = Date.now();
      const pins = new Set(this.readSettings().pins);
      const ledger = await scanStorage(this.paths.root, await this.liveSet());
      const plan = buildStoragePlan(ledger, {
        id: storagePlanId(nowMs, randomBytes(3).toString("hex")),
        nowMs,
        pins,
      });
      await this.writePlan(plan);
      this.audit({
        action: "scan",
        planId: plan.id,
        entries: plan.entries.length,
        bytes: plan.totalBytes,
        excluded: plan.excluded.length,
      });
      return toPlanView(plan, nowMs);
    } finally {
      this.running = null;
    }
  }

  async plans(): Promise<StoragePlanView[]> {
    const dir = storagePlansDir(this.paths.root);
    let names: string[];
    try {
      names = await fs.readdir(dir);
    } catch {
      return [];
    }
    const nowMs = Date.now();
    const views: StoragePlanView[] = [];
    // The id starts with its local timestamp, so a reverse string sort is newest first.
    for (const name of names
      .filter((n) => n.endsWith(".json"))
      .sort()
      .reverse()) {
      if (views.length >= PLAN_LIST_LIMIT) break;
      const plan = await this.readPlanFile(name.slice(0, -".json".length));
      if (plan !== null) views.push(toPlanView(plan, nowMs));
    }
    return views;
  }

  async plan(planId: string): Promise<StoragePlanView> {
    const plan = await this.readPlanFile(planId);
    if (plan === null) {
      throw new HttpError(
        404,
        "plan_not_found",
        "No plan with that id. Scan again for a new bill.",
      );
    }
    return toPlanView(plan, Date.now());
  }

  /**
   * The one destructive path: validate the whole batch against the bill and the disk, and only
   * then move each entry. Validation is all-or-nothing — a single stale, pinned, referenced or
   * disallowed entry refuses the run and names why, because a person approved a list and not a
   * subset of it — while the moves themselves are per entry, so one failure does not strand the
   * rest half-done (each move is logged before it happens, and a rerun converges).
   */
  async apply(input: {
    planId: string;
    fingerprint: string;
    paths: string[];
  }): Promise<StorageApplyResponse> {
    this.assertModeOn("applying");
    this.assertIdle("apply");
    this.running = "apply";
    try {
      const nowMs = Date.now();
      const plan = await this.readPlanFile(input.planId);
      if (plan === null) {
        throw new HttpError(
          404,
          "plan_not_found",
          "No plan with that id. Scan again for a new bill.",
        );
      }
      if (plan.appliedAtMs !== undefined) {
        throw new HttpError(
          409,
          "plan_used",
          "This plan has already been applied. A plan is valid for one run: scan again for a new bill.",
        );
      }
      if (nowMs > plan.expiresAtMs) {
        throw new HttpError(
          409,
          "plan_expired",
          "This plan is older than 24 hours. Scan again so the bill describes the disk as it is now.",
        );
      }
      if (input.fingerprint !== plan.fingerprint) {
        throw new HttpError(
          409,
          "plan_stale",
          "The fingerprint does not match this plan. Read the bill again before approving it.",
        );
      }
      if (input.paths.length === 0) {
        throw new HttpError(
          400,
          "nothing_selected",
          "Nothing was selected. Approve at least one entry, by its recorded path.",
        );
      }
      const entries = this.selectEntries(plan, input.paths);
      await this.assertBatchStillValid(entries);
      const result = await this.moveToTrash(plan, entries, nowMs);
      // The plan is spent even when every move failed: it was approved once, and nothing may be
      // replayed against a disk the next scan will describe differently.
      await this.writePlan({
        ...plan,
        appliedAtMs: nowMs,
        appliedPaths: result.moved.map((item) => item.path),
      });
      this.audit({
        action: "apply",
        planId: plan.id,
        trashId: result.trashId,
        moved: result.moved.length,
        failed: result.failed.length,
        bytes: result.freedBytes,
      });
      return result;
    } finally {
      this.running = null;
    }
  }

  async trash(): Promise<StorageTrashEntry[]> {
    const dir = storageTrashDir(this.paths.root);
    let names: string[];
    try {
      names = await fs.readdir(dir);
    } catch {
      return [];
    }
    const nowMs = Date.now();
    const ttlMs = this.readSettings().trashTtlDays * 86_400_000;
    const entries: StorageTrashEntry[] = [];
    for (const name of names.sort().reverse()) {
      const entry = await this.readTrashEntry(name);
      if (entry === null) continue;
      entries.push({ ...entry, expired: nowMs - Date.parse(entry.createdAt) > ttlMs });
    }
    return entries;
  }

  /** Puts every tree in one trash entry back where it came from, refusing what is in the way. */
  async restore(trashId: string): Promise<StorageRestoreResponse> {
    this.assertModeOn("restoring");
    this.assertIdle("restore");
    this.running = "restore";
    try {
      const manifest = await this.readTrashManifest(trashId);
      if (manifest === null) {
        throw new HttpError(404, "trash_not_found", "No trash entry with that id.");
      }
      const entryDir = path.join(storageTrashDir(this.paths.root), trashId);
      const restored: string[] = [];
      const skipped: { path: string; reason: string }[] = [];
      for (const item of manifest.items) {
        const source = path.join(entryDir, TRASH_ITEMS_DIR, ...item.path.split("/"));
        const target = path.join(this.paths.root, ...item.path.split("/"));
        if (!(await exists(source))) {
          skipped.push({ path: item.path, reason: "not_in_trash" });
          continue;
        }
        if (await exists(target)) {
          // Something else is there now — the path was reused by a new Session's Workspace, or
          // the tree was put back by other means. Neither is a reason to overwrite it.
          skipped.push({ path: item.path, reason: "target_exists" });
          continue;
        }
        try {
          await fs.mkdir(path.dirname(target), { recursive: true });
          await this.audit({ action: "restore", trashId, path: item.path });
          await fs.rename(source, target);
          restored.push(item.path);
        } catch (e) {
          skipped.push({ path: item.path, reason: reasonOf(e) });
        }
      }
      // An entry that holds nothing any more is removed with the empty directories it leaves:
      // nothing in it is data a person put there, and an empty trash reads as a broken one.
      // "Holds nothing" is asked of the whole tree, not of the top level: moving one tree out
      // leaves the directories it was nested in behind, empty.
      const remaining = await hasAnyContent(path.join(entryDir, TRASH_ITEMS_DIR));
      if (!remaining) await fs.rm(entryDir, { recursive: true, force: true });
      this.audit({
        action: "restore_done",
        trashId,
        restored: restored.length,
        skipped: skipped.length,
      });
      return { id: trashId, restored, skipped, remaining };
    } finally {
      this.running = null;
    }
  }

  /**
   * The one place that deletes. With an id it removes that trash entry; without one it removes
   * the entries past the retention. Both are a person's command — nothing calls this on a
   * timer — and neither can reach anything outside `<root>/.trash`.
   */
  async purge(trashId: string | null): Promise<StoragePurgeResponse> {
    this.assertModeOn("purging");
    this.assertIdle("purge");
    this.running = "purge";
    try {
      if (trashId !== null && !ID_PATTERN.test(trashId)) {
        throw new HttpError(400, "invalid_trash_id", "That is not a trash id.");
      }
      const ttlMs = this.readSettings().trashTtlDays * 86_400_000;
      const nowMs = Date.now();
      const purged: { id: string; bytes: number; files: number }[] = [];
      const trashRoot = storageTrashDir(this.paths.root);
      if (trashId !== null && !(await exists(path.join(trashRoot, trashId)))) {
        throw new HttpError(404, "trash_not_found", "No trash entry with that id.");
      }
      const candidates =
        trashId === null
          ? (await this.trash()).filter((entry) => entry.expired).map((entry) => entry.id)
          : [trashId];
      for (const id of candidates) {
        const dir = path.join(trashRoot, id);
        const measured = await measureStorageEntry(dir);
        if (measured === null) continue;
        await this.audit({
          action: "purge",
          trashId: id,
          bytes: measured.bytes,
          expiredOnly: trashId === null,
          ageMs: nowMs,
        });
        await fs.rm(dir, { recursive: true, force: true });
        purged.push({ id, bytes: measured.bytes, files: measured.files });
      }
      return { purged };
    } finally {
      this.running = null;
    }
  }

  /**
   * The selected paths, as plan entries: every one must be on the bill, of a class this version
   * may act on, allowed by the prefix whitelist, and not pinned. Checked before the disk is
   * touched at all, and the failure names the path so the person can fix the selection.
   */
  private selectEntries(plan: StoragePlan, paths: string[]): StoragePlanEntry[] {
    const byPath = new Map(plan.entries.map((entry) => [entry.path, entry]));
    const pins = new Set(this.readSettings().pins);
    const selected: StoragePlanEntry[] = [];
    const seen = new Set<string>();
    for (const requested of paths) {
      if (seen.has(requested)) continue;
      seen.add(requested);
      const entry = byPath.get(requested);
      if (entry === undefined) {
        throw new HttpError(
          400,
          "unknown_path",
          `Not an entry of this plan: ${requested}. Read the bill again.`,
        );
      }
      if (!isExecutableStorageClass(entry.class)) {
        throw new HttpError(
          409,
          "class_not_executable",
          `This version does not clean ${entry.class} entries; it only reports them: ${entry.path}.`,
        );
      }
      if (!isPlannablePath(entry.path, entry.class)) {
        throw new HttpError(
          400,
          "path_not_allowed",
          `Outside what this class may touch: ${entry.path}.`,
        );
      }
      if (pins.has(entry.path)) {
        throw new HttpError(
          409,
          "pinned_path",
          `Pinned — it will never be cleaned: ${entry.path}.`,
        );
      }
      selected.push(entry);
    }
    return selected;
  }

  /**
   * The disk check, run against the whole selection before a single move: every entry still
   * resolves inside the root as a real directory, still measures exactly as the bill recorded,
   * and is still unreferenced by live state. All-or-nothing on purpose — the answer to any
   * mismatch is a new scan, and a partial run would clean up a list nobody reviewed as a whole.
   */
  private async assertBatchStillValid(entries: StoragePlanEntry[]): Promise<void> {
    const root = this.paths.root;
    const live = await this.liveSet();
    const gone: string[] = [];
    const changed: string[] = [];
    const escaped: string[] = [];
    const revived: string[] = [];
    const targets: { entry: StoragePlanEntry; target: string }[] = [];
    for (const entry of entries) {
      const target = await resolveStorageEntry(root, entry.path);
      if (target === null) {
        // Either it vanished, or it is a symlink (or a file) where the bill recorded a
        // directory: both are drift, and neither may be moved.
        escaped.push(entry.path);
        continue;
      }
      const measured = await measureStorageEntry(target);
      if (measured === null) {
        gone.push(entry.path);
        continue;
      }
      const nowFingerprint = planEntryFingerprint({
        path: entry.path,
        bytes: measured.bytes,
        newestMtimeMs: measured.newestMtimeMs,
      });
      if (nowFingerprint !== entry.fingerprint) {
        changed.push(entry.path);
        continue;
      }
      if (live.workspacePaths.has(target)) {
        revived.push(entry.path);
        continue;
      }
      targets.push({ entry, target });
    }
    if (escaped.length > 0) {
      throw new HttpError(
        409,
        "path_not_allowed",
        `No longer a directory inside the data root, or not one this version may move: ${nameList(escaped)}.`,
      );
    }
    if (gone.length > 0) {
      throw new HttpError(409, "plan_stale", `Gone since the scan: ${nameList(gone)}. Scan again.`);
    }
    if (changed.length > 0) {
      throw new HttpError(
        409,
        "plan_stale",
        `Changed since the scan (size or modification time): ${nameList(changed)}. Scan again.`,
      );
    }
    if (revived.length > 0) {
      throw new HttpError(
        409,
        "entry_still_live",
        `A Session started using this after the scan, so it is not a candidate any more: ${nameList(revived)}.`,
      );
    }
  }

  /**
   * Moves each approved entry into this run's trash directory. A rename within one filesystem,
   * so a move is atomic and a failure leaves the tree exactly where it was; the audit line is
   * written *before* the move, which is what makes a torn run explainable.
   */
  private async moveToTrash(
    plan: StoragePlan,
    entries: StoragePlanEntry[],
    nowMs: number,
  ): Promise<StorageApplyResponse> {
    const trashRoot = storageTrashDir(this.paths.root);
    const moved: { path: string; bytes: number; files: number }[] = [];
    const failed: { path: string; reason: string }[] = [];
    // Resolve the entries again here rather than trusting the check above: the two are one
    // breath apart, but the path is what gets joined, and it is cheap to be sure.
    const resolved: { entry: StoragePlanEntry; target: string }[] = [];
    for (const entry of entries) {
      const target = await resolveStorageEntry(this.paths.root, entry.path);
      if (target === null) {
        failed.push({ path: entry.path, reason: "path_not_allowed" });
        continue;
      }
      resolved.push({ entry, target });
    }
    if (resolved.length === 0) {
      return { planId: plan.id, trashId: null, moved, failed, freedBytes: 0 };
    }
    const trashId = await this.createTrashEntry(trashRoot, plan, nowMs);
    const entryDir = path.join(trashRoot, trashId);
    const manifest: TrashManifest = {
      id: trashId,
      createdAtMs: nowMs,
      planId: plan.id,
      items: resolved.map(({ entry }) => ({
        path: entry.path,
        class: entry.class,
        bytes: entry.bytes,
        files: entry.files,
      })),
    };
    await fs.writeFile(
      path.join(entryDir, TRASH_MANIFEST),
      `${JSON.stringify(manifest, null, 2)}\n`,
      "utf8",
    );
    for (const { entry, target } of resolved) {
      const destination = path.join(entryDir, TRASH_ITEMS_DIR, ...entry.path.split("/"));
      try {
        await fs.mkdir(path.dirname(destination), { recursive: true });
        await this.audit({
          action: "move",
          planId: plan.id,
          trashId,
          path: entry.path,
          class: entry.class,
          bytes: entry.bytes,
          files: entry.files,
          rules: entry.rules,
        });
        await fs.rename(target, destination);
        moved.push({ path: entry.path, bytes: entry.bytes, files: entry.files });
      } catch (e) {
        failed.push({ path: entry.path, reason: reasonOf(e) });
        await this.audit({
          action: "move_failed",
          planId: plan.id,
          path: entry.path,
          reason: reasonOf(e),
        });
      }
    }
    return {
      planId: plan.id,
      trashId,
      moved,
      failed,
      freedBytes: moved.reduce((sum, item) => sum + item.bytes, 0),
    };
  }

  /** This run's trash directory, with a counter when another run already used the stamp. */
  private async createTrashEntry(
    trashRoot: string,
    plan: StoragePlan,
    nowMs: number,
  ): Promise<string> {
    const stamp = storageTrashId(nowMs);
    for (let attempt = 0; ; attempt += 1) {
      const id = attempt === 0 ? stamp : `${stamp}-${attempt + 1}`;
      const dir = path.join(trashRoot, id);
      try {
        await fs.mkdir(dir, { recursive: false });
        return id;
      } catch (e) {
        if ((e as NodeJS.ErrnoException).code === "ENOENT") {
          await fs.mkdir(trashRoot, { recursive: true });
          continue;
        }
        if ((e as NodeJS.ErrnoException).code === "EEXIST" && attempt < 50) continue;
        // Inside the trash but outside a run's directory, so the manifest is still the record
        // of what moved: a failure to name the run's own directory is worth stopping for.
        throw new HttpError(
          500,
          "trash_unavailable",
          `Could not create a trash entry under ${trashRoot} for plan ${plan.id}.`,
        );
      }
    }
  }

  /** Reads one trash entry: the manifest for its items, the disk for its size. */
  private async readTrashEntry(id: string): Promise<StorageTrashEntry | null> {
    const dir = path.join(storageTrashDir(this.paths.root), id);
    const measured = await measureStorageEntry(dir);
    if (measured === null) return null;
    const manifest = await this.readTrashManifest(id);
    const createdAtMs = manifest?.createdAtMs ?? (await mtimeMs(dir));
    return {
      id,
      createdAt: new Date(createdAtMs).toISOString(),
      planId: manifest?.planId ?? null,
      bytes: measured.bytes,
      files: measured.files,
      items: manifest?.items ?? [],
      // Overwritten by the caller, which is where the retention setting is read.
      expired: false,
    };
  }

  /**
   * A trash entry's manifest, or null when it is missing or unreadable. A hand-edited or
   * truncated manifest still lets the entry be listed and purged — it just cannot be restored
   * entry by entry, which is a documentable state rather than a crash.
   */
  private async readTrashManifest(id: string): Promise<TrashManifest | null> {
    if (!ID_PATTERN.test(id)) return null;
    try {
      const raw = await fs.readFile(
        path.join(storageTrashDir(this.paths.root), id, TRASH_MANIFEST),
        "utf8",
      );
      const parsed: unknown = JSON.parse(raw);
      if (typeof parsed !== "object" || parsed === null) return null;
      const manifest = parsed as Partial<TrashManifest>;
      if (!Array.isArray(manifest.items)) return null;
      return {
        id,
        createdAtMs: typeof manifest.createdAtMs === "number" ? manifest.createdAtMs : 0,
        planId: typeof manifest.planId === "string" ? manifest.planId : "",
        items: manifest.items.filter(
          (item): item is TrashManifest["items"][number] =>
            typeof item === "object" &&
            item !== null &&
            typeof (item as { path?: unknown }).path === "string",
        ),
      };
    } catch {
      return null;
    }
  }

  private async writePlan(plan: StoragePlan): Promise<void> {
    const dir = storagePlansDir(this.paths.root);
    await fs.mkdir(dir, { recursive: true });
    await fs.writeFile(
      path.join(dir, `${plan.id}.json`),
      `${JSON.stringify(plan, null, 2)}\n`,
      "utf8",
    );
  }

  private async readPlanFile(id: string): Promise<StoragePlan | null> {
    if (!ID_PATTERN.test(id)) return null;
    try {
      const raw = await fs.readFile(
        path.join(storagePlansDir(this.paths.root), `${id}.json`),
        "utf8",
      );
      const parsed: unknown = JSON.parse(raw);
      if (typeof parsed !== "object" || parsed === null) return null;
      const plan = parsed as Partial<StoragePlan>;
      if (typeof plan.fingerprint !== "string" || !Array.isArray(plan.entries)) return null;
      return {
        id,
        root: typeof plan.root === "string" ? plan.root : this.paths.root,
        createdAtMs: typeof plan.createdAtMs === "number" ? plan.createdAtMs : 0,
        expiresAtMs: typeof plan.expiresAtMs === "number" ? plan.expiresAtMs : 0,
        fingerprint: plan.fingerprint,
        totalBytes: typeof plan.totalBytes === "number" ? plan.totalBytes : 0,
        entries: plan.entries.filter((entry): entry is StoragePlanEntry => isPlanEntry(entry)),
        excluded: Array.isArray(plan.excluded)
          ? plan.excluded.filter((p) => typeof p === "string")
          : [],
        ...(typeof plan.appliedAtMs === "number" ? { appliedAtMs: plan.appliedAtMs } : {}),
        ...(Array.isArray(plan.appliedPaths)
          ? { appliedPaths: plan.appliedPaths.filter((p) => typeof p === "string") }
          : {}),
      };
    } catch {
      return null;
    }
  }

  private readSettings(): StorageSettings {
    const raw = this.settingsRepo.get(STORAGE_SETTINGS_KEY);
    if (raw === null) return { ...DEFAULT_STORAGE_SETTINGS };
    try {
      const parsed: unknown = JSON.parse(raw);
      if (typeof parsed !== "object" || parsed === null) return { ...DEFAULT_STORAGE_SETTINGS };
      const value = parsed as Partial<StorageSettings>;
      const ttl = value.trashTtlDays;
      return {
        // Default off on anything unreadable: the mode is the switch a person turns on, and an
        // unparseable row means nobody has.
        enabled: value.enabled === true,
        trashTtlDays:
          typeof ttl === "number" &&
          Number.isInteger(ttl) &&
          ttl >= MIN_TRASH_TTL_DAYS &&
          ttl <= MAX_TRASH_TTL_DAYS
            ? ttl
            : DEFAULT_TRASH_TTL_DAYS,
        pins: Array.isArray(value.pins) ? value.pins.filter((p) => typeof p === "string") : [],
      };
    } catch {
      return { ...DEFAULT_STORAGE_SETTINGS };
    }
  }

  /** The mode is the whole gate: with it off, nothing here writes and nothing may be planned. */
  private assertModeOn(what: string): void {
    if (!this.readSettings().enabled) {
      throw new HttpError(
        409,
        "storage_mode_off",
        `Cleanup mode is off, so ${what} is not available. The ledger stays readable; turn the mode on in Settings → Storage.`,
      );
    }
  }

  private assertIdle(what: string): void {
    if (this.running !== null) {
      throw new HttpError(
        409,
        "storage_busy",
        `Another storage ${this.running} is running; try ${what} once it finishes.`,
      );
    }
  }

  /**
   * A pin must name something inside the root that exists now — the same containment rule a
   * move obeys. A pin for a path that is not there would silently do nothing, and a pin that
   * escaped the root would be a decision about something this machine does not own.
   */
  private assertPinnablePath(relativePath: string): void {
    if (relativePath === "" || relativePath.startsWith("/") || relativePath.includes("\\")) {
      throw new HttpError(
        400,
        "invalid_pin",
        `A pin is a path relative to the data root: ${relativePath}.`,
      );
    }
    if (relativePath.split("/").some((segment) => segment === "" || segment === "..")) {
      throw new HttpError(
        400,
        "invalid_pin",
        `A pin must not contain empty or parent segments: ${relativePath}.`,
      );
    }
    const target = path.resolve(this.paths.root, relativePath);
    if (!isInsideRoot(this.paths.root, target)) {
      throw new HttpError(400, "invalid_pin", `Outside the data root: ${relativePath}.`);
    }
  }

  /**
   * One JSON line per decision about data, appended to `<root>/logs/storage-gc.jsonl` and never
   * rewritten. Best effort: a log that cannot be written must not take a move down with it (the
   * move is the thing the person asked for, and the trash manifest records it too), but the
   * failure is not swallowed silently either — it is reported on stderr of the server process.
   */
  private async audit(record: Record<string, unknown> & { action: string }): Promise<void> {
    const line = `${JSON.stringify({ at: new Date().toISOString(), ...record })}\n`;
    try {
      await fs.mkdir(path.dirname(storageLogFile(this.paths.root)), { recursive: true });
      await fs.appendFile(storageLogFile(this.paths.root), line, "utf8");
    } catch (e) {
      process.stderr.write(`storage: could not write the audit log: ${reasonOf(e)}\n`);
    }
  }

  /**
   * The server's live state, in the shape core's `StorageLiveSet` asks for: every Session id
   * that still exists, the REAL path of each Workspace those Sessions point at (core compares
   * realpaths, and a Workspace can sit under a symlinked parent — a user's home on macOS
   * reaches it through `/var` → `/private/var`), and each Session's last activity in epoch ms.
   *
   * One row per Session is enough for all three, so this is two indexed queries per Project
   * and no filesystem work beyond resolving the Workspace paths.
   *
   * Which Projects exist is the database's answer too (`Projects.listAll`), the same enumeration
   * the scheduler and the organization runtime make — so a Session whose Project the index does
   * not know (a root copied onto a machine whose index was never rebuilt for it) is not in the
   * set. That gap closes on its own: bringing such a root into the index is exactly what the
   * boot-time adoption sweep does.
   */
  private async liveSet(): Promise<StorageLiveSet> {
    const sessionIds = new Set<string>();
    const sessionLastActiveMs = new Map<string, number>();
    const workspaces = new Set<string>();
    for (const project of this.projects.listAll()) {
      for (const row of this.sessions.listByProject(project.projectId)) {
        sessionIds.add(row.sessionId);
        // A stamp that cannot be parsed is left out rather than replaced with "now": a Session
        // with no known activity is then never judged idle, which is the conservative way
        // round for a report a person may act on.
        const lastActiveMs = Date.parse(row.lastActiveAt);
        if (!Number.isNaN(lastActiveMs)) sessionLastActiveMs.set(row.sessionId, lastActiveMs);
        if (row.workspace !== "") workspaces.add(row.workspace);
      }
    }
    return {
      sessionIds,
      workspacePaths: await realPathsOf(workspaces),
      sessionLastActiveMs,
    };
  }
}

/**
 * A candidate as the Web contract spells it. Core reports the newest mtime as epoch ms and 0
 * for "nothing could be stat'd"; the DTO asks for ISO or null, because a 0 turned into a date
 * would read as a file from 1970 — an ancient entry — rather than one of unknown age.
 */
function toCandidate(entry: LedgerEntry): StorageCandidate {
  return {
    path: entry.path,
    class: entry.class,
    bytes: entry.bytes,
    files: entry.files,
    lastModifiedAt: entry.newestMtimeMs === 0 ? null : new Date(entry.newestMtimeMs).toISOString(),
    referenced: entry.referenced,
    rules: entry.rules,
  };
}

/** A stored plan as the page and the CLI read it: the same bill, with ISO instants. */
function toPlanView(plan: StoragePlan, nowMs: number): StoragePlanView {
  const expired = nowMs > plan.expiresAtMs;
  return {
    id: plan.id,
    root: plan.root,
    createdAt: new Date(plan.createdAtMs).toISOString(),
    expiresAt: new Date(plan.expiresAtMs).toISOString(),
    fingerprint: plan.fingerprint,
    totalBytes: plan.totalBytes,
    entries: plan.entries.map((entry) => ({
      path: entry.path,
      class: entry.class,
      bytes: entry.bytes,
      files: entry.files,
      lastModifiedAt:
        entry.newestMtimeMs === 0 ? null : new Date(entry.newestMtimeMs).toISOString(),
      rules: entry.rules,
      fingerprint: entry.fingerprint,
      executable: isExecutableStorageClass(entry.class),
    })),
    excluded: plan.excluded,
    executableClasses: [...EXECUTABLE_STORAGE_CLASSES],
    appliedAt: plan.appliedAtMs === undefined ? null : new Date(plan.appliedAtMs).toISOString(),
    appliedPaths: plan.appliedPaths ?? [],
    usable: plan.appliedAtMs === undefined && !expired,
    expired,
  };
}

/** Whether a parsed JSON value is one plan entry, field for field, before it is trusted. */
function isPlanEntry(value: unknown): value is StoragePlanEntry {
  if (typeof value !== "object" || value === null) return false;
  const entry = value as Partial<StoragePlanEntry>;
  return (
    typeof entry.path === "string" &&
    typeof entry.class === "string" &&
    typeof entry.bytes === "number" &&
    typeof entry.files === "number" &&
    typeof entry.newestMtimeMs === "number" &&
    typeof entry.fingerprint === "string" &&
    Array.isArray(entry.rules)
  );
}

/** A path list for a refusal message, capped so a wild selection cannot flood the response. */
function nameList(paths: string[]): string {
  const shown = paths.slice(0, 10).join(", ");
  return paths.length > 10 ? `${shown} … (${paths.length} in all)` : shown;
}

/** `fs.access` as a boolean, for the "is something already there" questions. */
async function exists(target: string): Promise<boolean> {
  try {
    await fs.access(target);
    return true;
  } catch {
    return false;
  }
}

/** Names in a directory, or none when it is not there. */
async function readdirNames(dir: string): Promise<string[]> {
  try {
    return await fs.readdir(dir);
  } catch {
    return [];
  }
}

/**
 * Whether anything under `dir` is not a directory: a file, a link, anything that would be lost
 * by removing the tree. Empty directories are what a restore leaves behind, and a trash entry
 * holding only those holds nothing.
 */
async function hasAnyContent(dir: string): Promise<boolean> {
  for (const name of await readdirNames(dir)) {
    const full = path.join(dir, name);
    const st = await fs.lstat(full).catch(() => null);
    if (st === null) continue;
    if (!st.isDirectory()) return true;
    if (await hasAnyContent(full)) return true;
  }
  return false;
}

/** A directory's own modification time, which is the fallback stamp of a manifest-less entry. */
async function mtimeMs(target: string): Promise<number> {
  try {
    return (await fs.stat(target)).mtimeMs;
  } catch {
    return 0;
  }
}

/** A failure's own words, for a report a person reads (`no such file or directory`). */
function reasonOf(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

/**
 * The realpaths of a set of Workspace paths. A path that is gone still needs a stable form to
 * compare against, so it falls back to its resolved self — core's own rule for the directory
 * it is walking — which keeps both sides of the temporary-Workspace comparison agreeing
 * whether or not that Workspace still exists.
 */
async function realPathsOf(workspaces: ReadonlySet<string>): Promise<Set<string>> {
  const resolved = await Promise.all(
    [...workspaces].map(async (workspace) => {
      try {
        return await fs.realpath(workspace);
      } catch {
        return path.resolve(workspace);
      }
    }),
  );
  return new Set(resolved);
}