Say what recovering a lost crop store would actually take (#4926)

The previous commit called crops irreplaceable and left it there, which
overstates it: the lab's research pano store keeps the source panoramas
(a 300-pano sample of expired-pano labels found 292/300 for Seattle,
300/300 for Chicago), so sidewalk-panorama-tools' CropRunner could re-cut
them. It is still not a rebuild — a cross-machine batch job over ~700k
labels, producing a tighter, differently framed image, out of a store
this deployment has no contract over — so the tier stands. The docs now
name that path instead of implying there is none.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: jonfroehlich

app/modules/PersistentMediaDirCheck.scala

@@ -80,9 +80,10 @@ object PersistentMediaDirCheck {
 
   val persistentDirs: Seq[PersistentDir] = Seq(
     // A crop is a screenshot of the pano canvas taken in the labeler's browser as the label was placed
-    // (Canvas.saveCanvasScreenshot); nothing regenerates one server-side. The Static API still we fall back to is a
-    // different image, and only exists while the provider still serves that pano — about half the labels on prod
-    // already sit on panos marked expired, where the crop is the only surviving picture of what was labeled.
+    // (Canvas.saveCanvasScreenshot); nothing here rebuilds one, and the Static API still we fall back to is a
+    // different image that only exists while the provider still serves that pano — about half the labels on prod sit
+    // on panos already marked expired. Re-cutting them from the lab's research pano store (sidewalk-panorama-tools
+    // CropRunner) is a cross-machine batch job producing a differently framed image, not a rebuild.
     PersistentDir("cropped.image.directory", "SIDEWALK_IMAGES_DIR", irreplaceable = true),
     // The self-hosted pano store backs up GSV imagery Google has already expired (pano_data.has_backup) — for those
     // panos it is the only copy left anywhere, as unrecoverable as a user upload.

conf/application.conf

@@ -266,8 +266,8 @@ custom.news.ribbon.link = null
 # the write paths.
 
 # Directory for label crops, organized as <dir>/<city-id>/<labelType>/crop_<labelId>.png. Each crop is a screenshot
-# of the pano canvas taken in the labeler's browser as the label was placed, so nothing can rebuild one — and once
-# the pano expires it is the only picture left of what was labeled. Irreplaceable, like the pano and story dirs.
+# of the pano canvas taken in the labeler's browser as the label was placed, and nothing here rebuilds one.
+# Irreplaceable, like the pano and story dirs.
 cropped.image.directory = ".crops"
 cropped.image.directory = ${?SIDEWALK_IMAGES_DIR}
 

docs/deployment-and-stages.md

@@ -290,9 +290,18 @@ outside the build tree** via its environment variable (a variable that is set bu
 |---|---|---|---|
 | `story.media.directory` | `SIDEWALK_STORY_MEDIA_DIR` | User-uploaded story photos (**irreplaceable**) | **App refuses to start** |
 | `pano.images.directory` | `SIDEWALK_PANO_DIR` | Self-hosted pano store — the only copies of GSV imagery Google has expired (**irreplaceable**) | **App refuses to start** |
-| `cropped.image.directory` | `SIDEWALK_IMAGES_DIR` | Label crops — browser captures of the pano as it was labeled, with no second copy (**irreplaceable**) | **App refuses to start** |
+| `cropped.image.directory` | `SIDEWALK_IMAGES_DIR` | Label crops — browser captures of the pano as it was labeled, with no rebuild path in the app (**irreplaceable**) | **App refuses to start** |
 | `share.image.directory` | `SIDEWALK_SHARE_IMAGES_DIR` | Cached social-share previews (regenerable) | Error logged at boot |
 
+Crops sit in the fatal tier because nothing in this app regenerates one: `/saveImage` stores a canvas screenshot the
+labeler's browser took as the label was placed, and the Street View Static still used as a fallback elsewhere is a
+different, smaller image of a pano the provider must still serve — roughly half the labels on prod sit on panos
+already marked expired. They are not *unrecoverable* in the absolute sense: the lab's research pano store keeps the
+source panoramas (a 300-pano sample of expired-pano labels found 292/300 for Seattle and 300/300 for Chicago), so
+[`sidewalk-panorama-tools`](https://github.com/ProjectSidewalk/sidewalk-panorama-tools)' `CropRunner.py` could re-cut
+them. That is a cross-machine batch job over ~700k labels, producing a tighter, differently framed crop, and it
+depends on a store outside this deployment — not something to trade a boot check for.
+
 `PersistentMediaDirCheck` enforces this at boot in **prod mode** — what every staged binary runs in — so it covers
 every deployed stage *and* a staged binary run by hand (export the four variables to `/tmp` paths for that; CI's
 `e2e-smoke` job does exactly this). It deliberately does not key on `ENV_TYPE`: that variable arrives through the