feat(tasks): image variant preprocessing queue engine (BE-3 parts 1+2)

[Zheaoli]

BE-3 part 1 — variant preprocessing processor

Part of the image-performance overhaul (parent task #1). BE-3 (the bulk variant generation / backfill pipeline) is landing in parts for reviewability since it's the largest backend piece:

• Part 1 (this PR) — types + the per-image processor (generation + upload logic).
• Part 2 (next) — the queue orchestration: a preprocess-images task on the existing AdminTaskRun framework (cursor batching + lease + advisory lock + tick), mirroring service.ts.
• Part 3 (next) — backfill entries: a CLI drain script (pnpm run preprocess:backfill) for one-time bulk + a /admin/tasks button.

This PR

• types/admin-tasks.ts — ADMIN_TASK_KEY_PREPROCESS_IMAGES (AdminTaskKey is now a union), PreprocessTaskScope ({ force }), and its normalizer.
• server/tasks/image-preprocess.ts — preprocessImage(image, storage, signal):
  • Fetches the original (30s timeout + cancellation), generates responsive variants via BE-2's generateImageVariants, uploads them to BE-4's resolveVariantStorage backend.
  • Uploads tiers smallest-to-largest, advancing ready_max_width only past a tier whose avif AND webp both uploaded → the persisted value always points at a fully-available tier (the loader invariant @Picimpact-Review flagged).
  • Object key = {storageFolder}/{buildVariantKey(image_key, w, fmt)} so the public URL {variantBaseUrl}/{image_key}_{w}.{fmt} resolves (per BE-4 review).
  • variants_ready flips true only when every tier uploaded; partial failure keeps it false (persisting the partial ready_max_width) so the backfill scope re-picks the image — re-upload is idempotent via content-addressed keys.

Verification

• tsc --noEmit: no errors in the new file. eslint --fix: clean.
• End-to-end (real fetch + storage upload) will be exercised when part 2's queue drives a real backfill — there is no test harness / storage creds in this environment. The processor is pure-ish (storage client injected) and unit-testable.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
picimpact	Ready	Preview, Comment	May 30, 2026 11:58am

[Zheaoli]

Updated: added part 2 (queue orchestration) to this branch — server/tasks/image-preprocess-service.ts. Folding it in so the PR is the cohesive engine rather than merging an unused processor on its own.

The orchestration is a faithful mirror of the already-reviewed server/tasks/service.ts (metadata task), with preprocess-specific adaptations:

• Own advisory lock id 42012 (never contends with the metadata task); batch size 4 + lease 5m (variant gen is heavy); sequential within a batch to bound memory.
• Scope = non-deleted images, variants_ready=false unless force.
• Per image: resolve storage once per kick → preprocessImage → persist updates whenever present (not only success) per your part-1 feedback (point 1).
• create refuses when variant_storage unconfigured; kick fails with a clear error if the backend disappears mid-run.
• Full lifecycle preserved: lease + per-image advisory-locked checkpoint (lease refresh + cooperative cancel) + succeeded/failed/cancelled finalization + cursor resumability. Exports create/kick/tick/cancel/list/detail/previewCount.

tsc --noEmit + eslint clean. The processor portion (part 1) is unchanged from your approval. Reviewing tip: diff image-preprocess-service.ts against service.ts — the lifecycle logic is intentionally identical.

Part 3 (CLI preprocess:backfill + /admin/tasks button + hono endpoints) will follow and is where the real end-to-end backfill test happens.