pn0 decouple stats from album internals

Stats reached directly into album-module internals: the private global
ALBUM_VIEW_PAGE_BY_PHOTO and the EXIF cache reader
cached_photo_identify_output. Introduce a clean boundary, behaviour and
generated HTML byte-identical.

- Promote the EXIF identify cache primitive (cached_photo_identify_output
  plus its private helpers photo_cache_signature and
  print_cached_photo_identify_output) out of album-metadata.source.sh into
  a new shared src/lib/metadata-cache.source.sh, sourced before both album
  and stats (right after metadata-label in LIB_SOURCES). It is a low-level
  metadata primitive used by both consumers, so it no longer belongs to
  album internals. Signature/behaviour unchanged.
- Add album_view_page_for_photo accessor in album-render.source.sh as the
  documented public API; keep ALBUM_VIEW_PAGE_BY_PHOTO as the album's
  private backing store. stats-filter-album.source.sh now calls the
  accessor instead of indexing the global, so a change to album page
  naming/caching stays contained in the album module.
- Add test_album_stats_decoupling_boundary asserting the accessor returns
  the backing-store value and that the assembled bin/shuriken keeps the
  cache primitive in the shared module and no longer indexes the global
  from the stats filter section. Existing stats/album tests unchanged.

Verified: 3-image fixture (STATS_PAGE=yes, fixed seed) diff -r of stashed
original vs new build is byte-identical across all 47 dist files (only the
inherent generated_at timestamp normalized). just test, just shellcheck,
just check-generated and git diff --check all pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 21 insertions, 6 deletions

diff --git a/src/lib/album-render.source.sh b/src/lib/album-render.source.sh
index 9bae930..e5817f3 100644
--- a/src/lib/album-render.source.sh
+++ b/src/lib/album-render.source.sh
@@ -1,10 +1,24 @@
 # Maps each album photo filename to its view-page basename ("<page>-<preview>")
-# as assigned during render_album_pages. The stats filter mini-albums read this
-# so each view page can link "Details" to the album's own details page for the
-# photo. Declared globally so it always exists for callers even when no album
-# was rendered.
+# as assigned during render_album_pages. Declared globally so it always exists
+# for the accessor even when no album was rendered.
+#
+# This is the album module's PRIVATE backing store (task pn0). Outside callers
+# must NOT index it directly: use the album_view_page_for_photo accessor below.
+# Keeping the map private behind a documented function decouples consumers (the
+# stats filter mini-albums) from how the album internally names or caches view
+# pages, so a change to the page-naming scheme stays contained in this module.
 declare -gA ALBUM_VIEW_PAGE_BY_PHOTO=()
 
+# Public album API (task pn0): return the view-page basename for a photo, or the
+# empty string when the photo was not rendered into the album. The stats filter
+# mini-albums call this to link each photo's "Details" to the album's own
+# details page, instead of reaching into ALBUM_VIEW_PAGE_BY_PHOTO directly.
+album_view_page_for_photo() {
+    local -r photo="$1"; shift
+
+    printf '%s' "${ALBUM_VIEW_PAGE_BY_PHOTO[$photo]:-}"
+}
+
 album_photo_files() {
     local -r photos_dir="$1"; shift
 
@@ -616,8 +630,9 @@ _album_record_view_photo() {
         "$pids_name" "$statuses_name" "$labels_name" "$failed_name"
     record_rendered_view_page "$view_pages_name" "$last_views_name" \
         "$page_num" "$preview_num"
-    # Read later by the stats filter mini-albums (render_filter_pages) for
-    # their Details links; shellcheck cannot see that cross-function use.
+    # Read later through the album_view_page_for_photo accessor (e.g. by the
+    # stats filter mini-albums for their Details links); shellcheck cannot see
+    # that cross-function use.
     # shellcheck disable=SC2034
     ALBUM_VIEW_PAGE_BY_PHOTO["$photo"]="$page_num-$preview_num"
 }