@milaboratories/pl-middle-layer 1.67.6 → 1.68.0

package/dist/middle_layer/tree_snapshot_store.js

@@ -0,0 +1,280 @@
+import { ML_BUILD_STAMP } from "./build_stamp.js";
+import path from "node:path";
+import { createPathAtomically, ensureDirExists } from "@milaboratories/ts-helpers";
+import fsp from "node:fs/promises";
+import { parseSignedResourceId } from "@milaboratories/pl-client";
+import { PERSISTED_TREE_SCHEMA_VERSION, decodePersistedTree, encodePersistedTree, readPersistedTreeHeader } from "@milaboratories/pl-tree";
+import { createHash } from "node:crypto";
+//#region src/middle_layer/tree_snapshot_store.ts
+function initialStat() {
+	return {
+		reads: 0,
+		hits: 0,
+		restores: 0,
+		misses: {
+			absent: 0,
+			unreadable: 0,
+			"session-rotated": 0,
+			"not-a-snapshot": 0,
+			"unknown-schema": 0,
+			truncated: 0,
+			checksum: 0,
+			malformed: 0
+		},
+		writes: 0,
+		writeFailures: 0,
+		bytesWritten: 0,
+		discarded: 0,
+		evicted: 0,
+		evictedForSize: 0,
+		bytesEvicted: 0,
+		millisReading: 0,
+		millisWriting: 0
+	};
+}
+const FILE_PREFIX = "tree.";
+const FILE_SUFFIX = ".plts";
+/** Keeps a filename to characters every filesystem we target accepts. */
+function safe(part) {
+	return part.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/** Names this class writes: a finished snapshot, or the staging file of a write killed before
+*  its rename. The directory is caller-supplied and only defaults to one of ours, so nothing
+*  failing this is ever deleted, by the purge or by the startup eviction. */
+function isOurFile(name) {
+	if (!name.startsWith(FILE_PREFIX)) return false;
+	return name.endsWith(FILE_SUFFIX) || name.includes(`${FILE_SUFFIX}.tmp.`);
+}
+/**
+* Snapshots of project tree mirrors on the local filesystem.
+*
+* A snapshot is addressed by backend instance, authenticated user, root resource, build stamp
+* and snapshot schema version. Everything except the root goes into the *scope*, which is
+* fixed for the lifetime of a client; the root distinguishes one project from another, so
+* there is one file per project per user per backend, rewritten in place.
+*
+* The session is deliberately not part of the key. It is witnessed inside the file and
+* compared on read: a snapshot from an ended session is a miss, but the file is kept, because
+* its bodies remain valid indefinitely and only its signatures have died. Deleting it would
+* destroy the evidence a future signature refresh would repair.
+*/
+var TreeSnapshotStore = class TreeSnapshotStore {
+	ops;
+	scope;
+	stat = initialStat();
+	constructor(ops, scope) {
+		this.ops = ops;
+		this.scope = scope;
+	}
+	/**
+	* Builds a store for the given client, or returns undefined when nothing should be
+	* persisted for it.
+	*
+	* Returns undefined for an impersonated client: reading and writing under `asUser` would
+	* leave another user's mirror at rest under the admin's identity, usable only if the admin
+	* returned to that exact root. One condition removes both the hygiene question and the
+	* orphan one.
+	*/
+	static create(pl, ops) {
+		if (!ops.enabled) {
+			ops.logger.info("tree snapshots are disabled by configuration");
+			return;
+		}
+		if (pl.conf.asUser !== void 0) {
+			ops.logger.info("tree snapshots are disabled while the client is opened as another user");
+			return;
+		}
+		const identity = createHash("sha256").update([
+			pl.conf.hostAndPort,
+			pl.serverInfo.instanceId ?? "",
+			pl.authUser ?? ""
+		].join("\0")).digest("hex").slice(0, 16);
+		return new TreeSnapshotStore(ops, `${PERSISTED_TREE_SCHEMA_VERSION}.${safe(ML_BUILD_STAMP)}.${identity}`);
+	}
+	/**
+	* Removes this class's files from the snapshot directory. Run when snapshots are switched
+	* off, so a user who turns the kill switch off because the disk is full or unwritable
+	* actually gets the space back, rather than leaving up to the size ceiling stranded there
+	* indefinitely.
+	*
+	* Deliberately keyed on the setting rather than on "there is no store": a store is also
+	* absent for an impersonated client, and deleting there would destroy the operator's own
+	* snapshots from their ordinary sessions. Never throws.
+	*/
+	static async purge(dir, logger) {
+		try {
+			for (const name of await fsp.readdir(dir)) {
+				if (!isOurFile(name)) continue;
+				await fsp.rm(path.join(dir, name), { force: true }).catch(() => {});
+			}
+			await fsp.rmdir(dir).catch(() => {});
+		} catch (e) {
+			if (e?.code === "ENOENT") return;
+			logger.warn(`failed to clear the tree snapshot directory: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	getStats() {
+		return this.stat;
+	}
+	fileFor(root) {
+		const { globalId } = parseSignedResourceId(root);
+		return path.join(this.ops.dir, `${FILE_PREFIX}${this.scope}.${globalId}${FILE_SUFFIX}`);
+	}
+	/**
+	* Reads the snapshot for a project root, or reports why there is nothing to restore.
+	*
+	* `root` is the id as resolved in the current session. Its signature is what the stored
+	* witness is compared against, so a rotated session is detected without inflating the
+	* payload, and no separate session lookup is needed anywhere.
+	*/
+	async read(root) {
+		const started = Date.now();
+		this.stat.reads++;
+		try {
+			const file = this.fileFor(root);
+			let bytes;
+			try {
+				bytes = await fsp.readFile(file);
+			} catch (e) {
+				const absent = e?.code === "ENOENT";
+				if (!absent) this.ops.logger.warn(`tree snapshot exists but could not be read: ${e instanceof Error ? e.message : String(e)}`);
+				return this.miss(absent ? "absent" : "unreadable");
+			}
+			const header = readPersistedTreeHeader(bytes);
+			if (!header.ok) return this.miss(header.reason);
+			const { signature } = parseSignedResourceId(root);
+			if (!Buffer.from(header.value.witness).equals(Buffer.from(signature))) return this.miss("session-rotated");
+			const decoded = await decodePersistedTree(bytes);
+			if (!decoded.ok) return this.miss(decoded.reason);
+			const now = /* @__PURE__ */ new Date();
+			await fsp.utimes(file, now, now).catch(() => {});
+			this.stat.hits++;
+			return {
+				ok: true,
+				tree: decoded.value
+			};
+		} finally {
+			this.stat.millisReading += Date.now() - started;
+		}
+	}
+	miss(miss) {
+		this.stat.misses[miss]++;
+		return {
+			ok: false,
+			miss
+		};
+	}
+	/** Recorded by the caller once it knows the tree accepted the snapshot. The store cannot
+	*  tell on its own: it hands over bytes, and whether they become a tree is the tree's call. */
+	noteRestored() {
+		this.stat.restores++;
+	}
+	/**
+	* Writes a snapshot, replacing any previous one for the same project.
+	*
+	* Never throws and never rejects: a write is an optimisation, and a full disk or a
+	* permissions problem must not fail the operation that triggered it. Staged and renamed
+	* into place, so a process killed mid-write leaves the previous snapshot rather than a torn
+	* one.
+	*/
+	async write(root, snapshot, ops = {}) {
+		const started = Date.now();
+		try {
+			const bytes = await encodePersistedTree(snapshot, { compress: ops.compress });
+			await ensureDirExists(this.ops.dir);
+			const file = this.fileFor(root);
+			await createPathAtomically(this.ops.logger, file, async (tempPath) => {
+				await fsp.writeFile(tempPath, bytes, { flag: "wx" });
+			});
+			this.stat.writes++;
+			this.stat.bytesWritten += bytes.length;
+			return true;
+		} catch (e) {
+			this.stat.writeFailures++;
+			this.ops.logger.warn(`failed to write tree snapshot: ${e instanceof Error ? e.message : String(e)}`);
+			return false;
+		} finally {
+			this.stat.millisWriting += Date.now() - started;
+		}
+	}
+	/** Deletes the snapshot for a project. Used by the fail-safe, when a restored tree turns
+	*  out not to match what the backend will serve. Never throws. */
+	async discard(root) {
+		try {
+			await fsp.rm(this.fileFor(root), { force: true });
+			this.stat.discarded++;
+		} catch (e) {
+			this.ops.logger.warn(`failed to discard tree snapshot: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	/**
+	* Startup housekeeping. Drops every snapshot outside the current scope (another build,
+	* backend, user or schema version), then trims what is left to the size ceiling, least
+	* recently written first.
+	*
+	* Modification time stands in for recency of use: an open project is rewritten
+	* periodically, so the file's age tracks how recently the project was worked on. Read times
+	* would be a truer signal but atime is unreliable across platforms and mount options.
+	*
+	* Runs at startup only, so the ceiling bounds what a session starts with rather than capping
+	* it throughout: a long session opening many projects can exceed it until the next launch.
+	*
+	* Never throws: an unusable cache directory should cost the cache, not the startup.
+	*/
+	async evict() {
+		try {
+			await ensureDirExists(this.ops.dir);
+			const names = await fsp.readdir(this.ops.dir);
+			const current = [];
+			for (const name of names) {
+				const file = path.join(this.ops.dir, name);
+				const inScope = name.startsWith(`${FILE_PREFIX}${this.scope}.`) && name.endsWith(FILE_SUFFIX);
+				if (!inScope && !isOurFile(name)) continue;
+				let size = 0;
+				let mtimeMs = 0;
+				try {
+					const stat = await fsp.stat(file);
+					if (!stat.isFile()) continue;
+					size = stat.size;
+					mtimeMs = stat.mtimeMs;
+				} catch {
+					continue;
+				}
+				if (inScope) {
+					current.push({
+						file,
+						size,
+						mtimeMs
+					});
+					continue;
+				}
+				await this.remove(file, size, false);
+			}
+			const ceiling = this.ops.maxSizeBytes;
+			let total = current.reduce((sum, e) => sum + e.size, 0);
+			if (total <= ceiling) return;
+			current.sort((a, b) => a.mtimeMs - b.mtimeMs);
+			for (const entry of current) {
+				if (total <= ceiling) break;
+				if (await this.remove(entry.file, entry.size, true)) total -= entry.size;
+			}
+		} catch (e) {
+			this.ops.logger.warn(`tree snapshot eviction failed: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	async remove(file, size, forSize) {
+		try {
+			await fsp.rm(file, { force: true });
+			this.stat.evicted++;
+			this.stat.bytesEvicted += size;
+			if (forSize) this.stat.evictedForSize++;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+export { TreeSnapshotStore };
+
+//# sourceMappingURL=tree_snapshot_store.js.map

package/dist/middle_layer/tree_snapshot_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_snapshot_store.js","names":[],"sources":["../../src/middle_layer/tree_snapshot_store.ts"],"sourcesContent":["import type { PersistedTree, PersistedTreeReadFailure } from \"@milaboratories/pl-tree\";\nimport {\n  decodePersistedTree,\n  encodePersistedTree,\n  PERSISTED_TREE_SCHEMA_VERSION,\n  readPersistedTreeHeader,\n} from \"@milaboratories/pl-tree\";\nimport type { PlClient, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { parseSignedResourceId } from \"@milaboratories/pl-client\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { createPathAtomically, ensureDirExists } from \"@milaboratories/ts-helpers\";\nimport { createHash } from \"node:crypto\";\nimport fsp from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { ML_BUILD_STAMP } from \"./build_stamp\";\n\n/** Why a read did not produce a tree to restore from. Counted rather than inferred, because\n *  \"no snapshot\" and \"a snapshot we refused\" are very different things when a warm reopen\n *  fails to be warm and someone has to work out why. */\nexport type TreeSnapshotMiss =\n  /** No file for this key: a first open, or the key moved (new build, new backend, new user). */\n  | \"absent\"\n  /** A file is there but could not be opened at all: permissions, a bad mount, an I/O error.\n   *  Distinct from `absent` because a first open and a broken cache directory need different\n   *  answers from whoever reads the counters. */\n  | \"unreadable\"\n  /** File exists, but its signatures belong to a session that has ended. Kept, not deleted. */\n  | \"session-rotated\"\n  /** File exists and could not be read. Carries the codec's reason. */\n  | PersistedTreeReadFailure;\n\nexport type TreeSnapshotStat = {\n  reads: number;\n  /** Snapshots read successfully. A hit is not yet a warm open: the tree can still refuse to\n   *  apply it, which is what {@link restores} counts. */\n  hits: number;\n  /** Snapshots actually applied as a tree's initial state. This is the number that says a\n   *  reopen was warm. */\n  restores: number;\n  /** Miss counts by reason. */\n  misses: Record<TreeSnapshotMiss, number>;\n  writes: number;\n  writeFailures: number;\n  bytesWritten: number;\n  /** Snapshots deleted by the fail-safe after a restored tree failed its first refresh. */\n  discarded: number;\n  /** Files removed at startup, and how many of those were dropped for being over the ceiling\n   *  rather than for belonging to another build, backend or user. */\n  evicted: number;\n  evictedForSize: number;\n  bytesEvicted: number;\n  millisReading: number;\n  millisWriting: number;\n};\n\nfunction initialStat(): TreeSnapshotStat {\n  return {\n    reads: 0,\n    hits: 0,\n    restores: 0,\n    misses: {\n      absent: 0,\n      unreadable: 0,\n      \"session-rotated\": 0,\n      \"not-a-snapshot\": 0,\n      \"unknown-schema\": 0,\n      truncated: 0,\n      checksum: 0,\n      malformed: 0,\n    },\n    writes: 0,\n    writeFailures: 0,\n    bytesWritten: 0,\n    discarded: 0,\n    evicted: 0,\n    evictedForSize: 0,\n    bytesEvicted: 0,\n    millisReading: 0,\n    millisWriting: 0,\n  };\n}\n\nexport type TreeSnapshotStoreOps = {\n  /** Directory holding the snapshots. One file per project. */\n  readonly dir: string;\n  /** Total bytes the directory may occupy after startup eviction. */\n  readonly maxSizeBytes: number;\n  readonly logger: MiLogger;\n};\n\nconst FILE_PREFIX = \"tree.\";\nconst FILE_SUFFIX = \".plts\";\n\n/** Keeps a filename to characters every filesystem we target accepts. */\nfunction safe(part: string): string {\n  return part.replace(/[^A-Za-z0-9_-]/g, \"_\");\n}\n\n/** Names this class writes: a finished snapshot, or the staging file of a write killed before\n *  its rename. The directory is caller-supplied and only defaults to one of ours, so nothing\n *  failing this is ever deleted, by the purge or by the startup eviction. */\nfunction isOurFile(name: string): boolean {\n  if (!name.startsWith(FILE_PREFIX)) return false;\n  return name.endsWith(FILE_SUFFIX) || name.includes(`${FILE_SUFFIX}.tmp.`);\n}\n\n/**\n * Snapshots of project tree mirrors on the local filesystem.\n *\n * A snapshot is addressed by backend instance, authenticated user, root resource, build stamp\n * and snapshot schema version. Everything except the root goes into the *scope*, which is\n * fixed for the lifetime of a client; the root distinguishes one project from another, so\n * there is one file per project per user per backend, rewritten in place.\n *\n * The session is deliberately not part of the key. It is witnessed inside the file and\n * compared on read: a snapshot from an ended session is a miss, but the file is kept, because\n * its bodies remain valid indefinitely and only its signatures have died. Deleting it would\n * destroy the evidence a future signature refresh would repair.\n */\nexport class TreeSnapshotStore {\n  private readonly stat = initialStat();\n\n  private constructor(\n    private readonly ops: TreeSnapshotStoreOps,\n    /** Identifies backend, user, build and schema. Same for every project in this session. */\n    private readonly scope: string,\n  ) {}\n\n  /**\n   * Builds a store for the given client, or returns undefined when nothing should be\n   * persisted for it.\n   *\n   * Returns undefined for an impersonated client: reading and writing under `asUser` would\n   * leave another user's mirror at rest under the admin's identity, usable only if the admin\n   * returned to that exact root. One condition removes both the hygiene question and the\n   * orphan one.\n   */\n  public static create(\n    pl: PlClient,\n    ops: TreeSnapshotStoreOps & { readonly enabled: boolean },\n  ): TreeSnapshotStore | undefined {\n    if (!ops.enabled) {\n      ops.logger.info(\"tree snapshots are disabled by configuration\");\n      return undefined;\n    }\n    if (pl.conf.asUser !== undefined) {\n      ops.logger.info(\"tree snapshots are disabled while the client is opened as another user\");\n      return undefined;\n    }\n\n    // The backend *instance*, not merely its address: instanceId rotates whenever the backend\n    // resets its database, which is exactly the case where the same address starts serving a\n    // different state under reused global ids. Without it, a reset at a fixed address (a local\n    // backend, whose working directory does not move) would be a key hit, and the only thing\n    // left to catch it would be the witness, which is empty on both sides on a backend that\n    // predates resource signatures.\n    //\n    // Hashed rather than spelled out: a login can be an email and an address can carry\n    // characters a filename cannot. The hash only has to be stable and to differ when any part\n    // differs, both of which it does. The NUL separator keeps the parts unambiguous.\n    const identity = createHash(\"sha256\")\n      .update([pl.conf.hostAndPort, pl.serverInfo.instanceId ?? \"\", pl.authUser ?? \"\"].join(\"\\0\"))\n      .digest(\"hex\")\n      .slice(0, 16);\n\n    const scope = `${PERSISTED_TREE_SCHEMA_VERSION}.${safe(ML_BUILD_STAMP)}.${identity}`;\n    return new TreeSnapshotStore(ops, scope);\n  }\n\n  /**\n   * Removes this class's files from the snapshot directory. Run when snapshots are switched\n   * off, so a user who turns the kill switch off because the disk is full or unwritable\n   * actually gets the space back, rather than leaving up to the size ceiling stranded there\n   * indefinitely.\n   *\n   * Deliberately keyed on the setting rather than on \"there is no store\": a store is also\n   * absent for an impersonated client, and deleting there would destroy the operator's own\n   * snapshots from their ordinary sessions. Never throws.\n   */\n  public static async purge(dir: string, logger: MiLogger): Promise<void> {\n    try {\n      // Deliberately NOT a recursive delete of `dir`. The path is caller-supplied and only\n      // defaults to a directory of ours, so removing it wholesale would let a misconfigured\n      // `treeSnapshotPath` take an unrelated directory with it, at the exact moment the user\n      // reached for a switch labelled \"my disk is troublesome\". Only files this class writes\n      // are removed, then the directory itself if that emptied it.\n      for (const name of await fsp.readdir(dir)) {\n        if (!isOurFile(name)) continue;\n        await fsp.rm(path.join(dir, name), { force: true }).catch(() => {});\n      }\n      await fsp.rmdir(dir).catch(() => {\n        // Still holds something that is not ours; leaving it is the point.\n      });\n    } catch (e: unknown) {\n      if ((e as NodeJS.ErrnoException | null)?.code === \"ENOENT\") return;\n      logger.warn(\n        `failed to clear the tree snapshot directory: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    }\n  }\n\n  public getStats(): Readonly<TreeSnapshotStat> {\n    return this.stat;\n  }\n\n  private fileFor(root: SignedResourceId): string {\n    // The root's global id, not the signed form: the signature changes every session while\n    // the file must not.\n    const { globalId } = parseSignedResourceId(root);\n    return path.join(this.ops.dir, `${FILE_PREFIX}${this.scope}.${globalId}${FILE_SUFFIX}`);\n  }\n\n  /**\n   * Reads the snapshot for a project root, or reports why there is nothing to restore.\n   *\n   * `root` is the id as resolved in the current session. Its signature is what the stored\n   * witness is compared against, so a rotated session is detected without inflating the\n   * payload, and no separate session lookup is needed anywhere.\n   */\n  public async read(\n    root: SignedResourceId,\n  ): Promise<{ ok: true; tree: PersistedTree } | { ok: false; miss: TreeSnapshotMiss }> {\n    const started = Date.now();\n    this.stat.reads++;\n    try {\n      const file = this.fileFor(root);\n      let bytes: Buffer;\n      try {\n        bytes = await fsp.readFile(file);\n      } catch (e: unknown) {\n        // A missing file and an unreadable one both mean a cold open, but they are different\n        // problems: one is an ordinary first open, the other is a cache directory that needs\n        // attention, and the counters are the only place that difference is visible.\n        const absent = (e as NodeJS.ErrnoException | null)?.code === \"ENOENT\";\n        if (!absent)\n          this.ops.logger.warn(\n            `tree snapshot exists but could not be read: ${e instanceof Error ? e.message : String(e)}`,\n          );\n        return this.miss(absent ? \"absent\" : \"unreadable\");\n      }\n\n      const header = readPersistedTreeHeader(bytes);\n      if (!header.ok) return this.miss(header.reason);\n\n      // On a backend predating resource signatures both sides are empty and always match,\n      // which is right: without signatures the ids are not session-bound in the first place.\n      const { signature } = parseSignedResourceId(root);\n      if (!Buffer.from(header.value.witness).equals(Buffer.from(signature)))\n        // Kept, not deleted. See the class comment.\n        return this.miss(\"session-rotated\");\n\n      const decoded = await decodePersistedTree(bytes);\n      if (!decoded.ok) return this.miss(decoded.reason);\n\n      // Touched on a hit so the modification time tracks last *use*, which is what the size\n      // trim is supposed to order by. Without this, a project reopened every day but never\n      // changed is never rewritten, and so ages out ahead of one touched once and abandoned.\n      const now = new Date();\n      await fsp.utimes(file, now, now).catch(() => {\n        // Ordering the trim is not worth failing a hit over.\n      });\n\n      this.stat.hits++;\n      return { ok: true, tree: decoded.value };\n    } finally {\n      this.stat.millisReading += Date.now() - started;\n    }\n  }\n\n  private miss(miss: TreeSnapshotMiss): { ok: false; miss: TreeSnapshotMiss } {\n    this.stat.misses[miss]++;\n    return { ok: false, miss };\n  }\n\n  /** Recorded by the caller once it knows the tree accepted the snapshot. The store cannot\n   *  tell on its own: it hands over bytes, and whether they become a tree is the tree's call. */\n  public noteRestored(): void {\n    this.stat.restores++;\n  }\n\n  /**\n   * Writes a snapshot, replacing any previous one for the same project.\n   *\n   * Never throws and never rejects: a write is an optimisation, and a full disk or a\n   * permissions problem must not fail the operation that triggered it. Staged and renamed\n   * into place, so a process killed mid-write leaves the previous snapshot rather than a torn\n   * one.\n   */\n  public async write(\n    root: SignedResourceId,\n    snapshot: PersistedTree,\n    ops: { compress?: boolean } = {},\n  ): Promise<boolean> {\n    const started = Date.now();\n    try {\n      const bytes = await encodePersistedTree(snapshot, { compress: ops.compress });\n      await ensureDirExists(this.ops.dir);\n\n      const file = this.fileFor(root);\n      await createPathAtomically(this.ops.logger, file, async (tempPath) => {\n        // \"wx\" so a colliding temp name fails instead of overwriting another writer's file.\n        await fsp.writeFile(tempPath, bytes, { flag: \"wx\" });\n      });\n\n      this.stat.writes++;\n      this.stat.bytesWritten += bytes.length;\n      return true;\n    } catch (e: unknown) {\n      this.stat.writeFailures++;\n      this.ops.logger.warn(\n        `failed to write tree snapshot: ${e instanceof Error ? e.message : String(e)}`,\n      );\n      return false;\n    } finally {\n      this.stat.millisWriting += Date.now() - started;\n    }\n  }\n\n  /** Deletes the snapshot for a project. Used by the fail-safe, when a restored tree turns\n   *  out not to match what the backend will serve. Never throws. */\n  public async discard(root: SignedResourceId): Promise<void> {\n    try {\n      await fsp.rm(this.fileFor(root), { force: true });\n      this.stat.discarded++;\n    } catch (e: unknown) {\n      this.ops.logger.warn(\n        `failed to discard tree snapshot: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    }\n  }\n\n  /**\n   * Startup housekeeping. Drops every snapshot outside the current scope (another build,\n   * backend, user or schema version), then trims what is left to the size ceiling, least\n   * recently written first.\n   *\n   * Modification time stands in for recency of use: an open project is rewritten\n   * periodically, so the file's age tracks how recently the project was worked on. Read times\n   * would be a truer signal but atime is unreliable across platforms and mount options.\n   *\n   * Runs at startup only, so the ceiling bounds what a session starts with rather than capping\n   * it throughout: a long session opening many projects can exceed it until the next launch.\n   *\n   * Never throws: an unusable cache directory should cost the cache, not the startup.\n   */\n  public async evict(): Promise<void> {\n    try {\n      await ensureDirExists(this.ops.dir);\n      const names = await fsp.readdir(this.ops.dir);\n\n      const current: { file: string; size: number; mtimeMs: number }[] = [];\n\n      for (const name of names) {\n        const file = path.join(this.ops.dir, name);\n\n        // Anything of ours not addressed to the current scope goes: another build, backend,\n        // user or schema version, and also the staging files of a write that was killed\n        // before its rename, which end in `.tmp.<hex>` rather than the suffix.\n        const inScope =\n          name.startsWith(`${FILE_PREFIX}${this.scope}.`) && name.endsWith(FILE_SUFFIX);\n\n        // Out of scope is not the same as ours to delete: a `treeSnapshotPath` pointed at an\n        // existing or shared directory would otherwise have every file in it removed at\n        // startup. Same rule as `purge`, for the same reason.\n        if (!inScope && !isOurFile(name)) continue;\n\n        let size = 0;\n        let mtimeMs = 0;\n        try {\n          const stat = await fsp.stat(file);\n          if (!stat.isFile()) continue;\n          size = stat.size;\n          mtimeMs = stat.mtimeMs;\n        } catch {\n          continue; // vanished under us, or unreadable: nothing to account for\n        }\n\n        if (inScope) {\n          current.push({ file, size, mtimeMs });\n          continue;\n        }\n\n        await this.remove(file, size, false);\n      }\n\n      const ceiling = this.ops.maxSizeBytes;\n      let total = current.reduce((sum, e) => sum + e.size, 0);\n      if (total <= ceiling) return;\n\n      // Oldest first, so the projects a user is actually working on are the ones that survive.\n      current.sort((a, b) => a.mtimeMs - b.mtimeMs);\n      for (const entry of current) {\n        if (total <= ceiling) break;\n        // Only a file that actually went stops counting against the ceiling. Subtracting\n        // regardless would let one undeletable file end the trim early and leave the directory\n        // over its limit.\n        if (await this.remove(entry.file, entry.size, true)) total -= entry.size;\n      }\n    } catch (e: unknown) {\n      this.ops.logger.warn(\n        `tree snapshot eviction failed: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    }\n  }\n\n  private async remove(file: string, size: number, forSize: boolean): Promise<boolean> {\n    try {\n      await fsp.rm(file, { force: true });\n      this.stat.evicted++;\n      this.stat.bytesEvicted += size;\n      if (forSize) this.stat.evictedForSize++;\n      return true;\n    } catch {\n      // A file we cannot delete is not worth failing startup over; it will be reconsidered\n      // on the next one.\n      return false;\n    }\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-middle-layer",
-  "version": "1.67.6",
+  "version": "1.68.0",
   "description": "Pl Middle Layer",
   "keywords": [],
   "license": "UNLICENSED",
@@ -30,25 +30,25 @@
     "utility-types": "^3.11.0",
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
-    "@milaboratories/computable": "2.9.8",
-    "@milaboratories/pl-drivers": "1.16.16",
+    "@milaboratories/columns-collection-driver": "0.2.4",
+    "@milaboratories/helpers": "1.14.5",
     "@milaboratories/pf-driver": "1.9.1",
     "@milaboratories/pf-spec-driver": "1.5.1",
+    "@milaboratories/computable": "2.9.8",
+    "@milaboratories/pl-drivers": "1.16.17",
     "@milaboratories/pl-client": "3.14.7",
-    "@milaboratories/columns-collection-driver": "0.2.4",
-    "@milaboratories/pl-deployments": "3.0.16",
     "@milaboratories/pl-errors": "1.4.36",
     "@milaboratories/pl-http": "1.2.4",
     "@milaboratories/pl-model-backend": "1.4.21",
+    "@milaboratories/pl-deployments": "3.0.16",
     "@milaboratories/pl-model-common": "1.48.0",
-    "@milaboratories/pl-tree": "1.13.7",
+    "@milaboratories/pl-tree": "1.14.0",
     "@milaboratories/pl-model-middle-layer": "1.32.0",
-    "@milaboratories/helpers": "1.14.5",
-    "@milaboratories/ts-helpers": "1.8.6",
+    "@platforma-sdk/block-tools": "2.14.3",
     "@milaboratories/resolve-helper": "1.1.3",
-    "@platforma-sdk/workflow-tengo": "6.8.3",
+    "@milaboratories/ts-helpers": "1.8.6",
     "@platforma-sdk/model": "1.83.0",
-    "@platforma-sdk/block-tools": "2.14.3"
+    "@platforma-sdk/workflow-tengo": "6.8.3"
   },
   "devDependencies": {
     "@types/node": "~24.5.2",

package/src/middle_layer/build_stamp.ts

@@ -0,0 +1,36 @@
+/** Injected by rolldown at build time, see `build.node.config.js`. Absent when the package is
+ *  consumed straight from sources (`USE_SOURCES=1`), because no build step runs then. */
+declare const __PL_ML_BUILD_STAMP__: string | undefined;
+
+function injectedStamp(): string | undefined {
+  try {
+    // Read inside a try: with no build step the identifier is an undeclared global, and
+    // reading it throws a ReferenceError rather than yielding undefined.
+    return __PL_ML_BUILD_STAMP__;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Identifies the build of this package, and through it the rules that shape what a persisted
+ * tree mirror contains: the pruning function, the field filter and the traversal stop rules,
+ * all of which live in this package. (The finality predicate comes from pl-client and is NOT
+ * covered, which is harmless: finality is recomputed on restore, so it is the one rule that
+ * cannot poison a stored file.)
+ *
+ * Used as a cache-key component, so a change to those rules invalidates every snapshot, costing
+ * one cold open. Each built artifact bakes in one stamp, so reopens stay warm across restarts
+ * of an installed version. A build from a dirty worktree includes the build time, so editing
+ * those rules locally can never hit a snapshot written under the old ones. In practice release
+ * builds are dirty too, because CI writes version bumps into the worktree before building; that
+ * costs nothing, since the stamp only has to be stable within an artifact.
+ *
+ * With no build at all (sources mode) the value is a constant. That deliberately trades away
+ * the dirty-worktree guarantee: it means someone running from sources exercises the restore
+ * path at all, rather than every snapshot being a guaranteed miss for the one audience most
+ * likely to find its defects. The exposure it reintroduces, editing pruning rules from sources
+ * and hitting a mirror written under the old ones, is the local-development gap the design
+ * already accepts, and `treeSnapshots: false` or deleting the directory clears it.
+ */
+export const ML_BUILD_STAMP: string = injectedStamp() ?? "sources";

package/src/middle_layer/index.ts

@@ -2,5 +2,6 @@ export { MiddleLayer } from "./middle_layer";
 export { Project } from "./project";
 export * from "./driver_kit";
 export * from "./ops";
+export type { TreeSnapshotMiss, TreeSnapshotStat } from "./tree_snapshot_store";
 export { ProjectsField } from "./project_list";
 export type { OutgoingShare, PendingShare } from "./sharing_list";

package/src/middle_layer/middle_layer.ts

@@ -111,6 +111,13 @@ import type { Dispatcher } from "undici";
 import { RetryAgent } from "undici";
 import { getDebugFlags } from "../debug";
 import { ProjectHelper } from "../model/project_helper";
+import type { TreeSnapshotStat } from "./tree_snapshot_store";
+import { TreeSnapshotStore } from "./tree_snapshot_store";
+
+/** How long shutdown waits for close-boundary snapshot writes that are already running. Long
+ *  enough for a ten-megabyte encode and write on ordinary storage, short enough that a wedged
+ *  filesystem does not hold the quit open. */
+const SNAPSHOT_DRAIN_TIMEOUT_MS = 5_000;
 
 export interface MiddleLayerEnvironment {
   dispose(): Promise<void>;
@@ -129,6 +136,9 @@ export interface MiddleLayerEnvironment {
   readonly driverKit: MiddleLayerDriverKit;
   readonly serviceRegistry: ModelServiceRegistry;
   readonly projectHelper: ProjectHelper;
+  /** Persisted project tree mirrors. Undefined when snapshots are switched off, or when the
+   *  client is impersonating another user, in which case nothing is read or written. */
+  readonly treeSnapshots?: TreeSnapshotStore;
 }
 
 /**
@@ -1132,6 +1142,36 @@ export class MiddleLayer {
 
   private readonly openedProjects = new Map<ProjectId, Project>();
 
+  /** Snapshot writes started by {@link closeProject} and not yet finished. Held only so
+   *  {@link close} can give them a bounded chance to land. */
+  private readonly pendingSnapshotWrites = new Set<Promise<void>>();
+
+  private trackSnapshotWrite(write: Promise<void>): void {
+    this.pendingSnapshotWrites.add(write);
+    void write.finally(() => this.pendingSnapshotWrites.delete(write));
+  }
+
+  /** Waits for close-boundary snapshot writes that are already running, up to `timeoutMs`.
+   *
+   * This starts no work: quitting still performs no snapshot of its own. It only lets a write
+   * that a project close already began finish, so closing a project and immediately quitting
+   * does not routinely lose it. Bounded, because a wedged filesystem must not hang the quit,
+   * and losing the write costs one cold open rather than any correctness. */
+  private async drainSnapshotWrites(timeoutMs: number): Promise<void> {
+    if (this.pendingSnapshotWrites.size === 0) return;
+
+    let timer: NodeJS.Timeout | undefined;
+    const expiry = new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, timeoutMs);
+      timer.unref?.();
+    });
+    try {
+      await Promise.race([Promise.allSettled(this.pendingSnapshotWrites), expiry]);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+
   /** Opens a project, and starts corresponding project maintenance loop. */
   public async openProject(id: ProjectId): Promise<void> {
     if (this.openedProjects.has(id)) throw new Error(`Project ${id} already opened`);
@@ -1145,6 +1185,16 @@ export class MiddleLayer {
     const prj = this.openedProjects.get(id);
     if (prj === undefined) throw new Error(`Project ${id} not found among opened projects`);
     this.openedProjects.delete(id);
+
+    // Snapshot before destroy, and here rather than inside destroy(): destroy() is also what
+    // application shutdown runs, and quitting should perform no snapshot work. Terminating the
+    // tree invalidates it, so the state has to be taken first either way.
+    //
+    // Started, not awaited. The capture happens synchronously inside, which is the part that
+    // needs the tree alive; the encode and write are up to ten megabytes of work that closing a
+    // project should not sit behind. Kept so shutdown can drain it.
+    this.trackSnapshotWrite(prj.snapshotOnClose());
+
     await prj.destroy();
     this.openedProjectsList.setValue([...this.openedProjects.keys()]);
   }
@@ -1161,6 +1211,13 @@ export class MiddleLayer {
     return this.openedProjects.has(id);
   }
 
+  /** Counters for the persisted project tree mirrors, or undefined when they are switched off.
+   *  Reads and hits are what show whether a reopen was actually warm, and the miss breakdown
+   *  says why it was not. */
+  public get treeSnapshotStats(): Readonly<TreeSnapshotStat> | undefined {
+    return this.env.treeSnapshots?.getStats();
+  }
+
   /**
    * Deallocates all runtime resources consumed by this object and awaits
    * actual termination of event loops and other processes associated with
@@ -1176,6 +1233,7 @@ export class MiddleLayer {
       this.sharingStateTree.terminate(),
       this.pendingSharesTree.terminate(),
     ]);
+    await this.drainSnapshotWrites(SNAPSHOT_DRAIN_TIMEOUT_MS);
     await this.env.dispose();
     await this.pl.close();
   }
@@ -1283,6 +1341,24 @@ export class MiddleLayer {
 
     const serviceRegistry = createModelServiceRegistry({ logger });
 
+    const treeSnapshots = TreeSnapshotStore.create(pl, {
+      dir: ops.treeSnapshotPath,
+      maxSizeBytes: ops.treeSnapshotOps.maxSizeBytes,
+      enabled: ops.treeSnapshotOps.enabled,
+      logger,
+    });
+    if (ops.treeSnapshotOps.enabled) {
+      // Housekeeping before any project opens: drop snapshots from other builds, backends and
+      // users, then trim to the ceiling.
+      await treeSnapshots?.evict();
+    } else {
+      // Switched off, so reclaim what earlier sessions left on disk. The reason to reach for
+      // this switch is usually the disk itself, and leaving the files behind would answer the
+      // wrong half of that complaint. Keyed on the setting, not on the store being absent: it
+      // is also absent for an impersonated client, whose session must not delete anything.
+      await TreeSnapshotStore.purge(ops.treeSnapshotPath, logger);
+    }
+
     const env: MiddleLayerEnvironment = {
       pl,
       blockEventDispatcher: new BlockEventDispatcher(),
@@ -1303,6 +1379,7 @@ export class MiddleLayer {
       serviceRegistry,
       quickJs,
       projectHelper: new ProjectHelper(quickJs, logger),
+      treeSnapshots,
       dispose: async () => {
         await serviceRegistry.dispose();
         await retryHttpDispatcher.destroy();

package/src/middle_layer/ops.ts

@@ -222,6 +222,40 @@ export type DriverKitOpsConstructor = Omit<
 export type MiddleLayerOpsPaths = DriverKitOpsPaths & {
   /** Common root where to put frontend code. */
   readonly frontendDownloadPath: string;
+
+  /**
+   * Directory holding persisted project tree mirrors, one file per project. Like
+   * {@link DriverKitOpsPaths.parquetCachePath} and unlike the spill directories, it is NOT
+   * emptied on startup: surviving a restart is the entire point. It is pruned instead, see
+   * {@link TreeSnapshotOps.maxSizeBytes}.
+   */
+  readonly treeSnapshotPath: string;
+};
+
+/** Tuning for the persisted project tree mirrors. Their directory is
+ *  {@link MiddleLayerOpsPaths.treeSnapshotPath}; this carries the behaviour knobs. */
+export type TreeSnapshotOps = {
+  /**
+   * Whether project tree mirrors are persisted and restored at all.
+   *
+   * On by default. This is an operational kill switch, for a deployment where the cache
+   * directory turns out to be unwritable or otherwise troublesome, not a rollout gate: the
+   * floor of the feature is current behaviour, since a cache that never hits is a cold open.
+   */
+  readonly enabled: boolean;
+
+  /**
+   * Minimum wall-clock gap between periodic writes for one project.
+   *
+   * Can be generous, because a stale snapshot is less complete rather than wrong: final
+   * resources never change and are never refetched, so this only bounds how much recent work
+   * comes back from the non-final frontier on restore.
+   */
+  readonly writeInterval: number;
+
+  /** Total bytes the snapshot directory may occupy after startup eviction. Needed because a
+   *  heavy project runs to roughly ten megabytes. */
+  readonly maxSizeBytes: number;
 };
 
 /** Debug options for middle layer. */
@@ -253,6 +287,10 @@ export type MiddleLayerOpsSettings = DriverKitOpsSettings & {
    * `sharedAt + envelopeTtlMs`. Share-with-everybody envelopes never expire
    * (`expiresAt: null`) and ignore this. */
   readonly envelopeTtlMs: number;
+
+  /** Settings for persisting project tree mirrors to disk, so reopening a project transfers
+   * what changed rather than the tree again. */
+  readonly treeSnapshotOps: TreeSnapshotOps;
 };
 
 export type MiddleLayerOps = MiddleLayerOpsSettings & MiddleLayerOpsPaths;
@@ -266,6 +304,7 @@ export const DefaultMiddleLayerOpsSettings: Pick<
   | "devBlockUpdateRecheckInterval"
   | "debugOps"
   | "envelopeTtlMs"
+  | "treeSnapshotOps"
 > = {
   ...DefaultDriverKitOpsSettings,
   defaultTreeOptions: {
@@ -279,17 +318,23 @@ export const DefaultMiddleLayerOpsSettings: Pick<
   devBlockUpdateRecheckInterval: 1000,
   projectRefreshInterval: 2000,
   envelopeTtlMs: 14 * 24 * 3600 * 1000, // 14 days
+  treeSnapshotOps: {
+    enabled: true,
+    writeInterval: 5 * 60 * 1000, // 5 minutes
+    maxSizeBytes: 256 * 1024 * 1024, // 256 MB, roughly 25 heavy projects
+  },
 };
 
 export function DefaultMiddleLayerOpsPaths(
   workDir: string,
 ): Pick<
   MiddleLayerOpsPaths,
-  keyof ReturnType<typeof DefaultDriverKitOpsPaths> | "frontendDownloadPath"
+  keyof ReturnType<typeof DefaultDriverKitOpsPaths> | "frontendDownloadPath" | "treeSnapshotPath"
 > {
   return {
     ...DefaultDriverKitOpsPaths(workDir),
     frontendDownloadPath: path.join(workDir, "frontend"),
+    treeSnapshotPath: path.join(workDir, "treeSnapshots"),
   };
 }