Fix document cover preview reliability

[BigSimmo]

Summary

• Resolve document cover previews from the selected committed generation and fail closed when legacy cover rows are stale, malformed, excessive, or ambiguous.
• Send the active authorization header and key cover cache/in-flight work by account and document; preserve authoritative misses while allowing transient lookups and settled image failures to recover.
• Hide only a failed optional cover after bounded automatic retries, while preserving the cited passage, source navigation, ordinary evidence, and original-PDF action.
• Add regression coverage for generation selection, auth transitions, cache races, retry settlement, late callbacks, and evidence preservation.

Verification

• npm run lint — passed after the final source fix (the later changes were a stable test mock and immutable review record)
• npm run typecheck — passed after the final source fix
• Focused Vitest selection — 5 files, 79/79 tests passed
• npm run build — production compile, TypeScript, 1,990 static pages, and client secret scan passed
• npm run check:repo-awareness-snapshot
• npm run check:branch-review-ledger
• npm run check:medication-interactions
• npm run check:medication-lexicon-report
• Offline RAG fixture contracts — 36 golden cases / 26 suites passed
• Adversarial fixture contract — 24 synthetic cases / 8 categories / 6 canaries passed
• Targeted Chromium answer/source journey passed on the implementation head
• npm run verify:pr-local — partial: runtime, installed-lock parity, changed-file formatting, lint, and typecheck passed. The full suite reported 10,489 passed / 75 skipped / 7 failed: six unchanged Windows-only Claude cloud provisioner failures (exit 127), plus one preview test whose unstable auth mock was then fixed and covered by the 79/79 focused rerun. Later offline Vitest selectors were admission-blocked by another worktree's Chromium lease.
• npm run verify:ui — not run; targeted Chromium coverage was used. Physical Safari/PWA remains unrun.
• UI verification not run: targeted Chromium answer/source journey passed; full verify:ui and physical Safari/PWA were not run.

Risk and rollout

• Risk: Low-to-moderate. An optional cover can now be omitted when selection is ambiguous or loading remains unavailable; the citation, passage, source controls, and PDF link remain available.
• Rollback: Revert this PR; no schema, migration, dependency, or hosted configuration change is involved.
• Provider or production effects: None.
• RAG impact: no retrieval behaviour change — this changes only authenticated cover lookup and optional image presentation, not retrieval, ranking, synthesis, or citation selection.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Notes

• Review ledger: docs/branch-review-records/04098ccb23c407505308b9e046181f8b978d85a4122db061e5b56a5f3cc0d988.record.md
• No provider calls, production mutations, deployment, or configuration changes were performed.

---

Note

Low Risk
Changes are limited to authenticated cover lookup and optional UI decoration; citation content and retrieval are unchanged, with conservative fail-closed cover selection when legacy data is ambiguous.

Overview
Improves optional document cover thumbnails in the answer source drawer without touching RAG or citation payloads.

The /api/documents/[id]/cover legacy path no longer delegates to fetchDocumentCoverImageIds. It queries bounded cover_page rows, picks the single candidate matching the document’s committed index generation, and returns null when results are stale, ambiguous, or exceed the cap.

useDocumentCoverImageId now sends the session Authorization header, keys cache and in-flight work by user + document, caches authoritative null misses but not transient errors or bad JSON, and exposes markCoverUnavailable so a settled signed-image failure drops the thumbnail without pinning “no cover” for the whole session.

SignedImage adds optional failurePresentation="hidden" and onSettledFailure (after automatic retries). The drawer uses that to remove a failed cover only while keeping passage, pager, evidence images, and PDF link intact.

Regression tests cover the cover route, hook auth/cache races, signed-image settlement, and drawer evidence preservation; a branch review ledger entry was added.

^{Reviewed by Cursor Bugbot for commit a8b981e. Configure here.}

[coderabbitai]

Warning

Review limit reached

Next included review available in 30 minutes.

View limit details

Limit details: You’ve used the included review currently available. Your 93 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 28478bb4-ae3d-414e-a3e8-1fa081da6fd2

📥 Commits

Reviewing files that changed from the base of the PR and between e126394 and 207f2eb.

⛔ Files ignored due to path filters (2)

• docs/branch-review-records/04098ccb23c407505308b9e046181f8b978d85a4122db061e5b56a5f3cc0d988.record.md is excluded by !docs/**, !**/*.md
• docs/branch-review-records/a3ef569d0937ef0d619ee26c491cf0bac4c4d808d1597a7d1969c1cd5fe49762.record.md is excluded by !docs/**, !**/*.md

📒 Files selected for processing (10)

• data/repo-awareness-snapshot.json
• src/app/api/documents/[id]/cover/route.ts
• src/components/clinical-dashboard/answer-source-drawer.tsx
• src/components/clinical-dashboard/signed-image.tsx
• src/components/clinical-dashboard/use-document-cover.ts
• tests/answer-source-marks.dom.test.tsx
• tests/answer-source-rail.dom.test.tsx
• tests/document-cover-route.test.ts
• tests/signed-image.dom.test.tsx
• tests/use-document-cover.dom.test.tsx

---

_{Comment @coderabbitai help to get the list of available commands.}

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:a8b981ea8b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BigSimmo]

@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. The only repository destination is BigSimmo/Database, and the only branch destination is the pull request head branch codex/chat-image-preview-reliability-image-preview-reliability at starting commit a8b981e; never publish fixes to a detached or synthetic work branch and never create a stacked pull request. Use the authenticated GitHub connector to commit each approved fix to BigSimmo/Database:codex/chat-image-preview-reliability-image-preview-reliability, then verify that the pull request head contains the published commit before reporting success. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. For a fixed thread, reply with as the first line and as the second line. For a no-code disposition, use followed by . These result markers authorize the workflow to close that exact thread only after it verifies a fixed commit is the pull request head; a local-only commit is not a fix. If publication or verification fails, do not use either result marker, do not claim success, and leave the thread open with the blocker. If human input or new authorization is required, do the same. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation.

[cursor]

Stale comment

Approved. Cursor Bugbot completed successfully with no findings that require human review. No reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Static PR checks — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #14008 (failure).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[chatgpt-codex-connector]

This request affects authenticated document access and credential rotation, which the repository classifies as an auth/privacy high-risk path requiring xhigh reasoning.

Please select xhigh in the Cloud reasoning control and resubmit the same request with the exact marker:

[xhigh-confirmed]

No repository inspection, edits, tests, commits, pushes, PR creation, or review-thread actions were performed.

View task →

[cursor]

Approved. Cursor Bugbot was not present after the first check poll, so that signal was skipped; no applicable approval policy requires human review. No reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[cursor]

Approved. Cursor Bugbot was not present after the first check poll, so that signal was skipped; no applicable approval policy requires human review. No reviewers assigned.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}