feat(docs): nested-entity 'This deal' / 'From client' split (B4 #8 phase 4)

Finishes B4 #8 by completing the UI half of the per-interest filing
model. Backend foundations (files.interest_id column, ensureEntityFolder
for 'interest', upload-zone scope radio, outcome rename hook, backfill)
shipped earlier in this audit cycle.

- listFiles validator + service: optional interestId filter
- listFilesAggregatedByEntity: routes entityType='interest' to a new
  helper that returns "THIS DEAL" + "FROM CLIENT" + symmetric-reach
  company/yacht groups
- InterestDocumentsTab: Attachments section now renders two cohorts
  via two paginated queries, with client-side de-duplication so files
  filed under this deal don't double-count under "From client"
- FileRow type exposes the optional interestId so the de-dupe filter
  doesn't need a re-fetch

docs/superpowers/audits/alpha-uat-master.md

@@ -814,6 +814,7 @@ _Functional defects. Tag each with `[critical|high|medium|low]` prefix._
      - One-off script `pnpm tsx scripts/backfill-nested-document-folders.ts --apply` — idempotent, per-port advisory-locked.
    - **Effort:** ~6-8h end-to-end (migration + service rewrites + folder-name derivation + upload-zone affordance + tree rendering + lifecycle hooks + backfill + tests). Bundles bug #4 — both touch the same code paths. Captured 2026-05-21 from UAT.
    - **SHIPPED (foundation only — phase 1/3) in e91055f, phases 2/3 in 0ed03fc:** migration `0078_files_interest_id.sql` adds `files.interest_id` text REFERENCES interests(id) ON DELETE SET NULL + indexes `idx_files_interest` + `idx_files_port_interest`. Drizzle schema picks up the column + `interestId` field. `EntityType` widened to include `'interest'` — `ensureEntityFolder('interest', ...)` recursively ensures the parent client folder first so the tree reads `Clients/<Name>/Deal <mooringNumber>/` nested. `resolveEntityDisplayName` derives the deal label from the primary berth via dynamic-import of `getPrimaryBerth` (circular-dep dodge), falling back to `Deal <YYYY-MM-DD>`. **Phases 2/3 SHIPPED in 0ed03fc:** UploadZone scope radio (`<FileUploadZone>` accepts optional `interestId`; when set, fieldset renders "File at: ⦿ This deal | ◯ Client-level"; default deal-scope so deal-specific docs don't bleed across historical interests of the client; interest FK forwarded only when "This deal" selected). Outcome → folder rename hook: `renameInterestFolderForOutcome(interestId, portId, outcome)` strips prior outcome suffix then appends (Won)/(Lost)/(Cancelled); fired fire-and-forget from `interests.service.setInterestOutcome` via dynamic import (circular-dep dodge); no-op when folder hasn't been created yet. Backfill script: `scripts/backfill-nested-document-folders.ts` iterates every (port_id, interest_id) pair in `files` with non-null interest_id and calls `ensureEntityFolder`; idempotent via per-port advisory lock (FNV-1a of port_id); dry-run by default, `--apply` to commit. **Still deferred:** `listFilesAggregatedByEntity` rewrite for "This deal" vs "From client" subheadings (UI polish; per-row filing already correct); Documents Hub tree rendering for nested interest folders (rows exist with parent_id; tree component picks them up automatically).
+   - **Final phase SHIPPED in this session:** `listFiles` now accepts an optional `interestId` filter (validator + service); `listFilesAggregatedByEntity` accepts `entityType='interest'` and routes to a new helper that returns "THIS DEAL" + "FROM CLIENT" + symmetric-reach company/yacht groups. `InterestDocumentsTab` Attachments section now fires two paginated queries (one scoped to `?interestId=<X>`, one scoped to `?clientId=<C>`), filters the client list to drop duplicates, and renders the two cohorts under "This deal" / "From client" subheadings. `FileRow` exposes the optional `interestId` so the de-dupe filter works without a re-fetch. Tree rendering in Documents Hub still relies on the tree component picking up child folders by `parent_id` (which already works); no additional UI surgery needed.
 9. **SHIPPED in c14f80a (Q58):** `<SelectTrigger>` now accepts `size?: 'default' | 'sm'`; default = `h-11` so trigger matches Input's h-11 default. Existing compact call sites (FilterBar, dense table headers) opt back in via `size="sm"`. Nothing else breaks. **[medium] SelectTrigger height (`h-9`) doesn't match Input height (`h-11`) — platform-wide visual inconsistency** — _src/components/ui/select.tsx:22_ (SelectTrigger default `h-9` = 36px) + _src/components/ui/input.tsx:18_ (Input default `h-11` = 44px). Every form where an Input sits next to a Select has an 8px height mismatch. Surfaced specifically on _src/components/expenses/expense-form-dialog.tsx:222-247_ (the Amount + Currency two-column row) but affects ALL such combinations across the platform. Fixing locally with `className="h-11"` on each call site is a sweep over dozens of spots and creates drift the next time someone copies the pattern.
    - **Fix (platform-wide):** introduce a `size` variant on SelectTrigger mirroring Button's idiom — `<SelectTrigger size="default" | "sm">`. Default to `"default"` = `h-11` so it pairs with the Input default out of the box. Migrate explicitly-compact uses (filter bars, dense table headers) to pass `size="sm"` = `h-9` to preserve their current density.
    - **Audit step:** grep every `<SelectTrigger>` and `<Select>` call site; flag the ones in compact contexts (FilterBar, DataTable header dropdowns, dense admin lists) for the `size="sm"` override; everything else inherits the new h-11 default.

src/components/files/file-grid.tsx

@@ -32,6 +32,10 @@ export interface FileRow {
   category: string | null;
   createdAt: string | Date;
   uploadedBy: string;
+  /** Optional — present when the file is scoped to a sales deal.
+   *  Consumers like InterestDocumentsTab filter on this to split the
+   *  "This deal" vs "From client" cohorts. */
+  interestId?: string | null;
 }
 
 interface FileGridProps {

src/components/interests/interest-documents-tab.tsx

@@ -45,24 +45,34 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
       apiFetch<{ data: InterestData }>(`/api/v1/interests/${interestId}`).then((r) => r.data),
   });
 
-  // Files attach at the client level (the schema has no interest_id
-  // FK on `files`). For an interest, surface every file that belongs
-  // to its parent client - covers the realistic case where a rep
-  // uploaded a passport / scan / photo while working a deal.
-  // Until the interest record loads we pass a sentinel clientId so the
-  // server returns empty rather than the unscoped port-wide file list.
+  // Two cohorts: files tagged with this interestId ("This deal") +
+  // files belonging to the parent client without an interestId, or
+  // tagged to another interest of the same client ("From client").
+  // Until the interest record loads we pass a sentinel clientId so
+  // the server returns empty rather than the unscoped port-wide list.
   const clientId = interest?.clientId ?? '__pending__';
-  const filesQueryKey = ['files', { clientId }] as const;
-  const { data: files, isLoading: filesLoading } = usePaginatedQuery<FileRow>({
-    queryKey: filesQueryKey,
+  const thisDealQueryKey = ['files', { interestId }] as const;
+  const fromClientQueryKey = ['files', { clientId }] as const;
+
+  const { data: thisDealFiles, isLoading: thisDealLoading } = usePaginatedQuery<FileRow>({
+    queryKey: thisDealQueryKey,
+    endpoint: `/api/v1/files?interestId=${encodeURIComponent(interestId)}`,
+    filterDefinitions: [],
+  });
+
+  const { data: clientFiles, isLoading: clientFilesLoading } = usePaginatedQuery<FileRow>({
+    queryKey: fromClientQueryKey,
     endpoint: `/api/v1/files?clientId=${encodeURIComponent(clientId)}`,
     filterDefinitions: [],
   });
 
+  // "From client" excludes anything we already surface under "This deal".
+  const fromClientFiles = clientFiles.filter((f) => !f.interestId || f.interestId !== interestId);
+
   useRealtimeInvalidation({
-    'file:uploaded': [filesQueryKey],
-    'file:updated': [filesQueryKey],
-    'file:deleted': [filesQueryKey],
+    'file:uploaded': [thisDealQueryKey, fromClientQueryKey],
+    'file:updated': [thisDealQueryKey, fromClientQueryKey],
+    'file:deleted': [thisDealQueryKey, fromClientQueryKey],
   });
 
   const handleDownload = async (file: FileRow) => {
@@ -85,13 +95,16 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
     if (!ok) return;
     try {
       await apiFetch(`/api/v1/files/${file.id}`, { method: 'DELETE' });
-      queryClient.invalidateQueries({ queryKey: filesQueryKey });
+      queryClient.invalidateQueries({ queryKey: thisDealQueryKey });
+      queryClient.invalidateQueries({ queryKey: fromClientQueryKey });
     } catch {
       // silent
     }
   };
 
-  const hasAttachments = files.length > 0;
+  const hasThisDeal = thisDealFiles.length > 0;
+  const hasFromClient = fromClientFiles.length > 0;
+  const hasAttachments = hasThisDeal || hasFromClient;
 
   return (
     <div className="space-y-8">
@@ -129,7 +142,8 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
           <h3 className="text-sm font-medium text-muted-foreground">Attachments</h3>
           {hasAttachments ? (
             <span className="text-xs text-muted-foreground">
-              {files.length} file{files.length === 1 ? '' : 's'}
+              {thisDealFiles.length + fromClientFiles.length} file
+              {thisDealFiles.length + fromClientFiles.length === 1 ? '' : 's'}
             </span>
           ) : null}
         </div>
@@ -148,22 +162,44 @@ export function InterestDocumentsTab({ interestId }: InterestDocumentsTabProps)
               // client-level.
               interestId={interestId}
               onUploadComplete={() => {
-                queryClient.invalidateQueries({ queryKey: filesQueryKey });
+                queryClient.invalidateQueries({ queryKey: thisDealQueryKey });
+                queryClient.invalidateQueries({ queryKey: fromClientQueryKey });
               }}
             />
           ) : null}
         </PermissionGate>
 
-        {hasAttachments ? (
-          <FileGrid
-            files={files}
-            onDownload={handleDownload}
-            onPreview={setPreviewFile}
-            onRename={() => {}}
-            onDelete={handleDelete}
-            isLoading={filesLoading}
-          />
-        ) : null}
+        {(hasThisDeal || thisDealLoading) && (
+          <div className="space-y-2">
+            <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              This deal
+            </h4>
+            <FileGrid
+              files={thisDealFiles}
+              onDownload={handleDownload}
+              onPreview={setPreviewFile}
+              onRename={() => {}}
+              onDelete={handleDelete}
+              isLoading={thisDealLoading}
+            />
+          </div>
+        )}
+
+        {(hasFromClient || clientFilesLoading) && (
+          <div className="space-y-2">
+            <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+              From client
+            </h4>
+            <FileGrid
+              files={fromClientFiles}
+              onDownload={handleDownload}
+              onPreview={setPreviewFile}
+              onRename={() => {}}
+              onDelete={handleDelete}
+              isLoading={clientFilesLoading}
+            />
+          </div>
+        )}
       </section>
 
       <EoiGenerateDialog

src/lib/services/files.ts

@@ -22,6 +22,7 @@ import { documentFolders } from '@/lib/db/schema/documents';
 import { clients } from '@/lib/db/schema/clients';
 import { companies, companyMemberships } from '@/lib/db/schema/companies';
 import { yachts } from '@/lib/db/schema/yachts';
+import { interests } from '@/lib/db/schema/interests';
 import type { EntityType } from '@/lib/services/document-folders.service';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -267,7 +268,8 @@ export async function deleteFile(id: string, portId: string, meta: AuditMeta) {
 // ─── List ─────────────────────────────────────────────────────────────────────
 
 export async function listFiles(portId: string, query: ListFilesInput) {
-  const { page, limit, sort, order, search, clientId, yachtId, companyId, category } = query;
+  const { page, limit, sort, order, search, clientId, yachtId, companyId, interestId, category } =
+    query;
 
   const filters = [];
 
@@ -280,6 +282,9 @@ export async function listFiles(portId: string, query: ListFilesInput) {
   if (companyId) {
     filters.push(eq(files.companyId, companyId));
   }
+  if (interestId) {
+    filters.push(eq(files.interestId, interestId));
+  }
   if (category) {
     filters.push(eq(files.category, category));
   }
@@ -333,7 +338,7 @@ export type AggregatedFileRow = Omit<typeof files.$inferSelect, 'storagePath' |
 
 export interface AggregatedFileGroup {
   label: string;
-  source: 'direct' | 'client' | 'company' | 'yacht';
+  source: 'direct' | 'client' | 'company' | 'yacht' | 'this_deal' | 'other_deals';
   files: AggregatedFileRow[];
   total: number;
 }
@@ -351,6 +356,74 @@ const GROUP_LIMIT = 20;
  * Source of truth: each file's snapshotted entity FKs.
  * Defense-in-depth: port_id at every entity / membership / yacht / file join.
  */
+async function listFilesAggregatedForInterest(
+  portId: string,
+  interestId: string,
+  clientId: string | null,
+): Promise<AggregatedFilesResult> {
+  const groups: AggregatedFileGroup[] = [];
+
+  // "THIS DEAL" — files explicitly tagged with this interest_id.
+  const thisDeal = await fetchGroupRows(portId, eq(files.interestId, interestId), GROUP_LIMIT);
+  if (thisDeal.rows.length > 0) {
+    groups.push({
+      label: 'THIS DEAL',
+      source: 'this_deal',
+      files: thisDeal.rows,
+      total: thisDeal.total,
+    });
+  }
+
+  if (clientId) {
+    // "FROM CLIENT" — files on the same client that aren't tagged to
+    // this interest. NULL interest_id = client-level, non-deal-specific.
+    // A different interest id = another deal's docs, still useful to
+    // surface so the rep can pull from history without leaving the
+    // current detail page.
+    const fromClient = await fetchGroupRows(
+      portId,
+      and(
+        eq(files.clientId, clientId),
+        or(isNull(files.interestId), sql`${files.interestId} <> ${interestId}`),
+      )!,
+      GROUP_LIMIT,
+    );
+    if (fromClient.rows.length > 0) {
+      groups.push({
+        label: 'FROM CLIENT',
+        source: 'other_deals',
+        files: fromClient.rows,
+        total: fromClient.total,
+      });
+    }
+
+    // Symmetric reach via the client's related companies + yachts.
+    const related = await collectRelatedEntities(portId, 'client', clientId);
+    for (const { id, name } of related.companies) {
+      const g = await fetchGroupRows(portId, eq(files.companyId, id), GROUP_LIMIT);
+      if (g.rows.length === 0) continue;
+      groups.push({
+        label: `FROM COMPANY: ${name.toUpperCase()}`,
+        source: 'company',
+        files: g.rows,
+        total: g.total,
+      });
+    }
+    for (const { id, name } of related.yachts) {
+      const g = await fetchGroupRows(portId, eq(files.yachtId, id), GROUP_LIMIT);
+      if (g.rows.length === 0) continue;
+      groups.push({
+        label: `FROM YACHT: ${name.toUpperCase()}`,
+        source: 'yacht',
+        files: g.rows,
+        total: g.total,
+      });
+    }
+  }
+
+  return { groups };
+}
+
 export async function listFilesAggregatedByEntity(
   portId: string,
   entityType: EntityType,
@@ -359,6 +432,20 @@ export async function listFilesAggregatedByEntity(
   const entityExists = await assertEntityInPort(portId, entityType, entityId);
   if (!entityExists) return { groups: [] };
 
+  // Interest view: split direct-attached files into "this deal" (files
+  // explicitly tagged with this interestId) + "from client" (files on
+  // the same client but no interestId OR a different interest). The
+  // client-level companies/yachts walk is reused via the underlying
+  // client.
+  if (entityType === 'interest') {
+    const interest = await db.query.interests.findFirst({
+      where: and(eq(interests.id, entityId), eq(interests.portId, portId)),
+      columns: { id: true, clientId: true },
+    });
+    if (!interest) return { groups: [] };
+    return listFilesAggregatedForInterest(portId, interest.id, interest.clientId ?? null);
+  }
+
   const related = await collectRelatedEntities(portId, entityType, entityId);
   const groups: AggregatedFileGroup[] = [];
 
@@ -434,6 +521,13 @@ export async function assertEntityInPort(
     });
     return Boolean(c);
   }
+  if (entityType === 'interest') {
+    const i = await db.query.interests.findFirst({
+      where: and(eq(interests.id, entityId), eq(interests.portId, portId)),
+      columns: { id: true },
+    });
+    return Boolean(i);
+  }
   const y = await db.query.yachts.findFirst({
     where: and(eq(yachts.id, entityId), eq(yachts.portId, portId)),
     columns: { id: true },

src/lib/validators/files.ts

@@ -23,14 +23,18 @@ export const listFilesSchema = baseListQuerySchema
     clientId: z.string().optional(),
     yachtId: z.string().optional(),
     companyId: z.string().optional(),
+    interestId: z.string().optional(),
     category: z.string().optional(),
     folderId: z
       .string()
       .uuid()
       .optional()
       .transform((v) => (v === '' ? null : v)),
-    /** Entity-aggregated projection params - mutually exclusive with folderId. */
-    entityType: z.enum(['client', 'company', 'yacht']).optional(),
+    /** Entity-aggregated projection params - mutually exclusive with folderId.
+     *  'interest' splits direct-attached into "This deal" (files.interestId
+     *  matches) and "From client" (client-level + other deals); the other
+     *  values fall through to the legacy symmetric-reach aggregator. */
+    entityType: z.enum(['client', 'company', 'yacht', 'interest']).optional(),
     entityId: z.string().uuid().optional(),
   })
   .refine(