feat(people): per-face crops via generic discovery thumbnail job (ADR 0095) #709

Merged
chris merged 1 commit from feature/face-crop-revival into main 2026-09-06 14:06:30 +02:00
Owner

Summary

Revives per-face thumbnail (crop) generation by extending the generic generate_discovery_thumbnail pipeline — no domain-specific job type reinstated (ADR 0094 generality kept). Recorded in ADR 0095 (docs/adr/0095, accepted). Also fulfills the thumbnail slice of spec 014 S014T003 by removing the deprecated legacy per-face path instead of reanimating it.

Worker (apps/worker-media)

  • generateDiscoveryThumbnail face mode: crops 256+512, variants face-{id}-{size}, gen face-thumbnail-v1, result carries faceAnnotationId + complete flag; job finalizes on the 512 upload only. Instance mode byte-identical to before.
  • CoreApiWorkerClient: per-variant idempotency-key discriminator extended to discovery_thumbnail (two submissions per face job must not collide).
  • Deleted generateFaceThumbnail + generate_face_thumbnail dispatch case; capability removed from WorkerProperties.

API (apps/api)

  • acceptDiscoveryThumbnail branches on faceAnnotationId → owner-checked resolve, upsert derived_assets(face_thumbnail), UPDATE discovery_results SET thumbnail_derived_asset_id (people domain). Instance path unchanged. shouldCompleteJob: complete-flag honored for discovery_thumbnail (256 partial does not finalize).
  • enqueueMissingFaceCropJobs(+ForMedia): photo-only, state accepted/owner_recognized, pointer IS NULL, idempotent (existing 512 asset / active job skip). FaceCropBackfillScheduler trickles 100 faces per 5 min. Acceptance triggers per-media enqueue adjacent to the existing thumbnail-enqueue call sites.
  • Removed deprecated path end-to-end: acceptFaceThumbnail, canonicalFaceThumbnailVariant, faceThumbnailPayload, enqueueMissingFaceThumbnailJobs, generate_face_thumbnail from credential bootstrap / resource policy / maintenance lists / processing summary / compose.yaml capabilities.

Ops notes

  • Backfill volume: ~4,466 faces on the owner instance → ~8,900 files at 100/5min (~4h trickle). Storage growth ~2 files/face.
  • Serving endpoint unchanged (DerivedAssetController resolves pointer OR face-{id} variant) — legacy 51k assets keep working; PR #708 URL guards light up automatically as the pointer fills.

Tests

  • Worker: 4 new/updated MediaJobHandlersTest cases (dual-size face crops + complete flag, instance mode unchanged, legacy bbox unwrap, HEIC decode failure)
  • API: 5 enqueue tests (payload/idempotency/state filters/existing-asset guards), 3 acceptance tests (256 no-finalize → 512 finalize + discovery pointer set + class_instances untouched, other-owner rejected)
  • Full module run: 789 tests, 0 failures, 9 pre-existing skips
## Summary Revives per-face thumbnail (crop) generation by extending the generic `generate_discovery_thumbnail` pipeline — no domain-specific job type reinstated (ADR 0094 generality kept). Recorded in **ADR 0095** (docs/adr/0095, accepted). Also fulfills the thumbnail slice of spec 014 S014T003 by *removing* the deprecated legacy per-face path instead of reanimating it. ### Worker (apps/worker-media) - `generateDiscoveryThumbnail` face mode: crops 256+512, variants `face-{id}-{size}`, gen `face-thumbnail-v1`, result carries faceAnnotationId + complete flag; job finalizes on the 512 upload only. Instance mode byte-identical to before. - `CoreApiWorkerClient`: per-variant idempotency-key discriminator extended to discovery_thumbnail (two submissions per face job must not collide). - Deleted `generateFaceThumbnail` + `generate_face_thumbnail` dispatch case; capability removed from WorkerProperties. ### API (apps/api) - `acceptDiscoveryThumbnail` branches on faceAnnotationId → owner-checked resolve, upsert derived_assets(face_thumbnail), `UPDATE discovery_results SET thumbnail_derived_asset_id` (people domain). Instance path unchanged. `shouldCompleteJob`: complete-flag honored for discovery_thumbnail (256 partial does not finalize). - `enqueueMissingFaceCropJobs(+ForMedia)`: photo-only, state accepted/owner_recognized, pointer IS NULL, idempotent (existing 512 asset / active job skip). `FaceCropBackfillScheduler` trickles 100 faces per 5 min. Acceptance triggers per-media enqueue adjacent to the existing thumbnail-enqueue call sites. - Removed deprecated path end-to-end: acceptFaceThumbnail, canonicalFaceThumbnailVariant, faceThumbnailPayload, enqueueMissingFaceThumbnailJobs, generate_face_thumbnail from credential bootstrap / resource policy / maintenance lists / processing summary / compose.yaml capabilities. ## Ops notes - Backfill volume: ~4,466 faces on the owner instance → ~8,900 files at 100/5min (~4h trickle). Storage growth ~2 files/face. - Serving endpoint unchanged (DerivedAssetController resolves pointer OR face-{id} variant) — legacy 51k assets keep working; PR #708 URL guards light up automatically as the pointer fills. ## Tests - Worker: 4 new/updated MediaJobHandlersTest cases (dual-size face crops + complete flag, instance mode unchanged, legacy bbox unwrap, HEIC decode failure) - API: 5 enqueue tests (payload/idempotency/state filters/existing-asset guards), 3 acceptance tests (256 no-finalize → 512 finalize + discovery pointer set + class_instances untouched, other-owner rejected) - Full module run: 789 tests, 0 failures, 9 pre-existing skips
feat(people): per-face crops via generic discovery thumbnail job (ADR 0095)
All checks were successful
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 / Build people worker image (push) Has been skipped
Build and Deploy / Build converter worker image (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 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 / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Build plants worker image (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 2m6s
cff9617088
Revive per-face thumbnail generation by extending the generic
generate_discovery_thumbnail pipeline instead of reinstating the
domain-specific generate_face_thumbnail job (ADR 0094 generality kept).

- Worker: face mode renders 256+512 crops, variants face-{id}-{size},
  gen face-thumbnail-v1, result carries faceAnnotationId+complete flag;
  job finalizes on the 512 upload only. Instance mode unchanged.
- API: acceptDiscoveryThumbnail branches on faceAnnotationId ->
  derived_assets(face_thumbnail) + discovery_results pointer update
  (owner-checked); instance path unchanged. CoreApiWorkerClient uses
  per-variant idempotency keys for the dual submissions.
- Enqueue: enqueueMissingFaceCropJobs(+ForMedia), photo-only,
  state accepted/owner_recognized, idempotent (existing 512 asset or
  active job skips); FaceCropBackfillScheduler trickles 100/5min;
  acceptance triggers enqueue per affected media.
- Removed deprecated legacy path end-to-end: generateFaceThumbnail,
  acceptFaceThumbnail, canonicalFaceThumbnailVariant, faceThumbnailPayload,
  enqueueMissingFaceThumbnailJobs, generate_face_thumbnail capability
  registrations (bootstrap, compose, resource policy, maintenance lists).

ADR: docs/adr/0095 (accepted). Spec 014 S014T003 thumbnail slice
fulfilled; broader legacy removal stays pending.
chris merged commit 4e46423de7 into main 2026-09-06 14:06:30 +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!709
No description provided.