@milaboratories/pl-middle-layer 1.67.5 → 1.68.0

package/dist/middle_layer/ops.d.ts

@@ -1,13 +1,16 @@
 import { TemporalSynchronizedTreeOps } from "./types.js";
 import { PFrameDriverOps, ParquetCacheOps } from "../pool/driver.js";
+import "../pool/index.js";
 import { MiLogger } from "@milaboratories/ts-helpers";
 import { DownloadBlobToURLDriverOps, DownloadDriverOps, DownloadUrlDriverOps, LocalStorageProjection, LogsStreamDriverOps, OpenFileDialogCallback, UploadDriverOps, VirtualLocalStorageSpec } from "@milaboratories/pl-drivers";
-
 //#region src/middle_layer/ops.d.ts
 /** Paths part of {@link DriverKitOps}. */
-type DriverKitOpsPaths = {
-  /** Common root where to put downloaded blobs / downloaded blob cache */readonly blobDownloadPath: string; /** Common root for a cache for range queries. */
-  readonly blobDownloadRangesCachePath: string; /** Common root where to put downloaded blobs with */
+export type DriverKitOpsPaths = {
+  /** Common root where to put downloaded blobs / downloaded blob cache */
+  readonly blobDownloadPath: string;
+  /** Common root for a cache for range queries. */
+  readonly blobDownloadRangesCachePath: string;
+  /** Common root where to put downloaded blobs with */
   readonly downloadBlobToURLPath: string;
   /**
    * List of pl storages that have projections in local file system.
@@ -26,7 +29,8 @@ type DriverKitOpsPaths = {
    * List of virtual storages that will allow homogeneous access to local FSs through LS API.
    * If undefined, default list will be created.
    * */
-  readonly virtualLocalStoragesOverride?: VirtualLocalStorageSpec[]; /** Path to the directory where pframes will spill temporary files and store materialized views */
+  readonly virtualLocalStoragesOverride?: VirtualLocalStorageSpec[];
+  /** Path to the directory where pframes will spill temporary files and store materialized views */
   readonly pframesSpillPath: string;
   /**
    * Path to the directory backing the persistent parquet blob cache. Unlike
@@ -36,7 +40,7 @@ type DriverKitOpsPaths = {
   readonly parquetCachePath: string;
 };
 /** Options required to initialize full set of middle layer driver kit */
-type DriverKitOpsSettings = {
+export type DriverKitOpsSettings = {
   readonly logger: MiLogger;
   /**
    * Local secret, that is used to sign and verify different pieces of information
@@ -49,21 +53,24 @@ type DriverKitOpsSettings = {
    * Settings related to the download driver making operations with blobs. This driver is also used
    * to download logs when source process terminates and log terns into a blob
    */
-  readonly blobDriverOps: DownloadDriverOps; /** Settings related to the frontend driver that downloads frontends. */
+  readonly blobDriverOps: DownloadDriverOps;
+  /** Settings related to the frontend driver that downloads frontends. */
   readonly frontendDownloadDriverOps: DownloadUrlDriverOps;
   readonly downloadBlobToURLDriverOps: DownloadBlobToURLDriverOps;
   /**
    * Settings related to the upload driver that actually performs upload and helps render upload
    * and indexing progresses from related pl resources.
    * */
-  readonly uploadDriverOps: UploadDriverOps; /** Settings related to the streaming log driver */
+  readonly uploadDriverOps: UploadDriverOps;
+  /** Settings related to the streaming log driver */
   readonly logStreamDriverOps: LogsStreamDriverOps;
   /**
    * Callback to access system file open dialog, must be provided by the environment,
    * to allow for {@link showOpenSingleFileDialog} / {@link showOpenMultipleFilesDialog}
    * calls from the UI.
    */
-  readonly openFileDialogCallback: OpenFileDialogCallback; /** Settings related to the PFrame driver */
+  readonly openFileDialogCallback: OpenFileDialogCallback;
+  /** Settings related to the PFrame driver */
   readonly pFrameDriverOps: PFrameDriverOps;
   /**
    * Tuning for the persistent parquet blob cache. Its directory is
@@ -72,40 +79,77 @@ type DriverKitOpsSettings = {
    */
   readonly parquetCacheOps: ParquetCacheOps;
 };
-type DriverKitOps = DriverKitOpsPaths & DriverKitOpsSettings;
+export type DriverKitOps = DriverKitOpsPaths & DriverKitOpsSettings;
 /** Some defaults fot MiddleLayerOps. */
-declare const DefaultDriverKitOpsSettings: Pick<DriverKitOpsSettings, "logger" | "blobDriverOps" | "frontendDownloadDriverOps" | "downloadBlobToURLDriverOps" | "uploadDriverOps" | "logStreamDriverOps" | "pFrameDriverOps" | "parquetCacheOps">;
-declare function DefaultDriverKitOpsPaths(workDir: string): Pick<DriverKitOpsPaths, "blobDownloadPath" | "blobDownloadRangesCachePath" | "downloadBlobToURLPath" | "pframesSpillPath" | "parquetCachePath">;
+export declare const DefaultDriverKitOpsSettings: Pick<DriverKitOpsSettings, "logger" | "blobDriverOps" | "frontendDownloadDriverOps" | "downloadBlobToURLDriverOps" | "uploadDriverOps" | "logStreamDriverOps" | "pFrameDriverOps" | "parquetCacheOps">;
+export declare function DefaultDriverKitOpsPaths(workDir: string): Pick<DriverKitOpsPaths, "blobDownloadPath" | "blobDownloadRangesCachePath" | "downloadBlobToURLPath" | "pframesSpillPath" | "parquetCachePath">;
 /** Fields with default values are marked as optional here. */
-type DriverKitOpsConstructor = Omit<DriverKitOpsSettings, keyof typeof DefaultDriverKitOpsSettings> & Partial<typeof DefaultDriverKitOpsSettings> & Omit<DriverKitOpsPaths, keyof ReturnType<typeof DefaultDriverKitOpsPaths>> & Partial<ReturnType<typeof DefaultDriverKitOpsPaths>>;
-type MiddleLayerOpsPaths = DriverKitOpsPaths & {
-  /** Common root where to put frontend code. */readonly frontendDownloadPath: string;
+export type DriverKitOpsConstructor = Omit<DriverKitOpsSettings, keyof typeof DefaultDriverKitOpsSettings> & Partial<typeof DefaultDriverKitOpsSettings> & Omit<DriverKitOpsPaths, keyof ReturnType<typeof DefaultDriverKitOpsPaths>> & Partial<ReturnType<typeof DefaultDriverKitOpsPaths>>;
+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. */
-type MiddleLayerDebugOptions = {
-  /** If true, will dump initial tree state to the file with root resource id as name. */dumpInitialTreeState: boolean;
+export type MiddleLayerDebugOptions = {
+  /** If true, will dump initial tree state to the file with root resource id as name. */
+  dumpInitialTreeState: boolean;
 };
 /** Configuration controlling different aspects of middle layer behaviour. */
-type MiddleLayerOpsSettings = DriverKitOpsSettings & {
-  /** Debug options. */readonly debugOps: MiddleLayerDebugOptions;
+export type MiddleLayerOpsSettings = DriverKitOpsSettings & {
+  /** Debug options. */
+  readonly debugOps: MiddleLayerDebugOptions;
   /** Contain temporal options controlling how often should pl trees be
    * synchronized with the pl server. */
   readonly defaultTreeOptions: TemporalSynchronizedTreeOps;
   /** Defines interval in milliseconds for running periodic project maintenance job.
    * Project maintenance includes background staging rendering and cached outputs cleanup. */
-  readonly projectRefreshInterval: number; /** How often to check for dev block updates */
-  readonly devBlockUpdateRecheckInterval: number; /** Prioritize this channel if update is available in this block */
+  readonly projectRefreshInterval: number;
+  /** How often to check for dev block updates */
+  readonly devBlockUpdateRecheckInterval: number;
+  /** Prioritize this channel if update is available in this block */
   readonly preferredUpdateChannel?: string;
   /** Default lifetime applied to a targeted shared envelope at creation, as
    * `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;
 };
-type MiddleLayerOps = MiddleLayerOpsSettings & MiddleLayerOpsPaths;
+export type MiddleLayerOps = MiddleLayerOpsSettings & MiddleLayerOpsPaths;
 /** Some defaults fot MiddleLayerOps. */
-declare const DefaultMiddleLayerOpsSettings: Pick<MiddleLayerOps, keyof typeof DefaultDriverKitOpsSettings | "defaultTreeOptions" | "projectRefreshInterval" | "devBlockUpdateRecheckInterval" | "debugOps" | "envelopeTtlMs">;
-declare function DefaultMiddleLayerOpsPaths(workDir: string): Pick<MiddleLayerOpsPaths, keyof ReturnType<typeof DefaultDriverKitOpsPaths> | "frontendDownloadPath">;
-type MiddleLayerOpsConstructor = Omit<MiddleLayerOpsSettings, keyof typeof DefaultMiddleLayerOpsSettings> & Partial<typeof DefaultMiddleLayerOpsSettings> & Omit<MiddleLayerOpsPaths, keyof Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>> & Partial<Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>>;
+export declare const DefaultMiddleLayerOpsSettings: Pick<MiddleLayerOps, keyof typeof DefaultDriverKitOpsSettings | "defaultTreeOptions" | "projectRefreshInterval" | "devBlockUpdateRecheckInterval" | "debugOps" | "envelopeTtlMs" | "treeSnapshotOps">;
+export declare function DefaultMiddleLayerOpsPaths(workDir: string): Pick<MiddleLayerOpsPaths, keyof ReturnType<typeof DefaultDriverKitOpsPaths> | "frontendDownloadPath" | "treeSnapshotPath">;
+export type MiddleLayerOpsConstructor = Omit<MiddleLayerOpsSettings, keyof typeof DefaultMiddleLayerOpsSettings> & Partial<typeof DefaultMiddleLayerOpsSettings> & Omit<MiddleLayerOpsPaths, keyof Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>> & Partial<Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>>;
 //#endregion
-export { DefaultDriverKitOpsPaths, DefaultDriverKitOpsSettings, DefaultMiddleLayerOpsPaths, DefaultMiddleLayerOpsSettings, DriverKitOps, DriverKitOpsConstructor, DriverKitOpsPaths, DriverKitOpsSettings, MiddleLayerDebugOptions, MiddleLayerOps, MiddleLayerOpsConstructor, MiddleLayerOpsPaths, MiddleLayerOpsSettings };
 //# sourceMappingURL=ops.d.ts.map

package/dist/middle_layer/ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ops.d.ts","names":[],"sources":["../../src/middle_layer/ops.ts"],"mappings":";;;;;;AAiBA;AAAA,KAAY,iBAAA;mFAED,gBAAA;EAAA,SAGA,2BAAA,UAGA;EAAA,SAAA,qBAAA;EAckB;;;;;;AAgBF;AAI3B;;;;;EApB6B,SAAlB,gBAAA,EAAkB,sBAAA;EA4DU;;;;EAAA,SAtD5B,4BAAA,GAA+B,uBAAuB,IAiGrC;EAAA,SA9FjB,gBAAA;EA8FgC;;;;;EAAA,SAvFhC,gBAAA;AAAA;;KAIC,oBAAA;EAAA,SAKD,MAAA,EAAQ,QAAA;EA6CR;;;;;;EAAA,SAjCA,WAAA;EA2DiB;;;;EAAA,SAjDjB,aAAA,EAAe,iBAAA,EA2Dd;EAAA,SApDD,yBAAA,EAA2B,oBAAA;EAAA,SAM3B,0BAAA,EAA4B,0BAAA;EA8CZ;AAAwC;AAGnE;;EAH2B,SApChB,eAAA,EAAiB,eAAA,EAuCc;EAAA,SA/B/B,kBAAA,EAAoB,mBAAA;EA4Ef;;;;;EAAA,SAjEL,sBAAA,EAAwB,sBAAA,EAoEjC;EAAA,SA7DS,eAAA,EAAiB,eAAA;EA6DT;AAiBnB;;;;EAjBmB,SAtDR,eAAA,EAAiB,eAAA;AAAA;AAAA,KAGhB,YAAA,GAAe,iBAAA,GAAoB,oBAAoB;;cAGtD,2BAAA,EAA6B,IAAI,CAC5C,oBAAA;AAAA,iBA4Cc,wBAAA,CACd,OAAA,WACC,IAAI,CACL,iBAAA;;KAiBU,uBAAA,GAA0B,IAAA,CACpC,oBAAA,eACa,2BAAA,IAEb,OAAA,QAAe,2BAAA,IACf,IAAA,CAAK,iBAAA,QAAyB,UAAA,QAAkB,wBAAA,KAChD,OAAA,CAAQ,UAAA,QAAkB,wBAAA;AAAA,KAEhB,mBAAA,GAAsB,iBAAiB;EAFzC,uDAIC,oBAAoB;AAAA;;KAInB,uBAAA;EAbV,uFAeA,oBAAoB;AAAA;;KAIV,sBAAA,GAAyB,oBAAA;EAf9B,8BAiBI,QAAA,EAAU,uBAAA;EAjB6B;;EAAA,SAqBvC,kBAAA,EAAoB,2BAAA;EApBH;;EAAA,SAwBjB,sBAAA,UAtBC;EAAA,SAyBD,6BAAA;WAGA,sBAAA;EA1BoB;AAI/B;;EAJ+B,SA+BpB,aAAA;AAAA;AAAA,KAGC,cAAA,GAAiB,sBAAA,GAAyB,mBAAmB;AAxBzE;AAAA,cA2Ba,6BAAA,EAA+B,IAAA,CAC1C,cAAA,eACe,2BAAA;AAAA,iBAqBD,0BAAA,CACd,OAAA,WACC,IAAA,CACD,mBAAA,QACM,UAAA,QAAkB,wBAAA;AAAA,KAQd,yBAAA,GAA4B,IAAA,CACtC,sBAAA,eACa,6BAAA,IAEb,OAAA,QAAe,6BAAA,IACf,IAAA,CAAK,mBAAA,QAA2B,OAAA,CAAQ,UAAA,QAAkB,0BAAA,MAC1D,OAAA,CAAQ,OAAA,CAAQ,UAAA,QAAkB,0BAAA"}
+{"version":3,"file":"ops.d.ts","names":[],"sources":["../../src/middle_layer/ops.ts"],"mappings":";;;;;;;YAiBY;;WAED;;WAGA;;WAGA;;;;;;;;;;;;;WAcA,kBAAkB;;;;;WAMlB,+BAA+B;;WAG/B;;;;;;WAOA;;;YAIC;WAKD,QAAQ;;;;;;;WAYR;;;;;WAUA,eAAe;;WAOf,2BAA2B;WAM3B,4BAA4B;;;;;WAU5B,iBAAiB;;WAQjB,oBAAoB;;;;;;WAWpB,wBAAwB;;WAOxB,iBAAiB;;;;;;WAOjB,iBAAiB;;YAGhB,eAAe,oBAAoB;;qBAGlC,6BAA6B,KACxC;wBA4Cc,yBACd,kBACC,KACD;;YAiBU,0BAA0B,KACpC,mCACa,+BAEb,eAAe,+BACf,KAAK,yBAAyB,kBAAkB,6BAChD,QAAQ,kBAAkB;YAEhB,sBAAsB;;WAEvB;;;;;;;WAQA;;;;YAKC;;;;;;;;WAQD;;;;;;;;WASA;;;WAIA;;;YAIC;;EAEV;;;YAIU,yBAAyB;;WAE1B,UAAU;;;WAIV,oBAAoB;;;WAIpB;;WAGA;;WAGA;;;;WAKA;;;WAIA,iBAAiB;;YAGhB,iBAAiB,yBAAyB;;qBAGzC,+BAA+B,KAC1C,6BACe;wBA2BD,2BACd,kBACC,KACD,2BACM,kBAAkB;YASd,4BAA4B,KACtC,qCACa,iCAEb,eAAe,iCACf,KAAK,2BAA2B,QAAQ,kBAAkB,gCAC1D,QAAQ,QAAQ,kBAAkB"}

package/dist/middle_layer/ops.js

@@ -58,12 +58,18 @@ const DefaultMiddleLayerOpsSettings = {
 	debugOps: { dumpInitialTreeState: false },
 	devBlockUpdateRecheckInterval: 1e3,
 	projectRefreshInterval: 2e3,
-	envelopeTtlMs: 336 * 3600 * 1e3
+	envelopeTtlMs: 336 * 3600 * 1e3,
+	treeSnapshotOps: {
+		enabled: true,
+		writeInterval: 300 * 1e3,
+		maxSizeBytes: 256 * 1024 * 1024
+	}
 };
 function DefaultMiddleLayerOpsPaths(workDir) {
 	return {
 		...DefaultDriverKitOpsPaths(workDir),
-		frontendDownloadPath: path.join(workDir, "frontend")
+		frontendDownloadPath: path.join(workDir, "frontend"),
+		treeSnapshotPath: path.join(workDir, "treeSnapshots")
 	};
 }
 //#endregion

package/dist/middle_layer/ops.js.map

@@ -1 +1 @@
-{"version":3,"file":"ops.js","names":[],"sources":["../../src/middle_layer/ops.ts"],"sourcesContent":["import type { TemporalSynchronizedTreeOps } from \"./types\";\nimport type {\n  DownloadBlobToURLDriverOps,\n  DownloadDriverOps,\n  DownloadUrlDriverOps,\n  OpenFileDialogCallback,\n  VirtualLocalStorageSpec,\n} from \"@milaboratories/pl-drivers\";\nimport type { UploadDriverOps } from \"@milaboratories/pl-drivers\";\nimport type { LogsStreamDriverOps } from \"@milaboratories/pl-drivers\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { ConsoleLoggerAdapter } from \"@milaboratories/ts-helpers\";\nimport type { LocalStorageProjection } from \"@milaboratories/pl-drivers\";\nimport path from \"node:path\";\nimport { PFrameDriverOpsDefaults, type PFrameDriverOps, type ParquetCacheOps } from \"../pool\";\n\n/** Paths part of {@link DriverKitOps}. */\nexport type DriverKitOpsPaths = {\n  /** Common root where to put downloaded blobs / downloaded blob cache */\n  readonly blobDownloadPath: string;\n\n  /** Common root for a cache for range queries. */\n  readonly blobDownloadRangesCachePath: string;\n\n  /** Common root where to put downloaded blobs with */\n  readonly downloadBlobToURLPath: string;\n\n  /**\n   * List of pl storages that have projections in local file system.\n   *\n   * This option affect two drivers:\n   *\n   *   (1) LS driver generates \"index\" handles instead of \"upload\" for paths inside those locations\n   *\n   *   (2) Download driver directly serves content retrieval requests for blobs from listed storages,\n   *       and don't apply any caching for such blobs (i.e. preventing duplication of files for Downloaded\n   *       type handles, making OnDemand and Downloaded handles equivalent)\n   *\n   * */\n  readonly localProjections: LocalStorageProjection[];\n\n  /**\n   * List of virtual storages that will allow homogeneous access to local FSs through LS API.\n   * If undefined, default list will be created.\n   * */\n  readonly virtualLocalStoragesOverride?: VirtualLocalStorageSpec[];\n\n  /** Path to the directory where pframes will spill temporary files and store materialized views */\n  readonly pframesSpillPath: string;\n\n  /**\n   * Path to the directory backing the persistent parquet blob cache. Unlike\n   * {@link pframesSpillPath} this directory is NOT emptied on startup - the cache\n   * (and its lifetime counters) is meant to survive restarts.\n   */\n  readonly parquetCachePath: string;\n};\n\n/** Options required to initialize full set of middle layer driver kit */\nexport type DriverKitOpsSettings = {\n  //\n  // Common\n  //\n\n  readonly logger: MiLogger;\n\n  //\n  // Signer\n  //\n\n  /**\n   * Local secret, that is used to sign and verify different pieces of information\n   * that can be used to access local data, like local paths for ongoing uploads.\n   *\n   * Use {@link MiddleLayer.generateLocalSecret} to generate sufficiently random string.\n   * */\n  readonly localSecret: string;\n\n  //\n  // Blob Driver\n  //\n\n  /**\n   * Settings related to the download driver making operations with blobs. This driver is also used\n   * to download logs when source process terminates and log terns into a blob\n   */\n  readonly blobDriverOps: DownloadDriverOps;\n\n  //\n  // Frontend Driver\n  //\n\n  /** Settings related to the frontend driver that downloads frontends. */\n  readonly frontendDownloadDriverOps: DownloadUrlDriverOps;\n\n  //\n  // Blob To URL Driver\n  //\n\n  readonly downloadBlobToURLDriverOps: DownloadBlobToURLDriverOps;\n\n  //\n  // Upload Driver\n  //\n\n  /**\n   * Settings related to the upload driver that actually performs upload and helps render upload\n   * and indexing progresses from related pl resources.\n   * */\n  readonly uploadDriverOps: UploadDriverOps;\n\n  //\n  // Log streaming ops\n  // (static logs are served via the blob driver)\n  //\n\n  /** Settings related to the streaming log driver */\n  readonly logStreamDriverOps: LogsStreamDriverOps;\n\n  //\n  // LS Driver\n  //\n\n  /**\n   * Callback to access system file open dialog, must be provided by the environment,\n   * to allow for {@link showOpenSingleFileDialog} / {@link showOpenMultipleFilesDialog}\n   * calls from the UI.\n   */\n  readonly openFileDialogCallback: OpenFileDialogCallback;\n\n  //\n  // PFrame Driver\n  //\n\n  /** Settings related to the PFrame driver */\n  readonly pFrameDriverOps: PFrameDriverOps;\n\n  /**\n   * Tuning for the persistent parquet blob cache. Its directory is\n   * {@link DriverKitOpsPaths.parquetCachePath}; this carries only the\n   * size/eviction knobs.\n   */\n  readonly parquetCacheOps: ParquetCacheOps;\n};\n\nexport type DriverKitOps = DriverKitOpsPaths & DriverKitOpsSettings;\n\n/** Some defaults fot MiddleLayerOps. */\nexport const DefaultDriverKitOpsSettings: Pick<\n  DriverKitOpsSettings,\n  | \"logger\"\n  | \"blobDriverOps\"\n  | \"frontendDownloadDriverOps\"\n  | \"downloadBlobToURLDriverOps\"\n  | \"uploadDriverOps\"\n  | \"logStreamDriverOps\"\n  | \"pFrameDriverOps\"\n  | \"parquetCacheOps\"\n> = {\n  logger: new ConsoleLoggerAdapter(),\n  blobDriverOps: {\n    cacheSoftSizeBytes: 8 * 1024 * 1024 * 1024, // 8 GB\n    rangesCacheMaxSizeBytes: 8 * 1024 * 1024 * 1024, // 8 GB\n    nConcurrentDownloads: 10,\n  },\n  frontendDownloadDriverOps: {\n    cacheSoftSizeBytes: 1 * 1024 * 1024 * 1024, // 1 GB\n    withGunzip: true,\n    nConcurrentDownloads: 50,\n  },\n  downloadBlobToURLDriverOps: {\n    cacheSoftSizeBytes: 1 * 1024 * 1024 * 1024, // 1 GB\n    nConcurrentDownloads: 10,\n  },\n  uploadDriverOps: {\n    nConcurrentPartUploads: 10,\n    nConcurrentGetProgresses: 10,\n    pollingInterval: 1000,\n    stopPollingDelay: 1000,\n  },\n  logStreamDriverOps: {\n    nConcurrentGetLogs: 10,\n    pollingInterval: 1000,\n    stopPollingDelay: 1000,\n  },\n  pFrameDriverOps: PFrameDriverOpsDefaults,\n  parquetCacheOps: {\n    maxSizeBytes: 8 * 1024 * 1024 * 1024, // 8 GB\n    admissionFraction: 0.2, // a single file may occupy at most 20% of the budget\n    maxFilesTracked: 50_000, // ghost (previously-evicted) files remembered to guide readmission\n  },\n};\n\nexport function DefaultDriverKitOpsPaths(\n  workDir: string,\n): Pick<\n  DriverKitOpsPaths,\n  | \"blobDownloadPath\"\n  | \"blobDownloadRangesCachePath\"\n  | \"downloadBlobToURLPath\"\n  | \"pframesSpillPath\"\n  | \"parquetCachePath\"\n> {\n  return {\n    blobDownloadPath: path.join(workDir, \"download\"),\n    blobDownloadRangesCachePath: path.join(workDir, \"downloadRangesCache\"),\n    downloadBlobToURLPath: path.join(workDir, \"downloadToURL\"),\n    pframesSpillPath: path.join(workDir, \"pframes\"),\n    parquetCachePath: path.join(workDir, \"parquetCache\"),\n  };\n}\n\n/** Fields with default values are marked as optional here. */\nexport type DriverKitOpsConstructor = Omit<\n  DriverKitOpsSettings,\n  keyof typeof DefaultDriverKitOpsSettings\n> &\n  Partial<typeof DefaultDriverKitOpsSettings> &\n  Omit<DriverKitOpsPaths, keyof ReturnType<typeof DefaultDriverKitOpsPaths>> &\n  Partial<ReturnType<typeof DefaultDriverKitOpsPaths>>;\n\nexport type MiddleLayerOpsPaths = DriverKitOpsPaths & {\n  /** Common root where to put frontend code. */\n  readonly frontendDownloadPath: string;\n};\n\n/** Debug options for middle layer. */\nexport type MiddleLayerDebugOptions = {\n  /** If true, will dump initial tree state to the file with root resource id as name. */\n  dumpInitialTreeState: boolean;\n};\n\n/** Configuration controlling different aspects of middle layer behaviour. */\nexport type MiddleLayerOpsSettings = DriverKitOpsSettings & {\n  /** Debug options. */\n  readonly debugOps: MiddleLayerDebugOptions;\n\n  /** Contain temporal options controlling how often should pl trees be\n   * synchronized with the pl server. */\n  readonly defaultTreeOptions: TemporalSynchronizedTreeOps;\n\n  /** Defines interval in milliseconds for running periodic project maintenance job.\n   * Project maintenance includes background staging rendering and cached outputs cleanup. */\n  readonly projectRefreshInterval: number;\n\n  /** How often to check for dev block updates */\n  readonly devBlockUpdateRecheckInterval: number;\n\n  /** Prioritize this channel if update is available in this block */\n  readonly preferredUpdateChannel?: string;\n\n  /** Default lifetime applied to a targeted shared envelope at creation, as\n   * `sharedAt + envelopeTtlMs`. Share-with-everybody envelopes never expire\n   * (`expiresAt: null`) and ignore this. */\n  readonly envelopeTtlMs: number;\n};\n\nexport type MiddleLayerOps = MiddleLayerOpsSettings & MiddleLayerOpsPaths;\n\n/** Some defaults fot MiddleLayerOps. */\nexport const DefaultMiddleLayerOpsSettings: Pick<\n  MiddleLayerOps,\n  | keyof typeof DefaultDriverKitOpsSettings\n  | \"defaultTreeOptions\"\n  | \"projectRefreshInterval\"\n  | \"devBlockUpdateRecheckInterval\"\n  | \"debugOps\"\n  | \"envelopeTtlMs\"\n> = {\n  ...DefaultDriverKitOpsSettings,\n  defaultTreeOptions: {\n    pollingInterval: 200,\n    stopPollingDelay: 2500,\n    initialTreeLoadingTimeout: 100 * 60 * 60 * 1000, // disable timeout for loading project tree (100 hours)\n  },\n  debugOps: {\n    dumpInitialTreeState: false,\n  },\n  devBlockUpdateRecheckInterval: 1000,\n  projectRefreshInterval: 2000,\n  envelopeTtlMs: 14 * 24 * 3600 * 1000, // 14 days\n};\n\nexport function DefaultMiddleLayerOpsPaths(\n  workDir: string,\n): Pick<\n  MiddleLayerOpsPaths,\n  keyof ReturnType<typeof DefaultDriverKitOpsPaths> | \"frontendDownloadPath\"\n> {\n  return {\n    ...DefaultDriverKitOpsPaths(workDir),\n    frontendDownloadPath: path.join(workDir, \"frontend\"),\n  };\n}\n\nexport type MiddleLayerOpsConstructor = Omit<\n  MiddleLayerOpsSettings,\n  keyof typeof DefaultMiddleLayerOpsSettings\n> &\n  Partial<typeof DefaultMiddleLayerOpsSettings> &\n  Omit<MiddleLayerOpsPaths, keyof Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>> &\n  Partial<Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>>;\n"],"mappings":";;;;;;AAoJA,MAAa,8BAUT;CACF,QAAQ,IAAI,qBAAqB;CACjC,eAAe;EACb,oBAAoB,IAAI,OAAO,OAAO;EACtC,yBAAyB,IAAI,OAAO,OAAO;EAC3C,sBAAsB;CACxB;CACA,2BAA2B;EACzB,oBAAoB,IAAI,OAAO,OAAO;EACtC,YAAY;EACZ,sBAAsB;CACxB;CACA,4BAA4B;EAC1B,oBAAoB,IAAI,OAAO,OAAO;EACtC,sBAAsB;CACxB;CACA,iBAAiB;EACf,wBAAwB;EACxB,0BAA0B;EAC1B,iBAAiB;EACjB,kBAAkB;CACpB;CACA,oBAAoB;EAClB,oBAAoB;EACpB,iBAAiB;EACjB,kBAAkB;CACpB;CACA,iBAAiB;CACjB,iBAAiB;EACf,cAAc,IAAI,OAAO,OAAO;EAChC,mBAAmB;EACnB,iBAAiB;CACnB;AACF;AAEA,SAAgB,yBACd,SAQA;CACA,OAAO;EACL,kBAAkB,KAAK,KAAK,SAAS,UAAU;EAC/C,6BAA6B,KAAK,KAAK,SAAS,qBAAqB;EACrE,uBAAuB,KAAK,KAAK,SAAS,eAAe;EACzD,kBAAkB,KAAK,KAAK,SAAS,SAAS;EAC9C,kBAAkB,KAAK,KAAK,SAAS,cAAc;CACrD;AACF;;AAkDA,MAAa,gCAQT;CACF,GAAG;CACH,oBAAoB;EAClB,iBAAiB;EACjB,kBAAkB;EAClB,2BAA2B,MAAW,KAAK;CAC7C;CACA,UAAU,EACR,sBAAsB,MACxB;CACA,+BAA+B;CAC/B,wBAAwB;CACxB,eAAe,MAAU,OAAO;AAClC;AAEA,SAAgB,2BACd,SAIA;CACA,OAAO;EACL,GAAG,yBAAyB,OAAO;EACnC,sBAAsB,KAAK,KAAK,SAAS,UAAU;CACrD;AACF"}
+{"version":3,"file":"ops.js","names":[],"sources":["../../src/middle_layer/ops.ts"],"sourcesContent":["import type { TemporalSynchronizedTreeOps } from \"./types\";\nimport type {\n  DownloadBlobToURLDriverOps,\n  DownloadDriverOps,\n  DownloadUrlDriverOps,\n  OpenFileDialogCallback,\n  VirtualLocalStorageSpec,\n} from \"@milaboratories/pl-drivers\";\nimport type { UploadDriverOps } from \"@milaboratories/pl-drivers\";\nimport type { LogsStreamDriverOps } from \"@milaboratories/pl-drivers\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { ConsoleLoggerAdapter } from \"@milaboratories/ts-helpers\";\nimport type { LocalStorageProjection } from \"@milaboratories/pl-drivers\";\nimport path from \"node:path\";\nimport { PFrameDriverOpsDefaults, type PFrameDriverOps, type ParquetCacheOps } from \"../pool\";\n\n/** Paths part of {@link DriverKitOps}. */\nexport type DriverKitOpsPaths = {\n  /** Common root where to put downloaded blobs / downloaded blob cache */\n  readonly blobDownloadPath: string;\n\n  /** Common root for a cache for range queries. */\n  readonly blobDownloadRangesCachePath: string;\n\n  /** Common root where to put downloaded blobs with */\n  readonly downloadBlobToURLPath: string;\n\n  /**\n   * List of pl storages that have projections in local file system.\n   *\n   * This option affect two drivers:\n   *\n   *   (1) LS driver generates \"index\" handles instead of \"upload\" for paths inside those locations\n   *\n   *   (2) Download driver directly serves content retrieval requests for blobs from listed storages,\n   *       and don't apply any caching for such blobs (i.e. preventing duplication of files for Downloaded\n   *       type handles, making OnDemand and Downloaded handles equivalent)\n   *\n   * */\n  readonly localProjections: LocalStorageProjection[];\n\n  /**\n   * List of virtual storages that will allow homogeneous access to local FSs through LS API.\n   * If undefined, default list will be created.\n   * */\n  readonly virtualLocalStoragesOverride?: VirtualLocalStorageSpec[];\n\n  /** Path to the directory where pframes will spill temporary files and store materialized views */\n  readonly pframesSpillPath: string;\n\n  /**\n   * Path to the directory backing the persistent parquet blob cache. Unlike\n   * {@link pframesSpillPath} this directory is NOT emptied on startup - the cache\n   * (and its lifetime counters) is meant to survive restarts.\n   */\n  readonly parquetCachePath: string;\n};\n\n/** Options required to initialize full set of middle layer driver kit */\nexport type DriverKitOpsSettings = {\n  //\n  // Common\n  //\n\n  readonly logger: MiLogger;\n\n  //\n  // Signer\n  //\n\n  /**\n   * Local secret, that is used to sign and verify different pieces of information\n   * that can be used to access local data, like local paths for ongoing uploads.\n   *\n   * Use {@link MiddleLayer.generateLocalSecret} to generate sufficiently random string.\n   * */\n  readonly localSecret: string;\n\n  //\n  // Blob Driver\n  //\n\n  /**\n   * Settings related to the download driver making operations with blobs. This driver is also used\n   * to download logs when source process terminates and log terns into a blob\n   */\n  readonly blobDriverOps: DownloadDriverOps;\n\n  //\n  // Frontend Driver\n  //\n\n  /** Settings related to the frontend driver that downloads frontends. */\n  readonly frontendDownloadDriverOps: DownloadUrlDriverOps;\n\n  //\n  // Blob To URL Driver\n  //\n\n  readonly downloadBlobToURLDriverOps: DownloadBlobToURLDriverOps;\n\n  //\n  // Upload Driver\n  //\n\n  /**\n   * Settings related to the upload driver that actually performs upload and helps render upload\n   * and indexing progresses from related pl resources.\n   * */\n  readonly uploadDriverOps: UploadDriverOps;\n\n  //\n  // Log streaming ops\n  // (static logs are served via the blob driver)\n  //\n\n  /** Settings related to the streaming log driver */\n  readonly logStreamDriverOps: LogsStreamDriverOps;\n\n  //\n  // LS Driver\n  //\n\n  /**\n   * Callback to access system file open dialog, must be provided by the environment,\n   * to allow for {@link showOpenSingleFileDialog} / {@link showOpenMultipleFilesDialog}\n   * calls from the UI.\n   */\n  readonly openFileDialogCallback: OpenFileDialogCallback;\n\n  //\n  // PFrame Driver\n  //\n\n  /** Settings related to the PFrame driver */\n  readonly pFrameDriverOps: PFrameDriverOps;\n\n  /**\n   * Tuning for the persistent parquet blob cache. Its directory is\n   * {@link DriverKitOpsPaths.parquetCachePath}; this carries only the\n   * size/eviction knobs.\n   */\n  readonly parquetCacheOps: ParquetCacheOps;\n};\n\nexport type DriverKitOps = DriverKitOpsPaths & DriverKitOpsSettings;\n\n/** Some defaults fot MiddleLayerOps. */\nexport const DefaultDriverKitOpsSettings: Pick<\n  DriverKitOpsSettings,\n  | \"logger\"\n  | \"blobDriverOps\"\n  | \"frontendDownloadDriverOps\"\n  | \"downloadBlobToURLDriverOps\"\n  | \"uploadDriverOps\"\n  | \"logStreamDriverOps\"\n  | \"pFrameDriverOps\"\n  | \"parquetCacheOps\"\n> = {\n  logger: new ConsoleLoggerAdapter(),\n  blobDriverOps: {\n    cacheSoftSizeBytes: 8 * 1024 * 1024 * 1024, // 8 GB\n    rangesCacheMaxSizeBytes: 8 * 1024 * 1024 * 1024, // 8 GB\n    nConcurrentDownloads: 10,\n  },\n  frontendDownloadDriverOps: {\n    cacheSoftSizeBytes: 1 * 1024 * 1024 * 1024, // 1 GB\n    withGunzip: true,\n    nConcurrentDownloads: 50,\n  },\n  downloadBlobToURLDriverOps: {\n    cacheSoftSizeBytes: 1 * 1024 * 1024 * 1024, // 1 GB\n    nConcurrentDownloads: 10,\n  },\n  uploadDriverOps: {\n    nConcurrentPartUploads: 10,\n    nConcurrentGetProgresses: 10,\n    pollingInterval: 1000,\n    stopPollingDelay: 1000,\n  },\n  logStreamDriverOps: {\n    nConcurrentGetLogs: 10,\n    pollingInterval: 1000,\n    stopPollingDelay: 1000,\n  },\n  pFrameDriverOps: PFrameDriverOpsDefaults,\n  parquetCacheOps: {\n    maxSizeBytes: 8 * 1024 * 1024 * 1024, // 8 GB\n    admissionFraction: 0.2, // a single file may occupy at most 20% of the budget\n    maxFilesTracked: 50_000, // ghost (previously-evicted) files remembered to guide readmission\n  },\n};\n\nexport function DefaultDriverKitOpsPaths(\n  workDir: string,\n): Pick<\n  DriverKitOpsPaths,\n  | \"blobDownloadPath\"\n  | \"blobDownloadRangesCachePath\"\n  | \"downloadBlobToURLPath\"\n  | \"pframesSpillPath\"\n  | \"parquetCachePath\"\n> {\n  return {\n    blobDownloadPath: path.join(workDir, \"download\"),\n    blobDownloadRangesCachePath: path.join(workDir, \"downloadRangesCache\"),\n    downloadBlobToURLPath: path.join(workDir, \"downloadToURL\"),\n    pframesSpillPath: path.join(workDir, \"pframes\"),\n    parquetCachePath: path.join(workDir, \"parquetCache\"),\n  };\n}\n\n/** Fields with default values are marked as optional here. */\nexport type DriverKitOpsConstructor = Omit<\n  DriverKitOpsSettings,\n  keyof typeof DefaultDriverKitOpsSettings\n> &\n  Partial<typeof DefaultDriverKitOpsSettings> &\n  Omit<DriverKitOpsPaths, keyof ReturnType<typeof DefaultDriverKitOpsPaths>> &\n  Partial<ReturnType<typeof DefaultDriverKitOpsPaths>>;\n\nexport type MiddleLayerOpsPaths = DriverKitOpsPaths & {\n  /** Common root where to put frontend code. */\n  readonly frontendDownloadPath: string;\n\n  /**\n   * Directory holding persisted project tree mirrors, one file per project. Like\n   * {@link DriverKitOpsPaths.parquetCachePath} and unlike the spill directories, it is NOT\n   * emptied on startup: surviving a restart is the entire point. It is pruned instead, see\n   * {@link TreeSnapshotOps.maxSizeBytes}.\n   */\n  readonly treeSnapshotPath: string;\n};\n\n/** Tuning for the persisted project tree mirrors. Their directory is\n *  {@link MiddleLayerOpsPaths.treeSnapshotPath}; this carries the behaviour knobs. */\nexport type TreeSnapshotOps = {\n  /**\n   * Whether project tree mirrors are persisted and restored at all.\n   *\n   * On by default. This is an operational kill switch, for a deployment where the cache\n   * directory turns out to be unwritable or otherwise troublesome, not a rollout gate: the\n   * floor of the feature is current behaviour, since a cache that never hits is a cold open.\n   */\n  readonly enabled: boolean;\n\n  /**\n   * Minimum wall-clock gap between periodic writes for one project.\n   *\n   * Can be generous, because a stale snapshot is less complete rather than wrong: final\n   * resources never change and are never refetched, so this only bounds how much recent work\n   * comes back from the non-final frontier on restore.\n   */\n  readonly writeInterval: number;\n\n  /** Total bytes the snapshot directory may occupy after startup eviction. Needed because a\n   *  heavy project runs to roughly ten megabytes. */\n  readonly maxSizeBytes: number;\n};\n\n/** Debug options for middle layer. */\nexport type MiddleLayerDebugOptions = {\n  /** If true, will dump initial tree state to the file with root resource id as name. */\n  dumpInitialTreeState: boolean;\n};\n\n/** Configuration controlling different aspects of middle layer behaviour. */\nexport type MiddleLayerOpsSettings = DriverKitOpsSettings & {\n  /** Debug options. */\n  readonly debugOps: MiddleLayerDebugOptions;\n\n  /** Contain temporal options controlling how often should pl trees be\n   * synchronized with the pl server. */\n  readonly defaultTreeOptions: TemporalSynchronizedTreeOps;\n\n  /** Defines interval in milliseconds for running periodic project maintenance job.\n   * Project maintenance includes background staging rendering and cached outputs cleanup. */\n  readonly projectRefreshInterval: number;\n\n  /** How often to check for dev block updates */\n  readonly devBlockUpdateRecheckInterval: number;\n\n  /** Prioritize this channel if update is available in this block */\n  readonly preferredUpdateChannel?: string;\n\n  /** Default lifetime applied to a targeted shared envelope at creation, as\n   * `sharedAt + envelopeTtlMs`. Share-with-everybody envelopes never expire\n   * (`expiresAt: null`) and ignore this. */\n  readonly envelopeTtlMs: number;\n\n  /** Settings for persisting project tree mirrors to disk, so reopening a project transfers\n   * what changed rather than the tree again. */\n  readonly treeSnapshotOps: TreeSnapshotOps;\n};\n\nexport type MiddleLayerOps = MiddleLayerOpsSettings & MiddleLayerOpsPaths;\n\n/** Some defaults fot MiddleLayerOps. */\nexport const DefaultMiddleLayerOpsSettings: Pick<\n  MiddleLayerOps,\n  | keyof typeof DefaultDriverKitOpsSettings\n  | \"defaultTreeOptions\"\n  | \"projectRefreshInterval\"\n  | \"devBlockUpdateRecheckInterval\"\n  | \"debugOps\"\n  | \"envelopeTtlMs\"\n  | \"treeSnapshotOps\"\n> = {\n  ...DefaultDriverKitOpsSettings,\n  defaultTreeOptions: {\n    pollingInterval: 200,\n    stopPollingDelay: 2500,\n    initialTreeLoadingTimeout: 100 * 60 * 60 * 1000, // disable timeout for loading project tree (100 hours)\n  },\n  debugOps: {\n    dumpInitialTreeState: false,\n  },\n  devBlockUpdateRecheckInterval: 1000,\n  projectRefreshInterval: 2000,\n  envelopeTtlMs: 14 * 24 * 3600 * 1000, // 14 days\n  treeSnapshotOps: {\n    enabled: true,\n    writeInterval: 5 * 60 * 1000, // 5 minutes\n    maxSizeBytes: 256 * 1024 * 1024, // 256 MB, roughly 25 heavy projects\n  },\n};\n\nexport function DefaultMiddleLayerOpsPaths(\n  workDir: string,\n): Pick<\n  MiddleLayerOpsPaths,\n  keyof ReturnType<typeof DefaultDriverKitOpsPaths> | \"frontendDownloadPath\" | \"treeSnapshotPath\"\n> {\n  return {\n    ...DefaultDriverKitOpsPaths(workDir),\n    frontendDownloadPath: path.join(workDir, \"frontend\"),\n    treeSnapshotPath: path.join(workDir, \"treeSnapshots\"),\n  };\n}\n\nexport type MiddleLayerOpsConstructor = Omit<\n  MiddleLayerOpsSettings,\n  keyof typeof DefaultMiddleLayerOpsSettings\n> &\n  Partial<typeof DefaultMiddleLayerOpsSettings> &\n  Omit<MiddleLayerOpsPaths, keyof Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>> &\n  Partial<Awaited<ReturnType<typeof DefaultMiddleLayerOpsPaths>>>;\n"],"mappings":";;;;;;AAoJA,MAAa,8BAUT;CACF,QAAQ,IAAI,qBAAqB;CACjC,eAAe;EACb,oBAAoB,IAAI,OAAO,OAAO;EACtC,yBAAyB,IAAI,OAAO,OAAO;EAC3C,sBAAsB;CACxB;CACA,2BAA2B;EACzB,oBAAoB,IAAI,OAAO,OAAO;EACtC,YAAY;EACZ,sBAAsB;CACxB;CACA,4BAA4B;EAC1B,oBAAoB,IAAI,OAAO,OAAO;EACtC,sBAAsB;CACxB;CACA,iBAAiB;EACf,wBAAwB;EACxB,0BAA0B;EAC1B,iBAAiB;EACjB,kBAAkB;CACpB;CACA,oBAAoB;EAClB,oBAAoB;EACpB,iBAAiB;EACjB,kBAAkB;CACpB;CACA,iBAAiB;CACjB,iBAAiB;EACf,cAAc,IAAI,OAAO,OAAO;EAChC,mBAAmB;EACnB,iBAAiB;CACnB;AACF;AAEA,SAAgB,yBACd,SAQA;CACA,OAAO;EACL,kBAAkB,KAAK,KAAK,SAAS,UAAU;EAC/C,6BAA6B,KAAK,KAAK,SAAS,qBAAqB;EACrE,uBAAuB,KAAK,KAAK,SAAS,eAAe;EACzD,kBAAkB,KAAK,KAAK,SAAS,SAAS;EAC9C,kBAAkB,KAAK,KAAK,SAAS,cAAc;CACrD;AACF;;AAwFA,MAAa,gCAST;CACF,GAAG;CACH,oBAAoB;EAClB,iBAAiB;EACjB,kBAAkB;EAClB,2BAA2B,MAAW,KAAK;CAC7C;CACA,UAAU,EACR,sBAAsB,MACxB;CACA,+BAA+B;CAC/B,wBAAwB;CACxB,eAAe,MAAU,OAAO;CAChC,iBAAiB;EACf,SAAS;EACT,eAAe,MAAS;EACxB,cAAc,MAAM,OAAO;CAC7B;AACF;AAEA,SAAgB,2BACd,SAIA;CACA,OAAO;EACL,GAAG,yBAAyB,OAAO;EACnC,sBAAsB,KAAK,KAAK,SAAS,UAAU;EACnD,kBAAkB,KAAK,KAAK,SAAS,eAAe;CACtD;AACF"}

package/dist/middle_layer/project.cjs

@@ -44,14 +44,28 @@ var Project = class Project {
 	activeConfigs;
 	refreshLoopResult;
 	abortController = new AbortController();
+	/** Tree change generation as of the snapshot currently on disk, or -1 when this session has
+	* not written one. Compared against the tree's current generation to skip writing a mirror
+	* that has not moved, which is what makes a project left open and idle go quiet. */
+	snapshotGeneration;
+	/** When a snapshot was last attempted, for the periodic write's wall-clock gate.
+	*
+	* Zero, not the construction time, so the first write lands on the first maintenance pass
+	* after the tree has settled rather than a full interval later. Sessions shorter than one
+	* interval are the common case for a desktop app that is quit with a project still open, and
+	* seeding this to now would leave every one of them with nothing on disk. Set on every
+	* attempt, successful or not, so a persistently failing write retries at the interval rather
+	* than on every pass of the loop. */
+	lastSnapshotAt = 0;
 	get destroyed() {
 		return this.abortController.signal.aborted;
 	}
-	constructor(env, id, rid, projectTree) {
+	constructor(env, id, rid, projectTree, restoredFromSnapshot = false) {
 		this.env = env;
 		this.id = id;
 		this.rid = rid;
 		this.projectTree = projectTree;
+		this.snapshotGeneration = restoredFromSnapshot ? 0 : -1;
 		this.overview = require_project_overview.projectOverview(projectTree.entry(), this.navigationStates, env).withPreCalculatedValueTree();
 		this.overviewLight = require_project_overview_light.projectOverviewLight(projectTree.entry()).withPreCalculatedValueTree();
 		this.refreshLoopResult = this.refreshLoop();
@@ -63,6 +77,85 @@ var Project = class Project {
 	get projectLockId() {
 		return "project:" + this.id.toString();
 	}
+	/**
+	* Periodic snapshot write, carried on the maintenance loop rather than a timer of its own.
+	*
+	* Gated on the tree having changed since the last snapshot, so a project left open and idle
+	* writes once and then goes quiet, and on wall clock, so a project changing continuously
+	* writes at most once per interval.
+	*/
+	async maybeWriteSnapshot() {
+		const store = this.env.treeSnapshots;
+		if (store === void 0) return;
+		const generation = this.projectTree.changeGeneration;
+		if (generation === this.snapshotGeneration) return;
+		if (Date.now() - this.lastSnapshotAt < this.env.ops.treeSnapshotOps.writeInterval) return;
+		await this.writeSnapshot(store, generation);
+	}
+	/**
+	* Starts the close-boundary snapshot and returns without waiting for the write.
+	*
+	* On top of the periodic write, since closing is a natural point to persist. Change-gated but
+	* not interval-gated: rewriting a mirror that has not moved is pure waste, but a mirror that
+	* has moved is worth keeping however recently the last write happened.
+	*
+	* The **capture is synchronous and happens here**, before the caller destroys the tree,
+	* because destroying it invalidates it and a later capture would be refused. Only the encode
+	* and the write are deferred: they are up to ten megabytes of work, and project switching
+	* should not wait for them. Deferring is safe only because a capture is a copy rather than a
+	* view of the tree.
+	*
+	* The returned promise never rejects. The caller is expected to keep it so it can be drained
+	* at shutdown, not to await it here.
+	*/
+	snapshotOnClose() {
+		const store = this.env.treeSnapshots;
+		if (store === void 0) return Promise.resolve();
+		const generation = this.projectTree.changeGeneration;
+		if (generation === this.snapshotGeneration) return Promise.resolve();
+		let snapshot;
+		try {
+			snapshot = this.projectTree.capture((0, _milaboratories_pl_client.parseSignedResourceId)(this.rid).signature);
+		} catch (e) {
+			this.env.logger.warn(new Error(`failed to capture tree snapshot for project ${this.id} on close`, { cause: e }));
+			return Promise.resolve();
+		}
+		this.lastSnapshotAt = Date.now();
+		const write = (this.snapshotInFlight ?? Promise.resolve()).then(async () => {
+			if (this.snapshotGeneration >= generation) return;
+			if (await store.write(this.rid, snapshot)) this.snapshotGeneration = generation;
+		});
+		this.snapshotInFlight = write.finally(() => {
+			this.snapshotInFlight = void 0;
+		});
+		return this.snapshotInFlight;
+	}
+	/** In-flight snapshot write, if any. Both triggers can fire close together (the close write
+	*  lands while the loop is mid-write), and encoding ten megabytes twice for the same mirror
+	*  is worth avoiding. */
+	snapshotInFlight;
+	/** Serializes writes, and skips one that the in-flight write has already made redundant. */
+	async writeSnapshot(store, generation) {
+		while (this.snapshotInFlight !== void 0) {
+			await this.snapshotInFlight;
+			if (this.snapshotGeneration >= generation) return;
+		}
+		this.snapshotInFlight = this.captureAndWrite(store, generation).finally(() => {
+			this.snapshotInFlight = void 0;
+		});
+		await this.snapshotInFlight;
+	}
+	/** Captures and writes, never throwing: a snapshot is an optimisation and must not fail
+	*  whatever triggered it. */
+	async captureAndWrite(store, generation) {
+		this.lastSnapshotAt = Date.now();
+		try {
+			const snapshot = this.projectTree.capture((0, _milaboratories_pl_client.parseSignedResourceId)(this.rid).signature);
+			if (await store.write(this.rid, snapshot)) this.snapshotGeneration = generation;
+		} catch (e) {
+			this.env.logger.warn(new Error(`failed to capture tree snapshot for project ${this.id}`, { cause: e }));
+		}
+	}
 	async refreshLoop() {
 		let retryState;
 		while (!this.destroyed) try {
@@ -74,6 +167,7 @@ var Project = class Project {
 			});
 			await this.activeConfigs.getValue();
 			await (0, node_timers_promises.setTimeout)(this.env.ops.projectRefreshInterval, void 0, { signal: this.abortController.signal });
+			await this.maybeWriteSnapshot();
 			const overviewLight = await this.overviewLight.getValue();
 			const existingBlocks = new Set(overviewLight.listOfBlocks);
 			for (const blockId of this.blockComputables.keys()) if (!existingBlocks.has(blockId)) {
@@ -470,12 +564,7 @@ var Project = class Project {
 	static async init(env, id, rid) {
 		await require_migration.applyProjectMigrations(env.pl, rid);
 		await require_project.withProject(env.projectHelper, env.pl, rid, (_) => {}, { name: "init" });
-		const projectTree = await _milaboratories_pl_tree.SynchronizedTreeState.init(env.pl, rid, {
-			...env.ops.defaultTreeOptions,
-			pruning: projectTreePruning(env.logger),
-			fieldFilter: projectTreeFieldFilter(),
-			traverseStopRules: projectTreeTraverseStopRules()
-		}, env.logger);
+		const { tree: projectTree, restored } = await loadProjectTree(env, rid);
 		if (env.ops.debugOps.dumpInitialTreeState) {
 			const state = projectTree.dumpState();
 			state.sort((a, b) => (b.data?.byteLength ?? 0) - (a.data?.byteLength ?? 0));
@@ -483,9 +572,74 @@ var Project = class Project {
 			await node_fs_promises.default.writeFile(`${(0, _milaboratories_pl_client.resourceIdToString)(rid)}.json`, stringifyForDump(state));
 			await node_fs_promises.default.writeFile(`${(0, _milaboratories_pl_client.resourceIdToString)(rid)}.stats.json`, stringifyForDump(stats));
 		}
-		return new Project(env, id, rid, projectTree);
+		return new Project(env, id, rid, projectTree, restored);
 	}
 };
+/**
+* Opens the project tree, seeded from a persisted mirror when there is a usable one.
+*
+* Carries the fail-safe: if the restored tree fails its first refresh on authentication,
+* permission or an inconsistency, the snapshot is deleted and the open is retried cold. Once,
+* and only for that first refresh, so a genuinely dead session still surfaces as itself rather
+* than being masked as a slow open.
+*
+* The fail-safe is what bounds every case the cache key does not cover: a rotated master
+* secret, a revoked grant, a snapshot valid in itself but no longer matching what the backend
+* will serve. Without it, an explicit-root tree propagates the refresh failure rather than
+* healing, so the project would fail to open on every attempt until someone deleted the cache
+* directory by hand.
+*/
+async function loadProjectTree(env, rid) {
+	const treeOps = {
+		...env.ops.defaultTreeOptions,
+		pruning: projectTreePruning(env.logger),
+		fieldFilter: projectTreeFieldFilter(),
+		traverseStopRules: projectTreeTraverseStopRules()
+	};
+	const cold = async () => ({
+		tree: await _milaboratories_pl_tree.SynchronizedTreeState.init(env.pl, rid, treeOps, env.logger),
+		restored: false
+	});
+	const store = env.treeSnapshots;
+	if (store === void 0) return await cold();
+	const snapshot = await store.read(rid);
+	if (!snapshot.ok) {
+		env.logger.info(`project tree opening cold, snapshot miss: ${snapshot.miss}`);
+		return await cold();
+	}
+	try {
+		const tree = await _milaboratories_pl_tree.SynchronizedTreeState.init(env.pl, rid, {
+			...treeOps,
+			restoreFrom: snapshot.tree
+		}, env.logger);
+		const restored = tree.wasRestoredFromSnapshot;
+		if (restored) store.noteRestored();
+		else env.logger.info("project tree opening cold: the snapshot was not applied");
+		return {
+			tree,
+			restored
+		};
+	} catch (e) {
+		env.logger.warn(new Error("restored project tree failed its first refresh, opening cold", { cause: e }));
+		if (isSnapshotFailsafeError(e)) await store.discard(rid);
+		return await cold();
+	}
+}
+/** The failures that implicate the snapshot rather than the link or the session: a rotated
+*  master secret, a revoked grant, or state the tree cannot reconcile. Only these delete the
+*  file; every other failure still falls back to a cold open, it just keeps the file.
+*
+*  The cause chain is walked because a wrapper anywhere between the tree update and here would
+*  otherwise silently disarm the inconsistency arm. `isUnauthenticated` and `isPermissionDenied`
+*  do their own one-level unwrapping. */
+function isSnapshotFailsafeError(e) {
+	if ((0, _milaboratories_pl_client.isUnauthenticated)(e) || (0, _milaboratories_pl_client.isPermissionDenied)(e)) return true;
+	for (let cause = e, depth = 0; cause !== void 0 && depth < 8; depth++) {
+		if (cause instanceof _milaboratories_pl_tree.TreeStateUpdateError) return true;
+		cause = cause?.cause;
+	}
+	return false;
+}
 function projectTreePruning(logger) {
 	return (r) => {
 		if (r.fields.length > 1e3) logger.warn(`resource with excessive field count: type=${r.type.name} id=${r.id} fields=${r.fields.length} names=[${r.fields.slice(0, 10).map((f) => f.name).join(", ")}, ...]`);
@@ -573,6 +727,7 @@ function throwIfMissingServerCapabilities(pl, requiredCapabilities) {
 }
 //#endregion
 exports.Project = Project;
+exports.isSnapshotFailsafeError = isSnapshotFailsafeError;
 exports.projectTreeFieldFilter = projectTreeFieldFilter;
 exports.projectTreePruning = projectTreePruning;
 exports.projectTreeTraverseStopRules = projectTreeTraverseStopRules;