Runner · Runtime & compatibility
Keeps one application session and its bounded catalogue and preview working set ready across safe restarts.
Keeps one application session and its bounded catalogue and preview working set ready across safe restarts.
runner.runtime.session-lifecycle
Opening Library starts two coordinated paths. The foreground path serves visible photos from a bounded local disk cache. At lower priority, the Runner checks an approved connected destination, compares the source, copies verified new photos under the existing approval policy, and refreshes the local cache while the Activity Bar reports progress.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and data boundaries for the Library session.
Foreground browsing and lower-priority synchronization shown as coordinated parallel paths.
Pause, restart, recovery and shutdown states for the Runner-owned session.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision 023dd4bd1eeedef249fe5f22003fa3d67333812c. Application and Runner release compatibility: unverified.
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.
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.
The workflow begins when a person opens Library or returns to it. Vanilla requests the current catalogue page, the visible previews and session activity.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Zero new identities can refresh the local checkpoint without starting a copy. A positive count proceeds to the explicit approval decision.
bean/actual_library.py · replica plan counts
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A copy may start only when the current plan, digest, destination and approver still match. Discovery alone does not grant destination write authority.
bean/replica_jobs.py · planDigest and approvedBy checks
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Create or resume the approved durable replica job. Copy, read back, verify and record each result while publishing phase and count updates.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"visibleRequests": 39,
"localCache": "available",
"destination": "connected",
"approval": "current"
}{
"foreground": "visible photos served first",
"synchronization": "copying 2 of 15",
"cacheRefresh": "after verified results",
"activity": "Copying 2 of 15"
}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
| 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 |
| 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.
| 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 |
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.
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.dartSynthetic 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.
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.
tests/test_catalog_lifecycle_cache.pytests/test_109_durable_state.pyflutter_photovault/test/runner/loom_display_rendition_test.dartBack to the architecture map · Authoring guidance is maintained in the repository template.
Collect durable receipts and evidence so a person can see what changed and why.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Activity history.
How completed work leaves an auditable history workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers engine activity evidence across jobs and document operations.
A participating workflow reaches a recordable event.
A workflow emits a receipt only for a meaningful accepted, changed or terminal event.
bean/document_receipts.py · document receipts
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Store the record durably with links to the job, source and result evidence.
bean/document_receipts.py · document receipts
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
bean/evidence_store.py · evidence store
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return ordered records without rewriting partial, failed or unavailable outcomes as success.
bean/document_receipts.py · document receipts
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"feature": "engine.vision.remove",
"jobId": "j-1",
"outcome": "partial"
}{
"historyEntry": "e-9",
"status": "partial",
"linkedReceipt": true
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"feature": "engine.vision.remove",
"jobId": "j-1",
"outcome": "partial"
},
"after": {
"historyEntry": "e-9",
"status": "partial",
"linkedReceipt": true
}
}Source: bean/document_receipts.py · document receipts; bean/pocket_receipts.py · Pocket receipts; bean/evidence_store.py · evidence store
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Receipt missing | Audit gap | Do not infer success | Workflow terminal path |
| Order ambiguous | Use sequence/time tie-break | Keep IDs | Evidence store |
| History says complete but job partial | Mapping defect | Correct status | Receipt source |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/document_receipts.py | document receipts | evidence writer | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pocket_receipts.py | Pocket receipts | evidence writer | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/evidence_store.py | evidence store | persistence | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.job.lifecycle | supplies job state and terminal receipts | terminal states or event sequence changes |
| runner.route.progress | uses activity for later inspection | event visibility or cursor semantics change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_110_rh01_runner_forwarding.pyNamed tests cover selected document/Runner receipt paths.
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: Complete audit coverage or retention policy.
Observed in source. document_receipts.py, pocket_receipts.py and evidence_store.py write several evidence forms; no single product history is verified.
Limits and remaining work. A provider-neutral event schema, retention policy and unified user-facing history remain intended architecture.
tests/test_110_rh01_runner_forwarding.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Persist source-linked AI findings with model revision, confidence and retention policy.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for AI annotation records.
How AI findings outlive one model run workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. proposal-only; no dedicated annotation record.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
bean/evidence_store.py · evidence storage precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
bean/evidence_store.py · evidence storage precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
bean/evidence_store.py · evidence storage precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
bean/evidence_store.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
bean/evidence_store.py · evidence storage precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "AI finding",
"source": "fixture-source"
}{
"status": "proposal-only",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "AI finding",
"source": "fixture-source"
},
"after": {
"status": "proposal-only",
"receipt": null
}
}Source: bean/evidence_store.py · evidence storage precedent
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/evidence_store.py | evidence storage precedent | architecture precedent | proposal-only; no dedicated annotation record |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| ai.read.understanding | produces findings | review when identity, receipt, retry, consistency or ownership semantics change |
| ai.read.context | future producer | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordDocumentation checks prove the missing implementation is visible.
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: Any product implementation.
Observed in source. proposal-only; no dedicated annotation record.
Limits and remaining work. Implementation, product integration, tests and release evidence remain open.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Build a reviewable album proposal and save membership only after acknowledgement.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Album creation.
How suggestions become a saved album workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers suggested and user-directed album membership.
Stable photo identities and the required place/time evidence exist.
Name the album outcome and candidate source identities.
photo_vault/albums.py · album proposal and membership
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Evaluate the supported album rule and retain why each photo was included or excluded.
photo_vault/albums.py · album proposal and membership
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
photo_vault/album_kinds.py · album kinds
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Persist membership only after the proposal or edit is accepted.
photo_vault/albums.py · album proposal and membership
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"kind": "place",
"name": "Berlin",
"candidates": [
"p-1",
"p-2"
]
}{
"albumId": "a-4",
"members": [
"p-1"
],
"excluded": [
"p-2"
]
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"kind": "place",
"name": "Berlin",
"candidates": [
"p-1",
"p-2"
]
},
"after": {
"albumId": "a-4",
"members": [
"p-1"
],
"excluded": [
"p-2"
]
}
}Source: photo_vault/albums.py · album proposal and membership; photo_vault/album_kinds.py · album kinds
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No coordinates | Excluded/review | Do not guess place | Place evidence |
| Proposal shown as saved | UI state error | Wait for receipt | Album persistence |
| Member unavailable | Explicit unavailable member | Keep identity | Catalogue |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/albums.py | album proposal and membership | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/album_kinds.py | album kinds | rule definition | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| application.request.compose | carries album intent and selected IDs | selection or album schema changes |
| memory.workspace.catalogue | stores stable membership references | photo identity or availability semantics change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_albums_read_frame_bound.py tests/test_rq23_coordinates_and_places.py tests/test_rq24_place_albums_by_name.pyTests cover frame bounds, coordinates and place album naming for fixtures.
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: Released UI persistence or suggestion quality.
Observed in source. albums.py and album_kinds.py implement album kinds and place-oriented grouping with tests.
Limits and remaining work. A unified correction and durable membership path across the product UI remains unverified.
tests/test_albums_read_frame_bound.pytests/test_rq23_coordinates_and_places.pytests/test_rq24_place_albums_by_name.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Connect the provider contract to cloud files with explicit identity, upload and consistency state.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Cloud files adapter.
How Memory uses a cloud file provider workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. proposal-only; no source adapter.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md · cloud destination proposal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md · cloud destination proposal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md · cloud destination proposal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md · cloud destination proposal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "cloud file session",
"source": "fixture-source"
}{
"status": "proposal-only",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "cloud file session",
"source": "fixture-source"
},
"after": {
"status": "proposal-only",
"receipt": null
}
}Source: docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md · cloud destination proposal
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | docs/architecture/bean-demo/FEATURE-TAXONOMY-PROPOSAL.md | cloud destination proposal | architecture precedent | proposal-only; no source adapter |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.destination.storage | selects cloud destination | review when identity, receipt, retry, consistency or ownership semantics change |
| memory.adapter.provider | defines consistency | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordDocumentation checks prove the missing implementation is visible.
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: Any product implementation.
Observed in source. proposal-only; no source adapter.
Limits and remaining work. Implementation, product integration, tests and release evidence remain open.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Carry one named deadline across admission and bounded work, then report expiry as a distinct outcome.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Deadline handling.
Deadline validation and expiry workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers request deadline fields and operations that actively enforce them. A declared timeout is not proof every worker checks it.
The operation declares whether it supports a caller deadline.
The caller supplies a supported positive limit with the request.
bean/contracts.py · timeoutMs
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The Runner validates units and boundary before submission.
bean/contracts.py · validate_request
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The operation checks the deadline around blocking or streamed work.
bean/media_stream.py · timeout handling
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Expiry is distinct from cancellation, unavailable and failed work; partial artifacts remain named.
bean/media_stream.py · expiry branch
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Only work that reaches its normal completion boundary before expiry is complete.
bean/media_stream.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"operation": "media.read",
"timeoutMs": 1500
}{
"status": "deadline_exceeded",
"partialBytes": 4096
}Use the supported Runner entry point with a disposable fixture. No personal library is used.
{
"request": {
"operation": "media.read",
"timeoutMs": 1500
},
"result": {
"status": "deadline_exceeded",
"partialBytes": 4096
}
}Source: bean/contracts.py; bean/media_stream.py
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Negative timeout | Validation refusal | Correct request | Contract |
| Work continues after expiry | Enforcement gap | Stop claiming bound | Worker checks |
| Expiry shown as cancel | Outcome mapping error | Preserve distinction | Result schema |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/contracts.py | timeoutMs validation | request boundary | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/media_stream.py | timeout handling | enforcement | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| application.request.compose | declares the deadline | units or field semantics change |
| engine.job.lifecycle | records expired/partial state | terminal-state or retry semantics change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_bean_contracts.py tests/test_media_stream.pyContract and media-stream tests prove their inspected timeout branches.
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: Deadline propagation through all operations or process termination.
Observed in source. Contracts and media streaming code include timeout handling with named tests. Enforcement is operation-specific.
Limits and remaining work. One monotonic deadline propagated through every dispatcher, worker and retry is not verified.
tests/test_bean_contracts.pytests/test_media_stream.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Browse durable document identities, open the protected source and hand reading or PDF work to the appropriate workflow.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Document library.
Document library browse and source workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the document product surface and the boundary to Pocket Runner. It does not imply that the currently installed Runner forwards every request.
The document catalogue is available and source protection state is known.
The product opens its document list and must distinguish unavailable storage from a valid empty result.
pockets:PocketsAppMac · document feed
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Search or filtering returns the same durable document identities that later source and processing requests use.
pockets:PocketsAppMac/Document/SourceDocumentView.swift · source navigation
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Opening a source can require a credential or protection decision. A list result is not authority to reveal protected content.
pockets:PocketsAppMac/Document/SourceDocumentView.swift · SourceDocumentView
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A typed request is forwarded to the matching workflow. Source evidence for forwarding is newer than the recorded installed Runner; compatibility remains explicit.
pocket_runner/src/Forwarding.swift
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The application attaches reading, export or failure results to the original document and keeps partial or unavailable outcomes distinct.
tests/test_110_rh01_runner_forwarding.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"document": "doc-42",
"action": "read"
}{
"sourceAccess": "allowed",
"forwarding": "version dependent",
"status": "pending"
}Use only a disposable Pockets fixture and the explicitly compatible Runner build. The workflow does not claim the installed 0.3.1 Runner forwards this path.
{
"request": {
"document": "doc-42",
"action": "read"
},
"result": {
"sourceAccess": "allowed",
"forwarding": "version dependent",
"status": "pending"
}
}Source: Pockets SourceDocumentView; Pocket Runner Forwarding.swift
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Feed empty after disconnect | Unavailable state | Do not call it empty | Storage destination |
| Protected source opens directly | Protection failure | Stop reveal | Source gate |
| Request never reaches engine | Compatibility/forwarding gap | Keep pending or unavailable | Pocket Runner version |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| pockets unverified local checkout | PocketsAppMac/Document/SourceDocumentView.swift | SourceDocumentView | direct product surface | observed source |
| pocket-runner newer than installed 0.3.1 | src/Forwarding.swift | request forwarding | transport | source and test only |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | tests/test_110_rh01_runner_forwarding.py | forwarding fixture | test evidence | named test |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| runner.runtime.compatibility | determines whether forwarding is supported | Runner protocol or release changes |
| ai.read.document | consumes selected documents for reading | document input or result schema changes |
| memory.sidecar.document | persists source-attached document records | document identity or sidecar schema changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_110_rh01_runner_forwarding.pyThe named forwarding test proves the inspected source contract for its fixture.
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: That the installed Runner or a released document UI carries the same code.
Observed in source. Native Pocket screens and a source document viewer exist. Forwarding code and tests exist in the source checkout, while recorded evidence says installed Pocket Runner 0.3.1 does not forward the newer request path.
Limits and remaining work. The supported product/platform and released forwarding boundary need owner approval and release evidence. FakePocketRunner must not be treated as product integration.
tests/test_110_rh01_runner_forwarding.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Extract page regions and reading order while preserving page and source identity.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Document reading.
How a document becomes ordered readable regions workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers geometry, region detection and reading order; understanding is separate.
The original document and supported page renditions exist.
Select supported pages without altering the original.
bean/ai/geometry.py · page geometry
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Normalize page geometry and identify candidate reading regions.
bean/ai/geometry.py · page geometry
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Produce ordered regions with page coordinates and abstain when structure is unsupported.
bean/ai/regions.py · region model
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
bean/ai/geometry.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Attach ordered regions or unreadable outcomes to the original document pages.
bean/ai/reading_order.py · reading order
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"documentId": "d-1",
"pages": [
1
]
}{
"pages": [
{
"page": 1,
"regions": 3,
"order": [
1,
2,
3
]
}
]
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"documentId": "d-1",
"pages": [
1
]
},
"after": {
"pages": [
{
"page": 1,
"regions": 3,
"order": [
1,
2,
3
]
}
]
}
}Source: bean/ai/geometry.py · page geometry; bean/ai/regions.py · region model; bean/ai/reading_order.py · reading order
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Rotated order wrong | Partial/incorrect | Do not infer meaning | Geometry |
| No text region | Unreadable page | Keep source | Region evidence |
| Result detached from page | Invalid | Reject result | Page identity |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ai/geometry.py | page geometry | supporting implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ai/regions.py | region model | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ai/reading_order.py | reading order | direct implementation | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.pdf.ocr | may supply recognized text | page/region coordinate contract changes |
| ai.read.understanding | consumes ordered regions | region identity or confidence changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_ai_reading_order.pyNamed fixtures cover reading-order primitives.
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: Released OCR/model quality.
Observed in source. ai/geometry.py, regions.py and reading_order.py implement source-observed primitives.
Limits and remaining work. One released document product path and per-region confidence contract remain unverified.
tests/test_ai_reading_order.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Persist page layout, PDF metadata and notes as a source-linked document record.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Document sidecar records.
How document metadata stays beside its source workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. proposal-only storage counterpart; no dedicated source record.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
bean/document_jobs.py · document record operations counterpart
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
bean/document_jobs.py · document record operations counterpart
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
bean/document_jobs.py · document record operations counterpart
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
bean/document_jobs.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
bean/document_jobs.py · document record operations counterpart
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "document",
"source": "fixture-source"
}{
"status": "proposal-only",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "document",
"source": "fixture-source"
},
"after": {
"status": "proposal-only",
"receipt": null
}
}Source: bean/document_jobs.py · document record operations counterpart
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/document_jobs.py | document record operations counterpart | architecture precedent | proposal-only storage counterpart; no dedicated source record |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| application.consumer.document | owns source identity | review when identity, receipt, retry, consistency or ownership semantics change |
| engine.pdf.ocr | supplies page/text evidence | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordDocumentation checks prove the missing implementation is visible.
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: Any product implementation.
Observed in source. proposal-only storage counterpart; no dedicated source record.
Limits and remaining work. Implementation, product integration, tests and release evidence remain open.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Classify and translate source-linked document content without hiding uncertainty.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Document understanding.
How readable regions become structured meaning workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers classification and translation after reading.
Document reading produced ordered source-linked regions.
Name classification or translation and preserve region identities.
bean/ai/classify.py · document classification
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Choose a supported model/task combination or return unavailable.
bean/ai/classify.py · document classification
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Produce structured findings with confidence and abstention.
bean/ai/translate.py · translation
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
bean/ai/classify.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Attach findings to their regions without replacing source text.
bean/ai/translate.py · translation
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"documentId": "d-1",
"task": "classify"
}{
"label": "invoice",
"confidence": 0.87,
"sourceRegions": [
1,
2
]
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"documentId": "d-1",
"task": "classify"
},
"after": {
"label": "invoice",
"confidence": 0.87,
"sourceRegions": [
1,
2
]
}
}Source: bean/ai/classify.py · document classification; bean/ai/translate.py · translation
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Unsupported language | Unavailable | Do not guess | Model route |
| Finding lacks region | Invalid | Reject | Source link |
| Low confidence | Review/abstain | Do not hard-label | Threshold |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ai/classify.py | document classification | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ai/translate.py | translation | direct implementation | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| ai.read.document | supplies ordered source regions | region schema changes |
| memory.sidecar.ai | may persist findings | annotation identity or retention changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_ai_classify.py tests/test_ai_translate.pyFixtures cover inspected classification/translation helpers.
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: Dewarping, per-region recognition or release integration.
Observed in source. ai/classify.py and translate.py implement parts; dewarping and per-region recognition remain planned.
Limits and remaining work. A complete model route, schema and released application experience are not verified.
tests/test_ai_classify.pytests/test_ai_translate.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Group likely duplicates, preserve every source identity and explain why one item is suggested as representative.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Duplicate detection.
Duplicate grouping and representative workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers grouping and recoverable suggestions. It does not remove originals.
The inventory has stable photo IDs and comparable renditions or embeddings.
Read candidate identities and available comparison data.
photo_vault/actual_data.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Build pair evidence without treating one signal as proof of identity.
photo_vault/analysis.py · build_visual_groups
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Create a group with stable member identities and evidence.
photo_vault/duplicates_recoverable.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Ambiguous members remain reviewable with their comparison evidence and stable source identities.
photo_vault/review.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Show a representative suggestion while retaining recoverability for every member.
photo_vault/duplicates_recoverable.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Below-threshold photos remain independent records and no membership or removal action is created.
photo_vault/analysis.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"photos": [
"p-1",
"p-2",
"p-3"
]
}{
"group": [
"p-1",
"p-2"
],
"representative": "p-1",
"separate": [
"p-3"
],
"removed": []
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"photos": [
"p-1",
"p-2",
"p-3"
]
},
"after": {
"group": [
"p-1",
"p-2"
],
"representative": "p-1",
"separate": [
"p-3"
],
"removed": []
}
}Source: photo_vault/analysis.py · build_visual_groups; photo_vault/duplicates_recoverable.py · recoverable duplicate model
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Missing rendition | Unassessed | Do not group | Preview/embedding source |
| Group changes on paging | Non-determinism | Hold action | Grouping inputs |
| Representative removed automatically | Boundary breach | Restore | Safe removal |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/analysis.py | build_visual_groups | group construction | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/duplicates_recoverable.py | recoverable duplicate model | direct implementation | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.vision.review | receives ambiguous groups | group evidence or correction schema changes |
| engine.vision.remove | consumes explicitly approved members | representative or recoverability policy changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_rq21_recoverable_and_people_count.pyThe fixture tests cover recoverable grouping behavior.
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: Threshold fitness across a personal collection.
Observed in source. analysis.build_visual_groups and duplicates_recoverable.py provide grouping and recoverability evidence.
Limits and remaining work. One reviewed similarity threshold and representative policy across products is not approved.
tests/test_rq21_recoverable_and_people_count.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Route an admitted operation to exactly one supported worker and return a durable job identity or a named refusal.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Job submission.
Accepted request routing workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers routing after structural validation and policy admission. It does not own permission or worker execution.
The request is structurally valid and admitted by policy.
Routing starts only after request and policy evidence exist.
bean/operations.py · operation entry
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Select the handler from the operation name without broad fallback.
bean/operations.py · dispatch
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Unsupported operations and incompatible payloads produce a named refusal without creating a job.
bean/operations.py · refusal branches
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The handler creates or reuses the operation job according to its idempotency contract.
bean/jobs.py · JobStore.create
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return the durable identity and explicit queued/running state for later progress and control.
bean/jobs.py · receipt
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"operation": "thumbnail.resolve",
"idempotencyKey": "thumb-photo-17"
}{
"jobId": "job-71",
"state": "queued"
}Use the supported Runner entry point with a disposable fixture. No personal library is used.
{
"request": {
"operation": "thumbnail.resolve",
"idempotencyKey": "thumb-photo-17"
},
"result": {
"jobId": "job-71",
"state": "queued"
}
}Source: bean/operations.py · dispatch
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Unknown operation | Refused | Do not create job | Route table |
| Same key changed payload | Conflict refusal | Use new key or original payload | Job store |
| Receipt without observable job | Routing defect | Do not report submitted | Job persistence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py | dispatch | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py | JobStore.create | durable identity | supporting source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.job.policy | provides admission evidence | policy decision contract changes |
| engine.job.lifecycle | creates the durable job | idempotency or initial-state semantics change |
| runner.route.progress | observes returned job identity | receipt or job ID format changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_operations.pyOperation tests prove only the exercised route and refusal branches.
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: Universal admission or worker completion.
Observed in source. bean.operations dispatches a broad operation table. The dispatcher is large and operation-specific; not every product entry point follows one universal admission path.
Limits and remaining work. A registry-driven route table with uniform admission evidence and advertised control support remains intended architecture.
tests/test_operations.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Score likely screenshots, blur and low-value captures without deleting a photo automatically.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Junk detection.
Junk detection, confidence and review workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers classification and review candidates. Safe removal is a separate feature.
The library catalogue contains stable photo records and supported renditions.
Read candidate records without changing the library.
photo_vault/clearout.py · candidate selection
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Compute native signals and keep missing measurements explicit.
photo_vault/junk_classify.py · classify
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Map signals to an explainable band rather than a delete command.
photo_vault/clearout.py · junk bands
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain and user-sensitive candidates enter review with reasons.
photo_vault/review.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Present a reversible candidate tied to its source identity.
photo_vault/clearout.py
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Protected, unsupported or insufficient-evidence photos are excluded without mutation.
photo_vault/junk_classify.py · abstention
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"photoId": "p-17",
"signals": {
"blur": 0.81,
"screenshot": false
}
}{
"classification": "review",
"reason": "low sharpness",
"deleted": false
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"photoId": "p-17",
"signals": {
"blur": 0.81,
"screenshot": false
}
},
"after": {
"classification": "review",
"reason": "low sharpness",
"deleted": false
}
}Source: photo_vault/clearout.py · junk candidate and band logic; photo_vault/junk_classify.py · native classifier
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No signal | Excluded/unknown | Do not call junk | Rendition and classifier |
| Candidate disappeared | Identity mismatch | Stop removal | Stable photo ID |
| Photo deleted | Boundary breach | Restore and investigate | engine.vision.remove |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/clearout.py | junk candidate and band logic | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/junk_classify.py | native classifier | direct implementation | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.vision.review | receives uncertain candidates | confidence bands or reason schema change |
| engine.vision.remove | may consume an approved candidate | candidate identity or approval contract changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_r18_junk_native.py tests/test_bean_junk_bands.pyThe named tests cover native signals and band mapping for fixtures.
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: Product threshold quality or user-approved deletion.
Observed in source. clearout.py and junk_classify.py build native junk signals and bands with named tests.
Limits and remaining work. Threshold calibration, explainable reasons and released UI review are not verified end to end.
tests/test_r18_junk_native.pytests/test_bean_junk_bands.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Plan, copy, verify and catalogue a recoverable library replica.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Library backup.
How a library copy becomes verified workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers copy planning, transactions, digests and replica index.
A reviewed plan and supported destination exist.
Name exact records and destination without copying during planning.
photo_vault/replica_index.py · replica index
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Resolve the destination through Memory and refuse unavailable or unsafe targets.
photo_vault/replica_index.py · replica index
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Write through transactions and verify content before counting an item complete.
photo_vault/file_transactions.py · file transaction
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
photo_vault/replica_index.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Update the copy catalogue only for verified outcomes and name partial failures.
photo_vault/digests.py · content digest
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"records": [
"p-1",
"p-2"
],
"destination": "fixture-drive"
}{
"verified": [
"p-1"
],
"failed": [
"p-2"
],
"status": "partial"
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"records": [
"p-1",
"p-2"
],
"destination": "fixture-drive"
},
"after": {
"verified": [
"p-1"
],
"failed": [
"p-2"
],
"status": "partial"
}
}Source: photo_vault/replica_index.py · replica index; photo_vault/file_transactions.py · file transaction; photo_vault/digests.py · content digest
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Destination full | Partial/refused | Do not mark complete | Capacity |
| Digest mismatch | Failed item | Keep source | Verification |
| Index says present but file missing | Consistency gap | Repair index/copy | Replica check |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/replica_index.py | replica index | copy catalogue | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/file_transactions.py | file transaction | copy execution | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/digests.py | content digest | verification | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.destination.storage | chooses and resolves destination | destination policy or identity changes |
| engine.ops.restore | consumes verified replicas | replica receipt or digest rules change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_109_replica_index_and_reads.pyFixtures cover replica index and read behavior.
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: All destination providers or disaster recovery.
Observed in source. replica_index.py, file_transactions.py, storage.py, files.py, destinations.py and digests.py provide source-backed parts.
Limits and remaining work. One provider-neutral end-to-end backup and restore proof across local, NAS and cloud is not verified.
tests/test_109_replica_index_and_reads.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Maintain a searchable local catalogue and bounded working state without becoming the source of truth for every file.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Library catalogue.
How the workspace remembers library records workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers catalogue snapshot, queries, cache pointers and working state.
A configured workspace or an explicit unavailable state exists.
Resolve the configured local workspace without treating missing storage as empty.
photo_vault/db.py · catalogue database
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Validate the database, data-root pointer and bounded caches.
photo_vault/db.py · catalogue database
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return records tied to a catalogue revision and explicit availability.
photo_vault/actual_library.py · workspace/data-root access
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
photo_vault/db.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The consumer receives stable IDs and honest missing/offline state.
photo_vault/thumbnail_store.py · bounded preview store
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"library": "fixture",
"query": "page 1"
}{
"records": 20,
"revision": 4,
"offline": 2
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"library": "fixture",
"query": "page 1"
},
"after": {
"records": 20,
"revision": 4,
"offline": 2
}
}Source: photo_vault/db.py · catalogue database; photo_vault/actual_library.py · workspace/data-root access; photo_vault/thumbnail_store.py · bounded preview store
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Database missing | Unavailable | Do not create silently | Workspace path |
| Drive offline | Records unavailable | Do not erase | Destination state |
| Revision changed | Stale page | Refresh | Catalogue revision |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/db.py | catalogue database | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/actual_library.py | workspace/data-root access | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/thumbnail_store.py | bounded preview store | working cache | supporting source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.destination.storage | resolves current availability | destination identity or offline semantics change |
| engine.media.preview | uses bounded preview state | preview key or cache policy changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_109_offline_and_footprint.py tests/test_catalog_query_matches_capture_date.pyFixtures cover offline footprint and catalogue query behavior.
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: Personal-library completeness.
Observed in source. db.py, actual_library.py and thumbnail_store.py implement catalogue and bounded local state.
Limits and remaining work. Provider-neutral reconciliation and one approved offline/online contract remain open.
tests/test_109_offline_and_footprint.pytests/test_catalog_query_matches_capture_date.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Count and classify library records while keeping unknown, unavailable and incomplete evidence visible.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Library inventory.
How a library proves what it contains workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers census and completeness reporting without mutating sources.
The selected catalogue or copy can be read without mutation.
Name the library/copy and which completeness evidence is required.
photo_vault/census.py · library census
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Read records and evidence without treating an inaccessible destination as empty.
photo_vault/census.py · library census
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
photo_vault/completeness.py · completeness evaluation
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return counts and named gaps tied to the inspected catalogue revision.
photo_vault/census.py · library census
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"library": "fixture",
"required": [
"source",
"preview"
]
}{
"known": 100,
"complete": 92,
"missingPreview": 6,
"unavailable": 2
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"library": "fixture",
"required": [
"source",
"preview"
]
},
"after": {
"known": 100,
"complete": 92,
"missingPreview": 6,
"unavailable": 2
}
}Source: photo_vault/census.py · library census; photo_vault/completeness.py · completeness evaluation
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Drive offline | Unavailable records | Do not count zero | Destination status |
| Counts change mid-scan | Revision changed | Restart/report partial | Catalogue revision |
| Known ≠ category totals | Report invalid | Reconcile | Census aggregation |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/census.py | library census | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/completeness.py | completeness evaluation | direct implementation | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.workspace.catalogue | supplies records and revision | catalogue scope or identity changes |
| memory.copy.backup | uses inventory for copy completeness | copy evidence or verification rules change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_census.py tests/test_completeness.pyFixture tests cover census and completeness rules they name.
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: Completeness of a personal library or offline destination.
Observed in source. census.py and completeness.py implement catalogue and evidence checks with multiple fixture tests.
Limits and remaining work. One owner-approved completeness definition across local, network and cloud copies remains open.
tests/test_census.pytests/test_completeness.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Select a verified copy, plan exact recovery and restore without overwriting unrelated data.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Library restore.
How a verified replica restores library records workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. allowlisted source path; application does not send restore.run.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
bean/release_rehearsal.py · restore rehearsal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
bean/release_rehearsal.py · restore rehearsal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
bean/release_rehearsal.py · restore rehearsal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
bean/release_rehearsal.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
bean/release_rehearsal.py · restore rehearsal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "restore plan",
"source": "fixture-source"
}{
"status": "planned",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "restore plan",
"source": "fixture-source"
},
"after": {
"status": "planned",
"receipt": null
}
}Source: bean/release_rehearsal.py · restore rehearsal
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/release_rehearsal.py | restore rehearsal | partial implementation | allowlisted source path; application does not send restore.run |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.copy.backup | supplies verified replicas | review when identity, receipt, retry, consistency or ownership semantics change |
| memory.destination.storage | opens source/destination | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_release_rehearsal.pyThe rehearsal test proves only its disposable fixture path.
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: Production restore or application integration.
Observed in source. allowlisted source path; application does not send restore.run.
Limits and remaining work. The application route, production provider behavior and end-to-end recovery verification remain open.
tests/test_release_rehearsal.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Connect the provider contract to HDD, SSD and other mounted local volumes.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Local volume adapter.
How Memory uses a mounted local volume workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. proposal 109 local-volume profile; adapter boundary not isolated.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
photo_vault/actual_library.py · local volume access precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
photo_vault/actual_library.py · local volume access precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
photo_vault/actual_library.py · local volume access precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
photo_vault/actual_library.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
photo_vault/actual_library.py · local volume access precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "local volume session",
"source": "fixture-source"
}{
"status": "planned",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "local volume session",
"source": "fixture-source"
},
"after": {
"status": "planned",
"receipt": null
}
}Source: photo_vault/actual_library.py · local volume access precedent
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/actual_library.py | local volume access precedent | partial implementation | proposal 109 local-volume profile; adapter boundary not isolated |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.destination.storage | selects the volume | review when identity, receipt, retry, consistency or ownership semantics change |
| memory.copy.backup | uses write/verify | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_release_rehearsal.pyThe rehearsal test proves only its disposable fixture path.
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: Production restore or application integration.
Observed in source. proposal 109 local-volume profile; adapter boundary not isolated.
Limits and remaining work. The application route, production provider behavior and end-to-end recovery verification remain open.
tests/test_release_rehearsal.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Connect the provider contract to a network destination with explicit disconnect and retry behavior.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Network volume adapter.
How Memory uses NAS and mounted network storage workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. proposal-only; no source adapter.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html · future network destination extension
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html · future network destination extension
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html · future network destination extension
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html · future network destination extension
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "network storage session",
"source": "fixture-source"
}{
"status": "proposal-only",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "network storage session",
"source": "fixture-source"
},
"after": {
"status": "proposal-only",
"receipt": null
}
}Source: docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html · future network destination extension
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | docs/proposals/109-drive-first-processing-the-destination-drives-are-the-library.html | future network destination extension | architecture precedent | proposal-only; no source adapter |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.destination.storage | selects network destination | review when identity, receipt, retry, consistency or ownership semantics change |
| memory.adapter.provider | defines retry/consistency | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordDocumentation checks prove the missing implementation is visible.
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: Any product implementation.
Observed in source. proposal-only; no source adapter.
Limits and remaining work. Implementation, product integration, tests and release evidence remain open.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Parse one operator command, compose a typed request, stream honest progress and finish with a machine-readable result.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Command-line operations.
Command-line request and control workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the Runner CLI surface. Individual operations decide which controls and outputs they support.
A compatible Runner is installed and the operator knows the target fixture.
Parse the command without guessing an operation or silently dropping unknown options.
runner/photovault_runner/src/Cli.swift · Cli
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Create the session and typed request context used by the operation.
runner/photovault_runner/src/CliSession.swift
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Invalid commands, unavailable operations and rejected controls end with a stable refusal and no false completion.
runner/photovault_runner/src/Cli.swift · error branches
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Dispatch only a supported operation or control. The CLI is a consumer; it does not redefine engine policy.
runner/photovault_runner/pvr.py · operation dispatch
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Translate observed events without inventing counts or reporting a requested control as acknowledged.
runner/photovault_runner/src/CliProgress.swift
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Print a stable terminal response and set the exit status from the explicit outcome.
runner/photovault_runner/src/CliSession.swift
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"command": "analysis status --job demo"
}{
"state": "running",
"progress": "3/10",
"exit": 0
}Use the supported Runner entry point with a disposable fixture. No personal library is used.
{
"command": "analysis status --job demo",
"result": {
"state": "running",
"progress": "3/10",
"exit": 0
}
}Source: runner/photovault_runner/src/Cli.swift · Cli; CliSession.swift; CliProgress.swift
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Unknown option | Usage refusal | Correct command | Cli parser |
| Control remains pending | No completion claim | Wait or inspect | Job events |
| Output cannot be parsed | CLI contract gap | Use human output cautiously | Machine format |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | runner/photovault_runner/src/Cli.swift | Cli | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | runner/photovault_runner/src/CliSession.swift | CliSession | session lifecycle | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | runner/photovault_runner/src/CliProgress.swift | CliProgress | progress presentation | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| application.request.compose | supplies typed command requests | request fields or operation names change |
| runner.route.progress | supplies observed state | event or state vocabulary changes |
| engine.job.lifecycle | owns supported controls | pause, resume, cancel or retry semantics change |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_109_runner_cli.py tests/test_109_repair_scan_steps.pyCLI tests prove the named parsing and repair-step behavior.
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: All operations share identical control or output support.
Observed in source. Cli.swift, CliSession.swift and CliProgress.swift provide parsing, session and progress behavior. Open contract items remain in the source review.
Limits and remaining work. Common exit codes, refusal formatting and full control parity are not verified across every operation.
tests/test_109_runner_cli.pytests/test_109_repair_scan_steps.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Detect faces, build person groups and keep corrections attached to the source photos.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for People detection.
How photos become reviewable people groups workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers face evidence and person grouping. Naming and consent remain product decisions.
Consent and supported source renditions are available.
Choose eligible sources under the product consent and policy boundary.
photo_vault/people.py · people grouping
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Produce source-linked face evidence and groups; missing faces and abstention remain valid outcomes.
photo_vault/people.py · people grouping
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
bean/face_jobs.py · face job orchestration
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Present groups with photo counts and correction actions without claiming an unknown identity.
photo_vault/people.py · people grouping
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"photos": [
"p-1",
"p-2"
],
"consent": true
}{
"groups": [
{
"id": "person-1",
"photos": [
"p-1",
"p-2"
]
}
],
"names": []
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"photos": [
"p-1",
"p-2"
],
"consent": true
},
"after": {
"groups": [
{
"id": "person-1",
"photos": [
"p-1",
"p-2"
]
}
],
"names": []
}
}Source: photo_vault/people.py · people grouping; photo_vault/ml/faces.py · face inference; bean/face_jobs.py · face job orchestration
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No consent | No analysis | Do not start model | Policy |
| Face without source | Invalid evidence | Hide group | Face record link |
| Wrong grouping | Review item | Correct membership | Group persistence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/people.py | people grouping | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/ml/faces.py | face inference | model adapter | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/face_jobs.py | face job orchestration | job execution | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.job.policy | guards consent and source access | consent or scope contract changes |
| engine.vision.review | receives grouping corrections | group membership or correction schema changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_109_faces_and_people.py tests/test_106_r17_people_actual_data.py tests/test_rq21_recoverable_and_people_count.pyFixture tests cover face jobs, actual-data reads and recoverable counts.
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: Identity accuracy, consent UI or released integration.
Observed in source. people.py, ml/faces.py, bean/faces.py and face_jobs.py implement detection and grouped evidence with tests.
Limits and remaining work. Consent, correction persistence and one approved released UI path are not verified end to end.
tests/test_109_faces_and_people.pytests/test_106_r17_people_actual_data.pytests/test_rq21_recoverable_and_people_count.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Describe supported photo content while preserving uncertainty and its source identity.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Photo context.
How a photo gets a source-linked description workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Proposal-only feature; no verified context-generation implementation exists.
A future authorized rendition and model contract exist.
Select an authorized photo and a bounded description task.
docs/proposals/86-photo-context.md · proposal record
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Refuse unavailable, unsupported or unauthorized input.
docs/proposals/86-photo-context.md · proposal record
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Proposed model work produces a source-linked description and can abstain.
docs/proposals/86-photo-context.md · proposal record
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
docs/proposals/86-photo-context.md · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The proposed result retains model revision, source identity and uncertainty.
docs/proposals/86-photo-context.md · proposal record
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"photoId": "p-1",
"task": "describe"
}{
"status": "proposal-only",
"description": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"photoId": "p-1",
"task": "describe"
},
"after": {
"status": "proposal-only",
"description": null
}
}Source: docs/proposals/86-photo-context.md · proposal record
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No model route | Unavailable | Do not invent description | Implementation |
| Source changed | Stale | Re-run only with approval | Digest |
| Unsafe inference | Abstain | Keep source only | Policy |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | docs/proposals/86-photo-context.md | proposal record | architecture proposal | proposal-only; no implementation |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.job.policy | future consent and scope | photo AI policy changes |
| memory.sidecar.ai | future context persistence | annotation schema changes |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordDocumentation checks prove proposal-only labeling.
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: Any model inference or product behavior.
Observed in source. No source-backed photo-context worker or result record was verified.
Limits and remaining work. Model contract, privacy, prompt policy, evaluation, persistence and product UI remain open.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Open a library, page through stable photo identities, request previews and keep selection or organisation actions attached to the same records.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Photo library.
Photo library browse and organise workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the Vanilla application experience from opening a library through browsing, selection and an acknowledged organisation action. Preview generation and catalogue persistence remain separate feature workflows.
A compatible library connection exists or the application can explain why it does not.
The person opens the library surface. The application must distinguish no configured library, a disconnected library and a successfully opened empty library.
app:flutter_photovault/lib/presentation/library_screen.dart · LibraryScreen
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The screen asks its repository or page source for catalogue records. Stable identifiers, rather than grid positions or filenames alone, carry selection and later actions.
app:flutter_photovault/lib/presentation/library_screen.dart · page source and repository inputs
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Visible records request previews through engine.media.preview. A missing preview remains attached to its photo and must not be replaced with an unrelated image.
bean/operations.py · thumbnail routes; engine.media.preview workflow
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The grid presents records and preserves selection as pages or preview updates arrive. Organisation commands operate on the selected stable identities.
app:flutter_photovault/lib/presentation/library_screen.dart · selection callbacks
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A selected-item action passes identities to the owning feature. Planning is not completion; the UI changes durable state only after that feature acknowledges its result.
app:flutter_photovault/lib/presentation/library_screen.dart · onAddToAlbumPlan, onArchivePlan
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"library": "fixture-library",
"page": 1
}{
"records": 24,
"missingPreviews": 2,
"selection": [
"photo-17"
],
"action": "album plan pending"
}Open the Vanilla library with a disposable fixture. This page does not authorize access to a personal photo library.
{
"request": {
"library": "fixture-library",
"page": 1
},
"result": {
"records": 24,
"missingPreviews": 2,
"selection": [
"photo-17"
],
"action": "album plan pending"
}
}Source: app LibraryScreen contract; bean thumbnail operation boundary
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Library cannot open | Unavailable, not empty | Connection or permission problem | Runner compatibility and catalogue |
| Preview missing | Placeholder tied to the photo | Preview work unavailable or pending | engine.media.preview |
| Selection changes after paging | Identity contract failure | Do not submit action | Record IDs and page merge |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| vanilla unverified local checkout | flutter_photovault/lib/presentation/library_screen.dart | LibraryScreen | direct product surface | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py | thumbnail operations | preview supplier | supporting workflow |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.media.preview | supplies each visible preview | preview identity, availability or cache contract changes |
| memory.workspace.catalogue | supplies stable records and paging | catalogue identity or query semantics change |
| application.request.compose | carries selected items into actions | selection or request schema changes |
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.
python3 -m pytest -q -p no:cacheprovider app:test/presentation/library_screen_test.dartUI fixture tests can prove paging, selection and missing-preview presentation for the tested screen state.
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: Release compatibility, real-library safety or successful engine integration.
Observed in source. The Flutter application has library, search, albums, globe, people, analysis, archive and work-tray surfaces. The library consumes page and thumbnail update sources and preserves selection callbacks.
Limits and remaining work. A single verified product path joining the released application, compatible Runner, catalogue and preview workflow has not been certified. Disconnected, unavailable and missing-preview states still require end-to-end evidence.
app:test/presentation/library_screen_test.dartBack to the architecture map · Authoring guidance is maintained in the repository template.
Persist source-linked photo metadata without modifying the original photo.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Photo sidecar records.
How photo notes and analysis stay beside their source workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers versioned photo sidecar format and understanding; Bean write/read integration is incomplete.
The photo has stable identity and an eligible sidecar destination.
Create metadata against a stable photo identity and source version.
photo_vault/sidecar.py · FORMAT_VERSION 2
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check supported schema and prevent a record from attaching to the wrong source.
photo_vault/sidecar.py · FORMAT_VERSION 2
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Persist the record under destination policy without altering the original media.
photo_vault/sidecar.py · FORMAT_VERSION 2
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
photo_vault/sidecar.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Confirm durable association and explicit copy state.
photo_vault/sidecar.py · FORMAT_VERSION 2
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"photoId": "p-1",
"note": "keep",
"schema": 2
}{
"status": "proposal-integration",
"sourceChanged": false
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"photoId": "p-1",
"note": "keep",
"schema": 2
},
"after": {
"status": "proposal-integration",
"sourceChanged": false
}
}Source: photo_vault/sidecar.py · FORMAT_VERSION 2
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Unsupported version | Refused | Migrate explicitly | Schema |
| Digest changed | Stale | Do not attach | Source identity |
| Copy lacks sidecar | Incomplete replica | Repair copy | Backup policy |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/sidecar.py | FORMAT_VERSION 2 | format definition | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.copy.backup | copies sidecar with its source | replica completeness rules change |
| memory.destination.storage | chooses sidecar location | destination policy changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_sidecar_understood.pyTests cover understood sidecar schema behavior.
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: Bean end-to-end persistence.
Observed in source. photo_vault/sidecar.py defines FORMAT_VERSION 2 and understanding tests.
Limits and remaining work. Bean does not yet provide a verified end-to-end read/write and copy policy for photo sidecars.
tests/test_sidecar_understood.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Observe one durable job, relay ordered updates and distinguish progress from a terminal result.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Progress tracking.
Progress relay and terminal state workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers progress transport and presentation. The job workflow owns state changes.
A submitted durable job identity exists.
Open observation for one job and optional sequence cursor.
runner/photovault_runner/pvr.py · observation route
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Write a bounded chunk without inventing missing totals or translating requested controls into completed states.
runner/photovault_runner/pvr.py · _write_relay_chunk
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
If the cursor is too old or a chunk is missing, name the gap and require a fresh snapshot.
bean/job_recovery.py · replay gap
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The consumer shows explicit job state, phase and only known counts.
app:flutter_photovault/lib/presentation/work_tray/runner_activity_progress.dart · runnerProgressLineText
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Observation finishes only from the durable terminal outcome, not from percent alone.
bean/jobs.py · TERMINAL
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"jobId": "job-71",
"after": 12
}{
"state": "running",
"phase": "thumbnails",
"done": 30,
"total": null
}Use the supported Runner entry point with a disposable fixture. No personal library is used.
{
"observation": {
"jobId": "job-71",
"after": 12
},
"result": {
"state": "running",
"phase": "thumbnails",
"done": 30,
"total": null
}
}Source: runner/photovault_runner/pvr.py · _write_relay_chunk
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Old cursor | Replay gap | Fetch snapshot | Event bounds |
| 100% but running | Still running | Wait for terminal state | Job receipt |
| Unknown total | Indeterminate progress | Show phase only | Worker event payload |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | runner/photovault_runner/pvr.py | _write_relay_chunk | direct relay | observed source |
| vanilla unverified local checkout | flutter_photovault/lib/presentation/work_tray/runner_activity_progress.dart | runnerProgressLineText | UI consumer | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.job.lifecycle | owns state and event sequence | state, phase or event replay semantics change |
| runner.opctrl.cli | presents operator progress | machine output or progress vocabulary changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_runner_progress.pyRunner progress tests prove the named relay behavior for their fixtures.
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: Every worker emits the same phases or totals.
Observed in source. The Runner writes relay chunks and product UI consumes observations. Different jobs expose different counts and phases.
Limits and remaining work. A universal event schema, replay cursor and gap behavior across all job families remains unverified.
tests/test_runner_progress.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Follow one durable job across worker attempts, pauses and interruptions without mistaking a restart for completion.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Job management.
Create, pause, resume and finish a job
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
The diagram combines the JobStore and JobRecovery primitives. An operation must wire these controls into its worker; their presence does not mean every job exposes every command.
Admission and an operation-specific worker already exist. The worker must opt into the lifecycle controls it exposes.
Create a durable job after admission. An owner-scoped idempotency key reuses the same request; a changed payload with the same key is refused. Queuing alone does not claim a worker.
bean/jobs.py · JobStore.create
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A changed payload cannot reuse the idempotency key. A live worker lease or respected operator hold prevents claiming work; do not pretend that a new worker started.
bean/jobs.py · create, claim
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Claim the next attempt. A live lease protects its worker; a stale worker cannot finalize a newer attempt. Respect the operator hold when using retry for controllable work.
bean/jobs.py · JobStore.claim; bean/job_recovery.py · JobRecovery.retry
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Workers process bounded units, renew leases and persist checkpoints and unit receipts. Progress events describe what happened; they are not a substitute for a terminal result.
bean/jobs.py · transition_with_lease; bean/job_recovery.py · checkpoint, record_work_unit
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
An operator hold prevents automatic re-claim when respected by the worker. Recovery parks an expired running attempt as paused, never complete. It refuses to interrupt a live lease. Pausing is cooperative at a worker boundary.
bean/jobs.py · request_hold, pause_with_lease; bean/job_recovery.py · recover
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Release an operator hold and claim a new fenced attempt, then continue using recorded work. JobStore.resume alone is restricted to never-leased jobs; leased work uses the recovery/claim path.
bean/jobs.py · release_hold, resume; bean/job_recovery.py · retry
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A cancellation request is not instant rollback. The worker records its safe boundary and cancellation outcome; completed work remains evidence. Operations must advertise which controls they support.
bean/job_recovery.py · request_cancellation, cancel_with_checkpoint
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A worker publishes a terminal result only through the current lease. Complete, partial, failed and unavailable remain separate outcomes; a lease-free cancellation of queued or paused work is a separate control path. An expired worker must not publish a successful result.
bean/jobs.py · STATES, TERMINAL, transition_with_lease, cancel
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a receipt or events after a supplied sequence. The client reads the explicit state and result. A bounded event window may require a snapshot before replaying newer events.
bean/jobs.py · receipt, events; bean/job_recovery.py · snapshot, replay
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative state sequence. Recovery is attempted only after the lease expires. A healthy lease returns lease_held; recovery does not steal live work.
{
"jobId": "demo-job",
"state": "running",
"generation": 1
}{
"recovery": "paused",
"retryGeneration": 2,
"resumeFrom": "last recorded unit",
"completion": "only after worker finalization"
}Run examples/job-lifecycle.py from the documentation checkout with the inspected Bean package on PYTHONPATH. It creates and deletes only temporary SQLite stores. Expected output is queued → paused → running generation 2 → complete, with six retained events. It does not open a library or dispatch OCR. Use only the controls advertised by the specific operation; JobStore primitives do not create a universal pause/resume API.
"""Fictional durable-job lifecycle walkthrough."""
from pathlib import Path
from tempfile import TemporaryDirectory
from bean.job_recovery import JobRecovery
from bean.jobs import JobStore
def main():
with TemporaryDirectory(prefix="lifecycle-workflow-") as scratch:
root = Path(scratch)
jobs = JobStore(root / "jobs.sqlite3", owner="pocket")
recovery = JobRecovery(jobs, root / "recovery.sqlite3")
created = jobs.create("demo-job", "sandbox", "demo-key",
{"kind": "ocr", "pages": ["page-1", "page-2"]})
first = jobs.claim("demo-job", "worker-a", lease_seconds=10, now=100.0)
recovery.record_work_unit("demo-job", first.generation, "page-1",
{"status": "read"}, worker_id="worker-a", now=101.0)
recovery.checkpoint("demo-job", first.generation, {"page": 1},
worker_id="worker-a", payload={"source": "fictional"}, now=101.1)
paused = recovery.recover("demo-job", reason="process_death")
second = recovery.retry("demo-job", "worker-b", lease_seconds=30, now=200.0)
resumed = jobs.get("demo-job")
completed = jobs.transition_with_lease("demo-job", "worker-b", second.generation,
"complete", result={"pages": 2}, now=201.0)
replay = recovery.replay("demo-job")
assert created.state == "queued" and paused.state == "paused"
assert resumed.state == "running" and second.generation == 2
assert completed.state == "complete" and replay.gap is False
print(f"created: {created.state}")
print(f"recovered: {paused.state}")
print(f"resumed: {resumed.state} generation {second.generation}")
print(f"completed: {completed.state}")
print(f"events: {len(replay.events)}")
if __name__ == "__main__":
main()
Source: examples/job-lifecycle.py; bean/jobs.py · JobStore; bean/job_recovery.py · JobRecovery
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Same key, changed payload | Create refused | No duplicate job | Compare the owner and original request; do not mutate an idempotent request. |
| Lease still live | Recovery refused | Worker keeps ownership | Wait for the operation’s supported control boundary. |
| Expired lease claimed directly | New generation interrupts old attempt | Job may remain running | Use JobRecovery.recover when the intended evidence is an explicit paused recovery. |
| Old worker finalizes | Lease fencing refuses | Newer attempt protected | Compare worker generation and lease evidence. |
| Pause command unavailable | Operation-specific refusal | No assumed pause | Read advertised controls; store primitives alone do not expose commands. |
| Event cursor too old | Snapshot/replay boundary | Partial history is explicit | Read a current snapshot before replaying newer events. |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · JobStore.create | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · create, claim | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · JobStore.claim; bean/job_recovery.py · JobRecovery.retry | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · transition_with_lease; bean/job_recovery.py · checkpoint, record_work_unit | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · request_hold, pause_with_lease; bean/job_recovery.py · recover | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · release_hold, resume; bean/job_recovery.py · retry | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/job_recovery.py · request_cancellation, cancel_with_checkpoint | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · STATES, TERMINAL, transition_with_lease, cancel | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/jobs.py · receipt, events; bean/job_recovery.py · snapshot, replay | See named source reference | workflow evidence | inspected source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|
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.
python3 -m pytest -q -p no:cacheprovider tests/test_bean_jobs.py tests/test_bean_job_recovery.py tests/test_jobs_durable_boundaries.pyFixture jobs are reopened after interruption; JobStore idempotency, leases, fencing and terminal transitions are exercised alongside recovery checkpoints, cancellation and replay boundaries. Durability-boundary fixtures also verify which job commits survive a restart or power-loss boundary.
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: A uniform pause/resume API for all operations, an asynchronous transport API, or live app integration. The tests do not certify PhotoVault library behavior.
Observed in source. Job identity and state are stored in SQLite. Worker leases fence stale attempts. Checkpoints and work-unit receipts persist recovery evidence in a separate SQLite sidecar. JobStore can mark an expired lease interrupted during a later claim; JobRecovery can explicitly park it as paused before a new attempt. Event sequences let callers observe progress.
Limits and remaining work. Control support varies: PhotoVault replica jobs expose pause/resume/retry; document jobs cancel at a page boundary and resume through ocr.pdf start with the same jobId. The Pocket jobs.observe path refuses generic pause/resume/retry. A universal operation-aware control surface remains intended architecture.
tests/test_bean_jobs.pytests/test_bean_job_recovery.pytests/test_jobs_durable_boundaries.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Check who may request work, which profile it may use, and why permission is granted or refused.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Policy management.
Existing sandbox grant path
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
This diagram follows the fictional-profile AuthorityRegistry. The intended common admission boundary combines permission, profile and library scope before job creation; this registry alone does not implement that boundary for every actual-data request.
A registered fictional app and owner, a fixed sandbox profile, and an operation request exist before authorization.
Register a fictional profile whose source, destination, database, queue, cache and credential folders are fixed. Reject symlinks, layout changes and ownership mismatches. The root is captured so later object changes cannot retarget a grant.
bean/authority.py · AuthorityRegistry.register_profile, create_profile
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The caller supplies a typed request for one registered app and owner. A permission decision is not a job and does not itself perform the requested work.
bean/contracts.py · validate_request
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Issue a unique, revocable grant for the request scope. Grant identity, profile, operation family and policy revision are checked again when the grant is used.
bean/authority.py · AuthorityRegistry.issue
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Authorization revalidates the envelope, rejects stale or revoked grants, and compares the request against the grant scope. A change in policy revision needs a matching grant. This scope check does not bind the exact operation or selected items, impose an expiry time, or revalidate profile directories.
bean/authority.py · AuthorityRegistry.authorize, _validate_request_scope
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A named refusal explains the rejected request. Invalid profile registration or grant issue also stops before authorization; do not fall through to a job or broaden the scope.
bean/authority.py · Refusal branches
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return AuthorizedOperation with the validated request, grant identity and revision, and the captured profile root. It is evidence of admission, not proof a job ran or succeeded.
bean/authority.py · AuthorizedOperation
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Revocation stops later use of that grant. It does not automatically cancel work already in flight; cancellation belongs to the job workflow.
bean/authority.py · AuthorityRegistry.revoke
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Summary of the runnable example below. The registry admits the request and refuses the next use after revocation. The example never dispatches OCR or creates a job.
{
"appId": "pocket",
"profile": "sandbox",
"operationFamily": "ocr.pdf",
"grant": "ocr-demo"
}{
"firstUse": "authorized",
"grantRevision": 1,
"afterRevocation": "grant_revoked",
"jobCreated": false
}Run from the inspected Bean checkout with its Python dependencies installed. This documentation example creates its own temporary sandbox folders and removes them on exit. Expected output: authorized: ocr-demo, revision 1; then refused after revocation: grant_revoked. It does not start a Runner, OCR worker or job.
python3 - <<'PY'
"""Fictional policy grant walkthrough; run with Bean importable.
Creates and deletes only its own temporary sandbox profile. No dispatch/job.
"""
from tempfile import TemporaryDirectory
from pathlib import Path
from bean.authority import AuthorityRegistry
from bean.contracts import Profile, Request
from bean.errors import Refusal
def main():
with TemporaryDirectory(prefix="policy-workflow-") as scratch:
profile = Profile.create(Path(scratch).resolve() / "profiles", "sandbox")
authority = AuthorityRegistry(app_id="pocket", owner="pocket")
authority.register_profile(profile)
request = Request(
"pocket", "pocket", "pocket-runner-loom", "ocr.pdf", "sandbox", "run",
{"jobId": "demo-job", "pageIds": ["demo-page"], "languages": ["en"]},
"policy-loom-1", result_schema="pocket.result/1",
)
grant = authority.issue("ocr-demo", request)
admitted = authority.authorize(request, grant)
assert admitted.profile_root == profile.root
print(f"authorized: {admitted.grant_id}, revision {admitted.grant_revision}")
authority.revoke(grant.grant_id)
try:
authority.authorize(request, grant)
except Refusal as error:
assert error.reason == "grant_revoked", error.reason
print(f"refused after revocation: {error.reason}")
else:
raise AssertionError("A revoked grant was admitted")
if __name__ == "__main__":
main()
PYSource: examples/policy-grant.py; bean/authority.py · register_profile, issue, authorize, revoke
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Revoked grant | Authorization refused | No work admitted | Issue a new authorized grant; do not reuse the revoked one. |
| Wrong owner or operation | Scope check refuses | No broadened access | Compare request ownership and operation family with the grant. |
| Invalid layout at registration | Registration refuses | No profile registered | Inspect the manifest and symlinks. Later authorization does not recheck the filesystem. |
| Actual-data profile requested | Provisioning refused here | No production access granted | Use the separately authorized actual-data path; this fixture registry is not that path. |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/authority.py · AuthorityRegistry.register_profile, create_profile | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/contracts.py · validate_request | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/authority.py · AuthorityRegistry.issue | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/authority.py · AuthorityRegistry.authorize, _validate_request_scope | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/authority.py · Refusal branches | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/authority.py · AuthorizedOperation | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/authority.py · AuthorityRegistry.revoke | See named source reference | workflow evidence | inspected source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|
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.
python3 -m pytest -q -p no:cacheprovider tests/test_bean_authority.py tests/test_110_authority.pyFixtures exercise grant scope, revocation, layout validation and refusal of actual-data provisioning.
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: Universal admission for every product operation, persistent grants, or integration with an installed Runner.
Observed in source. The registry validates app ownership, a fixed profile layout, and a current grant scoped to a profile, operation family and policy revision. Grants live in memory. They bind an operation family, not an individual operation name or selected item list. Layout is checked at registration; authorization does not repeat that filesystem check.
Limits and remaining work. Actual-data provisioning is explicitly refused here. RunnerAdapter.authorize and engine_host._serve_line use their own validation paths; neither calls this registry. A shared policy decision linking permission, selected resources and job creation remains a target, not an implemented universal route.
tests/test_bean_authority.pytests/test_110_authority.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Follow a selected phrase through preflight, removal and verification in a new PDF.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for PDF redaction.
Check every target before removing text
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
The inspected redactor removes supported PDF text operators and related text fields. It is not a general image-redaction or document-sanitization engine.
A supported text PDF, exact target strings and measured unrotated PDF coordinates are available.
A RedactionTarget uses a one-based page and unrotated content-stream coordinates, not screenshot pixels. The target text also identifies what to scrub from document-wide related fields.
bean/pdf/redact.py · RedactionTarget
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Resolve each target against actual text operators. Reject the entire request if a target is missing or a font, page rotation, overlapping object or attachment cannot be handled safely. No partial target success is advertised.
bean/pdf/redact.py · redact preflight
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Refusal is the correct result for an unsupported document. A visible black rectangle does not prove the underlying text or embedded content has been removed.
bean/pdf/redact.py · Refusal branches
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Rewrite supported content streams to remove the target strings and scrub those strings from related metadata, annotations, form fields and bookmarks across the document. Write a new copy.
bean/pdf/redact.py · redact
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The redactor verifies the output using independent extraction. Do not treat output-file creation alone as success. This check covers supported text removal, not every possible hidden representation of information.
bean/pdf/redact.py · redact verification
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
If the independent check cannot confirm removal, do not offer the copy as successfully redacted. Report the named reason so the caller can select another supported processing path.
bean/pdf/redact.py · verification refusal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return the output path and the removed target strings. Preserve the original separately and describe the supported scope to the user.
bean/pdf/redact.py · RedactionResult
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative supported text case. If that area contains an image, the current redactor refuses; it does not claim to remove the same number painted into image pixels.
{
"page": 1,
"text": "ACCOUNT-1234",
"coordinates": "measured in unrotated PDF space"
}{
"output": "fictional-statement-redacted.pdf",
"removed": [
"ACCOUNT-1234"
],
"original": "preserved"
}This API writes a new copy. The rectangle and paths illustrate the call; they are not valid targets for an arbitrary PDF. Use a disposable supported fixture, an unused output path and the required independent extractor.
from bean.pdf.redact import RedactionTarget, redact
target = RedactionTarget(page=1, rect=(72, 700, 220, 730),
text="ACCOUNT-1234")
result = redact("fictional-statement.pdf", [target],
"fictional-statement-redacted.pdf")Source: bean/pdf/redact.py · RedactionTarget, redact
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Screenshot coordinates used | Target may not match | Request refused | Convert to the supported PDF coordinate system. |
| Image overlaps target | Unsupported request | No claimed image redaction | Use a separately supported image-removal workflow. |
| One target unmatched | Whole request refused | No partial-target success | Verify every selected phrase and rectangle. |
| Text still extractable | Verification failure | Do not deliver as redacted | A visible covering box is not removal. |
| Verifier unavailable | Refused | No success claim | Restore the required verification dependency. |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · RedactionTarget | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · redact preflight | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · Refusal branches | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · redact | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · redact verification | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · verification refusal | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/redact.py · RedactionResult | See named source reference | workflow evidence | inspected source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|
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.
python3 -m pytest -q -p no:cacheprovider tests/bean_ai/test_pdf_redaction.pyFixture PDFs distinguish covering from removal, test source preservation, related-field scrubbing and unsupported cases.
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: Image redaction, every hidden information representation, or production UI coordinate mapping.
Observed in source. Each target identifies a one-based page, a rectangle in unrotated PDF coordinates and the exact text. All targets are checked before writing. Matching text is removed from content and scrubbed from annotations, forms, bookmarks and metadata.
Limits and remaining work. Overlapping images or Form objects, unsupported fonts, rotated pages, attachments and unmatched targets are refused. Image-based secrets require a different supported path; drawing a box on top is not secure removal.
tests/bean_ai/test_pdf_redaction.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Follow an ordered set of page photographs into one PDF, keeping a record of which images were excluded.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Photo to PDF.
Choose pages, straighten them and create a PDF
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
The inspected scan.pdf / run path resolves sandbox fixture captures or explicit fixture selections. It composes page selection, straightening and assembly in a durable job. It does not run OCR.
Sandbox captures or explicit fixture selections exist, with a disposable sandbox root and PDF dependencies.
Supply a captureId and optionally an explicit selection. When selection is present, it wins and retains the user’s order. Empty selections and unknown fixture identities are refused; no fallback silently broadens the request.
bean/operations.py · scan.pdf / run
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Use JobStore and JobRecovery to claim an attempt. A terminal replay returns the stored result. The current handler runs the scan inside its request while storing durable state; durable does not automatically mean an asynchronous request API.
bean/operations.py · scan.pdf / run, _run_pocket_scan_job
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
build_pageset preserves an explicit order or orders a capture set by its own rules. Record each inclusion or exclusion as a work-unit receipt before moving on. Page-set failure produces a failed job result.
bean/pockets/pagesets.py · build_pageset; bean/operations.py · _run_pocket_scan_job
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Straighten each included page photograph. A page that cannot be found is recorded as excluded. OcrPage is used as an assembly record with empty text and skipped OCR; the type name does not mean OCR ran.
bean/pockets/capture.py · straighten_page; bean/operations.py · _run_pocket_scan_job
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
If no pages survive, the job records partial with no_page_found and the exclusions. The operation returns refused. Do not offer an empty file as a completed PDF.
bean/operations.py · no_page_found branch
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
assemble_pdf consumes the surviving JPEG pages, embeds their bytes and creates a PDF artifact. Source hashes and a digest support the receipt. Assembly does not make the photographs searchable.
bean/pdf_assembly.py · assemble_pdf
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Complete under the current worker lease and return the durable result. Inspect excluded entries even on success: complete can mean a PDF of the pages that survived, not every selected image.
bean/operations.py · build_document_receipt and finalization
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Invalid selection is refused, a missing sandbox root is unavailable, and a page-set exception records failed. Other dependency or assembly exceptions must not be flattened into a successful PDF; the handler does not demonstrate a uniform recovery envelope for every exception.
bean/operations.py · scan.pdf / run and _run_pocket_scan_job
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative outcome. The inclusion reason comes from the actual page-set decision; this example is not an exact response schema. A successful PDF still reports the excluded photo.
{
"selection": [
"page-front",
"duplicate-front",
"page-back"
],
"order": "explicit"
}{
"pagesWritten": 2,
"excluded": [
{
"photo": "duplicate-front",
"reason": "page-set decision"
}
],
"ocr": "not run",
"searchable": false
}The public operation is scan.pdf / run in the sandbox Pocket path. The code excerpt is internal, not a standalone command. Do not substitute real-library paths for fixture IDs. OCR and searchable-PDF processing are separately requested features.
pageset = build_pageset(paths, preserve_order=explicit_order)Source: bean/operations.py · _run_pocket_scan_job
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Unknown/empty selection | Refused | No broader fallback | Use supported fixture identities and explicit order. |
| No sandbox root | Unavailable | No scan starts | Supply the expected disposable sandbox configuration. |
| No page survives | Job partial; operation refused | No PDF offered | Read no_page_found and each exclusion. |
| Some pages excluded | PDF can complete | Selected count differs from output | Compare inclusion/exclusion receipts with the original selection. |
| Terminal request replay | Stored result returned | No new successful work implied | Compare job identity and the saved result. |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py · scan.pdf / run | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py · scan.pdf / run, _run_pocket_scan_job | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pockets/pagesets.py · build_pageset; bean/operations.py · _run_pocket_scan_job | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pockets/capture.py · straighten_page; bean/operations.py · _run_pocket_scan_job | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py · no_page_found branch | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf_assembly.py · assemble_pdf | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py · build_document_receipt and finalization | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/operations.py · scan.pdf / run and _run_pocket_scan_job | See named source reference | workflow evidence | inspected source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|
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.
python3 -m pytest -q -p no:cacheprovider tests/test_pockets_pagesets.py tests/test_pocket_recovery.py tests/test_pdf_assembly.pyFixture tests cover page ordering, recovery and PDF assembly. They are separate checks of the composed path.
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: A production photo-library selection bridge, uniform scan job controls or searchable text.
Observed in source. Explicit selection order is preserved. Folder-style capture sets use page-set ordering. Included pages are straightened into JPEGs, assembled into a PDF and recorded in a document receipt with input hashes and exclusions.
Limits and remaining work. This source path resolves fixture IDs, not arbitrary personal-library handles. A production UI-to-library selection bridge and universal job controls are not established here. OCR is deliberately separate; a created scan is not automatically searchable.
tests/test_pockets_pagesets.pytests/test_pocket_recovery.pytests/test_pdf_assembly.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Follow a scanned page and its saved text boxes into a new PDF whose text can be selected and searched.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Searchable PDF.
Add text only where the stored read supports it
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
This is the existing-PDF overlay path in bean.pdf.searchable. Creating a new PDF from photographs is a separate feature. OCR supplies the read; this feature positions that saved text.
A scanned PDF and a successful saved read from that source are available, together with an independent text extractor.
Load the source PDF and its stored blocks. A missing sidecar or stored failed read is refused. The source is not overwritten; the output must be a new path.
bean/pdf/searchable.py · make_searchable, _load_blocks
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Inspect actual PDF text presence, page count, block bounds and supported text encoding. A sidecar label cannot override the bytes of a born-digital PDF. Multi-page blocks need page numbers that this contract does not yet carry.
bean/pdf/searchable.py · make_searchable; bean/ai/triage.py · pdf_text_presence
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Do not guess a text position, flatten a rotation or place all multi-page blocks on page one. Return the named refusal. Already born-digital input is also refused because adding an overlay would duplicate its text.
bean/pdf/searchable.py · pdf_searchable_* refusal branches
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Position the sidecar text on the supported page while preserving the visual source. Invisible text supports selection and search; it does not alter the source photograph or improve the OCR itself.
bean/pdf/searchable.py · make_searchable; bean/pdf/structure.py · _save_new
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Use the independent text extractor to compare the new reading order with the intended text. If verification fails, the operation must not be reported as successful. Inspect refusal handling before reusing a failed output path.
bean/pdf/searchable.py · _verify_reading_order
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A scrambled reading order or unavailable verifier is a named refusal. A file being present is not proof that this operation completed successfully.
bean/pdf/searchable.py · _verify_reading_order
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return SearchableResult with output path and block and byte counts after successful verification. This is a new artifact associated with the source, not a replacement of the original.
bean/pdf/searchable.py · SearchableResult
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative successful case. The same stored blocks on a two-page source are refused with pdf_searchable_multipage_unattributed, rather than positioned on the wrong page.
{
"input": "fictional-invoice.pdf",
"pages": 1,
"storedBlocks": 3,
"rotation": 0
}{
"output": "fictional-invoice-searchable.pdf",
"textSelectable": true,
"original": "unchanged"
}This API writes a new output PDF. The paths are fictional placeholders, not bundled fixtures. Supply a valid stored read from the same source, an unused output path and the PDF/text-extraction dependencies. This is not a claim that the example was run against these filenames.
from bean.pdf.searchable import make_searchable
result = make_searchable(
"fictional-invoice.pdf",
"fictional-invoice-searchable.pdf",
sidecar_path="fictional-invoice.sidecar.json",
)Source: bean/pdf/searchable.py · make_searchable
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No stored read | Refused | No accepted output | Create or locate a valid read for this source. |
| Multiple/rotated pages | Refused | No guessed placement | Per-page attribution and supported geometry are required. |
| Already digital PDF | Refused | No duplicated text overlay | Inspect actual PDF text, not only a sidecar label. |
| Extractor absent/order differs | Verification refuses | Do not offer file as successful | Inspect the verifier and output; choose a fresh path for another attempt. |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/searchable.py · make_searchable, _load_blocks | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/searchable.py · make_searchable; bean/ai/triage.py · pdf_text_presence | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/searchable.py · pdf_searchable_* refusal branches | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/searchable.py · make_searchable; bean/pdf/structure.py · _save_new | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/searchable.py · _verify_reading_order | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/pdf/searchable.py · SearchableResult | See named source reference | workflow evidence | inspected source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|
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.
python3 -m pytest -q -p no:cacheprovider tests/bean_ai/test_searchable.pyDisposable PDFs exercise text placement, reading order, source preservation and named refusals.
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: General multi-page or rotated input support, OCR quality, or an integrated export UI.
Observed in source. The source PDF and sidecar are checked before invisible text is overlaid. Real PDF bytes are inspected to avoid adding duplicate text to an already searchable document. Reading order is checked independently after writing.
Limits and remaining work. The current path refuses multiple pages because the saved blocks lack page attribution. It also refuses rotated pages, unsupported text encoding, invalid boxes and unavailable verification. General multi-page overlay needs an explicit per-page read contract before implementation.
tests/bean_ai/test_searchable.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Define provider-neutral identity, reads, writes, verification, resume and consistency.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Provider contract.
How every storage provider proves the same essentials workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers the public outcome and provider-neutral boundary. proposal-only unified contract.
A supported source and policy are known, or the feature reports that they are not implemented.
Name the source, intended operation and policy without assuming provider availability.
photo_vault/destinations.py · destination model precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Check stable identity, supported operations and policy before any write or restore.
photo_vault/destinations.py · destination model precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Execute only the declared provider operation and preserve partial, offline and retry state.
photo_vault/destinations.py · destination model precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
photo_vault/destinations.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return a provider-neutral, source-linked outcome that does not hide partial or unavailable work.
photo_vault/destinations.py · destination model precedent
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"request": "provider capability session",
"source": "fixture-source"
}{
"status": "proposal-only",
"receipt": null
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"request": "provider capability session",
"source": "fixture-source"
},
"after": {
"status": "proposal-only",
"receipt": null
}
}Source: photo_vault/destinations.py · destination model precedent
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No adapter/record implementation | Proposal-only/unavailable | Do not simulate success | Implementation status |
| Provider offline | Unavailable/retryable | Preserve pending state | Provider probe |
| Receipt cannot verify | Incomplete | Do not mark complete | Digest/identity evidence |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/destinations.py | destination model precedent | architecture precedent | proposal-only unified contract |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.adapter.local | implements locally | review when identity, receipt, retry, consistency or ownership semantics change |
| memory.adapter.network | implements for NAS | review when identity, receipt, retry, consistency or ownership semantics change |
| memory.adapter.cloud | implements for cloud | review when identity, receipt, retry, consistency or ownership semantics change |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordDocumentation checks prove the missing implementation is visible.
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: Any product implementation.
Observed in source. proposal-only unified contract.
Limits and remaining work. Implementation, product integration, tests and release evidence remain open.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Follow an image through a reader, then keep the text, its source and any unread pages together.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for OCR extraction.
Read each page and preserve uncertainty
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
This page follows the run_ocr page reader and RoutedOcr adapter. A document job can compose this work with preparation and storage; the OCR feature itself returns text and page evidence, not a finished PDF.
Ordered page inputs are available and an image reader is configured. PDF creation is outside this read operation.
Invalid identities, page order or metadata are rejected before the reader runs.
bean/document_pages.py · ordered_pages
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Create PageInput records for known source bytes. ordered_pages rejects an empty set, duplicate identities, invalid language or transform metadata and gaps in the one-based page order before any reader is called.
bean/document_pages.py · PageInput, ordered_pages
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
RoutedOcr accepts image pages and calls recognize_or_read. Recognized text and rough text remain different read results. A plain-text fixture reader is useful for deterministic tests but must not be called image recognition.
bean/ocr_adapters.py · RoutedOcr.read, recognize; bean/ocr_pdf.py · FixtureOcr
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Nonempty text is retained with its page citation and original bytes. Confidence may be absent; it must not be manufactured from a rough read. Citation metadata identifies the page, not a guarantee that every character is right.
bean/ocr_pdf.py · run_ocr, OcrPage
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
An empty reader result creates an abstained page with no citations. The batch may still be complete: complete means the pages were handled, not that every page yielded text.
bean/ocr_pdf.py · run_ocr
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Refusal marks the current page unsupported and remaining pages skipped, returning partial. WorkerUnavailable marks the remaining pages unavailable. Earlier page results are retained. Invalid reader result types or confidence are refused.
bean/ocr_pdf.py · run_ocr exception and result validation branches
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Continue page by page only while the adapter remains usable. Keep all page outcomes in order so the caller can distinguish extracted text from abstention and incomplete work.
bean/ocr_pdf.py · run_ocr page loop
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Consume the explicit aggregate and per-page statuses. A later workflow may analyze this text or turn it into a searchable PDF; neither is performed simply by receiving an OCR result.
bean/ocr_pdf.py · OcrResult; bean/document_jobs.py · document job integration
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative result summary, not the full wire schema. The blank back page is recorded honestly. The word complete does not turn the blank page into extracted text.
{
"pages": [
"invoice-front",
"invoice-back"
],
"reader": "configured image reader"
}{
"status": "complete",
"pages": [
{
"id": "invoice-front",
"status": "ok",
"text": "Invoice 42",
"citation": "invoice-front"
},
{
"id": "invoice-back",
"status": "abstained",
"text": "",
"citations": []
}
]
}The example uses fictional text bytes in memory. It exercises result handling, not image recognition. Durable document execution uses the existing ocr.pdf start integration; it is not a new CLI command invented for this page.
from bean.document_pages import PageInput
from bean.ocr_pdf import FixtureOcr, run_ocr
pages = [PageInput(page_id="demo-page", ordinal=1,
content=b"Invoice 42", mime_type="text/plain")]
result = run_ocr(pages, FixtureOcr())Source: bean/document_pages.py · PageInput; bean/ocr_pdf.py · run_ocr
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Invalid page order/identity | Request refused | Reader not called | Validate input before retrying. |
| Reader returns no text | Page abstained | No fabricated citation | Inspect the page outcome; blank is not a transport failure. |
| Unsupported page | Partial result | Earlier reads retained | Inspect the unsupported page and remaining skipped pages. |
| Reader unavailable | Unavailable result | Earlier evidence retained | Check the configured reader; do not replace missing evidence with text. |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/document_pages.py · ordered_pages | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/document_pages.py · PageInput, ordered_pages | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ocr_adapters.py · RoutedOcr.read, recognize; bean/ocr_pdf.py · FixtureOcr | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ocr_pdf.py · run_ocr, OcrPage | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ocr_pdf.py · run_ocr | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ocr_pdf.py · run_ocr exception and result validation branches | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ocr_pdf.py · run_ocr page loop | See named source reference | workflow evidence | inspected source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ocr_pdf.py · OcrResult; bean/document_jobs.py · document job integration | See named source reference | workflow evidence | inspected source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|
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.
python3 -m pytest -q -p no:cacheprovider tests/test_p85_f04_ocr_pdf_reads_or_abstains.pyThe read-or-abstain contract and page outcomes are exercised with controlled reader fixtures.
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: Recognition quality of a production model, searchable-PDF generation, or released UI compatibility.
Observed in source. Page identity and order are validated before reading. RoutedOcr calls the configured image reader and preserves the distinction between recognized text, rough text and reader failure. The fixture reader reads UTF-8 fixtures only; it does not recognize photographs.
Limits and remaining work. The low-level OcrPage result cannot express every rich reader distinction; RoutedOcr.reads retains it separately. UI integration and model-specific accuracy are not established by this source inspection. No reader result should be presented as guaranteed correct.
tests/test_p85_f03_routed_ocr_adapter.pytests/test_p85_f04_ocr_pdf_reads_or_abstains.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Name one operation, its items, caller, profile and result contract before any work is admitted.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Request composition.
Request composition and validation workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers request construction and structural validation. Permission and job creation occur in engine.job.policy and engine.job.lifecycle.
Stable item identities and an operation supported by the calling product are known.
The caller selects the requested outcome and stable item identities before transport.
bean/contracts.py · Request fields
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The application creates the request envelope without granting itself permission or assuming a worker.
bean/contracts.py · Request
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Structural validation rejects malformed identifiers, unsupported shape and inconsistent schema declarations before dispatch.
bean/contracts.py · validate_request
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A validation refusal returns to the caller with no admitted work and no inferred success.
bean/errors.py · Refusal
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A structurally valid request moves to policy admission. Valid structure does not prove authority, compatibility or completion.
bean/authority.py · AuthorityRegistry.authorize
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"appId": "vanilla",
"operation": "thumbnail.resolve",
"profile": "library",
"mode": "read",
"items": [
"photo-17"
]
}{
"validation": "valid",
"authorized": false,
"jobCreated": false
}Construct and validate through the supported application/Runner contract; this is not a standalone user CLI.
{
"request": {
"appId": "vanilla",
"operation": "thumbnail.resolve",
"profile": "library",
"mode": "read",
"items": [
"photo-17"
]
},
"result": {
"validation": "valid",
"authorized": false,
"jobCreated": false
}
}Source: bean/contracts.py · Request, validate_request
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Missing operation | Structural refusal | Correct the request | Request fields |
| Valid but unauthorized | Policy refusal | Do not retry as malformed | engine.job.policy |
| Result schema mismatch | Structural refusal | Use supported contract | Compatibility registry |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/contracts.py | Request, validate_request | direct implementation | observed source |
| vanilla unverified local checkout | lib/data/runner/loom_consumer_contract_tables.dart | consumer contract tables | request consumer metadata | supporting source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.job.policy | admits a valid request | identity, profile, policy or scope fields change |
| runner.route.submit | transports an admitted request | operation routing or envelope schema changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_bean_contracts.pyContract tests prove validation branches for the inspected Request schema.
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: Permission, dispatch, worker execution or product release support.
Observed in source. bean.contracts.Request and validate_request enforce identifiers, operation, profile, mode, payload and result-schema structure. Many product entry points still compose requests separately.
Limits and remaining work. A single product-facing composer and schema registry across all applications and operations remains intended architecture.
tests/test_bean_contracts.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Collect source-linked suggestions, let a person decide and preserve the correction for later work.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Review queue.
How uncertain results become human decisions workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers review items and decisions across vision features.
A producer has an uncertain or approval-required result.
A producer records uncertainty or a proposed action without mutating the source.
photo_vault/review.py · review records
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Queue and present the item with enough evidence to understand the decision.
photo_vault/review.py · review records
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
bean/review_queue.py · review queue
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Persist the explicit decision and route it back to the producing workflow.
photo_vault/review.py · review records
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"producer": "engine.vision.junk",
"photoId": "p-17",
"proposal": "junk"
}{
"decision": "reject",
"correction": "keep",
"sourcePreserved": true
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"producer": "engine.vision.junk",
"photoId": "p-17",
"proposal": "junk"
},
"after": {
"decision": "reject",
"correction": "keep",
"sourcePreserved": true
}
}Source: photo_vault/review.py · review records; bean/review_queue.py · review queue
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Missing source | Invalid item | Do not review detached claim | Source link |
| Decision not acknowledged | Pending | Do not apply action | Producer receipt |
| Same item duplicated | Deduplicate/idempotent | Keep one decision | Queue key |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/review.py | review records | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/review_queue.py | review queue | queue persistence | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.vision.junk | produces and consumes junk decisions | candidate evidence or decision options change |
| engine.vision.duplicates | produces ambiguous groups | group correction semantics change |
| engine.vision.people | consumes grouping corrections | person membership schema changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_review.py tests/test_review_queue.pyFixture tests cover queue records and review decisions.
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: All producers consume corrections or a released review UI.
Observed in source. review.py and bean/review_queue.py provide review records and queue behavior with named tests.
Limits and remaining work. A shared decision schema and released UI across every producer are not verified.
tests/test_review.pytests/test_review_queue.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Discover, identify and pair only a Runner whose protocol and product range match the application.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Runner compatibility.
Runner discovery and compatibility workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers installation identity, discovery and compatibility decision. It does not grant library access.
The application knows its required product and protocol range.
Find the product Runner without treating any responding process as compatible.
bean/runners.py · discovery
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The Runner reports stable identity and compatibility information.
runner/photovault_runner/pvr.py · identity
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The application compares its required protocol/product range with the Runner report.
bean/versioning.py · compatibility
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Missing, wrong-product and incompatible versions remain distinct setup outcomes.
bean/release_installer.py · installer boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
A compatible pair may exchange requests; permission and destination availability are still separate checks.
runner/photovault_runner/src/RequestTransport.swift
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It explains the boundary and is not an execution receipt.
{
"product": "vanilla",
"requires": "bean.compatibility/1"
}"paired"Use the supported Runner entry point with a disposable fixture. No personal library is used.
{
"application": {
"product": "vanilla",
"requires": "bean.compatibility/1"
},
"runner": {
"product": "vanilla-runner",
"protocol": "bean.compatibility/1"
},
"result": "paired"
}Source: bean/runners.py; runner/photovault_runner/pvr.py; RequestTransport.swift
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No endpoint | Runner missing | Offer install | Discovery |
| Wrong product | Product mismatch | Do not pair | Identity |
| Protocol too old | Incompatible | Offer verified update | Compatibility table |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/runners.py | Runner discovery | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | runner/photovault_runner/pvr.py | runner entry and identity | runtime identity | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/release_installer.py | release installer | setup/update | supporting source |
| pocket-runner unverified local checkout | src/RequestTransport.swift | RequestTransport | product transport | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| application.request.compose | uses the paired transport | protocol envelope changes |
| engine.job.policy | authorizes requests after pairing | identity or owner semantics change |
| application.consumer.document | depends on released forwarding support | Pocket Runner version changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_rq22_runner_icon.pyNamed tests prove the inspected identity/icon behavior only.
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: Signed distribution, update safety or cross-product release compatibility.
Observed in source. Runner identity, entry points, installer/release tooling and bean.compatibility/1 exist in source. Product pairing evidence varies by application.
Limits and remaining work. Signed release provenance and a single cross-product compatibility matrix need release-bound verification.
tests/test_rq22_runner_icon.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Review an exact removal plan, verify the source and record a recoverable outcome.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Safe removal.
How an approved photo is removed recoverably workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers sandbox-safe removal and receipts. Detection features only suggest candidates.
A reviewed plan and supported provider exist.
Show the precise identities and why each is proposed before mutation.
photo_vault/trash.py · trash operations
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Refuse non-sandbox or changed sources, perform the supported recoverable action and record each item.
photo_vault/trash.py · trash operations
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
photo_vault/sandbox_deletion.py · sandbox deletion provider
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return item-level outcomes and recovery evidence; partial work is not complete.
photo_vault/trash.py · trash operations
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"photos": [
"fixture-p1"
],
"approved": true,
"provider": "sandbox"
}{
"removed": [
"fixture-p1"
],
"recoverable": true,
"receipt": "r-1"
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"photos": [
"fixture-p1"
],
"approved": true,
"provider": "sandbox"
},
"after": {
"removed": [
"fixture-p1"
],
"recoverable": true,
"receipt": "r-1"
}
}Source: photo_vault/trash.py · trash operations; photo_vault/sandbox_deletion.py · sandbox deletion provider
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Provider is actual library | Refused | Never bypass | Provider guard |
| Source changed | Refused/stale | Re-plan | Identity digest |
| Some items fail | Partial | Show each result | Receipt |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/trash.py | trash operations | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/sandbox_deletion.py | sandbox deletion provider | safe provider | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| engine.vision.review | provides explicit approval | approval evidence or item identity changes |
| memory.copy.backup | may provide recovery copy | backup verification or retention policy changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_trash.py tests/test_sandbox_deletion.pyFixture tests cover sandbox boundaries and deletion behavior.
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: Production Photos-library mutation or recovery UI.
Observed in source. trash.py and sandbox_deletion.py implement removal boundaries; actual personal-library mutation is explicitly outside this documentation.
Limits and remaining work. Only the sandbox provider is verified; production provider behavior and recovery UI remain unapproved.
tests/test_trash.pytests/test_sandbox_deletion.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Transcribe supported audio into timestamped source-linked segments.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Speech transcription.
How recorded speech becomes time-linked text workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Proposal-only feature; no implementation was found beyond proposal references.
A future authorized audio source and model contract exist.
Select an authorized audio source and expected transcript schema.
bean/ai/amounts.py · speech proposal comment only
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Refuse unsupported or unauthorized sources before model work.
bean/ai/amounts.py · speech proposal comment only
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Proposed model work returns source-time-linked segments and abstention.
bean/ai/amounts.py · speech proposal comment only
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
bean/ai/amounts.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The proposed result preserves timestamps, confidence and source identity.
bean/ai/amounts.py · speech proposal comment only
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"audioId": "a-1",
"language": "en"
}{
"status": "proposal-only",
"segments": []
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"audioId": "a-1",
"language": "en"
},
"after": {
"status": "proposal-only",
"segments": []
}
}Source: bean/ai/amounts.py · speech proposal comment only
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| No worker | Unavailable | Do not fabricate text | Implementation status |
| Unsupported format | Refused | Convert explicitly | Audio contract |
| No timestamps | Invalid result | Reject | Transcript schema |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/ai/amounts.py | speech proposal comment only | non-implementation reference | proposal-only; no source record |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| runner.route.submit | future job transport | audio request contract is introduced |
| memory.sidecar.ai | future transcript persistence | annotation schema or retention changes |
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.
python3 -m pytest -q -p no:cacheprovider No product test — proposal-only architecture recordThe documentation check proves the proposal is visibly separated from implemented workflows.
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: Any speech transcription implementation.
Observed in source. No source-backed transcription worker or product route was verified.
Limits and remaining work. Audio contract, model selection, privacy, segmentation, persistence and UI all remain to be implemented.
No product test — proposal-only architecture recordBack to the architecture map · Authoring guidance is maintained in the repository template.
Choose a destination by policy and resolve it without exposing provider differences to Engine or AI.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Storage destinations.
How work uses local, network or cloud storage through one boundary workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers destination identity, policy, queueing and availability.
Destination policy and provider inventory are configured.
The caller names needs rather than a filesystem path.
photo_vault/destinations.py · destination model
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Memory chooses an eligible destination and adapter from current availability and policy.
photo_vault/destinations.py · destination model
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The adapter exposes supported operations and explicit offline or retry behavior.
photo_vault/disk_scheduler.py · disk scheduler
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The workflow returns an explicit unavailable or refused outcome without inventing content or mutating unrelated records.
photo_vault/destinations.py · refusal boundary
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
The caller receives provider-neutral results and never infers success from a path alone.
photo_vault/destination_queue.py · destination queue
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative contract summary using fictional identifiers. It does not claim product execution.
{
"purpose": "backup",
"preference": "local-or-nas"
}{
"destination": "fixture-volume",
"provider": "local",
"status": "ready"
}Use only the named disposable fixture or documentation check. No personal library is used.
{
"before": {
"purpose": "backup",
"preference": "local-or-nas"
},
"after": {
"destination": "fixture-volume",
"provider": "local",
"status": "ready"
}
}Source: photo_vault/destinations.py · destination model; photo_vault/disk_scheduler.py · disk scheduler; photo_vault/destination_queue.py · destination queue
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Drive missing | Unavailable | Do not use stale path | Adapter probe |
| Policy has no match | Refused | Ask for choice | Destination policy |
| Write accepted but unverified | Pending | Do not complete | Provider receipt |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/destinations.py | destination model | direct implementation | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/disk_scheduler.py | disk scheduler | local scheduling | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/destination_queue.py | destination queue | work queue | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.adapter.provider | defines provider-neutral operations | capability, receipt or consistency contract changes |
| memory.copy.backup | consumes destination sessions | copy policy changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_109_offline_and_footprint.pyFixtures cover selected local/offline behavior.
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: NAS or cloud adapters.
Observed in source. destinations, disk scheduler, destination queue and actual-library sources implement local/drive-oriented parts.
Limits and remaining work. Network and cloud providers and a complete provider contract are proposals.
tests/test_109_offline_and_footprint.pyBack to the architecture map · Authoring guidance is maintained in the repository template.
Turn a text or example-photo query into ranked, source-linked photo results.
Read the generated views in order: context, overall lifecycle flow, then state and outcomes. Use the wheel to zoom, drag to pan, and double-click to fit.
Components, ownership and boundaries for Visual search.
How a description finds matching photos workflow
Meaningful progress, refusal, recovery and terminal outcomes from the authored workflow.
Illustrative journey · select a step for its explanation.
Workflow draft for owner review · source-inspected, not a verified product release.
Bean source revision b22a3830ffe0b2db87865aaaf83584e9a4e2b085. Application and Runner release compatibility: unverified.
Covers embedding-backed retrieval and honest unavailable states.
A compatible embedding model and indexed library revision exist.
Compose a query without changing library records, source files or the current embedding index.
photo_vault/ml/clip.py · CLIP adapter
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Create the query representation and rank source-linked photo embeddings from the compatible index.
photo_vault/ml/clip.py · CLIP adapter
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Uncertain, incomplete or user-sensitive results remain reviewable with their source identity and reasons.
bean/embedding_jobs.py · embedding job
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Return ranked stable photo IDs and enough model/index metadata to explain unavailable or stale results.
photo_vault/ml/clip.py · CLIP adapter
Inspected at the Bean revision listed above. This identifies source behavior; it is not release certification.
Illustrative fixture summary. It explains the contract and is not a receipt from a personal library.
{
"query": "red bicycle"
}{
"matches": [
{
"photoId": "p-8",
"score": 0.84
}
],
"indexRevision": "fixture-1"
}Run only the named fixture tests against disposable data. This documentation does not authorize work on a personal photo library.
{
"before": {
"query": "red bicycle"
},
"after": {
"matches": [
{
"photoId": "p-8",
"score": 0.84
}
],
"indexRevision": "fixture-1"
}
}Source: photo_vault/ml/clip.py · CLIP adapter; bean/embeddings.py · embedding store; bean/embedding_jobs.py · embedding job
| Condition | Result | Caller interpretation | Check next |
|---|---|---|---|
| Index missing | Unavailable | Offer indexing | Embedding jobs |
| Model mismatch | Unavailable | Do not mix vectors | AI contract |
| Deleted result | Stale index | Hide and repair | Catalogue revision |
| Repository | Path | Symbol | Relationship | Evidence |
|---|---|---|---|---|
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | photo_vault/ml/clip.py | CLIP adapter | model adapter | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/embeddings.py | embedding store | index | observed source |
| bean-engine b22a3830ffe0b2db87865aaaf83584e9a4e2b085 | bean/embedding_jobs.py | embedding job | index builder | observed source |
Revision-bound evidence and executed checks are recorded in the documentation delivery tracker.
| Workflow | Relationship | Review when |
|---|---|---|
| memory.workspace.catalogue | supplies current photo identities | catalogue revision or deletion semantics change |
| engine.job.lifecycle | runs embedding backfill | checkpoint or retry behavior changes |
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.
python3 -m pytest -q -p no:cacheprovider tests/test_ml.py tests/test_109_clip_embeddings.pyFixture tests cover embedding and CLIP adapter behavior.
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: Ranking quality or released model availability.
Observed in source. ml/clip.py, ai_contract.py, embeddings.py and embedding_jobs.py implement parts of query and index work.
Limits and remaining work. Model compatibility, index freshness and released product ranking evidence remain unverified.
tests/test_ml.pytests/test_109_clip_embeddings.pyBack to the architecture map · Authoring guidance is maintained in the repository template.