docs+test: correct the ordering-safe index claim, and make the near-bottom refusal guard non-vacuous

[BigSimmo]

Summary

Two independently low-risk follow-ups from the #1396 review, each its own commit and each separately revertible while this PR is open.

1. docs/operator-apply-performance-latency-remediation.md — correct my mislabelled "ordering-safe" index. Docs only; no SQL applied.

The runbook's 2026-07-29 correction identified the unordered LIMIT 12 in rag-candidate-sources.ts:482 as the RAG hazard for the additive documents indexes (ledger #102), then attributed it only to the bare-column trigram index and listed documents_status_id_idx as "ordering-safe". Re-reading the statement it describes:

query=query.or(filters).eq("status","indexed").limit(12);

One statement carries both the status equality and the unordered LIMIT 12 — and (status, id) is exactly the index serving that equality. The mechanism the runbook already documents applies to it verbatim: a new plan can return a different twelve title-alias rows into candidate assembly. Reclassified as canary-gated.

The generalisation that produced the error is named in the doc, because it is the reusable lesson: the index has two consumers. search-scope.ts:271-277 pages with an explicit .order("id") and is genuinely safe; rag-candidate-sources.ts:482 is unordered and is not. Safety of one consumer is not transitive to the other. The SQL block is now marked inline too — the prose gated the indexes while the block still listed all three with no distinction, and the block is what an operator actually copies.

2. tests/ui-phone-scroll.spec.ts — make the calculator near-bottom refusal guard non-vacuous, and rename it. Test only; no production behaviour changed.

The overlay branch of this test was moved until it passed during #1396, and nothing checked that its scroll position still exercised a refusal — so it could have stopped guarding anything silently. Both target offsets are now derived from computeScrollHideUpdate's own clauses rather than from chosen numbers, because the two motions refuse for different reasons:

in-flow runwayAfterCollapse <= revealIntentDistance + collapseRunwaySlack (12 + 96)
reserve-only offset > postCollapseMaxOffset + bottomClampTolerance

Non-vacuity assertions now run ahead of the behavioural check. "Chrome stayed visible" only evidences a refusal if the offset sat inside the refusal band and the other clauses were satisfied. The load-bearing one is postCollapseMaxOffset >= topRevealOffset + hideIntentDistance: without it, a short post-collapse range refuses the hide on its own, the near-bottom clause is never reached, and the test passes while proving nothing.

Renamed, because 96 is collapseRunwaySlack and that term exists only on the in-flow branch — reserve-only has no slack test at all. One test covers both owners, so the title now names the behaviour. Nothing outside the definition referenced the old name, so no flake-ledger identity is broken.

RAG impact: no retrieval behaviour change — item 1 changes only prose in an operator runbook and item 2 changes only a Playwright assertion. Neither applies an index nor touches retrieval, ranking, selection, alias or citation code. Item 1's effect on retrieval is the opposite of a behaviour change: it withdraws a claim that an index was safe to apply without a live eval-canary pair, making the documented gate stricter rather than looser.

Verification

• npm run verify:cheap — exit 0, Test Files 431 passed (431), Tests 4493 passed | 4 skipped (4497).
• npm run typecheck, npx prettier --check — clean.
• npm run docs:check-links — docs link check passed: 1381 repo path references resolve.
• npm run docs:check-scripts — docs script-ref check passed: 395 npm-run reference(s) resolve to real scripts.
• npm run check:branch-review-ledger after each main merge — 1296 table records … no conflict markers, mojibake, heading records, or duplicates (the merge=union duplication watch condition, ledger #088).
• The renamed journey, against an isolated production build: 1 passed.
• The new guard was checked against the broken shape rather than assumed non-vacuous. Removing the offset <= postCollapseMaxOffset + bottomClampTolerance clause from use-hide-on-scroll.ts makes the test fail on expect(frames.every(frame => !frame.headerHidden && !frame.dockHidden)).toBe(true). The policy file was restored and git diff confirmed clean.
• Item 1's claim was verified by reading src/lib/rag/rag-candidate-sources.ts:470-495 directly, not inferred from the runbook's own description.

That broken-shape check found a real defect in the guard, which is worth recording because it is the same class of error the guard exists to catch. The first version read scrollTopafter the frame loop. When the policy wrongly allows the hide, the reserve collapses, maxOffset shrinks and the browser clamps scrollTop — so the value intended as "the offset under test" became "the offset after the bug". A policy regression therefore surfaced as "the test setup is wrong" rather than as a behavioural failure. Fixed by capturing targetScrollTop before dispatching and never re-reading it; the second broken-shape run then failed on the behavioural assertion as intended.

Not run, and why: no browser gate applies to item 1. check:drift was not run because supabase/** is untouched. Every provider-backed gate (eval:*, verify:release, check:supabase-project, test:live) was not run and is not implicated — no OpenAI, Supabase or hosted-CI call was made in producing or verifying either item.

Risk and rollout

• Risk: Low for both, and asymmetric in the safe direction. Item 1 withdraws a safety claim rather than adding one, so getting it wrong leaves an index un-applied pending a canary rather than an unguarded index reaching production. Item 2 strengthens a test; its failure mode is a red gate, not shipped behaviour.
• The error item 1 fixes had the opposite asymmetry, which is why it was worth a PR: an operator following the previous text would have applied an index to the live Clinical KB Database believing it could not affect retrieval selection, and that belief was not established.
• Rollback: git revert either commit independently while this PR is open. Note that a squash merge would fold them into one, so a post-merge revert of a single item means reverting hunks by hand. No migration, schema, data, or configuration change in either.
• Provider or production effects: none.

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 on the above: this PR changes runbook prose and one Playwright assertion, so every item is satisfied by construction rather than by inspection of new behaviour. No answer generation, citation, verification, source-governance or document-access code is touched; no credential or Supabase value appears in the diff; the pinned Supabase target is referenced only as unchanged context. Clinical decision-support behaviour is unaffected, so the SaMD classification is unchanged. The one clinically-relevant effect is indirect and protective: the runbook no longer tells an operator that a retrieval-path index is safe to apply without the canary this repository's own rules require.

Notes

• Branch context: this branch's previous PR (fix(chrome): overlay the phone header so hiding it never moves content #1396) merged at 06:49 and its remote ref was deleted. 746a88ed is an ancestor of main, so nothing was orphaned, and the branch was re-created carrying only new work plus main syncs — confirmed with git rev-list --left-right --count. This is a new PR, not a reuse of the merged one.
• Ledger #102 still tracks the operator apply itself. Item 1 corrects the instructions only; it does not change that item's status or apply anything.
• Still outstanding from fix(chrome): overlay the phone header so hiding it never moves content #1396 and deliberately not bundled here: the cold-load pre-paint guard (needs a Playwright pattern that samples first paint, which is a real design question rather than a chore), physical-device acceptance per docs/phone-chrome-physical-acceptance.md, and the fix(chrome): overlay the phone header so hiding it never moves content #1396 review ledger row.

🤖 Generated with Claude Code

https://claude.ai/code/session_01361jh3eYVjJCzXWjAhdZiF

[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 ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:46 minutes

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

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0a92541b-bfc3-48de-84ad-dfb721d65591

📥 Commits

Reviewing files that changed from the base of the PR and between fcd9041 and 369f9ac.

📒 Files selected for processing (3)

• docs/branch-review-ledger.md
• docs/operator-apply-performance-latency-remediation.md
• tests/ui-phone-scroll.spec.ts

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:40d35e697c

ℹ️ 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".