[devjerry0]

Summary

Queues authenticated draft previews through the existing URL-hash cache. Publication reuses fetched metadata and grants transient draft failures one bounded retry cycle.

Stack 4/6, split from closed #891. Depends on feat/external-gif-playback. This PR is in the fork to keep the review diff limited to this layer; open it upstream after its dependency lands.

Changes

Diff against this PR's base: 19 files, +1,110/-35. 72% of changed lines are tests, fixtures, or test support.

• Use the existing URL-hash row and queue; separate cache-read and new-work rate limits, with user/host-only audit logs.
• Add failure/retry state with atomic publication claims and generation checks. Definitive outcomes remain cached.
• Unique dispatch and serialized workers prevent duplicate fetches; real PostgreSQL/process tests cover concurrency and foreign-key access.

Visual explanation

flowchart TD
    D["Authenticated, validated draft URL"] --> C{"Shared URL-hash cache"}
    C -- Hit --> R["Return cached or pending preview"]
    C -- Miss --> N["Create shared row"]
    N --> Q["Queue UnfurlLink for this row"]
    Q --> W["Unique job and serialized worker"]
    W --> F["Guarded fetch and metadata completion"]
    F --> R
    R --> P["Publication reuses the same row"]
    P -- Recorded transient failure --> T["One atomic publication retry"]
    T --> Q

Loading

Stack and merge order

1. Fetch boundaries and service contract — upstream
2. External GIF verification
3. Inline GIF playback
4. Cached, queued draft API
5. Composer link previews
6. Optional mutation checks

Layers 2–6 target their immediate predecessor in the fork. Submit them upstream in order after their dependency lands; each review diff contains only its layer.

Validation

PreviewLink now lives under App\Contracts\Services (namespace-only follow-up, head d4daa17f998a820dd163d10f1b1382517dbc1430). Focused fetching/verification suites and the final stack’s required checks passed after the move; the earlier per-layer results and implementation review below remain the baseline.

Container checks passed on PHP 8.5.12: 4,650 PHP tests / 25,764 assertions, 100% PHP coverage and type coverage, 223 Node tests, and 631 component tests across 50 files. PHPStan, TypeScript, lint, and production build pass (19 lint warnings, no errors).

Lint: Pint, Rector --dry-run --debug (same rules, serial execution), and Bun lint. Other commands: composer test:types, composer test:type-coverage, full parallel Pest CI coverage at exactly 100%, bun run test:unit, and bun run build.

No UI or mobile interaction changes in this layer.

Independent review

Independent code review: PASS, base b8d3f368a56be51feb0d414d0b6a821565b5d34a, head 5277cd0fc4549392fb4899e830f7505df7664d52. Visual review is inapplicable to this backend/tooling-only layer.

Limitations

Hosted CI has not been verified for this new PR. Workers hold the row lock during DNS/HTTP to serialize fetches. Releasing it safely needs a durable claim and crash recovery; synchronous DNS remains outside the HTTP deadline. Selected draft URLs and metadata remain in the shared cache even if never published. The URL is sent as a query parameter, so deployment access logs may contain it; host-only logging applies to the structured application audit line.

Codex-Thread: 01a15b08-d4ad-7e72-8725-b3ea1fde71ce