refactor(eval): share public-sentinel owner default across read/eval scripts; close #347 answer-path gate

[BigSimmo]

Summary

Follow-up to #348. That PR defaulted the golden retrieval eval's owner to the public sentinel 00000000-…0000, but only in scripts/eval-retrieval.ts — so eval:quality (incl. --rag-only), eval:rag, eval:answer-quality, and eval:search still resolved the owner as args.ownerId ?? emailLookup ?? undefined and returned 0/N against the all-public (owner_id = NULL) live corpus unless RAG_EVAL_OWNER_ID was set by hand. This closes that gap and the outstanding #347 part-2 answer-path eval gate.

• Item 1 (shared default): hoisted DEFAULT_EVAL_OWNER_ID + resolveEvalOwnerId(supabase, args) into scripts/eval-utils.ts and applied it at the final owner-resolution point in all five read/eval scripts. eval-retrieval.ts is refactored onto the helper and its local duplicate constant removed. Precedence preserved: explicit --owner-id/RAG_EVAL_OWNER_ID/LOCAL_NO_AUTH_OWNER_ID → --owner-email/RAG_EVAL_OWNER_EMAIL lookup → sentinel.
• Item 3 (no silent narrowing): the helper prints a one-line warning whenever it falls back to the sentinel, so the narrowing to public-only scope is visible. (Observed firing in the live eval:quality run below.)
• Scope guard: write/backfill scripts (enrich-documents, classify-documents, backfill-*) are deliberately excluded — defaulting an owner there could write under the wrong owner.
• First-ever resolveEvalOwnerId unit coverage added to tests/eval-utils.test.ts.

Verification

• npm run verify:cheap — green (check:runtime, sitemap:check, lint 0 errors / pre-existing warnings only, typecheck, unit tests 1277 passed / 3 skipped incl. the 3 new resolveEvalOwnerId tests)
• npm run verify:ui — N/A (no UI/routing/styling change)
• npm run verify:release — not run (no release claim)
• npm run format:check — Prettier clean on changed files
• npm run eval:retrieval:quality — 36/36, failed_cases=0 (regression check on the refactored eval-retrieval.ts; behavior unchanged vs fix(eval): default golden retrieval eval owner to public sentinel #348)
• npm run eval:quality -- --rag-only — closes the refactor(rag): decompose rag.ts part 2 (extractive-answer, retrieval-variants, cache) — move-only #347 part-2 answer-path gate (live, no manual owner — the helper warned + used the sentinel):

## Answer Metrics
| Cases | 44 |
| Grounded supported rate | 0.90 | (#343 baseline 0.9333)
| Unsupported correct rate | 1 | (#343 baseline 1 — invariant held)
| Citation failure rate | 0.0455 | (#343 baseline 0.0455 — identical)
| Numeric grounding failure rate | 0.0227 | (#343 baseline 0.0227 — identical)

The 3 rate invariants match #343's live baseline exactly. The 5 failing answer cases are all in #343's documented live-variance set: 2 pure latency-threshold failures (clozapine-fbc-acronym-threshold, agitation-im-po-route-short-terms — this environment's Supabase p95 ≈ 49 s, the local→remote latency #343 called out) and 3 route/retrieval flakes (illegal-substances, discharge-documentation, community-admission — #343 named these as pre-existing variance outside the touched paths). Since this change is eval-config only (owner resolution) and touches no answer-generation code, the identical invariant rates confirm the part-2 decomposition preserved answer behavior.

• npm run check:production-readiness — N/A (no clinical/privacy/env/Supabase runtime change)

Clinical Governance Preflight

Touches only eval-harness owner configuration + docs — not ingestion, answer generation, search/ranking runtime, source rendering, document access, privacy, production env, or clinical output.

• Source-backed claims still require linked source verification (unchanged)
• No patient-identifiable document workflow introduced or expanded
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy) — reads only, no config touched
• Service-role keys and private document access remain server-only (eval secrets kept in gitignored .env.local, never committed)
• Demo/synthetic content remains separated from real clinical sources
• Source metadata/review-status/outdated behavior remain conservative
• Deployment classification/TGA SaMD impact — no clinical decision-support behavior changed

Notes

• Fixes items 1–3 of the post-fix(eval): default golden retrieval eval owner to public sentinel #348 review. Item 3 (silent-narrowing guard) is delivered centrally by the helper's warning, so it covers eval-retrieval too (which previously had none).
• docs/process-hardening.md records the result and corrects the earlier phrasing (fix(eval): default golden retrieval eval owner to public sentinel #348 closed the retrieval half; this closes the answer-path half — refactor(rag): decompose rag.ts part 2 (extractive-answer, retrieval-variants, cache) — move-only #347 part-2 fully settled). docs/retrieval-quality-runbook.md notes the default now spans the whole eval suite.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BdP9DwsGdvtEvyVh3juYZ5

---

Generated by Claude Code

[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]

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