ADR 0007: v1 Worker Protocol, Artifacts, and Idempotency
Status: proposed Date: 2026-05-10
Context
Memories uses workers for long-running media and ML jobs, but the Core API must remain authoritative for domain state, authorization, storage records, and user-visible processing state.
The v1 worker boundary already prohibits direct PostgreSQL writes, stored-original mutation, and worker-created StoredObject, OriginalAsset, or MediaItem records. Before task generation, the protocol also needs explicit decisions for versioning, derived artifact upload, and retry-safe result submission.
Decision
Use a small Core API-owned worker protocol with explicit version negotiation, Core API-mediated artifact upload, and idempotent result submission.
v1 supports exactly worker-protocol-v1. Workers include supported protocol versions when claiming jobs. The Core API leases jobs only when it can select a compatible protocol version and returns the selected version with the job. Future incompatible protocol changes create a new protocol version; additive optional fields are allowed within v1 only when old workers can safely ignore them.
The Core API owns final storage keys and authoritative records for derived assets, candidate metadata, face annotations, processing issues, audit events, and job completion. Workers are stateless executors that may read job-granted original inputs, produce local temporary outputs, upload those outputs as job-scoped artifacts through the Core API, and submit candidate result manifests.
Workers never write final paths under library/stored-objects or library/derived/v1. readonly_mount remains read-only original access only. Direct worker writes to final derived cache paths are not a v1 optimization.
Artifact Flow
For derived assets and other binary worker outputs:
- Worker claims a job and receives selected protocol version, input version, and media access grant.
- Worker reads only the leased input through the granted access mode.
- Worker creates a job-scoped artifact through the Core API with proposed type, variant, MIME type, byte size, and SHA-256 hash.
- Worker uploads artifact bytes to the Core API artifact endpoint.
- Core API stores bytes in artifact staging, verifies size/hash and basic type expectations, and marks the artifact uploaded.
- Worker submits a result referencing the uploaded artifact.
- Core API validates the result against the active job, input version, source stored object/hash, and artifact metadata.
- On acceptance, Core API promotes bytes to the final derived key and creates or updates the
DerivedAssetrecord.
Derived artifacts remain cache and are not required for fidelity restore, but their database records must tolerate missing/stale files and support regeneration.
Idempotency Rules
Worker result submission is idempotent by (workerJobId, idempotencyKey).
Retries with the same key return the same accepted or rejected outcome and do not create duplicate WorkerJobResult, DerivedAsset, candidate metadata, or ProcessingIssue records.
For derived assets, Core API acceptance is also naturally unique by media item, derived type, variant, generation version, source stored object, and source content hash. Replayed results for the same derived identity are no-ops or return the existing accepted result. Results for expired leases, wrong worker credentials, stale input versions, or mismatched artifacts are rejected unless the same idempotency key was already accepted.
Issue results are idempotent and must not spam duplicate visible processing issues when a worker retries submission after a timeout.
Consequences
- Worker protocol assumptions become testable contract behavior rather than hidden implementation detail.
- Core API owns final artifact placement, stale detection, cleanup, and future storage backend compatibility.
- Remote workers and same-host workers use the same authoritative result path.
- v1 gives up direct worker writes to
library/derived/v1for simplicity and correctness. - Artifact staging needs cleanup for abandoned, rejected, and superseded artifacts.
- Denied worker lease/grant access is persisted as Core API audit data and surfaced in the Super Admin operator dashboard. This improves operability without giving operators media-owner privacy bypass powers.
Deferred
v1 defers direct-to-object-storage signed artifact uploads, direct worker writes to designated staging mounts, protocol v2 compatibility, dynamic per-job bind mounts, resumable artifact upload, untrusted worker sandboxes, and GPU worker scheduling.
Revisit Triggers
Revisit this decision when adding object storage, large video transcodes that make Core API-mediated artifact upload too expensive, remote GPU workers, resumable artifact uploads, or incompatible worker protocol changes.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference