Fresh read variants that await a server round-trip (closes #75)

Adds Library.fresh(): forces a refresh, awaits its completion and persist, then returns the albums/photos/timeline read namespaces now reflecting a completed server round trip — the caller awaits and is guaranteed current at resolve. Default reads and the background loop are unchanged (immediate-from-cache). Concurrent fresh reads coalesce to one in-flight refresh; a fresh read whose refresh fails rejects rather than answering stale. The CLI adopts fresh reads separately (#52).

Model: opus-4-8

src/library/index.ts

@@ -6,10 +6,17 @@
 // existing copy loaded, that first refresh runs in the background and `open()`
 // returns as soon as the cached data is ready to serve — a slow or unreachable
 // server no longer stalls opening. A background timer then refreshes every
-// `refreshIntervalSeconds`. Every read is answered from RAM — no read touches
-// the network. There is deliberately no `sync()`, no `refresh()`, no
-// `serverReachable` flag, and no "before each read" mode (design #36): the
-// only ways state changes are the refreshes above.
+// `refreshIntervalSeconds`. Every default read is answered from RAM — no
+// default read touches the network. There is deliberately no `sync()`, no
+// `refresh()`, no `serverReachable` flag, and no "before each read" mode
+// (design #36).
+//
+// `fresh()` is the one exception (issue #75, an owner amendment to #36): it
+// forces a refresh, awaits it, and only then hands back the read namespaces, so
+// a caller that needs server-current data can ask for it. Concurrent `fresh()`
+// calls coalesce onto one in-flight refresh, and a refresh that fails rejects
+// the caller (the default reads stay silent and serve the last good copy). The
+// default methods and the background loop are unchanged.
 //
 // A refresh stages all of its network work first and only mutates the store
 // once every fetch has succeeded. A refresh that fails partway therefore never
@@ -40,6 +47,7 @@ import {
     type AlbumsAPI,
     type PhotosAPI,
     type TimelineAPI,
+    type FreshReads,
 } from "./read.js";
 import {
     ContentCache,
@@ -57,6 +65,7 @@ export {
     type AlbumsAPI,
     type PhotosAPI,
     type TimelineAPI,
+    type FreshReads,
     type PhotoFilter,
     type TimelineGroup,
     type GroupBy,
@@ -250,7 +259,12 @@ export class Library {
     private readonly precache?: Precache;
 
     private timer?: ReturnType<typeof setTimeout>;
-    private refreshing = false;
+    // The in-flight refresh cycle, or undefined when none runs. One slot serves
+    // both paths: the background loop skips when it is set, and a fresh read
+    // (issue #75) coalesces onto it or starts one. The promise carries the
+    // cycle's real outcome (it rejects on failure); the background loop ignores
+    // that, a fresh read propagates it.
+    private cycle?: Promise<void>;
     // Guards the ML fetch pass so a slow backfill never runs twice at once; a
     // refresh whose pass is still running kicks nothing new.
     private mlFetching = false;
@@ -484,6 +498,21 @@ export class Library {
         };
     }
 
+    // Fresh reads (issue #75, owner amendment to design #36). Force a refresh,
+    // wait for it to complete and persist, then hand back the same
+    // `albums`/`photos`/`timeline` namespaces — now guaranteed to reflect a
+    // completed server round-trip. Concurrent calls coalesce onto one refresh;
+    // a refresh that fails rejects here, where the default namespaces would
+    // instead stay silent and serve the last good copy.
+    async fresh(): Promise<FreshReads> {
+        await this.refreshNow();
+        return {
+            albums: this.albums,
+            photos: this.photos,
+            timeline: this.timeline,
+        };
+    }
+
     // Back up every in-scope file to `downloadDirectory` in the historical
     // on-disk layout, with a durable failure ledger (issue #51). Refreshes
     // first, fetches pending originals (and optional thumbnails) through the
@@ -543,11 +572,48 @@ export class Library {
         this.timer.unref?.();
     }
 
-    // One refresh cycle, guarded so a failure never escapes and overlapping
-    // cycles never run. Errors are reported, not thrown.
-    private async runRefresh(): Promise<void> {
-        if (this.closed || this.refreshing) return;
-        this.refreshing = true;
+    // The background loop's refresh: run a cycle unless one is already in flight
+    // (or the library is closed), and never let a failure escape — the
+    // background path reports errors through `status()`/`onProgress`, it does
+    // not throw. Resolves once the cycle it started (or skipped past) settles.
+    private runRefresh(): Promise<void> {
+        if (this.closed || this.cycle) return Promise.resolve();
+        return this.startCycle().catch(() => {});
+    }
+
+    // A fresh read's refresh (issue #75): force a cycle and await it, rejecting
+    // if it fails. Concurrent fresh reads coalesce onto the one in-flight cycle
+    // — the background loop's included — so they never fan out into redundant
+    // server round-trips.
+    private refreshNow(): Promise<void> {
+        if (this.closed) {
+            return Promise.reject(new Error("the library is closed"));
+        }
+        return this.cycle ?? this.startCycle();
+    }
+
+    // Start one refresh cycle and record it as the in-flight cycle so every
+    // caller coalesces onto it. The returned promise carries the cycle's real
+    // outcome; each caller attaches the handling its own path needs, and the
+    // slot is cleared once the cycle settles.
+    private startCycle(): Promise<void> {
+        const cycle = this.refreshCycle();
+        this.cycle = cycle;
+        void cycle.then(
+            () => {
+                if (this.cycle === cycle) this.cycle = undefined;
+            },
+            () => {
+                if (this.cycle === cycle) this.cycle = undefined;
+            },
+        );
+        return cycle;
+    }
+
+    // One refresh cycle: the network fetch and commit, wrapped in the progress
+    // events and status bookkeeping. Throws when the refresh fails so a fresh
+    // read can reject; `runRefresh` swallows that throw for the background loop.
+    private async refreshCycle(): Promise<void> {
         this.emit({ operation: "refresh", status: "started" });
         try {
             await this.refreshOnce();
@@ -563,8 +629,7 @@ export class Library {
             const error = err instanceof Error ? err.message : String(err);
             this.lastError = error;
             this.emit({ operation: "refresh", status: "failed", error });
-        } finally {
-            this.refreshing = false;
+            throw err;
         }
     }
 

src/library/read.ts

@@ -193,6 +193,15 @@ export interface TimelineAPI {
     groups(args: { groupBy: GroupBy; filter?: PhotoFilter }): TimelineGroup[];
 }
 
+// The surface `Library.fresh()` resolves to (issue #75). It is the same three
+// read namespaces as the default `albums`/`photos`/`timeline`, handed back only
+// after a forced refresh has brought the local copy current.
+export interface FreshReads {
+    albums: AlbumsAPI;
+    photos: PhotosAPI;
+    timeline: TimelineAPI;
+}
+
 export const makeAlbumsAPI = (
     derive: () => DerivedRecords,
     content?: PhotoContent,