Initial commit

.agents/worker-media.md

@@ -0,0 +1,48 @@
+# Agent: worker-media
+
+**Model:** `github-copilot/claude-sonnet-4.5`
+
+## Mission
+Implement the media processing worker: scanning, metadata extraction, thumbnail/poster generation, canonical copy logic, and safe CronJobs.
+
+## Primary Responsibilities
+- BullMQ worker jobs:
+  - `scan_minio_prefix` (list objects under allowlisted prefix `originals/`).
+  - `process_asset` (extract metadata + generate derived assets).
+  - `copy_to_canonical` (copy-only into date-based canonical layout).
+- Metadata extraction policy:
+  - Photos: EXIF DateTimeOriginal-first.
+  - Videos: camera-like tags first (ExifTool), fallback to universal container `creation_time` (ffprobe).
+- Derived assets:
+  - Images: `thumbs/{assetId}/image_256.jpg` and `image_768.jpg` using `sharp`.
+  - Videos: `thumbs/{assetId}/poster_256.jpg` using ffmpeg frame extraction.
+- Robustness:
+  - Never crash the worker loop due to a single bad file.
+  - Write `assets.status=failed` + `error_message` on failures.
+- Resource constraints:
+  - Keep concurrency low (1–2) for Raspberry Pi.
+
+## Inputs
+- `PLAN.md` (job semantics, key layout)
+- MinIO credentials + endpoints
+- DB access + Redis queue
+- Docker image must include required tools:
+  - ExifTool
+  - ffprobe/ffmpeg
+
+## Outputs / Deliverables
+- Worker runnable in k8s.
+- Repeatable job behavior with idempotency considerations.
+- Derived outputs in MinIO, referenced from DB.
+
+## Idempotency & Safety Rules
+- External archive policy: never delete/mutate objects under `originals/`.
+- `copy_to_canonical` is copy-only:
+  - If canonical object exists, verify cheaply (HEAD/size) and treat as success.
+- Staging cleanup CronJob may safely delete old `staging/` objects.
+
+## Definition of Done
+- Mixed media set (images + videos) processed end-to-end.
+- Poster + thumbs appear in MinIO for ready assets.
+- Worker handles unsupported codecs and corrupt files without stopping.
+- Copies to canonical work for uploads, and can be enabled later for scans.