Save path ./photos/YYYY/YYYY-MM/YYYY-MM-DD/YYYY-MM-DD.fileID.ext; download() from the cache first (closes #143)

Originals are saved at `{downloadDirectory}/YYYY/YYYY-MM/YYYY-MM-DD/YYYY-MM-DD.{fileID}{ext}`. The date is the photo's `takenAt` in local time, and `downloadDirectory` defaults to `./photos`, resolved when the library opens. The old `originals/` layout is gone.

`photo.download()` writes the original to `savePath`. It copies from the cache when the cache holds the original, and fetches otherwise. `lib.backup()` uses the same path and rule, and every album in `collections/` links to it. `isLocal` is true only when the original is at `savePath`.

For a file in several albums, one rule picks the copy everything uses: the most recently synced, with the lowest album ID breaking a tie.

Model: opus-5-5

src/library/index.ts

@@ -27,7 +27,7 @@
 // never masked by a subsequent empty refresh.
 
 import { rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import envPaths from "env-paths";
 
 import { MetadataStore } from "./store.js";
@@ -49,9 +49,12 @@ import {
     type PhotosAPI,
     type TimelineAPI,
     type FreshReads,
+    type SavePathLookup,
 } from "./read.js";
 import {
     ContentCache,
+    savePath,
+    storedAtSavePath,
     type ContentSource,
     type ThumbnailsAPI,
     type EnsureOptions,
@@ -70,6 +73,7 @@ export {
     type PhotoFilter,
     type TimelineGroup,
     type GroupBy,
+    type SavePathLookup,
 } from "./read.js";
 export {
     type ContentSource,
@@ -169,8 +173,10 @@ export interface LibraryOptions {
     // Where `metadata.json` lives. Defaults to the env-paths cache directory
     // plus the user id, so each account has its own cache.
     cacheDirectory?: string;
-    // Persistent backup destination. The refresh loop does not use it; the
-    // content cache treats an original already stored there as present.
+    // The root of every photo's save path, where `Photo.download()` and
+    // `lib.backup()` put originals. Defaults to `photos` in the working
+    // directory at open. The content cache treats an original already stored
+    // at its save path as present.
     downloadDirectory?: string;
     refreshIntervalSeconds?: number;
     onProgress?: RefreshProgressCallback;
@@ -234,7 +240,7 @@ export interface LibraryStatus {
 
 export class Library {
     readonly cacheDirectory: string;
-    readonly downloadDirectory?: string;
+    readonly downloadDirectory: string;
 
     // The in-process read surface (issue #44). Each namespace answers
     // synchronously from the live record projection; no read touches the
@@ -296,7 +302,7 @@ export class Library {
         store: MetadataStore;
         userID: number;
         cacheDirectory: string;
-        downloadDirectory?: string;
+        downloadDirectory: string;
         intervalMs: number;
         onProgress?: RefreshProgressCallback;
         pools: RequestPools;
@@ -320,8 +326,14 @@ export class Library {
         // The read namespaces derive fresh from the store on each call, so they
         // always reflect the latest refresh.
         const derive = (): DerivedRecords => this.deriveNow();
-        this.albums = makeAlbumsAPI(derive, this.cache);
-        this.photos = makePhotosAPI(derive, this.cache);
+        const root = this.downloadDirectory;
+        const saves: SavePathLookup = {
+            savePath: (file) =>
+                storedAtSavePath(root, file)?.path ?? savePath(root, file),
+            isLocal: (file) => storedAtSavePath(root, file) !== undefined,
+        };
+        this.albums = makeAlbumsAPI(derive, saves, this.cache);
+        this.photos = makePhotosAPI(derive, saves, this.cache);
         this.timeline = makeTimelineAPI(derive);
         this.thumbnails = {
             ensure: (opts: EnsureOptions): Promise<EnsureResult[]> => {
@@ -350,6 +362,13 @@ export class Library {
         const { userID } = opts.client.whoami();
         const cacheDirectory =
             opts.cacheDirectory ?? defaultCacheDirectory(userID);
+        if (opts.downloadDirectory === "") {
+            throw new Error(
+                "library: downloadDirectory is empty (leave it out to save " +
+                    "under photos/ in the working directory)",
+            );
+        }
+        const downloadDirectory = opts.downloadDirectory ?? resolve("photos");
         const metadataPath = join(cacheDirectory, "metadata.json");
         let store = await MetadataStore.load(metadataPath);
         // A cache directory given explicitly can hold another account's cache.
@@ -404,7 +423,7 @@ export class Library {
                 pools,
                 source,
                 cacheDirectory,
-                downloadDirectory: opts.downloadDirectory,
+                downloadDirectory,
                 getFile: (fileID) => store.getFileByID(fileID),
                 cacheOriginalsMaxBytes: opts.cacheOriginalsMaxBytes,
                 freeBelowBytes: opts.freeBelowBytes,
@@ -426,7 +445,7 @@ export class Library {
             store,
             userID,
             cacheDirectory,
-            downloadDirectory: opts.downloadDirectory,
+            downloadDirectory,
             intervalMs,
             onProgress: opts.onProgress,
             pools,
@@ -470,9 +489,10 @@ export class Library {
         return this.store.getFile(collectionID, fileID);
     }
 
-    // Any membership of a file, addressed by file id alone. A file's own
-    // metadata (title, creationTime) is identical across the collections it
-    // belongs to, so this serves the point commands that hold only a fileID.
+    // The membership of a file its record is read from, addressed by file id
+    // alone. A file's own metadata (title, creationTime) is identical across
+    // the collections it belongs to, so this serves the point commands that
+    // hold only a fileID.
     getFileByID(fileID: number): EnteFile | undefined {
         return this.store.getFileByID(fileID);
     }
@@ -543,27 +563,20 @@ export class Library {
         };
     }
 
-    // Back up every in-scope file to `downloadDirectory` in the historical
-    // on-disk layout, with a durable failure ledger (issue #51). Waits for a
-    // completed refresh first, as `fresh()` does, joining one already running,
-    // and rejects before touching any file when it fails. Then fetches pending
-    // originals (and optional thumbnails) through the content cache and pools,
-    // and rebuilds the derived symlink/JSON views from the model. Throws before
-    // any network work when no download directory is available or no content
-    // cache backs the originals it must fetch.
+    // Back up every in-scope file to `opts.downloadDirectory`, or else the
+    // library's, each original at its save path, with a durable failure
+    // ledger (issue #51). Waits for a completed refresh first, as `fresh()`
+    // does, joining one already running, and rejects before touching any file
+    // when it fails. Then puts pending originals at their save paths as
+    // `Photo.download()` does (and optional thumbnails) through the content
+    // cache and pools, and rebuilds the derived symlink/JSON views from the
+    // model. Throws before any network work when no content cache backs the
+    // originals it must fetch.
     backup(opts?: BackupOptions): Promise<BackupResult> {
         const downloadDirectory =
             opts?.downloadDirectory ?? this.downloadDirectory;
         const includeOriginals = opts?.includeOriginals ?? true;
         const includeThumbnails = opts?.includeThumbnails ?? false;
-        if (!downloadDirectory) {
-            return Promise.reject(
-                new Error(
-                    "backup requires a downloadDirectory (pass one to " +
-                        "backup() or open the library with one)",
-                ),
-            );
-        }
         if ((includeOriginals || includeThumbnails) && !this.cache) {
             return Promise.reject(
                 new Error(