Distinguish four og:image outcomes to prevent blank cards

[Kaikei-e]

Summary

Refactors the og:image resolution pipeline to distinguish four distinct outcomes (resolved, settled refusal, transient failure, never reached) instead of collapsing them into a binary present/absent answer. This prevents cards from being permanently blanked when a resolution request times out but the image was successfully stored server-side.

Problem

When ResolveOgImages fetches a publisher's page inline behind a per-host slot, a batch that cannot finish within one RPC leaves the reader's request dead while images the server did reach are already written to the store. The old code treated "request timed out" as "origin has no image", leaving cards blank for the session even though the image existed one cheap re-ask away.

Key Changes

Protocol & Wire Contract

• Added UnresolvedOgImage proto message carrying feed_id and retry_after_seconds to distinguish refusal types
• Split ResolveOgImagesResponse into two parallel lists: images (resolved) and unresolved (refused or failed)
• Updated all proto-generated code across alt-backend, alt-butterfly-facade, rag-orchestrator

Frontend Resolution Logic

• Introduced OgImageOutcome type with three states: resolved (has URL), absent (settled refusal), unavailable (transient failure with optional retry bar)
• ogImageResolver now returns outcomes instead of raw URLs, allowing callers to distinguish "ask again later" from "this feed has no image"
• Added ogImageRetry module with exponential backoff ladder (capped at OG_RETRY_CEILING_MS) and full jitter to spread retries across the window
• Cards now re-ask on a bounded ladder when resolution fails, filling in images that arrived after the initial request timed out

Backend Retry Tracking

• FeedOgImageTarget now carries Attempts (how many resolution attempts spent) and RetryAfterSeconds (remaining bar from last refusal)
• SaveFeedOgImage takes pre-computed retryAfter duration to ensure reader and server agree on the same bar
• OgImageRefusal.RetryAfter(attempts) implements escalation logic: settled answers (robots.txt, no og:image tag, 404) stay permanent; transient failures escalate exponentially from a 5s base, capped at 6h; 403 stays flat at 24h

Storage & Projection

• No migration. No schema change. feed_og_images.attempts and feed_og_images.retry_after already existed (20260811000000_create_feed_og_images.sql). attempts was incremented on every upsert and read by nothing in the codebase — this PR starts reading it, and resets it to 1 on a resolution so a feed that succeeds for months does not carry a grown counter into its first failure. retry_after's remaining seconds are now surfaced to the caller
• The two fields added are on the proto message FeedOgImageTarget, not on the table
• Datahub gateway and wave3 handler updated to project both counters unchanged
• Pact contract (alt-backend ↔ alt-data-hub) updated to verify the counters survive the mapping

Testing

• Contract tests pin the four outcomes at the wire format (proto JSON round-trip), including that proto3's default-value omission drops a zero bar but keeps its unresolved row — the property that makes two lists work where a status enum would not
• E2E spec visual-preview-late-og-resolve.spec.ts verifies cards fill in when resolution completes after request timeout, and that the fallback is never shown on the way
• Backend handler test og_image_resolve_test.go verifies all four outcomes are emitted correctly
• Domain tests verify retry escalation and settled-answer permanence

Implementation Details

• Outcome encoding: the server uses list membership to signal the outcome, not a status field. A feed in neither list means the server never considered it (batch cap trimmed it, no row exists) — an answer that costs no wire symbol of its own, and that a status enum would force the server to emit a row for.
• Retry ladder: bounded by MAX_RESOLVE_ATTEMPTS (3) with full jitter. The server's base bar for a transient failure is 5s deliberately: OG_RETRY_CEILING_MS is 10s, so a longer base would put the first retry beyond what a browser tab will wait for and the client ladder would never run. A bar past the ceiling folds the card to its fallback rather than shimmering at a wait we have already decided not to honour.
• Overlay store: new ogImageOverlay holds URLs that arrived after cards were rendered, keyed by article id. It is a plain Map of one-field $state cells rather than a SvelteMap: SvelteMap.get() on an absent key subscribes to the whole-map version signal, and the first set() for any key bumps it, so a cold grid of N cards filling in costs O(N²) re-renders.
• No silent fallback: a missing retry bar or attempts count fails a test rather than degrading quietly (ADR-000928).

CDC scope

Rule 7 (CLAUDE.md) is satisfied at the boundary it is about. alt-backend ↔ alt-data-hub (GetFeedOgImageTargets) has a real Pact RED→GREEN — removing retryAfterSeconds from the provider stub fails verification. The browser leg has no Pact and does not need one: alt-frontend-sv is not a pacticipant in this repo, the SvelteKit /api/v2 route is a byte-forwarder that never decodes the message, and both sides are generated from one proto in one commit — so the DI-wiring failure mode ADR-000928 describes cannot occur there. That leg is guarded by src/test/contracts/, which this PR extends to cover ResolveOgImages for the first time.

https://claude.ai/code/session_01LCVkXfwJMinQZ7pQwimg8M

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.