fix: serialize reindex with active enrichment

[BigSimmo]

Summary

• keep the current-main single/bulk preflight that reports fresh agent-enrichment conflicts before mutation
• close the remaining check-then-enqueue race with an owner-scoped transactional reindex RPC and a shared document-row lock in the agent claim path
• preserve indexed artifacts until the ingestion job is created atomically; reset non-indexed retry state in the same transaction
• repair the existing claim function's ambiguous ON CONFLICT (document_id) expression, proven against real PostgreSQL

RAG impact: no retrieval behaviour change — this changes ingestion/reindex queue serialization only; retrieval ranking, selection, answer generation and cache semantics are unchanged.

Why

A route-level lease check can pass immediately before an enrichment worker claims the same document. Reindex and enrichment can then mutate overlapping artifacts concurrently. Both paths now serialize on the document row, and the RPC re-checks the enrichment lease while that lock is held.

Verification

• focused Vitest after merging current origin/main: npx vitest run tests/ingestion-mutation-safety.test.ts tests/private-access-routes.test.ts tests/reindex-enrichment-lease.test.ts tests/stranded-queued-recovery.test.ts tests/supabase-schema.test.ts --maxWorkers=1 — 221/221 passed
• disposable Supabase PostgreSQL 17.6 schema replay and drift-manifest regeneration — passed; scratch container removed
• two-direction transactional concurrency probe in disposable PostgreSQL:
  • reindex held the document lock -> agent claim returned 0 rows; one ingestion job and no processing enrichment overlap
  • agent claim held the document lock -> reindex waited for commit, then returned agent_enrichment_active; zero ingestion jobs
• npm run typecheck
• scoped ESLint and Prettier
• npm run check:migration-role
• npm run check:function-grants — all 31 security-definer functions protected
• npm run check:owner-scope — 40 API files clean
• production-readiness script — READY for Clinical KB Database (sjrfecxgysukkwxsowpy); configuration-only, no API request
• exact-head hosted migration-chain replay and required checks — pending

Earlier on this PR, npm run verify:cheap passed runtime, policy/config, owner scope, lint and typecheck; the unit suite reached 3,265 passed/1 skipped before tracked issue #67 (reconciliation-preflight) hit its 30-second timeout. The exact post-migration focused suite is green above; the unchanged full wrapper was not repeated locally.

UI/browser verification was not run because no UI, routing or styling changed. No OpenAI/Railway/live RAG call was made. No live Supabase migration or data mutation was performed.

Risk and rollout

• Risk: medium and confined to full/retry reindex queue creation and agent-enrichment claiming. Bulk retains preflight-wide 409 behavior for conflicts visible at request start; a late per-document conflict is reported in that item's result.
• Rollback: before production apply, revert this PR. After apply, use a reviewed forward migration restoring the prior claim/RPC definitions; no data backfill or destructive data change is involved.
• Provider or production effects: None. No provider request, live migration, deployment or production-data mutation was run.

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

[coderabbitai]

Warning

Review limit reached

@BigSimmo, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 59 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

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 Plus

Run ID: 6c1c23e2-6ac7-40ca-825e-35284236de81

📥 Commits

Reviewing files that changed from the base of the PR and between e1fcd4c and 6377351.

📒 Files selected for processing (9)

• docs/branch-review-ledger.md
• src/app/api/documents/[id]/reindex/route.ts
• src/app/api/documents/bulk/reindex/route.ts
• src/lib/supabase/database.types.ts
• supabase/drift-manifest.json
• supabase/migrations/20260724060000_atomic_reindex_agent_guard.sql
• supabase/schema.sql
• tests/private-access-routes.test.ts
• tests/supabase-schema.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/reindex-agent-enrichment-guard

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{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: bce85d0bf0

ℹ️ 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. 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. After fixing or dispositioning a thread, reply in that thread with as the first line, followed by a concise summary; that marker authorizes the workflow to close that exact thread. If human input or new authorization is required, do not use the marker and leave the thread open with the blocker. 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.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: bce85d0bf0

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