feat(worker-media): profile_photo_crop derived asset handler (spec 057) #1149

Merged
chris merged 1 commit from feat/057-self-person-worker-crop into main 2026-10-12 20:29:55 +02:00
Owner

Summary (spec 057, S4 — WORKER lane, task S057T004)

Implements the profile_photo_crop job handler in apps:worker-media per the pinned cross-lane contract.

  • New ProfilePhotoCrop (mirrors the FaceScopeCrop pattern): job/derived-type constants, crop payload parsing, pixel-window geometry, and magic-byte container sniffing.
  • MediaJobHandlers: new case "profile_photo_crop" dispatch. Handler validates the payload, downloads the original (same media-access path as the existing crop handlers), decodes via decodeRegionSource (EXIF-orientation aware, ImageMagick for HEIC), renders square JPEG variants 256 and 512 (largest first; qualityScore computed once from the largest rendered crop like the face-crop path), then:
    1. uploads both artifacts first (every artifact endpoint requires an active job lease),
    2. submits one derived_asset result per variant (256 → 512, complete:false then complete:true) with derived_type="profile_photo", variant="256"/"512", generation_version=payload.generationVersion.
  • CoreApiWorkerClient: extracted static idempotencyKey(job, resultType, payload); per-variant discriminator now also applies to derived_asset results of profile_photo_crop only (all other job/result key shapes byte-for-byte unchanged).
  • Capabilities: profile_photo_crop added to the worker's default capability list (WorkerProperties, application.yml).
  • Re-crop: a new generationVersion makes upsertDerivedAsset write new (media, type, variant, generation) rows; old generations stay superseded — same regeneration semantics as face-scope crops. The worker never deletes rows.

Contract notes (cross-lane)

  • Job type: profile_photo_crop (string literal — apps/api has no shared job-type constants class, so no api constant was added).
  • Payload: {mediaItemId, cropX, cropY, cropSize, generationVersion} exactly as pinned.
  • Crop convention (width-anchored square): cropX = left/W, cropY = top/H, cropSize = side/W (side_px = size × width), position clamped into the raster. This matches the frontend lane's already-written apps/web/src/lib/utils/selfPersonCrop.ts + src/lib/api/self-person.ts docs — confirmed before implementing.
  • The pinned payload carries no detectedFormat, so the handler sniffs JPEG/PNG/HEIC magic bytes when the field is absent (HEIC still reaches the ImageMagick decode path).
  • Degenerate input flags the job failed exactly like existing handlers: missing mediaItemId/crop/generationVersion → invalid_worker_payload, undecodable/missing source → image_decode_failed, mediaType=video → unsupported/profile_photo_crop_for_non_photo.

Required api-side follow-ups (apps/api is owned by the parallel backend lane — NOT touched here)

  1. Result completion gap (blocking for the 512 variant): WorkerResultService.shouldCompleteJob completes a job on the first derived_asset result (only discovery_thumbnail honors a complete flag), and requireLease then rejects any further result. Until Core honors the complete flag this worker already sends (false/true), the second variant submission is rejected with missing_active_lease. The worker guards secondary submissions (warn + continue) so the worker loop never crashes; with the current API the 256 variant lands, the 512 variant is dropped. Recommended fix: honor an explicit payload complete boolean for derived_asset results (absent ⇒ true), exactly like discovery_thumbnail.
  2. Credential scope: add "profile_photo_crop" to WorkerCredentialBootstrap.ML_JOB_TYPES (or a Vxxx migration array_cat-ing worker_credentials.allowed_job_types, precedent V084/V095) — claims filter on worker.allowsJobType, so the job is otherwise unclaimable.
  3. Deploy capabilities: deploy/compose.yaml:145 sets MEMORIES_WORKER_CAPABILITIES explicitly for memories-worker-media; append profile_photo_crop there (out of this lane's write scope).
  4. Cosmetic (optional): ProcessingActivityLanes / JobEventsService.JOB_LABELS have no entry for this job type (it just won't show in a labelled activity lane).

Test evidence

rtk ./gradlew :apps:worker-media:test (from worktree root, fresh cleanTest run after rebase onto latest origin/main):

BUILD SUCCESSFUL in 6s
tests=52 failures=0 errors=0 skipped=0

12 new test cases, including: both square variants rendered at 256/512 with the cropped region's pixels verified, per-variant derived_asset payloads (complete, width/height, generationVersion, shared qualityScore), width-anchored window geometry + edge clamping, container sniffing, degenerate/sub-pixel crop, missing crop/generation, unreadable media, video media type, per-variant idempotency keys (existing key shapes asserted unchanged), and secondary-result rejection tolerance.

## Summary (spec 057, S4 — WORKER lane, task S057T004) Implements the `profile_photo_crop` job handler in `apps:worker-media` per the pinned cross-lane contract. - **New `ProfilePhotoCrop`** (mirrors the `FaceScopeCrop` pattern): job/derived-type constants, crop payload parsing, pixel-window geometry, and magic-byte container sniffing. - **`MediaJobHandlers`**: new `case "profile_photo_crop"` dispatch. Handler validates the payload, downloads the original (same media-access path as the existing crop handlers), decodes via `decodeRegionSource` (EXIF-orientation aware, ImageMagick for HEIC), renders **square JPEG variants 256 and 512** (largest first; `qualityScore` computed once from the largest rendered crop like the face-crop path), then: 1. uploads **both artifacts first** (every artifact endpoint requires an active job lease), 2. submits **one `derived_asset` result per variant** (256 → 512, `complete:false` then `complete:true`) with `derived_type="profile_photo"`, `variant="256"/"512"`, `generation_version=payload.generationVersion`. - **`CoreApiWorkerClient`**: extracted static `idempotencyKey(job, resultType, payload)`; per-variant discriminator now also applies to `derived_asset` results of `profile_photo_crop` only (all other job/result key shapes byte-for-byte unchanged). - **Capabilities**: `profile_photo_crop` added to the worker's default capability list (`WorkerProperties`, `application.yml`). - **Re-crop**: a new `generationVersion` makes `upsertDerivedAsset` write new (media, type, variant, generation) rows; old generations stay superseded — same regeneration semantics as face-scope crops. The worker never deletes rows. ## Contract notes (cross-lane) - Job type: `profile_photo_crop` (string literal — apps/api has no shared job-type constants class, so **no api constant was added**). - Payload: `{mediaItemId, cropX, cropY, cropSize, generationVersion}` exactly as pinned. - **Crop convention (width-anchored square)**: `cropX = left/W`, `cropY = top/H`, `cropSize = side/W` (side_px = size × width), position clamped into the raster. This matches the frontend lane's already-written `apps/web/src/lib/utils/selfPersonCrop.ts` + `src/lib/api/self-person.ts` docs — confirmed before implementing. - The pinned payload carries **no `detectedFormat`**, so the handler sniffs JPEG/PNG/HEIC magic bytes when the field is absent (HEIC still reaches the ImageMagick decode path). - Degenerate input flags the job failed exactly like existing handlers: missing `mediaItemId`/`crop`/`generationVersion` → `invalid_worker_payload`, undecodable/missing source → `image_decode_failed`, `mediaType=video` → `unsupported/profile_photo_crop_for_non_photo`. ## Required api-side follow-ups (apps/api is owned by the parallel backend lane — NOT touched here) 1. **Result completion gap (blocking for the 512 variant):** `WorkerResultService.shouldCompleteJob` completes a job on the **first** `derived_asset` result (only `discovery_thumbnail` honors a `complete` flag), and `requireLease` then rejects any further result. Until Core honors the `complete` flag this worker already sends (`false`/`true`), the second variant submission is rejected with `missing_active_lease`. The worker guards secondary submissions (warn + continue) so the worker loop never crashes; with the current API the **256 variant lands, the 512 variant is dropped**. Recommended fix: honor an explicit payload `complete` boolean for `derived_asset` results (absent ⇒ true), exactly like `discovery_thumbnail`. 2. **Credential scope:** add `"profile_photo_crop"` to `WorkerCredentialBootstrap.ML_JOB_TYPES` (or a `Vxxx` migration `array_cat`-ing `worker_credentials.allowed_job_types`, precedent V084/V095) — claims filter on `worker.allowsJobType`, so the job is otherwise unclaimable. 3. **Deploy capabilities:** `deploy/compose.yaml:145` sets `MEMORIES_WORKER_CAPABILITIES` explicitly for `memories-worker-media`; append `profile_photo_crop` there (out of this lane's write scope). 4. Cosmetic (optional): `ProcessingActivityLanes` / `JobEventsService.JOB_LABELS` have no entry for this job type (it just won't show in a labelled activity lane). ## Test evidence `rtk ./gradlew :apps:worker-media:test` (from worktree root, fresh `cleanTest` run after rebase onto latest `origin/main`): ``` BUILD SUCCESSFUL in 6s tests=52 failures=0 errors=0 skipped=0 ``` 12 new test cases, including: both square variants rendered at 256/512 with the cropped region's pixels verified, per-variant `derived_asset` payloads (`complete`, `width/height`, `generationVersion`, shared `qualityScore`), width-anchored window geometry + edge clamping, container sniffing, degenerate/sub-pixel crop, missing crop/generation, unreadable media, video media type, per-variant idempotency keys (existing key shapes asserted unchanged), and secondary-result rejection tolerance.
feat(worker-media): profile_photo_crop derived asset handler (spec 057)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m11s
1c4b964e21
- new ProfilePhotoCrop contract/geometry: width-anchored normalized crop
  (x=left/W, y=top/H, size=side/W, pinned with the web crop dialog), plus
  container sniffing so HEIC originals still reach the ImageMagick path
  (the pinned payload carries no detectedFormat)
- MediaJobHandlers dispatches profile_photo_crop: renders square JPEG
  variants 256/512 (largest first, qualityScore computed once from the
  largest crop like the face-crop path), uploads both artifacts while the
  lease is active, then submits one derived_asset result per variant
  (complete=false/true) with derived_type=profile_photo, variant=size,
  generation_version=payload.generationVersion
- CoreApiWorkerClient: extract static idempotencyKey(...) and extend the
  per-variant discriminator to profile_photo_crop derived_asset results
  (existing job/result key shapes unchanged)
- worker capability profile_photo_crop added to WorkerProperties and
  application.yml defaults
- tests: 12 new cases covering both variants (size + crop region colors),
  crop geometry/clamping, container sniffing, degenerate/missing payload
  and unreadable media flagging, idempotency keys, and tolerance of a
  rejected secondary variant result
chris force-pushed feat/057-self-person-worker-crop from 1c4b964e21
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m11s
to be0178cec2
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 2m3s
2026-10-12 20:18:51 +02:00
Compare
chris merged commit 5719a211e9 into main 2026-10-12 20:29:55 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1149
No description provided.