feat(phase-b): ship analytics dashboard, alerts, scanner PWA, dedup, audit view

Phase B (Insights & Alerts) PR4-11 in one drop. Builds on the schema +
service skeletons committed in PRs 1-3.

PR4  Analytics dashboard — 4 chart types (funnel/timeline/breakdown/source),
     date-range picker (today/7d/30d/90d), CSV+PNG export per card.
PR5  Alert rail UI + /alerts page — topbar bell w/ live count, dashboard
     right-rail, three-tab page (active/dismissed/resolved), socket-driven
     invalidation. Bell lazy-loads list on popover open to keep cold pages
     fast in non-dashboard routes.
PR6  EOI queue tab on documents hub — filters to in-flight EOIs, count
     surfaces in tab label.
PR7  Interests-by-berth tab on berth detail — replaces the stub.
PR8  Expense duplicate detection — BullMQ job runs scan on create, yellow
     banner on detail w/ Merge / Not-a-duplicate, transactional merge
     consolidates receipts and archives the source.
PR9  Receipt scanner PWA + multi-provider AI — port-scoped /scan route in
     its own (scanner) group with no dashboard chrome, dynamic per-port
     manifest, OpenAI + Claude provider abstraction, admin OCR settings
     page (port-level + super-admin global default w/ opt-in fallback),
     test-connection endpoint, manual-entry fallback when no key is
     configured. Verify form always shown before save — no ghost rows.
PR10 Audit log read view — swap to tsvector full-text search on the
     existing GIN index, cursor pagination, filters for entity/action/user
     /date range, batched actor-email resolution.
PR11 Real-API tests — opt-in receipt-ocr.spec (admin save+test, optional
     real-receipt parse via REALAPI_RECEIPT_FIXTURE) and alert-engine
     socket-fanout spec gated behind RUN_ALERT_ENGINE_REALAPI. Both skip
     cleanly without their gate envs so CI stays green.

Test totals: vitest 690 -> 713, smoke 130 -> 138, realapi +2 opt-in.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/integration/audit-search.test.ts

@@ -0,0 +1,196 @@
+/**
+ * PR10 — audit log search.
+ *
+ * Validates:
+ *  1. Tsvector full-text search via the GENERATED `search_text` column
+ *  2. All filters compose: entityType, action, userId, entityId, date range
+ *  3. Cursor pagination on (createdAt, id) yields stable, complete pages
+ *     and never duplicates rows across page boundaries
+ *  4. Per-port scoping isolates results
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { auditLogs } from '@/lib/db/schema/system';
+import { searchAuditLogs } from '@/lib/services/audit-search.service';
+import { makePort } from '../helpers/factories';
+
+async function seed(args: {
+  portId: string;
+  userId?: string;
+  action: string;
+  entityType: string;
+  entityId?: string;
+  createdAt?: Date;
+}) {
+  const [row] = await db
+    .insert(auditLogs)
+    .values({
+      portId: args.portId,
+      userId: args.userId ?? null,
+      action: args.action,
+      entityType: args.entityType,
+      entityId: args.entityId ?? null,
+      createdAt: args.createdAt ?? new Date(),
+    })
+    .returning();
+  return row!;
+}
+
+describe('audit log search', () => {
+  beforeEach(async () => {
+    // Tests are seed-isolated by port, so no global wipe needed.
+  });
+
+  it('finds rows by entityType filter', async () => {
+    const port = await makePort();
+    await seed({ portId: port.id, action: 'create', entityType: 'client' });
+    await seed({ portId: port.id, action: 'create', entityType: 'invoice' });
+    await seed({ portId: port.id, action: 'update', entityType: 'client' });
+
+    const { rows } = await searchAuditLogs({ portId: port.id, entityType: 'client' });
+    expect(rows).toHaveLength(2);
+    expect(rows.every((r) => r.entityType === 'client')).toBe(true);
+  });
+
+  it('filters by action and userId together', async () => {
+    const port = await makePort();
+    await seed({ portId: port.id, userId: 'u1', action: 'create', entityType: 'client' });
+    await seed({ portId: port.id, userId: 'u2', action: 'create', entityType: 'client' });
+    await seed({ portId: port.id, userId: 'u1', action: 'delete', entityType: 'client' });
+
+    const { rows } = await searchAuditLogs({
+      portId: port.id,
+      action: 'create',
+      userId: 'u1',
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.userId).toBe('u1');
+    expect(rows[0]?.action).toBe('create');
+  });
+
+  it('full-text search hits the tsvector column on action + entityType + entityId', async () => {
+    const port = await makePort();
+    await seed({
+      portId: port.id,
+      action: 'archive',
+      entityType: 'expense',
+      entityId: 'expense-marina-fuel-001',
+    });
+    await seed({
+      portId: port.id,
+      action: 'create',
+      entityType: 'invoice',
+      entityId: 'inv-001',
+    });
+
+    const { rows } = await searchAuditLogs({ portId: port.id, q: 'archive' });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.action).toBe('archive');
+  });
+
+  it('cursor pagination returns stable contiguous pages with no duplicates', async () => {
+    const port = await makePort();
+    const now = Date.now();
+    // Seed 7 rows with deterministic timestamps so ordering is stable.
+    for (let i = 0; i < 7; i++) {
+      await seed({
+        portId: port.id,
+        action: 'create',
+        entityType: 'client',
+        entityId: `c-${i}`,
+        createdAt: new Date(now - i * 1000),
+      });
+    }
+    const page1 = await searchAuditLogs({ portId: port.id, limit: 3 });
+    expect(page1.rows).toHaveLength(3);
+    expect(page1.nextCursor).not.toBeNull();
+
+    const page2 = await searchAuditLogs({
+      portId: port.id,
+      limit: 3,
+      cursor: page1.nextCursor!,
+    });
+    expect(page2.rows).toHaveLength(3);
+    expect(page2.nextCursor).not.toBeNull();
+
+    const page3 = await searchAuditLogs({
+      portId: port.id,
+      limit: 3,
+      cursor: page2.nextCursor!,
+    });
+    expect(page3.rows).toHaveLength(1);
+    expect(page3.nextCursor).toBeNull();
+
+    const allIds = [...page1.rows, ...page2.rows, ...page3.rows].map((r) => r.id);
+    expect(new Set(allIds).size).toBe(7);
+  });
+
+  it('isolates results by portId', async () => {
+    const portA = await makePort();
+    const portB = await makePort();
+    await seed({ portId: portA.id, action: 'create', entityType: 'client' });
+    await seed({ portId: portB.id, action: 'create', entityType: 'client' });
+
+    const a = await searchAuditLogs({ portId: portA.id });
+    const b = await searchAuditLogs({ portId: portB.id });
+    expect(a.rows.every((r) => r.portId === portA.id)).toBe(true);
+    expect(b.rows.every((r) => r.portId === portB.id)).toBe(true);
+  });
+
+  it('respects from/to date range', async () => {
+    const port = await makePort();
+    const now = Date.now();
+    await seed({
+      portId: port.id,
+      action: 'create',
+      entityType: 'client',
+      createdAt: new Date(now - 10 * 86_400_000),
+    });
+    await seed({
+      portId: port.id,
+      action: 'create',
+      entityType: 'client',
+      createdAt: new Date(now - 1 * 86_400_000),
+    });
+    await seed({
+      portId: port.id,
+      action: 'create',
+      entityType: 'client',
+      createdAt: new Date(now),
+    });
+
+    const { rows } = await searchAuditLogs({
+      portId: port.id,
+      from: new Date(now - 2 * 86_400_000),
+    });
+    expect(rows).toHaveLength(2);
+  });
+
+  it('without portId, returns rows across ports (super-admin path)', async () => {
+    const portA = await makePort();
+    const portB = await makePort();
+    await seed({
+      portId: portA.id,
+      action: 'create',
+      entityType: 'client',
+      entityId: 'across-port-marker',
+    });
+    await seed({
+      portId: portB.id,
+      action: 'create',
+      entityType: 'client',
+      entityId: 'across-port-marker',
+    });
+    const { rows } = await searchAuditLogs({ q: 'across-port-marker' });
+    const portIds = new Set(rows.map((r) => r.portId));
+    expect(portIds.has(portA.id)).toBe(true);
+    expect(portIds.has(portB.id)).toBe(true);
+
+    // Cleanup so the across-port query doesn't bleed into other tests.
+    await db.delete(auditLogs).where(eq(auditLogs.portId, portA.id));
+    await db.delete(auditLogs).where(eq(auditLogs.portId, portB.id));
+  });
+});

tests/integration/documents-hub-eoi-queue.test.ts

@@ -0,0 +1,153 @@
+/**
+ * PR6 — documents hub `eoi_queue` tab.
+ *
+ * Verifies that:
+ * - `listDocuments` with tab='eoi_queue' returns only EOI docs in
+ *   draft/sent/partially_signed status
+ * - `getHubTabCounts` reports the correct eoi_queue count
+ * - Other doc types (NDA, contract, welcome_letter) are excluded
+ * - Completed/expired EOIs are excluded (those belong to other tabs)
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { db } from '@/lib/db';
+import { documents } from '@/lib/db/schema/documents';
+import { getHubTabCounts, listDocuments } from '@/lib/services/documents.service';
+import { makePort, makeClient } from '../helpers/factories';
+
+describe('documents hub — eoi_queue tab', () => {
+  it('lists only EOIs in in-flight status', async () => {
+    const port = await makePort();
+    const client = await makeClient({ portId: port.id });
+
+    // Seed a mix: 2 in-flight EOIs, 1 completed EOI, 1 sent NDA, 1 sent welcome_letter.
+    await db.insert(documents).values([
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'EOI #1',
+        status: 'sent',
+        createdBy: 'seed',
+      },
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'EOI #2',
+        status: 'partially_signed',
+        createdBy: 'seed',
+      },
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'EOI #3 (done)',
+        status: 'completed',
+        createdBy: 'seed',
+      },
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'nda',
+        title: 'NDA',
+        status: 'sent',
+        createdBy: 'seed',
+      },
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'welcome_letter',
+        title: 'Welcome',
+        status: 'sent',
+        createdBy: 'seed',
+      },
+    ]);
+
+    const result = await listDocuments(
+      port.id,
+      {
+        page: 1,
+        limit: 50,
+        sort: 'createdAt',
+        order: 'desc',
+        includeArchived: false,
+        tab: 'eoi_queue',
+      },
+      {},
+    );
+
+    const docs = result.data as Array<{ documentType: string; status: string }>;
+    expect(docs).toHaveLength(2);
+    expect(docs.every((d) => d.documentType === 'eoi')).toBe(true);
+    expect(docs.every((d) => ['sent', 'partially_signed'].includes(d.status))).toBe(true);
+  });
+
+  it('reports the correct eoi_queue count via getHubTabCounts', async () => {
+    const port = await makePort();
+    const client = await makeClient({ portId: port.id });
+
+    await db.insert(documents).values([
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'EOI A',
+        status: 'draft',
+        createdBy: 'seed',
+      },
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'eoi',
+        title: 'EOI B',
+        status: 'sent',
+        createdBy: 'seed',
+      },
+      {
+        portId: port.id,
+        clientId: client.id,
+        documentType: 'contract',
+        title: 'Contract X',
+        status: 'sent',
+        createdBy: 'seed',
+      },
+    ]);
+
+    const counts = await getHubTabCounts(port.id, undefined);
+    expect(counts.eoi_queue).toBe(2);
+    // The contract should not bump eoi_queue.
+    expect(counts.all).toBe(3);
+  });
+
+  it('returns an empty list when no in-flight EOIs exist', async () => {
+    const port = await makePort();
+    const client = await makeClient({ portId: port.id });
+    await db.insert(documents).values({
+      portId: port.id,
+      clientId: client.id,
+      documentType: 'eoi',
+      title: 'old EOI',
+      status: 'expired',
+      createdBy: 'seed',
+    });
+
+    const result = await listDocuments(
+      port.id,
+      {
+        page: 1,
+        limit: 50,
+        sort: 'createdAt',
+        order: 'desc',
+        includeArchived: false,
+        tab: 'eoi_queue',
+      },
+      {},
+    );
+    expect(result.data).toHaveLength(0);
+
+    const counts = await getHubTabCounts(port.id, undefined);
+    expect(counts.eoi_queue).toBe(0);
+  });
+});

tests/integration/expense-dedup.test.ts

@@ -0,0 +1,202 @@
+/**
+ * PR8 — expense duplicate detection.
+ *
+ * Validates:
+ *  1. `scanForDuplicates` matches by port + lower(vendor) + amount + date ±3d
+ *  2. Same-day matches score 1.0; off-by-N-days score 0.85
+ *  3. `markBestDuplicate` writes the highest-confidence match into `duplicateOf`
+ *  4. `clearDuplicate` nulls `duplicateOf` but keeps `dedupScannedAt`
+ *  5. `mergeDuplicate` consolidates receipts + archives the source row
+ */
+
+import { describe, it, expect } from 'vitest';
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { expenses } from '@/lib/db/schema/financial';
+import {
+  scanForDuplicates,
+  markBestDuplicate,
+  clearDuplicate,
+  mergeDuplicate,
+} from '@/lib/services/expense-dedup.service';
+import { makePort } from '../helpers/factories';
+
+async function seedExpense(args: {
+  portId: string;
+  establishmentName: string;
+  amount: string;
+  expenseDate: Date;
+  receiptFileIds?: string[];
+}) {
+  const [row] = await db
+    .insert(expenses)
+    .values({
+      portId: args.portId,
+      establishmentName: args.establishmentName,
+      amount: args.amount,
+      currency: 'USD',
+      expenseDate: args.expenseDate,
+      receiptFileIds: args.receiptFileIds ?? [],
+      createdBy: 'seed',
+    })
+    .returning();
+  return row!;
+}
+
+describe('expense dedup', () => {
+  it('scanForDuplicates finds matches in the ±3 day window with case-insensitive vendor', async () => {
+    const port = await makePort();
+    const today = new Date('2026-04-15T12:00:00Z');
+    const target = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Marina Fuel',
+      amount: '120.00',
+      expenseDate: today,
+    });
+    // Match: same vendor (different case), same amount, +2 days
+    await seedExpense({
+      portId: port.id,
+      establishmentName: 'marina fuel',
+      amount: '120.00',
+      expenseDate: new Date('2026-04-17T09:00:00Z'),
+    });
+    // Non-match: outside the window
+    await seedExpense({
+      portId: port.id,
+      establishmentName: 'Marina Fuel',
+      amount: '120.00',
+      expenseDate: new Date('2026-04-22T09:00:00Z'),
+    });
+    // Non-match: different amount
+    await seedExpense({
+      portId: port.id,
+      establishmentName: 'Marina Fuel',
+      amount: '125.00',
+      expenseDate: today,
+    });
+
+    const matches = await scanForDuplicates(target.id);
+    expect(matches).toHaveLength(1);
+    expect(matches[0]?.confidence).toBeCloseTo(0.85, 2);
+  });
+
+  it('same-day match scores 1.0', async () => {
+    const port = await makePort();
+    const today = new Date('2026-04-15T12:00:00Z');
+    const target = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Acme',
+      amount: '50',
+      expenseDate: today,
+    });
+    await seedExpense({
+      portId: port.id,
+      establishmentName: 'Acme',
+      amount: '50',
+      expenseDate: today,
+    });
+    const [m] = await scanForDuplicates(target.id);
+    expect(m?.confidence).toBe(1.0);
+  });
+
+  it('markBestDuplicate writes duplicateOf when a candidate exists, leaves null otherwise', async () => {
+    const port = await makePort();
+    const lonely = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Solo',
+      amount: '10',
+      expenseDate: new Date('2026-04-15T12:00:00Z'),
+    });
+    const matchedId = await markBestDuplicate(lonely.id);
+    expect(matchedId).toBeNull();
+    const [refreshed] = await db.select().from(expenses).where(eq(expenses.id, lonely.id));
+    expect(refreshed?.duplicateOf).toBeNull();
+    expect(refreshed?.dedupScannedAt).not.toBeNull();
+
+    const original = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Twin',
+      amount: '20',
+      expenseDate: new Date('2026-04-15T12:00:00Z'),
+    });
+    const dup = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Twin',
+      amount: '20',
+      expenseDate: new Date('2026-04-15T13:00:00Z'),
+    });
+    const matched = await markBestDuplicate(dup.id);
+    expect(matched).toBe(original.id);
+    const [withDup] = await db.select().from(expenses).where(eq(expenses.id, dup.id));
+    expect(withDup?.duplicateOf).toBe(original.id);
+  });
+
+  it('clearDuplicate nulls duplicateOf but preserves dedupScannedAt', async () => {
+    const port = await makePort();
+    const a = await seedExpense({
+      portId: port.id,
+      establishmentName: 'X',
+      amount: '5',
+      expenseDate: new Date('2026-04-15T12:00:00Z'),
+    });
+    const b = await seedExpense({
+      portId: port.id,
+      establishmentName: 'X',
+      amount: '5',
+      expenseDate: new Date('2026-04-15T13:00:00Z'),
+    });
+    await markBestDuplicate(b.id);
+    await clearDuplicate(b.id, port.id);
+    const [refreshed] = await db.select().from(expenses).where(eq(expenses.id, b.id));
+    expect(refreshed?.duplicateOf).toBeNull();
+    expect(refreshed?.dedupScannedAt).not.toBeNull();
+    expect(a).toBeDefined();
+  });
+
+  it('mergeDuplicate combines receipts and archives the source', async () => {
+    const port = await makePort();
+    const target = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Y',
+      amount: '7',
+      expenseDate: new Date('2026-04-15T12:00:00Z'),
+      receiptFileIds: ['file-A'],
+    });
+    const source = await seedExpense({
+      portId: port.id,
+      establishmentName: 'Y',
+      amount: '7',
+      expenseDate: new Date('2026-04-15T13:00:00Z'),
+      receiptFileIds: ['file-B', 'file-A'],
+    });
+
+    await mergeDuplicate(source.id, target.id, port.id);
+
+    const [survivor] = await db.select().from(expenses).where(eq(expenses.id, target.id));
+    expect(new Set(survivor?.receiptFileIds ?? [])).toEqual(new Set(['file-A', 'file-B']));
+
+    const [archived] = await db.select().from(expenses).where(eq(expenses.id, source.id));
+    expect(archived?.archivedAt).not.toBeNull();
+    expect(archived?.duplicateOf).toBeNull();
+  });
+
+  it('mergeDuplicate refuses self-merge and cross-port', async () => {
+    const portA = await makePort();
+    const portB = await makePort();
+    const a = await seedExpense({
+      portId: portA.id,
+      establishmentName: 'Z',
+      amount: '1',
+      expenseDate: new Date('2026-04-15T12:00:00Z'),
+    });
+    const b = await seedExpense({
+      portId: portB.id,
+      establishmentName: 'Z',
+      amount: '1',
+      expenseDate: new Date('2026-04-15T12:00:00Z'),
+    });
+    await expect(mergeDuplicate(a.id, a.id, portA.id)).rejects.toThrow(/itself/);
+    await expect(mergeDuplicate(a.id, b.id, portA.id)).rejects.toThrow(/not found/);
+  });
+});

tests/integration/ocr-config.test.ts

@@ -0,0 +1,130 @@
+/**
+ * PR9 — OCR config service.
+ *
+ * Validates:
+ *  1. Per-port save/read round-trip (key encrypted at rest, decrypted on resolve)
+ *  2. Public view never echoes the raw key
+ *  3. Global fallback when port row sets useGlobal=true
+ *  4. Source field is correctly tagged ('port' | 'global' | 'none')
+ *  5. clearApiKey wipes the stored key
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { eq, isNull, and } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { systemSettings } from '@/lib/db/schema/system';
+import {
+  saveOcrConfig,
+  getResolvedOcrConfig,
+  getPublicOcrConfig,
+} from '@/lib/services/ocr-config.service';
+import { makePort } from '../helpers/factories';
+
+beforeEach(async () => {
+  await db.delete(systemSettings).where(eq(systemSettings.key, 'ocr.config'));
+});
+
+describe('OCR config', () => {
+  it('round-trips a per-port config and decrypts the key on resolve', async () => {
+    const port = await makePort();
+    await saveOcrConfig(
+      port.id,
+      { provider: 'openai', model: 'gpt-4o-mini', apiKey: 'sk-test-abc-123' },
+      'user-1',
+    );
+    const resolved = await getResolvedOcrConfig(port.id);
+    expect(resolved.provider).toBe('openai');
+    expect(resolved.model).toBe('gpt-4o-mini');
+    expect(resolved.apiKey).toBe('sk-test-abc-123');
+    expect(resolved.hasApiKey).toBe(true);
+    expect(resolved.source).toBe('port');
+  });
+
+  it('public view never includes the raw key', async () => {
+    const port = await makePort();
+    await saveOcrConfig(
+      port.id,
+      { provider: 'claude', model: 'claude-haiku-4-5', apiKey: 'sk-secret' },
+      'user-1',
+    );
+    const pub = await getPublicOcrConfig(port.id);
+    expect(pub).not.toHaveProperty('apiKey');
+    expect(pub.hasApiKey).toBe(true);
+    expect(pub.provider).toBe('claude');
+  });
+
+  it('falls back to global when useGlobal is true on the port row', async () => {
+    const port = await makePort();
+    // Set up the global row.
+    await saveOcrConfig(
+      null,
+      { provider: 'openai', model: 'gpt-4o', apiKey: 'global-key' },
+      'user-1',
+    );
+    // Port row opts in.
+    await saveOcrConfig(
+      port.id,
+      { provider: 'claude', model: 'claude-haiku-4-5', apiKey: 'port-key', useGlobal: true },
+      'user-1',
+    );
+    const resolved = await getResolvedOcrConfig(port.id);
+    expect(resolved.source).toBe('global');
+    expect(resolved.apiKey).toBe('global-key');
+    expect(resolved.provider).toBe('openai');
+    expect(resolved.useGlobal).toBe(true);
+  });
+
+  it('returns source=none when neither port nor global is configured', async () => {
+    const port = await makePort();
+    const resolved = await getResolvedOcrConfig(port.id);
+    expect(resolved.source).toBe('none');
+    expect(resolved.apiKey).toBeNull();
+    expect(resolved.hasApiKey).toBe(false);
+  });
+
+  it('clearApiKey nulls the stored key but preserves provider/model', async () => {
+    const port = await makePort();
+    await saveOcrConfig(
+      port.id,
+      { provider: 'openai', model: 'gpt-4o-mini', apiKey: 'first-key' },
+      'user-1',
+    );
+    await saveOcrConfig(
+      port.id,
+      { provider: 'openai', model: 'gpt-4o-mini', clearApiKey: true },
+      'user-1',
+    );
+    const resolved = await getResolvedOcrConfig(port.id);
+    expect(resolved.apiKey).toBeNull();
+    expect(resolved.hasApiKey).toBe(false);
+    expect(resolved.provider).toBe('openai');
+  });
+
+  it('omitting apiKey on save preserves the existing one', async () => {
+    const port = await makePort();
+    await saveOcrConfig(
+      port.id,
+      { provider: 'openai', model: 'gpt-4o-mini', apiKey: 'keep-me' },
+      'user-1',
+    );
+    // Update model only — no apiKey field provided.
+    await saveOcrConfig(port.id, { provider: 'openai', model: 'gpt-4o' }, 'user-1');
+    const resolved = await getResolvedOcrConfig(port.id);
+    expect(resolved.apiKey).toBe('keep-me');
+    expect(resolved.model).toBe('gpt-4o');
+  });
+
+  it('global rows force useGlobal=false on save (not meaningful at global scope)', async () => {
+    await saveOcrConfig(
+      null,
+      { provider: 'openai', model: 'gpt-4o-mini', apiKey: 'g', useGlobal: true },
+      'user-1',
+    );
+    const [row] = await db
+      .select()
+      .from(systemSettings)
+      .where(and(eq(systemSettings.key, 'ocr.config'), isNull(systemSettings.portId)));
+    expect((row?.value as { useGlobal: boolean }).useGlobal).toBe(false);
+  });
+});