Architecture status and compatibility
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision 023dd4bd1eeedef249fe5f22003fa3d67333812c. Application and Runner release compatibility: unverified.
What this guide covers
Starts at the Vanilla Library UI action and follows one Runner-owned session through safe grants, fast local browsing, destination-first comparison, source discovery, approved copy-and-verify work, local-cache refresh, progress reporting and clean shutdown. The 2 GiB tier is local disk cache on the PC, not process memory. Vanilla observes progress but never manages Bean cache or destination files directly.
Before the request
A compatible Runner can open safe grants for the selected source, one connected destination, durable state and the bounded local rendition-cache root. Destination writes additionally require a valid approved replica plan.
- Input
- Application session lifetime, opaque source/catalogue identity, connected destination identity, approved sync policy, visible request generations and the exact grid rendition recipe.
- Output
- Immediate local browsing or an explicit library failure, plus destination/source comparison, approved copy progress, refreshed local-cache progress and honest sync-paused outcomes in the Activity Bar.
- What completion means
- Foreground readiness means visible requests can be served or refused honestly without waiting for sync. Synchronization completes only when the approved durable job verifies its destination results and the local catalogue/cache checkpoint is refreshed; discovery alone is not completion.
Follow the workflow
Open Library
The workflow begins when a person opens Library or returns to it. Vanilla requests the current catalogue page, the visible previews and session activity.
Implementation evidence
flutter_photovault/lib/presentation/library_screen.dart · Library entry; flutter_photovault/lib/data/runner/loom_runner_transport_batch_helpers.dart · readBatch
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Start or reuse Runner
Use the compatible product Runner. It owns session lifetime and grants access only to the selected source, connected destination, durable state and bounded cache roots.
Implementation evidence
photovault_runner/src/RequestTransport.swift · runRequestTransport; Confinement.swift · actualDataConfinement
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Start parallel work
The Runner starts three coordinated activities. Visible browsing has priority; destination/source checks use bounded background work; the Activity Bar observes both without becoming a worker.
Implementation evidence
photovault_runner/src/RequestTransport.swift · session ownership and routed work
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Local preview cache
Open the cache for the matching opaque library and catalogue identity. Cache files are truth; the manifest is a rebuildable checkpoint. This single cache store serves foreground reads and later receives bounded refreshes.
Implementation evidence
bean/catalog_lifecycle.py · CatalogLifecycle.prepare; bean/thumbnail_store.py · LocalRenditionCache
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Connected destination drive
Inspect one explicitly connected destination first. Its verified inventory becomes the comparison baseline. A missing or disconnected destination is an honest sync-unavailable outcome, not an empty destination.
Implementation evidence
bean/actual_library.py · replica.plan destinationHandle; bean/replica_jobs.py · durable replica state
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Update Activity Bar
The Work Tray / Activity Bar observes durable phase and count updates such as “Checking destination”, “Found 15 new photos” and “Copying 2 of 15”. Use “Downloading” only when the selected provider is actually downloading.
Implementation evidence
flutter_photovault/lib/presentation/work_tray.dart; work_tray/runner_activity_progress.dart
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Show visible photos first
Serve the visible grid from the one local cache immediately and render the exact requested rendition. Merged Vanilla currently asks for 256 px JPEG, while the lifecycle candidate prewarms PNG; until one recipe is approved and shared, the backfill cannot guarantee a hit for the public client. New screen requests replace stale visible work and preempt lower-priority scans.
Implementation evidence
bean/thumbnail_prewarm.py · Prewarmer.schedule; flutter_photovault/lib/data/runner/loom_runner_transport_batch_helpers.dart · readBatch variant
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Compare source with destination
After the destination baseline is known, scan the granted source for stable identities that are not yet verified at the destination. Run bounded batches behind foreground viewport work and report the discovered count.
Implementation evidence
bean/location_scans.py · bounded source scan; bean/actual_library.py · replica planning
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
New photos found?
Zero new identities can refresh the local checkpoint without starting a copy. A positive count proceeds to the explicit approval decision.
Implementation evidence
bean/actual_library.py · replica plan counts
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Approved sync plan?
A copy may start only when the current plan, digest, destination and approver still match. Discovery alone does not grant destination write authority.
Implementation evidence
bean/replica_jobs.py · planDigest and approvedBy checks
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Copy and verify new photos
Create or resume the approved durable replica job. Copy, read back, verify and record each result while publishing phase and count updates.
Implementation evidence
bean/replica_jobs.py · approved async job; bean/actual_library.py · verified writes
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Update local cache
After verified destination results—or immediately when nothing is new—update the same local cache and newest-first preview target. Keep up to 5,000 likely previews only within the shared 2 GiB disk limit, then save advisory progress.
Implementation evidence
bean/catalog_lifecycle.py · prepare/checkpoint; bean/thumbnail_prewarm.py · schedule_backfill
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Explain why sync paused
Keep local browsing available while the Activity Bar names the sync problem. Do not copy when the destination is disconnected, the plan changed or approval is missing.
Implementation evidence
bean/replica_jobs.py · named refusal/unavailable outcomes; Vanilla Work Tray error state
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Settle session work
Join the visible and background outcomes without making one falsely depend on the other. Local browsing may be ready while synchronization is paused or still running.
Implementation evidence
photovault_runner/src/RequestTransport.swift · session stop and observation boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Close or resume later
On app close, idle expiry or an identity change, close background work and the engine session. The next compatible session reuses verified job state and recomputes cache progress from files.
Implementation evidence
photovault_runner/src/RequestTransport.swift · stop/idle lifecycle; bean/operations.py · close
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Worked example
Open Library while 15 new photos are waiting
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
Starting point
{
"visibleRequests": 39,
"localCache": "available",
"destination": "connected",
"approval": "current"
}Outcome
{
"foreground": "visible photos served first",
"synchronization": "copying 2 of 15",
"cacheRefresh": "after verified results",
"activity": "Copying 2 of 15"
}Code and invocation
Use the supported Runner entry point with a disposable fixture. No personal library is used.
{
"title": "Open Library while 15 new photos are waiting",
"before": {
"visibleRequests": 39,
"localCache": "available",
"destination": "connected",
"approval": "current"
},
"after": {
"foreground": "visible photos served first",
"synchronization": "copying 2 of 15",
"cacheRefresh": "after verified results",
"activity": "Copying 2 of 15"
},
"session": {
"libraryKey": "opaque-library-key",
"catalogueRevision": "fixture-rev-7"
},
"localCache": {
"kind": "disk",
"byteCap": "2 GiB",
"targetUpTo": 5000,
"publicGridRequest": {
"maxPixelSize": 256,
"format": "jpeg"
},
"candidateBackfillKey": {
"maxPixelSize": 256,
"format": "png"
},
"recipeAlignment": "mismatch — approval and implementation required"
},
"parallel": [
{
"call": "serve-visible",
"visible": 39
},
{
"call": "inspect-destination",
"destination": "approved-destination-handle"
},
{
"call": "scan-source-after-baseline",
"found": 15
}
],
"sync": {
"approval": "existing plan + digest + approver",
"phase": "copying",
"done": 2,
"total": 15
},
"activity": "Copying 2 of 15",
"restart": {
"manifest": "advisory",
"cacheFiles": "ground truth"
}
}Source: photovault_runner/src/RequestTransport.swift; bean/catalog_lifecycle.py; bean/thumbnail_prewarm.py; flutter_photovault/lib/data/runner/loom_runner_transport_batch_helpers.dart
Diagnose an unexpected result
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Library opens as empty after a grant failure | Incorrect success state | Show unavailable; do not call it empty | Runner session outcome |
| Warm cache still renders slowly | Public request and backfill keys differ | Public main requests JPEG; the lifecycle candidate warms PNG. Approve and implement one exact recipe before claiming cache hits. | Vanilla request + Bean backfill key |
| Destination check reports empty when disconnected | Sync truth failure | Show destination unavailable and keep local browsing separate | Destination grant and replica state |
| New photos copy without approval | Authority failure | Stop the job; require the current plan digest and approver | Replica approval boundary |
| Activity Bar says downloading for a local copy | Misleading phase label | Use provider-specific verb; default to copying | Runner progress mapping |
| First paint competes with scanning | Admission failure | Pause bounded scans for active or queued viewport work | Prewarmer activity state |
| Manifest counts disagree with files | Advisory checkpoint is stale | Rescan files; do not delete good entries | CatalogLifecycle.prepare |
Affected code
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine 023dd4bd1eeedef249fe5f22003fa3d67333812c | photovault_runner/src/RequestTransport.swift | runRequestTransport and session stop/idle handling | Runner lifecycle owner | current public source |
| bean-engine 9838b6bc701937d8d6992076f7af9e0761131fc8 | bean/catalog_lifecycle.py | CatalogLifecycle | unmerged cache lifecycle candidate only | candidate source and synthetic tests on current public main |
| bean-engine 9838b6bc701937d8d6992076f7af9e0761131fc8 | bean/thumbnail_prewarm.py | Prewarmer | foreground/cache-backfill admission only | candidate source and synthetic tests on current public main |
| bean-engine 9838b6bc701937d8d6992076f7af9e0761131fc8 | tests/test_catalog_lifecycle_cache.py | catalogue lifecycle fixture suite | focused verification of the integration candidate | 14 focused synthetic tests passed; real libraries and mounted destinations were not used |
| bean-engine 023dd4bd1eeedef249fe5f22003fa3d67333812c | bean/replica_jobs.py | approved durable replica execution | existing copy and progress primitive, not lifecycle orchestration | current source |
| bean-engine 023dd4bd1eeedef249fe5f22003fa3d67333812c | bean/location_scans.py | bounded source scan | existing discovery primitive, not lifecycle orchestration | current source |
| vanilla 1acb3c994c711621139a0f58ea2da9e92e2e0a6d | flutter_photovault/lib/presentation/work_tray/runner_activity_progress.dart | runnerProgressLineText | existing Activity Bar renderer | current source |
| vanilla 1acb3c994c711621139a0f58ea2da9e92e2e0a6d | flutter_photovault/lib/data/runner/loom_runner_transport_batch_helpers.dart | readBatch thumbnail variant | foreground consumer recipe | merged public source explicitly requests JPEG at 256 px |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
Dependency review
| Workflow | Relationship | Review when |
|---|---|---|
| runner.runtime.compatibility | permits reuse only for the compatible product/Runner identity | Runner identity, version or protocol compatibility changes |
| engine.media.preview | defines the exact rendition key and cache/fallback semantics | preview size, format, generation or origin semantics change |
| memory.workspace.catalogue | defines catalogue identity, projection and offline/online truth | catalogue revision or reconciliation semantics change |
| memory.destination.storage | defines the connected destination and verified inventory baseline | destination identity, mount or inventory semantics change |
| memory.copy.backup | owns plan approval, copy and verification semantics | replica plan, approval, copy or verification changes |
| runner.route.progress | publishes durable sync phases and counts | progress schema or phase vocabulary changes |
| ui.photo.jobs | renders synchronization and cache activity in the Activity Bar | activity grouping, labels, counts or error presentation changes |
| ui.photo.browse | supplies viewport demand and installed visual/performance acceptance | grid recipe, first-paint budget or visible failure state changes |
Try the fixture checks
Before you start
Use the inspected Bean checkout and its supported Python environment with dependencies installed. These tests create disposable fixtures; they do not launch the installed app or operate on the personal library.
Run the existing tests
python3 -m pytest -q -p no:cacheprovider tests/test_catalog_lifecycle_cache.py tests/test_109_durable_state.py flutter_photovault/test/runner/loom_display_rendition_test.dartInspect what the check proves
Synthetic lifecycle tests prove isolated cache manifests, cross-process checkpoint coordination, target-under-byte-cap semantics, metadata-only presence checks, viewport-first admission, honest failed-item progress and restart recomputation for integration 9838b6b. Existing replica-job code and tests provide approved plan, scan/copy/verify phases and durable count semantics. Existing Vanilla code renders Runner job titles, counts and ETA in the Work Tray.
Expected: pytest reports passing tests, with no failure or error. Skipped tests or a missing dependency do not establish the skipped behavior.
Outside this check: No test or released pairing proves the proposed destination-first orchestration, its cache-refresh handoff or cache-lifecycle publication in the Activity Bar. Integration 9838b6b is unmerged and cannot be released from the public export without source-first private handback. Its PNG backfill does not match merged Vanilla main's JPEG request. Existing evidence also does not prove installed launch latency, a guaranteed 5,000 retained renditions or real-library synchronization safety.
Implementation and intended direction
Observed in source. Current Bean main already has Runner-owned request sessions, destination planning and approved replica jobs with durable scan/copy/verify progress, a bounded 2 GiB local rendition cache and viewport prewarming. Vanilla already has a Work Tray / Activity Bar that renders Runner job titles, phase counts and ETA. Unmerged Bean lifecycle integration 9838b6b applies cleanly on current public Bean main and adds per-library advisory manifests, cross-process coordination, foreground-admitted presence scans and newest-first cache backfill of up to 5,000 items within the byte cap. Merged Vanilla main 1acb3c994c711621139a0f58ea2da9e92e2e0a6d explicitly requests JPEG for grid renditions at 256 px, while the independently reviewed but unmerged b17b3da candidate omits format and would use Bean's PNG default. The lifecycle integration currently prewarms PNG.
Limits and remaining work. No current implementation orchestrates destination-first comparison, source discovery, approved replica execution and local-cache refresh as one Runner session. Cache scan/backfill also does not publish lifecycle activity to the existing Activity Bar. The Bean lifecycle integration remains unmerged and its 256 px PNG backfill does not match merged Vanilla main's explicit 256 px JPEG request. The complete design still needs one approved cross-repository rendition recipe, an approved orchestration contract, source-first private handback and public export, UI activity mapping, the declared merge gates and installed cold/warm/reopen and sync evidence.
What to verify
- Every visual branch reaches a named outcome.
- Missing implementation remains visible and is never presented as shipped.
- Affected source and dependent workflows are named for change review.
Named test evidence
tests/test_catalog_lifecycle_cache.pytests/test_109_durable_state.pyflutter_photovault/test/runner/loom_display_rendition_test.dart
Connected features
Back to the architecture map · Authoring guidance is maintained in the repository template.