feat: responsive focal-crop, churn winback, ve-locking, and gauge voting

[privexlabs]

Summary

Resolves four architecture and integration spike tracks (#551, #552, #553, #554) behind dedicated feature flags (phase-142, phase-143, phase-144, phase-145) following the repository's modular rolling-delivery convention:

• Spike 688 (# Spike 688 — AI thumbnail and crop generation with focal-point-aware variants #551): AI thumbnail and crop generation with focal-point-aware variants, computing crop bounding boxes constrained to source dimensions and preserving focal interest across standard aspect ratios (thumbnail, preview, banner, portrait, landscape, og) behind phase-142.
• Spike 689 (# Spike 689 — AI-driven churn and winback with dormant detection plus experiments #552): AI-driven churn and winback engine with temporal dormancy tiering (active, at-risk, mild, deep, churned), activity-grounded reactivation hooks, deterministic experiment cohorts (control, quest_bonus, fee_discount, social_digest), and a 7-day fatigue cap behind phase-143.
• Spike 690 (# Spike 690 — ve-PHASELQ locking with time-locked weight plus fee share #553): ve-PHASELQ governance locking escrow with linear time-weighted decay (1 to 208 weeks), SQLite state tracking, and pro-rata treasury fee-share checkpoint accumulator and claims behind phase-144.
• Spike 691 (# Spike 691 — Gauge voting for emissions with ve-weight directing quest budgets #554): Gauge voting for emission budget allocation, enabling ve-PHASELQ lockers to cast percentage-weighted votes directing weekly quest emissions across collections with epoch aggregation behind phase-145.

Changes

• lib/feature-flags.ts: registered flags phase-142, phase-143, phase-144, and phase-145.
• lib/security-counters.ts: added closed-cardinality observability counters for variants, crops, winback dispatches, ve-locks, and gauge votes.
• lib/sqlite-db.ts: added ve_locks, ve_fee_distribution, gauge_votes, and gauge_epoch_aggregates tables with indexed lookups.
• lib/server-data-paths.ts: registered winbackExperiments sidecar path.
• lib/focal-crop.ts: focal point normalization, aspect crop rectangle math, and artifact metadata variant generation.
• lib/churn-winback.ts: wallet dormancy classifier, cohort assignment, fatigue cooldown checks, and winback campaign evaluator.
• lib/ve-phaselq.ts: ve-weight calculation, lock creation/decay tracking, fee distribution, and pro-rata claim settlement.
• lib/gauge-voting.ts: epoch gauge voting, aggregate ve-weight tallies, and quest emission budget allocation.
• app/api/ipfs/[...cid]/route.ts: added support for focal-crop variant transform query parameters.
• components/ipfs-display-img.tsx: added variant and focalPoint support for bandwidth-efficient responsive rendering.
• lib/forge/ipfs-publisher.ts: enriched forge metadata with artifact variants when publishing.
• app/api/notifications/winback/route.ts: GET and POST endpoints for winback campaign evaluation and dispatch.
• app/api/governance/ve-lock/route.ts: governance endpoint for locking, claimable fee calculations, and fee claims.
• app/api/governance/gauge/route.ts: gauge voting and epoch emission distribution endpoint.
• docs/spikes/688-thumbnail-crop-generation-findings.md: findings and architecture report for spike 688.
• docs/spikes/689-dormant-winback-experiments-findings.md: findings and architecture report for spike 689.
• docs/spikes/690-ve-phaselq-locking-fee-share-findings.md: findings and architecture report for spike 690.
• docs/spikes/691-gauge-voting-quest-emissions-findings.md: findings and architecture report for spike 691.
• PROJECT_ARCHITECTURE.md: updated §10 Feature Flags table for phase-142 through phase-145.
• docs/TECHNICAL.md: updated flag-gated extensions table.
• tests/focal-crop.test.ts: test suite for focal cropping, clamping, and URL transformation.
• tests/churn-winback.test.ts: test suite for dormancy tiers, deterministic cohorts, fatigue caps, and hook selection.
• tests/ve-phaselq-lock.test.ts: test suite for duration decay, lock extension, fee distribution, and expiry gating.
• tests/gauge-voting.test.ts: test suite for ve-weighted voting, 100% cap validation, epoch distribution, and ballot replacement.

Issues

Resolves #551
Resolves #552
Resolves #553
Resolves #554

Verification

• Manual code review completed: inspected git status, git diff --stat, and the full git diff.
• Verified that all changes are strictly additive, cleanly partitioned behind feature flags, and adhere to repository conventions.
• cargo build was not run.
• cargo test was not run.
• All new features default to disabled; zero regression when flags are off.

[drips-wave]

@privexlabs Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits