Merge branch 'fix/docai-governance-rebased' into release/v1.27.31

src/app/api/documents/inbound/[id]/extract/__tests__/route.test.ts

@@ -28,12 +28,13 @@ vi.mock("@/lib/ai/coach/bytes-codec", () => ({
   decryptFromBytes: vi.fn(() => "{}"),
 }));
 
-vi.mock("@/lib/labs/ocr-capability", () => ({
-  resolveVisionProvider: vi.fn(),
-  resolveTextProvider: vi.fn(),
+vi.mock("@/lib/documents/provider-order", () => ({
+  resolveDocumentVisionProvider: vi.fn(),
+  resolveDocumentTextProvider: vi.fn(),
 }));
 vi.mock("@/lib/ai/consent-guard", () => ({
-  assertConsentForChain: vi.fn().mockResolvedValue(undefined),
+  assertDocumentEgressConsent: vi.fn().mockResolvedValue(undefined),
+  ConsentRequiredError: class ConsentRequiredError extends Error {},
 }));
 vi.mock("@/lib/ai/coach/budget", () => ({
   buildDateKey: vi.fn(() => "2026-06-27"),
@@ -76,7 +77,7 @@ import { POST } from "../route";
 import { prisma } from "@/lib/db";
 import { getSession } from "@/lib/auth/session";
 import { requireModuleEnabled } from "@/lib/modules/gate";
-import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
+import { resolveDocumentVisionProvider } from "@/lib/documents/provider-order";
 
 const SESSION_OK = {
   session: { id: "sess-1", expiresAt: new Date(Date.now() + 3_600_000) },
@@ -109,7 +110,7 @@ beforeEach(() => {
 
 describe("POST /api/documents/inbound/[id]/extract", () => {
   it("422s without a vision provider and leaves the stored row intact", async () => {
-    vi.mocked(resolveVisionProvider).mockResolvedValue({
+    vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
       chain: [],
       pick: null,
     } as never);

src/app/api/documents/inbound/[id]/extract/route.ts

@@ -4,10 +4,10 @@
  * Extraction is no longer part of upload: a document is stored first
  * (provider-free), and THIS route is the explicit, user-triggered enhancement.
  * It carries the entire ingest gauntlet that upload used to run inline —
- * resolve provider → assertConsentForChain → rate-limit → reserveBudget →
- * runInboundExtraction → reconcileSpend → stage facts — but now against a row
- * that already exists. Absent a provider this 422s the ENHANCEMENT only; the
- * stored document is untouched and remains filed.
+ * resolve document provider (local-first, codex last) → assertDocumentEgressConsent
+ * → rate-limit → reserveBudget → runInboundExtraction → reconcileSpend → stage
+ * facts — but now against a row that already exists. Absent a provider this 422s
+ * the ENHANCEMENT only; the stored document is untouched and remains filed.
  *
  * Two modes, dispatched on content-type (mirroring the original upload):
  *   - VISION (no JSON body): decrypt the stored original, re-derive its MIME,
@@ -31,7 +31,7 @@ import {
   safeJson,
 } from "@/lib/api-response";
 import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
-import { assertConsentForChain } from "@/lib/ai/consent-guard";
+import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
 import {
   buildDateKey,
   reconcileSpend,
@@ -52,9 +52,9 @@ import {
   serialiseDocumentDetail,
 } from "@/lib/documents/store";
 import {
-  resolveTextProvider,
-  resolveVisionProvider,
-} from "@/lib/labs/ocr-capability";
+  resolveDocumentTextProvider,
+  resolveDocumentVisionProvider,
+} from "@/lib/documents/provider-order";
 import { detectOcrMimeType } from "@/lib/labs/ocr-upload";
 import { annotate } from "@/lib/logging/context";
 import { requireModuleEnabled } from "@/lib/modules/gate";
@@ -200,14 +200,18 @@ async function handleTextExtract(
     });
   }
 
-  const { chain, pick } = await resolveTextProvider(userId);
+  const { pick } = await resolveDocumentTextProvider(userId);
   if (!pick) {
     return apiError("No AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
 
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const rl = await checkRateLimit(
     `documents-inbound:${userId}`,
@@ -298,14 +302,18 @@ async function handleVisionExtract(
   userId: string,
   document: LoadedDocument,
 ): Promise<Response> {
-  const { chain, pick } = await resolveVisionProvider(userId);
+  const { pick } = await resolveDocumentVisionProvider(userId);
   if (!pick) {
     return apiError("No vision-capable AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
 
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const rl = await checkRateLimit(
     `documents-inbound:${userId}`,

src/app/api/documents/inbound/[id]/index/__tests__/route.test.ts

@@ -29,11 +29,12 @@ vi.mock("@/lib/documents/describe", () => ({
 vi.mock("@/lib/documents/content-index", () => ({
   upsertContentIndex: vi.fn().mockResolvedValue({ tokenCount: 7 }),
 }));
-vi.mock("@/lib/labs/ocr-capability", () => ({
-  resolveVisionProvider: vi.fn(),
+vi.mock("@/lib/documents/provider-order", () => ({
+  resolveDocumentVisionProvider: vi.fn(),
 }));
 vi.mock("@/lib/ai/consent-guard", () => ({
-  assertConsentForChain: vi.fn().mockResolvedValue(undefined),
+  assertDocumentEgressConsent: vi.fn().mockResolvedValue(undefined),
+  ConsentRequiredError: class ConsentRequiredError extends Error {},
 }));
 vi.mock("@/lib/ai/coach/budget", () => ({
   buildDateKey: vi.fn(() => "2026-07-07"),
@@ -68,7 +69,7 @@ vi.mock("next/headers", () => ({
 import { POST } from "../route";
 import { prisma } from "@/lib/db";
 import { getSession } from "@/lib/auth/session";
-import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
+import { resolveDocumentVisionProvider } from "@/lib/documents/provider-order";
 import { transcribeDocument } from "@/lib/documents/describe";
 import { upsertContentIndex } from "@/lib/documents/content-index";
 
@@ -109,7 +110,7 @@ beforeEach(() => {
 
 describe("POST /api/documents/inbound/[id]/index", () => {
   it("vision: transcribes then upserts the index, never facts", async () => {
-    vi.mocked(resolveVisionProvider).mockResolvedValue({
+    vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
       chain: [{ providerType: "anthropic", instance: {} }],
       pick: {
         entry: { providerType: "anthropic", instance: {} },
@@ -137,7 +138,7 @@ describe("POST /api/documents/inbound/[id]/index", () => {
   });
 
   it("vision: 422 without a provider", async () => {
-    vi.mocked(resolveVisionProvider).mockResolvedValue({
+    vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
       chain: [],
       pick: null,
     } as never);
@@ -160,7 +161,7 @@ describe("POST /api/documents/inbound/[id]/index", () => {
       expect.objectContaining({ source: "text-ocr", providerType: null }),
     );
     // No provider was resolved on the text path.
-    expect(resolveVisionProvider).not.toHaveBeenCalled();
+    expect(resolveDocumentVisionProvider).not.toHaveBeenCalled();
   });
 
   it("text: 422 when local OCR is not enabled", async () => {

src/app/api/documents/inbound/[id]/index/route.ts

@@ -14,8 +14,9 @@
  * Decision (maintainer, 2026-07-07): content indexing is gated on the EXISTING
  * AI consent / provider gate — there is NO separate `documentsContentIndexEnabled`
  * toggle (the plan's P2-D8 opt-in was refused to avoid toggle sprawl). The vision
- * path runs `assertConsentForChain`; the text path rides the local-OCR opt-in the
- * lab / extract text mode already uses.
+ * path runs `assertDocumentEgressConsent` (any external provider needs an active
+ * receipt; a local pick stays ungated); the text path rides the local-OCR opt-in
+ * the lab / extract text mode already uses — no provider egress at all.
  *
  * Persists ONLY AES-256-GCM ciphertext text + opaque HMAC token hashes (A4).
  */
@@ -29,7 +30,7 @@ import {
   safeJson,
 } from "@/lib/api-response";
 import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
-import { assertConsentForChain } from "@/lib/ai/consent-guard";
+import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
 import {
   buildDateKey,
   reconcileSpend,
@@ -51,7 +52,7 @@ import {
   DocumentDescribeError,
   transcribeDocument,
 } from "@/lib/documents/describe";
-import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
+import { resolveDocumentVisionProvider } from "@/lib/documents/provider-order";
 import { annotate } from "@/lib/logging/context";
 import { requireModuleEnabled } from "@/lib/modules/gate";
 import { prisma } from "@/lib/db";
@@ -164,13 +165,17 @@ async function handleVisionIndex(
   userId: string,
   document: LoadedDocument,
 ): Promise<Response> {
-  const { chain, pick } = await resolveVisionProvider(userId);
+  const { pick } = await resolveDocumentVisionProvider(userId);
   if (!pick) {
     return apiError("No vision-capable AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const rl = await checkRateLimit(
     `${DOCUMENT_AI_BUCKET}:${userId}`,

src/app/api/documents/inbound/[id]/suggest/__tests__/route.test.ts

@@ -27,12 +27,13 @@ vi.mock("@/lib/documents/assist", () => ({
   runDocumentAssist: vi.fn(),
   DocumentAssistError: class DocumentAssistError extends Error {},
 }));
-vi.mock("@/lib/labs/ocr-capability", () => ({
-  resolveVisionProvider: vi.fn(),
-  resolveTextProvider: vi.fn(),
+vi.mock("@/lib/documents/provider-order", () => ({
+  resolveDocumentVisionProvider: vi.fn(),
+  resolveDocumentTextProvider: vi.fn(),
 }));
 vi.mock("@/lib/ai/consent-guard", () => ({
-  assertConsentForChain: vi.fn().mockResolvedValue(undefined),
+  assertDocumentEgressConsent: vi.fn().mockResolvedValue(undefined),
+  ConsentRequiredError: class ConsentRequiredError extends Error {},
 }));
 vi.mock("@/lib/ai/coach/budget", () => ({
   buildDateKey: vi.fn(() => "2026-07-07"),
@@ -67,7 +68,7 @@ vi.mock("next/headers", () => ({
 import { POST } from "../route";
 import { prisma } from "@/lib/db";
 import { getSession } from "@/lib/auth/session";
-import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
+import { resolveDocumentVisionProvider } from "@/lib/documents/provider-order";
 import { runDocumentAssist } from "@/lib/documents/assist";
 
 const SESSION_OK = {
@@ -98,7 +99,7 @@ beforeEach(() => {
 
 describe("POST /api/documents/inbound/[id]/suggest", () => {
   it("422s without a vision provider and writes nothing", async () => {
-    vi.mocked(resolveVisionProvider).mockResolvedValue({
+    vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
       chain: [],
       pick: null,
     } as never);
@@ -113,7 +114,7 @@ describe("POST /api/documents/inbound/[id]/suggest", () => {
   });
 
   it("returns drafts and never persists them", async () => {
-    vi.mocked(resolveVisionProvider).mockResolvedValue({
+    vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
       chain: [{ providerType: "anthropic", instance: {} }],
       pick: {
         entry: { providerType: "anthropic", instance: {} },

src/app/api/documents/inbound/[id]/suggest/route.ts

@@ -22,7 +22,7 @@ import {
   safeJson,
 } from "@/lib/api-response";
 import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
-import { assertConsentForChain } from "@/lib/ai/consent-guard";
+import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
 import {
   buildDateKey,
   reconcileSpend,
@@ -45,9 +45,9 @@ import {
   type LoadedDocument,
 } from "@/lib/documents/ai-route-support";
 import {
-  resolveTextProvider,
-  resolveVisionProvider,
-} from "@/lib/labs/ocr-capability";
+  resolveDocumentTextProvider,
+  resolveDocumentVisionProvider,
+} from "@/lib/documents/provider-order";
 import { annotate } from "@/lib/logging/context";
 import { requireModuleEnabled } from "@/lib/modules/gate";
 import { prisma } from "@/lib/db";
@@ -133,14 +133,18 @@ async function handleTextSuggest(
     });
   }
 
-  const { chain, pick } = await resolveTextProvider(userId);
+  const { pick } = await resolveDocumentTextProvider(userId);
   if (!pick) {
     return apiError("No AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
 
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const rl = await checkRateLimit(
     `${DOCUMENT_AI_BUCKET}:${userId}`,
@@ -209,14 +213,18 @@ async function handleVisionSuggest(
   userId: string,
   document: LoadedDocument,
 ): Promise<Response> {
-  const { chain, pick } = await resolveVisionProvider(userId);
+  const { pick } = await resolveDocumentVisionProvider(userId);
   if (!pick) {
     return apiError("No vision-capable AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
 
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const rl = await checkRateLimit(
     `${DOCUMENT_AI_BUCKET}:${userId}`,

src/app/api/documents/inbound/[id]/summary/__tests__/route.test.ts

@@ -27,12 +27,13 @@ vi.mock("@/lib/documents/describe", () => ({
   transcribeDocument: vi.fn(),
   DocumentDescribeError: class DocumentDescribeError extends Error {},
 }));
-vi.mock("@/lib/labs/ocr-capability", () => ({
-  resolveVisionProvider: vi.fn(),
-  resolveTextProvider: vi.fn(),
+vi.mock("@/lib/documents/provider-order", () => ({
+  resolveDocumentVisionProvider: vi.fn(),
+  resolveDocumentTextProvider: vi.fn(),
 }));
 vi.mock("@/lib/ai/consent-guard", () => ({
-  assertConsentForChain: vi.fn().mockResolvedValue(undefined),
+  assertDocumentEgressConsent: vi.fn().mockResolvedValue(undefined),
+  ConsentRequiredError: class ConsentRequiredError extends Error {},
 }));
 vi.mock("@/lib/ai/coach/budget", () => ({
   buildDateKey: vi.fn(() => "2026-07-07"),
@@ -67,7 +68,7 @@ vi.mock("next/headers", () => ({
 import { POST } from "../route";
 import { prisma } from "@/lib/db";
 import { getSession } from "@/lib/auth/session";
-import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
+import { resolveDocumentVisionProvider } from "@/lib/documents/provider-order";
 import { auditLog } from "@/lib/auth/audit";
 import {
   runDocumentSummary,
@@ -105,7 +106,7 @@ beforeEach(() => {
     mimeType: "image/png",
     status: "STORED",
   } as never);
-  vi.mocked(resolveVisionProvider).mockResolvedValue({
+  vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
     chain: [{ providerType: "anthropic", instance: {} }],
     pick: {
       entry: { providerType: "anthropic", instance: {} },
@@ -151,7 +152,7 @@ describe("POST /api/documents/inbound/[id]/summary", () => {
   });
 
   it("422s without a provider", async () => {
-    vi.mocked(resolveVisionProvider).mockResolvedValue({
+    vi.mocked(resolveDocumentVisionProvider).mockResolvedValue({
       chain: [],
       pick: null,
     } as never);

src/app/api/documents/inbound/[id]/summary/route.ts

@@ -23,7 +23,7 @@ import {
   safeJson,
 } from "@/lib/api-response";
 import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
-import { assertConsentForChain } from "@/lib/ai/consent-guard";
+import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
 import {
   buildDateKey,
   reconcileSpend,
@@ -47,9 +47,9 @@ import {
   type DescribeInput,
 } from "@/lib/documents/describe";
 import {
-  resolveTextProvider,
-  resolveVisionProvider,
-} from "@/lib/labs/ocr-capability";
+  resolveDocumentTextProvider,
+  resolveDocumentVisionProvider,
+} from "@/lib/documents/provider-order";
 import { annotate } from "@/lib/logging/context";
 import { requireModuleEnabled } from "@/lib/modules/gate";
 import { prisma } from "@/lib/db";
@@ -188,13 +188,17 @@ async function handleTextSummary(
     return finishSummary(request, userId, document.id, "text", mode, result);
   }
 
-  const { chain, pick } = await resolveTextProvider(userId);
+  const { pick } = await resolveDocumentTextProvider(userId);
   if (!pick) {
     return apiError("No AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const dateKey = buildDateKey();
   const reservation = await reserveBudget(
@@ -235,13 +239,17 @@ async function handleVisionSummary(
   document: LoadedDocument,
   mode: DocumentSummaryMode,
 ): Promise<Response> {
-  const { chain, pick } = await resolveVisionProvider(userId);
+  const { pick } = await resolveDocumentVisionProvider(userId);
   if (!pick) {
     return apiError("No vision-capable AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
-  await assertConsentForChain({ userId, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const rl = await checkRateLimit(
     `${DOCUMENT_AI_BUCKET}:${userId}`,

src/app/api/documents/inbound/capability/route.ts

@@ -0,0 +1,42 @@
+/**
+ * GET /api/documents/inbound/capability
+ *
+ * Document-scoped AI capability probe (no provider call). Mirrors the labs
+ * `/api/labs/ocr/capability` probe but resolves over the DOCUMENT provider
+ * order (local-first, codex last — governance fix, oauth-investigation
+ * SYNTHESIS §1) and adds the vendor-blind `egress` class so the vault UI can
+ * show the "this leaves your machine to a third-party AI" notice BEFORE a read.
+ *
+ * The `mode` / `pdfSupported` / `egress` here reflect exactly what the document
+ * routes (suggest / summary / extract / index) will do, so the affordance the
+ * UI offers never diverges from what the endpoint accepts.
+ */
+import { apiHandler, requireAuth } from "@/lib/api-handler";
+import { apiSuccess } from "@/lib/api-response";
+import { resolveDocumentAiCapability } from "@/lib/documents/provider-order";
+import { annotate } from "@/lib/logging/context";
+import { requireModuleEnabled } from "@/lib/modules/gate";
+
+export const dynamic = "force-dynamic";
+
+export const GET = apiHandler(async () => {
+  const { user } = await requireAuth();
+
+  const gate = await requireModuleEnabled(user.id, "inboundDocuments");
+  if (!gate.enabled) return gate.response;
+
+  const capability = await resolveDocumentAiCapability(user.id);
+
+  annotate({
+    action: { name: "documents.ai.capability" },
+    meta: {
+      available: capability.available,
+      mode: capability.mode,
+      reason: capability.reason,
+      pdfSupported: capability.pdfSupported,
+      egress: capability.egress,
+    },
+  });
+
+  return apiSuccess(capability);
+});

src/app/api/documents/inbound/reindex/route.ts

@@ -9,10 +9,10 @@
  */
 import { apiHandler, requireAuth } from "@/lib/api-handler";
 import { apiError, apiSuccess, getClientIp } from "@/lib/api-response";
-import { assertConsentForChain } from "@/lib/ai/consent-guard";
+import { assertDocumentEgressConsent } from "@/lib/ai/consent-guard";
 import { auditLog } from "@/lib/auth/audit";
 import { enqueueContentIndexBackfill } from "@/lib/jobs/document-content-index-backfill";
-import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
+import { resolveDocumentVisionProvider } from "@/lib/documents/provider-order";
 import { annotate } from "@/lib/logging/context";
 import { requireModuleEnabled } from "@/lib/modules/gate";
 import { checkRateLimit, rateLimitHeaders } from "@/lib/rate-limit";
@@ -46,13 +46,17 @@ export const POST = apiHandler(async (request) => {
 
   // Fail fast when the precondition is not met so the UI gets immediate
   // feedback rather than a silently no-op'd job.
-  const { chain, pick } = await resolveVisionProvider(user.id);
+  const { pick } = await resolveDocumentVisionProvider(user.id);
   if (!pick) {
     return apiError("No vision-capable AI provider is configured", 422, {
       errorCode: "documents.inbound.providerUnsupported",
     });
   }
-  await assertConsentForChain({ userId: user.id, chain, surface: "insights" });
+  await assertDocumentEgressConsent({
+    userId: user.id,
+    providerType: pick.providerType,
+    surface: "insights",
+  });
 
   const { enqueued } = await enqueueContentIndexBackfill(user.id);