akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/ops/appInfo.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { type DatabaseMode, getEnv } from "../../base/baseEnv";
+
+export interface AppPublicInfo {
+  appName: string;
+  repoName: string;
+  environment: string;
+  operationMode: string;
+}
+
+export interface AppDetailInfo extends AppPublicInfo {
+  akanVersion: string | null;
+  buildId: string | null;
+  serverMode: string;
+  databaseMode: DatabaseMode | null;
+  solo: boolean;
+  startedAt: string;
+  replicaIdx: number | null;
+}
+
+export interface AppBuildInfo {
+  buildId: string | null;
+  akanVersion: string | null;
+  builtAt: string | null;
+}
+
+export interface AppProcessInfo {
+  serverMode: string;
+  solo: boolean;
+  replicaIdx: number | null;
+}
+
+export class AppInfo {
+  static readonly publicPath = "/_akan/app/info";
+  static readonly buildFileName = "akan.build.json";
+  static readonly startedAt = new Date();
+  static #build: AppBuildInfo | null = null;
+
+  static public(): AppPublicInfo {
+    const { appName, repoName, environment, operationMode } = getEnv();
+    return { appName, repoName, environment, operationMode };
+  }
+
+  static detail(proc: AppProcessInfo): AppDetailInfo {
+    const { buildId, akanVersion } = AppInfo.build();
+    return {
+      ...AppInfo.public(),
+      akanVersion,
+      buildId,
+      serverMode: proc.serverMode,
+      databaseMode: getEnv().databaseMode ?? null,
+      solo: proc.solo,
+      startedAt: AppInfo.startedAt.toISOString(),
+      replicaIdx: proc.replicaIdx,
+    };
+  }
+
+  static build(): AppBuildInfo {
+    AppInfo.#build ??= AppInfo.#readBuildFile();
+    const envBuildId = process.env.AKAN_BUILD_ID?.trim();
+    return {
+      ...AppInfo.#build,
+      buildId: envBuildId || AppInfo.#build.buildId,
+      akanVersion: AppInfo.#build.akanVersion ?? AppInfo.#installedAkanVersion(),
+    };
+  }
+
+  static handlePublic(): Response {
+    return Response.json(AppInfo.public(), { headers: { "cache-control": "no-store" } });
+  }
+
+  static #readBuildFile(): AppBuildInfo {
+    try {
+      const raw = JSON.parse(readFileSync(path.join(path.dirname(Bun.main), AppInfo.buildFileName), "utf8")) as
+        | Partial<AppBuildInfo>
+        | undefined;
+      return { buildId: raw?.buildId ?? null, akanVersion: raw?.akanVersion ?? null, builtAt: raw?.builtAt ?? null };
+    } catch {
+      return { buildId: null, akanVersion: null, builtAt: null };
+    }
+  }
+
+  static #installedAkanVersion(): string | null {
+    try {
+      const file = Bun.resolveSync("akanjs/package.json", path.dirname(Bun.main));
+      return (JSON.parse(readFileSync(file, "utf8")) as { version?: string }).version ?? null;
+    } catch {
+      return null;
+    }
+  }
+}

package/server/ops/opsCommand.ts

@@ -0,0 +1,116 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { SnapshotRestore } from "./snapshotRestore";
+import type { SnapshotSources } from "./snapshotTypes";
+import { SqliteFiles } from "./sqliteFiles";
+import { SqliteSnapshot } from "./sqliteSnapshot";
+
+export class OpsCommand {
+  static readonly usage = [
+    "Usage:",
+    "  bun main.js ops snapshot [--id <id>] [--out <dir>] [--include-solid] [--db <file>] [--solid-db <file>] [--json]",
+    "  bun main.js ops restore <manifest.json> [--identity <file>] [--db <file>] [--solid-db <file>] [--force]",
+  ].join("\n");
+
+  static async run(argv: string[]): Promise<number> {
+    const [command, ...rest] = argv;
+    try {
+      if (command === "snapshot") return await OpsCommand.#snapshot(rest);
+      if (command === "restore") return await OpsCommand.#restore(rest);
+      process.stderr.write(`${OpsCommand.usage}\n`);
+      return 2;
+    } catch (error) {
+      process.stderr.write(`ops ${command}: ${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+  }
+
+  static async #snapshot(argv: string[]) {
+    const { values } = parseArgs({
+      args: argv,
+      options: {
+        id: { type: "string" },
+        out: { type: "string" },
+        db: { type: "string" },
+        "solid-db": { type: "string" },
+        "include-solid": { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+      },
+    });
+    const sources = OpsCommand.#sources(values.db, values["solid-db"]);
+    const capture = await SqliteSnapshot.capture({
+      id: values.id ?? `snap-${new Date().toISOString().replace(/[:.]/g, "-")}`,
+      dir: path.resolve(values.out ?? SqliteFiles.snapshotDir(sources)),
+      sources,
+      includeSolid: values["include-solid"],
+      encryptor: await OpsCommand.#encryptor(),
+    });
+    process.stdout.write(values.json ? `${JSON.stringify(capture)}\n` : `${JSON.stringify(capture, null, 2)}\n`);
+    return 0;
+  }
+
+  static async #restore(argv: string[]) {
+    const { values, positionals } = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        identity: { type: "string" },
+        db: { type: "string" },
+        "solid-db": { type: "string" },
+        force: { type: "boolean", default: false },
+      },
+    });
+    const manifestPath = positionals[0];
+    if (!manifestPath) throw new Error(`a manifest path is required\n${OpsCommand.usage}`);
+    const running = values.force ? null : await OpsCommand.#runningApp();
+    if (running)
+      throw new Error(
+        `${running} is answering on port ${process.env.PORT ?? "8282"}; stop it first (or pass --force if that is another app)`,
+      );
+    const { restored } = await SnapshotRestore.run({
+      manifestPath: path.resolve(manifestPath),
+      sources: OpsCommand.#sources(values.db, values["solid-db"]),
+      decryptor: await OpsCommand.#decryptor(values.identity),
+    });
+    for (const { role, target, preservedAs } of restored)
+      process.stdout.write(`restored ${role} → ${target}${preservedAs ? ` (previous kept at ${preservedAs})` : ""}\n`);
+    return 0;
+  }
+
+  static #sources(db?: string, solidDb?: string): SnapshotSources {
+    const fromEnv = SqliteFiles.fromEnv();
+    return {
+      main: db ? path.resolve(db) : fromEnv.main,
+      solid: solidDb ? path.resolve(solidDb) : fromEnv.solid,
+    };
+  }
+
+  static async #runningApp() {
+    const base = `http://127.0.0.1:${process.env.PORT ?? "8282"}`;
+    try {
+      const health = await fetch(`${base}/_akan/app/health`, { signal: AbortSignal.timeout(1_000) });
+      if (!health.ok) return null;
+      const info = (await fetch(`${base}/_akan/app/info`, { signal: AbortSignal.timeout(1_000) })
+        .then((res) => (res.ok ? res.json() : null))
+        .catch(() => null)) as { appName?: string; environment?: string } | null;
+      return info?.appName ? `${info.appName}/${info.environment ?? "?"}` : "An app";
+    } catch {
+      return null;
+    }
+  }
+
+  static async #encryptor() {
+    if (!process.env.AKAN_BACKUP_RECIPIENT?.trim()) return null;
+    const { AgeEncryption } = await import("./ageEncryption");
+    return await AgeEncryption.fromEnv();
+  }
+
+  static async #decryptor(identityFile = process.env.AKAN_BACKUP_IDENTITY_FILE) {
+    if (!identityFile) return null;
+    const { AgeEncryption } = await import("./ageEncryption");
+    const identities = AgeEncryption.identitiesIn(await readFile(path.resolve(identityFile), "utf8"));
+    if (!identities.length) throw new Error(`${identityFile} holds no AGE-SECRET-KEY-1 identity`);
+    return await AgeEncryption.decryptor(identities);
+  }
+}

package/server/ops/opsRoute.ts

@@ -0,0 +1,151 @@
+import { Logger } from "akanjs/common";
+import { getEnv } from "../../base/baseEnv";
+import type { AppDetailInfo } from "./appInfo";
+import { OpsTokenVerifier } from "./opsToken";
+import { type SnapshotJobRequest, SnapshotJobs } from "./snapshotJobs";
+import type { SnapshotSources } from "./snapshotTypes";
+import { SqliteFiles } from "./sqliteFiles";
+import { type SnapshotCapture, SqliteSnapshot } from "./sqliteSnapshot";
+
+export interface OpsRouteOptions {
+  verifier: OpsTokenVerifier;
+  detail: () => AppDetailInfo;
+  jobs: SnapshotJobs;
+  rateLimitPerMinute?: number;
+}
+
+export interface OpsRouteEnvOptions {
+  detail: () => AppDetailInfo;
+  sources?: () => SnapshotSources;
+}
+
+export class OpsRoute {
+  static readonly prefix = "/_akan/ops/";
+
+  readonly #logger = new Logger("OpsRoute");
+  readonly #verifier: OpsTokenVerifier;
+  readonly #detail: () => AppDetailInfo;
+  readonly #jobs: SnapshotJobs;
+  readonly #rateLimit: number;
+  #window: number[] = [];
+
+  constructor({ verifier, detail, jobs, rateLimitPerMinute = 30 }: OpsRouteOptions) {
+    this.#verifier = verifier;
+    this.#detail = detail;
+    this.#jobs = jobs;
+    this.#rateLimit = rateLimitPerMinute;
+  }
+
+  static fromEnv({ detail, sources = SqliteFiles.fromEnv }: OpsRouteEnvOptions): OpsRoute | null {
+    const publicKey = process.env.AKAN_OPS_PUBLIC_KEY?.trim();
+    if (!publicKey) return null;
+    const { appName, environment } = getEnv();
+    const logger = new Logger("OpsRoute");
+    let verifier: OpsTokenVerifier;
+    try {
+      verifier = new OpsTokenVerifier(
+        OpsTokenVerifier.parsePublicKey(publicKey),
+        OpsTokenVerifier.audienceOf(appName, environment),
+      );
+    } catch (error) {
+      
+      logger.error(`Ops channel disabled: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+    const snapshotDir = SqliteFiles.snapshotDir(sources());
+    const jobs = new SnapshotJobs({
+      snapshotDir,
+      capture: (request) => OpsRoute.captureInChild(request, sources(), snapshotDir),
+    });
+    logger.info(`Ops channel enabled for audience ${verifier.audience}`);
+    return new OpsRoute({ verifier, detail, jobs });
+  }
+
+  static async captureInChild(request: SnapshotJobRequest, sources: SnapshotSources, dir: string) {
+    const args = ["ops", "snapshot", "--id", request.id, "--out", dir, "--db", sources.main, "--json"];
+    if (sources.solid) args.push("--solid-db", sources.solid);
+    if (request.includeSolid) args.push("--include-solid");
+    const proc = Bun.spawn([process.execPath, Bun.main, ...args], {
+      env: process.env,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    const lastLine = stdout.trim().split("\n").at(-1) ?? "";
+    if (code !== 0) throw new Error(stderr.trim().split("\n").at(-1) || `snapshot process exited with ${code}`);
+    return JSON.parse(lastLine) as SnapshotCapture;
+  }
+
+  matches(pathname: string) {
+    return pathname.startsWith(OpsRoute.prefix);
+  }
+
+  async handle(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    if (!this.#admit()) return OpsRoute.#json({ error: "rate limited" }, 429, { "retry-after": "60" });
+    const verdict = this.#verifier.verifyRequest(req);
+    if (!verdict.ok) {
+      this.#logger.warn(`Refused ops call to ${url.pathname}: ${verdict.reason}`);
+      return OpsRoute.#json({ error: "unauthorized" }, 401, { "www-authenticate": "Bearer" });
+    }
+    const route = url.pathname.slice(OpsRoute.prefix.length);
+    if (route === "info" && req.method === "GET") return OpsRoute.#json(this.#detail(), 200);
+    if (route === "snapshot" && req.method === "POST") return await this.#startSnapshot(req);
+    const jobMatch = /^snapshot\/([^/]+)$/.exec(route);
+    if (jobMatch?.[1] && req.method === "GET") {
+      const job = this.#jobs.get(decodeURIComponent(jobMatch[1]));
+      return job ? OpsRoute.#json(job, 200) : OpsRoute.#json({ error: "unknown snapshot" }, 404);
+    }
+    return OpsRoute.#json({ error: "not found" }, 404);
+  }
+
+  async #startSnapshot(req: Request) {
+    const body = (await req.json().catch(() => null)) as {
+      id?: unknown;
+      includeSolid?: unknown;
+      uploadUrls?: { main?: unknown; solid?: unknown; manifest?: unknown };
+    } | null;
+    const id = typeof body?.id === "string" ? body.id : "";
+    if (!SqliteSnapshot.idPattern.test(id))
+      return OpsRoute.#json({ error: `id must match ${SqliteSnapshot.idPattern.source}` }, 400);
+    const includeSolid = body?.includeSolid === true;
+    const main = OpsRoute.#uploadUrl(body?.uploadUrls?.main);
+    const manifest = OpsRoute.#uploadUrl(body?.uploadUrls?.manifest);
+    const solid = body?.uploadUrls?.solid === undefined ? undefined : OpsRoute.#uploadUrl(body.uploadUrls.solid);
+    if (!main || !manifest || solid === null)
+      return OpsRoute.#json({ error: "uploadUrls.main and uploadUrls.manifest must be https URLs" }, 400);
+    if (includeSolid && !solid) return OpsRoute.#json({ error: "includeSolid needs uploadUrls.solid" }, 400);
+    const started = this.#jobs.start({ id, includeSolid, uploadUrls: { main, manifest, ...(solid ? { solid } : {}) } });
+    if (started === "exists") return OpsRoute.#json({ error: "snapshot id already used" }, 409);
+    if (started === "busy") return OpsRoute.#json({ error: "another snapshot is running" }, 409);
+    return OpsRoute.#json(started, 202);
+  }
+
+  static #uploadUrl(value: unknown): string | null {
+    if (typeof value !== "string") return null;
+    try {
+      const url = new URL(value);
+      if (url.protocol === "https:") return url.toString();
+      if (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)) return url.toString();
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  #admit() {
+    const now = Date.now();
+    this.#window = this.#window.filter((at) => now - at < 60_000);
+    if (this.#window.length >= this.#rateLimit) return false;
+    this.#window.push(now);
+    return true;
+  }
+
+  static #json(value: unknown, status: number, headers: Record<string, string> = {}) {
+    return Response.json(value, { status, headers: { "cache-control": "no-store", ...headers } });
+  }
+}

package/server/ops/opsToken.ts

@@ -0,0 +1,93 @@
+import { createPublicKey, type KeyObject, verify } from "node:crypto";
+
+export interface OpsTokenClaims {
+  aud: string;
+  exp: number;
+  iat: number;
+  jti: string;
+}
+
+export type OpsTokenVerdict = { ok: true; claims: OpsTokenClaims } | { ok: false; reason: string };
+
+export class OpsTokenVerifier {
+  static readonly maxLifetimeSec = 300;
+  static readonly clockSkewSec = 30;
+  static readonly maxRememberedJti = 10_000;
+
+  readonly audience: string;
+  readonly #key: KeyObject;
+  readonly #seen = new Map<string, number>();
+
+  constructor(key: KeyObject, audience: string) {
+    if (key.asymmetricKeyType !== "ed25519") throw new Error("AKAN_OPS_PUBLIC_KEY must be an Ed25519 public key");
+    this.#key = key;
+    this.audience = audience;
+  }
+
+  static audienceOf(appName: string, environment: string, instance = process.env.AKAN_OPS_INSTANCE?.trim()) {
+    return instance ? `${appName}/${environment}/${instance}` : `${appName}/${environment}`;
+  }
+
+  static parsePublicKey(value: string): KeyObject {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("{")) return createPublicKey({ key: JSON.parse(trimmed) as JsonWebKey, format: "jwk" });
+    const pem = trimmed.includes("-----BEGIN") ? trimmed.replace(/\\n/g, "\n") : null;
+    if (pem) return createPublicKey(pem);
+    const raw = Buffer.from(trimmed, "base64url");
+    if (raw.length === 32)
+      return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") }, format: "jwk" });
+    if (raw.length === 44) return createPublicKey({ key: raw, format: "der", type: "spki" });
+    throw new Error("AKAN_OPS_PUBLIC_KEY must be a PEM, a JWK, base64 SPKI DER, or a raw 32-byte base64url key");
+  }
+
+  verifyRequest(req: Request, nowSec = Math.floor(Date.now() / 1000)): OpsTokenVerdict {
+    const match = /^Bearer\s+(\S+)$/i.exec(req.headers.get("authorization") ?? "");
+    if (!match?.[1]) return { ok: false, reason: "missing bearer token" };
+    return this.verify(match[1], nowSec);
+  }
+
+  verify(token: string, nowSec = Math.floor(Date.now() / 1000)): OpsTokenVerdict {
+    const parts = token.split(".");
+    if (parts.length !== 3) return { ok: false, reason: "malformed token" };
+    const [headerPart = "", payloadPart = "", signaturePart = ""] = parts;
+    const header = OpsTokenVerifier.#decodeJson(headerPart);
+    if (header?.alg !== "EdDSA") return { ok: false, reason: "alg must be EdDSA" };
+    const signed = verify(
+      null,
+      Buffer.from(`${headerPart}.${payloadPart}`),
+      this.#key,
+      Buffer.from(signaturePart, "base64url"),
+    );
+    if (!signed) return { ok: false, reason: "bad signature" };
+    const claims = OpsTokenVerifier.#decodeJson(payloadPart);
+    if (!claims) return { ok: false, reason: "malformed claims" };
+    const { aud, exp, iat, jti } = claims;
+    if (typeof exp !== "number" || typeof iat !== "number" || typeof jti !== "string" || !jti)
+      return { ok: false, reason: "exp, iat and jti are required" };
+    const audiences = Array.isArray(aud) ? aud : [aud];
+    if (!audiences.includes(this.audience)) return { ok: false, reason: "audience mismatch" };
+    if (exp <= nowSec) return { ok: false, reason: "expired" };
+    if (iat > nowSec + OpsTokenVerifier.clockSkewSec) return { ok: false, reason: "issued in the future" };
+    if (exp - iat > OpsTokenVerifier.maxLifetimeSec) return { ok: false, reason: "lifetime exceeds 300s" };
+    if (!this.#remember(jti, exp, nowSec)) return { ok: false, reason: "replayed jti" };
+    return { ok: true, claims: { aud: this.audience, exp, iat, jti } };
+  }
+
+  #remember(jti: string, exp: number, nowSec: number) {
+    for (const [seen, seenExp] of this.#seen) if (seenExp <= nowSec) this.#seen.delete(seen);
+    if (this.#seen.has(jti)) return false;
+    
+    if (this.#seen.size >= OpsTokenVerifier.maxRememberedJti) return false;
+    this.#seen.set(jti, exp);
+    return true;
+  }
+
+  static #decodeJson(part: string): Record<string, unknown> | null {
+    try {
+      const value = JSON.parse(Buffer.from(part, "base64url").toString("utf8")) as unknown;
+      return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+    } catch {
+      return null;
+    }
+  }
+}

package/server/ops/snapshotJobs.ts

@@ -0,0 +1,133 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { SnapshotJobState, SnapshotUploadUrls } from "./snapshotTypes";
+import type { SnapshotCapture } from "./sqliteSnapshot";
+
+export interface SnapshotJobRequest {
+  id: string;
+  includeSolid: boolean;
+  uploadUrls: SnapshotUploadUrls;
+}
+
+export interface SnapshotJobsOptions {
+  capture: (request: SnapshotJobRequest) => Promise<SnapshotCapture>;
+  snapshotDir: string;
+  keep?: number;
+  fetcher?: typeof fetch;
+  uploadAttempts?: number;
+  retryDelayMs?: number;
+}
+
+export class SnapshotJobs {
+  static readonly maxRemembered = 20;
+  static readonly uploadTimeoutMs = 30 * 60_000;
+
+  readonly #logger = new Logger("SnapshotJobs");
+  readonly #jobs = new Map<string, SnapshotJobState>();
+  readonly #options: Required<Omit<SnapshotJobsOptions, "capture">> & Pick<SnapshotJobsOptions, "capture">;
+  #running: Promise<void> | null = null;
+
+  constructor({
+    keep = Number(process.env.AKAN_OPS_SNAPSHOT_KEEP ?? 2),
+    fetcher = fetch,
+    uploadAttempts = 3,
+    retryDelayMs = 2_000,
+    ...options
+  }: SnapshotJobsOptions) {
+    this.#options = { ...options, keep: Math.max(1, keep || 1), fetcher, uploadAttempts, retryDelayMs };
+  }
+
+  get(id: string) {
+    return this.#jobs.get(id) ?? null;
+  }
+
+  start(request: SnapshotJobRequest): SnapshotJobState | "busy" | "exists" {
+    if (this.#jobs.has(request.id)) return "exists";
+    if (this.#running) return "busy";
+    const job: SnapshotJobState = { id: request.id, status: "running", startedAt: new Date().toISOString() };
+    this.#remember(job);
+    this.#running = this.#run(job, request).finally(() => {
+      this.#running = null;
+    });
+    return { ...job };
+  }
+
+  async idle() {
+    await this.#running;
+  }
+
+  async #run(job: SnapshotJobState, request: SnapshotJobRequest) {
+    try {
+      const capture = await this.#options.capture(request);
+      job.manifest = capture.manifest;
+      job.status = "uploading";
+      for (const file of capture.manifest.files) {
+        const url = file.role === "main" ? request.uploadUrls.main : request.uploadUrls.solid;
+        const filePath = capture.paths[file.role];
+        if (!url || !filePath) throw new Error(`No upload URL for the ${file.role} file`);
+        await this.#put(url, Bun.file(filePath), "application/octet-stream", file.name);
+      }
+      
+      await this.#put(request.uploadUrls.manifest, Bun.file(capture.manifestPath), "application/json", "manifest");
+      job.status = "done";
+      await this.#prune();
+    } catch (error) {
+      job.status = "failed";
+      job.error = error instanceof Error ? error.message : String(error);
+      this.#logger.error(`Snapshot ${job.id} failed: ${job.error}`);
+    } finally {
+      job.finishedAt = new Date().toISOString();
+    }
+  }
+
+  async #put(url: string, body: Blob, contentType: string, label: string) {
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= this.#options.uploadAttempts; attempt++) {
+      try {
+        const res = await this.#options.fetcher(url, {
+          method: "PUT",
+          body,
+          headers: { "content-type": contentType, "content-length": String(body.size) },
+          signal: AbortSignal.timeout(SnapshotJobs.uploadTimeoutMs),
+        });
+        if (res.ok) return;
+        lastError = new Error(`upload of ${label} answered ${res.status}`);
+        
+        if (res.status < 500) break;
+      } catch (error) {
+        lastError = error;
+      }
+      if (attempt < this.#options.uploadAttempts)
+        await new Promise((resolve) => setTimeout(resolve, this.#options.retryDelayMs * attempt));
+    }
+    throw lastError instanceof Error ? lastError : new Error(`upload of ${label} failed`);
+  }
+
+  #remember(job: SnapshotJobState) {
+    this.#jobs.set(job.id, job);
+    while (this.#jobs.size > SnapshotJobs.maxRemembered) {
+      const oldest = this.#jobs.keys().next().value;
+      if (oldest === undefined) break;
+      this.#jobs.delete(oldest);
+    }
+  }
+
+  async #prune() {
+    const dir = this.#options.snapshotDir;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const dated = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) => {
+          const full = path.join(dir, entry.name);
+          const manifest = await stat(path.join(full, "manifest.json")).catch(() => null);
+          return manifest ? { full, mtime: manifest.mtimeMs } : null;
+        }),
+    );
+    const snapshots = dated
+      .filter((entry): entry is { full: string; mtime: number } => !!entry)
+      .sort((a, b) => b.mtime - a.mtime);
+    for (const stale of snapshots.slice(this.#options.keep)) await rm(stale.full, { recursive: true, force: true });
+  }
+}