fix: unify answer reliability across all prompts

docs/branch-review-ledger.md

@@ -392,11 +392,14 @@ Use this ledger to prevent repeated branch and PR reviews when the reviewed HEAD
 | 2026-07-13 | origin/codex/rag-canary-completion | d1b7647bde73e7d0558472ad6aa19c3b49d94639 | branch-cleanup | Retained for open PR #612 and active worktree activity. | Fresh GitHub open-PR query and moving-head observation; deletion prohibited. |
 | 2026-07-13 | origin/main | 528a1752f41cd29a518ca9341c93c724030173ae | branch-cleanup | Protected base branch retained. | Final refreshed origin/main snapshot before the ledger PR. |
 | 2026-07-14 | PR #629 / codex/eval-canary-quota-handling | 8fe1be6d0c58c60afeeb82f720b03c90ce57c2cf | review-followup | One P2 structured-error retry defect confirmed and fixed on `codex/eval-canary-structured-errors`. | GitHub connector thread inspection; `tests/eval-utils.test.ts` 14/14; focused ESLint and Prettier. |
+| 2026-07-14 | codex/global-answer-reliability | 01d2749978d4e8f3b4ac508e068ec7b8d331f816 | release-readiness / answer generation, source governance, progress, and document access | No unresolved P0-P2 findings after fixing demo-path governance parity, preserving feedback-token binding during the `origin/main` rebase, and binding legacy-summary feedback to the delivered governed answer. Ready for hosted PR checks. | `npm run verify:pr-local` (2,223 passed, 1 skipped; production build and offline RAG evaluation passed); focused Chromium answer regressions (4/4 passed); focused answer and route regressions (124/124 passed). |
 | 2026-07-14 | claude/repo-next-steps-e53523 | 3f7d6d76f597f2a0311af1052480f84b68ecc259 | launch-readiness and RAG-performance follow-up | Branch changes were already squash-merged by PR #513. Fresh review found one P1 governance inconsistency (Singapore app/worker processing omitted from the PIA's cross-border account) and three P2 follow-ups: degraded-answer SLO overcounting, a second blocking shared-cache miss diagnostic query, and stale launch/RAG backlog status. No source fix was applied in this review. | `git diff --check c3828ceb9f3812abeebc1b653361fc254dda9f5e..3f7d6d76f597f2a0311af1052480f84b68ecc259`; focused Vitest 92/92; `npm run eval:rag:offline` 36 fixtures and 59/59 contract tests; `npm run verify:cheap` passed runtime, action pins, sitemap, type scale, lint, typecheck, and 1,672 passed/1 skipped tests. Provider-backed Supabase/OpenAI, browser, release, drift, and live retrieval-quality checks were not run. |
 | 2026-07-14 | codex/rag-performance-followups | 5502fd498ea2069f810795a8659f98ab3abf8c80 | release-readiness review | The local release review found no P0-P2 defect after correcting one stale PIA statement; the later hosted review follow-up is recorded below. The scoped RAG round-trip, SLO, retention, privacy, and documentation changes were ready for PR handoff. Highest residual risk is the known live hybrid-RPC latency tail; model experiments remain blocked by provider quota and legal execution remains operator/counsel work. | Rebased onto `origin/main`; runtime and full Prettier check; ESLint; TypeScript; Vitest 2,213 passed/1 skipped; Next.js production build (636 pages) plus client-bundle secret scan; offline RAG 36 fixtures and 277/277 contract tests; `git diff --check`. Live retention jobs 13/16 were already verified during this workstream. |
 | 2026-07-14 | PR #632 / codex/rag-performance-followups | aa264e92c44b42fdcceeac6292011ba51169b862 | review-followup | One P2 SLO-classification defect was confirmed: the broad source-only `degraded` flag also included healthy extractive answers. Fixed by persisting and counting a separate `provider_generation_degraded` flag derived only from `generation_fallback`. | GitHub connector plus UTF-8 thread-aware review inspection; focused ESLint; 45/45 targeted Vitest tests; TypeScript; offline RAG 36 fixtures and 277/277 contract tests; `git diff --check`. |
 | 2026-07-14 | PR #632 / codex/rag-performance-followups | 07cac8f4e094bf4b5ccd264feb6420fbd4e35e2b | review-followup | CodeRabbit's APP 1/5 governance contradiction was confirmed and corrected; Railway's pending DPA and Singapore processor basis are now explicit checklist/status items. The optional cache-miss granularity suggestion was not adopted because it would undo the reviewed single-read cold-miss design or require a broader schema/RPC change. | GitHub review-thread inspection; focused Prettier and `git diff --check` passed. Local production-readiness inspection reported the expected missing provider env; the Railway production-context check had already passed on this workstream. |
 | 2026-07-14 | PR #632 / codex/rag-performance-followups | 0c792b8c10516c85d18832fc96562dd70a671b5f | review-followup | One P1 privacy-disclosure defect was confirmed: OpenAI retrieval embedding can receive query text even when answer synthesis remains source-only. Fixed the PIA and public `/privacy` copy to distinguish retrieval-embedding egress from model-backed synthesis egress, with focused copy coverage. | GitHub connector review-thread inspection; focused privacy UI test, ESLint, TypeScript, Prettier, production-readiness, and `git diff --check`. |
 | 2026-07-14 | PR #632 / codex/rag-performance-followups | a2eb6db0efbef983e1b3242261d5cc6b2b9d839d | review-followup | One late P2 rollout-compatibility defect was confirmed: the provider-fallback SLO would omit recent rows written before `provider_generation_degraded` existed. Fixed the count predicate to include the new flag or legacy `generation_fallback:` reasons while continuing to exclude intentional extractive routes. | GitHub connector review-thread inspection; focused answer-SLO test, ESLint, TypeScript, Prettier, and `git diff --check`. |
+| 2026-07-14 | PR #634 / codex/global-answer-reliability | 588c34c3d455c367e6aa38dc9fce64191678631b | review-followup | One late P2 quota-bypass defect was confirmed: streamed full-document summaries consumed only the general answer quota. Fixed the route to enforce the stricter `document_summarize` quota before starting the stream or provider work while retaining the general answer ceiling. | GitHub connector review-thread inspection; focused private-access route suite 116/116; ESLint; TypeScript; Prettier; `git diff --check`. |
 | 2026-07-14 | codex/specifiers-design | c3e7024e15d2157bbc0b989276324cc6ad3eea5c | Specifiers UI, clinical decision-support, accessibility, and release-readiness review | One P2 WCAG contrast defect was reproduced and fixed across the builder, comparison, and map accent eyebrows. No remaining high-confidence defect was found in the changed scope; residual risk is clinical/manual governance of the original specifier summaries. | Focused Vitest 18/18; focused Chromium desktop/mobile 2/2 with serious/critical axe WCAG A/AA scanning and overflow checks; `npm run check:production-readiness:ci` READY; `npm run verify:cheap` 2,210 passed/1 skipped; `npm run verify:pr-local` 2,213 passed/1 skipped plus production build and client-bundle secret scan; `git diff --check`. Full advisory `verify:ui` exceeded the local 10-minute execution window; provider-backed checks were not run. |
 | 2026-07-14 | PR #633 / codex/specifiers-design | 03daca3bfdf86517b9956f3c7d91be27d9f1a751 | Review follow-up and failed UI regression | Eight distinct P2 behaviors across nine review threads were confirmed and fixed: initial selection normalization, duplicate query removal, clinical applicability mapping, canonical Specifiers routing, severity-neutral base wording, diagnostic-section ordering, base/specifier compatibility, and severe psychotic-features wording. The failed app-menu keyboard test was a stale order assertion and now covers the inserted Specifiers item. | Focused Vitest 6/6; focused Chromium 4/4; scoped ESLint and TypeScript; CI-mode production readiness READY; production build and client-bundle secret scan passed. Hosted required checks passed on the refreshed `main` merge before the final compatibility fixes; provider-backed Supabase/OpenAI checks were not run. |
+| 2026-07-14 | PR #634 / codex/global-answer-reliability | b411329ec5f181661e5d49276c398440aa928fa2 | review-followup | One late P2 fast-context defect was confirmed: Australian tier ordering could push a higher-ranked supplementary passage outside the four-chunk routine fast budget. Fixed by preserving the retrieval-ranked, crowding-capped candidate budget before applying the order-only Australian preference within that set. | GitHub connector review-thread inspection; focused RAG context-budget suite 22/22; ESLint; TypeScript; Prettier; `git diff --check`. |

src/app/api/answer/route.ts

@@ -16,20 +16,19 @@ import { buildSmartRagApiPlan } from "@/lib/smart-rag-api";
 import { clinicalQueryModeSchema, queryClassForClinicalMode, queryForClinicalMode } from "@/lib/clinical-query-mode";
 import { resolveSearchScope, searchScopeFiltersSchema } from "@/lib/search-scope";
 import { resolveRetrievalAccessScope } from "@/lib/owner-scope";
-import {
-  hasDangerSourceGovernanceWarning,
-  sourceGovernanceRefusalAnswer,
-  sourceGovernanceWarnings,
-} from "@/lib/source-governance";
+import { sourceGovernanceWarnings } from "@/lib/source-governance";
 import { parseJsonBody } from "@/lib/validation/body";
-import { toClientAnswerPayload } from "@/lib/answer-client-payload";
+import {
+  answerDegradedModeSignal,
+  buildGovernedAnswerClientResponse,
+  buildGovernedDemoAnswerClientResponse,
+} from "@/lib/answer-response";
 import { answerServerTimingEntries, buildServerTimingHeader } from "@/lib/server-timing";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { captureServerException } from "@/lib/observability/error-capture";
 import { logAnswerDiagnostics } from "@/lib/answer-telemetry";
 import { nonProductionSupabaseDemoFallbackReason } from "@/lib/supabase/errors";
 import * as serverAuth from "@/lib/supabase/auth";
-import type { RagAnswer } from "@/lib/types";
 import { answerFeedbackMetadata } from "@/lib/answer-feedback-token";
 
 export const runtime = "nodejs";
@@ -46,15 +45,6 @@ type AnswerRequestBody = z.infer<typeof answerSchema>;
 const emptyScopeAnswer =
   "The selected filters did not match any indexed documents, so I cannot generate an answer for that scope.";
 
-function answerDegradedModeSignal(answer?: Pick<RagAnswer, "degradedMode" | "answerQualityTier" | "fallbackReason">) {
-  if (answer?.degradedMode) return answer.degradedMode;
-  const active = answer?.answerQualityTier === "source_only";
-  return {
-    active,
-    reason: active ? (answer?.fallbackReason ?? "source_only") : null,
-  };
-}
-
 function buildDemoAnswerPayload(body: AnswerRequestBody, fallbackReason?: string) {
   const answer = demoAnswer(body.query, body.documentId, body.documentIds);
   const answerFocusQuery = queryForClinicalMode(body.query, body.queryMode);
@@ -65,14 +55,14 @@ function buildDemoAnswerPayload(body: AnswerRequestBody, fallbackReason?: string
     routeMode: answer.routingMode,
     retrievalStrategy: "hybrid",
   });
-  return {
-    ...answer,
-    responseMode: smartApiPlan.displayMode,
-    smartApiPlan,
-    demoMode: true,
-    degradedMode: fallbackReason ? { active: true, reason: fallbackReason } : answerDegradedModeSignal(answer),
-    ...(fallbackReason ? { fallbackMode: "non_production_demo", fallbackReason } : {}),
-  };
+  return buildGovernedDemoAnswerClientResponse(
+    {
+      ...answer,
+      responseMode: smartApiPlan.displayMode,
+      smartApiPlan,
+    },
+    fallbackReason,
+  );
 }
 
 export async function POST(request: Request) {
@@ -137,59 +127,23 @@ export async function POST(request: Request) {
       queryMode: answerBody.queryMode,
       signal: request.signal,
     });
-    const warnings = sourceGovernanceWarnings({
-      results: answer.sources ?? [],
-      relevance: answer.relevance ?? answer.smartPanel?.relevance ?? null,
+    const governedResponse = buildGovernedAnswerClientResponse(answer);
+    logAnswerDiagnostics({
+      supabase,
+      query: answerBody.query,
+      ownerId: access.ownerId,
+      answer: governedResponse.telemetryAnswer,
     });
-    const shouldUseSourceGovernanceRefusal =
-      answer.grounded !== false && answer.confidence !== "unsupported" && answer.responseMode !== "evidence_gap";
-    if (shouldUseSourceGovernanceRefusal && hasDangerSourceGovernanceWarning(warnings)) {
-      // Build the refusal explicitly — never spread ...answer here, or the original
-      // (refused) sources/smartPanel/smartApiPlan would still reach the client and
-      // defeat the refusal. Keep only the safe "unsupported" contract fields, matching
-      // the empty-scope branch above.
-      void logAnswerDiagnostics({
-        supabase,
-        query: answerBody.query,
-        ownerId: access.ownerId,
-        answer: {
-          ...answer,
-          grounded: false,
-          confidence: "unsupported",
-          sources: [],
-          responseMode: "evidence_gap",
-          fallbackReason: "source_governance_refusal",
-          routingReason: [answer.routingReason, "source_governance_refusal"].filter(Boolean).join("; "),
-        },
-      });
-      return NextResponse.json({
-        answer: sourceGovernanceRefusalAnswer,
-        grounded: false,
-        confidence: "unsupported",
-        citations: [],
-        sources: [],
-        degradedMode: answerDegradedModeSignal(answer),
-        scope: { ...scope, queryMode: answerBody.queryMode },
-        sourceGovernanceWarnings: warnings,
-        ...answerFeedbackMetadata(interactionId, sourceGovernanceRefusalAnswer),
-      });
-    }
-
-    logAnswerDiagnostics({ supabase, query: answerBody.query, ownerId: access.ownerId, answer });
 
     // Durations only — see server-timing.ts for the trust-boundary constraint.
     const serverTiming = buildServerTimingHeader(
       answerServerTimingEntries(answer.latencyTimings, Date.now() - routeStartedAt),
     );
     return NextResponse.json(
       {
-        // Boundary trim only — governance warnings and diagnostics above
-        // consumed the full answer (see answer-client-payload.ts).
-        ...toClientAnswerPayload(answer),
-        degradedMode: answerDegradedModeSignal(answer),
+        ...governedResponse.payload,
         scope: { ...scope, queryMode: answerBody.queryMode },
-        sourceGovernanceWarnings: warnings,
-        ...answerFeedbackMetadata(interactionId, answer.answer),
+        ...answerFeedbackMetadata(interactionId, governedResponse.payload.answer),
       },
       serverTiming ? { headers: { "Server-Timing": serverTiming } } : undefined,
     );